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.

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.

{
  "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.

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:

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 for precedence and storage behavior.

Overview

Chat Completions

Agents

Missions

Memory

Files

Sessions

Vault

Skills

Approvals

Schedules

Playbooks

Logs

Config

Watchers

Templates

Health

Tasks

Endpoints

Create a task

Update a task

Execute a task

​Endpoints

​Create a task

​Update a task

​Execute a task

Endpoints

Create a task

Update a task

Execute a task