Missions

Missions orchestrate multi-agent task execution: a LEAD agent plans a breakdown, agents work tasks, and the mission moves through a status flow from PLANNING to a terminal state. Beyond CRUD, the API exposes lifecycle actions — start, restart, resume, and clone — plus task management, mission checkpoints, and workspace-wide metrics.

All mission endpoints require authentication and workspace context.

Endpoints

Method	Endpoint	Purpose
`GET`	`/api/v1/missions`	List all missions in a workspace
`GET`	`/api/v1/crews/{crewId}/missions`	List a crew’s missions
`POST`	`/api/v1/crews/{crewId}/missions`	Create a mission
`GET`	`/api/v1/crews/{crewId}/missions/{missionId}`	Get a mission with tasks
`PATCH`	`/api/v1/crews/{crewId}/missions/{missionId}`	Update a mission
`DELETE`	`/api/v1/crews/{crewId}/missions/{missionId}`	Delete a mission
`POST`	`/api/v1/crews/{crewId}/missions/{missionId}/start`	Start a mission
`POST`	`/api/v1/crews/{crewId}/missions/{missionId}/restart`	Restart a terminal mission
`POST`	`/api/v1/crews/{crewId}/missions/{missionId}/resume`	Resume a failed mission
`POST`	`/api/v1/crews/{crewId}/missions/{missionId}/clone`	Clone a mission
`POST`	`/api/v1/crews/{crewId}/missions/{missionId}/tasks`	Add a task
`PATCH`	`/api/v1/crews/{crewId}/missions/{missionId}/tasks/{taskId}`	Update a task
`GET`	`/api/v1/missions/{missionId}/checkpoints`	List mission checkpoints
`POST`	`/api/v1/missions/{missionId}/checkpoints`	Create a mission checkpoint
`GET`	`/api/v1/mission-metrics`	Aggregated mission metrics

Create, read, update, and delete missions. Write operations require OWNER, ADMIN, or MANAGER role.

List All Missions (Workspace)

GET /api/v1/missions?workspace_id={workspaceId}

List all missions across the workspace. Query Parameters:

Parameter	Type	Default	Description
`workspace_id`	string	Required	Workspace ID
`status`	string	—	Filter by status (e.g., `IN_PROGRESS`)
`include_tasks`	string	`"false"`	Set to `"true"` to include task details
`q`	string	—	Search in title or identifier (LIKE match), on the server
`limit`	integer	`20`	Rows per page (1-200; each row can carry its task list)
`offset`	integer	`0`	Pagination offset

The body stays a bare array. The total the filter matched — before limit/offset — is in the X-Total-Count response header, with X-Limit and X-Offset echoing the values applied. Response: 200 OK

[
  {
    "id": "mission_abc",
    "workspace_id": "ws_123",
    "crew_id": "crew_456",
    "lead_agent_id": "agent_789",
    "lead_agent_name": "Tech Lead",
    "lead_agent_slug": "tech-lead",
    "trace_id": "mission-cm1abc123",
    "title": "Implement user authentication",
    "description": "Add JWT-based auth with refresh tokens",
    "status": "IN_PROGRESS",
    "plan": "1. Create auth middleware\n2. Add login endpoint...",
    "workflow_template": null,
    "total_token_count": 15000,
    "total_estimated_cost": 0.45,
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T11:00:00Z",
    "completed_at": null,
    "task_stats": {
      "total": 4,
      "pending": 1,
      "blocked": 0,
      "in_progress": 1,
      "completed": 2,
      "failed": 0,
      "skipped": 0,
      "awaiting_approval": 0
    }
  }
]

The tasks array is only included when include_tasks=true; it is omitted from the default list response.

List Crew Missions

GET /api/v1/crews/{crewId}/missions?workspace_id={workspaceId}

Query Parameters:

Parameter	Type	Default	Description
`status`	string	—	Filter by status
`q`	string	—	Search title and identifier on the server (substring match)
`limit`	integer	`20`	Max items (1-100)
`offset`	integer	`0`	Pagination offset

