Overview
Sessions represent a unit of work in Contox. Events from the MCP server, CLI, and VS Code extension are grouped into sessions. Each session can be enriched to extract structured memory items from the raw event data.
List sessions
Retrieves all sessions for a project.
GET /api/v2/sessions
Query parameters
| Parameter | Type | Description |
|---|---|---|
projectId | string | Filter by project ID |
status | string | Filter by status (active, completed, enriching, failed) |
Response
[
{
"id": "sess_abc123",
"projectId": "proj_xyz789",
"status": "completed",
"eventCount": 12,
"createdAt": "2025-01-20T10:00:00Z",
"completedAt": "2025-01-20T12:30:00Z"
}
]
Create session
Manually creates a new session. Typically sessions are created automatically when events are ingested.
POST /api/v2/sessions
Request body
| Field | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | The project ID |
Get session
Retrieves a single session with full details.
GET /api/v2/sessions/[id]
Response
{
"id": "sess_abc123",
"projectId": "proj_xyz789",
"status": "completed",
"eventCount": 12,
"itemsExtracted": 8,
"enrichmentModel": "medium",
"createdAt": "2025-01-20T10:00:00Z",
"completedAt": "2025-01-20T12:30:00Z"
}
Update session
Updates session properties.
PATCH /api/v2/sessions/[id]
Request body
| Field | Type | Required | Description |
|---|---|---|---|
status | string | No | New status |
Trigger enrichment
Starts the AI enrichment pipeline for a session. This is the "Generate Memory" action in the dashboard.
POST /api/v2/sessions/[id]/enrich
The enrichment pipeline processes the session's events through multiple stages:
- Enrich -- AI extracts memory items from event chunks
- Embed -- Items are embedded for semantic search
- Dedup -- Duplicate items are detected and merged
- Drift check -- Existing items are checked for consistency
Response
{
"jobId": "job_abc123",
"status": "queued",
"pipeline": ["enrich", "embed", "dedup", "drift_check"]
}
AI model selection
The AI model used for enrichment depends on your plan:
| Plan | Model |
|---|---|
| Free / Personal | Small (faster, lower cost) |
| Team / Business / Enterprise | Medium (more accurate, higher cost) |
Retry failed enrichment
Retries a failed enrichment job for a session.
POST /api/v2/sessions/[id]/retry
Response
{
"jobId": "job_def456",
"status": "queued",
"retriedFrom": "job_abc123"
}
Use this when enrichment fails due to transient errors. The pipeline restarts from the failed stage.
List session events
Retrieves all raw events associated with a session.
GET /api/v2/sessions/[id]/events
Response
[
{
"id": "evt_abc123",
"event": "session_save",
"payload": {
"summary": "Implemented auth middleware",
"changes": [...]
},
"createdAt": "2025-01-20T10:15:00Z"
}
]
List session jobs
Retrieves the enrichment jobs for a session, showing pipeline progress.
GET /api/v2/sessions/[id]/jobs
Response
[
{
"id": "job_abc123",
"status": "completed",
"pipeline": [
{ "stage": "enrich", "status": "completed", "duration": 4500 },
{ "stage": "embed", "status": "completed", "duration": 1200 },
{ "stage": "dedup", "status": "completed", "duration": 800 },
{ "stage": "drift_check", "status": "completed", "duration": 600 }
],
"itemsExtracted": 8,
"createdAt": "2025-01-20T12:00:00Z",
"completedAt": "2025-01-20T12:02:00Z"
}
]
Pipeline stages
| Stage | Description |
|---|---|
enrich | AI processes event chunks and extracts memory items |
embed | Generates embeddings for semantic search |
dedup | Detects and merges duplicate items |
drift_check | Validates consistency with existing brain |
Next steps
- Enrichment Guide -- Understand the enrichment pipeline in depth
- V2 Items -- View extracted memory items
- V2 Pipeline Guide -- Full event flow from ingest to memory