Developers

Szum gives applications one chart contract for immediate images, durable saved charts, interactive embeds, and the definitions shared with designers and agents.

Render a chart now

Start with a ChartDocument: semantic config, row data, and optional presentation, size, and output policy.

 1{
 2  "version": "2026-09-26",
 3  "config": {
 4    "version": "2026-09-26",
 5    "title": "Quarterly revenue",
 6    "type": "column",
 7    "subtitle": "USD thousands",
 8    "category": {
 9      "field": "quarter"
10    },
11    "values": {
12      "type": "long",
13      "field": "revenue"
14    },
15    "labels": {
16      "content": [
17        "value"
18      ]
19    },
20    "valueAxis": false,
21    "theme": "editorial"
22  },
23  "data": [
24    {
25      "quarter": "Q1",
26      "revenue": 42
27    },
28    {
29      "quarter": "Q2",
30      "revenue": 58
31    },
32    {
33      "quarter": "Q3",
34      "revenue": 65
35    },
36    {
37      "quarter": "Q4",
38      "revenue": 81
39    }
40  ],
41  "presentation": {
42    "background": "opaque",
43    "colorScheme": "system",
44    "systemFallback": "light"
45  }
46}

Send the same request to POST /validate before a changed render when you need structured diagnostics without consuming render allowance. Send it to POST /chart with an API key for image bytes, or to keyless GET /chart?config=... for small public requests.

Choose how the chart ships

Immediate image: POST /chart returns SVG or PNG bytes for one request.

Saved chart: POST /api/charts stores a complete ChartDocument and returns stable image, embed, edit, and management URLs.

Interactive embed: place the saved chart's /e/{id} URL in an iframe. It is responsive and interactive without a separate embed configuration.

Shared definition: read /api/charts/{id}/document to reuse or update the published document. A newer Studio draft is returned separately and is never silently substituted for the publication.

Use the SDK in production

Install the TypeScript SDK:

pnpm add @szum-io/sdk

import { writeFile } from "node:fs/promises";

import { Szum, type ChartDocument } from "@szum-io/sdk";

const request = {
  "config": {
    "type": "column",
    "category": {
      "field": "quarter"
    },
    "values": {
      "type": "long",
      "field": "revenue"
    }
  },
  "data": [
    {
      "quarter": "Q1",
      "revenue": 42
    },
    {
      "quarter": "Q2",
      "revenue": 58
    }
  ],
  "output": {
    "format": "svg"
  }
} satisfies ChartDocument;

const apiKey = process.env.SZUM_API_KEY;

if (!apiKey) {
  throw new Error("SZUM_API_KEY is required");
}

const szum = new Szum({ apiKey });
const image = await szum.render(request);
await writeFile("chart.svg", image);

The SDK adds the current chart version it was generated with when config.version or version is omitted. Raw HTTP callers must send the explicit current version.

Generated SDK types cover config, documents, validation, render metadata, and saved-chart operations. The public /schema.json describes the active data-free ChartConfig; other languages pair that generated config type with the document envelope documented here.

Production behavior

• Authenticate with one API key in the Authorization: Bearer header; never put a key in an image URL, iframe, client bundle, or public repository.
• Reuse one idempotency key when retrying one intended saved-chart create.
• Treat 429 as backpressure and honor Retry-After.
• Read structured validation paths and codes rather than parsing human messages.
• Keep a saved chart id when updating; its public image and embed URLs stay stable.
• Expect CDN hits for saved images and embeds to avoid origin render charges.

Next steps