Polyvia API

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)

import { Polyvia } from "polyvia";

const client = new Polyvia({ apiKey: "poly_<key>" });

// Ingest a batch into a group, then ask one question across all of it.
const items = await client.ingest.batch(
  ["q1.pdf", "q2.pdf", "q3.pdf", "q4.pdf"],
  { group: "FY24 Earnings" },
);
await Promise.all(items.map((i) => client.ingest.wait(i.task_id)));

// Answers cite the exact page in each document.
const answer = await client.query(
  "How did revenue trend across the four quarters?",
  { group: "FY24 Earnings" },
);
console.log(answer.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

Get Started

Products

API Reference

Releases

Overview

/api/v1/ingest

/api/v1/documents

/api/v1/groups

/api/v1/query

/api/v1/usage

/api/v1/rate-limits

Quick Example

Or use the REST API directly

1. Create a Group

2. Ingest Documents

3. Query the Group

Next Steps

API Reference

Python SDK

JS / TS SDK

Polyvia MCP Server

Polyvia Platform

​Overview

/api/v1/ingest

/api/v1/documents

/api/v1/groups

/api/v1/query

/api/v1/usage

/api/v1/rate-limits

​Quick Example

​Or use the REST API directly

​1. Create a Group

​2. Ingest Documents

​3. Query the Group

​Next Steps

API Reference

Python SDK

JS / TS SDK

Polyvia MCP Server

Polyvia Platform

Overview

Quick Example

Or use the REST API directly

1. Create a Group

2. Ingest Documents

3. Query the Group

Next Steps