---
title: "Context Documents API reference"
canonical_url: https://zentrik.ai/docs/api/context-documents
markdown_url: https://zentrik.ai/docs/api/context-documents.md
last_reviewed: 2026-09-03
---

# Context Documents API reference

Context documents are workspace knowledge files used by retrieval and product context surfaces. Use these endpoints to import text, upload files, scope documents to products, and inspect previewable content.

- Human reference: https://zentrik.ai/docs/api/context-documents
- Complete Markdown index: https://zentrik.ai/docs/api/index.md
- Base URL: `https://zentrik.ai/api`
- Authentication: `Authorization: Bearer YOUR_API_KEY`
- Shared pagination and rate limits: https://zentrik.ai/docs/api/index.md#shared-conventions

## GET /external/v1/context-documents — List all context documents

Operation ID: `list-context-documents`

List context documents in the current workspace. Raw storage keys are never returned.

Required API key scopes: `context-documents:read`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | number | No | Maximum number of documents to return. |
| `offset` | number | No | Number of documents to skip. |

### Example request

```curl
curl -X GET 'https://zentrik.ai/api/external/v1/context-documents?limit=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | Context documents were successfully retrieved. | Array<ContextDocument> |

### Example response

```json
[
  {
    "id": "context-document-uuid",
    "fileName": "activation-research.md",
    "mimeType": "text/markdown",
    "size": 1834,
    "description": "Research notes for activation planning.",
    "productId": "product-uuid",
    "workspaceId": "workspace-uuid",
    "vectorFileId": "file-vector-id",
    "indexingStatus": "indexed",
    "createdAt": "2026-05-14T10:00:00Z",
    "updatedAt": "2026-05-14T10:00:00Z"
  }
]
```

---

## GET /external/v1/context-documents/:id — Get one context document

Operation ID: `get-context-document`

Retrieve metadata for one context document in the current workspace.

Required API key scopes: `context-documents:read`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid | Yes | The context document UUID. |

### Example request

```curl
curl -X GET https://zentrik.ai/api/external/v1/context-documents/context-document-uuid \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | The context document was successfully retrieved. | ContextDocument |
| 404 | Not Found | No context document found with the provided id. | — |

### Example response

```json
{
  "id": "context-document-uuid",
  "fileName": "activation-research.md",
  "mimeType": "text/markdown",
  "size": 1834,
  "description": "Research notes for activation planning.",
  "productId": "product-uuid",
  "workspaceId": "workspace-uuid",
  "vectorFileId": "file-vector-id",
  "indexingStatus": "indexed",
  "createdAt": "2026-05-14T10:00:00Z",
  "updatedAt": "2026-05-14T10:00:00Z"
}
```

---

## GET /external/v1/context-documents/:id/content — Preview context document content

Operation ID: `get-context-document-content`

Preview text-like context document content. Large content is truncated to the documented limit.

Required API key scopes: `context-documents:read`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid | Yes | The context document UUID. |

### Example request

```curl
curl -X GET https://zentrik.ai/api/external/v1/context-documents/context-document-uuid/content \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | The preview payload was returned. | — |

### Example response

```json
{
  "supported": true,
  "content": "# Activation research",
  "contentFormat": "markdown",
  "truncated": false,
  "maxChars": 40000,
  "sourceUrl": null,
  "sourceLabel": null
}
```

---

## POST /external/v1/context-documents — Import a text context document

Operation ID: `create-context-document`

Import a text or markdown context document from JSON. The document is stored and indexed for retrieval.

Required API key scopes: `context-documents:write`

### JSON request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `fileName` | string | Yes | Display file name, including extension. |
| `content` | string | Yes | Text content to store and index. |
| `mimeType` | string | No | Defaults to text/markdown. |
| `productId` | uuid \| null | No | Optional product scope. Omit or null for global workspace context. |
| `description` | string \| null | No | Human-readable context note. |

### Example request

```json
{
  "fileName": "activation-research.md",
  "content": "# Activation research\n\nTeams need clearer setup progress.",
  "mimeType": "text/markdown",
  "productId": "product-uuid",
  "description": "Research notes for activation planning."
}
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 201 | Created | The context document was stored and queued for retrieval indexing. | ContextDocument |

### Example response

```json
{
  "id": "context-document-uuid",
  "fileName": "activation-research.md",
  "mimeType": "text/markdown",
  "size": 1834,
  "description": "Research notes for activation planning.",
  "productId": "product-uuid",
  "workspaceId": "workspace-uuid",
  "vectorFileId": "file-vector-id",
  "indexingStatus": "indexed",
  "createdAt": "2026-05-14T10:00:00Z",
  "updatedAt": "2026-05-14T10:00:00Z"
}
```

---

## POST /external/v1/context-documents/upload — Upload a context document file

Operation ID: `upload-context-document`

Upload a binary or text file as multipart/form-data. The file field name must be file.

Required API key scopes: `context-documents:write`

### JSON request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `file` | file | Yes | The file to upload. Maximum size is 50 MB. |
| `productId` | uuid \| null | No | Optional product scope. |
| `description` | string \| null | No | Human-readable context note. |

### Example request

```curl
curl -X POST https://zentrik.ai/api/external/v1/context-documents/upload \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'file=@activation-research.md' \
  -F 'productId=product-uuid'
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 201 | Created | The context document file was uploaded. | ContextDocument |

### Example response

```json
{
  "id": "context-document-uuid",
  "fileName": "activation-research.md",
  "mimeType": "text/markdown",
  "size": 1834,
  "description": "Research notes for activation planning.",
  "productId": "product-uuid",
  "workspaceId": "workspace-uuid",
  "vectorFileId": "file-vector-id",
  "indexingStatus": "indexed",
  "createdAt": "2026-05-14T10:00:00Z",
  "updatedAt": "2026-05-14T10:00:00Z"
}
```

---

## PATCH /external/v1/context-documents/:id — Update a context document

Operation ID: `update-context-document`

Update document metadata. Changing productId re-indexes the document with the new retrieval scope.

Required API key scopes: `context-documents:write`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid | Yes | The context document UUID. |

### JSON request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `fileName` | string | No | Updated display file name. |
| `description` | string \| null | No | Updated context note. |
| `productId` | uuid \| null | No | Replacement product scope. Null makes the document global. |

### Example request

```curl
curl -X PATCH https://zentrik.ai/api/external/v1/context-documents/context-document-uuid \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"productId":null}'
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Updated | The context document was successfully updated. | ContextDocument |

---

## DELETE /external/v1/context-documents/:id — Delete a context document

Operation ID: `delete-context-document`

Delete a context document, its stored file, and its retrieval index entry when present.

Required API key scopes: `context-documents:delete`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid | Yes | The context document UUID. |

### Example request

```curl
curl -X DELETE https://zentrik.ai/api/external/v1/context-documents/context-document-uuid \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Deleted | The context document was successfully deleted. | — |