List contexts
Retrieves all contexts for the current project.
GET /api/contexts
Query parameters
| Parameter | Type | Description |
|---|---|---|
projectId | string | Filter by project ID |
parentId | string | Filter by parent context ID |
Response
[
{
"id": "ctx_abc123",
"name": "Architecture",
"description": "Tech stack and patterns",
"schemaKey": "root/architecture",
"parentContextId": null,
"state": "approved",
"tier": 1,
"contextType": "memory",
"createdAt": "2025-01-15T10:30:00Z",
"updatedAt": "2025-01-20T14:00:00Z"
}
]
Create context
Creates a new context.
POST /api/contexts
Request body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Context name |
description | string | No | Brief description |
content | string | No | Markdown content |
parentContextId | string | No | Parent context ID for hierarchy |
schemaKey | string | No | Unique schema key (e.g., "root/api/auth") |
tier | number | No | Priority tier (1 = always loaded, 2 = on demand, 3 = archive) |
contextType | string | No | "system", "reference", or "memory" |
Example
curl -X POST https://contox.dev/api/contexts \
-H "Authorization: Bearer contox_sk_yourkey" \
-H "Content-Type: application/json" \
-d '{
"name": "Authentication",
"description": "Auth patterns and decisions",
"content": "# Auth\nUsing JWT with refresh tokens.",
"schemaKey": "root/architecture/auth",
"tier": 1
}'
Get context
Retrieves a single context by ID.
GET /api/contexts/[id]
Response
Returns the full context object including content.
Update context
Updates a context's properties or content.
PATCH /api/contexts/[id]
Request body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | No | New name |
description | string | No | New description |
content | string | No | New content (replaces existing) |
Delete context
Permanently deletes a context.
DELETE /api/contexts/[id]
Returns 204 No Content on success.
Approve context
Changes the state of a context to approved or deprecated.
POST /api/contexts/[id]/approve
Request body
| Field | Type | Required | Description |
|---|---|---|---|
action | string | Yes | "approve" or "deprecate" |
Approved contexts are included in the brain document. Deprecated contexts are hidden from the brain but not deleted.
Example
curl -X POST https://contox.dev/api/contexts/ctx_abc123/approve \
-H "Authorization: Bearer contox_sk_yourkey" \
-H "Content-Type: application/json" \
-d '{"action": "approve"}'
Compact context
Summarizes all entries in a journal-like context into a single content block. This reduces token count while preserving key information.
POST /api/contexts/[id]/compact
Response
{
"id": "ctx_abc123",
"entriesBefore": 47,
"entriesAfter": 1,
"tokensSaved": 3200
}
Use compaction when a context accumulates too many entries and becomes unwieldy.
Get context tree
Returns the hierarchical tree of all contexts for a project.
GET /api/contexts/tree
Query parameters
| Parameter | Type | Description |
|---|---|---|
projectId | string | The project ID |
Response
[
{
"id": "ctx_root",
"name": "Project Memory",
"schemaKey": "root",
"children": [
{
"id": "ctx_arch",
"name": "Architecture",
"schemaKey": "root/architecture",
"children": []
},
{
"id": "ctx_bugs",
"name": "Bugs",
"schemaKey": "root/bugs",
"children": []
}
]
}
]
Populate contexts
Batch creates or updates multiple contexts using schema keys. This is the primary method used by the codebase scanner and CLI to push structured context data.
POST /api/contexts/populate
Request body
| Field | Type | Required | Description |
|---|---|---|---|
nodes | array | Yes | Array of context node objects |
source | string | No | Source identifier (e.g., "cli-scan") |
dryRun | boolean | No | If true, only return diff without writing |
Each node in the nodes array:
| Field | Type | Required | Description |
|---|---|---|---|
schemaKey | string | Yes | Unique schema key |
name | string | Yes | Display name |
description | string | No | Brief description |
content | string | No | Markdown content |
parentSchemaKey | string | No | Parent schema key for hierarchy |
contextType | string | No | "system", "reference", or "memory" |
tier | number | No | Priority tier (1-3) |
Example
curl -X POST https://contox.dev/api/contexts/populate \
-H "Authorization: Bearer contox_sk_yourkey" \
-H "Content-Type: application/json" \
-d '{
"source": "cli-scan",
"nodes": [
{
"schemaKey": "root/scan/routes",
"name": "Routes",
"content": "## API Routes\n- GET /api/users\n- POST /api/auth/login",
"parentSchemaKey": "root/scan"
}
]
}'