Documents

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

string

Filter by status: uploading, parsing, completed, failed

string

Filter to documents in a specific group.

string

Comma-separated list of group IDs. Returns documents belonging to any of the specified groups. Cannot be combined with group_id.

Response

array

Array of document objects

Show Document object

string

Document identifier

string

Document display name

string

Processing status: uploading, parsing, completed, failed

string

MIME type of the uploaded file

string

AI-generated summary of the document

integer

Unix timestamp (milliseconds) of when the document was uploaded

string | null

Group identifier if the document belongs to a group, otherwise null

Examples

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

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

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

from polyvia import Polyvia

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

# Filter by status and group
docs = client.documents.list(status="completed", group_id="g_...")

# Filter across multiple groups
docs = client.documents.list(group_ids=["g_abc", "g_def"])

{
  "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

string

required

The document identifier

Response

string

Document identifier

string

Document display name

string

Processing status: uploading, parsing, completed, failed

string

MIME type of the uploaded file

string

Signed URL to download the original file

string

AI-generated summary of the document

integer

Unix timestamp (milliseconds) of upload

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

string

required

The document identifier

Request Body

application/json

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"}'

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": null}'

from polyvia import Polyvia

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

client.documents.update("k57abc123...", group_id="g_finance")  # move
client.documents.update("k57abc123...", group_id=None)         # remove from group

{ "ok": true }

Delete Document

Permanently delete a document and all its indexed content.

Endpoint

DELETE /api/v1/documents/{document_id}

Path Parameters

string

required

The document identifier

Example

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

client.documents.delete("k57abc123...")

{ "ok": true }

Deletion is permanent and cannot be undone. All indexed content for the document is removed immediately.

Get Started

Products

API Reference

Releases

List Documents

Endpoint

Query Parameters

Response

Examples

Get Document

Endpoint

Path Parameters

Response

Example

Update Document

Endpoint

Path Parameters

Request Body

Example

Delete Document

Endpoint

Path Parameters

Example

​List Documents

​Endpoint

​Query Parameters

​Response

​Examples

​Get Document

​Endpoint

​Path Parameters

​Response

​Example

​Update Document

​Endpoint

​Path Parameters

​Request Body

​Example

​Delete Document

​Endpoint

​Path Parameters

​Example

List Documents

Endpoint

Query Parameters

Response

Examples

Get Document

Endpoint

Path Parameters

Response

Example

Update Document

Endpoint

Path Parameters

Request Body

Example

Delete Document

Endpoint

Path Parameters

Example