> ## 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.

# Polyvia API

> Multimodal Document Retrieval API — for developers of AI agents

**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

<CardGroup cols={3}>
  <Card title="/api/v1/ingest" icon="file-arrow-up">
    Upload single or multiple documents and poll ingestion status
  </Card>

  <Card title="/api/v1/documents" icon="folder-open">
    List, update, and delete documents in your workspace
  </Card>

  <Card title="/api/v1/groups" icon="layer-group">
    Create and manage document groups
  </Card>

  <Card title="/api/v1/query" icon="magnifying-glass">
    Ask natural-language questions — workspace-wide, by group, or per document
  </Card>

  <Card title="/api/v1/usage" icon="chart-bar">
    Monitor request and document counts for the current period
  </Card>

  <Card title="/api/v1/rate-limits" icon="gauge">
    Check your plan limits and remaining capacity
  </Card>
</CardGroup>

## 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.

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```ts TypeScript theme={null}
  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);
  ```
</CodeGroup>

## Or use the REST API directly

The same workflow over raw HTTP — no SDK required.

### 1. Create a Group

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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

<CardGroup cols={2}>
  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Full endpoint documentation with all parameters
  </Card>

  <Card title="Python SDK" icon="python" href="/products/python-sdk">
    Typed Python SDK with MCP and agent-tools support
  </Card>

  <Card title="JS / TS SDK" icon="js" href="/products/js-sdk">
    Typed TypeScript SDK for Node.js and modern JS frameworks
  </Card>

  <Card title="Polyvia MCP Server" icon="plug" href="/products/mcp">
    Connect Polyvia to Claude Desktop and other AI tools
  </Card>

  <Card title="Polyvia Platform" icon="browser" href="/products/platform">
    Upload and manage documents in the web UI
  </Card>
</CardGroup>