Annotation Agent

curl --request POST \
  --url https://agents.graphy.dev/api/v0/annotate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "config": {
    "type": "column",
    "data": {
      "columns": [
        {
          "key": "month",
          "label": "Month"
        },
        {
          "key": "revenue",
          "label": "Revenue"
        }
      ],
      "rows": [
        {
          "month": "Jan",
          "revenue": 100
        },
        {
          "month": "Feb",
          "revenue": 140
        },
        {
          "month": "Mar",
          "revenue": 220
        }
      ]
    }
  },
  "userPrompt": "Highlight the March peak and add a tooltip explaining it",
  "metadata": {
    "callId": "req-annotate-1",
    "locale": "EN_US"
  }
}
'

import requests

url = "https://agents.graphy.dev/api/v0/annotate"

payload = {
    "config": {
        "type": "column",
        "data": {
            "columns": [
                {
                    "key": "month",
                    "label": "Month"
                },
                {
                    "key": "revenue",
                    "label": "Revenue"
                }
            ],
            "rows": [
                {
                    "month": "Jan",
                    "revenue": 100
                },
                {
                    "month": "Feb",
                    "revenue": 140
                },
                {
                    "month": "Mar",
                    "revenue": 220
                }
            ]
        }
    },
    "userPrompt": "Highlight the March peak and add a tooltip explaining it",
    "metadata": {
        "callId": "req-annotate-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: 'month', label: 'Month'}, {key: 'revenue', label: 'Revenue'}],
        rows: [
          {month: 'Jan', revenue: 100},
          {month: 'Feb', revenue: 140},
          {month: 'Mar', revenue: 220}
        ]
      }
    },
    userPrompt: 'Highlight the March peak and add a tooltip explaining it',
    metadata: {callId: 'req-annotate-1', locale: 'EN_US'}
  })
};

fetch('https://agents.graphy.dev/api/v0/annotate', 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/annotate",
  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' => 'revenue',
                                                                'label' => 'Revenue'
                                ]
                ],
                'rows' => [
                                [
                                                                'month' => 'Jan',
                                                                'revenue' => 100
                                ],
                                [
                                                                'month' => 'Feb',
                                                                'revenue' => 140
                                ],
                                [
                                                                'month' => 'Mar',
                                                                'revenue' => 220
                                ]
                ]
        ]
    ],
    'userPrompt' => 'Highlight the March peak and add a tooltip explaining it',
    'metadata' => [
        'callId' => 'req-annotate-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/annotate"

	payload := strings.NewReader("{\n  \"config\": {\n    \"type\": \"column\",\n    \"data\": {\n      \"columns\": [\n        {\n          \"key\": \"month\",\n          \"label\": \"Month\"\n        },\n        {\n          \"key\": \"revenue\",\n          \"label\": \"Revenue\"\n        }\n      ],\n      \"rows\": [\n        {\n          \"month\": \"Jan\",\n          \"revenue\": 100\n        },\n        {\n          \"month\": \"Feb\",\n          \"revenue\": 140\n        },\n        {\n          \"month\": \"Mar\",\n          \"revenue\": 220\n        }\n      ]\n    }\n  },\n  \"userPrompt\": \"Highlight the March peak and add a tooltip explaining it\",\n  \"metadata\": {\n    \"callId\": \"req-annotate-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/annotate")
  .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\": \"revenue\",\n          \"label\": \"Revenue\"\n        }\n      ],\n      \"rows\": [\n        {\n          \"month\": \"Jan\",\n          \"revenue\": 100\n        },\n        {\n          \"month\": \"Feb\",\n          \"revenue\": 140\n        },\n        {\n          \"month\": \"Mar\",\n          \"revenue\": 220\n        }\n      ]\n    }\n  },\n  \"userPrompt\": \"Highlight the March peak and add a tooltip explaining it\",\n  \"metadata\": {\n    \"callId\": \"req-annotate-1\",\n    \"locale\": \"EN_US\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://agents.graphy.dev/api/v0/annotate")

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\": \"revenue\",\n          \"label\": \"Revenue\"\n        }\n      ],\n      \"rows\": [\n        {\n          \"month\": \"Jan\",\n          \"revenue\": 100\n        },\n        {\n          \"month\": \"Feb\",\n          \"revenue\": 140\n        },\n        {\n          \"month\": \"Mar\",\n          \"revenue\": 220\n        }\n      ]\n    }\n  },\n  \"userPrompt\": \"Highlight the March peak and add a tooltip explaining it\",\n  \"metadata\": {\n    \"callId\": \"req-annotate-1\",\n    \"locale\": \"EN_US\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "message": "<string>"
}

POST

api

annotate

Annotation Agent

curl --request POST \
  --url https://agents.graphy.dev/api/v0/annotate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "config": {
    "type": "column",
    "data": {
      "columns": [
        {
          "key": "month",
          "label": "Month"
        },
        {
          "key": "revenue",
          "label": "Revenue"
        }
      ],
      "rows": [
        {
          "month": "Jan",
          "revenue": 100
        },
        {
          "month": "Feb",
          "revenue": 140
        },
        {
          "month": "Mar",
          "revenue": 220
        }
      ]
    }
  },
  "userPrompt": "Highlight the March peak and add a tooltip explaining it",
  "metadata": {
    "callId": "req-annotate-1",
    "locale": "EN_US"
  }
}
'

