BrightshoalDocsOpen console
MenuKnowledge

API reference

Knowledge

Knowledge bases hold the pages, documents and text an assistant answers from. Sources are revised, approved and published as immutable publications, then attached to assistants.

Create a knowledge base

POST/api/knowledge

An empty knowledge base. Added public sources are approved immediately and go live automatically once indexing succeeds. Needs an org-wide API key: project keys cannot use organization knowledge.

Secret API key, not a viewer key, org-wide (not pinned to a project). How it works

Request body

  • namestringrequiredup to 200 characters

    Trimmed; 1 to 200 characters.

  • descriptionstringup to 2000 characters

    Default ""

  • reread_weeklyboolean

    Default true

Returns

201 Created

Response attributes
  • dataKnowledgeBaserequired

    18 attributes
    • idstringrequired

      kb_...

    • org_idstringrequired

    • namestringrequired

    • descriptionstringrequired

    • enabledbooleanrequired

    • active_publication_idstring | nullrequired

      The live publication, or null before the first publish.

    • versionintegerrequired

      The content counter: bumped when sources change and when name, description or enabled is updated. Approvals, publishing, test picks and retrieval_mode leave it as it is.

    • retrieval_modestringrequired

      One of vector_store hybrid

    • statestring

      Included on detail and list reads. Updating takes priority while an import or build is running; otherwise failures are problem, an active publication is live, and the remainder is empty.

      One of empty updating live problem

    • source_countinteger

      List reads: non-revoked sources.

    • page_countinteger

      List reads: non-revoked URL sources.

    • reread_weeklyboolean

    • last_reread_atstring | nullISO 8601 timestamp

    • next_reread_atstring | nullISO 8601 timestamp

    • test_publication_idstring | null

      The publication sandbox chats search instead of the live one, or null.

    • test_base_publication_idstring | null

      The live publication when the sandbox one was picked; promoting is refused once live has moved on.

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

  • 400 invalid_knowledge_payload
  • 401 Missing or invalid API key (unauthorized)
  • 403 insufficient_role (below admin) or knowledge_forbidden (a project-scoped key)
  • 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).
  • 502 knowledge_operation_failed: an unexpected failure; retry
POST /api/knowledge
curl -X POST "https://api.brightshoal.com/api/knowledge" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme Travel policies"
}'
Response 201
{
  "data": {
    "id": "kb_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "name": "Front desk",
    "description": "string",
    "enabled": true,
    "active_publication_id": "kpub_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "version": 1,
    "retrieval_mode": "vector_store",
    "state": "empty",
    "source_count": 1,
    "page_count": 1,
    "reread_weekly": true,
    "last_reread_at": "2026-10-28T09:30:00.000Z",
    "next_reread_at": "2026-10-28T09:30:00.000Z",
    "test_publication_id": "kpub_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "test_base_publication_id": "kpub_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "created_at": "2026-10-28T09:30:00.000Z",
    "updated_at": "2026-10-28T09:30:00.000Z"
  }
}

List knowledge bases

GET/api/knowledge

Every knowledge base in the organization, newest first. Needs an org-wide API key: project keys cannot use organization knowledge. A project key gets an empty list.

Secret API key, org-wide (not pinned to a project). How it works

Returns

200 OK

Response attributes
  • dataarray of KnowledgeBaserequired

    18 attributes
    • idstringrequired

      kb_...

    • org_idstringrequired

    • namestringrequired

    • descriptionstringrequired

    • enabledbooleanrequired

    • active_publication_idstring | nullrequired

      The live publication, or null before the first publish.

    • versionintegerrequired

      The content counter: bumped when sources change and when name, description or enabled is updated. Approvals, publishing, test picks and retrieval_mode leave it as it is.

    • retrieval_modestringrequired

      One of vector_store hybrid

    • statestring

      Included on detail and list reads. Updating takes priority while an import or build is running; otherwise failures are problem, an active publication is live, and the remainder is empty.

      One of empty updating live problem

    • source_countinteger

      List reads: non-revoked sources.

    • page_countinteger

      List reads: non-revoked URL sources.

    • reread_weeklyboolean

    • last_reread_atstring | nullISO 8601 timestamp

    • next_reread_atstring | nullISO 8601 timestamp

    • test_publication_idstring | null

      The publication sandbox chats search instead of the live one, or null.

    • test_base_publication_idstring | null

      The live publication when the sandbox one was picked; promoting is refused once live has moved on.

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

  • 401 Missing or invalid 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).
  • 502 knowledge_operation_failed: an unexpected failure; retry
