Embeds
Rename a filter in an embed
Give a dashboard or metric filter your own label for one customer or for all of them.
Your app calls this with a guest token, for the customer who is viewing. The alias shows instead of the filter name.
curl --request POST https://api.usedatabrain.com/api/v2/dashboard/updateDashboardFilterAlias \ --header "X-Plugin-Token: $GUEST_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "externalDashboard": "sales-overview", "filterKey": "public.orders.region", "alias": "Sales region" }'For a metric filter, call POST /api/v2/dashboard/updateMetricFilterAlias with externalMetricId instead of externalDashboard.
Auth
A guest token in the X-Plugin-Token header, not a Bearer token. The guest token needs params.accessPermissions.isAllowDashboardFilterNameChange (or isAllowMetricFilterNameChange for a metric) set to true. See Create a guest token.
A guest token that sees all tenants sets the alias for every customer. Otherwise it is set for the token's clientId only.
Body
Required dashboard. The dashboard's externalDashboardId
Required metric. The metric id.
The filter's column as table.column, for example public.orders.region. Letter case does not matter.
The new label, up to 100 characters. "" removes the alias.
Only filters that you made in the app can get an alias, not filters a customer added.
Response
{ "data": { "id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e", "filterKey": "public.orders.region", "alias": "Sales region" } }When you remove the alias, id is not in the response.
Errors
This endpoint puts the error in data.error:
{ "data": { "error": { "message": "Invalid dashboard filter" } } }| Status | Message | Why |
|---|---|---|
| 400 | Invalid dashboard filter alias payload | A field is missing or empty |
| 400 | Dashboard filter alias is too long | alias is over 100 characters |
| 400 | Invalid dashboard filter | No filter on the dashboard has this filterKey |
| 403 | UNAUTHORIZED | The guest token may not rename filters, or the dashboard is outside it |
| 404 | Dashboard not found or Metric not found | The id is unknown |
The metric endpoint returns the same messages with metric instead of dashboard.
curl -X POST 'https://api.usedatabrain.com/api/v2/dashboard/updateDashboardFilterAlias' \ -H 'Content-Type: application/json' \ -d '{ "externalDashboard": "sales-overview", "filterKey": "public.orders.region", "alias": "Sales region"}'{ "data": { "filterKey": "public.orders.region", "alias": "" }}