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

# Missions

> Store and execute multi-task mission documents

## Mission endpoints

| Method   | Path                        | Description                         |
| -------- | --------------------------- | ----------------------------------- |
| `GET`    | `/v1/missions`              | List missions                       |
| `GET`    | `/v1/missions/resumable`    | List resumable missions             |
| `POST`   | `/v1/missions`              | Create a mission                    |
| `GET`    | `/v1/missions/{id}`         | Get a mission                       |
| `PATCH`  | `/v1/missions/{id}`         | Update a mission                    |
| `DELETE` | `/v1/missions/{id}`         | Delete a mission                    |
| `POST`   | `/v1/missions/{id}/execute` | Materialize and queue mission tasks |
| `POST`   | `/v1/missions/{id}/resume`  | Resume a mission                    |
| `POST`   | `/v1/missions/{id}/abort`   | Abort a mission                     |

## Create a mission

The required `data` field is a JSON-encoded mission document string. Do not send `tasks` or `team` as top-level request properties. Optional top-level fields are `prompt`, `name`, `status`, `schedule`, `deadline`, `endDate`, `notifications`, and `user`.

```typescript theme={null}
const document = {
  tasks: [
    {
      title: "Collect evidence",
      description: "Collect and cite primary sources.",
      assignTo: "researcher",
      expectations: [{ type: "llm_review", criteria: "Every claim is cited", threshold: 0.8 }],
    },
    {
      title: "Write report",
      description: "Write the final report from the collected evidence.",
      assignTo: "writer",
      dependsOn: ["Collect evidence"],
    },
  ],
  team: [
    { name: "researcher", role: "Collects primary sources", volatile: true },
    { name: "writer", role: "Writes cited reports", volatile: true },
  ],
};

const response = await fetch("https://{project}.polpo.cloud/v1/missions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POLPO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Weekly research report",
    prompt: "Research this week's market changes.",
    data: JSON.stringify(document),
    deadline: "2026-07-20T17:00:00Z",
  }),
});
```

A task in the document requires `title` and `description` and can include `assignTo`, `dependsOn`, `expectations`, `expectedOutcomes`, `metrics`, `maxRetries`, `maxDuration`, `retryPolicy`, `notifications`, and `sideEffects`. `team` is an array of volatile agent configurations. Quality gates, checkpoints, and delays require a `name`, at least one `afterTasks` entry, and at least one `blocksTasks` entry.

Mission resources retain `data` as a string and include `id`, `name`, `prompt`, `status`, scheduling fields, `qualityThreshold`, `notifications`, `executionCount`, `user`, and timestamps.

## Update a mission

`PATCH /v1/missions/{id}` accepts only `data`, `status`, `name`, `schedule`, `deadline`, and `endDate`.

```bash theme={null}
curl -X PATCH https://{project}.polpo.cloud/v1/missions/mission_abc123 \
  -H "Authorization: Bearer $POLPO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"paused"}'
```

## Execute a mission

Mission execution returns JSON rather than an SSE stream:

```bash theme={null}
curl -X POST https://{project}.polpo.cloud/v1/missions/mission_abc123/execute \
  -H "Authorization: Bearer $POLPO_API_KEY"
```

```json theme={null}
{
  "ok": true,
  "data": {
    "tasks": [
      {"id":"task_1","title":"Collect evidence","status":"pending"},
      {"id":"task_2","title":"Write report","status":"pending"}
    ],
    "group": "Weekly research report"
  }
}
```

Poll the created tasks or connect to `/v1/events` for live progress.

## Atomic document endpoints

| Resource      | Endpoints                                                                                                                                  |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Tasks         | `POST /missions/{missionId}/tasks`, `PATCH` or `DELETE /missions/{missionId}/tasks/{taskTitle}`, `PUT /missions/{missionId}/tasks/reorder` |
| Team          | `GET`, `POST`, `PATCH`, or `DELETE /missions/{missionId}/team`                                                                             |
| Checkpoints   | CRUD under `/missions/{missionId}/checkpoints`; resume with `POST /missions/{missionId}/checkpoints/{name}/resume`                         |
| Delays        | CRUD under `/missions/{missionId}/delays`                                                                                                  |
| Quality gates | CRUD under `/missions/{missionId}/quality-gates`                                                                                           |
| Notifications | `PUT /missions/{missionId}/notifications`                                                                                                  |

Task mutation paths identify a task by its title, not its generated task ID. Global checkpoint and delay listings are available at `GET /v1/missions/checkpoints` and `GET /v1/missions/delays`.