Checkpoints - Crewship

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

Path parameters:

Param	Description
`missionId`	Mission ID. Must belong to caller’s workspace.

Query parameters:

Param	Type	Default	Description
`limit`	integer	50	1-200.

Response: 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

Request body (optional):

{ "label": "green build" }

Field	Type	Required	Description
`label`	string	No	Human-readable label. Body may be empty.

Response: 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}

Path parameters: id is the checkpoint ID. The request has no body. Response: 200 OK — full checkpoint object. Errors: 401 without an authenticated workspace; 404 on a missing or cross-tenant checkpoint; 500 on a database read failure.

Restore (advisory)

POST /api/v1/checkpoints/{id}/restore

Path parameters: id is the checkpoint ID. The request has no body. Returns the checkpoint plus the list of journal entries that have diverged since it was made. No mission state is mutated. Response: 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: 401 without an authenticated workspace; 404 on a missing or cross-tenant checkpoint; 500 on a database read failure.

Fork

POST /api/v1/checkpoints/{id}/fork

Creates a new mission anchored at the checkpoint’s cursor, plus a matching fresh checkpoint in the new mission with fork_of = <source checkpoint id>. Request body (optional):

{ "label": "experiment-1" }

Auth: Authenticated user required (the checkpoint’s created_by is stamped with the caller’s user ID). Response: 201 Created

{
  "new_mission_id": "MIS-43",
  "new_checkpoint_id": "chk_new0001"
}

Errors: 401 if no user; 404 on missing or cross-tenant.

Delete

DELETE /api/v1/checkpoints/{id}

Path parameters: id is the checkpoint ID. The request has no body. Response: 204 No Content. Errors: 401 without an authenticated workspace; 404 on a missing or cross-tenant checkpoint; 500 on a database delete failure.

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)

​Endpoints

​Mission checkpoints

​List checkpoints

​Create checkpoint

​Inspect, restore, and fork

​Get checkpoint

​Restore (advisory)

​Fork

​Delete

​Journal side-effects

​Related

Endpoints

Mission checkpoints

List checkpoints

Create checkpoint

Inspect, restore, and fork

Get checkpoint

Restore (advisory)

Fork

Delete

Journal side-effects

Related