BrightshoalDocsOpen console
MenuPublishable keys

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.

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_idstringrequired

  • accessstringrequired

    One of public team

  • expires_atstring | nullrequiredISO 8601 timestamp

    In the future; null works until it is turned off.

Returns

201 OK

Response attributes
  • dataPreviewLinkrequired

    8 attributes
    • idstringrequired

      Also the page address: /preview/{id} on the console.

    • assistant_idstringrequired

    • project_idstringrequired

    • keystringrequired

      The preview key the page loads the widget with.

    • accessstringrequired

      One of public team

    • expires_atstring | nullrequiredISO 8601 timestamp

    • expiredbooleanrequired

    • created_atstringrequiredISO 8601 timestamp

  • 400 Validation error: usually invalid_request, with the failing fields in issues when 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). Wait Retry-After seconds. 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).
POST /api/preview-links
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"
}'
Response 201
{
  "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"
  }
}

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_idstring

    Only keys for this project.

  • assistant_idstring

    Only keys pinned to this assistant.

  • kindstring

    site (the default) lists the keys for live websites, test the sandbox keys (kind: test, pk_test_...), all both.

    One of site test all

Returns

200 OK

Response attributes
  • dataarray of WidgetKeyrequired

    10 attributes
    • idstringrequired

    • org_idstringrequired

    • project_idstringrequired

    • assistant_idstring | nullrequired

      The assistant a pinned key is bound to; null for a project-scoped key.

    • keystringrequired

      Public, revocable widget key, pk_live_....

    • kindstring

      site keys go on the live website; sandbox keys on a staging site or localhost.

      One of site test

    • allowed_originsarray of string

      Sandbox keys: where the key loads. Site keys use the assistant's allowed_origins.

    • revoked_atstring | nullISO 8601 timestamp

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. 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).
GET /api/publishable-keys
curl "https://api.brightshoal.com/api/publishable-keys" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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 empty

    Mint a project-scoped key.

  • assistant_idstringnot empty

    Mint a key pinned to this assistant.

  • kindstring

    site for your live site, test for a sandbox key (pk_test_...) on a staging site or localhost.

    One of site test

    Default "site"

  • allowed_originsarray of stringup to 20 items

    Sandbox keys only, and required for them: the HTTP(S) origins the key loads on.

Returns

201 OK

Response attributes
  • dataWidgetKeyrequired

    10 attributes
    • idstringrequired

    • org_idstringrequired

    • project_idstringrequired

    • assistant_idstring | nullrequired

      The assistant a pinned key is bound to; null for a project-scoped key.

    • keystringrequired

      Public, revocable widget key, pk_live_....

    • kindstring

      site keys go on the live website; sandbox keys on a staging site or localhost.

      One of site test

    • allowed_originsarray of string

      Sandbox keys: where the key loads. Site keys use the assistant's allowed_origins.

    • revoked_atstring | nullISO 8601 timestamp

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

  • 400 Validation error: usually invalid_request, with the failing fields in issues when 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_found or project_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). Wait Retry-After seconds. 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).
POST /api/publishable-keys
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"
}'
Response 201
{
  "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

  • idstringrequired

    Key record id, wkey_... (not the pk_live_ key itself).

Returns

200 OK

Response attributes
  • dataWidgetKeyrequired

    10 attributes
    • idstringrequired

    • org_idstringrequired

    • project_idstringrequired

    • assistant_idstring | nullrequired

      The assistant a pinned key is bound to; null for a project-scoped key.

    • keystringrequired

      Public, revocable widget key, pk_live_....

    • kindstring

      site keys go on the live website; sandbox keys on a staging site or localhost.

      One of site test

    • allowed_originsarray of string

      Sandbox keys: where the key loads. Site keys use the assistant's allowed_origins.

    • revoked_atstring | nullISO 8601 timestamp

    • created_atstringISO 8601 timestamp

    • updated_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). Wait Retry-After seconds. 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).
DELETE /api/publishable-keys/{id}
curl -X DELETE "https://api.brightshoal.com/api/publishable-keys/PUBLISHABLE_KEY_ID" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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_urlstring

    Optional 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_idstring

  • assistant_idstring

  • daysinteger1 to 90

    Default 7

Returns

200 Site activity

Response attributes
  • dataobjectrequired

    3 attributes
    • sincestringrequiredISO 8601 timestamp

    • install_checkobject | null

      4 attributes
      • urlstring

      • checked_atstringISO 8601 timestamp

      • causestring | null

      • checksarray of object

        5 attributes
        • checkstringrequired

        • statusstringrequired

          One of passed failed unknown

        • causestring | nullrequired

          One of snippet_missing script_blocked_by_csp wrong_key page_unreachable origin_not_allowed

        • messagestringrequired

        • urlstring | nullrequired

    • sitesarray of objectrequiredup to 200 items

      8 attributes
      • assistant_idstringrequired

      • project_idstringrequired

      • sitestringrequireduri

        Scheme and host, for example https://www.example.com.

      • last_loaded_atstring | nullrequiredISO 8601 timestamp

      • loaded_countintegerrequiredmin 0

        widget_loaded page loads in the window; config/ok signals do not increase this count.

      • last_refused_atstring | nullrequiredISO 8601 timestamp

      • refused_countintegerrequiredmin 0

      • chats_countintegerrequiredmin 0

  • 400 Validation error: usually invalid_request, with the failing fields in issues when 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). Wait Retry-After seconds. 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).
GET /api/publishable-keys/site-activity
curl "https://api.brightshoal.com/api/publishable-keys/site-activity" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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
      }
    ]
  }
}