REST API

Generate charts and boards programmatically using the Chartr.ai API.

Base URL: https://chartr.ai

Endpoints

Method	Path	Description
`GET`	`/api/v1/charts/types`	List available chart types (no auth)
`GET`	`/api/v1/charts/types/:code`	Get JSON schema + example for a chart type (no auth)
`POST`	`/api/v1/render`	Render chart JSON to an image (and optionally save)

The below endpoints use AI and consume credits:

Method	Path	Description
`POST`	`/api/v1/boards`	Generate a multi-chart board from a prompt
`POST`	`/api/v1/chart`	Generate a single chart from a prompt

Authentication

All requests require an API key via the X-API-Key header.

-H "X-API-Key: YOUR_API_KEY"

Get your API key from Settings.

List Chart Types

List all chart type IDs and labels. No authentication required; useful for discovery and UIs.

GET /api/v1/charts/types

Response

{ "types": [ { "id": "barChart", "label": "Bar Chart", "description": "Compare values side by side" }, { "id": "timeline", "label": "Timeline", "description": "Show events chronologically" } ] }

Get Chart Type Schema

Get the JSON schema, validation rules, and an example payload for a chart type. Use with Render Chart to build charts programmatically. No authentication required.

GET /api/v1/charts/types/:code

Param	Description
`code`	Chart type ID (e.g. `barChart`, `timeline`, `mermaid_flowchart`). See List Chart Types.

Response

{ "id": "barChart", "label": "Bar Chart", "description": "Compare values side by side", "jsonSchema": { ... }, "rules": [ ... ], "example": { "code": "barChart", "title": "...", "bars": [...] } }

Render chart data (JSON) to a PNG image. Use this when you already have chart payloads (e.g. from your own UI or from GET /api/v1/charts/types/:code) and want an image without going through the LLM. Counts against your usage.

POST /api/v1/render

Request

curl -X POST https://chartr.ai/api/v1/render \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "chart": { "code": "barChart", "title": "Sales 2024", "bars": [...] }, "imageOptions": { "withTitle": true, "withFootnotes": true, "withBackground": true }, "save": false }'

Parameter	Type	Required	Description
`chart`	object	Yes	Chart payload. Must include `code`; shape depends on type. Use `/api/v1/charts/types/:code` for schema + example.
`imageOptions`	object	No	Controls what appears in the chart image
`imageOptions.withTitle`	boolean	No	Include title and subtitle (default: `true`)
`imageOptions.withFootnotes`	boolean	No	Include footnotes (default: `true`)
`imageOptions.withBackground`	boolean	No	Include background (default: `true`)
`save`	boolean	No	If `true`, persist chart as a board and return `id`, `url`. Default: `false`.

Response

{ "imageUrl": "https://storage-url.com/chart-xxx.png", "chartData": { ... }, "id": "optional-board-id-if-save-true", "url": "https://chartr.ai/boards/optional-board-id" }

Generate Board

Generate a board with one or more charts. Returns the board URL and chart image URLs.

POST /api/v1/boards

Request

curl -X POST https://chartr.ai/api/v1/boards \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Create a timeline of major AI breakthroughs in 2024" }'

Parameter	Type	Required	Description
`prompt`	string	Yes	Prompt describing the board to generate
`imageOptions`	object	No	Controls what appears in chart images
`imageOptions.withTitle`	boolean	No	Include title and subtitle (default: `true`)
`imageOptions.withFootnotes`	boolean	No	Include footnotes (default: `true`)
`imageOptions.withBackground`	boolean	No	Include background (default: `true`)

Response

{ "id": "board_id_here", "url": "https://chartr.ai/boards/board_id_here", "title": "AI Breakthroughs Timeline 2024", "charts": 1, "imageUrls": ["https://storage-url.com/chart-0.png"] }

Field	Type	Description
`id`	string	Board ID
`url`	string	Direct link to the board
`title`	string	Generated title
`charts`	number	Number of charts created
`imageUrls`	string	Image URLs for each chart

Generate Chart

Generate a single chart. Returns chart data and an image URL.

POST /api/v1/chart

Request

curl -X POST https://chartr.ai/api/v1/chart \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Create a quadrant comparing dog breeds" }'

Parameter	Type	Required	Description
`prompt`	string	Yes	Prompt describing the chart to generate
`imageOptions`	object	No	Controls what appears in the chart image
`imageOptions.withTitle`	boolean	No	Include title and subtitle (default: `true`)
`imageOptions.withFootnotes`	boolean	No	Include footnotes (default: `true`)
`imageOptions.withBackground`	boolean	No	Include background (default: `true`)

Response

{ "id": "chart_id_here", "url": "https://chartr.ai/boards/chart_id_here", "title": "Create a quadrant comparing dog breeds", "chartData": { ... }, "imageUrl": "https://storage-url.com/chart.png" }

Field	Type	Description
`id`	string	Chart ID
`url`	string	Direct link to the board
`title`	string	Generated title
`chartData`	object	Raw chart data
`imageUrl`	string	Chart image URL

Examples

JavaScript

// Generate a single chart const chart = await fetch('https://chartr.ai/api/v1/chart', { method: 'POST', headers: { 'X-API-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ prompt: 'Create a timeline of Beatles albums' }) }).then(r => r.json()); // chart.imageUrl - embed as // chart.url - link to interactive board

// Generate a board (multiple charts) const board = await fetch('https://chartr.ai/api/v1/boards', { method: 'POST', headers: { 'X-API-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ prompt: 'Compare top 5 programming languages by popularity, salary, and job openings', imageOptions: { withBackground: false } }) }).then(r => r.json()); // board.imageUrls - array of chart images // board.url - link to interactive board

Support

Questions or issues? Contact us at support@chartr.ai