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.jsonfor the exact schema of each tool.
Read tools
| Tool | Purpose |
|---|---|
query-entities |
List robots, features, the operation, templates, schedules, scheduled commands, faults, mission runs, alerts, events, 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 the fleet operation, one robot, or one schedule. |
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, mission_run, alert, event, 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. Alerts, events, and mission runs are lists, so they stay on query-entities.
Past ranges
Pass a lookback in filters with exactly one of these:
| Field | Example | Meaning |
|---|---|---|
window |
"7d", "24h", "30m", "90s", "2w" |
A whole number plus s, m, h, d, or w. No spaces. |
days |
7 |
That many days back from now. |
hours |
12 |
That many hours back from now. |
The longest range is 90 days. Zero and mixed fields return 400. History kinds (mission_run, alert, event, fault, mission_history) cover from that time through now. Schedule kinds keep future fires and drop rows that ended before the cutoff.
Defaults when you omit the range: mission_run and alert use 7 days, fault returns currently active faults, and event, mission_history, scheduled_mission, and scheduled_command are unbounded. Pass window: "30d" when you want the schedule drawer. fault with active also needs a past range. mission_history can still use from_ms and to_ms; do not send those together with a past range.
A scheduled_command item includes the timezone, cron or interval, creator name, robots, operation name, service, parameters, run status, and feature, mission, and field-rule ids and names. scheduled_start_ms is the start time.
Live fleet status
get-runtime-status needs org_id and fleet_id. That is enough for the fleet's one operation: the response scope is "fleet" and includes operation feedback plus every live schedule status. Send operation_id only when you already have it and want the server to check that it is this fleet's operation.
schedule_id returns one status. It may be a mission schedule id or a nav: / traffic: road-wait id. robot_id returns that robot.
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 schedule, a command schedule, or an unsent road wait. |
ack-alerts |
Acknowledge open alerts in the fleet. |
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. |
relay-chat |
Interpret a natural-language fleet instruction. |
relay-respond |
Approve or cancel a proposed command, or answer a clarification. |
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-statuswithschedule_idfor 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.
Acknowledge alerts
POST /v1/agent/ack-alerts
Permission: fleet:write. Omit alert_ids to acknowledge every open alert. Send an empty array to acknowledge nothing.
{
"org_id": "org-uuid",
"fleet_id": "fleet-uuid",
"alert_ids": [42]
}
The response is { "updated": 1, "acknowledgedBy": "user-id" }.
Cancel a schedule
POST /v1/agent/cancel-schedule
schedule_id is the mission schedule id, the scheduled-command id, or a nav: / traffic: road-wait id. schedule_type (mission or command) is optional. A road-wait prefix is enough on its own. A mission that was already sent is not cancelled here; abort that run with control-mission.
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.
Relay
Relay turns a written fleet instruction into either an immediate answer or a command waiting for approval. Nothing in a proposed command runs until you approve it. These two routes use the same interpretation and approval behavior as the fleet app.
Relay can ask about the fleet and can propose the same kinds of actions as the control tools on this page. It does not create mission templates, create Field Rules, teleoperate a robot, or send a go-to.
These routes do not use Idempotency-Key. Sending the same instruction again starts a new turn.
Interpret an instruction
POST /v1/agent/relay-chat
Permission: fleet:read to submit the instruction. The action Relay understands must also be allowed by the key, using the same permission as that control tool. Stopping a robot needs robots:write. Assigning or controlling a mission needs missions:write. Operation changes need operations:control. Feature and Field Rule changes need features:write. A question needs the read permission for that information. If the key cannot perform the action, the response is still 200 with outcome error and error.code permission, and no proposal is created.
text is required, after trimming, and at most 4096 characters. robot_ids is optional and accepts at most 100 ids. timezone is an optional IANA name, such as America/Chicago. The fleet app sends the browser's timezone. If you omit timezone and the instruction names a clock time or a calendar day, the response asks which timezone to use. An interval with no clock time, such as every 30 minutes, does not need one.
{
"org_id": "org-uuid",
"fleet_id": "fleet-uuid",
"text": "Stop mowing and come home",
"robot_ids": ["robot-uuid"]
}
When robot_ids is present, those robots are the target of the instruction. Relay does not choose different robots from the wording. Each id must be an active robot in this fleet. An unknown id returns outcome error and error.code no_match. Omit robot_ids, or send an empty list, when the instruction should name the robots itself or when Relay should ask you to pick them.
A normal response is 200. The body uses the same camelCase fields for every outcome. proposals is an empty array when there is nothing to approve.
A command that is ready for approval:
{
"outcome": "ok",
"conversationId": "conversation-uuid",
"requestId": "request-uuid",
"text": "Stop robot West-1",
"workItems": [
{
"id": "work-item-uuid",
"kind": "command",
"verbId": "stop_robot",
"summary": "Stop robot West-1"
}
],
"clarifications": [],
"queryResult": null,
"error": null,
"traceSummary": [],
"proposals": [
{
"id": "proposal-uuid",
"conversationId": "conversation-uuid",
"verbId": "stop_robot",
"summary": "Stop robot West-1",
"status": "pending",
"payload": {},
"createdBy": { "userId": "api_key:key-uuid", "name": "api_key:key-uuid" },
"createdAt": "2026-09-22T12:00:00Z",
"decidedBy": null,
"decidedAt": null,
"error": null
}
]
}
summary is the one-line description to show an operator. payload is the command that will run on approval. It includes the robots, mission, schedule, and other choices Relay already decided. Review payload before approving. One instruction can produce more than one proposal. Each proposal is approved or cancelled on its own.
A question is answered in this same response. queryResult holds the matching rows, text is the answer, and proposals is empty.
When Relay needs a choice before it can build a command, outcome is clarify:
{
"outcome": "clarify",
"conversationId": "conversation-uuid",
"text": "I need a couple of things before this can be a command.",
"clarifications": [
{
"workItemId": "work-item-uuid",
"slot": "missions",
"prompt": "Select missions",
"multi": false,
"options": [
{ "id": "mission-uuid", "label": "Mow field" }
]
}
],
"proposals": []
}
Send the chosen option id values back with relay-respond. When multi is false, send one value. When multi is true, send every selected id. For an assign-mission robot question, the option id best_available means "Best available robot": approval lets the fleet operation assign one robot that can run that mission.
traceSummary is a short list of stage labels for the turn. Use error.message when showing a failure to a person.
An instruction Relay cannot turn into an answer or a command is still 200, with outcome error:
{
"outcome": "error",
"conversationId": "conversation-uuid",
"text": "No fleet robot with id robot-uuid. (failed at: preset robots)",
"error": {
"code": "no_match",
"step": "code.preset_robots",
"message": "No fleet robot with id robot-uuid. (failed at: preset robots)"
},
"proposals": []
}
error.code |
Meaning |
|---|---|
irrelevant |
The text is not a fleet question or command. |
unknown_verb |
Relay could not tell which fleet action was meant. |
out_of_scope |
That action is outside Relay, such as creating a template or a Field Rule. |
nonsensical |
The text does not map to a fleet command. Empty or overlong text is rejected with 400 before interpretation. |
missing_slots |
A required choice was still empty after options were shown. |
no_match |
No fleet record matched, including a robot_ids entry that is not an active robot in this fleet. |
parse_failed |
Relay could not finish the instruction. |
low_confidence |
The instruction was too ambiguous to become a command. |
permission |
The key cannot perform that action on this fleet. |
busy |
The instruction asked for too many separate actions, or this fleet already has 100 commands waiting for approval. |
model_unavailable |
The language service could not be reached. |
error.step names the stage that failed. error.message is the sentence to show the caller.
Approve, cancel, or answer
POST /v1/agent/relay-respond
action is approve, cancel, or clarify.
Approve one pending proposal. This runs the command.
Permission: the permission of the proposed action (robots:write, missions:write, operations:control, or features:write).
{
"org_id": "org-uuid",
"fleet_id": "fleet-uuid",
"action": "approve",
"proposal_id": "proposal-uuid"
}
Cancel a pending proposal. It does not run.
Permission: fleet:read when the same API key created the proposal. Cancelling another caller's proposal requires the proposed action's permission.
{
"org_id": "org-uuid",
"fleet_id": "fleet-uuid",
"action": "cancel",
"proposal_id": "proposal-uuid"
}
Approve and cancel return 200:
{
"result": "deployed",
"proposal": {
"id": "proposal-uuid",
"verbId": "stop_robot",
"summary": "Stop robot West-1",
"status": "deployed",
"error": null
}
}
result is the stored status: deployed, failed, or cancelled. A second approve or cancel of a proposal that is no longer pending returns result already_decided and the current proposal. failed means the command was not run. proposal.error says why. Approve and cancel still succeed when new interpretation is disabled, so a proposal that is already waiting can be cleared.
Answer a clarification. The response is the same object as relay-chat, including a new proposal or another clarification.
Permission: fleet:read. Only the caller who started the conversation can answer it. The action permission is checked again when the command is ready.
{
"org_id": "org-uuid",
"fleet_id": "fleet-uuid",
"action": "clarify",
"conversation_id": "conversation-uuid",
"answers": [
{ "slot": "missions", "values": ["mission-uuid"] },
{ "slot": "robots", "values": ["robot-uuid"] }
]
}
slot is the clarifications[].slot you were asked. values are option ids from that question.
| Status | When |
|---|---|
400 |
text is blank or longer than 4096 characters, robot_ids has more than 100 entries, action is not approve, cancel, or clarify, approve or cancel omits proposal_id, or clarify omits conversation_id or sends an answer with no slot or no value. |
403 |
The key lacks the permission for this call, or it is answering another caller's conversation. |
404 |
The proposal or conversation does not exist in this fleet. |
409 |
The conversation is not waiting for an answer. |
503 |
Interpretation is disabled, or Relay is busy. Retry a busy call. Approve and cancel are not disabled with interpretation. |