Workspace APIs
Create a dashboard from tiles
Make a dashboard in a workspace from a JSON list of chart tiles in one call.
You describe the dashboard as a tile list. Databrain makes the dashboard and one metric per tile, and checks every tile.
curl --request POST "https://api.usedatabrain.com/api/v2/workspace/dashboard?workspaceName=Customer%20analytics" \ --header "Authorization: Bearer $DATABRAIN_SERVICE_TOKEN" \ --header "Content-Type: application/json" \ --header "Idempotency-Key: 6c1f0b7e-2d3a-4e5f-8a9b-0c1d2e3f4a5b" \ --data '{ "schemaVersion": 1, "title": "Sales overview", "layout": { "columns": 24 }, "tiles": [ { "id": "revenue-by-month", "kind": "databrain-chart", "title": "Revenue by month", "position": { "x": 0, "y": 0, "w": 12, "h": 8 }, "chart": { "type": "line", "metricRef": "<metric id>" } } ] }'Auth
A service token only. See Authentication.
ServiceTokenAuthorizationBearer <token>A service token. A data app API token is refused.
Query and headers
The workspace, up to 200 characters.
A UUID v4. A retry with the same key and body returns the first answer, with the header Idempotency-Replay: true
Body
The body follows the tile-list schema https://schemas.usedatabrain.com/agent/tile-list/v1.json. Unknown fields are refused, except inside chart.
1
Dashboard name, 1 to 200 characters.
Up to 2,000 characters.
The grid. columns is the grid width, an integer.
1 field in layout
12 or 24. Default 24
1 to 50 tiles.
5 fields in tiles
Your id for the tile: lower-case letters, numbers and -, up to 63 characters.
databrain-chart
Tile title, 1 to 200 characters.
x 0 to 23, y from 0, w 1 to 24, h 1 to 40.
What the tile shows. Every tile needs it. type is required.
5 fields in chart
A chart type, or custom:<key> for a published custom chart.
An existing metric to show.
A query for a new metric.
Chart settings.
The datasource id the query runs on. Required with query.
Response
The status is 201.
{ "dashboardId": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8", "workspaceId": "9a7c1e2b-3d4f-4a5b-8c6d-7e8f9a0b1c2d", "slugMap": { "revenue-by-month": "b3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e" }, "tileVerdicts": [{ "id": "revenue-by-month", "ok": true, "problems": [] }]}slugMap gives the metric id made for each tile id.
Errors
Errors on this endpoint have only a message: { "error": { "message": "..." } }.
| Status | Why |
|---|---|
| 400 | The body does not match the schema, workspaceName is missing, or Idempotency-Key is not a UUID v4 |
| 403 | You used a data app API token |
| 404 | Workspace not found. |
| 409 | The Idempotency-Key was used with a different body, or the first request is still running |
| 422 | A tile is not valid. The body has tileVerdicts with each tile's problems. Nothing was made |
| 500 | Dashboard creation failed. |
For errors that every endpoint returns, see Authentication.
Next, read the dashboard back.
curl -X POST 'https://api.usedatabrain.com/api/v2/workspace/dashboard?workspaceName=string' \ -H 'Content-Type: application/json' \ -d '{ "schemaVersion": 1, "title": "Sales overview", "layout": { "columns": 24 }, "tiles": [ { "id": "revenue-by-month", "kind": "databrain-chart", "title": "Revenue by month", "position": { "x": 0, "y": 0, "w": 12, "h": 8 }, "chart": { "type": "line", "metricRef": "<metric id>" } } ]}'{ "dashboardId": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8", "workspaceId": "9a7c1e2b-3d4f-4a5b-8c6d-7e8f9a0b1c2d", "slugMap": { "revenue-by-month": "b3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e" }, "tileVerdicts": [ { "id": "revenue-by-month", "ok": true, "problems": [] } ]}