Skip to Content

Embeds

Update embed access settings

Change what your customers can do in an embedded dashboard.

PUT
/api/v2/data-app/embeds

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.

Authorization

DataAppApiToken
headerAuthorizationBearer <token>

A data app API token. A service token is refused.

Body

embedIdstringrequired

A dashboard embed of the data app.

accessSettingsobjectrequired

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.

joinModelstring

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
clientColumnstringrequired
namestringrequired

Columns they can filter dashboards on: { "tableName": "public.orders", "columns": ["region"] }

2 fields in dashboardFilterColumns
tableNamestringrequired
columnsstring[]required

Columns they can filter metrics on, same shape.

2 fields in metricFilterColumns
tableNamestringrequired
columnsstring[]required

Send booleans as JSON true or false: the string "false" is saved as true.

These fields work differently on update:

  • datamartName does not move the embed to another datamart. It reloads the table list from that datamart.
  • tableTenancySettings works only with datamartName in the same call. Tables you leave out of it lose their tenant column, so list every table.
  • joinModel replaces isIncrementalJoin.

Response

{ "id": "sales-overview" }

Errors

Statuserror.codeWhy
400INVALID_REQUEST_BODYA field is unknown or wrong, or nothing would change: Access settings cannot be empty
400INVALID_DATA_APP_API_KEYYou used a service token
400INVALID_EMBED_IDNo dashboard embed of this data app has this id
400INVALID_DATAMART or DATAMART_TABLE_NOT_FOUNDThe datamartName is wrong
403entitlement_requiredYour plan does not include embedding
500INTERNAL_SERVER_ERRORThe update failed

For errors that every endpoint returns, see Authentication.

Example Request
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  }}'
Example Response
{  "id": "sales-overview"}