Narrative Agent

curl --request POST \
  --url https://agents.graphy.dev/api/v0/narrate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "config": {
    "type": "line",
    "data": {
      "columns": [
        {
          "key": "month",
          "label": "Month"
        },
        {
          "key": "users",
          "label": "Active Users"
        }
      ],
      "rows": [
        {
          "month": "Jan",
          "users": 1200
        },
        {
          "month": "Feb",
          "users": 1800
        },
        {
          "month": "Mar",
          "users": 3100
        }
      ]
    }
  },
  "userPrompt": "Write a punchy title and a one-line caption",
  "metadata": {
    "callId": "req-narrate-1",
    "locale": "EN_US"
  }
}
'

import requests

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

payload = {
    "config": {
        "type": "line",
        "data": {
            "columns": [
                {
                    "key": "month",
                    "label": "Month"
                },
                {
                    "key": "users",
                    "label": "Active Users"
                }
            ],
            "rows": [
                {
                    "month": "Jan",
                    "users": 1200
                },
                {
                    "month": "Feb",
                    "users": 1800
                },
                {
                    "month": "Mar",
                    "users": 3100
                }
            ]
        }
    },
    "userPrompt": "Write a punchy title and a one-line caption",
    "metadata": {
        "callId": "req-narrate-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: 'line',
      data: {
        columns: [{key: 'month', label: 'Month'}, {key: 'users', label: 'Active Users'}],
        rows: [
          {month: 'Jan', users: 1200},
          {month: 'Feb', users: 1800},
          {month: 'Mar', users: 3100}
        ]
      }
    },
    userPrompt: 'Write a punchy title and a one-line caption',
    metadata: {callId: 'req-narrate-1', locale: 'EN_US'}
  })
};

fetch('https://agents.graphy.dev/api/v0/narrate', 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/narrate",
  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' => 'line',
        'data' => [
                'columns' => [
                                [
                                                                'key' => 'month',
                                                                'label' => 'Month'
                                ],
                                [
                                                                'key' => 'users',
                                                                'label' => 'Active Users'
                                ]
                ],
                'rows' => [
                                [
                                                                'month' => 'Jan',
                                                                'users' => 1200
                                ],
                                [
                                                                'month' => 'Feb',
                                                                'users' => 1800
                                ],
                                [
                                                                'month' => 'Mar',
                                                                'users' => 3100
                                ]
                ]
        ]
    ],
    'userPrompt' => 'Write a punchy title and a one-line caption',
    'metadata' => [
        'callId' => 'req-narrate-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/narrate"

	payload := strings.NewReader("{\n  \"config\": {\n    \"type\": \"line\",\n    \"data\": {\n      \"columns\": [\n        {\n          \"key\": \"month\",\n          \"label\": \"Month\"\n        },\n        {\n          \"key\": \"users\",\n          \"label\": \"Active Users\"\n        }\n      ],\n      \"rows\": [\n        {\n          \"month\": \"Jan\",\n          \"users\": 1200\n        },\n        {\n          \"month\": \"Feb\",\n          \"users\": 1800\n        },\n        {\n          \"month\": \"Mar\",\n          \"users\": 3100\n        }\n      ]\n    }\n  },\n  \"userPrompt\": \"Write a punchy title and a one-line caption\",\n  \"metadata\": {\n    \"callId\": \"req-narrate-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/narrate")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"config\": {\n    \"type\": \"line\",\n    \"data\": {\n      \"columns\": [\n        {\n          \"key\": \"month\",\n          \"label\": \"Month\"\n        },\n        {\n          \"key\": \"users\",\n          \"label\": \"Active Users\"\n        }\n      ],\n      \"rows\": [\n        {\n          \"month\": \"Jan\",\n          \"users\": 1200\n        },\n        {\n          \"month\": \"Feb\",\n          \"users\": 1800\n        },\n        {\n          \"month\": \"Mar\",\n          \"users\": 3100\n        }\n      ]\n    }\n  },\n  \"userPrompt\": \"Write a punchy title and a one-line caption\",\n  \"metadata\": {\n    \"callId\": \"req-narrate-1\",\n    \"locale\": \"EN_US\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

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

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\": \"line\",\n    \"data\": {\n      \"columns\": [\n        {\n          \"key\": \"month\",\n          \"label\": \"Month\"\n        },\n        {\n          \"key\": \"users\",\n          \"label\": \"Active Users\"\n        }\n      ],\n      \"rows\": [\n        {\n          \"month\": \"Jan\",\n          \"users\": 1200\n        },\n        {\n          \"month\": \"Feb\",\n          \"users\": 1800\n        },\n        {\n          \"month\": \"Mar\",\n          \"users\": 3100\n        }\n      ]\n    }\n  },\n  \"userPrompt\": \"Write a punchy title and a one-line caption\",\n  \"metadata\": {\n    \"callId\": \"req-narrate-1\",\n    \"locale\": \"EN_US\"\n  }\n}"

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

{
  "message": "<string>"
}

POST

api

narrate

Narrative Agent

curl --request POST \
  --url https://agents.graphy.dev/api/v0/narrate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "config": {
    "type": "line",
    "data": {
      "columns": [
        {
          "key": "month",
          "label": "Month"
        },
        {
          "key": "users",
          "label": "Active Users"
        }
      ],
      "rows": [
        {
          "month": "Jan",
          "users": 1200
        },
        {
          "month": "Feb",
          "users": 1800
        },
        {
          "month": "Mar",
          "users": 3100
        }
      ]
    }
  },
  "userPrompt": "Write a punchy title and a one-line caption",
  "metadata": {
    "callId": "req-narrate-1",
    "locale": "EN_US"
  }
}
'

