Skip to main content
The Query endpoint provides visual search and reasoning capabilities across your indexed documents. Get answers with audit-ready citations pointing to exact sources.

​
Search Knowledge Base

Perform visual search and reasoning across your entire knowledge base.

​
Endpoint

POST /query

​
Request Body

​
query
string
required
Natural language query
​
include_citations
boolean
default:"true"
Include source citations in the response
​
limit
integer
default:"10"
Maximum number of source chunks to consider (1-50)
​
filters
object
Filter results by document metadata
​
mode
string
default:"reasoning"
Query mode: search (return matching chunks) or reasoning (synthesized answer)

​
Response

​
answer
string
Synthesized answer to the query (when mode is reasoning)
​
citations
array
Source citations for the answer
​
query_time_ms
integer
Query execution time in milliseconds

​
Example

curl -X POST https://api.polyvia.ai/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is the difference between Apple and Microsoft Q4 2024 revenue?",
    "include_citations": true,
    "mode": "reasoning"
  }'

{
  "answer": "Apple's Q4 2024 revenue was $119.58B while Microsoft's Q4 2024 revenue was $62.02B. The difference is $57.56B, with Apple generating approximately 93% more revenue than Microsoft in this quarter.",
  "citations": [
    {
      "document_id": "doc_apple_10k",
      "document_name": "Apple 10-K 2024",
      "page": 24,
      "content": "Total net revenue: $119,575 million",
      "visual_type": "table",
      "confidence": 0.97
    },
    {
      "document_id": "doc_msft_10k",
      "document_name": "Microsoft 10-K 2024",
      "page": 31,
      "content": "Revenue: $62,020 million",
      "visual_type": "chart",
      "confidence": 0.95
    }
  ],
  "query_time_ms": 342
}

​
Search Mode

For simple retrieval without synthesized answers, use mode: "search".

​
Example

{
  "query": "revenue charts",
  "mode": "search",
  "limit": 5
}

​
Response

{
  "results": [
    {
      "document_id": "doc_abc123",
      "document_name": "Q4 Financial Report",
      "page": 12,
      "content": "Q4 Revenue by Region chart showing...",
      "visual_type": "chart",
      "score": 0.94
    }
  ],
  "query_time_ms": 127
}

​
Filtering

​
Filter by Documents

Query only specific documents: 
{
  "query": "What were the key findings?",
  "filters": {
    "document_ids": ["doc_abc123", "doc_def456"]
  }
}

​
Filter by Tags

Query documents with specific tags: 
{
  "query": "quarterly revenue trends",
  "filters": {
    "tags": ["finance", "quarterly"]
  }
}

​
Filter by Date

Query documents from a specific time period: 
{
  "query": "security incidents",
  "filters": {
    "date_range": {
      "start": "2024-01-01",
      "end": "2024-12-31"
    }
  }
}

​
Cross-Document Reasoning

Polyvia automatically reasons across multiple documents to answer complex queries. For example: Query: “Compare the revenue growth of Apple, Microsoft, and Google over the last 3 years” Polyvia will:
  1. Search for revenue data across all relevant documents
  2. Extract facts from charts, tables, and text
  3. Synthesize a comparative answer with citations from each source
For best results with cross-document queries, ensure your documents are properly tagged with metadata like company names, time periods, and document types.

​
Visual Citation Types

Polyvia identifies the type of visual source for each citation:
TypeDescription
chartBar charts, line graphs, pie charts
tableData tables, spreadsheet content
diagramFlow charts, org charts, architecture diagrams
infographicComplex visual compositions
textRegular text content
This helps you understand where each piece of information originated.