Query

The Query endpoint lets you ask questions about your documents using natural language. Scope the query to a single document, a group (or multiple groups), or leave it unscoped to search your entire workspace.

Query Documents

Endpoint

POST /api/v1/query

Scoping behaviour

Parameters provided	Scope
(none)	All completed documents in your workspace
`document_id`	That document only (fastest)
`group_id`	All completed documents in that group
`group_ids`	All completed documents across those groups

Request Body

application/json

string

required

Your natural-language question

string

Restrict the query to a single document.

string

Restrict the query to documents in a specific group. Cannot be combined with document_id or group_ids.

string[]

Restrict the query to documents across multiple groups. Cannot be combined with document_id or group_id.

Response

string

The answer to your question

string

The document used to answer (present only for single-document queries)

Examples

curl -X POST https://app.polyvia.ai/api/v1/query \
  -H "Authorization: Bearer poly_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{"query": "What risks are mentioned across all reports?"}'

curl -X POST https://app.polyvia.ai/api/v1/query \
  -H "Authorization: Bearer poly_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "query":       "What is the executive summary?",
    "document_id": "k57abc123..."
  }'

curl -X POST https://app.polyvia.ai/api/v1/query \
  -H "Authorization: Bearer poly_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "query":    "What are the key findings?",
    "group_id": "g_finance"
  }'

curl -X POST https://app.polyvia.ai/api/v1/query \
  -H "Authorization: Bearer poly_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "query":     "Compare the Q3 and Q4 results.",
    "group_ids": ["g_q3", "g_q4"]
  }'

from polyvia import Polyvia

client = Polyvia(api_key="poly_...")

# All documents
answer = client.query("What risks are mentioned across all reports?")

# Single document (fastest)
answer = client.query("Summarise section 3.", document_id="doc_...")

# Group
answer = client.query("Key findings?", group_id="g_finance")

# Multiple groups
answer = client.query("Compare Q3 vs Q4.", group_ids=["g_q3", "g_q4"])

print(answer.answer)

{
  "answer":      "The gross margin improved by 4 pp year-over-year, driven by...",
  "document_id": "k57abc123..."
}

Documents must have status=completed before they can be queried. Use the Check Ingestion Status endpoint to confirm a document is ready.

Get Started

Products

API Reference

Releases

Query Documents

Endpoint

Scoping behaviour

Request Body

Response

Examples

​Query Documents

​Endpoint

​Scoping behaviour

​Request Body

​Response

​Examples

Query Documents

Endpoint

Scoping behaviour

Request Body

Response

Examples