Response: 200 OK — array of mission objects with task_stats. The same X-Total-Count, X-Limit and X-Offset headers as the workspace list, so a crew-scoped page knows how many rows the crew has.

Create Mission

POST /api/v1/crews/{crewId}/missions?workspace_id={workspaceId}

Auth: OWNER, ADMIN, or MANAGER role Request Body:

Field	Type	Required	Description
`title`	string	Yes	Mission title
`description`	string	No	Mission description
`lead_agent_id`	string	Yes	ID of the LEAD agent in the crew
`workflow_template`	string	No	Workflow template ID to use

{
  "title": "Implement user authentication",
  "description": "Add JWT-based auth with refresh tokens",
  "lead_agent_id": "agent_789"
}

The lead agent must exist in the specified crew and have the LEAD role. Response: 201 Created — mission object with status PLANNING.

Status	Condition
`400`	Missing title, missing/invalid lead_agent_id, agent not LEAD role
`403`	Insufficient role

WebSocket events: mission.created on crew:{crewId}, mission.updated on workspace:{workspaceId}

Get Mission

GET /api/v1/crews/{crewId}/missions/{missionId}?workspace_id={workspaceId}

Returns the mission with all tasks and task stats. Response: 200 OK

{
  "id": "mission_abc",
  "title": "Implement user authentication",
  "status": "IN_PROGRESS",
  "tasks": [
    {
      "id": "task_001",
      "mission_id": "mission_abc",
      "assigned_agent_id": "agent_dev1",
      "agent_name": "Backend Dev",
      "agent_slug": "backend-dev",
      "title": "Create auth middleware",
      "description": "Implement JWT validation middleware",
      "status": "COMPLETED",
      "task_order": 1,
      "depends_on": "[]",
      "iteration": 1,
      "max_iterations": 3,
      "result_summary": "Created middleware with token validation",
      "output_path": "/workspace/internal/auth/middleware.go",
      "error_message": null,
      "assignment_id": "assign_abc",
      "token_count": 5000,
      "estimated_cost": 0.15,
      "started_at": "2024-01-15T10:05:00Z",
      "completed_at": "2024-01-15T10:15:00Z",
      "duration_ms": 600000,
      "confidence": 0.95,
      "needs_review": false,
      "handoff_context": null,
      "evaluation_status": "PASS",
      "evaluation_notes": null,
      "approval_required": false,
      "approval_status": null,
      "approved_by": null,
      "approved_at": null,
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T10:15:00Z"
    }
  ],
  "task_stats": { ... }
}

Status	Condition
`404`	Mission not found

Update Mission

PATCH /api/v1/crews/{crewId}/missions/{missionId}?workspace_id={workspaceId}

Auth: OWNER, ADMIN, or MANAGER role Request Body: All fields optional.

Field	Type	Description
`title`	string	Mission title
`description`	string	Mission description
`plan`	string	Mission plan (markdown)
`status`	string	New status (must be a valid transition)

Status Transitions:

From	Allowed To
`PLANNING`	`IN_PROGRESS`, `CANCELLED`
`IN_PROGRESS`	`REVIEW`, `FAILED`, `CANCELLED`
`REVIEW`	`DONE`, `IN_PROGRESS`, `FAILED`, `CANCELLED`

When status changes to DONE, FAILED, or CANCELLED, completed_at is automatically set.

Before this release, a mission approved out of REVIEW moved to COMPLETED while an issue approved the same way moved to DONE — two words for the identical operator action, sharing one column (missions.status). COMPLETED is now retired: this endpoint writes DONE for both. For backward compatibility, {"status":"COMPLETED"} is still accepted and silently normalized to DONE — it is never written or returned again. Any script or dashboard still matching the literal string COMPLETED on a mission’s status field should switch to DONE.

Response: 200 OK — updated mission object.

Status	Condition
`400`	Invalid status transition
`404`	Mission not found

Delete Mission

