Update 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": "string",
                "schemaName": "public",
                "tableName": "orders",
                "columnName": "region"
              }
            ]
          }
        ]
      },
      {
        "dashboardId": "db_67890",
        "filters": [
          {
            "name": "Created Date",
            "applyOnTables": [
              {
                "dataType": "date",
                "schemaName": "analytics",
                "tableName": "events",
                "columnName": "created_at"
              }
            ]
          }
        ]
      }
    ]
  }'

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",
        "appendMetrics": [
          { "metricId": "metric_revenue" }
        ],
        "removedMetrics": [
          "metric_old_gallery_copy"
        ]
      }
    ]
  }'

const response = await fetch('https://api.usedatabrain.com/api/v2/workspace/dashboards', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer dbn_live_abc123...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    workspaceName: 'sales-workspace',
    dashboards: [
      {
        dashboardId: 'db_12345',
        filters: [
          {
            name: 'Region',
            applyOnTables: [
              {
                dataType: 'string',
                schemaName: 'public',
                tableName: 'orders',
                columnName: 'region'
              }
            ]
          }
        ]
      }
    ]
  })
});

const result = await response.json();
console.log(result);

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

{
  "error": {
    "code": "INVALID_REQUEST_BODY",
    "message": "\"dashboards\" is required"
  }
}

{
  "error": {
    "code": "INVALID_DASHBOARD_ID",
    "message": "Dashboard with id db_12345 not found"
  }
}

{
  "error": {
    "code": "INVALID_REQUEST_BODY",
    "message": "Filter name(s) not found for dashboard db_12345: Region"
  }
}

{
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Dashboard gallery metric updates require a service token, not a data app API token."
  }
}

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": "string",
                "schemaName": "public",
                "tableName": "orders",
                "columnName": "region"
              }
            ]
          }
        ]
      },
      {
        "dashboardId": "db_67890",
        "filters": [
          {
            "name": "Created Date",
            "applyOnTables": [
              {
                "dataType": "date",
                "schemaName": "analytics",
                "tableName": "events",
                "columnName": "created_at"
              }
            ]
          }
        ]
      }
    ]
  }'

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",
        "appendMetrics": [
          { "metricId": "metric_revenue" }
        ],
        "removedMetrics": [
          "metric_old_gallery_copy"
        ]
      }
    ]
  }'

const response = await fetch('https://api.usedatabrain.com/api/v2/workspace/dashboards', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer dbn_live_abc123...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    workspaceName: 'sales-workspace',
    dashboards: [
      {
        dashboardId: 'db_12345',
        filters: [
          {
            name: 'Region',
            applyOnTables: [
              {
                dataType: 'string',
                schemaName: 'public',
                tableName: 'orders',
                columnName: 'region'
              }
            ]
          }
        ]
      }
    ]
  })
});

const result = await response.json();
console.log(result);

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

{
  "error": {
    "code": "INVALID_REQUEST_BODY",
    "message": "\"dashboards\" is required"
  }
}

{
  "error": {
    "code": "INVALID_DASHBOARD_ID",
    "message": "Dashboard with id db_12345 not found"
  }
}

{
  "error": {
    "code": "INVALID_REQUEST_BODY",
    "message": "Filter name(s) not found for dashboard db_12345: Region"
  }
}

{
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Dashboard gallery metric updates require a service token, not a data app API token."
  }
}

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": "string",
                "schemaName": "public",
                "tableName": "orders",
                "columnName": "region"
              }
            ]
          }
        ]
      },
      {
        "dashboardId": "db_67890",
        "filters": [
          {
            "name": "Created Date",
            "applyOnTables": [
              {
                "dataType": "date",
                "schemaName": "analytics",
                "tableName": "events",
                "columnName": "created_at"
              }
            ]
          }
        ]
      }
    ]
  }'

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",
        "appendMetrics": [
          { "metricId": "metric_revenue" }
        ],
        "removedMetrics": [
          "metric_old_gallery_copy"
        ]
      }
    ]
  }'

const response = await fetch('https://api.usedatabrain.com/api/v2/workspace/dashboards', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer dbn_live_abc123...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    workspaceName: 'sales-workspace',
    dashboards: [
      {
        dashboardId: 'db_12345',
        filters: [
          {
            name: 'Region',
            applyOnTables: [
              {
                dataType: 'string',
                schemaName: 'public',
                tableName: 'orders',
                columnName: 'region'
              }
            ]
          }
        ]
      }
    ]
  })
});

const result = await response.json();
console.log(result);

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

{
  "error": {
    "code": "INVALID_REQUEST_BODY",
    "message": "\"dashboards\" is required"
  }
}

{
  "error": {
    "code": "INVALID_DASHBOARD_ID",
    "message": "Dashboard with id db_12345 not found"
  }
}

{
  "error": {
    "code": "INVALID_REQUEST_BODY",
    "message": "Filter name(s) not found for dashboard db_12345: Region"
  }
}

{
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Dashboard gallery metric updates require a service token, not a data app API token."
  }
}

PUT

api

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": "string",
                "schemaName": "public",
                "tableName": "orders",
                "columnName": "region"
              }
            ]
          }
        ]
      },
      {
        "dashboardId": "db_67890",
        "filters": [
          {
            "name": "Created Date",
            "applyOnTables": [
              {
                "dataType": "date",
                "schemaName": "analytics",
                "tableName": "events",
                "columnName": "created_at"
              }
            ]
          }
        ]
      }
    ]
  }'

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",
        "appendMetrics": [
          { "metricId": "metric_revenue" }
        ],
        "removedMetrics": [
          "metric_old_gallery_copy"
        ]
      }
    ]
  }'

