Skip to content

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, run control, roster changes, and priorities require missions:write. Recent mission-run reads use fleet:read. See Authentication.

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
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

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

Mission templates

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

Method and path Purpose
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. Template reads are available through Agent API query-entities and get-entity.

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. See Agent API.