Skip to main content
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

/v1/missions
Returns all missions in the project.
curl
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

/v1/missions
Create a new mission with tasks, team configuration, quality gates, and checkpoints.

Request body

name
string
required
Human-readable mission name. Must be unique within the project.
prompt
string
High-level instruction for the mission. Provides context to all agents.
data
object
Arbitrary JSON payload available to all tasks during execution.
tasks
object[]
required
Array of task definitions. Each task has title, description, assignTo, and optionally dependsOn, expectations, expectedOutcomes, maxRetries, priority, sideEffects.
team
object
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.
qualityThreshold
number
Minimum assessment score (1-5) for tasks to pass. Defaults to 3.0.
deadline
string
ISO 8601 timestamp. Hard deadline for the entire mission.
schedule
string
Cron expression or ISO 8601 timestamp for scheduling. See Scheduling.
qualityGates
object[]
Quality gates that block downstream tasks until upstream tasks meet a minimum score.
checkpoints
object[]
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

/v1/missions/{missionId}
Retrieve a single mission by ID, including its tasks and current status.
missionId
string
required
The mission’s unique ID.
curl
curl https://{project}.polpo.cloud/v1/missions/msn_abc123 \
  -H "Authorization: Bearer sk_live_abc123"

Update mission

/v1/missions/{missionId}
Update one or more fields on an existing mission. Only the fields you include are modified.
missionId
string
required
The mission’s unique ID.
curl
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

/v1/missions/{missionId}
Delete a mission and all its associated tasks.
missionId
string
required
The mission’s unique ID.
curl
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.
missionId
string
required
The mission’s unique ID.
This endpoint returns an SSE stream. Set Accept: text/event-stream in your request headers.
curl
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

EventDescription
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.
missionId
string
required
The mission’s unique ID.

Request body

retryFailed
boolean
default:"false"
When true, failed tasks are retried before resuming. When false, failed tasks remain in their current state.
curl
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.
missionId
string
required
The mission’s unique ID.
curl
curl -X POST https://{project}.polpo.cloud/v1/missions/msn_abc123/abort \
  -H "Authorization: Bearer sk_live_abc123"

List resumable missions

/v1/missions/resumable
Returns missions that are currently paused and can be resumed.
curl
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
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
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
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"
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.
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.
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.