> ## 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 for one or more dashboards inside a workspace.

Update dashboard filter-to-table mappings 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) 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.
</Note>

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

<Note>
  Array fields are required by schema (`dashboards`, `filters`, `applyOnTables`) but can be empty. Empty arrays result in a valid no-op update.
</Note>

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

<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 filter update payloads.
</ParamField>

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

<ParamField body="dashboards.filters" type="array" required>
  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' | 'number' | 'date'" required>
  Datatype of the target column. Must be one of: `string`, `number`, or `date`.
</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>

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

<Info>
  If a provided filter name does not match any existing dashboard filter label, that filter is ignored and existing filter configuration remains unchanged.
</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": "text",
                    "schemaName": "public",
                    "tableName": "orders",
                    "columnName": "region"
                  }
                ]
              }
            ]
          },
          {
            "dashboardId": "db_67890",
            "filters": [
              {
                "name": "Created Date",
                "applyOnTables": [
                  {
                    "dataType": "timestamp",
                    "schemaName": "analytics",
                    "tableName": "events",
                    "columnName": "created_at"
                  }
                ]
              }
            ]
          }
        ]
      }'
    ```

    ```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: 'text',
                    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"
      }
    }
    ```
  </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        |
| `INVALID_DASHBOARD_ID`  | 400         | Dashboard does not exist in the given workspace |
| `INTERNAL_SERVER_ERROR` | 500         | Unexpected server error                         |

## HTTP Status Code Summary

| Status Code | Description                                                                       |
| ----------- | --------------------------------------------------------------------------------- |
| `200`       | **OK** - Dashboard filters updated successfully                                   |
| `400`       | **Bad Request** - Validation failure, invalid token context, or invalid dashboard |
| `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>