Suggestions Agent
curl --request POST \
--url https://agents.graphy.dev/api/v0/suggestions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"config": {
"type": "column",
"data": {
"columns": [
{
"key": "month",
"label": "Month"
},
{
"key": "sales",
"label": "Sales"
},
{
"key": "region",
"label": "Region"
}
],
"rows": [
{
"month": "Jan",
"sales": 100,
"region": "North"
},
{
"month": "Feb",
"sales": 120,
"region": "South"
},
{
"month": "Mar",
"sales": 115,
"region": "North"
}
]
}
},
"userPrompt": "Show me interesting trends",
"metadata": {
"callId": "req-67890",
"locale": "EN_US"
}
}
'import requests
url = "https://agents.graphy.dev/api/v0/suggestions"
payload = {
"config": {
"type": "column",
"data": {
"columns": [
{
"key": "month",
"label": "Month"
},
{
"key": "sales",
"label": "Sales"
},
{
"key": "region",
"label": "Region"
}
],
"rows": [
{
"month": "Jan",
"sales": 100,
"region": "North"
},
{
"month": "Feb",
"sales": 120,
"region": "South"
},
{
"month": "Mar",
"sales": 115,
"region": "North"
}
]
}
},
"userPrompt": "Show me interesting trends",
"metadata": {
"callId": "req-67890",
"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: 'month', label: 'Month'},
{key: 'sales', label: 'Sales'},
{key: 'region', label: 'Region'}
],
rows: [
{month: 'Jan', sales: 100, region: 'North'},
{month: 'Feb', sales: 120, region: 'South'},
{month: 'Mar', sales: 115, region: 'North'}
]
}
},
userPrompt: 'Show me interesting trends',
metadata: {callId: 'req-67890', locale: 'EN_US'}
})
};
fetch('https://agents.graphy.dev/api/v0/suggestions', 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/suggestions",
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' => 'month',
'label' => 'Month'
],
[
'key' => 'sales',
'label' => 'Sales'
],
[
'key' => 'region',
'label' => 'Region'
]
],
'rows' => [
[
'month' => 'Jan',
'sales' => 100,
'region' => 'North'
],
[
'month' => 'Feb',
'sales' => 120,
'region' => 'South'
],
[
'month' => 'Mar',
'sales' => 115,
'region' => 'North'
]
]
]
],
'userPrompt' => 'Show me interesting trends',
'metadata' => [
'callId' => 'req-67890',
'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/suggestions"
payload := strings.NewReader("{\n \"config\": {\n \"type\": \"column\",\n \"data\": {\n \"columns\": [\n {\n \"key\": \"month\",\n \"label\": \"Month\"\n },\n {\n \"key\": \"sales\",\n \"label\": \"Sales\"\n },\n {\n \"key\": \"region\",\n \"label\": \"Region\"\n }\n ],\n \"rows\": [\n {\n \"month\": \"Jan\",\n \"sales\": 100,\n \"region\": \"North\"\n },\n {\n \"month\": \"Feb\",\n \"sales\": 120,\n \"region\": \"South\"\n },\n {\n \"month\": \"Mar\",\n \"sales\": 115,\n \"region\": \"North\"\n }\n ]\n }\n },\n \"userPrompt\": \"Show me interesting trends\",\n \"metadata\": {\n \"callId\": \"req-67890\",\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/suggestions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"config\": {\n \"type\": \"column\",\n \"data\": {\n \"columns\": [\n {\n \"key\": \"month\",\n \"label\": \"Month\"\n },\n {\n \"key\": \"sales\",\n \"label\": \"Sales\"\n },\n {\n \"key\": \"region\",\n \"label\": \"Region\"\n }\n ],\n \"rows\": [\n {\n \"month\": \"Jan\",\n \"sales\": 100,\n \"region\": \"North\"\n },\n {\n \"month\": \"Feb\",\n \"sales\": 120,\n \"region\": \"South\"\n },\n {\n \"month\": \"Mar\",\n \"sales\": 115,\n \"region\": \"North\"\n }\n ]\n }\n },\n \"userPrompt\": \"Show me interesting trends\",\n \"metadata\": {\n \"callId\": \"req-67890\",\n \"locale\": \"EN_US\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://agents.graphy.dev/api/v0/suggestions")
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\": \"month\",\n \"label\": \"Month\"\n },\n {\n \"key\": \"sales\",\n \"label\": \"Sales\"\n },\n {\n \"key\": \"region\",\n \"label\": \"Region\"\n }\n ],\n \"rows\": [\n {\n \"month\": \"Jan\",\n \"sales\": 100,\n \"region\": \"North\"\n },\n {\n \"month\": \"Feb\",\n \"sales\": 120,\n \"region\": \"South\"\n },\n {\n \"month\": \"Mar\",\n \"sales\": 115,\n \"region\": \"North\"\n }\n ]\n }\n },\n \"userPrompt\": \"Show me interesting trends\",\n \"metadata\": {\n \"callId\": \"req-67890\",\n \"locale\": \"EN_US\"\n }\n}"
response = http.request(request)
puts response.read_body{
"message": "<string>"
}REST API
Suggestions Agent
Generate chart type and data preparation suggestions from a dataset. Send a GraphConfig and a prompt, receive suggested visualizations.
The response is a Server-Sent Events (SSE) stream with progress, complete, and error events.
POST
/
api
/
v0
/
suggestions
Suggestions Agent
curl --request POST \
--url https://agents.graphy.dev/api/v0/suggestions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"config": {
"type": "column",
"data": {
"columns": [
{
"key": "month",
"label": "Month"
},
{
"key": "sales",
"label": "Sales"
},
{
"key": "region",
"label": "Region"
}
],
"rows": [
{
"month": "Jan",
"sales": 100,
"region": "North"
},
{
"month": "Feb",
"sales": 120,
"region": "South"
},
{
"month": "Mar",
"sales": 115,
"region": "North"
}
]
}
},
"userPrompt": "Show me interesting trends",
"metadata": {
"callId": "req-67890",
"locale": "EN_US"
}
}
'import requests
url = "https://agents.graphy.dev/api/v0/suggestions"
payload = {
"config": {
"type": "column",
"data": {
"columns": [
{
"key": "month",
"label": "Month"
},
{
"key": "sales",
"label": "Sales"
},
{
"key": "region",
"label": "Region"
}
],
"rows": [
{
"month": "Jan",
"sales": 100,
"region": "North"
},
{
"month": "Feb",
"sales": 120,
"region": "South"
},
{
"month": "Mar",
"sales": 115,
"region": "North"
}
]
}
},
"userPrompt": "Show me interesting trends",
"metadata": {
"callId": "req-67890",
"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: 'month', label: 'Month'},
{key: 'sales', label: 'Sales'},
{key: 'region', label: 'Region'}
],
rows: [
{month: 'Jan', sales: 100, region: 'North'},
{month: 'Feb', sales: 120, region: 'South'},
{month: 'Mar', sales: 115, region: 'North'}
]
}
},
userPrompt: 'Show me interesting trends',
metadata: {callId: 'req-67890', locale: 'EN_US'}
})
};
fetch('https://agents.graphy.dev/api/v0/suggestions', 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/suggestions",
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' => 'month',
'label' => 'Month'
],
[
'key' => 'sales',
'label' => 'Sales'
],
[
'key' => 'region',
'label' => 'Region'
]
],
'rows' => [
[
'month' => 'Jan',
'sales' => 100,
'region' => 'North'
],
[
'month' => 'Feb',
'sales' => 120,
'region' => 'South'
],
[
'month' => 'Mar',
'sales' => 115,
'region' => 'North'
]
]
]
],
'userPrompt' => 'Show me interesting trends',
'metadata' => [
'callId' => 'req-67890',
'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/suggestions"
payload := strings.NewReader("{\n \"config\": {\n \"type\": \"column\",\n \"data\": {\n \"columns\": [\n {\n \"key\": \"month\",\n \"label\": \"Month\"\n },\n {\n \"key\": \"sales\",\n \"label\": \"Sales\"\n },\n {\n \"key\": \"region\",\n \"label\": \"Region\"\n }\n ],\n \"rows\": [\n {\n \"month\": \"Jan\",\n \"sales\": 100,\n \"region\": \"North\"\n },\n {\n \"month\": \"Feb\",\n \"sales\": 120,\n \"region\": \"South\"\n },\n {\n \"month\": \"Mar\",\n \"sales\": 115,\n \"region\": \"North\"\n }\n ]\n }\n },\n \"userPrompt\": \"Show me interesting trends\",\n \"metadata\": {\n \"callId\": \"req-67890\",\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/suggestions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"config\": {\n \"type\": \"column\",\n \"data\": {\n \"columns\": [\n {\n \"key\": \"month\",\n \"label\": \"Month\"\n },\n {\n \"key\": \"sales\",\n \"label\": \"Sales\"\n },\n {\n \"key\": \"region\",\n \"label\": \"Region\"\n }\n ],\n \"rows\": [\n {\n \"month\": \"Jan\",\n \"sales\": 100,\n \"region\": \"North\"\n },\n {\n \"month\": \"Feb\",\n \"sales\": 120,\n \"region\": \"South\"\n },\n {\n \"month\": \"Mar\",\n \"sales\": 115,\n \"region\": \"North\"\n }\n ]\n }\n },\n \"userPrompt\": \"Show me interesting trends\",\n \"metadata\": {\n \"callId\": \"req-67890\",\n \"locale\": \"EN_US\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://agents.graphy.dev/api/v0/suggestions")
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\": \"month\",\n \"label\": \"Month\"\n },\n {\n \"key\": \"sales\",\n \"label\": \"Sales\"\n },\n {\n \"key\": \"region\",\n \"label\": \"Region\"\n }\n ],\n \"rows\": [\n {\n \"month\": \"Jan\",\n \"sales\": 100,\n \"region\": \"North\"\n },\n {\n \"month\": \"Feb\",\n \"sales\": 120,\n \"region\": \"South\"\n },\n {\n \"month\": \"Mar\",\n \"sales\": 115,\n \"region\": \"North\"\n }\n ]\n }\n },\n \"userPrompt\": \"Show me interesting trends\",\n \"metadata\": {\n \"callId\": \"req-67890\",\n \"locale\": \"EN_US\"\n }\n}"
response = http.request(request)
puts response.read_body{
"message": "<string>"
}Generate chart type and data preparation suggestions from a dataset. Send a
Final response data:
Errors may also arrive as SSE events within a 200 response. See Error Codes.
GraphConfig and a prompt, receive suggested visualizations via Server-Sent Events.
Request body
Besidesconfig, userPrompt, and optional metadata, you may send maxSuggestionCount (integer 1–4). When set, it is communicated to the model as the target maximum number of suggestions. The stream is not validated or truncated to that count if the model returns more.
Response
The response is a Server-Sent Events stream. See SSE Format for parsing details.event: progress
data: {"message":"Generating suggestions..."}
event: complete
data: {"suggestions":[{"dataPrepPrompt":"...","chartType":"line","summary":"Monthly sales trend"}]}
interface SuggestionsResponse {
suggestions: Suggestion[];
}
interface Suggestion {
dataPrepPrompt: string;
chartType: AiChartType;
summary: 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 description of what to visualize
Maximum string length:
10000Optional tracking information for requests
Show child attributes
Show child attributes
Optional upper bound (1–4) communicated to the model for how many suggestions to aim for. The response is not truncated; the model may still return more items.
Required range:
1 <= x <= 4Response
SSE stream with progress and completion events
⌘I