GET /api/knowledge
curl "https://api.brightshoal.com/api/knowledge" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "data": [
    {
      "id": "kb_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "name": "Front desk",
      "description": "string",
      "enabled": true,
      "active_publication_id": "kpub_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "version": 1,
      "retrieval_mode": "vector_store",
      "state": "empty",
      "source_count": 1,
      "page_count": 1,
      "reread_weekly": true,
      "last_reread_at": "2026-10-28T09:30:00.000Z",
      "next_reread_at": "2026-10-28T09:30:00.000Z",
      "test_publication_id": "kpub_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "test_base_publication_id": "kpub_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "created_at": "2026-10-28T09:30:00.000Z",
      "updated_at": "2026-10-28T09:30:00.000Z"
    }
  ]
}

Get a knowledge base

GET/api/knowledge/{id}

The base with its sources (and each one's latest revision), publications, the assistants answering from it (attachments) and what open assistant drafts would change (pending). Private sources are listed only for admins and above. Poll this after starting a publication until its status is ready.

Secret API key, org-wide (not pinned to a project). How it works

Path parameters

  • idstringrequired

    Knowledge base id, kb_....

Returns

200 OK

Response attributes
  • dataKnowledgeBaseDetailrequired

    25 attributes
    • idstringrequired

      kb_...

    • org_idstringrequired

    • namestringrequired

    • descriptionstringrequired

    • enabledbooleanrequired

    • active_publication_idstring | nullrequired

      The live publication, or null before the first publish.

    • versionintegerrequired

      The content counter: bumped when sources change and when name, description or enabled is updated. Approvals, publishing, test picks and retrieval_mode leave it as it is.

    • retrieval_modestringrequired

      One of vector_store hybrid

    • statestring

      Included on detail and list reads. Updating takes priority while an import or build is running; otherwise failures are problem, an active publication is live, and the remainder is empty.

      One of empty updating live problem

    • source_countinteger

      List reads: non-revoked sources.

    • page_countinteger

      List reads: non-revoked URL sources.

    • reread_weeklyboolean

    • last_reread_atstring | nullISO 8601 timestamp

    • next_reread_atstring | nullISO 8601 timestamp

    • test_publication_idstring | null

      The publication sandbox chats search instead of the live one, or null.

    • test_base_publication_idstring | null

      The live publication when the sandbox one was picked; promoting is refused once live has moved on.

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

    • can_editbooleanrequired

      Whether the caller may change this base: admins and above, and admin keys.

    • importKnowledgePageImport | null

      5 attributes
      • statusstringrequired

        One of running done failed

      • totalintegerrequired

      • doneintegerrequired

      • failedarray of objectrequired

        6 attributes
        • urlstringrequired

        • errorstringrequired

        • messagestring

        • resourcestring

        • limitinteger

        • usedinteger

      • started_atstringrequiredISO 8601 timestamp

    • configuredboolean

      Whether this deployment can index and search knowledge.

    • sourcesarray of KnowledgeSourcerequired

      10 attributes
      • idstringrequired

        ksrc_...

      • titlestringrequired

      • kindstringrequired

        One of text url file

      • urlstring | null

      • audiencestringrequired

        One of public private

      • read_atstring | nullISO 8601 timestamp

      • read_errorstring | null

        Last failed read's short code, such as not_found, unreachable, blocked or too_large; cleared after a successful read.

      • revoked_atstring | nullISO 8601 timestamp

      • expires_atstring | nullISO 8601 timestamp

      • revisionobject | nullrequired

        The latest revision.

        5 attributes
        • idstringrequired

          krev_...

        • approvedbooleanrequired

        • charactersintegerrequired

        • content_hashstringrequired

        • created_atstringrequiredISO 8601 timestamp

    • publicationsarray of KnowledgePublicationrequired

      11 attributes
      • idstringrequired

        kpub_...

      • statusstringrequired

        One of queued indexing ready failed

      • errorstring | null

      • hybrid_errorstring | null

      • hybrid_error_detailsobject | null

      • error_detailsobject | null

        Billing refusal body, including message and resource or feature.

      • retryingboolean

        True while a failed publication will be retried automatically: a provider indexing failure (indexing_failed, indexing_timeout or provider_file_missing), fewer than five attempts so far, and no source change since it was built. Keep polling while it is true; otherwise retry it yourself, or build again after a change.

      • hybrid_statusstring | null

        The hybrid search index for this publication, or null when it has none.

        One of queued indexing ready failed

      • base_versionintegerrequired

        The base version it was built from.

      • created_atstringrequiredISO 8601 timestamp

      • published_atstring | nullISO 8601 timestamp

    • attachmentsarray of objectrequired

      5 attributes
      • assistant_idstringrequired

      • namestringrequired

      • chatbooleanrequired

      • voicebooleanrequired

      • priorityintegerrequired

    • pendingarray of objectrequired

      What publishing each open assistant draft would change for this base.

      6 attributes
      • assistant_idstringrequired

      • namestringrequired

      • changestringrequired

        One of attach update detach

      • chatbooleanrequired

      • voicebooleanrequired

      • priorityintegerrequired

  • 401 Missing or invalid API key (unauthorized)
  • 403 organization_knowledge_access_required: a project-scoped key
  • 404 knowledge_not_found
  • 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).
  • 502 knowledge_operation_failed: an unexpected failure; retry
