Search API
POST /api/v1/conversations/search
Summary: Search Conversations
Search conversations by content.
Request Schema (ConversationSearchRequest):
| Property | Type | Required | Description |
|---|---|---|---|
query | string | * | |
org_id | any | ||
mode | any | ||
status | any | ||
limit | integer |
Response Schema (ConversationSearchResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
results | array of ConversationResponse | * | |
total | integer | * | |
query | string | * |
POST /api/v1/query/
Summary: Execute Query
Execute a query through the agent workflow.
Organization-aware: If organization context is present in request, uses product-specific workflow (Knowledge Base, Advisor, Docs).
Credit system: Deducts 1 credit per query (2 if reformulation triggered). Returns X-Credits-Remaining header with updated balance.
Returns answer with citations and metadata.
Request Schema (QueryRequest):
| Property | Type | Required | Description |
|---|---|---|---|
query | string | * | The search query |
thread_id | any | Conversation thread ID for context | |
collection_id | any | Filter results to specific collection |
Response Schema (QueryResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
answer | string | * | |
citations | array of CitationSource | ||
ui_blocks | array of UIBlock | ||
thread_id | string | * | |
iterations | integer | * | |
critique_score | any | ||
query_id | any | ||
latency_ms | any | ||
timestamp | string | ||
source | any | Answer source: 'knowledge_base', 'general_knowledge', or 'no_answer' | |
kb_documents_found | any | Number of documents found in knowledge base | |
confidence | any | Unified answer confidence (0.0-1.0) | |
is_uncertain | boolean | True when the answer confidence is below the uncertainty threshold | |
detected_language | any | Detected language of the user query (BCP-47, e.g. 'ar'); None when multilingual is off/English |
POST /api/v1/query/stream
Summary: Stream Query
Execute a query with streaming updates.
Organization-aware: If organization context is present in request, uses product-specific workflow (Knowledge Base, Advisor, Docs).
Returns server-sent events with progress updates.
Request Schema (QueryRequest):
| Property | Type | Required | Description |
|---|---|---|---|
query | string | * | The search query |
thread_id | any | Conversation thread ID for context | |
collection_id | any | Filter results to specific collection |
GET /api/v1/query/threads
Summary: List Threads
List all chat threads for the current user
GET /api/v1/query/threads/{thread_id}
Summary: Get Thread
Get thread info and messages
DELETE /api/v1/query/threads/{thread_id}
Summary: Delete Thread
Delete a chat thread
POST /api/v1/research/
Summary: Deep Research
Perform deep research using multi-step reasoning across local and external sources.
This endpoint:
- Plans the research by decomposing the query
- Gathers information from local knowledge base
- Gathers information from external sources (web, Wikipedia, ArXiv)
- Synthesizes findings into a comprehensive report
- Critiques quality and refines if needed
- Returns structured report with citations
Requires authentication. Costs 10 credits per research request.
Request Schema (ResearchRequest):
| Property | Type | Required | Description |
|---|---|---|---|
query | string | * | The research question |
max_iterations | integer | Maximum refinement iterations | |
include_external | boolean | Include external sources (web, Wikipedia, ArXiv) | |
thread_id | any | Thread ID for context |
Response Schema (APIResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
success | boolean | ||
data | any | ||
message | any | ||
error | any |
GET /api/v1/research/status
Summary: Research Status
Get research mode status and configuration.
Response Schema (APIResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
success | boolean | ||
data | any | ||
message | any | ||
error | any |
POST /api/v1/multimodal/query
Summary: Multimodal Query
Query endpoint with multimodal support.
Searches both text and visual content, returning integrated results.
Costs 3 credits per multimodal query.
Request Schema (MultimodalQueryRequest):
| Property | Type | Required | Description |
|---|---|---|---|
query | string | * | The search query |
thread_id | any | Conversation thread ID for context | |
collection_id | any | Filter results to specific collection | |
include_visual | boolean | Include visual content in search |
Response Schema (MultimodalQueryResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
answer | string | * | |
citations | array of CitationSource | ||
image_citations | array of ImageReference | ||
thread_id | string | * | |
iterations | integer | * | |
critique_score | any | ||
query_id | any | ||
latency_ms | any | ||
timestamp | string | ||
source | any | Answer source: 'knowledge_base', 'general_knowledge', or 'no_answer' | |
kb_documents_found | any | Number of documents found in knowledge base | |
confidence | any | Unified answer confidence (0.0-1.0) | |
is_uncertain | boolean | True when the answer confidence is below the uncertainty threshold | |
detected_language | any | Detected language of the user query (BCP-47, e.g. 'ar'); None when multilingual is off/English |
POST /api/v1/search
Summary: Search
Returns source chunks without generating an answer. vector uses pgvector and
query embeddings; full_text uses pg_textsearch BM25 with query-side typo
correction; hybrid combines those two legs with reciprocal rank fusion.
The retired fuzzy mode is rejected.
Authentication: Platform-user JWTs, scoped secret keys (X-API-Key or
Bearer), and delegated end-user tokens are supported. Customer credentials need
the search scope and API access entitlement. Secret keys follow their active
issuer's project permissions and retain org-only document ACLs. Publishable and
portal credentials can retrieve only org-shared or org-wide project sources.
Supplying a collection ID never grants access to it.
Relevance: By default, the configured reranker scores candidates and removes
scores below min_relevance=0.1. Scores describe model relevance, not factual
answer confidence. search_metadata.coverage_status distinguishes strong,
weak, no_match, unscored and unavailable. These are retrieval signals,
not guarantees that a question can be answered. Scores are cached by model,
query and chunk content, after current access checks.
rerank_k caps the candidate window before scoring and pagination. The response
reports rerank_candidates (unique authorized chunks considered, including cache
hits) and rerank_candidate_limit in search_metadata. These are not provider
call counts. Results and pagination totals cover that window. It is ignored when
rerank=false. The console defaults to a 20-candidate window and lets operators
disable the limit; API clients keep their existing window unless they opt in.
Overlapping identical cache misses share embedding and reranker work within one API worker. Reranker sharing happens after current source and ACL checks, and is keyed by scope, model, exact query and chunk content. Redis continues sharing scores between workers; entire authorized search responses are not cached.
Set rerank=false for raw retrieval. Set min_relevance=null to retain all
scored candidates, or provide a threshold suited to your workload. If scoring
is unavailable, the threshold is not applied: results are returned with
degraded=true and relevance_status=unavailable.
Failures: Each retrieval leg reports ok, failed or timeout in
component_status. A partial failure returns flagged fallback results with
degraded=true. If every requested retrieval leg fails, the endpoint returns
HTTP 503; the platform error envelope contains search_unavailable, a request
ID and failed modes in error.message. A healthy query with no hits returns
200. Missing credentials return 401; missing scope/access returns 403, and
foreign collections return 404.
Pagination and sorting: Each mode honors offset/limit. Multi-mode results
apply the same page to each component; pagination.total sums their bounded
candidate counts. Hybrid returns one fused page. Sorting supports title,
score and ord, ascending or descending, within the retrieved candidate
window. Totals are not a whole-corpus match count. Unsupported sort fields
return 422. Facets aggregate the authorized filter scope.
Latency depends on corpus size, embeddings, reranking and caches. Disabling reranking skips its provider call. Rate limits and component timeouts are deployment-configured; this endpoint has no fixed latency or throughput SLA.
Request Schema (SearchRequest):
| Property | Type | Required | Description |
|---|---|---|---|
query | string | * | Nonempty query, up to 8000 characters |
search_modes | array of SearchMode | vector, full_text, or hybrid (default) | |
top_k_per_mode | integer | Maximum results per search mode (before fusion) | |
final_k | integer | Final number of results to return (after fusion/dedup) | |
rerank | boolean | Score relevance; default true | |
rerank_k | integer or null | Optional candidate budget per mode, 1–200; hybrid applies it after fusion. Default null preserves all retrieval candidates. Smaller windows may reduce recall. | |
min_relevance | number or null | Minimum scored relevance, 0–1; default 0.1 | |
filters | any | Structured filter clauses | |
facets | any | Facet aggregations to compute | |
sort | object | field: title/score/ord; order: asc/desc | |
pagination | any | Pagination configuration | |
collection_id | any | Filter to specific collection | |
project_id | any | Filter to specific project | |
include_debug | boolean | Include debug information |
Response Schema (SearchResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
query_received | string | * | Query as received |
search_metadata | SearchMetadata | * | Search execution metadata |
results | any | * | Results by mode (dict) or fused results (list) |
facets | any | Facet aggregations | |
pagination | object | * | Pagination info: offset, limit, total |
request_id | string | * | Unique request ID for tracing |
POST /api/v1/admin/playground/search
Summary: Test Search
Test search queries with detailed breakdown by method.
Admin only - Test retrieval quality before exposing to end users.
Credits: 1 credit per search test (retrieval only, no LLM).
Features:
- Side-by-side comparison of vector and BM25 search
- RRF fusion breakdown showing contribution of each retrieval leg
- Gap analysis identifying low scores and missing coverage
- Latency breakdown for the requested retrieval methods
Use this to:
- Benchmark search quality for specific collections
- Identify gaps in document coverage
- Tune retrieval parameters
- Compare different search strategies
Request Schema (PlaygroundSearchRequest):
| Property | Type | Required | Description |
|---|---|---|---|
query | string | * | Search query to test |
collection_id | any | Filter to specific collection | |
project_id | any | Filter to specific project | |
search_modes | array of string | Search modes to test | |
top_k_per_mode | integer | Results per search mode | |
show_scores | boolean | Include relevance scores | |
show_rrf_breakdown | boolean | Show RRF fusion details |
Response Schema (PlaygroundSearchResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
query | string | * | Query that was tested |
total_latency_ms | number | * | Total execution time |
method_results | object | * | Results grouped by search method |
fused_results | any | RRF-fused results from all methods | |
rrf_breakdown | any | RRF score breakdown by chunk_id per method | |
gaps | array of object | Identified gaps (low scores, missing coverage) | |
request_id | string | * | Unique request ID for tracing |
credits_used | any | Credits consumed by this request | |
credits_remaining | any | Remaining credit balance |
POST /api/v1/cms/delivery/{type_slug}/query
Summary: Query Content
Query published content with filters.
Filters are applied to the data JSONB column.
Example:
\{
"category": "news",
"author_id": "abc123"
\}