REST API

API: Sharing

Public share links and their settings. All endpoints require authentication unless noted. 19 endpoints.

`GET /api/embed-frame-policy`

Frame-ancestors for an embed page (asked by the edge proxy)

Responses: 204 — The list is in the X-Frame-Ancestors header

`GET /api/shares`

List shares

Query parameters

Name	Type	Required
`contentType`	string	no
`contentId`	string	no
`limit`	integer	no
`offset`	integer	no

Responses: 200 · 400 · 401

`POST /api/shares`

Create a share link

Request body (JSON)

Field	Type	Required
`contentType`	`"dashboard"` \| `"report"`	yes
`contentId`	string	yes
`shareType`	`"public"` \| `"password"` \| `"rls"`	yes
`password`	string	no
`rlsContext`	object	no
`expiresAt`	string	no

Responses: 201 · 400 · 401 · 409

`DELETE /api/shares/{id}`

Delete a share

Path parameters

Name	Type	Required	Description
`id`	string	yes

Responses: 204 — No content · 401 · 404

`PUT /api/shares/{id}/ai`

Enable/disable Ask-AI on a share and set its hourly cap (AIX-20)

Ask AI on a share link or embed is off until its publisher turns it on. When on, anyone with the link can ask about that view’s data only, and the publishing workspace’s AI credits pay for every question.

Path parameters

Name	Type	Required	Description
`id`	string	yes

Request body (JSON)

Field	Type	Required	Description
`allowAi`	boolean	yes	true turns Ask AI on for the people who open this share: the publishing workspace’s AI credits pay for every question they ask. false turns it off. API keys can turn it off, not on.
`aiRatePerHour`	integer	no

Responses: 200 · 400 · 401 · 404

`GET /api/shares/{token}`

Access a shared resource by token (public)

An embed session’s token (dsess_…) is answered only from the site its session is bound to (X-DS-Embed-Origin), counts no view and does not name the app’s maker.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses: 200 · 400 · 401 · 404

`POST /api/shares/{token}/card-data`

Run a shared dashboard card’s query by token (public)

Path parameters

Name	Type	Required	Description
`token`	string	yes

Request body (JSON)

Field	Type	Required
`cardId`	string	yes
`password`	string	no
`limit`	integer	no
`distinctColumn`	string	no
`filters`	array of object	no

Responses: 200

`POST /api/shares/{token}/cards/{cardId}/metric-value`

Read a shared dashboard’s metric card: its headline, for the share’s reader (public)

Answers as POST /api/metrics/{id}/value answers with include headline and latestPeriod: the metric’s headline (its latest whole period that has settled, in the workspace’s time zone; all of its data for a metric without a time dimension), read for the share’s reader under the viewer’s filters on the metric’s model. A link’s guest reads no model under row security, a row-security link only its own rows, labelled fields masked; an embedded person as an embedded card is read. A token that does not open a dashboard, a card not on its visible pages and a card that shows no metric answer 404, 404 and 400.

Path parameters

Name	Type	Required	Description
`token`	string	yes
`cardId`	string	yes

Request body (JSON)

Field	Type	Required	Description
`password`	string	no
`filters`	array of object	no	The page’s filters on fields of the metric’s model (D2): they narrow the metric’s own filters, never replace them.

Responses: 200 · 400 · 401 · 403 · 404 · 429

`POST /api/shares/{token}/chart-data`

Run a shared dashboard model-backed card’s query by token (public)

Path parameters

Name	Type	Required	Description
`token`	string	yes

Request body (JSON)

Field	Type	Required
`cardId`	string	yes
`password`	string	no
`distinctFieldId`	string	no
`pivotTotals`	`"rows"` \| `"columns"` \| `"grand"`	no
`filters`	array of object	no

Responses: 200

`POST /api/shares/{token}/chat`

Ask-AI on a shared/embedded view, scoped to the token’s own data (AIX-20, public)

Path parameters

Name	Type	Required	Description
`token`	string	yes

Request body (JSON)

Field	Type	Required	Description
`message`	string	yes
`password`	string	no
`conversationId`	string	no	The id the first answer carried. Omit it to start a conversation.

Responses: 200 · 403 · 404 · 429 · 503

`GET /api/shares/{token}/content`

Get shared content (dashboard cards or report layout) by token (public)

Path parameters

Name	Type	Required	Description
`token`	string	yes

Query parameters

Name	Type	Required	Description
`password`	string	no

