Skip to Content

Data Retrieval

Promote a dashboard to the next environment

Check, then publish a dashboard from one environment to the next, for example from staging to production.

POST
/api/v2/data-app/dashboard-releases

A release copies a dashboard and its metrics from its workspace to the linked workspace of the next environment. Every call is a dry run unless you send "dryRun": false.

Before you start

  • You have a service token. See Authentication.
  • An admin linked two or more workspaces as environments in Settings > Environments.

Steps

  1. Run a dry run:

    curl --request POST https://api.usedatabrain.com/api/v2/data-app/dashboard-releases \  --header "Authorization: Bearer $DATABRAIN_SERVICE_TOKEN" \  --header "Content-Type: application/json" \  --data '{ "workspaceName": "Staging", "dashboardId": "sales-overview" }'
  2. Read data.checks, data.metrics and data.canPublish. Each metric's action is added, updated, retired or unchanged. Copy data.expectedVersion.

  3. Publish with the version:

    curl --request POST https://api.usedatabrain.com/api/v2/data-app/dashboard-releases \  --header "Authorization: Bearer $DATABRAIN_SERVICE_TOKEN" \  --header "Content-Type: application/json" \  --data '{    "workspaceName": "Staging",    "dashboardId": "sales-overview",    "dryRun": false,    "expectedVersion": "<data.expectedVersion from step 1>",    "message": "Add churn chart",    "tag": "v12"  }'

You get the release id. Next, list releases.

Authorization

ServiceToken
headerAuthorizationBearer <token>

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

Body

workspaceNamestringrequired

The workspace the dashboard is in now.

dashboardIdstringrequired

The dashboard's externalDashboardId

dryRunboolean

Only false publishes. Default: a dry run.

Default: true

Required to publish. The expectedVersion of your dry run. If the dashboard changed since, you get 409 LIVE_CHANGED

Names of shared metrics you agree to change. The dry run lists them.

Default: []
messagestring

A note on the release, up to 200 characters.

Default: ""
tagstring

A label, up to 40 characters.

An https URL that gets a signed POST after the publish. See below.

Response

Dry run:

{  "data": {    "sourceDashboardId": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8",    "target": { "environment": "Production", "externalDashboardId": "sales-overview", "isNew": false },    "summary": { "added": 1, "updated": 2, "retired": 0, "unchanged": 5 },    "metrics": [{ "name": "Churn", "action": "added" }],    "checks": [],    "canPublish": true,    "noChanges": false,    "expectedVersion": "9f2c..."  }}

Publish:

{ "data": { "releaseId": "0a1b2c3d-...", "shortId": "r-8k2m", "dashboardId": "...", "summary": { "added": 1, "updated": 2, "retired": 0, "unchanged": 5 } } }

With callbackUrl, the response also has callback: { "delivered": true, "status": 200 }.

Callback

Databrain sends POST <callbackUrl> with { "id", "type": "release.published", "createdAt", "data": { ... } } and the header Databrain-Signature: t=<unix time>,v1=<signature>. The signature is the hex HMAC-SHA256 of <t>.<body>, keyed with your service token. The URL must be https on a public host. Databrain waits 10 seconds and does not follow redirects. A failed callback does not undo the release.

Errors

Statuserror.codeWhy
400WORKSPACE_NOT_FOUNDNo workspace, or more than one, has this name
400EXPECTED_VERSION_REQUIREDYou published without expectedVersion
400INVALID_CALLBACK_URLcallbackUrl is not a public https URL
403AUTH_ERRORA service token is required.
403FEATURE_NOT_ENABLEDDashboard environments are not on for your company.
404DASHBOARD_NOT_FOUNDNo dashboard in the workspace has this id
409LIVE_CHANGEDThe dashboard changed after your dry run. Run it again
409NO_CHANGESNothing to promote. Both environments match.
409CLIENT_DASHBOARDCustomer dashboards cannot be promoted
422CHECKS_FAILEDFix the failed checks first. The body has checks
500INTERNAL_SERVER_ERRORNothing was changed. Try again.

For errors that every endpoint returns, see Authentication.

Example Request
curl -X POST 'https://api.usedatabrain.com/api/v2/data-app/dashboard-releases' \  -H 'Content-Type: application/json' \  -d '{  "workspaceName": "string",  "dashboardId": "string"}'
Example Response
{  "data": {    "releaseId": "0a1b2c3d-...",    "shortId": "r-8k2m",    "dashboardId": "...",    "externalDashboardId": "sales-overview",    "summary": {      "added": 1,      "updated": 2,      "retired": 0,      "unchanged": 5    },    "callback": {      "delivered": true,      "status": 200    }  }}