Agent API

The Agent API provides intent-oriented tools at:

POST /v1/agent/{tool}

Every request body includes org_id and fleet_id. The API is designed for automations and LLM-backed integrations that need a smaller, typed surface than low-level resource routes.

Compatibility. Agent request objects reject unknown fields. Use GET /openapi.json for the exact schema of each tool.

Read tools

Tool	Purpose
`query-entities`	List robots, features, the operation, templates, schedules, scheduled commands, faults, finished mission history, Field Rules, or tracked objects.
`get-entity`	Read detailed robot, feature, operation, template, Field Rule, or tracked-object data.
`get-runtime-status`	Read live fleet, operation, robot, or schedule status.
`get-map-context`	Read fleet geometry and robot positions.
`explain-capability`	Find robots that advertise an action capability.
`resolve`	Resolve names and ids for robots, features, mission templates, and the fleet operation.

query-entities kind values are robot, feature, operation, mission_template, scheduled_mission, scheduled_command, fault, mission_history, field_rule, and object. Pass kinds: [...] to list several kinds in one call. get-entity supports robot, feature, operation, mission_template, field_rule, and object.

Pagination

Single-kind query-entities calls support opaque keyset cursors. Pass the prior response's next_cursor as cursor. A cursor is bound to the entity kind and exact filters, so using it with a different query returns 400. Legacy numeric offset cursors are not accepted. Multi-kind calls are not pageable.

mission_history contains finished runs only. Use get-runtime-status or GET /v1/mission-runs for active work.

Control tools

Tool	Purpose
`submit-job`	Define one mission inline and run or schedule it.
`deploy-mission`	Request a fire-now run of an existing template.
`schedule-mission`	Schedule an existing template.
`edit-schedule`	Update an existing mission schedule.
`schedule-command`	Schedule a non-mission command.
`cancel-schedule`	Cancel a mission or command schedule.
`control-operation`	Start, pause, reset, restart, enable or disable a mission, or otherwise control the fleet operation.
`control-mission`	Pause, resume, cancel, or abort one mission run.
`set-mission-priorities`	Update mission priorities as one batch.
`control-robot`	Start, stop, release, reset, set mode, invoke an action, update settings, or stop every active robot.
`control-feature`	Lock, unlock, or reset a feature, or enable or disable a Field Rule.
`upsert-field-rule`	Create or edit a Field Rule.

Submit a job

submit-job creates an enabled reusable mission template and registers its schedule in one request. It requires Idempotency-Key.

{
  "org_id": "org-uuid",
  "fleet_id": "fleet-uuid",
  "name": "Inspect north pad",
  "feature_id": "feature-uuid",
  "capabilities": ["inspect"],
  "robot_ids": [],
  "schedule": null,
  "deployment_deadline_ms": 900000
}

An empty robot_ids list allows any robot on the template roster, one id targets one robot, and multiple ids restrict eligibility to that set. A single targeted robot is rejected unless it is an active member of the fleet and advertises every capability the template requires. schedule: null requests a fire-now schedule. The fleet operation must be running, and the template must be enabled, before a robot is selected. See Missions.

A normal response is 201 Created:

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

Deployment is asynchronous

submit-job, deploy-mission, schedule-mission, and edit-schedule return status: "scheduled". This means the schedule was accepted. It does not mean a robot was selected, a run was created, or the robot acknowledged the work.

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

Follow the result with:

POST /v1/agent/get-runtime-status with schedule_id for live phase, summary, candidate robots, and blocking reasons.
GET /v1/mission-schedule?fleet_id=...&id=... for durable schedule status and failure details.
GET /v1/mission-runs?fleet_id=...&schedule_id=... for runs created by that schedule.
GET /v1/events?fleet_id=...&correlation_id=... for the correlated event timeline.

deploy-mission returns 202 Accepted because robot deployment remains asynchronous. submit-job normally returns 201, but can return 202 when its resources were committed and live runtime synchronization is still pending. edit-schedule updates an existing schedule and never mints a new schedule_id.

Deploy or schedule an existing template

deploy-mission and schedule-mission require Idempotency-Key and missions:write. mission_id is the template UUID. robot_ids uses the same empty, one, and many rules as submit-job.

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

schedule-mission also requires schedule. kind is "once", { "interval": { "everySeconds": 3600 } }, or { "cron": { "expr": "0 */2 * * *" } }, with owner and timezone. Both calls return status: "scheduled" before a robot is selected. Start the fleet operation first. Full request fields are on Missions.

Control one mission run

POST /v1/agent/control-mission

Permission: missions:write. One robot per call. action is pause, resume, cancel, or abort.

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

Pass run_id from the mission-runs read. If it is omitted, the server addresses the command with mission_id. pause, cancel, and abort succeed with delivery.state deferred when the robot is offline, and are asked again after it reconnects. resume requires a connected robot (503 when it is offline). Resuming a cancelled or aborted run returns 409. cancel and abort both ask the robot to cancel the run. See Missions.

Operation control

Each fleet has one operation, so control-operation.operation_id is optional. Omit it to control the fleet's operation, or include it to assert a specific operation id.

start and pause require operations:control. start resumes assignment and sends a resume to the operation's robots. pause stops new assignment and pauses runs in flight for this operation. abort_missions applies while the operation is paused.

assign_robot and unassign_robot require robot_id, mission_id, and missions:write. They edit who may be given that template later. They do not start a run. A template with no roster is open to every fleet robot. See Mission rosters.

Other actions are reset, restart, reset_step, reset_decomposers, enable_mission, and disable_mission. Enable and disable require mission_id and missions:write. Decomposer reset requires features:write.

Feature and Field Rule control

control-feature covers immediate feature and Field Rule intents:

Action	Required id	Purpose
`lock` / `unlock`	`feature_id`	Lock or unlock the feature resource. Optional `lock_reason` on lock.
`reset`	`feature_id`	Clear holders and reset decomposition.
`enable_field_rule` / `disable_field_rule`	`directive_id`	Toggle a Field Rule without a full upsert.

upsert-field-rule creates a Field Rule when directive_id is omitted (server-minted id, 201) or edits one when directive_id is set (200). The field_rule object is the same Field Rule payload used by nested REST. Persistence followed by incomplete robot delivery returns 207.

Robot delivery outcomes

Robot-hop tools can optionally wait for an acknowledgement using either wait_for_ack: true or positive wait_for_ack_ms. Do not specify both. Waiting is bounded to 30 seconds and reports delivery, not physical task completion.

Delivery states are dispatched, deferred, agent_received, agent_rejected, and timed_out. A timeout can indicate that only the HTTP wait expired while retries continue.

control-robot supports up to 100 targets for start, stop, release, mode, invoke_action, and update_settings. The request is split into one independent command per robot. It returns 200 when all targets succeed, 207 for mixed outcomes, and 502 when all fail.

stop pauses the robot and requires robots:write. An offline stop is queued and reported as delivery.state deferred. start resumes autonomous operation and requires the same permission. An offline start fails for that robot with code unavailable, because resuming requires a live connection. See Robots.

stop_all pauses every active robot in the fleet and does not take a robot list. force_reset requires exactly one robot. Go-to remains on the nested endpoint.