GET /api/knowledge/{id}
curl "https://api.brightshoal.com/api/knowledge/KNOWLEDGE_ID" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "data": {
    "id": "kb_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "name": "Front desk",
    "description": "string",
    "enabled": true,
    "active_publication_id": "kpub_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "version": 1,
    "retrieval_mode": "vector_store",
    "state": "empty",
    "source_count": 1,
    "page_count": 1,
    "reread_weekly": true,
    "last_reread_at": "2026-10-28T09:30:00.000Z",
    "next_reread_at": "2026-10-28T09:30:00.000Z",
    "test_publication_id": "kpub_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "test_base_publication_id": "kpub_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "created_at": "2026-10-28T09:30:00.000Z",
    "updated_at": "2026-10-28T09:30:00.000Z",
    "can_edit": true,
    "import": {
      "status": "running",
      "total": 1,
      "done": 1,
      "failed": [
        {
          "url": "https://example.com/hook",
          "error": "string",
          "message": "Hi, can I book a trip to Lisbon in May?",
          "resource": "string",
          "limit": 1,
          "used": 1
        }
      ],
      "started_at": "2026-10-28T09:30:00.000Z"
    },
    "configured": true,
    "sources": [
      {
        "id": "ksrc_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "title": "Front desk",
        "kind": "text",
        "url": "https://example.com/hook",
        "audience": "public",
        "read_at": "2026-10-28T09:30:00.000Z",
        "read_error": "string",
        "revoked_at": "2026-10-28T09:30:00.000Z",
        "expires_at": "2026-10-28T09:30:00.000Z",
        "revision": {
          "id": "ksrc_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
          "approved": true,
          "characters": 1,
          "content_hash": "string",
          "created_at": "2026-10-28T09:30:00.000Z"
        }
      }
    ],
    "publications": [
      {
        "id": "kpub_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "status": "queued",
        "error": "string",
        "hybrid_error": "string",
        "hybrid_error_details": {},
        "error_details": {},
        "retrying": true,
        "hybrid_status": "queued",
        "base_version": 1,
        "created_at": "2026-10-28T09:30:00.000Z",
        "published_at": "2026-10-28T09:30:00.000Z"
      }
    ],
    "attachments": [
      {
        "assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "name": "Front desk",
        "chat": true,
        "voice": true,
        "priority": 1
      }
    ],
    "pending": [
      {
        "assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "name": "Front desk",
        "change": "attach",
        "chat": true,
        "voice": true,
        "priority": 1
      }
    ]
  }
}

Update a knowledge base

PATCH/api/knowledge/{id}

Rename it, change its description, turn it off (enabled: false stops every attached assistant using it at once, without deleting anything), or choose how it is searched.

Secret API key, not a viewer key, org-wide (not pinned to a project). How it works

Path parameters

  • idstringrequired

    Knowledge base id, kb_....

Request body

  • namestringup to 200 characters

    Trimmed; 1 to 200 characters.

  • descriptionstringup to 2000 characters

  • enabledboolean

  • reread_weeklyboolean

    Fetch non-revoked URL sources about once a week.

  • retrieval_modestring

    How assistants search it. New bases use hybrid, which takes effect once the live publication's hybrid index is ready; until then search uses the vector store.

    One of vector_store hybrid

Returns

200 OK

