Skip to Content

Workspace APIs

Update workspace dashboards

Change where dashboard filters apply, and add or remove metrics on customer dashboards.

PUT
/api/v2/workspace/dashboards

Use it on many dashboards in one call. Each dashboard entry changes its filters, its metrics, or both.

curl --request PUT https://api.usedatabrain.com/api/v2/workspace/dashboards \  --header "Authorization: Bearer $DATABRAIN_SERVICE_TOKEN" \  --header "Content-Type: application/json" \  --data '{    "workspaceName": "Customer analytics",    "dashboards": [      {        "dashboardId": "sales-overview",        "filters": [          {            "name": "Region",            "applyOnTables": [              { "schemaName": "public", "tableName": "orders", "columnName": "region", "dataType": "string" }            ]          }        ],        "appendMetrics": [{ "metricId": "b3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e" }]      }    ]  }'

Auth

A service token. A data app API token can change filters only. See Authentication.

Authorization

ApiToken
headerAuthorizationBearer <token>

A service token or a data app API token.

Body

workspaceNamestringrequired

The workspace.

dashboardsany[]required

One entry per dashboard. Each dashboardId once.

4 fields in dashboards
dashboardIdstringrequired

The dashboard's externalDashboardId, from Fetch dashboards by workspace

filtersobject[]

Filters to point at other columns. name is the filter's label on the dashboard. applyOnTables replaces where it applies: schemaName, tableName, columnName and dataType, all required.

2 fields in filters
namestringrequired

The label of a filter that is already on the dashboard.

applyOnTablesobject[]required

The tables and columns the filter applies to.

4 fields in applyOnTables
dataTypestringrequired
tableNamestringrequired
columnNamestringrequired
schemaNamestringrequired

Workspace metrics to add, as { "metricId": "..." }

1 field in appendMetrics
metricIdstringrequired

The id of the metric to add.

Metric ids to remove that were added with appendMetrics

appendMetrics and removedMetrics work only on a dashboard that a customer made in the embed. Databrain adds a copy of each metric to that dashboard. The source metric must be live and in the workspace.

Response

{ "data": { "success": true }, "error": null }

Errors

Statuserror.codeWhy
400INVALID_REQUEST_BODYA field is missing or wrong. A metric is both added and removed. A filter name is not on the dashboard
400WORKSPACE_ID_ERRORNo workspace has this name
400INVALID_DASHBOARD_IDNo dashboard in the workspace has this id
400CLIENT_ID_ERRORYou added or removed metrics on a dashboard that a customer did not make
400INVALID_METRIC_IDA metric id is unknown, or was not added to this dashboard
403AUTHENTICATION_ERRORA data app API token tried to add or remove metrics
500INTERNAL_SERVER_ERRORThe update failed

Dashboards are saved one after the other. If one fails, the ones before it stay changed.

For errors that every endpoint returns, see Authentication.

Example Request
curl -X PUT 'https://api.usedatabrain.com/api/v2/workspace/dashboards' \  -H 'Content-Type: application/json' \  -d '{  "workspaceName": "Customer analytics",  "dashboards": [    {      "dashboardId": "sales-overview",      "filters": [        {          "name": "Region",          "applyOnTables": [            {              "schemaName": "public",              "tableName": "orders",              "columnName": "region",              "dataType": "string"            }          ]        }      ],      "appendMetrics": [        {          "metricId": "b3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e"        }      ]    }  ]}'
Example Response
{  "data": {    "success": true  },  "error": null}