Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.polyvia.ai/llms.txt

Use this file to discover all available pages before exploring further.

The Polyvia API provides programmatic access to document ingestion, group management, natural-language querying, and workspace analytics. Build applications that upload documents, organise them into groups, and ask questions across your workspace.

​
Overview

/api/v1/ingest

Upload single or multiple documents and poll ingestion status

/api/v1/documents

List, update, and delete documents in your workspace

/api/v1/groups

Create and manage document groups

/api/v1/query

Ask natural-language questions — workspace-wide, by group, or per document

/api/v1/usage

Monitor request and document counts for the current period

/api/v1/rate-limits

Check your plan limits and remaining capacity

​
Quick Example

Here’s a complete workflow: ingest two documents into a group, wait for processing, then query across them.

​
1. Create a Group

import httpx

API_KEY = "poly_<your-key>"
BASE    = "https://app.polyvia.ai"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

group_id = httpx.post(
    f"{BASE}/api/v1/groups",
    headers=HEADERS,
    json={"name": "Finance"},
).json()["group_id"]

​
2. Ingest Documents

import time

with open("q3.pdf", "rb") as f:
    r1 = httpx.post(f"{BASE}/api/v1/ingest", headers=HEADERS,
                    files={"file": ("q3.pdf", f)},
                    data={"name": "Q3 Report", "group_id": group_id}).json()

with open("q4.pdf", "rb") as f:
    r2 = httpx.post(f"{BASE}/api/v1/ingest", headers=HEADERS,
                    files={"file": ("q4.pdf", f)},
                    data={"name": "Q4 Report", "group_id": group_id}).json()

# Wait for both
for task_id in [r1["task_id"], r2["task_id"]]:
    while True:
        status = httpx.get(f"{BASE}/api/v1/ingest/{task_id}", headers=HEADERS).json()["status"]
        if status in ("completed", "failed"):
            break
        time.sleep(5)

​
3. Query the Group

answer = httpx.post(
    f"{BASE}/api/v1/query",
    headers=HEADERS,
    json={"query": "Compare the key findings.", "group_id": group_id},
).json()["answer"]

print(answer)

​
Or use an SDK

The same workflow in a few lines with either official SDK: 
from polyvia import Polyvia

client = Polyvia(api_key="poly_<key>")

group_id = client.groups.create("Finance")["group_id"]

batch = client.ingest.batch(["q3.pdf", "q4.pdf"],
                             names=["Q3 Report", "Q4 Report"],
                             group_id=group_id)
for item in batch:
    client.ingest.wait(item.task_id)

print(client.query("Compare the key findings.", group_id=group_id).answer)

​
Next Steps

API Reference

Full endpoint documentation with all parameters

Python SDK

Typed Python SDK with MCP and agent-tools support

JS / TS SDK

Typed TypeScript SDK for Node.js and modern JS frameworks

Polyvia MCP Server

Connect Polyvia to Claude Desktop and other AI tools

Polyvia Studio

Upload and manage documents in the web UI