Response attributes
  • dataKnowledgeBaserequired

    18 attributes
    • idstringrequired

      kb_...

    • org_idstringrequired

    • namestringrequired

    • descriptionstringrequired

    • enabledbooleanrequired

    • active_publication_idstring | nullrequired

      The live publication, or null before the first publish.

    • versionintegerrequired

      The content counter: bumped when sources change and when name, description or enabled is updated. Approvals, publishing, test picks and retrieval_mode leave it as it is.

    • retrieval_modestringrequired

      One of vector_store hybrid

    • statestring

      Included on detail and list reads. Updating takes priority while an import or build is running; otherwise failures are problem, an active publication is live, and the remainder is empty.

      One of empty updating live problem

    • source_countinteger

      List reads: non-revoked sources.

    • page_countinteger

      List reads: non-revoked URL sources.

    • reread_weeklyboolean

    • last_reread_atstring | nullISO 8601 timestamp

    • next_reread_atstring | nullISO 8601 timestamp

    • test_publication_idstring | null

      The publication sandbox chats search instead of the live one, or null.

    • test_base_publication_idstring | null

      The live publication when the sandbox one was picked; promoting is refused once live has moved on.

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

  • 400 invalid_knowledge_payload
  • 401 Missing or invalid API key (unauthorized)
  • 403 organization_knowledge_access_required (a project-scoped key) or insufficient_role (changes need admin or above)
  • 404 knowledge_not_found
  • 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).
  • 502 knowledge_operation_failed: an unexpected failure; retry
PATCH /api/knowledge/{id}
curl -X PATCH "https://api.brightshoal.com/api/knowledge/KNOWLEDGE_ID" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Front desk",
  "description": "string"
}'
Response 200
{
  "data": {
    "id": "kb_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "name": "Front desk",
    "description": "string",
    "enabled": true,
    "active_publication_id": "kpub_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "version": 1,
    "retrieval_mode": "vector_store",
    "state": "empty",
    "source_count": 1,
    "page_count": 1,
    "reread_weekly": true,
    "last_reread_at": "2026-10-28T09:30:00.000Z",
    "next_reread_at": "2026-10-28T09:30:00.000Z",
    "test_publication_id": "kpub_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "test_base_publication_id": "kpub_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "created_at": "2026-10-28T09:30:00.000Z",
    "updated_at": "2026-10-28T09:30:00.000Z"
  }
}

Add or revise a source

POST/api/knowledge/{id}/sources

Adds text, a web page (url) or a file (filename and base64: txt, md, html, docx or pdf up to 5 MB) and saves an approved revision. Approved public content is indexed and activated automatically; a failed build keeps the previous live publication. Pass an existing source id to revise it. Only public sources are ever published; audience defaults to public and cannot change later. URL sources must be public HTTPS pages that robots.txt allows, without query or fragment.

Secret API key, not a viewer key, org-wide (not pinned to a project). How it works

Path parameters

  • idstringrequired

    Knowledge base id, kb_....

Request body

  • idstring

    An existing source to revise. Omit to add a new one.

  • kindstringrequired

    One of text url file

  • titlestringrequiredup to 200 characters

    Trimmed; 1 to 200 characters.

  • audiencestring

    Fixed when the source is created.

    One of public private

    Default "public"

  • textstringup to 200000 characters

    text sources: the content.

  • urlstringup to 2048 characters

    url sources: the page to fetch.

  • filenamestringup to 200 characters

    file sources: the name, whose extension picks the parser.

  • base64stringup to 7000000 characters

    file sources: the file bytes, base64-encoded.

  • expires_atstring | nullISO 8601 timestamp

    Stop using the source after this time.

Returns

201 Created; data.id is the source id, ksrc_...

Response attributes
  • dataobjectrequired

    1 attribute
    • idstringrequired

  • 400 invalid_knowledge_payload (including text over 200,000 characters), source_text_required_or_too_large (empty text), invalid_source_id, or a URL or file code: invalid_source_url, public_https_url_required, source_path_not_allowed, source_disallowed_by_robots, source_address_not_public, source_redirect_not_allowed, source_too_large, source_needs_review_no_text, website_content_type_not_supported, unsupported_document_type, pdf_page_limit_reached, document_expansion_too_large
  • 401 Missing or invalid API key (unauthorized)
  • 403 organization_knowledge_access_required (a project-scoped key) or insufficient_role (changes need admin or above)
  • 404 knowledge_not_found, or source_not_found when revising
  • 409 source_identity_is_immutable (a revision changed the kind, URL or audience: add a new source instead) or source_limit_reached (100 active sources)
  • 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).
  • 502 source_fetch_failed, source_not_found or source_blocked (the page did not answer 200) or knowledge_operation_failed
  • 503 knowledge_storage_not_configured: this deployment cannot store sources
POST /api/knowledge/{id}/sources
curl -X POST "https://api.brightshoal.com/api/knowledge/KNOWLEDGE_ID/sources" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "url",
  "title": "Refund policy",
  "audience": "public",
  "url": "https://www.acmetravel.com/refunds"
}'
Response 201
{
  "data": {
    "id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
  }
}

Attach a knowledge base (retired)

POST/api/knowledge/{id}/attachments/{assistantId}

