Skip to main content
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 providedScope
(none)All completed documents in your workspace
document_idThat document only (fastest)
group_idAll completed documents in that group
group_idsAll completed documents across those groups

​
Request Body

application/json
​
query
string
required
Your natural-language question
​
document_id
string
Restrict the query to a single document.
​
group_id
string
Restrict the query to documents in a specific group. Cannot be combined with document_id or group_ids.
​
group_ids
string[]
Restrict the query to documents across multiple groups. Cannot be combined with document_id or group_id.

​
Response

​
answer
string
The answer to your question
​
document_id
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?"}'

{
  "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.