Knowledge

Last updated: September 30, 2026

The knowledge search API runs the same search the BrokerBot agent uses (title matching, vector retrieval, and agentic search) against a team’s knowledge base, and returns matching documents with the relevant page text. Use it to show BrokerBot documents in your own UI.

Authentication

Send a team API key as Authorization: Bearer YOUR_API_KEY. Call this endpoint from your backend only: the key can read your team’s knowledge base. A key can only search its own team and that team’s sub-teams.

Search the knowledge base

POST https://api.brokerbot.ai/v1/knowledge/search

curl -X POST https://api.brokerbot.ai/v1/knowledge/search \
  -H "Authorization: Bearer $BROKERBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"commission split policy","userEmail":"[email protected]","limit":10}'

Request body:

Field Type Required Description
query string Yes What to search for. Up to 500 characters.
teamId string No Team or sub-team to search. Defaults to the API key’s team. Must be the key’s team or one of its sub-teams.
userEmail string No Search as this member, so documents shared only with them are included. The member must belong to the team being searched. Without it, results are limited to what an anonymous widget visitor can see.
limit integer No Maximum documents to return, 1–15. Default 10.

Response (200):

{
  "documents": [
    {
      "id": "doc_123",
      "name": "Commission Split Policy.pdf",
      "type": "pdf",
      "folderPath": "Policies/Compensation",
      "totalPages": 4,
      "pages": [
        { "pageNumber": 2, "text": "Agents on the 70/30 plan..." }
      ]
    }
  ]
}
Field Description
id Document ID. Pass it to the widget to open the document in chat.
name File name.
type File type, for example pdf or docx.
folderPath Folder the document lives in, or null at the root.
totalPages Page count, or null if unknown.
pages The pages that matched, with their text.

Errors:

Status Meaning
400 Missing or invalid query, teamId, userEmail, or limit, or the body isn’t JSON.
401 Missing or invalid API key, or the key has no team.
404 teamId is outside the key’s team, or userEmail isn’t a member of the team being searched.
502 Search failed. Safe to retry.

TypeScript / JavaScript

The brokerbot package wraps the same endpoint:

npm install brokerbot
import { BrokerBot, BrokerBotError } from "brokerbot"

const brokerbot = new BrokerBot({ apiKey: process.env.BROKERBOT_API_KEY! })

try {
  const { documents } = await brokerbot.searchKnowledge({
    query: "commission split policy",
    userEmail: "[email protected]",
    limit: 10
  })
} catch (error) {
  if (error instanceof BrokerBotError) {
    console.error(error.status, error.message)
  }
}

Open a result in the chat widget

A typical flow:

  1. Your backend calls search and returns id and name for each document to your UI.
  2. Your UI lists the results.
  3. When the visitor clicks one, open it in the widget:
window.BrokerBotWidget.open({
  document: { id: "doc_123", name: "Commission Split Policy.pdf" }
})

The widget starts a new chat with the document attached, and the agent knows which document the visitor is asking about. Downloading the document is still permission-checked for the visitor, so sign members in with SSO when documents aren’t public. See Control the widget from your page for the full widget API.