Retired: always 410 knowledge_attachments_moved. Which knowledge bases an assistant answers from is part of its config now (knowledge on PATCH /assistants/{id}), drafted and published with the rest of it, so a change no longer reaches live chats at once. Requires admin or above.

Secret API key, not a viewer key, org-wide (not pinned to a project). How it works

Path parameters

  • idstringrequired

    Knowledge base id, kb_....

  • assistantIdstringrequired

    Assistant id.

Returns

  • 401 Missing or invalid API key (unauthorized)
  • 403 insufficient_role (changes need admin or above)
  • 410 knowledge_attachments_moved
  • 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).
  • 502 knowledge_operation_failed: an unexpected failure; retry
POST /api/knowledge/{id}/attachments/{assistantId}
curl -X POST "https://api.brightshoal.com/api/knowledge/KNOWLEDGE_ID/attachments/ASSISTANT_ID" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"

Detach a knowledge base (retired)

DELETE/api/knowledge/{id}/attachments/{assistantId}

Retired: always 410 knowledge_attachments_moved. Which knowledge bases an assistant answers from is part of its config now (knowledge on PATCH /assistants/{id}), drafted and published with the rest of it, so a change no longer reaches live chats at once. Requires admin or above.

Secret API key, not a viewer key, org-wide (not pinned to a project). How it works

Path parameters

  • idstringrequired

    Knowledge base id, kb_....

  • assistantIdstringrequired

    Assistant id.

Returns

  • 401 Missing or invalid API key (unauthorized)
  • 403 insufficient_role (changes need admin or above)
  • 410 knowledge_attachments_moved
  • 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).
  • 502 knowledge_operation_failed: an unexpected failure; retry
DELETE /api/knowledge/{id}/attachments/{assistantId}
curl -X DELETE "https://api.brightshoal.com/api/knowledge/KNOWLEDGE_ID/attachments/ASSISTANT_ID" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"

Find a site's pages from its sitemap

POST/api/knowledge/{id}/discover

Reads robots-advertised sitemaps and bounded sitemap indexes, falling back to the homepage and its links. Follows redirects between the apex and www hosts, checks each origin's robots rules, excludes asset URLs and returns up to 100 page URLs without importing anything. Add the ones you want as url sources.

Secret API key, not a viewer key, org-wide (not pinned to a project). How it works

Path parameters

  • idstringrequired

    Knowledge base id, kb_....

Request body

  • urlstringrequiredup to 2048 characters

    Any page on the site; its origin's /sitemap.xml is read.

Returns

200 Page URLs

Response attributes
  • dataarray of stringrequiredup to 100 items

  • 400 invalid_knowledge_payload or a URL code such as public_https_url_required, source_disallowed_by_robots or source_address_not_public
  • 401 Missing or invalid API key (unauthorized)
  • 403 organization_knowledge_access_required (a project-scoped key) or insufficient_role (changes need admin or above)
  • 404 knowledge_not_found
  • 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).
  • 502 knowledge_operation_failed: an unexpected failure; retry
POST /api/knowledge/{id}/discover
curl -X POST "https://api.brightshoal.com/api/knowledge/KNOWLEDGE_ID/discover" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/hook"
}'
Response 200
{
  "data": [
    "https://example.com/hook"
  ]
}

Import website pages

POST/api/knowledge/{id}/pages

Durably fetch the selected same-origin public HTTP(S) pages, saving approved public URL sources. Unchanged text is reused. Poll the base for progress. One build is queued at completion.

Secret API key, not a viewer key, org-wide (not pinned to a project). How it works

Path parameters

  • idstringrequired

    Knowledge base id, kb_....

Request body

  • urlsarray of stringrequiredup to 100 items

  • reread_weeklyboolean

Returns

202 Queued

Response attributes
  • dataKnowledgePageImportAcceptedrequired

    2 attributes
    • totalintegerrequired

    • import_idstringrequired

  • 400 invalid_knowledge_payload, pages_same_origin_required, invalid_source_url, public_https_url_required or source_path_not_allowed
  • 401 Missing or invalid API key (unauthorized)
  • 403 organization_knowledge_access_required (a project-scoped key) or insufficient_role (changes need admin or above)
  • 404 knowledge_not_found
  • 409 page_import_in_progress
  • 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).
  • 502 knowledge_operation_failed: an unexpected failure; retry
POST /api/knowledge/{id}/pages
curl -X POST "https://api.brightshoal.com/api/knowledge/KNOWLEDGE_ID/pages" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "urls": [
    "https://example.com/hook"
  ]
}'
Response 202
{
  "data": {
    "total": 1,
    "import_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
  }
}

