Skip to main content
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"
  }
}
'
{
  "message": "<string>"
}
Generate chart type and data preparation suggestions from a dataset. Send a GraphConfig and a prompt, receive suggested visualizations via Server-Sent Events.

​
Request body

Besides config, 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"}]}
Final response data: 
interface SuggestionsResponse {
  suggestions: Suggestion[];
}

interface Suggestion {
  dataPrepPrompt: string;
  chartType: AiChartType;
  summary: string;
}

​
HTTP Status Codes

StatusDescription
200Success (stream begins)
400Invalid request body
401Invalid or missing API key
429Rate limit exceeded
500Internal server error
Errors may also arrive as SSE events within a 200 response. See Error Codes.

Authorizations

​
Authorization
string
header
required

Your Graphy API key

Body

application/json
​
config
object
required

The graph configuration object used to render charts. See Graph Config Schema for the complete reference.

​
userPrompt
string
required

Natural language description of what to visualize

Maximum string length: 10000
​
metadata
object

Optional tracking information for requests

​
maxSuggestionCount
integer

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 <= 4

Response

SSE stream with progress and completion events

SSE event name is "progress"

​
message
string