Missions

Mission templates define reusable work. A mission run is one robot's execution of that work. Mission deployment is schedule-based, including fire-now requests.

Authentication

Template and schedule reads require missions:read. Authoring, dispatch, enable or disable, run control, roster changes, and priorities require missions:write. Recent mission-run reads use fleet:read. See Authentication.

Recommended workflow

Goal	Endpoint
Define and run one job in one call	POST /v1/agent/submit-job
Run an existing template now	POST /v1/agent/deploy-mission
Schedule an existing template	POST /v1/agent/schedule-mission
Update an existing schedule	POST /v1/agent/edit-schedule
Cancel a mission schedule	POST /v1/agent/cancel-schedule
Read a schedule	GET /v1/mission-schedule
Read runs produced by a schedule	GET /v1/mission-runs?schedule_id=...
Diagnose a live schedule	POST /v1/agent/get-runtime-status with schedule_id
Pause, resume, cancel, or abort one run	POST /v1/agent/control-mission

The former flat POST and DELETE /v1/mission-schedule routes were removed. Use the Agent API so changes are synchronized with the live scheduler.

Request a run

deploy-mission requests a fire-now run of an existing template. schedule-mission registers the same request on a schedule. Both require Idempotency-Key and missions:write. The key's organization must match org_id, and a fleet-scoped key must match fleet_id.

{
  "org_id": "org-uuid",
  "fleet_id": "fleet-uuid",
  "mission_id": "template-uuid",
  "robot_ids": ["robot-uuid"],
  "deployment_deadline_ms": 900000
}

mission_id is the template UUID. robot_ids chooses who may take the run:

robot_ids	Who may take it
[]	Any robot allowed by the template roster.
one id	That robot only. The call is rejected unless the robot is an active member of the fleet and advertises every capability the template requires.
several ids	Only those robots. Each id must belong to the fleet.

schedule-mission adds a schedule object:

{
  "owner": "server",
  "timezone": "America/Chicago",
  "startTimeMs": 1785859200000,
  "kind": "once"
}

kind is "once", { "interval": { "everySeconds": 3600 } }, or { "cron": { "expr": "0 */2 * * *" } }. timezone is an IANA name such as UTC. submit-job uses the same robot_ids rules. On submit-job, omit schedule or send null for a fire-now request. That call creates the template already enabled.

The response status is scheduled: the schedule is registered, and a robot has not been selected yet. The fleet operation must be running before a robot is given the mission. Start it with control-operation action start. A disabled template is not dispatched. Enable it with PUT …/mission-templates/{mission_id}/enabled or control-operation action enable_mission. Then follow the schedule as described under Schedule and deployment responses.

Changing which robots may run a template later, without starting a run, is control-operation assign_robot / unassign_robot. See Mission rosters.

Pause, resume, cancel, or abort a run

POST /v1/agent/control-mission

Permission: missions:write, with the same organization and fleet-scope checks as other Agent API calls. One robot per call.

{
  "org_id": "org-uuid",
  "fleet_id": "fleet-uuid",
  "robot_id": "robot-uuid",
  "mission_id": "template-uuid",
  "run_id": "run-uuid",
  "action": "pause"
}

action is pause, resume, cancel, or abort. Pass run_id from GET /v1/mission-runs. If run_id is omitted, the server addresses the command with mission_id.

pause suspends that run. resume continues a paused run. cancel and abort both ask the robot to cancel the run and record that an abort was requested. The robot's later status report is the finished outcome.

pause, cancel, and abort are kept when the robot is offline. The call succeeds and delivery.state is deferred. The server asks again after the robot reconnects and still reports that run. resume requires a connected robot. An offline robot returns 503 with code unavailable. Resuming a run that was cancelled or aborted returns 409.

Optional wait_for_ack or wait_for_ack_ms works as on robot commands. A successful body is:

{
  "success": true,
  "robotId": "robot-uuid",
  "missionId": "template-uuid",
  "delivery": { "state": "dispatched", "commandId": "command-uuid" }
}

Pause or resume the robot itself with control-robot.

Mission templates

Nested paths below start with /v1/orgs/{org_id}/fleets/{fleet_id}.

Method and path	Purpose
GET …/mission-templates	List templates as { "items": [{ "missionId", "name", "featureId" }] }.
GET …/mission-templates/{mission_id}	Read one template, including enabled state, step configuration, parameters, capabilities, and prerequisites.
POST …/mission-templates	Create a template. Requires Idempotency-Key; the server mints missionId.
PUT …/mission-templates/{mission_id}	Edit a template. Omitted step configuration is preserved.
DELETE …/mission-templates/{mission_id}	Delete a template. Returns 409 while a schedule references it or a robot is running it.
PUT …/mission-templates/{mission_id}/enabled	Enable or disable dispatch with { "enabled": true }.

The old top-level mission-template write routes were removed. Agent API query-entities and get-entity with kind: "mission_template" cover the same reads. control-operation enable_mission / disable_mission is the Agent API peer of the nested enabled route.

Template mutations wait briefly for the live operation to adopt the committed change. A confirmed response includes runtimeSync: "applied". If persistence committed but synchronization is still pending, the endpoint returns 202 with:

{
  "success": false,
  "persistenceState": "committed",
  "runtimeSync": "pending",
  "runtimeSyncError": "..."
}

This response does not mean the database change was rolled back.

Read scheduled missions

GET /v1/mission-schedule?fleet_id={fleet_id}&id={schedule_id}

Omit id to list schedules. Supplying limit or before selects the paginated response:

{ "items": [], "next_cursor": null }

Rows include status, last_failure_reason, last_failure_detail, deployment_deadline_ms, and template_mission_id. Status normally moves from scheduled to pending, then to deployed or failed.

Read mission runs

GET /v1/mission-runs?fleet_id={fleet_id}&days={n}&schedule_id={schedule_id}&robot_id={robot_id}&limit={n}

schedule_id and robot_id are optional. limit is capped at 500. Each item includes scheduleId when the run came from a schedule.

For finished-run keyset pagination and richer filters, use Agent API query-entities with kind: "mission_history".

Schedule and deployment responses

Agent mission-creation tools require Idempotency-Key and return separate template and schedule identifiers:

{
  "missionId": "template-uuid",
  "scheduleId": "schedule-uuid",
  "status": "scheduled"
}

Treat scheduled as asynchronous acceptance. edit-schedule uses the same response shape and requires an existing schedule_id; it never mints a new schedule and does not use Idempotency-Key.

submit-job, deploy-mission, schedule-mission, and edit-schedule accept optional retry_limit and retry_interval_secs for later fires of that schedule.

See Agent API.

Related

• Agent API
• Operations
• Features