Developers

HTTP API

Validate documents, render images, and manage saved charts.

The chart image API accepts the same chart document as Studio, Figma, MCP, and the TypeScript SDK. Its JSON endpoints use UTF-8 and allow cross-origin requests.

POST /validate

Validate a ChartDocument or supported 2026-03-20 config without rendering or saving. Validation needs no key, is read-only, and does not count against any render allowance.

curl 'https://szum.io/validate' \
  --fail-with-body \
  --max-time 30 \
  -H 'Content-Type: application/json' \
  -d '{
  "version": "2026-09-26",
  "config": {
    "version": "2026-09-26",
    "type": "column",
    "category": { "field": "quarter" },
    "values": { "type": "long", "field": "revenue" }
  },
  "data": [
    { "quarter": "Q1", "revenue": 42 },
    { "quarter": "Q2", "revenue": 58 }
  ],
  "output": { "format": "svg" }
}'

Valid and invalid charts both return a validation result:

{
  "valid": true,
  "diagnostics": []
}

When a deterministic fix exists, the result may include one complete, validated suggestedDocument; review it before using it, and validate again only if you change it. An older config also gets a compatibility object with its classification and codes. See Validation and compatibility.

Send an API key to also check the chart rules your workspace enforces. Their findings join diagnostics with the workspace_rule code, and a rule set to Block makes the chart invalid. Without a key, validation never reads account state.

POST /chart

Render a current ChartDocument or supported 2026-03-20 config. New integrations should send a document. Authenticate with an API key or a dashboard session. The response body is the image in the selected format.

curl 'https://szum.io/chart' \
  --fail \
  --max-time 30 \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "version": "2026-09-26",
  "config": {
    "version": "2026-09-26",
    "type": "column",
    "category": { "field": "quarter" },
    "values": { "type": "long", "field": "revenue" }
  },
  "data": [
    { "quarter": "Q1", "revenue": 42 },
    { "quarter": "Q2", "revenue": 58 }
  ],
  "output": { "format": "svg" }
}' \
  --output 'chart.svg'

Successful responses carry the image Content-Type, Content-Length, and the account’s X-Usage-* headers, and use private, no-store because usage is account-specific.

Theme overrides require Creator, Pro, or Team. Free output uses built-in themes and includes attribution. Semantic errors, plan rejections, and failed renders are not charged.

In a Team workspace, a chart that breaks a chart rule set to Block is refused with validation_failed before rendering, and rules set to Warn are listed in X-Chart-Diagnostics with the image.

In a Team workspace, add ?sharedTheme=NAME to render in one of the workspace’s shared themes. A document that sets neither theme nor themeOverrides renders in the workspace’s default theme.

GET /chart

For small public images, URL-encode the complete document into the config query parameter, named that way for historical reasons:

https://szum.io/chart?config={URL_ENCODED_DOCUMENT}

No API key is needed. Keyless output uses the anonymous monthly allowance, includes attribution, and rejects theme overrides. Successful responses are publicly cacheable by their exact URL; cache hits never reach Szum and are not charged.

Do not put private data or credentials in this URL. Query strings can appear in browser history, proxy logs, analytics, and referrer metadata.

Response formats

Set output.format to "svg" or "png". PNG scale accepts 1, 2, 3, or 4 and defaults to 2. The format is part of the document rather than an Accept header, so it is validated and part of the cache key.

SVG responses are UTF-8 XML and PNG responses are binary. Treat both as bytes, never as JSON.

Saved charts

Saved-chart endpoints store a ChartDocument under a stable chart id:

  • POST /api/charts creates and publishes { document, title?, source?, sharedTheme? }.
  • GET /api/charts lists owner-scoped metadata with source, sort, search, limit, and opaque cursor filters.
  • GET /api/charts/{id} reads metadata.
  • PATCH /api/charts/{id} renames the chart.
  • GET /api/charts/{id}/document reads the published document plus any newer draft.
  • PUT /api/charts/{id}/document replaces and publishes { document, sharedTheme? } in place.
  • POST /api/charts/{id}/unpublish takes the public URLs offline; replacing the document publishes it again under the same URLs.
  • GET /api/charts/documents?ids=... reads up to 100 of your documents in one request.
  • DELETE /api/charts/{id} permanently deletes the chart.

