API reference
Publishable keys
Publishable keys (pk_live_...) let a browser start web chats with one assistant from the origins you allow. They are safe to ship in page source; secret API keys are not.
- GET
/api/preview-linksGet an assistant's preview link - POST
/api/preview-linksMake a preview link (pk_preview_…) - PATCH
/api/preview-links/{id}Change who may open a preview link, or when it expires - DELETE
/api/preview-links/{id}Turn a preview link off - GET
/api/preview-links/{id}/pageRead a preview link for its page - GET
/api/publishable-keysList publishable keys - POST
/api/publishable-keysCreate a publishable key - DELETE
/api/publishable-keys/{id}Revoke a publishable key - GET
/api/publishable-keys/site-activityList web chat install evidence by assistant and site
Get an assistant's preview link
GET/api/preview-links
The assistant's live (unrevoked) preview link, expired or not, or null when it has none.
Secret API key. How it works
Query parameters
assistant_idstringrequired
Returns
200 OK
Response attributes
dataPreviewLink | nullOne of 2 shapes
PreviewLink
idstringrequiredAlso the page address: /preview/{id} on the console.
assistant_idstringrequiredproject_idstringrequiredkeystringrequiredThe preview key the page loads the widget with.
accessstringrequiredOne of
publicteamexpires_atstring | nullrequiredISO 8601 timestampexpiredbooleanrequiredcreated_atstringrequiredISO 8601 timestamp
Option 2
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen there are any - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/preview-links?assistant_id=asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"key": "string",
"access": "public",
"expires_at": "2026-10-28T09:30:00.000Z",
"expired": true,
"created_at": "2026-10-28T09:30:00.000Z"
}
}Make a preview link (pk_preview_…)
POST/api/preview-links
A page where anyone with the link, or only signed-in members of the org, can try the assistant's web chat; it loads from any site and while web chat is off, and its chats are tests that send nothing outside. One live link per assistant: making one turns the previous link off, with its open chats.
Secret API key, not a viewer key. How it works
Request body
assistant_idstringrequiredaccessstringrequiredOne of
publicteamexpires_atstring | nullrequiredISO 8601 timestampIn the future; null works until it is turned off.
Returns
201 OK
Response attributes
dataPreviewLinkrequired8 attributes
idstringrequiredAlso the page address: /preview/{id} on the console.
assistant_idstringrequiredproject_idstringrequiredkeystringrequiredThe preview key the page loads the widget with.
accessstringrequiredOne of
publicteamexpires_atstring | nullrequiredISO 8601 timestampexpiredbooleanrequiredcreated_atstringrequiredISO 8601 timestamp
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen there are any - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 404 Not found, or outside what the key can see
- 409
assistant_archived: the assistant is archived; restore it first - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X POST "https://api.brightshoal.com/api/preview-links" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"access": "public",
"expires_at": "2026-10-28T09:30:00.000Z"
}'{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"key": "string",
"access": "public",
"expires_at": "2026-10-28T09:30:00.000Z",
"expired": true,
"created_at": "2026-10-28T09:30:00.000Z"
}
}Change who may open a preview link, or when it expires
PATCH/api/preview-links/{id}
The URL and key stay the same.
Secret API key, not a viewer key. How it works
Path parameters
idstringrequired
Request body
accessstringOne of
publicteamexpires_atstring | nullISO 8601 timestamp
Returns
200 OK
Response attributes
dataPreviewLinkrequired8 attributes
idstringrequiredAlso the page address: /preview/{id} on the console.
assistant_idstringrequiredproject_idstringrequiredkeystringrequiredThe preview key the page loads the widget with.
accessstringrequiredOne of
publicteamexpires_atstring | nullrequiredISO 8601 timestampexpiredbooleanrequiredcreated_atstringrequiredISO 8601 timestamp
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen there are any - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 404 Not found, or outside what the key can see
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X PATCH "https://api.brightshoal.com/api/preview-links/PREVIEW_LINK_ID" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"access": "public",
"expires_at": "2026-10-28T09:30:00.000Z"
}'{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"key": "string",
"access": "public",
"expires_at": "2026-10-28T09:30:00.000Z",
"expired": true,
"created_at": "2026-10-28T09:30:00.000Z"
}
}Turn a preview link off
DELETE/api/preview-links/{id}
The page stops loading, and the chats open on it end.
Secret API key, not a viewer key. How it works
Path parameters
idstringrequired
Returns
200 OK
Response attributes
dataPreviewLinkrequired8 attributes
idstringrequiredAlso the page address: /preview/{id} on the console.
assistant_idstringrequiredproject_idstringrequiredkeystringrequiredThe preview key the page loads the widget with.
accessstringrequiredOne of
publicteamexpires_atstring | nullrequiredISO 8601 timestampexpiredbooleanrequiredcreated_atstringrequiredISO 8601 timestamp
- 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 404 Not found, or outside what the key can see
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X DELETE "https://api.brightshoal.com/api/preview-links/PREVIEW_LINK_ID" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"key": "string",
"access": "public",
"expires_at": "2026-10-28T09:30:00.000Z",
"expired": true,
"created_at": "2026-10-28T09:30:00.000Z"
}
}Read a preview link for its page
GET/api/preview-links/{id}/page
Needs no session. A team-only link returns only access and org_id unless the caller is a member of that org, who also gets the key.
Secret API key. How it works
Path parameters
idstringrequired
Returns
200 OK
Response attributes
dataobject8 attributes
idstringrequiredaccessstringrequiredOne of
publicteamkeystringAbsent for a team-only link read by a non-member.
assistant_idstringnamestringThe widget's display name.
subtitlestring | nullexpires_atstring | nullISO 8601 timestamporg_idstringPresent only when the key is withheld.
- 404 Not found, or outside what the key can see
- 410 The link has expired
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/preview-links/PREVIEW_LINK_ID/page" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"access": "public",
"key": "string",
"assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"subtitle": "string",
"expires_at": "2026-10-28T09:30:00.000Z",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
}
}List publishable keys
GET/api/publishable-keys
Filter by project_id (covers project-scoped keys) or assistant_id (legacy pinned keys); no filter returns everything in scope. Site keys only unless kind says otherwise. Revoked keys are included, with revoked_at set.
Secret API key. How it works
Query parameters
project_idstringOnly keys for this project.
assistant_idstringOnly keys pinned to this assistant.
kindstringsite (the default) lists the keys for live websites, test the sandbox keys (
kind: test,pk_test_...), all both.One of
sitetestall
Returns
200 OK
Response attributes
dataarray of WidgetKeyrequired10 attributes
idstringrequiredorg_idstringrequiredproject_idstringrequiredassistant_idstring | nullrequiredThe assistant a pinned key is bound to; null for a project-scoped key.
keystringrequiredPublic, revocable widget key,
pk_live_....kindstringsite keys go on the live website; sandbox keys on a staging site or localhost.
One of
sitetestallowed_originsarray of stringSandbox keys: where the key loads. Site keys use the assistant's allowed_origins.
revoked_atstring | nullISO 8601 timestampcreated_atstringISO 8601 timestampupdated_atstringISO 8601 timestamp
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen there are any - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/publishable-keys" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": [
{
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"key": "string",
"kind": "site",
"allowed_origins": [
"https://www.example.com"
],
"revoked_at": "2026-10-28T09:30:00.000Z",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z"
}
]
}Create a publishable key
POST/api/publishable-keys
Returns the key in data.key: pk_live_... for a site key, pk_test_... for a sandbox key. project_id (or, with a project API key, nothing at all) mints a project-scoped key, usable with any assistant in the project: the embed names the assistant with data-mlf-assistant and public chat requests send assistant. assistant_id mints a key pinned to that assistant. An org-wide API key must send one of the two (400 otherwise). Publishable keys are safe in page source; which sites may use a site key is the assistant's channels.web_chat.allowed_origins. kind: test mints a sandbox key for a staging site or localhost: it loads only on its own allowed_origins, and its chats run the assistant's draft, search the sandbox knowledge publication and reach sandbox webhooks only.
Secret API key, not a viewer key. How it works
Request body
project_idstringnot emptyMint a project-scoped key.
assistant_idstringnot emptyMint a key pinned to this assistant.
kindstringsitefor your live site,testfor a sandbox key (pk_test_...) on a staging site or localhost.One of
sitetestDefault
"site"allowed_originsarray of stringup to 20 itemsSandbox keys only, and required for them: the HTTP(S) origins the key loads on.
Returns
201 OK
Response attributes
dataWidgetKeyrequired10 attributes
idstringrequiredorg_idstringrequiredproject_idstringrequiredassistant_idstring | nullrequiredThe assistant a pinned key is bound to; null for a project-scoped key.
keystringrequiredPublic, revocable widget key,
pk_live_....kindstringsite keys go on the live website; sandbox keys on a staging site or localhost.
One of
sitetestallowed_originsarray of stringSandbox keys: where the key loads. Site keys use the assistant's allowed_origins.
revoked_atstring | nullISO 8601 timestampcreated_atstringISO 8601 timestampupdated_atstringISO 8601 timestamp
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen there are any - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 404
assistant_not_foundorproject_not_found: not in this key's scope - 409
assistant_archived: the assistant is archived; restore it first (its existing keys stay) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X POST "https://api.brightshoal.com/api/publishable-keys" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"assistant_id": "asst_7d2e9b14c6a04f3e8b5d1a9c0e7f6b23"
}'{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"key": "string",
"kind": "site",
"allowed_origins": [
"https://www.example.com"
],
"revoked_at": "2026-10-28T09:30:00.000Z",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z"
}
}Revoke a publishable key
DELETE/api/publishable-keys/{id}
Revocation, not deletion: the row stays and gains a revoked_at, so an embed that still carries the key gets a clean refusal rather than a missing record.
Secret API key, not a viewer key. How it works
Path parameters
idstringrequiredKey record id,
wkey_...(not thepk_live_key itself).
Returns
200 OK
Response attributes
dataWidgetKeyrequired10 attributes
idstringrequiredorg_idstringrequiredproject_idstringrequiredassistant_idstring | nullrequiredThe assistant a pinned key is bound to; null for a project-scoped key.
keystringrequiredPublic, revocable widget key,
pk_live_....kindstringsite keys go on the live website; sandbox keys on a staging site or localhost.
One of
sitetestallowed_originsarray of stringSandbox keys: where the key loads. Site keys use the assistant's allowed_origins.
revoked_atstring | nullISO 8601 timestampcreated_atstringISO 8601 timestampupdated_atstringISO 8601 timestamp
- 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 404 Not found, or outside what the key can see
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X DELETE "https://api.brightshoal.com/api/publishable-keys/PUBLISHABLE_KEY_ID" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"key": "string",
"kind": "site",
"allowed_origins": [
"https://www.example.com"
],
"revoked_at": "2026-10-28T09:30:00.000Z",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z"
}
}List web chat install evidence by assistant and site
GET/api/publishable-keys/site-activity
Viewer role. Live traffic only, within the caller's org and project scope. Counts cover the requested window; last_loaded_at looks back 180 days across widget_loaded events and sampled config/ok outcomes, and last_refused_at looks back 30 days across origin_not_allowed outcomes on any chat route. Refusal counts cover the full requested window, including windows longer than 30 days. Chats count live web_chat conversations by their parent origin. Includes refused sites even if now allowed. Sorted by latest activity descending, at most 200 sites.
Secret API key. How it works
Query parameters
check_urlstringOptional HTTPS page to inspect now. Requires assistant_id. Adds install_check with per-check causes; null when the assistant is outside scope. No page fetch is performed without this parameter.
project_idstringassistant_idstringdaysinteger1 to 90Default
7
Returns
200 Site activity
Response attributes
dataobjectrequired3 attributes
sincestringrequiredISO 8601 timestampinstall_checkobject | null4 attributes
urlstringchecked_atstringISO 8601 timestampcausestring | nullchecksarray of object5 attributes
checkstringrequiredstatusstringrequiredOne of
passedfailedunknowncausestring | nullrequiredOne of
snippet_missingscript_blocked_by_cspwrong_keypage_unreachableorigin_not_allowedmessagestringrequiredurlstring | nullrequired
sitesarray of objectrequiredup to 200 items8 attributes
assistant_idstringrequiredproject_idstringrequiredsitestringrequireduriScheme and host, for example https://www.example.com.
last_loaded_atstring | nullrequiredISO 8601 timestamploaded_countintegerrequiredmin 0widget_loaded page loads in the window; config/ok signals do not increase this count.
last_refused_atstring | nullrequiredISO 8601 timestamprefused_countintegerrequiredmin 0chats_countintegerrequiredmin 0
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen there are any - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/publishable-keys/site-activity" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"since": "2026-10-28T09:30:00.000Z",
"install_check": {
"url": "https://example.com/hook",
"checked_at": "2026-10-28T09:30:00.000Z",
"cause": "string",
"checks": [
{
"check": "string",
"status": "passed",
"cause": "snippet_missing",
"message": "Hi, can I book a trip to Lisbon in May?",
"url": "https://example.com/hook"
}
]
},
"sites": [
{
"assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"site": "https://example.com/hook",
"last_loaded_at": "2026-10-28T09:30:00.000Z",
"loaded_count": 1,
"last_refused_at": "2026-10-28T09:30:00.000Z",
"refused_count": 1,
"chats_count": 1
}
]
}
}