Create a dashboard via the API

Building a dashboard from scratch touches five resources, in this dependency order: data source → query → visualization → dashboard → widget → publish.

1. Create (or reuse) a data source

POST /api/data_sources
{ "name": "Production Postgres", "type": "pg", "options": { "host": "db.internal", "port": 5432, "user": "readonly", "password": "...", "dbname": "app" } }

Returns the created data source’s id. See the Data sources reference — POST /api/data_sources/test is worth calling first to confirm the connection works before saving it.

2. Create a query against it

POST /api/queries
{ "data_source_id": 3, "name": "Weekly signups", "query": "select date_trunc('week', created_at) as week, count(*) from signups group by 1 order by 1" }

A newly created query is an unpublished draft. Call POST /api/queries/{id}/publish (with the returned working_version as expected_version) once you’re happy with it — see the Query versions reference.

3. Create a visualization on the query

POST /api/visualizations
{ "query_id": 42, "type": "chart", "name": "Signups over time", "options": { "globalSeriesType": "line" } }

See the Visualizations reference.

4. Create the dashboard

POST /api/dashboards
{ "name": "Weekly Growth" }

Returns a slug — every subsequent dashboard call is addressed by slug, not id. See the Dashboards reference.

5. Add the visualization as a widget

POST /api/widgets
{ "dashboard_id": 9, "visualization_id": 71, "width": 2 }

See the Widgets reference. Repeat steps 2–5 for each additional tile.

6. Publish the dashboard

POST /api/dashboards/{slug}/publish

Until this call, only editors see the dashboard’s draft widgets — everyone else sees nothing (a never-published dashboard has no published snapshot yet). Publishing snapshots the current draft as what every other viewer sees; re-run it any time you add or rearrange widgets and want the changes live.

Optional: share it publicly

POST /api/dashboards/{slug}/share

Returns a secret_token and public_url that anyone with the link can view, no login required. See the Dashboards reference for rotating or revoking that link.