import requests

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

payload = {
    "config": {
        "type": "line",
        "data": {
            "columns": [
                {
                    "key": "month",
                    "label": "Month"
                },
                {
                    "key": "users",
                    "label": "Active Users"
                }
            ],
            "rows": [
                {
                    "month": "Jan",
                    "users": 1200
                },
                {
                    "month": "Feb",
                    "users": 1800
                },
                {
                    "month": "Mar",
                    "users": 3100
                }
            ]
        }
    },
    "userPrompt": "Write a punchy title and a one-line caption",
    "metadata": {
        "callId": "req-narrate-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: 'line',
      data: {
        columns: [{key: 'month', label: 'Month'}, {key: 'users', label: 'Active Users'}],
        rows: [
          {month: 'Jan', users: 1200},
          {month: 'Feb', users: 1800},
          {month: 'Mar', users: 3100}
        ]
      }
    },
    userPrompt: 'Write a punchy title and a one-line caption',
    metadata: {callId: 'req-narrate-1', locale: 'EN_US'}
  })
};

fetch('https://agents.graphy.dev/api/v0/narrate', 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/narrate",
  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' => 'line',
        'data' => [
                'columns' => [
                                [
                                                                'key' => 'month',
                                                                'label' => 'Month'
                                ],
                                [
                                                                'key' => 'users',
                                                                'label' => 'Active Users'
                                ]
                ],
                'rows' => [
                                [
                                                                'month' => 'Jan',
                                                                'users' => 1200
                                ],
                                [
                                                                'month' => 'Feb',
                                                                'users' => 1800
                                ],
                                [
                                                                'month' => 'Mar',
                                                                'users' => 3100
                                ]
                ]
        ]
    ],
    'userPrompt' => 'Write a punchy title and a one-line caption',
    'metadata' => [
        'callId' => 'req-narrate-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/narrate"

	payload := strings.NewReader("{\n  \"config\": {\n    \"type\": \"line\",\n    \"data\": {\n      \"columns\": [\n        {\n          \"key\": \"month\",\n          \"label\": \"Month\"\n        },\n        {\n          \"key\": \"users\",\n          \"label\": \"Active Users\"\n        }\n      ],\n      \"rows\": [\n        {\n          \"month\": \"Jan\",\n          \"users\": 1200\n        },\n        {\n          \"month\": \"Feb\",\n          \"users\": 1800\n        },\n        {\n          \"month\": \"Mar\",\n          \"users\": 3100\n        }\n      ]\n    }\n  },\n  \"userPrompt\": \"Write a punchy title and a one-line caption\",\n  \"metadata\": {\n    \"callId\": \"req-narrate-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/narrate")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"config\": {\n    \"type\": \"line\",\n    \"data\": {\n      \"columns\": [\n        {\n          \"key\": \"month\",\n          \"label\": \"Month\"\n        },\n        {\n          \"key\": \"users\",\n          \"label\": \"Active Users\"\n        }\n      ],\n      \"rows\": [\n        {\n          \"month\": \"Jan\",\n          \"users\": 1200\n        },\n        {\n          \"month\": \"Feb\",\n          \"users\": 1800\n        },\n        {\n          \"month\": \"Mar\",\n          \"users\": 3100\n        }\n      ]\n    }\n  },\n  \"userPrompt\": \"Write a punchy title and a one-line caption\",\n  \"metadata\": {\n    \"callId\": \"req-narrate-1\",\n    \"locale\": \"EN_US\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

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

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\": \"line\",\n    \"data\": {\n      \"columns\": [\n        {\n          \"key\": \"month\",\n          \"label\": \"Month\"\n        },\n        {\n          \"key\": \"users\",\n          \"label\": \"Active Users\"\n        }\n      ],\n      \"rows\": [\n        {\n          \"month\": \"Jan\",\n          \"users\": 1200\n        },\n        {\n          \"month\": \"Feb\",\n          \"users\": 1800\n        },\n        {\n          \"month\": \"Mar\",\n          \"users\": 3100\n        }\n      ]\n    }\n  },\n  \"userPrompt\": \"Write a punchy title and a one-line caption\",\n  \"metadata\": {\n    \"callId\": \"req-narrate-1\",\n    \"locale\": \"EN_US\"\n  }\n}"

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

{
  "message": "<string>"
}

Generate a chart’s title, subtitle, and caption with natural language. Send a GraphConfig and a prompt, receive an updated GraphConfig via Server-Sent Events. Narrative is written into config.content as TipTap JSON.

Request body

userPrompt is required — the narrative agent needs an instruction to write against. Which fields are produced (title only, title + caption, or all three) depends on the storytelling level derived from metadata.effort.

Response

The response is a Server-Sent Events stream. See SSE Format for parsing details.

event: progress
data: {"message":"Generating narrative..."}

event: complete
data: {"config":{...},"response":{"message":"Wrote a title and caption"}}

Final response data:

interface NarrateResponse {
  config: GraphConfig;
  response: {
    message: 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

Annotation Agent Extract Agent

Get Started

TypeScript SDK

REST API

Reference

Narrative Agent

Request body

Response

HTTP Status Codes

Authorizations

Body

Response

​Request body

​Response

​HTTP Status Codes

Authorizations

Body

Response

Request body

Response

HTTP Status Codes