Skip to documentation

Context Documents

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.

7 endpoints

GET

List all context documents

GET /external/v1/context-documents

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

Requirements

API scopes required:
context-documents:read

Request

Parameters

NameTypeDescription
limit numberMaximum number of documents to return.
offset numberNumber of documents to skip.

Responses

200
Success

Context documents were successfully retrieved.

Schema
Array<ContextDocument>

Example Request

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

Example Response

200 OK
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

Get one context document

GET /external/v1/context-documents/:id

Retrieve metadata for one context document in the current workspace.

Requirements

API scopes required:
context-documents:read

Request

Parameters

NameTypeDescription
id *uuidThe context document UUID.

Responses

200
Success

The context document was successfully retrieved.

Schema
ContextDocument
404
Not Found

No context document found with the provided id.

Example Request

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

Example Response

200 OK
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

Preview context document content

GET /external/v1/context-documents/:id/content

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

Requirements

API scopes required:
context-documents:read

Request

Parameters

NameTypeDescription
id *uuidThe context document UUID.

Responses

200
Success

The preview payload was returned.

Example Request

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

Example Response

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

Import a text context document

POST /external/v1/context-documents

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

Requirements

API scopes required:
context-documents:write

Request

Request body (application/json)

fileNamestring
Required

Display file name, including extension.

contentstring
Required

Text content to store and index.

mimeTypestring

Defaults to text/markdown.

productIduuid | null

Optional product scope. Omit or null for global workspace context.

descriptionstring | null

Human-readable context note.

Responses

201
Created

The context document was stored and queued for retrieval indexing.

Schema
ContextDocument

Example Request

POST
/external/v1/context-documents
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."
}

Example Response

201 Created
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

Upload a context document file

POST /external/v1/context-documents/upload

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

Requirements

API scopes required:
context-documents:write

Request

Request body (application/json)

filefile
Required

The file to upload. Maximum size is 50 MB.

productIduuid | null

Optional product scope.

descriptionstring | null

Human-readable context note.

Responses

201
Created

The context document file was uploaded.

Schema
ContextDocument

Example Request

POST
/external/v1/context-documents/upload
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'

Example Response

201 Created
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

Update a context document

PATCH /external/v1/context-documents/:id

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

Requirements

API scopes required:
context-documents:write

Request

Parameters

NameTypeDescription
id *uuidThe context document UUID.

Request body (application/json)

fileNamestring

Updated display file name.

descriptionstring | null

Updated context note.

productIduuid | null

Replacement product scope. Null makes the document global.

Responses

200
Updated

The context document was successfully updated.

Schema
ContextDocument

Example Request

PATCH
/external/v1/context-documents/:id
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}'
DELETE

Delete a context document

DELETE /external/v1/context-documents/:id

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

Requirements

API scopes required:
context-documents:delete

Request

Parameters

NameTypeDescription
id *uuidThe context document UUID.

Responses

200
Deleted

The context document was successfully deleted.

Example Request

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

Data Models

Context document responses expose retrieval status and safe metadata, not storage keys.

ContextDocument Object

FieldTypeDescription
iduuidThe unique identifier for the context document.
fileNamestringDisplay file name.
mimeTypestring | nullStored MIME type.
sizenumber | nullStored byte size.
descriptionstring | nullHuman-readable note.
productIduuid | nullProduct retrieval scope, or null for global workspace context.
workspaceIduuidWorkspace that owns the context document.
vectorFileIdstring | nullRetrieval provider file id when indexing has completed.
indexingStatusenumindexed when retrieval indexing is available, pending otherwise.
createdAtiso-dateTimestamp when the document was created.
updatedAtiso-dateTimestamp of the latest metadata update.
Create a workspaceAsk supportDocumentation