> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usedatabrain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Workspace Dashboards

> Update filter mappings and dashboard gallery metrics for one or more dashboards inside a workspace.

Update dashboard filter-to-table mappings and incrementally add or remove metrics from dashboard galleries for dashboards that belong to a workspace.

<Note>
  **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](/developer-docs/helpers/api-reference/create-embed) or [Create Dashboard Embed](/developer-docs/helpers/api-reference/create-dashboard-embed).
  2. **List embeds:** Use [List Embeds](/developer-docs/helpers/api-reference/list-embed) to verify metadata configurations and identify the created embed.
  3. **Update:** Call [Update Workspace Dashboards](/developer-docs/helpers/api-reference/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.
</Note>

<Note>
  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.
</Note>

<Note>
  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.
</Note>

<Note>
  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.
</Note>

## 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:

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

<ParamField header="Authorization" type="string" required>
  Bearer token for API authentication. Use your service token.

  ```
  Authorization: Bearer dbn_live_abc123...
  ```
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be set to `application/json`.

  ```
  Content-Type: application/json
  ```
</ParamField>

## Request Body

<ParamField body="workspaceName" type="string" required>
  Name of the workspace containing the dashboards to update.
</ParamField>

<ParamField body="dashboards" type="array" required>
  List of dashboard update payloads. Dashboard IDs must be unique within this array.
</ParamField>

<ParamField body="dashboards.dashboardId" type="string" required>
  External dashboard ID to update.
</ParamField>

<ParamField body="dashboards.filters" type="array">
  Optional list of filters to update for this dashboard.
</ParamField>

<ParamField body="dashboards.filters.name" type="string" required>
  Filter name to match against the existing dashboard filter label.
</ParamField>

<ParamField body="dashboards.filters.applyOnTables" type="array" required>
  List of table/column targets where this filter should apply.
</ParamField>

<ParamField body="dashboards.filters.applyOnTables.dataType" type="string" required>
  Datatype of the target column. This required string is passed through to the dashboard filter mapping.
</ParamField>

<ParamField body="dashboards.filters.applyOnTables.schemaName" type="string" required>
  Schema name of the target table.
</ParamField>

<ParamField body="dashboards.filters.applyOnTables.tableName" type="string" required>
  Table name without schema.
</ParamField>

<ParamField body="dashboards.filters.applyOnTables.columnName" type="string" required>
  Target column name.
</ParamField>

<ParamField body="dashboards.appendMetrics" type="array">
  Optional list of workspace metric IDs to add to this dashboard's gallery.
</ParamField>

<ParamField body="dashboards.appendMetrics[].metricId" type="string" required>
  Workspace metric ID to add to the dashboard gallery. Each `metricId` may appear only once within `appendMetrics`.
</ParamField>

<ParamField body="dashboards.removedMetrics" type="array">
  Optional list of dashboard gallery metric IDs to remove from this dashboard. Each ID may appear only once.
</ParamField>

<ParamField body="dashboards.removedMetrics[]" type="string" required>
  Dashboard gallery metric ID to remove. A metric ID cannot be included in both `appendMetrics` and `removedMetrics` for the same dashboard.
</ParamField>

<Info>
  Internally, DataBrain stores table references as `schemaName.tableName` while preserving the provided `columnName`.
</Info>

<Info>
  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.
</Info>

## Response

<ResponseField name="data" type="object">
  Success payload.

  <ResponseField name="data.success" type="boolean">
    Returns `true` when all requested dashboard updates succeed.
  </ResponseField>
</ResponseField>

<ResponseField name="error" type="null | object">
  Error object if the request fails, otherwise `null`.
</ResponseField>

## Examples

<Panel>
  <RequestExample>
    ```bash cURL theme={"dark"}
    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"
                  }
                ]
              }
            ]
          }
        ]
      }'
    ```

    ```bash cURL - Update dashboard gallery metrics theme={"dark"}
    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"
            ]
          }
        ]
      }'
    ```

    ```javascript Node.js icon="fa-brands fa-node-js" theme={"dark"}
    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);
    ```
  </RequestExample>

  <ResponseExample>
    ```json 200 - Success theme={"dark"}
    {
      "data": {
        "success": true
      },
      "error": null
    }
    ```

    ```json 400 - Validation Error theme={"dark"}
    {
      "error": {
        "code": "INVALID_REQUEST_BODY",
        "message": "\"dashboards\" is required"
      }
    }
    ```

    ```json 400 - Invalid Dashboard theme={"dark"}
    {
      "error": {
        "code": "INVALID_DASHBOARD_ID",
        "message": "Dashboard with id db_12345 not found"
      }
    }
    ```

    ```json 400 - Unknown Filter theme={"dark"}
    {
      "error": {
        "code": "INVALID_REQUEST_BODY",
        "message": "Filter name(s) not found for dashboard db_12345: Region"
      }
    }
    ```

    ```json 403 - Gallery Metrics Require Service Token theme={"dark"}
    {
      "error": {
        "code": "AUTHENTICATION_ERROR",
        "message": "Dashboard gallery metric updates require a service token, not a data app API token."
      }
    }
    ```
  </ResponseExample>
</Panel>

## 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                                      |

## Next Steps

<CardGroup cols={2}>
  <Card title="List Workspaces" icon="list" href="/developer-docs/helpers/api-reference/list-workspaces">
    Verify workspace names before update calls
  </Card>

  <Card title="Fetch Metrics by Workspace" icon="chart-line" href="/developer-docs/helpers/api-reference/fetch-metrics-by-workspace">
    Validate downstream metric behavior after dashboard filter updates
  </Card>
</CardGroup>