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 <token> 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

string[]

required

Array of KB UUIDs to search across. Must be non-empty.

string

Text search query. At least one of query, images, or files must be provided.

object[]

Image inputs for visual similarity search.

Show Image object

string

required

Base64-encoded image data.

string

required

Image MIME type (e.g., image/png).

object[]

File content for text-based search.

Show File object

string

required

File text content.

string

required

File MIME type.

number

Maximum number of results to return. Default varies by context.

Query Parameters

string

Search source: manual (user-initiated) or agent_rag (automated by agent during chat).

string

Agent UUID (for RAG attribution in search logs).

string

Conversation UUID (for RAG attribution).

string

Message UUID (for RAG attribution).

Response (200)

object[]

Ranked search results from all queried KBs.

Show Result object

string

Chunk text content.

number

Combined relevance score (0-1).

string

Source KB UUID.

object

Result metadata.

Show Metadata

string

Source document UUID.

string

Document title.

number

Position within document.

string

text, image, video, audio, or transcript.

string[]

How this result was found: semantic, image, and/or graph.

string

If discovered via graph, the entity relationship path.

string[]

AI-suggested follow-up queries based on the results.

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?"
  }'

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:

Semantic search: Embed the query using Gemini Embedding 2, then vector search across all specified KBs
Image search: If images are provided, embed them and search for visually similar content
Graph-informed discovery: Use the knowledge graph to find related documents through entity relationships
Merge and deduplicate: Combine results from all methods, deduplicate, and rank by combined score
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

string

required

KB UUID.

Request Body

string

required

Search query for entity matching.

string

Optional base64-encoded image for visual entity matching.

string

MIME type of the image (required if imageBase64 is provided).

Response (200)

string

The original query.

object[]

Matched entities.

Show Entity object

string

Entity UUID.

string

Entity name.

string

Entity type (e.g., person, concept, product).

string[]

Alternative names.

number

Number of document mentions.

object[]

Relationships between matched entities.

Show Relationship object

string

Source entity UUID.

string

Target entity UUID.

string

Relationship type.

number

Relationship strength.

string

Human-readable context string for LLM consumption.

string[]

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

string

required

KB UUID.

Response (200)

string

KB UUID.

string

KB name.

number

Number of documents.

object[]

Document registry entries.

Show Document entry

string

Document UUID.

string

Document title.

string

AI-generated document summary.

string[]

Key topics covered.

number

Number of chunks.

curl

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

string

required

KB UUID.

Clear Search History

Clear all search log entries for a knowledge base.

Getting Started

Agent Provisioning

Bot Service

Auth Service

Knowledge Service

Search

Search

Unified Search

Request Body

Query Parameters

Response (200)

Search Pipeline

Graph Entity Search

Path Parameters

Request Body

Response (200)

KB Document Map

Path Parameters

Response (200)

Search Logs

Get Search History

Path Parameters

Clear Search History

​Search

​Unified Search

​Request Body

​Query Parameters

​Response (200)

​Search Pipeline

​Graph Entity Search

​Path Parameters

​Request Body

​Response (200)

​KB Document Map

​Path Parameters

​Response (200)

​Search Logs

​Get Search History

​Path Parameters

​Clear Search History

Search

Unified Search

Request Body

Query Parameters

Response (200)

Search Pipeline

Graph Entity Search

Path Parameters

Request Body

Response (200)

KB Document Map

Path Parameters

Response (200)

Search Logs

Get Search History

Path Parameters

Clear Search History