POST a small JSON description and get back a deck-ready PNG (or SVG). The endpoint is open and CORS-enabled, so it works from browsers, scripts, CI and anywhere else you can make an HTTP call. The same JSON opens in the builder.
| Field | Type | Description |
|---|---|---|
| title | string | Heading shown top-left of the chart at 22px bold. An empty string hides the title row. max 140 chars · default "Project Timeline" |
| subtitle | string | Optional muted line under the title, e.g. a date range or owner. Omit for none. max 200 chars |
| columns | integer | Number of time columns across the chart (2–52, default 8). 2–52 · default 8 |
| unit | string | Column unit label, e.g. "Week", "Sprint", "Month", "Day", "Q". Headers read "<unit> <number>". Default "Week". max 24 chars · default "Week" |
| start | integer | Number of the first column, so 1 gives "Week 1, Week 2…" (default 1). 0–9999 · default 1 |
| width | integer | Chart width in pixels (640–2400, default 1280, which suits a 16:9 slide). PNG output renders at 2x. Height is always computed from the content. 640–2400 · default 1280 |
| labelsInBars | boolean | Draw each task's name inside its bar (and beside milestone diamonds). Default true. default true |
| palette | string[] | Hex colours applied in order to items that have no colour of their own. Pass the user's brand colours here when they name them. Default: indigo, sky, emerald, amber, red, gray. max 12 items · default ["#4f46e5","#0ea5e9","#10b981","#f59e0b","#ef4444","#6b7280"] |
| footnote | string | Optional small muted line at the bottom-left, for a source or "Illustrative". Omit for none. max 240 chars |
| tasksrequired | object[] | Rows in the chart, top to bottom (up to 100). Normally just task bars and milestones, which is all most timelines need. Section bands ({ "type": "section" }) may optionally be inserted to group the tasks below them into labelled phases. max 100 items |
| Field | Type | Description |
|---|---|---|
| type | string | Omit for a normal task bar. "section" draws a full-width labelled divider band (start and duration are ignored). "task", "section" · default "task" |
| namerequired | string | Task or section label. Long names are truncated to fit. max 120 chars |
| start | number | 0-based start column; 0 is the first column. Quarter steps work (e.g. 1.5). Tasks only. 0–52 · default 0 |
| duration | number | Length in columns. 0.25 draws a milestone diamond instead of a bar. Tasks only. 0.25–52 · default 0.25 |
| color | string | Hex colour, e.g. "#4f46e5". Optional: tasks without one take the next palette colour; sections default to light grey (#e2e8f0). Section label text switches between dark and white for contrast. max 40 chars |
POST /api/render/timeline returns image/png; add ?format=svg for SVG.GET /timeline.png?d=<payload> and /timeline.svg?d=<payload> render a chart from a link. The payload is the JSON body, raw-deflated and base64url-encoded. Nothing is stored: links are permanent and cached for a year./timeline#d=<payload> opens the same chart in the builder for editing.GET /api/render/timeline?demo=1 returns the demo chart.GET /api/schema/timeline returns the JSON Schema, for code generators and AIs.Input is lenient where the intent is clear: numeric strings become numbers, out-of-range values are clamped, and unknown fields are ignored. Adjustments are listed in the X-Render-Warnings header. Anything unclear returns a 400 that says how to fix it:
{
"error": "Invalid payload",
"issues": [{ "path": "tasks", "message": "must be an array" }],
"example": { … }
}
Use the hosted MCP server instead. It gives Claude, Cursor and other MCP clients a create_timeline tool that returns the image plus image, SVG and edit links. See the MCP page →