Context Units

Context units are curated Markdown guidance that agents and product workflows reuse across a workspace. Use these endpoints for text-based rules, decisions, constraints, and product-scoped guidance.

5 endpoints

GET

List all context units

GET /external/v1/context-units

List context units in the current workspace. Responses include the full Markdown body.

Requirements

API scopes required:

context-units:read

Request

Parameters

Name	Type	Description
limit	number	Maximum number of context units to return.
offset	number	Number of context units to skip.

Responses

200

Success

Context units were successfully retrieved.

Schema

Array<ContextUnit>

Example Request

GET

/external/v1/context-units

curl

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

Example Response

200 OK

json

[
  {
    "id": "context-unit-uuid",
    "name": "Engineering principles",
    "description": "Reusable engineering guidance for product delivery.",
    "data": "## Principles\n\n- Prefer focused changes\n- Validate workspace relationships",
    "productId": null,
    "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 unit

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

Retrieve one context unit from the current workspace.

Requirements

API scopes required:

context-units:read

Request

Parameters

Name	Type	Description
id *	uuid	The context unit UUID.

Responses

200

Success

The context unit was successfully retrieved.

Schema

ContextUnit

404

Not Found

No context unit found with the provided id.

Example Request

GET

/external/v1/context-units/:id

curl

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

Example Response

200 OK

json

{
  "id": "context-unit-uuid",
  "name": "Engineering principles",
  "description": "Reusable engineering guidance for product delivery.",
  "data": "## Principles\n\n- Prefer focused changes\n- Validate workspace relationships",
  "productId": null,
  "workspaceId": "workspace-uuid",
  "vectorFileId": "file-vector-id",
  "indexingStatus": "indexed",
  "createdAt": "2026-05-14T10:00:00Z",
  "updatedAt": "2026-05-14T10:00:00Z"
}

POST

Create a context unit

POST /external/v1/context-units

Create a native text context unit. The data field accepts Markdown and is indexed for retrieval.

Requirements

API scopes required:

context-units:write

Request

Request body (application/json)

namestring

Required

Short title for the context unit.

descriptionstring

Human-readable summary.

datastring

Required

Full Markdown context body.

productIduuid | null

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

Responses

201

Created

The context unit was stored and indexed.

Schema

ContextUnit

Example Request

POST

/external/v1/context-units

json

{
  "name": "Engineering principles",
  "description": "Reusable engineering guidance for product delivery.",
  "data": "## Principles\n\n- Prefer focused changes\n- Validate workspace relationships",
  "productId": null
}

Example Response

201 Created

json

{
  "id": "context-unit-uuid",
  "name": "Engineering principles",
  "description": "Reusable engineering guidance for product delivery.",
  "data": "## Principles\n\n- Prefer focused changes\n- Validate workspace relationships",
  "productId": null,
  "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 unit

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

Update context unit text or metadata. Any content or scope change reindexes the context unit.

Requirements

API scopes required:

context-units:write

Request

Parameters

Name	Type	Description
id *	uuid	The context unit UUID.

Request body (application/json)

namestring

Updated title.

descriptionstring

Updated summary.

datastring

Updated Markdown context body.

productIduuid | null

Replacement product scope. Null makes the unit global.

Responses

200

Updated

The context unit was successfully updated.

Schema

ContextUnit

Example Request

PATCH

/external/v1/context-units/:id

curl

curl -X PATCH https://zentrik.ai/api/external/v1/context-units/context-unit-uuid \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"data":"## Principles\n\n- Validate workspace relationships"}'

DELETE

Delete a context unit

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

Delete a context unit and its retrieval index entry when present.

Requirements

API scopes required:

context-units:delete

Request

Parameters

Name	Type	Description
id *	uuid	The context unit UUID.

Responses

200

Deleted

The context unit was successfully deleted.

Example Request

DELETE

/external/v1/context-units/:id

curl

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

Data Models

Context unit responses include the full Markdown body in data and retrieval indexing status.

ContextUnit Object

Field	Type	Description
id	uuid	The unique identifier for the context unit.
name	string	Short title for the reusable context.
description	string	Human-readable summary for when to use this context.
data	string	Full Markdown context body.
productId	uuid \| null	Product retrieval scope, or null for global workspace context.
workspaceId	uuid	Workspace that owns the context unit.
vectorFileId	string \| null	Retrieval provider file id when indexing has completed.
indexingStatus	enum	indexed when retrieval indexing is available, pending otherwise.
createdAt	iso-date	Timestamp when the context unit was created.
updatedAt	iso-date	Timestamp of the latest context unit update.