Cartographer checkpoints capture a mission’s journal cursor and agent state so a run can be inspected, advisory-restored, or forked into a new mission. Restore is non-destructive — it reports divergence without mutating mission state — while Fork branches a fresh mission anchored at the checkpoint. See the Cartographer guide.
All endpoints require authentication and are workspace-scoped. Cross-tenant IDs return 404 (same shape as “not found”).
Endpoints
| Method | Endpoint | Purpose |
|---|
| GET | /api/v1/missions/{missionId}/checkpoints | List checkpoints for a mission |
| POST | /api/v1/missions/{missionId}/checkpoints | Create a checkpoint |
| GET | /api/v1/checkpoints/{id} | Get a single checkpoint |
| POST | /api/v1/checkpoints/{id}/restore | Advisory restore (reports divergence) |
| POST | /api/v1/checkpoints/{id}/fork | Fork into a new mission |
| DELETE | /api/v1/checkpoints/{id} | Delete a checkpoint |
Mission checkpoints
List and create checkpoints scoped to a mission’s journal.
List checkpoints
GET /api/v1/missions/{missionId}/checkpoints?limit=50
| Param | Description |
|---|
missionId | Mission ID. Must belong to caller’s workspace. |
| Param | Type | Default | Description |
|---|
limit | integer | 50 | 1-200. |
200 OK
{
"mission_id": "MIS-42",
"checkpoints": [
{
"id": "chk_a1b2c3d4e5f60718",
"workspace_id": "ws_123",
"crew_id": "crw_backend",
"mission_id": "MIS-42",
"label": "green build",
"journal_cursor": "j_7f3e2a1b8c9d0e12",
"state": {
"agent_memory": { "viktor": "9f86d081..." },
"pending_tasks": ["mt_001"],
"open_assignments": []
},
"created_by": "user_123",
"created_at": "2026-04-17T10:23:41Z"
}
],
"count": 1
}
fork_of is omitempty: it appears only on checkpoints created by Fork (carrying the source checkpoint id) and is dropped from the JSON entirely on independent checkpoints. crew_id, label, and state.crew_container_id/state.meta are likewise omitted when empty.
Errors:
| Status | Condition |
|---|
| 400 | Missing missionId. |
| 404 | Mission not in your workspace. |
Create checkpoint
POST /api/v1/missions/{missionId}/checkpoints
{ "label": "green build" }
| Field | Type | Required | Description |
|---|
label | string | No | Human-readable label. Body may be empty. |
201 Created — full checkpoint object.
Errors:
| Status | Condition |
|---|
| 400 | Invalid JSON body. |
| 404 | Mission not in your workspace. |
| 409 | Mission has no journal entries to anchor a checkpoint. |
Inspect, restore, and fork
Read a single checkpoint by ID, run an advisory restore that only reports drift, or branch a new mission from a checkpoint.
Get checkpoint
GET /api/v1/checkpoints/{id}
200 OK — full checkpoint object.
Errors: 404 on missing or cross-tenant.
Restore (advisory)
POST /api/v1/checkpoints/{id}/restore
200 OK
{
"checkpoint": { "id": "chk_...", "label": "green build", ... },
"journal_cursor": "j_7f3e2a1b8c9d0e12",
"warn_divergence": [
"mission.status_change at j_8a4f3b2c9d0e1234",
"exec.command at j_9b5f4c3d0e1f2345"
]
}
warn_divergence is always an array (empty when no drift). Callers should treat a long list as a signal to fork, not restore.
Errors: 404 on missing or cross-tenant.
Fork
POST /api/v1/checkpoints/{id}/fork
fork_of = <source checkpoint id>.
Request body (optional):
{ "label": "experiment-1" }
created_by is stamped with the caller’s user ID).
Response: 201 Created
{
"new_mission_id": "MIS-43",
"new_checkpoint_id": "chk_new0001"
}
401 if no user; 404 on missing or cross-tenant.
Delete
DELETE /api/v1/checkpoints/{id}
204 No Content.
Errors: 404 on missing or cross-tenant.
Forks that referenced the deleted checkpoint via fork_of are orphaned (their reference is set to NULL) — no cascade. The forked missions themselves are untouched.
Journal side-effects
| Operation | Entry |
|---|
| Create | checkpoint.created (info) |
| Restore | checkpoint.restored (info, payload includes divergence count) |
| Fork | fork.created (notice) |
