API

Every endpoint, response headers, usage, errors and limits.

The API lives at https://api.chartshot.dev. A chart is a GET request, so it works anywhere an image URL does.

Authentication

Chart URLs work without a key, with the "chartshot.dev" badge. Everything else takes a key from the Keys page: send the secret key as Authorization: Bearer sk_live_…, or sign a chart URL with it. Keys and signed URLs explains both.

GET /v1/chart

Draws the chart a spec describes and returns the image.

Any other parameter is an error, so a typo doesn't go unnoticed. A secret key (sk_…) in the URL is refused, and should be rolled.

curl -o chart.png "https://api.chartshot.dev/v1/chart?c=eyJ0eXBlIjoiYmFyIiwiZGF0YSI6eyJsYWJlbHMiOlsiTW9uIiwiVHVlIl0sInNlcmllcyI6W3sibmFtZSI6IlNpZ251cHMiLCJ2YWx1ZXMiOlsxMiwxOF19XX19"

The image's format is the spec's format: png (the default), svg or webp. An SVG can't run scripts or load anything when opened on its own.

POST /v1/render

Draws the spec in the body (JSON, up to 64 KB) and returns the image, for code that handles the image itself. It takes a secret key, and its errors are always JSON.

curl https://api.chartshot.dev/v1/render \
  -H "Authorization: Bearer $CHARTSHOT_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d @spec.json -o chart.png

POST /v1/charts

Draws the spec in the body and stores the image at a permanent URL, for places that keep a link for a long time. Stored charts come with Pro and up, and are kept for 90 days on Pro and a year on Team and Business.

curl https://api.chartshot.dev/v1/charts \
  -H "Authorization: Bearer $CHARTSHOT_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d @spec.json

{
  "id": "7fQ2mZk1Lr8xWc3NvB0pYd",
  "url": "https://c.chartshot.dev/7fQ2mZk1Lr8xWc3NvB0pYd.png",
  "format": "png",
  "width": 600,
  "height": 300,
  "alt": "Bar chart. Signups, highest 18 (Tue), lowest 12 (Mon).",
  "expiresAt": "2027-01-22T09:30:00.000Z"
}

The id is random, so the URL can't be guessed. DELETE /v1/charts/{id} deletes a chart, and its URL stops working within a minute. The dashboard lists your stored charts.

GET /v1/usage

This month's renders for your account, every key together:

{
  "plan": "pro",
  "period": { "start": "2026-10-01", "end": "2026-11-01" },
  "renders": { "used": 1240, "included": 10000, "limit": 11000, "remaining": 8760 },
  "days": [{ "date": "2026-10-01", "renders": 310 }]
}

days lists the days with renders. Counts can lag by up to a minute.

Saved themes

Save a theme once and use it by id in any spec drawn with your key: "theme": "theme_…". A saved theme is the same object as an inline theme (extends, font, light, dark). The dashboard has an editor that imports a shadcn globals.css.

Pro saves three themes, Team and Business any number. Keyless chart URLs can't use saved themes.

Usage

Renders are counted per calendar month in UTC, for every plan, so the count resets on the 1st. Each chart a key gets counts once, whether it was drawn or came from the API's memory; a 304 and an error don't count, and neither do copies the CDN serves.

Past your plan's renders, charts keep coming for another 10%. After that, POST requests get usage_limit_reached (402) and signed URLs an image saying the limit is reached, until the month ends or you upgrade. The account's email gets a note at 80% and at 100%.

Response headers

Warnings

A field the spec doesn't know doesn't stop the chart. It is drawn without that field, and X-Chart-Warnings says what was ignored. Putting title at the top level instead of in options gives:

X-Chart-Warnings: title: Not a field, so it was ignored. Did you mean options.title?

Several warnings are joined with ; . Each one is percent-encoded on its own, ; included, so split on ; and decode each part (decodeURIComponent in JavaScript) to get the text back.

The playground shows the same warnings beside the editor.

Errors

An <img> can't show JSON, and shows any non-200 response as a broken image. So by default an error comes back as an image with status 200: a short message drawn at the size the spec asked for, with the code in X-Error-Code.

Add errors=status while you debug a URL, and the error comes back as JSON with its real status. Requests with a secret key always get JSON. issues lists each field at fault by its path in the spec:

{
  "error": {
    "code": "invalid_spec",
    "message": "data.series[0].values: Expected 2 values, one per label, got 1",
    "issues": [
      { "path": "data.series[0].values", "message": "Expected 2 values, one per label, got 1" }
    ]
  }
}

Error codes never change their meaning, so code can check them:

A series of only null values, a single value and null gaps are not errors: each draws a chart. A null leaves a gap in a line, and a lone value is drawn as a dot.

Limits

Each limit exists for a reason on the server or in an image format. Anything else a spec asks for is drawn.

POST /mcp

Chartshot's MCP server, for AI assistants, at https://api.chartshot.dev/mcp. It takes a secret key as Authorization: Bearer sk_live_…, like the other routes, and charts drawn through it count against your plan.

GET /v1/schema

Returns the spec's JSON Schema (draft 2020-12). Point an editor at it for autocomplete, or give it to a language model. It allows requests from any origin and is cached for an hour.

curl https://api.chartshot.dev/v1/schema

The spec reference is built from the same schema.