API Endpoint

One endpoint, two methods. Send a chart config, get back an SVG or PNG.

Need stable URLs without exposing your API key in the markup? See Saved charts for the production embed primitive.

GET /chart

Pass the config as a query parameter. This is what makes <img> embeds work – no JavaScript required:

<img src='https://szum.io/chart?config={"version":"2026-03-20","format":"svg","marks":[{"type":"barY","data":[{"x":"Q1","y":42},{"x":"Q2","y":58}]}]}' />

GET requests are keyless – no API key, no sign-up. Limited to 200 renders per month per IP.

GET URLs must be percent-encoded in production. We show them unencoded here for readability. Your HTTP client or browser will typically handle this for you.

Both methods accept up to 50 KB of JSON.

Response

Header	Value
`Content-Type`	`image/svg+xml` or `image/png` (depends on `format`)
`Cache-Control`	`public, max-age=86400, s-maxage=604800, stale-while-revalidate=86400`
`Access-Control-Allow-Origin`	`*`

format is required – set it to "svg" or "png" in your config. CORS is fully open – you can call the API from any browser origin.

Responses are cached on Vercel's edge network. Identical URLs served from cache do not count as renders.

POST responses include usage headers:

Header	Description
`X-Usage-Used`	Renders consumed this month
`X-Usage-Limit`	Monthly render allowance for the plan
`X-Usage-Remaining`	Renders left before the included limit
`X-Usage-Overage`	`"true"` when rendering beyond the included quota (overage billing enabled)

Unauthenticated requests are limited to 10 requests per second per IP. Authenticated POST requests are limited to 30 requests per second per key. Beyond that, each plan has a monthly render allowance.

Plan	Monthly renders
Free	1,337
Pro	100,000 included

Pro users can opt in to overage billing ($1 per 5,000 additional renders). When you exceed your limit without overage billing, the API returns 429 Too Many Requests:

{ "error": "Monthly render limit exceeded. Enable overage billing at szum.io/dashboard/billing." }

Limits reset on the 1st of each month (UTC). See Plans & Limits for full details.

Errors

/chart returns the standard szum error envelope on any failure: { "error": "..." } with a meaningful HTTP status. See Errors for the full status table and response shape. The error message contains a JSON path like marks.0.type so you can jump straight to the offending field.

Common mistakes

Missing version – Every config needs "version": "2026-03-20". Without it you'll get a 400.

Missing format – format is required. Set it to "svg" or "png".

Wrong mark type – Valid types are barY, barX, line, dot, areaY, areaX, pie, text, ruleX, ruleY. Typos like "bar" or "Bar" will fail.

Mismatched field names – If your data has { "month": "Jan", "revenue": 42 } but your mark uses "x": "date", the chart will render with no data. Field names must match exactly.

Mixing sizing modes – You cannot set both width/height and plotWidth/plotHeight. Pick one. See Sizing.

Unquoted JSON in GET – The config query parameter must be valid JSON with double-quoted keys. Single quotes or unquoted keys will return a 400.

Versioning

version is required. The current version is "2026-03-20". Configs with older versions are automatically migrated forward – old configs keep working. See the changelog for version history.

Language examples

For Node and TypeScript, the @szum-io/sdk package provides typed configs, error handling, and timeouts out of the box. Any language that can make an HTTP request also works – see Language Examples for copy-paste examples in Node, Python, Go, Ruby, and curl.

For AI agents

Building an integration or tool that generates charts? Three resources:

MCP endpoint – POST https://szum.io/mcp – connect AI agents directly, no API key required.
szum.io/schema.json – JSON Schema for chart configs. Use it in tool definitions or for validation.
szum.io/llms.txt – Compact API reference designed for LLM context windows.