Create supports Idempotency-Key. One key identifies one intended create: reuse it across retries and use a fresh key for a different chart. Deduplication is by key, not by comparing bodies. A concurrent request with the same key returns 409 with Retry-After. Replacing a document keeps /c/{id} and /e/{id} stable, and API-key callers cannot overwrite unpublished Studio changes.

See Saved charts for request bodies, response objects, drafts, storage, public URLs, and lifecycle behavior.

GET /api/themes

Lists the workspace’s shared themes. Authenticate with an API key or a dashboard session:

{
  "themes": [
    {
      "name": "Brand colors",
      "theme": "clean",
      "themeOverrides": { "colors": { "categorical": ["#23314c", "#b84233"] } },
      "isDefault": true
    }
  ],
  "defaultBuiltInTheme": null
}

Each entry has the theme’s name, its built-in theme, any themeOverrides, and whether new charts start in it; the default comes first. When new charts start in one of Szum’s built-in themes instead, defaultBuiltInTheme names it. A personal workspace has no themes and no default. The response is private, no-store.

GET /api/chart-rules

Returns the chart rules your workspace enforces, each set to off, warn, or block, the themes Charts use allowed themes accepts, and the chart types Charts use allowed chart types accepts. Authenticate with an API key or a dashboard session:

{
  "rules": {
    "zero_baseline": "warn",
    "title_required": "block",
    "caption_required": "warn",
    "description_required": "off",
    "pie_slice_limit": "warn",
    "color_limit": "off",
    "allowed_themes": "block",
    "allowed_chart_types": "warn"
  },
  "allowedThemes": [
    {
      "id": {
        "kind": "shared",
        "themeId": "5b8e1f0a-6c2d-4e7a-9f3b-2d4c6a8e0b13"
      },
      "name": "Brand colors",
      "theme": "clean",
      "themeOverrides": { "colors": { "categorical": ["#23314c", "#b84233"] } }
    },
    {
      "id": { "kind": "built-in", "theme": "editorial" },
      "name": "Editorial",
      "theme": "editorial"
    }
  ],
  "allowedChartTypes": ["column", "bar", "line"]
}

rules is null when the workspace enforces none, as in a personal workspace. Ignore rules your code doesn’t know: Szum may add more. Each allowed theme has an id (a built-in theme, or a shared theme’s themeId), a name, its built-in theme, and any themeOverrides, like GET /api/themes; a chart passes when its own theme fields match one exactly. allowedChartTypes lists the chart types a chart may use. Each list is empty while its rule is off. The response is private, no-store.

Rate limits

  • Ordinary API traffic is limited to 10 requests per second per IP at the edge.
  • API-key traffic also has a 30 requests-per-second credential bucket.
  • Keyless GET /chart has a 100 image monthly allowance per IP.
  • Authenticated renders consume the account’s monthly plan allowance; validation and saved-chart metadata reads do not.

On 429, honor Retry-After and retry with backoff. CDN hits for public image and embed URLs never reach these limits.

Errors

Handled failures return an error object with code, message, and retryable, plus one diagnostics array for chart input failures. /validate returns its validation result instead. Errors shows an example response and covers status codes, retry rules, and common mistakes.

Compatibility and versioning

New integrations should use 2026-09-26. The API also accepts the documented subset of 2026-03-20 configs for validation, rendering, save, and update. exact and normalized conversions render and save normally, lossy writes need every returned loss code in acceptLosses, and unsupported input is rejected with a stable code. See older config compatibility.

Language examples

See Language examples for TypeScript, Python, Go, Ruby, curl, and HTML.

For agents

Agents should prefer the MCP server, which offers chart-type discovery, examples, validation, previews, and saved charts as tools with machine-readable schemas. Use HTTP when an MCP client is not an option.

Developers

Render current chart requests and manage durable chart documents.

Language examples

Render the same current request from TypeScript or any HTTP client.

On this page

POST /validatePOST /chartGET /chartResponse formatsSaved chartsGET /api/themesGET /api/chart-rulesRate limitsErrorsCompatibility and versioningLanguage examplesFor agents