Evaluation
curl --request POST \
--url https://agents.graphy.dev/api/v0/evaluate \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"config": {
"type": "column",
"data": {
"columns": [
{
"key": "product",
"label": "Product"
},
{
"key": "revenue",
"label": "Revenue"
}
],
"rows": [
{
"product": "Widget A",
"revenue": 4200
},
{
"product": "Widget B",
"revenue": 3100
},
{
"product": "Widget C",
"revenue": 5600
}
]
}
},
"metadata": {
"callId": "req-evaluate-1"
}
}
'import requests
url = "https://agents.graphy.dev/api/v0/evaluate"
payload = {
"config": {
"type": "column",
"data": {
"columns": [
{
"key": "product",
"label": "Product"
},
{
"key": "revenue",
"label": "Revenue"
}
],
"rows": [
{
"product": "Widget A",
"revenue": 4200
},
{
"product": "Widget B",
"revenue": 3100
},
{
"product": "Widget C",
"revenue": 5600
}
]
}
},
"metadata": { "callId": "req-evaluate-1" }
}
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: 'product', label: 'Product'}, {key: 'revenue', label: 'Revenue'}],
rows: [
{product: 'Widget A', revenue: 4200},
{product: 'Widget B', revenue: 3100},
{product: 'Widget C', revenue: 5600}
]
}
},
metadata: {callId: 'req-evaluate-1'}
})
};
fetch('https://agents.graphy.dev/api/v0/evaluate', 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/evaluate",
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' => 'product',
'label' => 'Product'
],
[
'key' => 'revenue',
'label' => 'Revenue'
]
],
'rows' => [
[
'product' => 'Widget A',
'revenue' => 4200
],
[
'product' => 'Widget B',
'revenue' => 3100
],
[
'product' => 'Widget C',
'revenue' => 5600
]
]
]
],
'metadata' => [
'callId' => 'req-evaluate-1'
]
]),
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/evaluate"
payload := strings.NewReader("{\n \"config\": {\n \"type\": \"column\",\n \"data\": {\n \"columns\": [\n {\n \"key\": \"product\",\n \"label\": \"Product\"\n },\n {\n \"key\": \"revenue\",\n \"label\": \"Revenue\"\n }\n ],\n \"rows\": [\n {\n \"product\": \"Widget A\",\n \"revenue\": 4200\n },\n {\n \"product\": \"Widget B\",\n \"revenue\": 3100\n },\n {\n \"product\": \"Widget C\",\n \"revenue\": 5600\n }\n ]\n }\n },\n \"metadata\": {\n \"callId\": \"req-evaluate-1\"\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/evaluate")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"config\": {\n \"type\": \"column\",\n \"data\": {\n \"columns\": [\n {\n \"key\": \"product\",\n \"label\": \"Product\"\n },\n {\n \"key\": \"revenue\",\n \"label\": \"Revenue\"\n }\n ],\n \"rows\": [\n {\n \"product\": \"Widget A\",\n \"revenue\": 4200\n },\n {\n \"product\": \"Widget B\",\n \"revenue\": 3100\n },\n {\n \"product\": \"Widget C\",\n \"revenue\": 5600\n }\n ]\n }\n },\n \"metadata\": {\n \"callId\": \"req-evaluate-1\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://agents.graphy.dev/api/v0/evaluate")
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\": \"product\",\n \"label\": \"Product\"\n },\n {\n \"key\": \"revenue\",\n \"label\": \"Revenue\"\n }\n ],\n \"rows\": [\n {\n \"product\": \"Widget A\",\n \"revenue\": 4200\n },\n {\n \"product\": \"Widget B\",\n \"revenue\": 3100\n },\n {\n \"product\": \"Widget C\",\n \"revenue\": 5600\n }\n ]\n }\n },\n \"metadata\": {\n \"callId\": \"req-evaluate-1\"\n }\n}"
response = http.request(request)
puts response.read_body{
"ranking": [
{
"rank": 123,
"score": 123,
"factors": [
{
"label": "<string>",
"weight": 123,
"reason": "<string>"
}
]
}
]
}REST API
Evaluation
Score how well every chart type fits a dataset. Deterministic — a rule-based scorer with no language model, so it returns a single result and uses no tokens. Only config.data is scored.
The response is a Server-Sent Events (SSE) stream. Evaluation emits no progress events — the result arrives in a single complete event.
POST
/
api
/
v0
/
evaluate
Evaluation
curl --request POST \
--url https://agents.graphy.dev/api/v0/evaluate \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"config": {
"type": "column",
"data": {
"columns": [
{
"key": "product",
"label": "Product"
},
{
"key": "revenue",
"label": "Revenue"
}
],
"rows": [
{
"product": "Widget A",
"revenue": 4200
},
{
"product": "Widget B",
"revenue": 3100
},
{
"product": "Widget C",
"revenue": 5600
}
]
}
},
"metadata": {
"callId": "req-evaluate-1"
}
}
'import requests
url = "https://agents.graphy.dev/api/v0/evaluate"
payload = {
"config": {
"type": "column",
"data": {
"columns": [
{
"key": "product",
"label": "Product"
},
{
"key": "revenue",
"label": "Revenue"
}
],
"rows": [
{
"product": "Widget A",
"revenue": 4200
},
{
"product": "Widget B",
"revenue": 3100
},
{
"product": "Widget C",
"revenue": 5600
}
]
}
},
"metadata": { "callId": "req-evaluate-1" }
}
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: 'product', label: 'Product'}, {key: 'revenue', label: 'Revenue'}],
rows: [
{product: 'Widget A', revenue: 4200},
{product: 'Widget B', revenue: 3100},
{product: 'Widget C', revenue: 5600}
]
}
},
metadata: {callId: 'req-evaluate-1'}
})
};
fetch('https://agents.graphy.dev/api/v0/evaluate', 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/evaluate",
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' => 'product',
'label' => 'Product'
],
[
'key' => 'revenue',
'label' => 'Revenue'
]
],
'rows' => [
[
'product' => 'Widget A',
'revenue' => 4200
],
[
'product' => 'Widget B',
'revenue' => 3100
],
[
'product' => 'Widget C',
'revenue' => 5600
]
]
]
],
'metadata' => [
'callId' => 'req-evaluate-1'
]
]),
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/evaluate"
payload := strings.NewReader("{\n \"config\": {\n \"type\": \"column\",\n \"data\": {\n \"columns\": [\n {\n \"key\": \"product\",\n \"label\": \"Product\"\n },\n {\n \"key\": \"revenue\",\n \"label\": \"Revenue\"\n }\n ],\n \"rows\": [\n {\n \"product\": \"Widget A\",\n \"revenue\": 4200\n },\n {\n \"product\": \"Widget B\",\n \"revenue\": 3100\n },\n {\n \"product\": \"Widget C\",\n \"revenue\": 5600\n }\n ]\n }\n },\n \"metadata\": {\n \"callId\": \"req-evaluate-1\"\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/evaluate")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"config\": {\n \"type\": \"column\",\n \"data\": {\n \"columns\": [\n {\n \"key\": \"product\",\n \"label\": \"Product\"\n },\n {\n \"key\": \"revenue\",\n \"label\": \"Revenue\"\n }\n ],\n \"rows\": [\n {\n \"product\": \"Widget A\",\n \"revenue\": 4200\n },\n {\n \"product\": \"Widget B\",\n \"revenue\": 3100\n },\n {\n \"product\": \"Widget C\",\n \"revenue\": 5600\n }\n ]\n }\n },\n \"metadata\": {\n \"callId\": \"req-evaluate-1\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://agents.graphy.dev/api/v0/evaluate")
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\": \"product\",\n \"label\": \"Product\"\n },\n {\n \"key\": \"revenue\",\n \"label\": \"Revenue\"\n }\n ],\n \"rows\": [\n {\n \"product\": \"Widget A\",\n \"revenue\": 4200\n },\n {\n \"product\": \"Widget B\",\n \"revenue\": 3100\n },\n {\n \"product\": \"Widget C\",\n \"revenue\": 5600\n }\n ]\n }\n },\n \"metadata\": {\n \"callId\": \"req-evaluate-1\"\n }\n}"
response = http.request(request)
puts response.read_body{
"ranking": [
{
"rank": 123,
"score": 123,
"factors": [
{
"label": "<string>",
"weight": 123,
"reason": "<string>"
}
]
}
]
}Score how well every chart type fits a dataset. Evaluation is deterministic — a rule-based scorer with no language model — so it returns a single result and uses no tokens. Send a
Final response data:
See the SDK Evaluation page for the full
Errors may also arrive as SSE events within a 200 response — for example, a dataset with no plottable columns. See Error Codes.
GraphConfig, receive a ranked list of chart types via Server-Sent Events.
Request body
Send aGraphConfig in config. Only config.data is scored — the chart type, styling, and annotations are ignored. Optionally pass a chartFamily hint (comparison, relationship, distribution, composition) to bias the ranking toward that family.
Response
The response is a Server-Sent Events stream. See SSE Format for parsing details. Evaluation is deterministic, so there are noprogress events — the result arrives in a single complete event.
event: complete
data: {"ranking":[{"rank":1,"type":"bar","score":0.82,"verdict":"ok","factors":[{"kind":"pro","label":"Categorical x-axis","weight":0.3,"reason":"One categorical dimension maps cleanly to bars"}]}]}
interface EvaluateResponse {
ranking: ChartFitEntry[];
}
interface ChartFitEntry {
rank: number;
type: AiChartType;
score: number;
verdict: 'ok' | 'disqualified';
factors: ChartFitFactor[];
}
ChartFitEntry and ChartFitFactor field reference.
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
Deterministic evaluation reads only config.data and the optional chartFamily — there is no userPrompt.
The graph configuration object used to render charts. See Graph Config Schema for the complete reference.
Show child attributes
Show child attributes
Optional Abela chart-family hint. When set, chart types in that family get a fit bonus.
Available options:
comparison, relationship, distribution, composition Optional tracking information for requests
Show child attributes
Show child attributes
Response
SSE stream with a single completion event
- Evaluation complete event
- Error event
SSE event name is "complete". Evaluation emits no progress events.
Every supported chart type, scored and ranked by fit (best first).
Show child attributes
Show child attributes
⌘I