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

# Documents

> List, retrieve, update, and delete documents in your workspace

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

<ParamField query="status" type="string">
  Filter by status: `uploading`, `parsing`, `completed`, `failed`
</ParamField>

<ParamField query="group_id" type="string">
  Filter to documents in a specific group.
</ParamField>

<ParamField query="group_ids" type="string">
  Comma-separated list of group IDs. Returns documents belonging to any of the specified groups.
  Cannot be combined with `group_id`.
</ParamField>

### Response

<ResponseField name="documents" type="array">
  Array of document objects

  <Expandable title="Document object">
    <ResponseField name="id" type="string">
      Document identifier
    </ResponseField>

    <ResponseField name="title" type="string">
      Document display name
    </ResponseField>

    <ResponseField name="status" type="string">
      Processing status: `uploading`, `parsing`, `completed`, `failed`
    </ResponseField>

    <ResponseField name="file_type" type="string">
      MIME type of the uploaded file
    </ResponseField>

    <ResponseField name="summary" type="string">
      AI-generated summary of the document
    </ResponseField>

    <ResponseField name="created_at" type="integer">
      Unix timestamp (milliseconds) of when the document was uploaded
    </ResponseField>

    <ResponseField name="group_id" type="string | null">
      Group identifier if the document belongs to a group, otherwise `null`
    </ResponseField>
  </Expandable>
</ResponseField>

### Examples

<CodeGroup>
  ```bash All completed documents theme={null}
  curl "https://app.polyvia.ai/api/v1/documents?status=completed" \
    -H "Authorization: Bearer poly_<your-key>"
  ```

  ```bash Filter by group theme={null}
  curl "https://app.polyvia.ai/api/v1/documents?group_id=g_..." \
    -H "Authorization: Bearer poly_<your-key>"
  ```

  ```bash Filter by multiple groups theme={null}
  curl "https://app.polyvia.ai/api/v1/documents?group_ids=g_abc,g_def" \
    -H "Authorization: Bearer poly_<your-key>"
  ```

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

<ResponseExample>
  ```json Success theme={null}
  {
    "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"
      }
    ]
  }
  ```
</ResponseExample>

***

## Get Document

Fetch metadata for a single document.

### Endpoint

`GET /api/v1/documents/{document_id}`

### Path Parameters

<ParamField path="document_id" type="string" required>
  The document identifier
</ParamField>

### Response

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

### Example

```bash cURL theme={null}
curl "https://app.polyvia.ai/api/v1/documents/k57abc123..." \
  -H "Authorization: Bearer poly_<your-key>"
```

<ResponseExample>
  ```json Success theme={null}
  {
    "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"
  }
  ```
</ResponseExample>

***

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

<ParamField path="document_id" type="string" required>
  The document identifier
</ParamField>

### Request Body

`application/json`

<ParamField body="group_id" type="string | null" required>
  The group to assign the document to, or `null` to remove it from any group.
</ParamField>

### Example

<CodeGroup>
  ```bash Move to a group theme={null}
  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"}'
  ```

  ```bash Remove from group theme={null}
  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}'
  ```

  ```python Python SDK theme={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
  ```
</CodeGroup>

<ResponseExample>
  ```json Success theme={null}
  { "ok": true }
  ```
</ResponseExample>

***

## Delete Document

Permanently delete a document and all its indexed content.

### Endpoint

`DELETE /api/v1/documents/{document_id}`

### Path Parameters

<ParamField path="document_id" type="string" required>
  The document identifier
</ParamField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://app.polyvia.ai/api/v1/documents/k57abc123..." \
    -H "Authorization: Bearer poly_<your-key>"
  ```

  ```python Python SDK theme={null}
  client.documents.delete("k57abc123...")
  ```
</CodeGroup>

<ResponseExample>
  ```json Success theme={null}
  { "ok": true }
  ```
</ResponseExample>

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