Mutation Agent
curl --request POST \
--url https://agents.graphy.dev/api/v0/mutate \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"config": {
"type": "column",
"data": {
"columns": [
{
"key": "region",
"label": "Region"
},
{
"key": "sales",
"label": "Sales"
}
],
"rows": [
{
"region": "North",
"sales": 100
},
{
"region": "South",
"sales": 80
},
{
"region": "North",
"sales": 120
}
]
}
},
"userPrompt": "Total sales by region, sorted highest first",
"metadata": {
"callId": "req-mutate-1",
"locale": "EN_US"
}
}
'import requests
url = "https://agents.graphy.dev/api/v0/mutate"
payload = {
"config": {
"type": "column",
"data": {
"columns": [
{
"key": "region",
"label": "Region"
},
{
"key": "sales",
"label": "Sales"
}
],
"rows": [
{
"region": "North",
"sales": 100
},
{
"region": "South",
"sales": 80
},
{
"region": "North",
"sales": 120
}
]
}
},
"userPrompt": "Total sales by region, sorted highest first",
"metadata": {
"callId": "req-mutate-1",
"locale": "EN_US"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
config: {
type: 'column',
data: {
columns: [{key: 'region', label: 'Region'}, {key: 'sales', label: 'Sales'}],
rows: [
{region: 'North', sales: 100},
{region: 'South', sales: 80},
{region: 'North', sales: 120}
]
}
},
userPrompt: 'Total sales by region, sorted highest first',
metadata: {callId: 'req-mutate-1', locale: 'EN_US'}
})
};
fetch('https://agents.graphy.dev/api/v0/mutate', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://agents.graphy.dev/api/v0/mutate",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'config' => [
'type' => 'column',
'data' => [
'columns' => [
[
'key' => 'region',
'label' => 'Region'
],
[
'key' => 'sales',
'label' => 'Sales'
]
],
'rows' => [
[
'region' => 'North',
'sales' => 100
],
[
'region' => 'South',
'sales' => 80
],
[
'region' => 'North',
'sales' => 120
]
]
]
],
'userPrompt' => 'Total sales by region, sorted highest first',
'metadata' => [
'callId' => 'req-mutate-1',
'locale' => 'EN_US'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://agents.graphy.dev/api/v0/mutate"
payload := strings.NewReader("{\n \"config\": {\n \"type\": \"column\",\n \"data\": {\n \"columns\": [\n {\n \"key\": \"region\",\n \"label\": \"Region\"\n },\n {\n \"key\": \"sales\",\n \"label\": \"Sales\"\n }\n ],\n \"rows\": [\n {\n \"region\": \"North\",\n \"sales\": 100\n },\n {\n \"region\": \"South\",\n \"sales\": 80\n },\n {\n \"region\": \"North\",\n \"sales\": 120\n }\n ]\n }\n },\n \"userPrompt\": \"Total sales by region, sorted highest first\",\n \"metadata\": {\n \"callId\": \"req-mutate-1\",\n \"locale\": \"EN_US\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://agents.graphy.dev/api/v0/mutate")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"config\": {\n \"type\": \"column\",\n \"data\": {\n \"columns\": [\n {\n \"key\": \"region\",\n \"label\": \"Region\"\n },\n {\n \"key\": \"sales\",\n \"label\": \"Sales\"\n }\n ],\n \"rows\": [\n {\n \"region\": \"North\",\n \"sales\": 100\n },\n {\n \"region\": \"South\",\n \"sales\": 80\n },\n {\n \"region\": \"North\",\n \"sales\": 120\n }\n ]\n }\n },\n \"userPrompt\": \"Total sales by region, sorted highest first\",\n \"metadata\": {\n \"callId\": \"req-mutate-1\",\n \"locale\": \"EN_US\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://agents.graphy.dev/api/v0/mutate")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"config\": {\n \"type\": \"column\",\n \"data\": {\n \"columns\": [\n {\n \"key\": \"region\",\n \"label\": \"Region\"\n },\n {\n \"key\": \"sales\",\n \"label\": \"Sales\"\n }\n ],\n \"rows\": [\n {\n \"region\": \"North\",\n \"sales\": 100\n },\n {\n \"region\": \"South\",\n \"sales\": 80\n },\n {\n \"region\": \"North\",\n \"sales\": 120\n }\n ]\n }\n },\n \"userPrompt\": \"Total sales by region, sorted highest first\",\n \"metadata\": {\n \"callId\": \"req-mutate-1\",\n \"locale\": \"EN_US\"\n }\n}"
response = http.request(request)
puts response.read_body{
"message": "<string>"
}REST API
Mutation Agent
Transform a chart’s dataset with natural language — filter, group, aggregate, derive, sort.
The response is a Server-Sent Events (SSE) stream with progress, complete, and error events.
POST
/
api
/
v0
/
mutate
Mutation Agent
curl --request POST \
--url https://agents.graphy.dev/api/v0/mutate \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"config": {
"type": "column",
"data": {
"columns": [
{
"key": "region",
"label": "Region"
},
{
"key": "sales",
"label": "Sales"
}
],
"rows": [
{
"region": "North",
"sales": 100
},
{
"region": "South",
"sales": 80
},
{
"region": "North",
"sales": 120
}
]
}
},
"userPrompt": "Total sales by region, sorted highest first",
"metadata": {
"callId": "req-mutate-1",
"locale": "EN_US"
}
}
'import requests
url = "https://agents.graphy.dev/api/v0/mutate"
payload = {
"config": {
"type": "column",
"data": {
"columns": [
{
"key": "region",
"label": "Region"
},
{
"key": "sales",
"label": "Sales"
}
],
"rows": [
{
"region": "North",
"sales": 100
},
{
"region": "South",
"sales": 80
},
{
"region": "North",
"sales": 120
}
]
}
},
"userPrompt": "Total sales by region, sorted highest first",
"metadata": {
"callId": "req-mutate-1",
"locale": "EN_US"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
config: {
type: 'column',
data: {
columns: [{key: 'region', label: 'Region'}, {key: 'sales', label: 'Sales'}],
rows: [
{region: 'North', sales: 100},
{region: 'South', sales: 80},
{region: 'North', sales: 120}
]
}
},
userPrompt: 'Total sales by region, sorted highest first',
metadata: {callId: 'req-mutate-1', locale: 'EN_US'}
})
};
fetch('https://agents.graphy.dev/api/v0/mutate', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://agents.graphy.dev/api/v0/mutate",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'config' => [
'type' => 'column',
'data' => [
'columns' => [
[
'key' => 'region',
'label' => 'Region'
],
[
'key' => 'sales',
'label' => 'Sales'
]
],
'rows' => [
[
'region' => 'North',
'sales' => 100
],
[
'region' => 'South',
'sales' => 80
],
[
'region' => 'North',
'sales' => 120
]
]
]
],
'userPrompt' => 'Total sales by region, sorted highest first',
'metadata' => [
'callId' => 'req-mutate-1',
'locale' => 'EN_US'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://agents.graphy.dev/api/v0/mutate"
payload := strings.NewReader("{\n \"config\": {\n \"type\": \"column\",\n \"data\": {\n \"columns\": [\n {\n \"key\": \"region\",\n \"label\": \"Region\"\n },\n {\n \"key\": \"sales\",\n \"label\": \"Sales\"\n }\n ],\n \"rows\": [\n {\n \"region\": \"North\",\n \"sales\": 100\n },\n {\n \"region\": \"South\",\n \"sales\": 80\n },\n {\n \"region\": \"North\",\n \"sales\": 120\n }\n ]\n }\n },\n \"userPrompt\": \"Total sales by region, sorted highest first\",\n \"metadata\": {\n \"callId\": \"req-mutate-1\",\n \"locale\": \"EN_US\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://agents.graphy.dev/api/v0/mutate")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"config\": {\n \"type\": \"column\",\n \"data\": {\n \"columns\": [\n {\n \"key\": \"region\",\n \"label\": \"Region\"\n },\n {\n \"key\": \"sales\",\n \"label\": \"Sales\"\n }\n ],\n \"rows\": [\n {\n \"region\": \"North\",\n \"sales\": 100\n },\n {\n \"region\": \"South\",\n \"sales\": 80\n },\n {\n \"region\": \"North\",\n \"sales\": 120\n }\n ]\n }\n },\n \"userPrompt\": \"Total sales by region, sorted highest first\",\n \"metadata\": {\n \"callId\": \"req-mutate-1\",\n \"locale\": \"EN_US\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://agents.graphy.dev/api/v0/mutate")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"config\": {\n \"type\": \"column\",\n \"data\": {\n \"columns\": [\n {\n \"key\": \"region\",\n \"label\": \"Region\"\n },\n {\n \"key\": \"sales\",\n \"label\": \"Sales\"\n }\n ],\n \"rows\": [\n {\n \"region\": \"North\",\n \"sales\": 100\n },\n {\n \"region\": \"South\",\n \"sales\": 80\n },\n {\n \"region\": \"North\",\n \"sales\": 120\n }\n ]\n }\n },\n \"userPrompt\": \"Total sales by region, sorted highest first\",\n \"metadata\": {\n \"callId\": \"req-mutate-1\",\n \"locale\": \"EN_US\"\n }\n}"
response = http.request(request)
puts response.read_body{
"message": "<string>"
}Transform a chart’s dataset with natural language — filter, group, aggregate, derive, sort. Send a
Final response data:
Errors may also arrive as SSE events within a 200 response. See Error Codes.
GraphConfig and a prompt, receive an updated GraphConfig via Server-Sent Events.
Response
The response is a Server-Sent Events stream. See SSE Format for parsing details.event: progress
data: {"message":"Mutating dataset..."}
event: complete
data: {"config":{...},"response":{"message":"Grouped sales by region","steps":["Grouped rows by region","Sorted by total sales descending"]}}
interface MutateResponse {
config: GraphConfig;
response: {
message: string;
steps?: string[];
};
}
HTTP Status Codes
| Status | Description |
|---|---|
| 200 | Success (stream begins) |
| 400 | Invalid request body |
| 401 | Invalid or missing API key |
| 429 | Rate limit exceeded |
| 500 | Internal server error |
Authorizations
Your Graphy API key (starts with graphy_). Create one in the Graphy console at https://agents.graphy.dev/console/
Body
application/json
The graph configuration object used to render charts. See Graph Config Schema for the complete reference.
Show child attributes
Show child attributes
Natural language instruction describing the desired changes
Maximum string length:
10000Optional tracking information for requests
Show child attributes
Show child attributes
Response
SSE stream with progress and completion events
⌘I