A mission groups related tasks into an orchestrated workflow. Missions handle dependency resolution, quality gates, checkpoints, and scheduling. Create a mission, add tasks, and execute it — Polpo handles the rest.
List missions
Returns all missions in the project.
curl https://{project}.polpo.cloud/v1/missions \
-H "Authorization: Bearer sk_live_abc123"
Response
[
{
"id" : "msn_abc123" ,
"name" : "weekly-report" ,
"status" : "completed" ,
"executionCount" : 4 ,
"qualityThreshold" : 3.5 ,
"taskCount" : 3
},
{
"id" : "msn_def456" ,
"name" : "onboarding-flow" ,
"status" : "draft" ,
"executionCount" : 0 ,
"qualityThreshold" : 4.0 ,
"taskCount" : 5
}
]
Create mission
Create a new mission with tasks, team configuration, quality gates, and checkpoints.
Request body
Human-readable mission name. Must be unique within the project.
High-level instruction for the mission. Provides context to all agents.
Arbitrary JSON payload available to all tasks during execution.
Array of task definitions. Each task has title, description, assignTo, and optionally dependsOn, expectations, expectedOutcomes, maxRetries, priority, sideEffects.
Team definition for the mission. Include name, volatile (boolean), and agents (array of agent configs). Volatile teams are created when the mission starts and cleaned up when it completes.
Minimum assessment score (1-5) for tasks to pass. Defaults to 3.0.
ISO 8601 timestamp. Hard deadline for the entire mission.
Cron expression or ISO 8601 timestamp for scheduling. See Scheduling .
Quality gates that block downstream tasks until upstream tasks meet a minimum score.
Checkpoints that pause the mission for human review.
curl -X POST https://{project}.polpo.cloud/v1/missions \
-H "Authorization: Bearer sk_live_abc123" \
-H "Content-Type: application/json" \
-d '{
"name": "deploy-pipeline",
"prompt": "Run the deployment pipeline for the backend service.",
"qualityThreshold": 4.0,
"tasks": [
{
"title": "Run tests",
"description": "Execute the full test suite and report results.",
"assignTo": "backend-dev",
"maxRetries": 2,
"expectations": [
{ "criterion": "All tests pass" },
{ "criterion": "Code coverage above 80%" }
]
},
{
"title": "Deploy to staging",
"description": "Deploy the latest build to the staging environment.",
"assignTo": "deploy-agent",
"dependsOn": ["Run tests"],
"sideEffects": true
}
],
"team": {
"name": "deploy-crew",
"volatile": true,
"agents": [
{
"name": "backend-dev",
"role": "Run tests and validate build",
"model": "anthropic/claude-sonnet-4-5"
},
{
"name": "deploy-agent",
"role": "Deploy services to staging and production",
"model": "anthropic/claude-sonnet-4-5"
}
]
},
"qualityGates": [
{
"afterTasks": ["Run tests"],
"blocksTasks": ["Deploy to staging"],
"minScore": 4.0,
"requireAllPassed": true
}
]
}'
Response
{
"id" : "msn_abc123" ,
"name" : "deploy-pipeline" ,
"status" : "draft" ,
"prompt" : "Run the deployment pipeline for the backend service." ,
"qualityThreshold" : 4.0 ,
"executionCount" : 0 ,
"tasks" : [
{
"id" : "task_001" ,
"title" : "Run tests" ,
"assignTo" : "backend-dev" ,
"status" : "draft"
},
{
"id" : "task_002" ,
"title" : "Deploy to staging" ,
"assignTo" : "deploy-agent" ,
"status" : "draft" ,
"dependsOn" : [ "Run tests" ]
}
]
}
Get mission
Retrieve a single mission by ID, including its tasks and current status.
curl https://{project}.polpo.cloud/v1/missions/msn_abc123 \
-H "Authorization: Bearer sk_live_abc123"
Update mission
Update one or more fields on an existing mission. Only the fields you include are modified.
curl -X PATCH https://{project}.polpo.cloud/v1/missions/msn_abc123 \
-H "Authorization: Bearer sk_live_abc123" \
-H "Content-Type: application/json" \
-d '{
"qualityThreshold": 4.5,
"deadline": "2026-04-01T00:00:00Z"
}'
Delete mission
Delete a mission and all its associated tasks.
curl -X DELETE https://{project}.polpo.cloud/v1/missions/msn_abc123 \
-H "Authorization: Bearer sk_live_abc123"
Deleting a mission is permanent and removes all tasks within it. Running missions must be aborted first.
Execute mission
/v1/missions/{missionId}/execute
Start executing a mission. Tasks are scheduled based on their dependencies and priorities. Returns an SSE stream with real-time progress.
This endpoint returns an SSE stream. Set Accept: text/event-stream in your request headers.
curl -N -X POST https://{project}.polpo.cloud/v1/missions/msn_abc123/execute \
-H "Authorization: Bearer sk_live_abc123" \
-H "Accept: text/event-stream"
Stream events
Event Description mission:statusMission status changed (e.g., active, paused, completed) task:statusA task’s status changed task:outputIncremental output from a task’s agent task:assessmentAssessment result for a task gate:blockedA quality gate blocked downstream tasks checkpoint:waitingMission paused at a checkpoint for human review mission:doneMission execution completed errorAn error occurred
Resume mission
/v1/missions/{missionId}/resume
Resume a paused mission. Missions pause at checkpoints or when a quality gate blocks execution.
Request body
When true, failed tasks are retried before resuming. When false, failed tasks remain in their current state.
curl -X POST https://{project}.polpo.cloud/v1/missions/msn_abc123/resume \
-H "Authorization: Bearer sk_live_abc123" \
-H "Content-Type: application/json" \
-d '{ "retryFailed": true }'
Abort mission
/v1/missions/{missionId}/abort
Immediately stop a running mission. All in-progress tasks are killed and the mission status is set to cancelled.
curl -X POST https://{project}.polpo.cloud/v1/missions/msn_abc123/abort \
-H "Authorization: Bearer sk_live_abc123"
List resumable missions
Returns missions that are currently paused and can be resumed.
curl https://{project}.polpo.cloud/v1/missions/resumable \
-H "Authorization: Bearer sk_live_abc123"
Response
[
{
"id" : "msn_abc123" ,
"name" : "deploy-pipeline" ,
"status" : "paused" ,
"pauseReason" : "checkpoint" ,
"pauseMessage" : "Approve the staging deployment before proceeding to production."
}
]
Mission task sub-operations
You can manage tasks within a mission directly.
Add task to mission
/v1/missions/{missionId}/tasks
Add a new task to an existing mission.
curl -X POST https://{project}.polpo.cloud/v1/missions/msn_abc123/tasks \
-H "Authorization: Bearer sk_live_abc123" \
-H "Content-Type: application/json" \
-d '{
"title": "Notify team",
"description": "Send a Slack notification with the deployment status.",
"assignTo": "deploy-agent",
"dependsOn": ["Deploy to staging"],
"sideEffects": true
}'
Update task in mission
/v1/missions/{missionId}/tasks/{taskId}
Update a task within a mission.
curl -X PATCH https://{project}.polpo.cloud/v1/missions/msn_abc123/tasks/task_003 \
-H "Authorization: Bearer sk_live_abc123" \
-H "Content-Type: application/json" \
-d '{ "priority": 5 }'
Delete task from mission
/v1/missions/{missionId}/tasks/{taskId}
Remove a task from a mission.
curl -X DELETE https://{project}.polpo.cloud/v1/missions/msn_abc123/tasks/task_003 \
-H "Authorization: Bearer sk_live_abc123"
Example: create and execute a mission
A complete flow that creates a mission with two tasks and executes it.
# 1. Create the mission
MISSION_ID = $( curl -s -X POST https://{project}.polpo.cloud/v1/missions \
-H "Authorization: Bearer sk_live_abc123" \
-H "Content-Type: application/json" \
-d '{
"name": "code-review-pipeline",
"prompt": "Review the latest PR and provide feedback.",
"qualityThreshold": 4.0,
"tasks": [
{
"title": "Analyze code changes",
"description": "Review the diff for the latest PR. Check for bugs, security issues, and style violations.",
"assignTo": "code-reviewer",
"expectations": [
{ "criterion": "All critical issues identified" },
{ "criterion": "Feedback is actionable and specific" }
]
},
{
"title": "Write review summary",
"description": "Compile the analysis into a structured review summary with approve/request-changes recommendation.",
"assignTo": "tech-lead",
"dependsOn": ["Analyze code changes"]
}
],
"team": {
"name": "review-team",
"volatile": true,
"agents": [
{
"name": "code-reviewer",
"role": "Senior code reviewer",
"model": "anthropic/claude-sonnet-4-5"
},
{
"name": "tech-lead",
"role": "Technical lead who writes review summaries",
"model": "anthropic/claude-sonnet-4-5"
}
]
}
}' | jq -r '.id' )
echo "Created mission: $MISSION_ID "
# 2. Execute the mission (streams SSE)
curl -N -X POST "https://{project}.polpo.cloud/v1/missions/ $MISSION_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 mission
const createRes = await fetch ( ` ${ BASE } /missions` , {
method: "POST" ,
headers: {
Authorization: `Bearer ${ API_KEY } ` ,
"Content-Type" : "application/json" ,
},
body: JSON . stringify ({
name: "code-review-pipeline" ,
prompt: "Review the latest PR and provide feedback." ,
qualityThreshold: 4.0 ,
tasks: [
{
title: "Analyze code changes" ,
description: "Review the diff for the latest PR." ,
assignTo: "code-reviewer" ,
},
{
title: "Write review summary" ,
description: "Compile the analysis into a structured review summary." ,
assignTo: "tech-lead" ,
dependsOn: [ "Analyze code changes" ],
},
],
team: {
name: "review-team" ,
volatile: true ,
agents: [
{
name: "code-reviewer" ,
role: "Senior code reviewer" ,
model: "anthropic/claude-sonnet-4-5" ,
},
{
name: "tech-lead" ,
role: "Technical lead" ,
model: "anthropic/claude-sonnet-4-5" ,
},
],
},
}),
});
const mission = await createRes . json ();
console . log ( "Created mission:" , mission . id );
// 2. Execute and stream events
const execRes = await fetch ( ` ${ BASE } /missions/ ${ mission . 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
API_KEY = "sk_live_abc123"
BASE = "https:// {project} .polpo.cloud/v1"
# 1. Create the mission
mission = requests.post(
f " { BASE } /missions" ,
headers = { "Authorization" : f "Bearer { API_KEY } " },
json = {
"name" : "code-review-pipeline" ,
"prompt" : "Review the latest PR and provide feedback." ,
"qualityThreshold" : 4.0 ,
"tasks" : [
{
"title" : "Analyze code changes" ,
"description" : "Review the diff for the latest PR." ,
"assignTo" : "code-reviewer" ,
},
{
"title" : "Write review summary" ,
"description" : "Compile the analysis into a structured review summary." ,
"assignTo" : "tech-lead" ,
"dependsOn" : [ "Analyze code changes" ],
},
],
"team" : {
"name" : "review-team" ,
"volatile" : True ,
"agents" : [
{
"name" : "code-reviewer" ,
"role" : "Senior code reviewer" ,
"model" : "anthropic/claude-sonnet-4-5" ,
},
{
"name" : "tech-lead" ,
"role" : "Technical lead" ,
"model" : "anthropic/claude-sonnet-4-5" ,
},
],
},
},
).json()
print ( f "Created mission: { mission[ 'id' ] } " )
# 2. Execute and stream events
with requests.post(
f " { BASE } /missions/ { mission[ '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())
What happens if a task fails during mission execution?
The mission’s retry policy kicks in. The task is retried up to maxRetries times. If all retries fail, the retryPolicy escalation rules apply (fallback agent, model upgrade). If the task still fails, dependent tasks are skipped and the mission status is set to failed.
Can I add tasks to a running mission?
Yes. Use POST /v1/missions/{missionId}/tasks to add tasks even while the mission is active. New tasks are scheduled according to their dependsOn configuration. Tasks with no dependencies start immediately.
How do checkpoints differ from quality gates?
Quality gates are automatic — they block downstream tasks until upstream tasks meet a minimum score. Checkpoints are manual — they pause the entire mission until a human approves via the dashboard or the resume endpoint.