DELETE /api/v1/crews/{crewId}/missions/{missionId}?workspace_id={workspaceId}

Only missions in PLANNING or CANCELLED status can be deleted (hard delete).

Request: crewId and missionId are required path parameters; workspace_id selects the workspace. No request body. Auth: OWNER, ADMIN, or MANAGER role Response: 204 No Content

Status	Condition
`400`	Mission is not in PLANNING or CANCELLED status
`404`	Mission not found

Lifecycle Actions

Drive a mission through execution: start a planned mission, or restart, resume, and clone existing ones. All require OWNER, ADMIN, or MANAGER role.

Start Mission

POST /api/v1/crews/{crewId}/missions/{missionId}/start?workspace_id={workspaceId}

Transitions a PLANNING mission to IN_PROGRESS and starts the MissionEngine. Validates the task dependency DAG before starting. Uses atomic compare-and-swap to prevent concurrent start races. Auth: OWNER, ADMIN, or MANAGER role Response: 200 OK

{
  "id": "mission_abc",
  "status": "IN_PROGRESS"
}

Status	Condition
`400`	Mission not in PLANNING state, or invalid task DAG
`403`	Mission was created under an autonomy hold and the hold is undecided or denied. Body: `{"error": "Mission start rejected by policy", "reason", "mission_id", "remedy"}` — an OWNER/ADMIN approves the `autonomy_gate` row (`crewship approvals approve <id>`) and the start is retried. Same helper as the internal start route, so a held mission cannot be started from either.
`404`	Mission not found
`409`	Mission was already started by another request
`500`	MissionEngine failed to start (rolls back to PLANNING)

Restart Mission

POST /api/v1/crews/{crewId}/missions/{missionId}/restart?workspace_id={workspaceId}

Restarts a DONE, FAILED, or CANCELLED mission. Resets non-COMPLETED tasks (PENDING if dependencies allow, BLOCKED otherwise), increments their iteration, clears errors, and moves the mission back to PLANNING (call start afterwards to dispatch). (internal/api/task_state.go:14) Request: crewId and missionId are required path parameters; workspace_id selects the workspace. No request body. Auth: OWNER, ADMIN, or MANAGER role Response: 200 OK

{ "id": "mission_abc", "status": "PLANNING" }

Status	Condition
`404`	Mission not found
`409`	Mission is not in a terminal state (`DONE`/`FAILED`/`CANCELLED`)

Resume Mission

POST /api/v1/crews/{crewId}/missions/{missionId}/resume?workspace_id={workspaceId}

Resumes a FAILED mission from the point of failure. The handler atomically claims the mission into RESUMING, resets the FAILED/AWAITING_APPROVAL tasks plus their downstream dependents, validates the DAG, and re-engages the MissionEngine. COMPLETED tasks are preserved. (internal/api/task_state.go:103) Request: crewId and missionId are required path parameters; workspace_id selects the workspace. No request body. Auth: OWNER, ADMIN, or MANAGER role Response: 200 OK

Status	Condition
`400`	No failed tasks to resume from, or invalid DAG
`404`	Mission not found
`409`	Mission is not currently `FAILED`

Clone Mission

POST /api/v1/crews/{crewId}/missions/{missionId}/clone?workspace_id={workspaceId}

Creates a copy of the mission with all its tasks, resetting statuses to PLANNING/PENDING (or BLOCKED if the cloned task carries dependencies). Request: crewId and missionId are required path parameters; workspace_id selects the workspace. No request body. Auth: OWNER, ADMIN, or MANAGER role Response: 201 Created

{ "id": "mission_new", "status": "PLANNING" }

The handler returns the new mission id and status only; fetch GET /api/v1/crews/{crewId}/missions/{newId} for the full mission object (internal/api/task_state.go:472).

Tasks

Add and update the individual tasks that make up a mission’s work breakdown.

Create Task

POST /api/v1/crews/{crewId}/missions/{missionId}/tasks?workspace_id={workspaceId}

