Skip to main content
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.

​
Upload Document

Upload a single file for parsing and indexing.

​
Endpoint

POST /api/v1/ingest

​
Request Body

multipart/form-data
​
file
file
required
The document to upload. Supported formats: PDF, DOCX, PPTX, XLSX, TXT, MD, and more.
​
name
string
Display name in your workspace. Defaults to the filename if omitted.
​
group_id
string
Assign the document to a group on upload.

​
Response

​
document_id
string
required
Unique identifier for the uploaded document
​
task_id
string
required
Ingestion task identifier — use this to poll for status
​
status
string
Initial status: always pending

​
Example

cURL
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_..."

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

​
Upload Multiple Documents

Upload several files in a single request. Each file is queued as an independent ingestion task.

​
Endpoint

POST /api/v1/ingest/batch

​
Request Body

multipart/form-data
​
files
file[]
required
One or more files to upload (repeat the files field for each file).
​
names
string[]
Display names for each file in the same order as files. If omitted, filenames are used.
​
group_id
string
Assign all uploaded documents to this group.

​
Response

​
results
array
One entry per file, in the same order as files.

​
Example

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

{
  "results": [
    { "document_id": "k57abc...", "task_id": "3f2e...", "status": "pending", "error": null },
    { "document_id": "k57def...", "task_id": "4a1b...", "status": "pending", "error": null }
  ]
}

​
Check Ingestion Status

Poll a parse task started by either upload endpoint.

​
Endpoint

GET /api/v1/ingest/{task_id}

​
Path Parameters

​
task_id
string
required
The task identifier returned by POST /api/v1/ingest or POST /api/v1/ingest/batch

​
Response

​
task_id
string
Task identifier
​
document_id
string
Document identifier
​
status
string
Processing status (see table below)
​
error
string | null
Error message if status is failed, otherwise null
status valueMeaning
pendingQueued, not yet started
parsingBeing parsed and indexed
completedReady to query
failedParsing 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

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

​
Supported File Formats

PDF, DOCX, PPTX, XLSX, TXT, MD, and other common document formats.
Documents are typically processed within 1–2 minutes. Poll the status endpoint every few seconds to check progress.