Overview

The Polyvia REST API lets you upload documents, organise them into groups, ask natural-language questions across your workspace, and monitor usage. This page covers authentication, the base URL, and workspace scoping; the pages that follow document each endpoint.

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>

How to get an API key

Create, use, and manage your key — and how workspace binding works.

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 and create a separate key for each (on the API page). 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)

# 1. Upload
curl -X POST https://app.polyvia.ai/api/v1/ingest \
  -H "Authorization: Bearer poly_<your-key>" \
  -F "file=@/path/to/report.pdf" \
  -F "name=Q4 Report"

# 2. Check status (replace TASK_ID)
curl https://app.polyvia.ai/api/v1/ingest/TASK_ID \
  -H "Authorization: Bearer poly_<your-key>"

# 3. Query
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?", "document_id": "DOCUMENT_ID"}'

Support

Need help? Reach out to our team:

Email: mgierlach5@gmail.com
Platform: Polyvia Platform

Get Started

Products

API Reference

Releases

Authentication

How to get an API key

Workspace Scoping

Base URL

Quick Start

Support

​Authentication

How to get an API key

​Workspace Scoping

​Base URL

​Quick Start

​Support

Authentication

Workspace Scoping

Base URL

Quick Start

Support