Add a task to a mission. Auth: OWNER, ADMIN, or MANAGER role Request Body: (internal/api/task_handler.go:42)

Field	Type	Required	Default	Description
`title`	string	Yes	—	Task title
`description`	string	No	`null`	Task description
`assigned_agent_id`	string	No	`null`	Agent to assign to
`task_order`	integer	No	`0`	Position in task list
`depends_on`	string[]	No	`[]`	Array of task IDs this depends on
`max_iterations`	integer	No	`null`	Max retry iterations

Tasks can only be added to missions in PLANNING or IN_PROGRESS state. If any dependency task is not COMPLETED, the new task is created with status BLOCKED; otherwise PENDING. Response: 201 Created

Update Task

PATCH /api/v1/crews/{crewId}/missions/{missionId}/tasks/{taskId}?workspace_id={workspaceId}

Auth: Authenticated workspace caller with the mission write permission (OWNER, ADMIN, or MANAGER). Request: crewId, missionId, and taskId path parameters, optional workspace_id, and a JSON body containing any of the optional fields below. Response: the updated task object. Statuses: 200 OK; 400 for an invalid transition or body, 403 for insufficient role, 404 when the mission or task is not in the workspace, and 500 for a persistence failure. Request Body: All fields optional. (internal/api/task_handler.go:160 — updateTaskRequest)

Field	Type	Description
`title`	string	Task title (PENDING/BLOCKED only)
`description`	string	Task description (PENDING/BLOCKED only)
`assigned_agent_id`	string	Reassign to a different agent
`status`	string	New status (valid transition required)
`depends_on`	string	JSON-encoded dependency task IDs (PENDING/BLOCKED only)
`result_summary`	string	Result summary text
`error_message`	string	Error message text
`output_path`	string	Output file path
`token_count`	integer	Token usage
`estimated_cost`	number	Estimated cost in USD
`max_iterations`	integer	Max retry iterations (0–`maxTaskIterations`)

status and depends_on cannot be set in the same request — the handler returns 400 with “Cannot update status and depends_on in the same request” (internal/api/task_handler.go:382). task_order and approval_required are not currently mutable through this endpoint. Task Status Transitions:

From	Allowed To
`PENDING`	`IN_PROGRESS`, `SKIPPED`
`BLOCKED`	`PENDING`, `SKIPPED`
`IN_PROGRESS`	`COMPLETED`, `FAILED`, `SKIPPED`

Response: 200 OK

Checkpoints

Cartographer checkpoints bookmark a mission’s journal cursor and state snapshot for the timeline UI. Cartographer checkpoints capture a mission’s journal cursor plus a state snapshot (agent-memory hashes, pending tasks, open assignments, crew container id) so the timeline UI can offer “list bookmarks” and (advisory) “restore/fork from here” affordances. The full restore/fork/get/delete surface is documented on the Checkpoints page; the two endpoints below are mission-scoped and live here for convenience. (internal/api/cartographer_handler.go)

List Mission Checkpoints

GET /api/v1/missions/{missionId}/checkpoints?limit=50

Returns newest-first checkpoints for a mission. Cross-workspace IDs are folded into the same 404 shape as “mission not found” so existence isn’t leaked. Query Parameters:

Parameter	Type	Default	Description
`limit`	integer	`50`	1-200. Values outside the range fall back to the default.

Response: 200 OK

{
  "mission_id": "mission_abc",
  "count": 1,
  "checkpoints": [
    {
      "id": "chk_01h9z7k0",
      "workspace_id": "ws_123",
      "crew_id": "crew_456",
      "mission_id": "mission_abc",
      "label": "green build",
      "journal_cursor": "j_7f3e2a1b8c9d0e12",
      "state": {
        "agent_memory": { "backend-dev": "sha256:…" },
        "pending_tasks": ["task_1"],
        "open_assignments": [],
        "crew_container_id": "crew_456-runner"
      },
      "created_by": "user_5",
      "created_at": "2026-05-14T09:12:44Z"
    }
  ]
}

