Skip to Content

Workspace APIs

Create a dashboard from tiles

Make a dashboard in a workspace from a JSON list of chart tiles in one call.

POST
/api/v2/workspace/dashboard

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.

Authorization

ServiceToken
headerAuthorizationBearer <token>

A service token. A data app API token is refused.

Query and headers

workspaceNamestringrequired

The workspace, up to 200 characters.

Idempotency-Keystringheader

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.

schemaVersionintegerrequired

1

titlestringrequired

Dashboard name, 1 to 200 characters.

Up to 2,000 characters.

layoutobject

The grid. columns is the grid width, an integer.

1 field in layout
columnsinteger

12 or 24. Default 24

tilesobject[]required

1 to 50 tiles.

5 fields in tiles
idstringrequired

Your id for the tile: lower-case letters, numbers and -, up to 63 characters.

kindstringrequired

databrain-chart

titlestringrequired

Tile title, 1 to 200 characters.

positionobjectrequired

x 0 to 23, y from 0, w 1 to 24, h 1 to 40.

chartobject

What the tile shows. Every tile needs it. type is required.

5 fields in chart
typestringrequired

A chart type, or custom:<key> for a published custom chart.

metricRefstring

An existing metric to show.

querystring

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": "..." } }.

StatusWhy
400The body does not match the schema, workspaceName is missing, or Idempotency-Key is not a UUID v4
403You used a data app API token
404Workspace not found.
409The Idempotency-Key was used with a different body, or the first request is still running
422A tile is not valid. The body has tileVerdicts with each tile's problems. Nothing was made
500Dashboard creation failed.

For errors that every endpoint returns, see Authentication.

Next, read the dashboard back.

Example Request
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>"      }    }  ]}'
Example Response
{  "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": []    }  ]}