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
Returns all tasks in the project. Use query parameters to filter.
Query parameters
Filter by task status. One of draft, pending, assigned, in_progress, review, done, failed, awaiting_approval.
Filter by task group or mission ID.
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
Create a new task and optionally assign it to an agent.
Request body
Short name for the task. Used for dependency references within a mission.
Detailed instructions for the agent. The more specific, the better the result.
Name of the agent to execute this task.
Task titles that must complete before this task can start.
Assessment criteria the task result will be evaluated against. See Assessment.
Declared output types (file, text, url, json, media) so assessment can verify outputs.
Maximum retry attempts before the task is marked as failed.
Execution priority. Higher values execute first when multiple tasks are ready.
Set to true if the task modifies external state (deploy, send email, etc.). The task will pause for human approval before completing.
Timeout in milliseconds for the task execution.
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
Retrieve a single task by ID, including its result and assessment.
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
Update one or more fields on an existing task. Only the fields you include are modified.
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
Delete a task. Cannot delete tasks that are currently executing.
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
Retry a failed task. Resets the task status and runs it again. The retry count is incremented.
curl -X POST https://{project}.polpo.cloud/v1/tasks/task_abc123/retry \
-H "Authorization: Bearer sk_live_abc123"
Kill task
Immediately stop a running task. The task status is set to failed.
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.
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.
This endpoint always returns an SSE stream. Set Accept: text/event-stream in your request headers.
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
| Event | Description |
|---|
status | Task status changed (e.g., assigned, in_progress, review) |
phase | Task phase changed (e.g., execution, review, fix) |
output | Incremental output from the agent |
tool_use | Agent invoked a tool |
assessment | Assessment result available |
done | Task execution completed |
error | An 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"
const API_KEY = "sk_live_abc123";
const BASE = "https://{project}.polpo.cloud/v1";
// 1. Create the task
const createRes = await fetch(`${BASE}/tasks`, {
method: "POST",
headers: {
Authorization: `Bearer ${API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
title: "Write unit tests",
description:
"Write Jest unit tests for the auth module at src/server/auth.ts.",
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" }],
}),
});
const task = await createRes.json();
console.log("Created task:", task.id);
// 2. Execute and stream output
const execRes = await fetch(`${BASE}/tasks/${task.id}/execute`, {
method: "POST",
headers: {
Authorization: `Bearer ${API_KEY}`,
Accept: "text/event-stream",
},
});
const reader = execRes.body.getReader();
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader.read();
if (done) break;
process.stdout.write(decoder.decode(value));
}
import requests
import json
API_KEY = "sk_live_abc123"
BASE = "https://{project}.polpo.cloud/v1"
# 1. Create the task
task = requests.post(
f"{BASE}/tasks",
headers={"Authorization": f"Bearer {API_KEY}"},
json={
"title": "Write unit tests",
"description": "Write Jest unit tests for the auth module at src/server/auth.ts.",
"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"}],
},
).json()
print(f"Created task: {task['id']}")
# 2. Execute and stream output
with requests.post(
f"{BASE}/tasks/{task['id']}/execute",
headers={
"Authorization": f"Bearer {API_KEY}",
"Accept": "text/event-stream",
},
stream=True,
) as res:
for line in res.iter_lines():
if line:
print(line.decode())