The charts API
Create, update, publish, and export charts from code. A chart made through the API is a chart in your account.
A chart is a resource in your account. Create it, load data into it, publish it as a live embed, and export it as a file. A chart created through the API appears in My charts, opens in the editor, and records version history like any other. On a team plan, charts are workspace-scoped: the list includes the team's shared charts, and a teammate's key can update or delete them.
Creating a chart
Send a JSON body to POST /v1/charts. Supply data either as series references to library statistics or as a CSV data body of your own.
| Field | Type | Description |
|---|---|---|
| kind | string | The chart type (see chart kinds). Defaults to line. |
| series | array | References to library data: { "statistic": <id> } using an id from the data API, or { "source": <id>, "select": {…} } for an exact selection. |
| data | string | A CSV of your own data, as an alternative to series (also settable later with PUT /v1/charts/{id}/data). It follows the table shapes in Data shapes for every chart. |
| meta | object | Chart settings (see the meta object). |
A body that is not a JSON object returns 422 invalid_body; an unparseable CSV returns 422 invalid_data.
Chart kinds
The kind field takes one of:
| kind | Family |
|---|---|
| line | Line, area, stacked and 100% area (the default) |
| horizontal-bar | Bar, column, stacked, grouped, 100%, bar race |
| pie | Pie, donut, half-pie |
| scatter | Scatter, bubble, connected |
| themeriver | Streamgraph |
| multiples | Small multiples |
| map | Choropleth (world, US states) |
| dot, range, arrow | Dot plot, range plot, arrow plot |
| candlestick | OHLC candles |
| heatmap | Heatmap, calendar |
| treemap | Treemap |
| sankey | Sankey flows |
| boxplot | Box plot |
| radar | Radar |
| table | Data table |
The meta object
meta carries every editor setting. The common fields:
| Field | Type | Description |
|---|---|---|
| title | string | The chart title. |
| subtitle | string | The description shown under the title. |
| sourceText | string | The source line in the footer. |
| theme | string | A built-in theme id, or one of your theme ids from GET /v1/themes. |
| mode | string | "light" or "dark". |
| w, h | number | The chart width and height, in pixels. |
| seriesTransform | object | Per-series transforms (see transforming a series). |
To find any other setting, style a chart in the editor and read its meta back with GET /v1/charts/{id}.
Transforming a series
A transform reshapes one series without changing its data: rescale it, smooth it, index it, accumulate it, or hide it. Set meta.seriesTransform to an object keyed by series name, each value a config of an optional hidden flag and an ops pipeline.
ops is an ordered pipeline; each entry names a function and its arguments:
| fn | args | Effect |
|---|---|---|
| divide | [n] | Divide every value by n (e.g. [1000000000] to read in billions). |
| multiply | [n] | Multiply every value by n. |
| rollsum | [n] | Rolling sum over the last n periods (a trailing-n total). |
| rollmean | [n] | Rolling average over the last n periods. |
| index100 | none | Rebase to 100 at the first non-null period. |
| cumulative | none | Running total across periods. |
Set "hidden": true to keep a series in the data but off the chart, which is what a total charted beside its own parts needs.
The key is the resolved series name, which is not the statistic id or its title. It comes from the data: US GDP resolves to United States, Apple revenue to AAPL. Read the exact names from a chart's series array with GET /v1/charts/{id} before setting a transform.
Worked example
Create a chart from a statistic, read its resolved series name, then key a rolling sum to it:
A transform is a chart view, so GET /v1/charts/{id}/export/csv returns the original series and the transformed one side by side.
The chart resource
| Field | Description |
|---|---|
| id | The chart id. |
| name | The chart name (its title). |
| kind | The chart type. |
| series | The resolved series names, in order. These are the keys for meta.seriesTransform. |
| meta | The full settings object. |
| hasData | Whether data has been loaded. |
| folderId | The folder the chart is filed in, or null. |
| published | The live embed once published ({ embedUrl }), or null. |
Listing, updating, deleting
| Request | Scope | Effect |
|---|---|---|
| GET /v1/charts | chart:read | List your charts (workspace-scoped, unpaginated). Each item is { id, name, kind, updatedAt, folderId, published }. |
| PATCH /v1/charts/{id} | chart:write | Update kind, series, or meta; pass folderId to file it into a folder. |
| DELETE /v1/charts/{id} | chart:write | Delete the chart. Returns { "deleted": true }. |
Publishing
Publishing creates the hosted live embed, or updates it in place. The URL is stable: republish, and every page embedding it shows the new version. Scope: chart:write.
See the Embedding page for the responsive snippet.
Exporting
Export returns a one-time file of the chart as it stands. Rendering is synchronous. Scope: chart:read.
| Request | Returns |
|---|---|
| GET /v1/charts/{id}/export/png | A raster PNG image. |
| GET /v1/charts/{id}/export/svg | A vector SVG image. |
| GET /v1/charts/{id}/export/pdf | A print-ready PDF. |
| GET /v1/charts/{id}/export/csv | The chart's data, with both the raw and transformed columns. |
At most two exports render at once. A busy renderer returns 503 export_busy with Retry-After: 5; a format other than png, svg, pdf, or csv returns 422 invalid_format.
Folders
Folders organize charts within a workspace, and nest one under another. File a chart into one with folderId on PATCH /v1/charts/{id}. Deleting a folder keeps its charts and moves them up a level.
| Request | Effect |
|---|---|
| GET /v1/folders | List your folders (workspace-scoped). |
| POST /v1/folders | Create a folder (name, optional parentId). |
| GET /v1/folders/{id} | One folder. |
| PATCH /v1/folders/{id} | Rename or move a folder. |
| DELETE /v1/folders/{id} | Delete a folder; its charts move up a level. |
A folder is { id, name, parentId, workspaceId }. A new folder inherits its parent's workspace; a bad parentId returns 422 invalid_parent. Scopes: folder:read to list and read, folder:write to change.
Themes
Themes are authored in the editor (Visualize → Layout → Custom theme) and referenced by id. Set one on a chart with meta.theme, which takes a built-in theme id or one of your theme ids. Scope: theme:read.