Responses: 200

`POST /api/shares/{token}/content`

Get shared content by token (public; password in body)

Path parameters

Name	Type	Required	Description
`token`	string	yes

Request body (JSON)

Field	Type	Required	Description
`password`	string	no

Responses: 200

`GET /api/shares/{token}/conversations`

An embedded person’s Ask AI conversations on this view, newest first (embed sessions only, public)

Path parameters

Name	Type	Required	Description
`token`	string	yes

Query parameters

Name	Type	Required	Description
`limit`	`20` \| `50` \| `100`	no
`offset`	integer	no

Responses: 200 · 401 · 403 · 404

`GET /api/shares/{token}/conversations/{conversationId}`

One of an embedded person’s Ask AI conversations: its questions and answers (embed sessions only, public)

Path parameters

Name	Type	Required	Description
`token`	string	yes
`conversationId`	string	yes

Responses: 200 · 401 · 403 · 404

`POST /api/shares/{token}/deck-assets/{assetId}`

Read a picture of a presentation’s published version through its link or embed (public)

Path parameters

Name	Type	Required	Description
`token`	string	yes
`assetId`	string	yes

Request body (JSON)

Field	Type	Required	Description
`password`	string	no

Responses: 200 — The picture’s bytes (image/png, image/jpeg or image/webp) · 401 · 404 · 429

`POST /api/shares/{token}/deck-data`

Read one slide’s figures through a presentation’s link or embed (public)

Answers contracts DeckDataResponse for the slide’s elements, each figure read with the viewer’s access: through a link as a guest (figures from data with row security are not shown, a row-security link’s rows only, never its maker’s session); through an embed as the embedded person. A dead link answers 404, as a token that never was.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Request body (JSON)

Field	Type	Required	Description
`slideId`	string	yes
`version`	integer	yes	The published version the viewer holds (409 when it was published again: reload it)
`mode`	`"live"` \| `"frozen"`	no	frozen: a frozen deck’s frozen values, served only to a viewer whose access is the freezer’s (else live, with liveInstead)
`password`	string	no

Responses: 200 · 400 · 401 · 403 · 404 · 409 · 429

`POST /api/shares/{token}/entity-color-slots`

Resolve the colour slots of the members a shared or embedded dashboard’s cards draw (public)

Answers the slot of exactly the keys sent, in the caller’s own access scope, never a map. Signed-in members who read a field’s rows unrestricted and in clear share the scope ‘all’ (whose rows a card reads is the catalogue’s: its model’s source); a member whom row-level security restricts or a label masks keeps their own, as does every link (shared by its guests) and each embedded customer (its tenant), measures included, so none learns another’s members. A key the scope does not keep yet takes the lowest slot free in its field, in the order sent, appended only (unless assign is false, a lookup); only a signed-in member adds to ‘all’ (an API key only looks it up), and a link, an embed or an API key adds at most 32 new members a request. A field keeps 64 members a scope; past them a key is answered no slot. A masked member (‘***’) is never kept, and a key no dashboard keeps (no field, over 512 characters, U+0000 or half a surrogate pair) is answered 400. Resolving never claims the dashboard for editing or moves its edit token or its updated time; a request that adds members to colours a scope shares (members’ ‘all’, a link’s, a tenant’s) writes one audit row, dashboard.colors_kept, naming who and how many. A link or embed that does not open a dashboard answers 404, as a token that never was.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Request body (JSON)

Field	Type	Required	Description
`keys`	array of string	yes	Colour keys (`\<field id>=\<member>`, or `measure=\<name>`) of the members the caller’s cards draw, in the order they draw them.
`assign`	boolean	no	Give a key the caller’s scope does not keep yet the lowest slot free in its field (false: only look up kept ones).
`password`	string	no

Responses: 200 · 400 · 401 · 403 · 404 · 429

`POST /api/shares/{token}/report-block-data`

Run a shared report block’s query by token (public)

Path parameters

Name	Type	Required	Description
`token`	string	yes

Request body (JSON)

Field	Type	Required
`blockId`	string	yes
`password`	string	no
`parameters`	array of object	no
`filters`	array of object	no

Responses: 200

`POST /api/shares/{token}/usage`

Record embed usage events (public)

Path parameters

Name	Type	Required	Description
`token`	string	yes

Request body (JSON)

Field	Type	Required	Description
`password`	string	no
`events`	array of object	yes

Responses: 200