Skip to main content
The Documents endpoints let you list, fetch, update, and delete documents in your workspace.

​
List Documents

List documents in your workspace with optional filters.

​
Endpoint

GET /api/v1/documents

​
Query Parameters

​
status
string
Filter by status: uploading, parsing, completed, failed
​
group_id
string
Filter to documents in a specific group.
​
group_ids
string
Comma-separated list of group IDs. Returns documents belonging to any of the specified groups. Cannot be combined with group_id.

​
Response

​
documents
array
Array of document objects

​
Examples

curl "https://app.polyvia.ai/api/v1/documents?status=completed" \
  -H "Authorization: Bearer poly_<your-key>"

{
  "documents": [
    {
      "id":         "k57abc123...",
      "title":      "Q4 2024 Report",
      "status":     "completed",
      "file_type":  "application/pdf",
      "summary":    "This document covers Q4 financial results...",
      "created_at": 1712345678000,
      "group_id":   "g_finance"
    }
  ]
}

​
Get Document

Fetch metadata for a single document.

​
Endpoint

GET /api/v1/documents/{document_id}

​
Path Parameters

​
document_id
string
required
The document identifier

​
Response

​
id
string
Document identifier
​
title
string
Document display name
​
status
string
Processing status: uploading, parsing, completed, failed
​
file_type
string
MIME type of the uploaded file
​
file_url
string
Signed URL to download the original file
​
summary
string
AI-generated summary of the document
​
created_at
integer
Unix timestamp (milliseconds) of upload
​
group_id
string | null
Group identifier if the document belongs to a group

​
Example

cURL
curl "https://app.polyvia.ai/api/v1/documents/k57abc123..." \
  -H "Authorization: Bearer poly_<your-key>"

{
  "id":         "k57abc123...",
  "title":      "Q4 2024 Report",
  "status":     "completed",
  "file_type":  "application/pdf",
  "file_url":   "https://...",
  "summary":    "This document covers Q4 financial results...",
  "created_at": 1712345678000,
  "group_id":   "g_finance"
}

​
Update Document

Update a document’s group assignment. Pass null to remove it from its current group.

​
Endpoint

PATCH /api/v1/documents/{document_id}

​
Path Parameters

​
document_id
string
required
The document identifier

​
Request Body

application/json
​
group_id
string | null
required
The group to assign the document to, or null to remove it from any group.

​
Example

curl -X PATCH "https://app.polyvia.ai/api/v1/documents/k57abc123..." \
  -H "Authorization: Bearer poly_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{"group_id": "g_finance"}'

{ "ok": true }

​
Delete Document

Permanently delete a document and all its indexed content.

​
Endpoint

DELETE /api/v1/documents/{document_id}

​
Path Parameters

​
document_id
string
required
The document identifier

​
Example

curl -X DELETE "https://app.polyvia.ai/api/v1/documents/k57abc123..." \
  -H "Authorization: Bearer poly_<your-key>"

{ "ok": true }
Deletion is permanent and cannot be undone. All indexed content for the document is removed immediately.