Ingest

The Ingest endpoints handle document uploads and status polling. Parsing runs asynchronously — upload returns a task_id immediately, which you then poll until ingestion completes.

Use an official SDK if you can — the Python and JavaScript SDKs wrap the direct-upload flow into a single client.ingest.file(...) / client.ingest.batch(...) call that works for any file size. The endpoint-level details below are only needed if you’re calling the REST API directly.

Upload a Document

The default upload flow streams your file bytes straight from your client to Polyvia’s storage backend, then asks our API to register and parse it. This is a three-step flow that works for any file size — there is no practical upper limit.

Step 1 — Get an upload URL

POST /api/v1/ingest/upload-url No request body.

string

required

Short-lived signed URL for the storage backend. Expires in ~1 hour and is single-use.

{ "upload_url": "https://<your-deployment>.convex.cloud/api/storage/upload?token=..." }

Step 2 — PUT the file to that URL

Stream the raw file bytes to the returned upload_url. Set Content-Type to the file’s MIME type.

Do not include your Polyvia Authorization: Bearer poly_<key> header on this request. The URL is already signed, and forwarding the key to a different origin would leak it unnecessarily.

Storage responds with the new object’s identifier:

{ "storageId": "kg2abc...", "size": 12345678 }

Step 3 — Finalize the upload

POST /api/v1/ingest/finalize application/json

string

required

The storageId returned by storage in Step 2.

string

required

MIME type of the uploaded file.

string

Display name. Defaults to “Untitled” if omitted.

string

Assign the document to a group on creation.

Response

string

required

Unique identifier for the uploaded document

string

required

Ingestion task identifier — use this to poll for status

string

Initial status: always pending

Example

# 1. Get a signed upload URL
UPLOAD_URL=$(curl -s -X POST https://app.polyvia.ai/api/v1/ingest/upload-url \
  -H "Authorization: Bearer poly_<your-key>" | jq -r '.upload_url')

# 2. PUT the file bytes directly to storage (no auth header!)
STORAGE_ID=$(curl -s -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf | jq -r '.storageId')

# 3. Finalize — register the document and queue parsing
curl -X POST https://app.polyvia.ai/api/v1/ingest/finalize \
  -H "Authorization: Bearer poly_<your-key>" \
  -H "Content-Type: application/json" \
  -d "{\"storage_id\": \"$STORAGE_ID\", \"file_type\": \"application/pdf\", \"name\": \"Q4 Report\", \"group_id\": \"g_...\"}"

import httpx

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

# 1. Get an upload URL
upload_url = httpx.post(
    f"{BASE}/api/v1/ingest/upload-url", headers=HEADERS
).json()["upload_url"]

# 2. PUT the file directly to storage (no auth header here!)
with open("report.pdf", "rb") as f:
    storage_id = httpx.put(
        upload_url,
        content=f.read(),
        headers={"Content-Type": "application/pdf"},
        timeout=300,
    ).json()["storageId"]

# 3. Finalize
resp = httpx.post(
    f"{BASE}/api/v1/ingest/finalize",
    headers=HEADERS,
    json={
        "storage_id": storage_id,
        "file_type":  "application/pdf",
        "name":       "Q4 Report",
        "group_id":   "g_...",
    },
).json()
# {"document_id": "...", "task_id": "...", "status": "pending"}

from polyvia import Polyvia

client = Polyvia(api_key="poly_...")

# The SDK runs the three-step direct-upload flow internally.
result = client.ingest.file("report.pdf", name="Q4 Report", group_id="g_...")
client.ingest.wait(result.task_id)

{
  "document_id": "k57abc123...",
  "task_id":     "3f2e1d0c-...",
  "status":      "pending"
}

Upload Multiple Documents

For batches, run the direct-upload flow once per file. The official SDKs do this in client.ingest.batch(...) — each file is uploaded and finalized independently, so a failure on one file is isolated to that entry instead of failing the whole batch.

from polyvia import Polyvia

client = Polyvia(api_key="poly_...")

batch = client.ingest.batch(
    ["q3.pdf", "q4.pdf"],
    names=["Q3 Report", "Q4 Report"],
    group_id="g_...",
)
for item in batch.results:
    if item.error:
        print(f"failed: {item.file}: {item.error}")
    else:
        client.ingest.wait(item.task_id)

import { Polyvia } from "polyvia";

const client = new Polyvia({ apiKey: "poly_..." });