Build a publication

POST/api/knowledge/{id}/publications

Snapshots every approved public source into a new immutable publication and indexes it in the background (202). Poll the knowledge base until the publication is ready, then publish it. Returns the pending build instead when one is already queued. No request body.

Secret API key, not a viewer key, org-wide (not pinned to a project). How it works

Path parameters

  • idstringrequired

    Knowledge base id, kb_....

Returns

202 Queued; data.id is the publication id, kpub_...

Response attributes
  • dataobjectrequired

    1 attribute
    • idstringrequired

  • 400 no_public_sources
  • 401 Missing or invalid API key (unauthorized)
  • 403 organization_knowledge_access_required (a project-scoped key) or insufficient_role (changes need admin or above)
  • 404 knowledge_not_found
  • 409 review_all_public_sources_first or publication_limit_reached
  • 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).
  • 502 knowledge_operation_failed: an unexpected failure; retry
  • 503 knowledge_not_configured, knowledge_storage_not_configured or knowledge_provider_not_configured
POST /api/knowledge/{id}/publications
curl -X POST "https://api.brightshoal.com/api/knowledge/KNOWLEDGE_ID/publications" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 202
{
  "data": {
    "id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
  }
}

Publish a ready publication

POST/api/knowledge/{id}/publications/{publicationId}/publish

Makes a ready publication the live one, atomically; publishing an older ready publication rolls back to it. 409 publication_not_ready, or sources_changed_rebuild_publication when sources changed since it was built.

Secret API key, not a viewer key, org-wide (not pinned to a project). How it works

Path parameters

  • idstringrequired

    Knowledge base id, kb_....

  • publicationIdstringrequired

    Publication id, kpub_....

Returns

200 Published

Response attributes
  • dataobjectrequired

    1 attribute
    • idstringrequired

  • 401 Missing or invalid API key (unauthorized)
  • 403 organization_knowledge_access_required (a project-scoped key) or insufficient_role (changes need admin or above)
  • 404 knowledge_not_found
  • 409 publication_not_ready (also for an unknown publication id) or sources_changed_rebuild_publication
  • 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).
  • 502 knowledge_operation_failed: an unexpected failure; retry
POST /api/knowledge/{id}/publications/{publicationId}/publish
curl -X POST "https://api.brightshoal.com/api/knowledge/KNOWLEDGE_ID/publications/PUBLICATION_ID/publish" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "data": {
    "id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
  }
}

Retry a failed publication

POST/api/knowledge/{id}/publications/{publicationId}/retry

Queues a failed publication for indexing again, from the files it already stored. A publication already queued, indexing or ready returns its id unchanged. If a build is already queued for this base, returns that build's id.

Secret API key, not a viewer key, org-wide (not pinned to a project). How it works

Path parameters

  • idstringrequired

    Knowledge base id, kb_....

  • publicationIdstringrequired

    Publication id, kpub_....

Returns

200 Queued again

Response attributes
  • dataobjectrequired

    1 attribute
    • idstringrequired

  • 401 Missing or invalid API key (unauthorized)
  • 403 organization_knowledge_access_required (a project-scoped key) or insufficient_role (changes need admin or above)
  • 404 knowledge_not_found, or failed_publication_not_found (no failed publication with that id)
  • 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).
  • 502 knowledge_operation_failed: an unexpected failure; retry
POST /api/knowledge/{id}/publications/{publicationId}/retry
curl -X POST "https://api.brightshoal.com/api/knowledge/KNOWLEDGE_ID/publications/PUBLICATION_ID/retry" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "data": {
    "id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
  }
}

Try a publication in sandbox chats

POST/api/knowledge/{id}/publications/{publicationId}/test

Sandbox chats (on a sandbox publishable key, or the console's sandbox chat) search this ready publication instead of the live one, so new content can be tried before it goes live. Live chats are unchanged. Make it live with POST /knowledge/{id}/test-publication/promote. Requires admin or above.

Secret API key, not a viewer key, org-wide (not pinned to a project). How it works

Path parameters

  • idstringrequired

    Knowledge base id, kb_....

  • publicationIdstringrequired

    Publication id, kpub_....

Returns

200 Sandbox chats now search it

Response attributes
  • dataobjectrequired

    1 attribute
    • idstringrequired

  • 401 Missing or invalid API key (unauthorized)
  • 403 organization_knowledge_access_required (a project-scoped key) or insufficient_role (changes need admin or above)
  • 404 knowledge_not_found
  • 409 publication_not_ready (also for an unknown publication id) or sources_changed_rebuild_publication
  • 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).
  • 502 knowledge_operation_failed: an unexpected failure; retry
