> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crewship.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Missions

> Mission lifecycle management -- create, start, monitor, and control multi-agent task execution.

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.

<Note>
  All mission endpoints require authentication and workspace context.
</Note>

## Endpoints

| Method   | Endpoint                                                                     | Purpose                          |
| -------- | ---------------------------------------------------------------------------- | -------------------------------- |
| `GET`    | [`/api/v1/missions`](#list-all-missions-workspace)                           | List all missions in a workspace |
| `GET`    | [`/api/v1/crews/{crewId}/missions`](#list-crew-missions)                     | List a crew's missions           |
| `POST`   | [`/api/v1/crews/{crewId}/missions`](#create-mission)                         | Create a mission                 |
| `GET`    | [`/api/v1/crews/{crewId}/missions/{missionId}`](#get-mission)                | Get a mission with tasks         |
| `PATCH`  | [`/api/v1/crews/{crewId}/missions/{missionId}`](#update-mission)             | Update a mission                 |
| `DELETE` | [`/api/v1/crews/{crewId}/missions/{missionId}`](#delete-mission)             | Delete a mission                 |
| `POST`   | [`/api/v1/crews/{crewId}/missions/{missionId}/start`](#start-mission)        | Start a mission                  |
| `POST`   | [`/api/v1/crews/{crewId}/missions/{missionId}/restart`](#restart-mission)    | Restart a terminal mission       |
| `POST`   | [`/api/v1/crews/{crewId}/missions/{missionId}/resume`](#resume-mission)      | Resume a failed mission          |
| `POST`   | [`/api/v1/crews/{crewId}/missions/{missionId}/clone`](#clone-mission)        | Clone a mission                  |
| `POST`   | [`/api/v1/crews/{crewId}/missions/{missionId}/tasks`](#create-task)          | Add a task                       |
| `PATCH`  | [`/api/v1/crews/{crewId}/missions/{missionId}/tasks/{taskId}`](#update-task) | Update a task                    |
| `GET`    | [`/api/v1/missions/{missionId}/checkpoints`](#list-mission-checkpoints)      | List mission checkpoints         |
| `POST`   | [`/api/v1/missions/{missionId}/checkpoints`](#create-mission-checkpoint)     | Create a mission checkpoint      |
| `GET`    | [`/api/v1/mission-metrics`](#mission-metrics)                                | Aggregated mission metrics       |

***

## Missions

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`

```json theme={null}
[
  {
    "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      |

```json theme={null}
{
  "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`

```json theme={null}
{
  "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}
```

<Warning>
  Only missions in `PLANNING` or `CANCELLED` status can be deleted (hard delete).
</Warning>

**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`

```json theme={null}
{
  "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`

```json theme={null}
{ "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`

```json theme={null}
{ "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](/api-reference/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`

```json theme={null}
{
  "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 |

```json theme={null}
{ "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`

```json theme={null}
{
  "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                |