> ## 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
> Unified multi-modal search across knowledge bases with semantic, image, and graph discovery.
# Search
The search endpoints provide unified retrieval across multiple knowledge bases, combining semantic vector search, image similarity, and knowledge graph context.
All API requests require a valid JWT token in the `Authorization: Bearer ` header. The API Gateway decodes the JWT and forwards auth context (`user-id`, `organization-id`, `user-email`, `x-platform-role`, `x-org-role`) as headers to downstream services.
This endpoint incurs provider cost and records a billing event via `record_external_cost_event()`. Credits are deducted from the organization's wallet based on the configured margin multiplier.
## Unified Search
Search across one or more knowledge bases using text queries, images, and/or file content. This is the primary search endpoint used by both the manual search UI and the agent RAG pipeline.
### Request Body
Array of KB UUIDs to search across. Must be non-empty.
Text search query. At least one of `query`, `images`, or `files` must be provided.
Image inputs for visual similarity search.
Base64-encoded image data.
Image MIME type (e.g., `image/png`).
File content for text-based search.
File text content.
File MIME type.
Maximum number of results to return. Default varies by context.
### Query Parameters
Search source: `manual` (user-initiated) or `agent_rag` (automated by agent during chat).
Agent UUID (for RAG attribution in search logs).
Conversation UUID (for RAG attribution).
Message UUID (for RAG attribution).
### Response (200)
Ranked search results from all queried KBs.
Chunk text content.
Combined relevance score (0-1).
Source KB UUID.
Result metadata.
Source document UUID.
Document title.
Position within document.
`text`, `image`, `video`, `audio`, or `transcript`.
How this result was found: `semantic`, `image`, and/or `graph`.
If discovered via graph, the entity relationship path.
AI-suggested follow-up queries based on the results.
```bash curl theme={null}
curl -X POST https://your-domain.com/api/knowledge/search \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"knowledgeBaseIds": ["kb-uuid-1", "kb-uuid-2"],
"query": "What is the return policy for electronics?"
}'
```
```javascript JavaScript theme={null}
const response = await fetch("https://your-domain.com/api/knowledge/search", {
method: "POST",
headers: {
Authorization: `Bearer ${token}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
knowledgeBaseIds: ["kb-uuid-1", "kb-uuid-2"],
query: "What is the return policy for electronics?",
}),
});
const { results, suggestedFollowUps } = await response.json();
```
### Search Pipeline
The unified search orchestrates multiple discovery methods in parallel:
1. **Semantic search**: Embed the query using Gemini Embedding 2, then vector search across all specified KBs
2. **Image search**: If images are provided, embed them and search for visually similar content
3. **Graph-informed discovery**: Use the knowledge graph to find related documents through entity relationships
4. **Merge and deduplicate**: Combine results from all methods, deduplicate, and rank by combined score
5. **Tag discovery methods**: Each result is tagged with how it was found (`semantic`, `image`, `graph`)
***
## Graph Entity Search
Search the knowledge graph for entities and relationships matching a query. Returns structured entity data with relationship context.
### Path Parameters
KB UUID.
### Request Body
Search query for entity matching.
Optional base64-encoded image for visual entity matching.
MIME type of the image (required if `imageBase64` is provided).
### Response (200)
The original query.
Matched entities.
Entity UUID.
Entity name.
Entity type (e.g., `person`, `concept`, `product`).
Alternative names.
Number of document mentions.
Relationships between matched entities.
Source entity UUID.
Target entity UUID.
Relationship type.
Relationship strength.
Human-readable context string for LLM consumption.
Names of entities directly matched by the query.
***
## KB Document Map
Get the document registry for a knowledge base, including summaries and topics for each document. Used by agents for document awareness.
### Path Parameters
KB UUID.
### Response (200)
KB UUID.
KB name.
Number of documents.
Document registry entries.
Document UUID.
Document title.
AI-generated document summary.
Key topics covered.
Number of chunks.
```bash curl theme={null}
curl https://your-domain.com/api/knowledge/kb/KB_ID/map \
-H "Authorization: Bearer $TOKEN"
```
***
## Search Logs
### Get Search History
Get paginated search log history for a knowledge base.
### Path Parameters
KB UUID.
### Clear Search History
Clear all search log entries for a knowledge base.