POST /api/knowledge/{id}/publications/{publicationId}/test
curl -X POST "https://api.brightshoal.com/api/knowledge/KNOWLEDGE_ID/publications/PUBLICATION_ID/test" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "data": {
    "id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
  }
}

Re-read website pages

POST/api/knowledge/{id}/reread

Durably re-fetch every non-revoked URL source. A failed fetch keeps the previous approved revision. Changed public text is indexed and goes live automatically.

Secret API key, not a viewer key, org-wide (not pinned to a project). How it works

Path parameters

  • idstringrequired

    Knowledge base id, kb_....

Returns

202 Queued

Response attributes
  • dataKnowledgePageImportAcceptedrequired

    2 attributes
    • totalintegerrequired

    • import_idstringrequired

  • 401 Missing or invalid API key (unauthorized)
  • 403 organization_knowledge_access_required (a project-scoped key) or insufficient_role (changes need admin or above)
  • 404 knowledge_not_found
  • 409 page_import_in_progress
  • 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).
  • 502 knowledge_operation_failed: an unexpected failure; retry
POST /api/knowledge/{id}/reread
curl -X POST "https://api.brightshoal.com/api/knowledge/KNOWLEDGE_ID/reread" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 202
{
  "data": {
    "total": 1,
    "import_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
  }
}

Preview a revision's extracted text

GET/api/knowledge/{id}/revisions/{revisionId}

The text extracted from a source revision, to check before approving it. A private source's revision is revision_not_found below admin.

Secret API key, org-wide (not pinned to a project). How it works

Path parameters

  • idstringrequired

    Knowledge base id, kb_....

  • revisionIdstringrequired

    Revision id, krev_..., from the source's revision.id.

Returns

200 OK

Response attributes
  • dataKnowledgeRevisionPreviewrequired

    4 attributes
    • revision_idstringrequired

    • titlestringrequired

    • textstringrequired

    • urlstring | null

  • 401 Missing or invalid API key (unauthorized)
  • 403 organization_knowledge_access_required: a project-scoped key
  • 404 knowledge_not_found or revision_not_found
  • 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).
  • 502 knowledge_operation_failed: an unexpected failure; retry
  • 503 knowledge_storage_not_configured
GET /api/knowledge/{id}/revisions/{revisionId}
curl "https://api.brightshoal.com/api/knowledge/KNOWLEDGE_ID/revisions/REVISION_ID" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "data": {
    "revision_id": "krev_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "title": "Front desk",
    "text": "Hi, can I book a trip to Lisbon in May?",
    "url": "https://example.com/hook"
  }
}

Approve a revision

POST/api/knowledge/{id}/revisions/{revisionId}/approve

Marks the extracted text as fit to publish. Every public source's latest revision must be approved before a publication can be built. Requires admin or above. No request body.

Secret API key, not a viewer key, org-wide (not pinned to a project). How it works

Path parameters

  • idstringrequired

    Knowledge base id, kb_....

  • revisionIdstringrequired

    Revision id, krev_....

Returns

200 Approved

Response attributes
  • dataobjectrequired

    1 attribute
    • idstringrequired

  • 401 Missing or invalid API key (unauthorized)
  • 403 organization_knowledge_access_required (a project-scoped key) or insufficient_role (changes need admin or above)
  • 404 knowledge_not_found or revision_not_found
  • 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).
  • 502 knowledge_operation_failed: an unexpected failure; retry
POST /api/knowledge/{id}/revisions/{revisionId}/approve
curl -X POST "https://api.brightshoal.com/api/knowledge/KNOWLEDGE_ID/revisions/REVISION_ID/approve" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "data": {
    "id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
  }
}

Search a knowledge base

POST/api/knowledge/{id}/search

Runs a question against the live publication (or, with publication: test, the sandbox one that sandbox chats search) and returns the passages an assistant would get, for checking coverage. It only reads, so a viewer key may call it although it is a POST.

Secret API key, org-wide (not pinned to a project). How it works

Path parameters

  • idstringrequired

    Knowledge base id, kb_....

Request body

  • querystringrequiredup to 2000 characters

  • publicationstring

    test searches the publication sandbox chats use.

    One of live test

    Default "live"

Returns

200 OK

