# szum

> Chart rendering API. Send JSON, get SVG or PNG. One grammar, curated themes, editorial-quality output.

## Endpoint

POST https://szum.io/chart
  Authorization: Bearer YOUR_API_KEY
  Content-Type: application/json
  Body: chart config JSON (must include "format": "svg" or "png" – required)
  Response: image bytes (svg or png, matching the requested format)
  CORS: open (Access-Control-Allow-Origin: *)

GET https://szum.io/chart?config=<url-encoded-json>
  Keyless, free-tier only. Works in <img> tags.

## Saved charts

A saved chart is one object, returned identically by create, list, and read:
  { id, source ("api"|"app"|"figma"|"mcp" - open set, match on known values), title, createdAt (ISO-8601 string), updatedAt (ISO-8601 string), sizeBytes, imageUrl (https://szum.io/c/<id> image), embedUrl (https://szum.io/e/<id> interactive), configUrl (https://szum.io/api/charts/<id>/config) }
The config, image, and embed are sub-resources you fetch off it; the object itself is metadata + links.

POST https://szum.io/api/charts
  Authorization: Bearer YOUR_API_KEY (Free or Pro)
  Body: { "config": <chart config JSON> }
  Response: 201, the chart object. /c/<id> renders an image (embed in <img>); /e/<id> is an interactive HTML embed (<iframe>).

GET https://szum.io/api/charts?source=figma|api|app|mcp&limit=<1-1000>&cursor=<cursor>
  Authorization: Bearer YOUR_API_KEY
  Lists your charts, newest first – ordered by immutable createdAt, so paging is stable across edits. All params optional: source (omit = all charts; or one/comma-separated of figma|api|app|mcp), limit (default 100, max 1000), cursor (opaque; omit = first page, then pass the previous response's nextCursor back unchanged – don't parse or construct it). Response: { "items": [<chart object>], "nextCursor": <string|null> }. Read-only, no render charge. The only way to enumerate API-saved charts.

GET https://szum.io/api/charts/<id>
  Authorization: Bearer YOUR_API_KEY. Reads one chart object (owner-only; 404 otherwise).

GET https://szum.io/api/charts/<id>/config
  Authorization: Bearer YOUR_API_KEY. Returns { "config": <chart config JSON> } (owner-only).

GET https://szum.io/api/charts/configs?ids=<id1,id2,...>
  Authorization: Bearer YOUR_API_KEY. Batch config read (max 100 ids; owner-only). Returns { "configs": [{ "id", "config" }], "missing": [{ "id", "reason" }] } where reason is an open set (match on known values, treat unfamiliar ones as a non-fatal skip): today not_found (unowned or absent) or unavailable (transient storage error).

PUT https://szum.io/api/charts/<id>/config
  Authorization: Bearer YOUR_API_KEY. Body: { "config": <chart config JSON> }. Replaces the config in place (same id + URLs; edge caches purged). Response: the chart object.

DELETE https://szum.io/api/charts/<id>
  Authorization: Bearer YOUR_API_KEY (Free or Pro)
  Revokes a single saved chart.

GET https://szum.io/c/<id>
  Public chart-image endpoint. Each cache-miss fetch counts as one render against the creator's monthly quota. CDN cache hits are served from the edge for free.
  Returns 403 if the creator's plan was Pro and is now in the 30-day Pro→Free pause grace period.

GET https://szum.io/e/<id>
  Public interactive embed endpoint. Returns HTML for any <iframe>; hover tooltips, legend toggle, container-sized. Same render-on-cache-miss billing and pause behavior as /c/.

Per-config size cap: 50 KB.
Free accounts get a small storage allowance; Pro accounts effectively unlimited for normal use. Pro→Free downgrade pauses URLs for 30 days, then deletion.

## TypeScript SDK

npm install @szum-io/sdk

import { Szum } from "@szum-io/sdk";
const szum = new Szum({ apiKey: "YOUR_API_KEY" });
const svg = await szum.render({ format: "svg", marks: [...] });
const chart = await szum.charts.create({ format: "png", marks: [...] });
// chart.imageUrl → https://szum.io/c/<id>  (image)
// chart.embedUrl → https://szum.io/e/<id>  (interactive iframe)
// Also: charts.list({ source }), charts.get(id), charts.getConfig(id), charts.update(id, config), charts.delete(id)

The SDK automatically injects the schema version it was built against. No need to pass "version" in configs.
Provides typed configs with autocomplete, error handling (SzumError with status and retryAfter), and timeouts.
For Node/TypeScript projects, prefer the SDK over raw HTTP.

## JSON Schema

https://szum.io/schema.json

## Minimal config

{
  "version": "2026-03-20",
  "marks": [{
    "type": "barY",
    "data": [
      { "x": "Q1", "y": 42 },
      { "x": "Q2", "y": 58 }
    ]
  }]
}

Only "version" and "marks" are required. Everything else has defaults.

## Top-level fields

version        Required. "2026-03-20". Schema version.
format         Required. "svg" | "png". Output image format.
scale          1–4 (default 1 (svg) / 2 (png)). Pixel density.
width          1–4096 (default 640). Total image width. Cannot mix with plotWidth/plotHeight.
height         1–4096 (default 400). Total image height. Cannot mix with plotWidth/plotHeight.
plotWidth      1–4096. Data area width. Cannot mix with width/height.
plotHeight     1–4096. Data area height. Cannot mix with width/height.
margin         object (default auto). Override auto margins: top, right, bottom, left.
title          string. Chart title string.
subtitle       string. Subtitle string.
attribution    boolean. Show a "made with szum" credit. Forced on for free/keyless renders; Pro omits it by default, set true to opt in.
theme          ThemeName (default "modern"). One of the built-in themes.
themeOverrides object. Override individual theme properties.
data           Datum[]. Top-level dataset shared by all marks.
marks          Required. Mark[]. Visual layers rendered in order.
x              AxisConfig (default auto). X-axis configuration.
y              AxisConfig (default auto). Y-axis configuration.
color          ColorConfig (default auto). Color scale configuration.

## Marks

10 mark types: barY, barX, line, dot, areaY, areaX, text, pie, ruleX, ruleY.

All marks share:
  type         Required. One of the 10 types above.
  data         Datum[]. Mark-specific data. Overrides top-level data.
  x            string (default "x"). Field name for x position.
  y            string (default "y"). Field name for y position.
  fill         string. Fill color: field name for color scale, or #hex literal.
  stroke       string. Stroke color: field name for color scale, or #hex literal.
  strokeWidth  number (default 1). Stroke width in pixels.

Mark-specific properties:
  barY         group: "stack" | "dodge" (default "stack").
  barX         group: "stack" | "dodge" (default "stack").
  line         strokeWidth: number (default 2.5).
  dot          r: number (default 4).
  areaY        strokeWidth: number (default 0).
  areaX        strokeWidth: number (default 0).
  text         text: string (default "text"), dx: number (default 0), dy: number (default 0), fontSize: number, fontWeight: string, textAnchor: "start" | "center" | "end" (default "center").
  pie          innerRadius: number (default 0).
  ruleX        No extra properties.
  ruleY        No extra properties.

## Data

Flat array of objects. Keys are field names, values are strings or numbers.

[{ "month": "Jan", "revenue": 42 }, { "month": "Feb", "revenue": 58 }]

Top-level "data" is shared by all marks. Mark-level "data" overrides it.
Field references: mark properties x, y, fill, stroke, text look up field names in data.
If fill/stroke starts with "#", it is a literal color (no scale, no legend).

## Axis config (x, y)

type         "linear" | "band" | "utc" (default auto). Override the inferred scale type.
domain       [min, max] or string[] (default auto). Force a specific range.
label        string. Axis label text.
tickFormat   string. D3 format specifier for tick labels.
display      boolean (default true). Set false to hide the axis.

Scale auto-inference: numbers → linear, ISO dates → utc, other strings → band.

## Color config

type     "categorical" | "sequential". Auto-inferred.
label    Legend label string.
domain   string[] (categorical) or [min, max] (sequential).
range    string[] (categorical) or [string, string] (sequential gradient endpoints).

## Themes

"modern", "editorial", "dark", "neon", "pastel", "technical"

Default is "modern". Use themeOverrides to customize any property (requires Pro plan):
backgroundColor, colors, sequentialRange, fontFamily, fontSize, titleFontWeight, titleFontSize, subtitleFontSize, titleColor, subtitleColor, titleSubtitleGap, headerGap, axisLineWidth, axisColor, axisLabelColor, axisLabelFontWeight, gridLineWidth, gridColor, tickSize, tickPadding, tickLabelColor, tickLabelFontWeight.

## Examples

Bar chart with categories:
{"version":"2026-03-20","format":"svg","theme":"editorial","title":"Revenue","marks":[{"type":"barY","data":[{"x":"Q1","y":4.2,"region":"US"},{"x":"Q1","y":2.1,"region":"EU"},{"x":"Q2","y":5.1,"region":"US"},{"x":"Q2","y":2.8,"region":"EU"}],"fill":"region"}]}

Line chart with dates:
{"version":"2026-03-20","format":"svg","marks":[{"type":"line","data":[{"x":"2025-01-01","y":10},{"x":"2025-04-01","y":25},{"x":"2025-07-01","y":18},{"x":"2025-10-01","y":32}]}]}

Scatter with reference lines:
{"version":"2026-03-20","format":"svg","marks":[{"type":"dot","data":[{"x":2,"y":8},{"x":5,"y":3},{"x":8,"y":7}],"r":5},{"type":"ruleY","data":[{"y":5}],"stroke":"#999"},{"type":"ruleX","data":[{"x":5}],"stroke":"#999"}]}

Bar + text labels:
{"version":"2026-03-20","format":"svg","data":[{"x":"A","y":42},{"x":"B","y":58}],"marks":[{"type":"barY"},{"type":"text","text":"y","dy":-12}]}

Pie chart:
{"version":"2026-03-20","format":"svg","marks":[{"type":"pie","data":[{"x":"Chrome","y":65},{"x":"Safari","y":18},{"x":"Firefox","y":8},{"x":"Edge","y":5}]}]}

Donut chart:
{"version":"2026-03-20","format":"svg","marks":[{"type":"pie","innerRadius":0.5,"data":[{"x":"Americas","y":42},{"x":"EMEA","y":28},{"x":"APAC","y":18}]}]}

## Errors

400  Invalid JSON, missing version, or validation error. Response: { "error": "..." }.
401  Missing or invalid API key.
403  Feature not available on current plan (e.g. themeOverrides on free tier).
413  Config exceeds 50 KB.
429  Burst rate limit or monthly render limit exceeded. Retry-After header included (seconds).
500  Render failure.

## Limits

Per plan, per month:
  Unauthenticated (GET)        250 renders per IP (no API key)
  Free (with API key)          5,000 renders
  Pro                          100,000 renders (overage $1 per 5,000, opt-in)

Renders count function executions (POST /chart, GET /c/<id> cache miss, GET /e/<id> cache miss, /r/<id>).
Audience-facing loads of /c/<id> and /e/<id> are served from the CDN and are free.

Limits reset on the 1st of each month (UTC).

POST responses include usage headers:
  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).

## MCP

Connect agents via Model Context Protocol.
Endpoint: POST https://szum.io/mcp
Auth: optional Bearer API key. Without one, shared 250/mo per-IP keyless tier (no theme overrides). With a key, renders count against the key's monthly plan limit – same as the HTTP API.
Tools:
  render_chart   Counts as 1 render. Returns a URL to the rendered image (expires after 10 min).
  validate_chart Free.
  list_themes    Free.
  list_marks     Free.
  get_examples   Free.
Resources: szum://schema, szum://llms-txt.

## Docs

https://szum.io/docs