Embeds
Update embed access settings
Change what your customers can do in an embedded dashboard.
Only the fields you send change. Metric embeds have no access settings to change.
curl --request PUT https://api.usedatabrain.com/api/v2/data-app/embeds \ --header "Authorization: Bearer $DATABRAIN_API_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "embedId": "sales-overview", "accessSettings": { "isAllowUnderlyingData": false, "isAllowAiPilot": true } }'Before you start
- You have a data app API token for the data app. See Authentication.
- Your plan includes embedding.
DataAppApiTokenAuthorizationBearer <token>A data app API token. A service token is refused.
Body
A dashboard embed of the data app.
Any fields of accessSettings. None is required.
19 fields in accessSettings
The datamart the embed queries. Its tenancy must match the workspace.
Create metrics with DRAG_DROP or CHAT
Schedule email reports.
Manage metrics.
Save dashboard views.
Create metrics.
Delete metrics.
Move and resize metrics.
Edit metrics.
See the underlying data.
Use AI features.
Add dashboard filters.
Add metric filters.
Import a dashboard that uses another tenant's metrics, rebound to their own tenant.
multi lets metrics join tables. single does not.
Same as joinModel: multi (older field)
The tenant column per table: { "name": "orders", "clientColumn": "customer_id" }. name has no schema.
2 fields in tableTenancySettings
Columns they can filter dashboards on: { "tableName": "public.orders", "columns": ["region"] }
Columns they can filter metrics on, same shape.
Send booleans as JSON true or false: the string "false" is saved as true.
These fields work differently on update:
datamartNamedoes not move the embed to another datamart. It reloads the table list from that datamart.tableTenancySettingsworks only withdatamartNamein the same call. Tables you leave out of it lose their tenant column, so list every table.joinModelreplacesisIncrementalJoin.
Response
{ "id": "sales-overview" }Errors
| Status | error.code | Why |
|---|---|---|
| 400 | INVALID_REQUEST_BODY | A field is unknown or wrong, or nothing would change: Access settings cannot be empty |
| 400 | INVALID_DATA_APP_API_KEY | You used a service token |
| 400 | INVALID_EMBED_ID | No dashboard embed of this data app has this id |
| 400 | INVALID_DATAMART or DATAMART_TABLE_NOT_FOUND | The datamartName is wrong |
| 403 | entitlement_required | Your plan does not include embedding |
| 500 | INTERNAL_SERVER_ERROR | The update failed |
For errors that every endpoint returns, see Authentication.
curl -X PUT 'https://api.usedatabrain.com/api/v2/data-app/embeds' \ -H 'Content-Type: application/json' \ -d '{ "embedId": "sales-overview", "accessSettings": { "isAllowUnderlyingData": false, "isAllowAiPilot": true }}'{ "id": "sales-overview"}