Polyvia API - Polyvia

Polyvia API is the Multimodal Document Retrieval API — for developers of AI agents. It gives you programmatic access to document ingestion, group management, natural-language querying, and workspace analytics — multimodal retrieval as a tool, so your agents can reason over 100K+ visual & multimodal docs where file-by-file agentic search stalls. Build applications that upload documents, organise them into groups, and ask questions across your workspace, with every answer grounded in a cited source page.

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 a batch into a group, wait for processing, then query across all of it. The quickest path is an official SDK.

from polyvia import Polyvia

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

# Ingest a batch into a group, then ask one question across all of it.
items = client.ingest.batch(
    ["q1.pdf", "q2.pdf", "q3.pdf", "q4.pdf"],
    group="FY24 Earnings",
)
for item in items:
    client.ingest.wait(item.task_id)

# Answers cite the exact page in each document.
print(client.query("How did revenue trend across the four quarters?",
                   group="FY24 Earnings").answer)

Or use the REST API directly

The same workflow over raw HTTP — no SDK required.

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={"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={"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)

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 Platform

Upload and manage documents in the web UI

​Overview