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

# Context Units API reference

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.

- Human reference: https://zentrik.ai/docs/api/context-units
- 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-units — List all context units

Operation ID: `list-context-units`

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

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

### Parameters

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

### Example request

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

### Responses

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

### Example response

```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 /external/v1/context-units/:id — Get one context unit

Operation ID: `get-context-unit`

Retrieve one context unit from the current workspace.

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

### Parameters

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

### Example request

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

### Responses

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

### Example response

```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 /external/v1/context-units — Create a context unit

Operation ID: `create-context-unit`

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

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

### JSON request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Short title for the context unit. |
| `description` | string | No | Human-readable summary. |
| `data` | string | Yes | Full Markdown context body. |
| `productId` | uuid \| null | No | Optional product scope. Omit or null for global workspace context. |

### Example request

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

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 201 | Created | The context unit was stored and indexed. | ContextUnit |

### Example response

```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 /external/v1/context-units/:id — Update a context unit

Operation ID: `update-context-unit`

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

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

### Parameters

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

### JSON request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | No | Updated title. |
| `description` | string | No | Updated summary. |
| `data` | string | No | Updated Markdown context body. |
| `productId` | uuid \| null | No | Replacement product scope. Null makes the unit global. |

### Example request

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

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Updated | The context unit was successfully updated. | ContextUnit |

---

## DELETE /external/v1/context-units/:id — Delete a context unit

Operation ID: `delete-context-unit`

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

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

### Parameters

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

### Example request

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

### Responses

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