Skip to content

Operations

Each fleet has one long-lived operation composed from its mission templates. A template is one operation step. Create or edit templates to change the operation; do not create a separate plan object.

The former plan draft, validation, and deployment lifecycle and its plans endpoints were removed. The old operation list, feedback, progress, history, per-action control, operation-priority, and operation-wide reset-decomposers routes were also replaced by the Agent API.

Authentication

Use operations:read for live operation context and operations:control for lifecycle and scheduled-command control. Template authoring, enable/disable, mission rosters, and mission priorities use missions:write. Resetting feature decomposers uses features:write.

Read live operation state

Use these Agent API tools:

Tool Purpose
get-runtime-status Fleet rollup or live operation, robot, and schedule status.
get-entity with kind: "operation" Detailed operation state.
query-entities with kind: "operation" Resolve the fleet operation.
get-map-context Feature geometry and robot positions relevant to work.

The fleet manifest also returns the operation as one object, not an array:

{
  "operation": {
    "operation_id": "operation-uuid",
    "name": "North yard operation"
  }
}

Control the operation

POST /v1/agent/control-operation

Supported actions include start, pause, reset, restart, abort_missions, reset_step, assign_robot, unassign_robot, reset_decomposers, enable_mission, and disable_mission.

{
  "org_id": "org-uuid",
  "fleet_id": "fleet-uuid",
  "action": "start"
}

operation_id is optional because a fleet has one operation. A fleet with no operation yet returns 404 until a mission template exists.

start uses operations:control. It resumes assignment and sends a resume to the operation's robots. pause uses the same permission. It stops new assignment and pauses runs that are in flight for this operation. A scheduled mission is assigned only while the operation is running. abort_missions applies while the operation is paused.

enable_mission and disable_mission require mission_id and use missions:write.

Mission rosters

assign_robot and unassign_robot edit which robots may be given one template. They do not start a run. Permission: missions:write.

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

assign_robot requires an active robot in the fleet that advertises every capability the template requires. A missing capability returns 400. A robot that is not an active member of the fleet returns 404. A template with no roster is already open to every fleet robot, so adding a robot in that state leaves the roster open. A robot already on the roster is left unchanged.

unassign_robot removes that robot from future assignment. A run already in progress finishes. Removing the last listed robot returns 400, because an empty roster means every fleet robot is eligible. Removing a robot from an open roster records the other active fleet robots as the roster.

To request a run now, use deploy-mission. The operation must be running.

Mission priorities are changed through:

POST /v1/agent/set-mission-priorities

Priority updates are applied as one batch.

Scheduled commands

Use:

POST /v1/agent/schedule-command
POST /v1/agent/cancel-schedule

schedule-command requires Idempotency-Key and returns 201 Created with status: "scheduled". It is for non-mission commands. Use schedule-mission for mission templates.

The required authorization is derived from the command kind. Resources named inside the command must belong to the target fleet.

Submit one inline job

For one-call job intake, use POST /v1/agent/submit-job. It creates one enabled template and registers its schedule. See Agent API.

Runtime synchronization

Template create, update, delete, and enable operations can return 202 Accepted after persistence if the live operation has not yet confirmed the update. Inspect persistenceState, runtimeSync, and runtimeSyncError before deciding whether to retry.

Audit and events

Use GET /v1/audit-log for command audit entries and GET /v1/events for the full correlated event timeline. The removed nested activity-log endpoint is not a replacement for either.