Response attributes
  • dataKnowledgeSearchResultrequired

    3 attributes
    • statusstringrequired

      empty: nothing matched or nothing is published. unavailable: search failed this time.

      One of unattached skipped ok empty unavailable

    • evidencearray of objectrequired

      8 attributes
      • knowledge_base_idstringrequired

      • publication_idstringrequired

      • source_idstringrequired

      • revision_idstringrequired

      • titlestringrequired

      • urlstring | nullrequired

      • textstringrequired

      • scorenumberrequired

        Similarity, for ordering only; not a confidence.

    • elapsed_msintegerrequired

  • 400 invalid_knowledge_payload
  • 401 Missing or invalid API key (unauthorized)
  • 403 organization_knowledge_access_required: a project-scoped key
  • 404 knowledge_not_found
  • 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).
  • 502 knowledge_operation_failed: an unexpected failure; retry
POST /api/knowledge/{id}/search
curl -X POST "https://api.brightshoal.com/api/knowledge/KNOWLEDGE_ID/search" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "Can I get a refund if my flight is cancelled?"
}'
Response 200
{
  "data": {
    "status": "unattached",
    "evidence": [
      {
        "knowledge_base_id": "kb_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "publication_id": "kpub_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "source_id": "ksrc_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "revision_id": "krev_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "title": "Front desk",
        "url": "https://example.com/hook",
        "text": "Hi, can I book a trip to Lisbon in May?",
        "score": 1
      }
    ],
    "elapsed_ms": 640
  }
}

Revoke a source

DELETE/api/knowledge/{id}/sources/{sourceId}

Answers stop using the source at once, even from the live publication; the next publication leaves it out.

Secret API key, not a viewer key, org-wide (not pinned to a project). How it works

Path parameters

  • idstringrequired

    Knowledge base id, kb_....

  • sourceIdstringrequired

    Source id, ksrc_....

Returns

200 Revoked; data is the source row with revoked_at set

Response attributes
  • dataobjectrequired

    1 attribute
    • idstringrequired

  • 401 Missing or invalid API key (unauthorized)
  • 403 organization_knowledge_access_required (a project-scoped key) or insufficient_role (changes need admin or above)
  • 404 knowledge_not_found or source_not_found
  • 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).
  • 502 knowledge_operation_failed: an unexpected failure; retry
DELETE /api/knowledge/{id}/sources/{sourceId}
curl -X DELETE "https://api.brightshoal.com/api/knowledge/KNOWLEDGE_ID/sources/SOURCE_ID" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "data": {
    "id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
  }
}

Stop trying a publication

DELETE/api/knowledge/{id}/test-publication

Sandbox chats go back to searching the live publication. Requires admin or above.

Secret API key, not a viewer key, org-wide (not pinned to a project). How it works

Path parameters

  • idstringrequired

    Knowledge base id, kb_....

Returns

200 Cleared; data.id is the knowledge base id

Response attributes
  • dataobjectrequired

    1 attribute
    • idstringrequired

  • 401 Missing or invalid API key (unauthorized)
  • 403 organization_knowledge_access_required (a project-scoped key) or insufficient_role (changes need admin or above)
  • 404 knowledge_not_found
  • 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).
  • 502 knowledge_operation_failed: an unexpected failure; retry
DELETE /api/knowledge/{id}/test-publication
curl -X DELETE "https://api.brightshoal.com/api/knowledge/KNOWLEDGE_ID/test-publication" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "data": {
    "id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
  }
}

Make the tested publication live

POST/api/knowledge/{id}/test-publication/promote

Makes the publication sandbox chats are searching the live one, then clears the sandbox pick. Send expected_publication_id to be sure it is the one you tested. Refused when another publication went live after it was picked, since it may lack what that one added: try the publication again, or build a new one. Requires admin or above.

Secret API key, not a viewer key, org-wide (not pinned to a project). How it works

Path parameters

  • idstringrequired

    Knowledge base id, kb_....

Request body

  • expected_publication_idstringnot empty

    The publication you tested, kpub_...; 409 test_publication_changed when the sandbox pick is another one.

Returns

200 Live; data.id is the publication id

Response attributes
  • dataobjectrequired

    1 attribute
    • idstringrequired

  • 400 invalid_knowledge_payload
  • 401 Missing or invalid API key (unauthorized)
  • 403 organization_knowledge_access_required (a project-scoped key) or insufficient_role (changes need admin or above)
  • 404 knowledge_not_found
  • 409 no_test_publication, test_publication_changed, test_publication_stale (another publication went live after this one was picked), publication_not_ready or sources_changed_rebuild_publication
  • 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).
  • 502 knowledge_operation_failed: an unexpected failure; retry
POST /api/knowledge/{id}/test-publication/promote
curl -X POST "https://api.brightshoal.com/api/knowledge/KNOWLEDGE_ID/test-publication/promote" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "expected_publication_id": "kpub_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
}'
Response 200
{
  "data": {
    "id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
  }
}