Status	Condition
`400`	Missing `missionId` path value
`401`	No workspace context on the request
`404`	Mission not in caller’s workspace

Create Mission Checkpoint

POST /api/v1/missions/{missionId}/checkpoints

Captures the mission’s current journal cursor + materialized state and writes a checkpoint row. Body is optional — an unlabelled checkpoint is a valid “bookmark right now” gesture. (internal/api/cartographer_handler.go:91) Request Body: (optional)

Field	Type	Required	Description
`label`	string	No	Human-readable label for the timeline UI

{ "label": "green build" }

Response: 201 Created — full checkpoint object (same shape as the List array entries above). When the row was committed but the immediate re-read failed, the response degrades to { "id": "chk_..." } so the client can still navigate to it.

Status	Condition
`400`	Missing `missionId`, or invalid JSON body
`401`	No workspace context on the request
`404`	Mission not in caller’s workspace
`409`	Mission has no journal entries to anchor a checkpoint against

Metrics

Workspace-wide aggregates for dashboards.

Mission Metrics

GET /api/v1/mission-metrics?workspace_id={workspaceId}

Auth: Authenticated workspace request. Request: required workspace_id query parameter; no body. Response: JSON aggregate metrics object. Statuses: 200 OK; 400 for missing or invalid workspace context, 401 when unauthenticated, and 500 for an aggregation failure. Aggregated mission metrics for the workspace. total_missions and active_missions are lifetime counts; the *_24h fields cover the trailing 24 hours. total_tokens_24h and total_cost_24h are mission totals: they sum the tokens and estimated cost of mission tasks completed in the window, and nothing else. Spend that happens outside a mission — chats, ad-hoc agent runs, routine runs — is not counted here, so a workspace can report 0 on both while it is genuinely spending money. That spend lives in the cost ledger, which the paymaster endpoints report (and crewship cost prints). A 0 here means “no mission task was recorded in the window”, not “no spend”. Response: 200 OK

{
  "total_missions": 45,
  "active_missions": 3,
  "completed_24h": 8,
  "failed_24h": 1,
  "total_tokens_24h": 125000,
  "total_cost_24h": 3.75,
  "avg_completion_time_ms": 180000,
  "tasks_completed_24h": 24,
  "tasks_failed_24h": 2
}

Reference

Mission Statuses

Status	Description
`PLANNING`	Lead is analyzing and creating task breakdown
`IN_PROGRESS`	Agents are working on tasks
`REVIEW`	All tasks done, lead is reviewing results
`DONE`	Successfully finished and approved (formerly `COMPLETED` — still accepted as `PATCH` input, normalized)
`FAILED`	Unresolvable problem encountered
`CANCELLED`	Cancelled by user or system

Task Statuses

Status	Description
`PENDING`	Not yet started, waiting for dependencies
`BLOCKED`	Blocked by unfinished dependency tasks
`IN_PROGRESS`	Agent is currently working on it
`COMPLETED`	Successfully finished
`FAILED`	Agent failed the task
`SKIPPED`	Manually skipped
`AWAITING_APPROVAL`	Waiting for human approval

​Endpoints

​Missions

​List All Missions (Workspace)

​List Crew Missions

​Create Mission

​Get Mission

​Update Mission

​Delete Mission

​Lifecycle Actions

​Start Mission

​Restart Mission

​Resume Mission

​Clone Mission

​Tasks

​Create Task

​Update Task

​Checkpoints

​List Mission Checkpoints

​Create Mission Checkpoint

​Metrics

​Mission Metrics

​Reference

​Mission Statuses

​Task Statuses

Endpoints

Missions

List All Missions (Workspace)

List Crew Missions

Create Mission

Get Mission

Update Mission

Delete Mission

Lifecycle Actions

Start Mission

Restart Mission

Resume Mission

Clone Mission

Tasks

Create Task

Update Task

Checkpoints

List Mission Checkpoints

Create Mission Checkpoint

Metrics

Mission Metrics

Reference

Mission Statuses

Task Statuses