API: Embedding

Embed apps and their keys, the sessions each embedded person gets, embedded use, and domain allowlists. All endpoints require authentication unless noted. 15 endpoints.

GET /api/embed-apps

List the workspace’s embed apps (company admins)

Each app’s keys are listed by their last four characters: a key’s secret is shown only when it is made.

Responses: 200 · 400 · 401 · 404

POST /api/embed-apps

Make an embed app: its client id and first key (company admins)

The key’s secret is in this response and never again: keep it on your server, where it signs a short-lived token for each person. Internal apps need Business; customer-facing apps need Enterprise.

Request body (JSON)

Field	Type	Required	Description
name	string	yes
content	array of object	yes
allowedSites	array of string	yes	The sites the app may be shown on: hosts such as portal.example.com or *.example.com (never every site).
attributeRules	array of object	no	Customer-facing apps: each token attribute and the model field it filters. Every rule is required in every token, and a token attribute with no rule is refused.
aiEnabled	boolean	no	true offers Ask AI to the app’s viewers whose token role is viewer_ai (a token setting, not a seat): the company’s bought credits pay, and API keys cannot turn it on.
personMonthlyCredits	integer | null	no	Whole credits a person may use a month (null: no budget).
tenantMonthlyCredits	integer | null	no	Whole credits a tenant may use a month (null: no budget).
personQuestionsPerHour	integer	no
tenantQuestionsPerHour	integer	no
audience	"internal" | "customer"	yes

Responses: 201 · 400 · 401 · 409

PATCH /api/embed-apps/{id}

Change an embed app (company admins)

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
name	string	no
content	array of object	no
allowedSites	array of string	no	The sites the app may be shown on: hosts such as portal.example.com or *.example.com (never every site).
attributeRules	array of object	no	Customer-facing apps: each token attribute and the model field it filters. Every rule is required in every token, and a token attribute with no rule is refused.
aiEnabled	boolean	no	true offers Ask AI to the app’s viewers whose token role is viewer_ai (a token setting, not a seat): the company’s bought credits pay, and API keys cannot turn it on.
personMonthlyCredits	integer | null	no	Whole credits a person may use a month (null: no budget).
tenantMonthlyCredits	integer | null	no	Whole credits a tenant may use a month (null: no budget).
personQuestionsPerHour	integer	no
tenantQuestionsPerHour	integer	no
audience	string	no

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

DELETE /api/embed-apps/{id}

Revoke an embed app: its sessions end now (company admins)

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 204 — No content · 401 · 404

POST /api/embed-apps/{id}/keys

Make a second key for an embed app, to rotate (company admins)

Two keys are active at a time at most. The secret is in this response and never again.

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 201 · 400 · 401 · 403 · 404 · 409

DELETE /api/embed-apps/{id}/keys/{keyId}

Revoke an embed app’s key: the sessions it made end now (company admins)

Path parameters

Name	Type	Required	Description
id	string	yes
keyId	string	yes

Responses: 204 — No content · 401 · 404

DELETE /api/embed-apps/people/{personId}

Erase a customer-facing embedded person (company admins)

For your own customer’s erasure request: the person’s record goes, with their sessions, which end now, and their conversations with the AI. Their views and questions stay counted, without them. Only a customer-facing person this workspace’s apps have seen (personId from GET /api/embed-apps/usage); a later token for the same id makes a new person.

Path parameters

Name	Type	Required	Description
personId	string	yes

Responses: 204 — No content · 401 · 404

GET /api/embed-apps/usage

Embedded use by app, tenant and person (company admins)

Views, Ask AI questions and AI credits (whole credits) of the workspace’s embed apps over the last days days, by app, by tenant and by person; and this month’s customer-facing views against the views a month Enterprise includes (the price book’s, as the month began: GET /api/public/catalog; views past them go on the next invoice). The tenants and the people are paged each on its own, the busiest first.

Query parameters

Name	Type	Required	Description
days	integer	no
tenantsLimit	20 | 50 | 100	no	Tenants a page
tenantsOffset	integer	no	Where the page of tenants starts
peopleLimit	20 | 50 | 100	no	People a page
peopleOffset	integer	no	Where the page of people starts

Responses: 200 · 400 · 401 · 404

GET /api/embed-config

Get embed configuration for workspace

Responses: 200 · 400 · 401 · 404

PUT /api/embed-config

Update embed configuration for workspace

Request body (JSON)

Field	Type	Required	Description
allowedOrigins	array of string	no
defaultTheme	string	no
logoUrl	string	no
showToolbar	boolean	no
allowExport	boolean	no

Responses: 200 · 400 · 401 · 404

GET /api/embed-tokens

List the company’s remaining embed tokens (retired; company admins)

Responses: 200 · 400 · 401

POST /api/embed-tokens

Retired: per-viewer embed tokens are replaced by embed apps

Always 410 EMBED_TOKENS_RETIRED. Make an embed app (Administration → Settings → Embedding); your server signs a short-lived token for each person with its key, and the embed swaps it for a session (POST /api/embed/sessions).

Responses: 401 · 410

DELETE /api/embed-tokens/{id}

Revoke an embed token

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 204 — No content · 401 · 404

GET /api/embed-usage

Embed usage rollups per share

Query parameters

Name	Type	Required	Description
days	integer	no

Responses: 200

POST /api/embed/sessions

Swap a person’s signed embed token for a session (public)

The embedded page sends the token the publisher’s server signed for one person (HS256 with an embed app’s key, 10 minutes at most, one session per token) and the site it is shown on (X-DS-Embed-Origin). The answer is a session token for an hour, accepted wherever a share token is (/api/shares/{token}/…) from that site only. No API key or account is involved, and the app’s secret never leaves the publisher’s server.

Request body (JSON)

Field	Type	Required	Description
token	string	yes

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