> ## 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.

# Tasks

> Create, manage, and execute tasks

## Endpoints

| Method   | Path                        | Description                                            |
| -------- | --------------------------- | ------------------------------------------------------ |
| `GET`    | `/v1/tasks`                 | List tasks; filter by `status`, `group`, or `assignTo` |
| `POST`   | `/v1/tasks`                 | Create a task                                          |
| `GET`    | `/v1/tasks/{id}`            | Get a task                                             |
| `PATCH`  | `/v1/tasks/{id}`            | Update a task                                          |
| `DELETE` | `/v1/tasks/{id}`            | Delete a task                                          |
| `POST`   | `/v1/tasks/{id}/retry`      | Retry a failed task                                    |
| `POST`   | `/v1/tasks/{id}/kill`       | Stop a running task                                    |
| `POST`   | `/v1/tasks/{id}/reassess`   | Reassess output                                        |
| `POST`   | `/v1/tasks/{id}/queue`      | Queue a task                                           |
| `POST`   | `/v1/tasks/{id}/force-fail` | Force a failure                                        |
| `GET`    | `/v1/tasks/{id}/activity`   | Get task activity                                      |
| `POST`   | `/v1/tasks/{id}/execute`    | Execute through the Cloud sandbox and stream events    |
| `DELETE` | `/v1/tasks`                 | Bulk delete by `status`, `group`, or `all=true`        |

## Create a task

`title`, `description`, and `assignTo` are required. The request also accepts `executionMode`, `sandbox`, `loop`, `draft`, `expectations`, `expectedOutcomes`, `dependsOn`, `group`, `maxDuration`, `retryPolicy`, `notifications`, `sideEffects`, and `user`.

```bash theme={null}
curl -X POST https://{project}.polpo.cloud/v1/tasks \
  -H "Authorization: Bearer $POLPO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Add health endpoint",
    "description": "Implement GET /health and add an integration test.",
    "assignTo": "backend-dev",
    "loop": "implementation-flow",
    "expectations": [
      {"type":"test","command":"pnpm test -- health"},
      {"type":"file_exists","paths":["src/routes/health.ts"]},
      {"type":"llm_review","criteria":"The endpoint has no side effects","threshold":0.8}
    ],
    "expectedOutcomes": [
      {"type":"file","label":"Health route","path":"src/routes/health.ts"}
    ],
    "maxDuration": 1800,
    "sandbox": {"isolation": "fresh"},
    "retryPolicy": {"escalateAfter":2,"fallbackAgent":"senior-backend-dev"}
  }'
```

`priority` and a top-level create-time `maxRetries` are not task creation fields. `retryPolicy` accepts `escalateAfter`, `fallbackAgent`, and `escalateModel`; `maxRetries` can be changed later through `PATCH`.

```json theme={null}
{
  "ok": true,
  "data": {
    "id": "task_abc123",
    "title": "Add health endpoint",
    "status": "pending",
    "assignTo": "backend-dev"
  }
}
```

## Update a task

`PATCH` accepts `description`, `assignTo`, `loop`, `status`, `expectations`, `retries`, `maxRetries`, `sideEffects`, and `sandbox`.

```bash theme={null}
curl -X PATCH https://{project}.polpo.cloud/v1/tasks/task_abc123 \
  -H "Authorization: Bearer $POLPO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"assignTo":"senior-backend-dev","maxRetries":3}'
```

## Execute a task

The Cloud extension streams runtime events as SSE:

```bash theme={null}
curl -N -X POST https://{project}.polpo.cloud/v1/tasks/task_abc123/execute \
  -H "Authorization: Bearer $POLPO_API_KEY" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"sandbox":{"isolation":"fresh"}}'
```

For normal orchestration, create or queue the task and monitor `GET /v1/tasks/{id}`, activity, or the project event stream.

`sandbox.isolation` can be `reuse` or `fresh`. See [Runtime Sandboxes](/docs/platform/runtime-sandboxes) for precedence and storage behavior.