Update Embedded Filter Alias

Update the label shown for an existing dashboard or metric filter in an embedded experience. These are end-user plugin APIs: authenticate with a guest token in X-Plugin-Token, not with a Data App API key.

Enable the matching rename permission in params.accessPermissions when you mint the guest token: isAllowDashboardFilterNameChange for dashboard filters or isAllowMetricFilterNameChange for metric filters.

Endpoints

Cloud Databrain

POST https://api.usedatabrain.com/api/v2/dashboard/updateDashboardFilterAlias
POST https://api.usedatabrain.com/api/v2/dashboard/updateMetricFilterAlias

Self-hosted Databrain

POST <SELF_HOSTED_URL>/api/v2/dashboard/updateDashboardFilterAlias
POST <SELF_HOSTED_URL>/api/v2/dashboard/updateMetricFilterAlias

Authentication

string

required

Guest token generated by the Guest Token API. The token determines the dashboard, metric, workspace, and client scope for the request.

string

required

Must be set to application/json.

Update a dashboard filter alias

string

required

Dashboard identifier. The API accepts the dashboard’s internal UUID or its external dashboard ID.

string

required

Case-insensitive dashboard filter key in the form tableName.columnName, for example public.sales_data.region. The filter must already exist and must not be a client-created dashboard filter.

string

required

New label for the filter. Leading and trailing whitespace is removed and the trimmed value can be at most 100 characters. Send an empty string to clear the alias.

cURL

curl --request POST \
  --url https://api.usedatabrain.com/api/v2/dashboard/updateDashboardFilterAlias \
  --header 'X-Plugin-Token: <GUEST_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "externalDashboard": "dashboard-uuid-or-external-id",
    "filterKey": "public.sales_data.region",
    "alias": "Sales region"
  }'

Update a metric filter alias

string

required

Metric identifier. The API accepts the metric’s internal UUID or metric ID.

string

required

Case-insensitive metric filter key in the form tableName.columnName, for example public.sales_data.region. The filter must already exist.

string

required

New label for the filter. Leading and trailing whitespace is removed and the trimmed value can be at most 100 characters. Send an empty string to clear the alias.

cURL

curl --request POST \
  --url https://api.usedatabrain.com/api/v2/dashboard/updateMetricFilterAlias \
  --header 'X-Plugin-Token: <GUEST_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "externalMetricId": "metric-uuid-or-id",
    "filterKey": "public.sales_data.region",
    "alias": "Sales region"
  }'

Response

Both endpoints return the updated alias in the data object:

{
  "data": {
    "id": "alias_abc123",
    "filterKey": "public.sales_data.region",
    "alias": "Sales region"
  }
}

When alias is an empty string, the endpoint removes the stored alias and returns:

{
  "data": {
    "filterKey": "public.sales_data.region",
    "alias": ""
  }
}

Status codes

Status	Description
`200`	Alias updated or cleared successfully.
`400`	Missing or invalid body fields, an unknown filter, or an alias longer than 100 characters.
`403`	The guest token is not authorized for the requested dashboard or metric, or the matching rename permission is disabled.
`404`	The dashboard or metric was not found in the guest token’s authorized scope.
`500`	The alias could not be persisted or an unexpected server error occurred.

Authentication

Datasource APIs

Datamart APIs

Semantic Layer APIs

Workspace APIs

Embeds

Data App APIs

Metric APIs

Self-Hosted APIs

Update Embedded Filter Alias

Endpoints

Cloud Databrain

Self-hosted Databrain

Authentication

Update a dashboard filter alias

Update a metric filter alias

Response

Status codes

​Endpoints

​Cloud Databrain

​Self-hosted Databrain

​Authentication

​Update a dashboard filter alias

​Update a metric filter alias

​Response

​Status codes

Endpoints

Cloud Databrain

Self-hosted Databrain

Authentication

Update a dashboard filter alias

Update a metric filter alias

Response

Status codes