# 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 (see below)
  Response: image (SVG default, PNG if format: "png")

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

## 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".
format      "svg" (default) or "png".
scale       1–4 (default 2). Pixel density.
width       1–4096 (default 640). Total image width.
height      1–4096 (default 400). Total image height.
plotWidth   1–4096. Data area width. Cannot mix with width/height.
plotHeight  1–4096. Data area height. Cannot mix with width/height.
margin      { top, right, bottom, left }. Override auto margins.
title       Chart title string.
subtitle    Subtitle string.
theme       "classic" | "modern" | "dark" | "minimal" | "brand" | "editorial" | "pastel" | "neon" | "print" (default "modern").
themeOverrides  Override individual theme properties (see themes).
data        Datum[]. Top-level dataset shared by all marks.
marks       Mark[]. Required. Visual layers rendered in order.
x           Axis config for x-axis.
y           Axis config for y-axis.
color       Color scale config.

## Marks

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

All marks share:
  type         Required. One of the 9 types above.
  data         Datum[]. Overrides top-level data.
  x            Field name for x position (default "x").
  y            Field name for y position (default "y").
  fill         Field name for color scale, or "#hex" for literal color.
  stroke       Field name for color scale, or "#hex" for literal color.
  strokeWidth  Number (default 1).

Mark-specific properties:
  barY, barX   group: "stack" (default) or "dodge".
  line         strokeWidth default 2.5.
  dot          r: radius (default 4).
  areaY, areaX strokeWidth default 0.
  text         text: field name (default "text"), dx, dy: offset (default 0),
               fontSize, fontWeight, textAnchor: "start" | "center" | "end".
  ruleX, 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". Auto-inferred from data.
domain      [min, max] for numeric, string[] for categorical.
label       Axis label string.
tickFormat  D3 format specifier. Examples: ".0%" for percent, "~s" for SI, "$,.0f" for currency.
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

"classic", "modern", "dark", "minimal", "brand", "editorial", "pastel", "neon", "print"

Default is "modern". Use themeOverrides to customize any property (requires Pro or Business plan):
backgroundColor, colors (array of 10 hex), sequentialRange ([start, end]),
fontFamily ("DM Sans" | "Inter" | "JetBrains Mono" | "Playfair Display" | "Roboto" | "Space Mono"),
fontSize, titleFontWeight, titleFontSize, subtitleFontSize,
titleColor, subtitleColor, titleSubtitleGap, headerGap,
axisLineWidth, axisColor, axisLabelColor, axisLabelFontWeight,
gridLineWidth, gridColor, tickSize, tickPadding, tickLabelColor.

## Examples

Bar chart with categories:
{"version":"2026-03-20","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","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","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","data":[{"x":"A","y":42},{"x":"B","y":58}],"marks":[{"type":"barY"},{"type":"text","text":"y","dy":-12}]}

## 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 100 KB.
429  Rate limit or monthly render limit exceeded.
500  Render failure.

## MCP

Connect AI agents via Model Context Protocol.
Endpoint: POST https://szum.io/mcp
Auth: same API key as Bearer token.
Tools: render_chart, validate_chart, list_themes, list_marks, get_examples.
render_chart returns a URL to the rendered image (expires after 1h).
Resources: szum://schema, szum://llms-txt.
Renders via MCP count against the same monthly limit as the HTTP API.

## Docs

https://szum.io/docs