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
`limit`	integer	`20`	Max items (1-100)
`offset`	integer	`0`	Pagination offset

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
`limit`	integer	`20`	Max items (1-100)
`offset`	integer	`0`	Pagination offset

Response: 200 OK — array of mission objects with task_stats.

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`	`COMPLETED`, `IN_PROGRESS`, `FAILED`, `CANCELLED`

When status changes to COMPLETED, FAILED, or CANCELLED, completed_at is automatically set. 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).

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
`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 COMPLETED, 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) 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 (`COMPLETED`/`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) 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). 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}

Request Body: All fields optional. (internal/api/task_handler.go:146)

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

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:359). task_order, max_iterations, 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}

Aggregated mission metrics for the workspace. total_missions and active_missions are lifetime counts; the *_24h fields cover the trailing 24 hours. 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
`COMPLETED`	Successfully finished
`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