Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.brainstormer.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Search a knowledge base

Run a semantic search against a knowledge base and retrieve the most relevant content chunks. 
POST /v1/kb/search
This endpoint works independently of chat. You can use it to power your own search UI, build document Q&A features, or retrieve relevant context before calling your own AI model.

​
Request body

​
kb_id
string
required
The ID of the knowledge base to search. You can find knowledge base IDs in the Brainstormer dashboard under Knowledge Base.
​
query
string
required
The search query. Brainstormer uses semantic (vector) search, so natural language queries work best.
​
top_k
number
default:"5"
The maximum number of results to return. Defaults to 5.
curl -X POST https://your-domain/v1/kb/search \
  -H "Authorization: Bearer brs_live_xxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "kb_id": "kb_xxxxxxxxxxxxxxxx",
    "query": "How do I reset my password?",
    "top_k": 3
  }'

​
Response

{
  "results": [
    {
      "id": "chunk_abc123",
      "score": 0.92,
      "knowledgeBaseId": "kb_xxxxxxxxxxxxxxxx",
      "discoveryMethods": ["semantic"],
      "metadata": {
        "documentId": "doc_xxxxxxxxxxxxxxxx",
        "text": "To reset your password, click the 'Forgot password' link on the login page. You will receive an email with a reset link valid for 24 hours.",
        "fileName": "account-help.pdf",
        "chunkIndex": 4
      }
    },
    {
      "id": "chunk_def456",
      "score": 0.78,
      "knowledgeBaseId": "kb_xxxxxxxxxxxxxxxx",
      "discoveryMethods": ["semantic"],
      "metadata": {
        "documentId": "doc_xxxxxxxxxxxxxxxx",
        "text": "If you did not receive the password reset email, check your spam folder or contact support.",
        "fileName": "account-help.pdf",
        "chunkIndex": 5
      }
    }
  ],
  "suggestedFollowUps": [
    "How long is the reset link valid?",
    "What if I don't receive the reset email?"
  ]
}
​
results
array
List of matching content chunks ordered by relevance score (highest first).
​
results[].id
string
Unique identifier for this chunk.
​
results[].score
number
Relevance score between 0 and 1. Higher values indicate a closer semantic match to your query.
​
results[].knowledgeBaseId
string
The ID of the knowledge base this result came from.
​
results[].discoveryMethods
array
The search strategies that surfaced this result. Possible values: "semantic", "image", "graph".
​
results[].metadata
object
Content and provenance information for the chunk.
​
results[].metadata.documentId
string
The ID of the source document this chunk belongs to.
​
results[].metadata.text
string
The text content of the matched chunk.
​
results[].metadata.fileName
string
The name of the source file.
​
results[].metadata.chunkIndex
number
The position of this chunk within its source document.
​
suggestedFollowUps
array
Optional list of suggested queries the user might want to search for next.