Pragence

Search API

POST /api/v1/conversations/search

Summary: Search Conversations

Search conversations by content.

Request Schema (ConversationSearchRequest):

PropertyTypeRequiredDescription
querystring*
org_idany
modeany
statusany
limitinteger

Response Schema (ConversationSearchResponse - Status 200):

PropertyTypeRequiredDescription
resultsarray of ConversationResponse*
totalinteger*
querystring*

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):

PropertyTypeRequiredDescription
querystring*The search query
thread_idanyConversation thread ID for context
collection_idanyFilter results to specific collection

Response Schema (QueryResponse - Status 200):

PropertyTypeRequiredDescription
answerstring*
citationsarray of CitationSource
ui_blocksarray of UIBlock
thread_idstring*
iterationsinteger*
critique_scoreany
query_idany
latency_msany
timestampstring
sourceanyAnswer source: 'knowledge_base', 'general_knowledge', or 'no_answer'
kb_documents_foundanyNumber of documents found in knowledge base
confidenceanyUnified answer confidence (0.0-1.0)
is_uncertainbooleanTrue when the answer confidence is below the uncertainty threshold
detected_languageanyDetected 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):

PropertyTypeRequiredDescription
querystring*The search query
thread_idanyConversation thread ID for context
collection_idanyFilter 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:

  1. Plans the research by decomposing the query
  2. Gathers information from local knowledge base
  3. Gathers information from external sources (web, Wikipedia, ArXiv)
  4. Synthesizes findings into a comprehensive report
  5. Critiques quality and refines if needed
  6. Returns structured report with citations

Requires authentication. Costs 10 credits per research request.

Request Schema (ResearchRequest):

PropertyTypeRequiredDescription
querystring*The research question
max_iterationsintegerMaximum refinement iterations
include_externalbooleanInclude external sources (web, Wikipedia, ArXiv)
thread_idanyThread ID for context

Response Schema (APIResponse - Status 200):

PropertyTypeRequiredDescription
successboolean
dataany
messageany
errorany

GET /api/v1/research/status

Summary: Research Status

Get research mode status and configuration.

Response Schema (APIResponse - Status 200):

PropertyTypeRequiredDescription
successboolean
dataany
messageany
errorany

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):

PropertyTypeRequiredDescription
querystring*The search query
thread_idanyConversation thread ID for context
collection_idanyFilter results to specific collection
include_visualbooleanInclude visual content in search

Response Schema (MultimodalQueryResponse - Status 200):

PropertyTypeRequiredDescription
answerstring*
citationsarray of CitationSource
image_citationsarray of ImageReference
thread_idstring*
iterationsinteger*
critique_scoreany
query_idany
latency_msany
timestampstring
sourceanyAnswer source: 'knowledge_base', 'general_knowledge', or 'no_answer'
kb_documents_foundanyNumber of documents found in knowledge base
confidenceanyUnified answer confidence (0.0-1.0)
is_uncertainbooleanTrue when the answer confidence is below the uncertainty threshold
detected_languageanyDetected 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):

PropertyTypeRequiredDescription
querystring*Nonempty query, up to 8000 characters
search_modesarray of SearchModevector, full_text, or hybrid (default)
top_k_per_modeintegerMaximum results per search mode (before fusion)
final_kintegerFinal number of results to return (after fusion/dedup)
rerankbooleanScore relevance; default true
rerank_kinteger or nullOptional candidate budget per mode, 1–200; hybrid applies it after fusion. Default null preserves all retrieval candidates. Smaller windows may reduce recall.
min_relevancenumber or nullMinimum scored relevance, 0–1; default 0.1
filtersanyStructured filter clauses
facetsanyFacet aggregations to compute
sortobjectfield: title/score/ord; order: asc/desc
paginationanyPagination configuration
collection_idanyFilter to specific collection
project_idanyFilter to specific project
include_debugbooleanInclude debug information

Response Schema (SearchResponse - Status 200):

PropertyTypeRequiredDescription
query_receivedstring*Query as received
search_metadataSearchMetadata*Search execution metadata
resultsany*Results by mode (dict) or fused results (list)
facetsanyFacet aggregations
paginationobject*Pagination info: offset, limit, total
request_idstring*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):

PropertyTypeRequiredDescription
querystring*Search query to test
collection_idanyFilter to specific collection
project_idanyFilter to specific project
search_modesarray of stringSearch modes to test
top_k_per_modeintegerResults per search mode
show_scoresbooleanInclude relevance scores
show_rrf_breakdownbooleanShow RRF fusion details

Response Schema (PlaygroundSearchResponse - Status 200):

PropertyTypeRequiredDescription
querystring*Query that was tested
total_latency_msnumber*Total execution time
method_resultsobject*Results grouped by search method
fused_resultsanyRRF-fused results from all methods
rrf_breakdownanyRRF score breakdown by chunk_id per method
gapsarray of objectIdentified gaps (low scores, missing coverage)
request_idstring*Unique request ID for tracing
credits_usedanyCredits consumed by this request
credits_remaininganyRemaining 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"
\}

On this page