Skip to main content
Tasks are the building blocks of agent work. Each task is a unit of work with a clear deliverable, an assigned agent, and an automated assessment cycle. Tasks can run standalone or as part of a mission.

List tasks

/v1/tasks
Returns all tasks in the project. Use query parameters to filter.

Query parameters

status
string
Filter by task status. One of draft, pending, assigned, in_progress, review, done, failed, awaiting_approval.
group
string
Filter by task group or mission ID.
assignTo
string
Filter by assigned agent name.
curl "https://{project}.polpo.cloud/v1/tasks?status=in_progress&assignTo=backend-dev" \
  -H "Authorization: Bearer sk_live_abc123"

Response

[
  {
    "id": "task_abc123",
    "title": "Implement user auth",
    "description": "Add JWT-based authentication to the Express server.",
    "assignTo": "backend-dev",
    "status": "in_progress",
    "phase": "execution",
    "priority": 10,
    "retries": 0,
    "maxRetries": 3,
    "sideEffects": false
  }
]

Create task

/v1/tasks
Create a new task and optionally assign it to an agent.

Request body

title
string
required
Short name for the task. Used for dependency references within a mission.
description
string
required
Detailed instructions for the agent. The more specific, the better the result.
assignTo
string
required
Name of the agent to execute this task.
dependsOn
string[]
Task titles that must complete before this task can start.
expectations
object[]
Assessment criteria the task result will be evaluated against. See Assessment.
expectedOutcomes
object[]
Declared output types (file, text, url, json, media) so assessment can verify outputs.
maxRetries
number
Maximum retry attempts before the task is marked as failed.
priority
number
Execution priority. Higher values execute first when multiple tasks are ready.
sideEffects
boolean
Set to true if the task modifies external state (deploy, send email, etc.). The task will pause for human approval before completing.
maxDuration
number
Timeout in milliseconds for the task execution.
retryPolicy
object
Escalation and fallback configuration. Fields: escalateAfter (number), fallbackAgent (string), escalateModel (string).
curl -X POST https://{project}.polpo.cloud/v1/tasks \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Implement user auth",
    "description": "Add JWT-based authentication to the Express server. Create login and register endpoints, middleware for protected routes, and token refresh logic.",
    "assignTo": "backend-dev",
    "maxRetries": 3,
    "priority": 10,
    "sideEffects": false,
    "expectations": [
      { "criterion": "All auth endpoints return correct status codes" },
      { "criterion": "JWT tokens are signed and verified correctly" },
      { "criterion": "Protected routes reject unauthenticated requests" }
    ],
    "expectedOutcomes": [
      { "type": "file", "path": "src/server/auth.ts" },
      { "type": "file", "path": "src/server/middleware/auth.ts" }
    ]
  }'

Response

{
  "id": "task_abc123",
  "title": "Implement user auth",
  "description": "Add JWT-based authentication to the Express server...",
  "assignTo": "backend-dev",
  "status": "draft",
  "phase": null,
  "priority": 10,
  "retries": 0,
  "maxRetries": 3,
  "sideEffects": false
}

Get task

/v1/tasks/{taskId}
Retrieve a single task by ID, including its result and assessment.
taskId
string
required
The task’s unique ID.
curl
curl https://{project}.polpo.cloud/v1/tasks/task_abc123 \
  -H "Authorization: Bearer sk_live_abc123"

Response

{
  "id": "task_abc123",
  "title": "Implement user auth",
  "description": "Add JWT-based authentication to the Express server...",
  "assignTo": "backend-dev",
  "status": "done",
  "phase": null,
  "priority": 10,
  "retries": 0,
  "maxRetries": 3,
  "sideEffects": false,
  "result": {
    "content": "Implemented JWT auth with login, register, and refresh endpoints...",
    "filesCreated": ["src/server/auth.ts", "src/server/middleware/auth.ts"]
  },
  "assessment": {
    "score": 4.5,
    "passed": true,
    "feedback": "All endpoints implemented correctly. Token refresh logic is sound."
  }
}

Update task

/v1/tasks/{taskId}
Update one or more fields on an existing task. Only the fields you include are modified.
taskId
string
required
The task’s unique ID.
curl
curl -X PATCH https://{project}.polpo.cloud/v1/tasks/task_abc123 \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "priority": 20,
    "maxRetries": 5
  }'

Delete task

/v1/tasks/{taskId}
Delete a task. Cannot delete tasks that are currently executing.
taskId
string
required
The task’s unique ID.
curl
curl -X DELETE https://{project}.polpo.cloud/v1/tasks/task_abc123 \
  -H "Authorization: Bearer sk_live_abc123"
Deleting a task that other tasks depend on (via dependsOn) will cause those downstream tasks to fail when executed within a mission.

Retry task

/v1/tasks/{taskId}/retry
Retry a failed task. Resets the task status and runs it again. The retry count is incremented.
taskId
string
required
The task’s unique ID.
curl
curl -X POST https://{project}.polpo.cloud/v1/tasks/task_abc123/retry \
  -H "Authorization: Bearer sk_live_abc123"

Kill task

/v1/tasks/{taskId}/kill
Immediately stop a running task. The task status is set to failed.
taskId
string
required
The task’s unique ID.
curl
curl -X POST https://{project}.polpo.cloud/v1/tasks/task_abc123/kill \
  -H "Authorization: Bearer sk_live_abc123"

Reassess task

/v1/tasks/{taskId}/reassess
Re-run the assessment on a completed task without re-executing it. Useful when you have updated the assessment criteria and want to re-evaluate an existing result.
taskId
string
required
The task’s unique ID.
curl
curl -X POST https://{project}.polpo.cloud/v1/tasks/task_abc123/reassess \
  -H "Authorization: Bearer sk_live_abc123"

Execute task

/v1/tasks/{taskId}/execute
Execute a task in a sandbox environment. Returns a Server-Sent Events stream with real-time progress.
taskId
string
required
The task’s unique ID.
This endpoint always returns an SSE stream. Set Accept: text/event-stream in your request headers.
curl
curl -N https://{project}.polpo.cloud/v1/tasks/task_abc123/execute \
  -X POST \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "Accept: text/event-stream"

Stream events

EventDescription
statusTask status changed (e.g., assigned, in_progress, review)
phaseTask phase changed (e.g., execution, review, fix)
outputIncremental output from the agent
tool_useAgent invoked a tool
assessmentAssessment result available
doneTask execution completed
errorAn error occurred

Example: create and execute

A complete flow that creates a task and executes it.
# 1. Create the task
TASK_ID=$(curl -s -X POST https://{project}.polpo.cloud/v1/tasks \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Write unit tests",
    "description": "Write Jest unit tests for the auth module at src/server/auth.ts. Cover login, register, and token refresh.",
    "assignTo": "backend-dev",
    "maxRetries": 2,
    "expectations": [
      { "criterion": "Tests cover all three endpoints" },
      { "criterion": "Tests pass when run with npm test" }
    ],
    "expectedOutcomes": [
      { "type": "file", "path": "tests/auth.test.ts" }
    ]
  }' | jq -r '.id')

echo "Created task: $TASK_ID"

# 2. Execute it (streams SSE)
curl -N -X POST "https://{project}.polpo.cloud/v1/tasks/$TASK_ID/execute" \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "Accept: text/event-stream"