Skip to main content
Welcome to the Polyvia API documentation. Our API enables you to upload documents, organise them into groups, ask natural-language questions across your workspace, and monitor usage.
The Python SDK (pip install polyvia) wraps every endpoint with a typed client and adds first-class support for the MCP server and agent frameworks.

​
Authentication

All API requests require authentication using an API key. Include your key in the Authorization header: 
Authorization: Bearer poly_<your-key>
Keep your API key secure. Never expose it in client-side code or public repositories.

​
Getting Your API Key

  1. Sign in to Polyvia
  2. Go to Settings → API
  3. Click Create API Key, give it a name, and optionally set an expiry date
  4. Copy the key — it is shown only once
All keys start with poly_. To revoke a key, return to Settings → API and click the delete icon next to it.

​
Workspace Scoping

Each API key is bound to one workspace at the moment you create it — either your personal workspace or a specific organization. Every request made with that key reads and writes only that workspace’s data; the key cannot reach across workspaces.
  • Mint a key while you’re in your personal workspace → it sees personal documents, groups, and chats only.
  • Mint a key while you’re in an organization → it sees that org’s shared documents and groups. Any teammate’s API key minted in the same org reads the same data.
To work across multiple workspaces from the same script, switch workspace in Settings → API and create a separate key for each. Use the appropriate key per request.
Switching your active workspace in the UI later does not change what an existing key can access. The binding is permanent — revoke and re-mint to change scope.

​
Base URL

https://app.polyvia.ai
All endpoints are prefixed with /api/v1.

​
Quick Start

Here’s a complete example: ingest a document and query for insights. 
import httpx
import time

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

# 1. Upload
with open("report.pdf", "rb") as f:
    resp = httpx.post(
        f"{BASE}/api/v1/ingest",
        headers=HEADERS,
        files={"file": ("report.pdf", f, "application/pdf")},
        data={"name": "Q4 Report"},
    )
resp.raise_for_status()
task_id     = resp.json()["task_id"]
document_id = resp.json()["document_id"]

# 2. Poll until ingestion completes
while True:
    status = httpx.get(f"{BASE}/api/v1/ingest/{task_id}", headers=HEADERS).json()["status"]
    print(f"Status: {status}")
    if status in ("completed", "failed"):
        break
    time.sleep(5)

# 3. Query
answer = httpx.post(
    f"{BASE}/api/v1/query",
    headers=HEADERS,
    json={"query": "What are the key findings?", "document_id": document_id},
).json()["answer"]

print(answer)

​
Support

Need help? Reach out to our team: