Skip to main content
curl --request PUT \
  --url https://api.usedatabrain.com/api/v2/workspace/dashboards \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "workspaceName": "sales-workspace",
    "dashboards": [
      {
        "dashboardId": "db_12345",
        "filters": [
          {
            "name": "Region",
            "applyOnTables": [
              {
                "dataType": "text",
                "schemaName": "public",
                "tableName": "orders",
                "columnName": "region"
              }
            ]
          }
        ]
      },
      {
        "dashboardId": "db_67890",
        "filters": [
          {
            "name": "Created Date",
            "applyOnTables": [
              {
                "dataType": "timestamp",
                "schemaName": "analytics",
                "tableName": "events",
                "columnName": "created_at"
              }
            ]
          }
        ]
      }
    ]
  }'

{
  "data": {
    "success": true
  },
  "error": null
}
PUT
/
api
/
v2
/
workspace
/
dashboards
curl --request PUT \
  --url https://api.usedatabrain.com/api/v2/workspace/dashboards \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "workspaceName": "sales-workspace",
    "dashboards": [
      {
        "dashboardId": "db_12345",
        "filters": [
          {
            "name": "Region",
            "applyOnTables": [
              {
                "dataType": "text",
                "schemaName": "public",
                "tableName": "orders",
                "columnName": "region"
              }
            ]
          }
        ]
      },
      {
        "dashboardId": "db_67890",
        "filters": [
          {
            "name": "Created Date",
            "applyOnTables": [
              {
                "dataType": "timestamp",
                "schemaName": "analytics",
                "tableName": "events",
                "columnName": "created_at"
              }
            ]
          }
        ]
      }
    ]
  }'

{
  "data": {
    "success": true
  },
  "error": null
}
Update dashboard filter-to-table mappings for dashboards that belong to a workspace.
First-time workspace dashboard integration: If you are wiring this flow for the first time, complete provisioning before calling this endpoint:
  1. Create an embed: Set up embedding with Create Embed or Create Dashboard Embed.
  2. List embeds: Use List Embeds to verify metadata configurations and identify the created embed.
  3. Update: Call Update Workspace Dashboards to apply filter mapping changes using the embed id listed in metadata.
Skipping these steps often leads to unknown dashboard IDs or filter names that do not match anything on the dashboard, in which case updates are ignored or fail validation.
This endpoint updates existing dashboard filters by filter name. For each dashboard, DataBrain matches each input filter name against existing filter labels and updates only matched filters.
Array fields are required by schema (dashboards, filters, applyOnTables) but can be empty. Empty arrays result in a valid no-op update.

​
Authentication

This endpoint requires a service token in the Authorization header. To access your service token:
  1. In Settings page, navigate to the Service Tokens section.
  2. Click Generate Token to create a service token if you do not have one.

​
Headers

​
Authorization
string
required
Bearer token for API authentication. Use your service token.
Authorization: Bearer dbn_live_abc123...
​
Content-Type
string
required
Must be set to application/json.
Content-Type: application/json

​
Request Body

​
workspaceName
string
required
Name of the workspace containing the dashboards to update.
​
dashboards
array
required
List of dashboard filter update payloads.
​
dashboards.dashboardId
string
required
External dashboard ID to update.
​
dashboards.filters
array
required
List of filters to update for this dashboard.
​
dashboards.filters.name
string
required
Filter name to match against the existing dashboard filter label.
​
dashboards.filters.applyOnTables
array
required
List of table/column targets where this filter should apply.
​
dashboards.filters.applyOnTables.dataType
'string' | 'number' | 'date'
required
Datatype of the target column. Must be one of: string, number, or date.
​
dashboards.filters.applyOnTables.schemaName
string
required
Schema name of the target table.
​
dashboards.filters.applyOnTables.tableName
string
required
Table name without schema.
​
dashboards.filters.applyOnTables.columnName
string
required
Target column name.
Internally, DataBrain stores table references as schemaName.tableName while preserving the provided columnName.
If a provided filter name does not match any existing dashboard filter label, that filter is ignored and existing filter configuration remains unchanged.

​
Response

​
data
object
Success payload.
​
data.success
boolean
Returns true when all requested dashboard updates succeed.
​
error
null | object
Error object if the request fails, otherwise null.

​
Examples

​
Possible Errors

Error CodeHTTP StatusDescription
INVALID_REQUEST_BODY400Missing or invalid fields in request body
INVALID_SERVICE_TOKEN400Missing or invalid service token context
INVALID_DASHBOARD_ID400Dashboard does not exist in the given workspace
INTERNAL_SERVER_ERROR500Unexpected server error

​
HTTP Status Code Summary

Status CodeDescription
200OK - Dashboard filters updated successfully
400Bad Request - Validation failure, invalid token context, or invalid dashboard
500Internal Server Error - Unexpected server error

​
Next Steps

List Workspaces

Verify workspace names before update calls

Fetch Metrics by Workspace

Validate downstream metric behavior after dashboard filter updates