const response = await fetch('https://api.usedatabrain.com/api/v2/workspace/dashboards', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer dbn_live_abc123...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    workspaceName: 'sales-workspace',
    dashboards: [
      {
        dashboardId: 'db_12345',
        filters: [
          {
            name: 'Region',
            applyOnTables: [
              {
                dataType: 'string',
                schemaName: 'public',
                tableName: 'orders',
                columnName: 'region'
              }
            ]
          }
        ]
      }
    ]
  })
});

const result = await response.json();
console.log(result);

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

{
  "error": {
    "code": "INVALID_REQUEST_BODY",
    "message": "\"dashboards\" is required"
  }
}

{
  "error": {
    "code": "INVALID_DASHBOARD_ID",
    "message": "Dashboard with id db_12345 not found"
  }
}

{
  "error": {
    "code": "INVALID_REQUEST_BODY",
    "message": "Filter name(s) not found for dashboard db_12345: Region"
  }
}

{
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Dashboard gallery metric updates require a service token, not a data app API token."
  }
}

Update dashboard filter-to-table mappings and incrementally add or remove metrics from dashboard galleries 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:

Create an embed: Set up embedding with Create Embed or Create Dashboard Embed.
List embeds: Use List Embeds to verify metadata configurations and identify the created embed.
Update: Call Update Workspace Dashboards with the dashboard ID and filter labels from the embed metadata.

Skipping these steps often leads to unknown dashboard IDs or filter names that do not match anything on the dashboard, in which case the request fails validation.

This endpoint updates existing dashboard filters by filter name. For each dashboard, DataBrain matches each input filter name against existing filter labels. Every requested filter name must match an existing filter label or the request fails validation.

Each dashboard entry must include at least one operation: filters, appendMetrics, or removedMetrics. The dashboards array and each dashboard’s dashboardId are required. filters is optional, but each filter must include applyOnTables; appendMetrics and removedMetrics are also optional.

Metric gallery updates require a service token. A data app API token can be used for filter mapping updates, but requests containing appendMetrics or removedMetrics must use a service token.

Authentication

This endpoint requires an authorized API token in the Authorization header. Use a service token for dashboard gallery metric updates; filter mapping updates can also use a data app API token. To access your service token:

In Settings page, navigate to the Service Tokens section.
Click Generate Token to create a service token if you do not have one.

Headers

string

required

Bearer token for API authentication. Use your service token.

Authorization: Bearer dbn_live_abc123...

string

required

Must be set to application/json.

Content-Type: application/json

Request Body

string

required

Name of the workspace containing the dashboards to update.

array

required

List of dashboard update payloads. Dashboard IDs must be unique within this array.

string

required

External dashboard ID to update.

array

Optional list of filters to update for this dashboard.

string

required

Filter name to match against the existing dashboard filter label.

array

required

List of table/column targets where this filter should apply.

string

required

Datatype of the target column. This required string is passed through to the dashboard filter mapping.

string

required

Schema name of the target table.

string

required

Table name without schema.

string

required

Target column name.

array

Optional list of workspace metric IDs to add to this dashboard’s gallery.

string

required

Workspace metric ID to add to the dashboard gallery. Each metricId may appear only once within appendMetrics.

array

Optional list of dashboard gallery metric IDs to remove from this dashboard. Each ID may appear only once.

string

required

Dashboard gallery metric ID to remove. A metric ID cannot be included in both appendMetrics and removedMetrics for the same dashboard.

Internally, DataBrain stores table references as schemaName.tableName while preserving the provided columnName.

When appending a workspace metric, DataBrain creates or reuses the dashboard-gallery copy for the dashboard’s client. When removing a metric, only its association with the requested dashboard gallery is removed.

Response

object

Success payload.

boolean

Returns true when all requested dashboard updates succeed.

null | object

Error object if the request fails, otherwise null.

Examples

Possible Errors

Error Code	HTTP Status	Description
`INVALID_REQUEST_BODY`	400	Missing or invalid fields in request body
`INVALID_SERVICE_TOKEN`	400	Missing or invalid service token context
`WORKSPACE_ID_ERROR`	400	Workspace does not exist for the authenticated organization
`INVALID_DASHBOARD_ID`	400	Dashboard does not exist in the given workspace
`INVALID_METRIC_ID`	400	A metric to append or remove is not available in the requested dashboard gallery context
`AUTHENTICATION_ERROR`	403	Gallery metric updates were attempted with a data app API token instead of a service token
`INTERNAL_SERVER_ERROR`	500	Unexpected server error

HTTP Status Code Summary

Status Code	Description
`200`	OK - Requested dashboard filter and/or gallery metric updates completed successfully
`400`	Bad Request - Validation failure, invalid token context, or invalid dashboard
`403`	Forbidden - Gallery metric updates require a service token
`500`	Internal Server Error - Unexpected server error

Authentication

Datasource APIs

Datamart APIs

Semantic Layer APIs

Workspace APIs

Embeds

Data App APIs

Metric APIs

Self-Hosted APIs

Update Workspace Dashboards

Authentication

Headers

Request Body

Response

Examples

Possible Errors

HTTP Status Code Summary

Next Steps

List Workspaces

Fetch Metrics by Workspace

​Authentication

​Headers

​Request Body

​Response

​Examples

​Possible Errors

​HTTP Status Code Summary

​Next Steps

List Workspaces

Fetch Metrics by Workspace

Authentication

Headers

Request Body

Response

Examples

Possible Errors

HTTP Status Code Summary

Next Steps