const items = await client.ingest.batch(["q3.pdf", "q4.pdf"], {
  names: ["Q3 Report", "Q4 Report"],
  groupId: "g_...",
});
for (const item of items) {
  if (item.error) {
    console.error(`failed: ${item.error}`);
  } else if (item.task_id) {
    await client.ingest.wait(item.task_id);
  }
}

Quick Multipart Upload (small files)

These multipart endpoints proxy file bytes through the API server, which has a 4.5 MB total request-body limit. They exist as a one-call convenience for small uploads. For any file size, prefer the direct-upload flow above (or use an SDK, which does it for you).

`POST /api/v1/ingest`

multipart/form-data

file

required

The document to upload. See Supported File Formats below.

string

Display name in your workspace. Defaults to the filename.

string

Assign the document to a group on upload.

Returns the same {document_id, task_id, status} shape as /finalize.

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 2024 Report" \
  -F "group_id=g_..."

`POST /api/v1/ingest/batch`

multipart/form-data. Same fields as /ingest but files is repeated per file and names is a comma-separated string aligned to files. Returns {results: [...], errors: [...] | null}.

curl -X POST https://app.polyvia.ai/api/v1/ingest/batch \
  -H "Authorization: Bearer poly_<your-key>" \
  -F "files=@q3.pdf" \
  -F "files=@q4.pdf" \
  -F "names=Q3 Report,Q4 Report" \
  -F "group_id=g_..."

Check Ingestion Status

Poll a parse task started by either upload flow.

Endpoint

GET /api/v1/ingest/{task_id}

Path Parameters

string

required

The task identifier returned by /ingest/finalize (or the legacy multipart endpoints)

Response

string

Task identifier

string

Document identifier

string

Processing status (see table below)

string | null

Error message if status is failed, otherwise null

`status` value	Meaning
`pending`	Queued, not yet started
`parsing`	Being parsed and indexed
`completed`	Ready to query
`failed`	Parsing failed; see `error` field

Example

cURL

curl https://app.polyvia.ai/api/v1/ingest/3f2e1d0c-... \
  -H "Authorization: Bearer poly_<your-key>"

while true; do
  STATUS=$(curl -s \
    -H "Authorization: Bearer poly_<your-key>" \
    "https://app.polyvia.ai/api/v1/ingest/3f2e1d0c-..." \
    | jq -r '.status')
  echo "Status: $STATUS"
  [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ] && break
  sleep 5
done

from polyvia import Polyvia

client = Polyvia(api_key="poly_...")

# Blocks until done — raises IngestionError on failure
done = client.ingest.wait(task_id, poll_interval=5, timeout=300)

{
  "task_id":     "3f2e1d0c-...",
  "document_id": "k57abc123...",
  "status":      "completed",
  "error":       null
}

Supported File Formats

Category	Extensions
Documents	`.pdf`, `.docx`, `.pptx`
Text	`.txt`, `.md` (Markdown)
Images	`.png`, `.jpg` / `.jpeg`, `.webp`, `.gif`
Audio	`.wav`, `.mp3`, `.m4a`

See Supported Formats for parser-by-parser details on what gets extracted from each file type.

Documents are typically processed within 1–2 minutes. Audio files take longer — roughly real-time playback for transcription. Poll the status endpoint every few seconds to check progress.

Get Started

Products

API Reference

Releases

Upload a Document

Step 1 — Get an upload URL

Step 2 — PUT the file to that URL

Step 3 — Finalize the upload

Response

Example

Upload Multiple Documents

Quick Multipart Upload (small files)

`POST /api/v1/ingest`

`POST /api/v1/ingest/batch`

Check Ingestion Status

Endpoint

Path Parameters

Response

Example

Supported File Formats

​Upload a Document

​Step 1 — Get an upload URL

​Step 2 — PUT the file to that URL

​Step 3 — Finalize the upload

​Response

​Example

​Upload Multiple Documents

​Quick Multipart Upload (small files)

​POST /api/v1/ingest

​POST /api/v1/ingest/batch

​Check Ingestion Status

​Endpoint

​Path Parameters

​Response

​Example

​Supported File Formats

Upload a Document

Step 1 — Get an upload URL

Step 2 — PUT the file to that URL

Step 3 — Finalize the upload

Response

Example

Upload Multiple Documents

Quick Multipart Upload (small files)

`POST /api/v1/ingest`

`POST /api/v1/ingest/batch`

Check Ingestion Status

Endpoint

Path Parameters

Response

Example

Supported File Formats