import requests

url = "https://agents.graphy.dev/api/v0/annotate"

payload = {
    "config": {
        "type": "column",
        "data": {
            "columns": [
                {
                    "key": "month",
                    "label": "Month"
                },
                {
                    "key": "revenue",
                    "label": "Revenue"
                }
            ],
            "rows": [
                {
                    "month": "Jan",
                    "revenue": 100
                },
                {
                    "month": "Feb",
                    "revenue": 140
                },
                {
                    "month": "Mar",
                    "revenue": 220
                }
            ]
        }
    },
    "userPrompt": "Highlight the March peak and add a tooltip explaining it",
    "metadata": {
        "callId": "req-annotate-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: 'month', label: 'Month'}, {key: 'revenue', label: 'Revenue'}],
        rows: [
          {month: 'Jan', revenue: 100},
          {month: 'Feb', revenue: 140},
          {month: 'Mar', revenue: 220}
        ]
      }
    },
    userPrompt: 'Highlight the March peak and add a tooltip explaining it',
    metadata: {callId: 'req-annotate-1', locale: 'EN_US'}
  })
};

fetch('https://agents.graphy.dev/api/v0/annotate', 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/annotate",
  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' => 'revenue',
                                                                'label' => 'Revenue'
                                ]
                ],
                'rows' => [
                                [
                                                                'month' => 'Jan',
                                                                'revenue' => 100
                                ],
                                [
                                                                'month' => 'Feb',
                                                                'revenue' => 140
                                ],
                                [
                                                                'month' => 'Mar',
                                                                'revenue' => 220
                                ]
                ]
        ]
    ],
    'userPrompt' => 'Highlight the March peak and add a tooltip explaining it',
    'metadata' => [
        'callId' => 'req-annotate-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/annotate"

	payload := strings.NewReader("{\n  \"config\": {\n    \"type\": \"column\",\n    \"data\": {\n      \"columns\": [\n        {\n          \"key\": \"month\",\n          \"label\": \"Month\"\n        },\n        {\n          \"key\": \"revenue\",\n          \"label\": \"Revenue\"\n        }\n      ],\n      \"rows\": [\n        {\n          \"month\": \"Jan\",\n          \"revenue\": 100\n        },\n        {\n          \"month\": \"Feb\",\n          \"revenue\": 140\n        },\n        {\n          \"month\": \"Mar\",\n          \"revenue\": 220\n        }\n      ]\n    }\n  },\n  \"userPrompt\": \"Highlight the March peak and add a tooltip explaining it\",\n  \"metadata\": {\n    \"callId\": \"req-annotate-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/annotate")
  .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\": \"revenue\",\n          \"label\": \"Revenue\"\n        }\n      ],\n      \"rows\": [\n        {\n          \"month\": \"Jan\",\n          \"revenue\": 100\n        },\n        {\n          \"month\": \"Feb\",\n          \"revenue\": 140\n        },\n        {\n          \"month\": \"Mar\",\n          \"revenue\": 220\n        }\n      ]\n    }\n  },\n  \"userPrompt\": \"Highlight the March peak and add a tooltip explaining it\",\n  \"metadata\": {\n    \"callId\": \"req-annotate-1\",\n    \"locale\": \"EN_US\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://agents.graphy.dev/api/v0/annotate")

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\": \"revenue\",\n          \"label\": \"Revenue\"\n        }\n      ],\n      \"rows\": [\n        {\n          \"month\": \"Jan\",\n          \"revenue\": 100\n        },\n        {\n          \"month\": \"Feb\",\n          \"revenue\": 140\n        },\n        {\n          \"month\": \"Mar\",\n          \"revenue\": 220\n        }\n      ]\n    }\n  },\n  \"userPrompt\": \"Highlight the March peak and add a tooltip explaining it\",\n  \"metadata\": {\n    \"callId\": \"req-annotate-1\",\n    \"locale\": \"EN_US\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "message": "<string>"
}

Add highlights, tooltips, stickers, and other annotations to a chart with natural language. Send a 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":"Adding annotations..."}

event: complete
data: {"config":{...},"response":{"message":"Highlighted the March peak","steps":["Added highlight","Added tooltip"]}}

Final response data:

interface AnnotateResponse {
  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

Errors may also arrive as SSE events within a 200 response. See Error Codes.

Authorizations

Authorization

string

header

required

Your Graphy API key (starts with graphy_). Create one in the Graphy console at https://agents.graphy.dev/console/

Body

application/json

config

object

required

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

Show child attributes

userPrompt

string

required

Natural language instruction describing the desired changes

Maximum string length: 10000

metadata

object

Optional tracking information for requests

Show child attributes

Response

SSE stream with progress and completion events

Progress event
Complete event
Error event

SSE event name is "progress"

message

string

Get Started

TypeScript SDK

REST API

Reference

Annotation Agent

Response

HTTP Status Codes

Authorizations

Body

Response

​Response

​HTTP Status Codes

Authorizations

Body

Response

Response

HTTP Status Codes