Robots

A robot is an enrolled device in a fleet that reports telemetry and accepts commands.

Authentication

Robot reads require robots:read. Robot edits, settings, tracked objects, and live commands require robots:write. Mission-run control uses missions:write. Release and force-reset also require operations:control. Fleet-wide stop uses robots:write.

Read robots

fleet_id is the fleet UUID from List reachable fleets. Robot reads require robots:read. The key's organization must match, and a fleet-scoped key must match this fleet.

List robots that are active in the fleet with POST /v1/agent/query-entities:

{ "org_id": "org-uuid", "fleet_id": "fleet-uuid", "kind": "robot" }

Each item includes robot_id and name, plus capabilities and live status. Optional filters are capability, available, and online.

{
  "items": [
    { "robot_id": "robot-uuid", "name": "Rover 1", "capabilities": ["inspect"] }
  ]
}

get-entity with kind: "robot" returns one robot's identity, live state, capability descriptors, and current settings. get-runtime-status with robot_id returns its current mission and operation state.

Resolve a robot name to an id inside a fleet you already identified by UUID:

{
  "org_id": "org-uuid",
  "fleet_id": "fleet-uuid",
  "names": ["Rover 1"],
  "kinds": ["robot"]
}

Each item is { "kind": "robot", "id", "name" }.

The top-level compatibility endpoints remain available:

GET /v1/robots?fleet_id={fleet_uuid}
GET /v1/robots/{robot_id}
GET /v1/robots/{robot_id}/details
PATCH /v1/robots/{robot_id}

GET /v1/robots returns a JSON array of every robot record in the fleet, including robots that are not yet active. Each object includes id and name, plus the latest stored telemetry described in Telemetry. Use query-entities when the caller wants robots that can take work. details returns usage totals and latest per-device health. PATCH updates mutable metadata or transfers an idle robot to another authorized fleet.

Send a robot command

Prefer Agent API control-robot for start, stop, release, force reset, mode, action invocation, and settings updates. Nested command paths start with /v1/orgs/{org_id}/fleets/{fleet_id} and remain for commands the Agent API does not fold in:

Endpoint	Purpose
POST …/robots/{robot_id}/go-to	Assign a one-shot geographic destination.
POST …/robots/{robot_id}/mode	Set the robot mode.
POST …/robots/{robot_id}/invoke-service	Invoke an advertised action. The route keeps its compatibility name.
POST …/robots/{robot_id}/settings	Send setting updates.
POST …/stop-all	Pause every active robot in the fleet.

Safety. Robot commands can move or stop physical equipment. Verify the work area and maintain an independent stop mechanism.

POST …/stop-all is the same fleet-wide stop used by the Fleet Manager Stop All control. It returns { "success": true|false, "count": n, "outcomes": [...] } and uses the same 200 / 207 / 502 outcome rules as bulk control-robot.

The nested stop, resume, release, force-reset, and mission-run-status routes were removed. Use Agent API control-robot and control-mission instead.

Pause and resume a robot

control-robot action stop pauses the robot. Action start resumes autonomous operation. Permission: robots:write.

{
  "org_id": "org-uuid",
  "fleet_id": "fleet-uuid",
  "robot_ids": ["robot-uuid"],
  "action": "stop"
}

A single robot_id is accepted and combined with robot_ids. Up to 100 robots. Outcome status codes are in Bulk control.

An offline stop is accepted and sent when the robot reconnects. That robot's outcome has delivery.state deferred. An offline start fails for that robot because resuming requires a live connection. The outcome then carries code unavailable and an error string. Every target failing returns 502. A mix of successes and failures returns 207.

stop and start act on the robot. Pause or resume one mission run with control-mission. control-operation pause stops the fleet operation from assigning new work and pauses runs already in flight for that operation. See Operations.

Optional acknowledgement wait

Reliable robot commands accept either:

{ "wait_for_ack": true }

or:

{ "wait_for_ack_ms": 10000 }

Do not send both. Camel-case aliases are accepted, and waits are capped at 30 seconds.

Responses include a delivery object whose state is dispatched, deferred, agent_received, agent_rejected, or timed_out. A timeout is a delivery observation, not proof that physical execution failed. If retryBudgetExhausted is false, background retries may continue.

A robot policy rejection returns 422 policy_rejected.

Bulk control

POST /v1/agent/control-robot supports up to 100 robot targets for start, stop, release, mode, invoke_action, and update_settings. It starts all dispatches before collecting acknowledgement results.

• 200: every target succeeded.
• 207: mixed outcomes.
• 502: every target failed.

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.

Robot configuration

The nested onboard-settings and configuration endpoints read or update supported robot-local configuration:

GET  …/robots/{robot_id}/onboard-settings
POST …/robots/{robot_id}/onboard-settings
GET  …/robots/{robot_id}/config
POST …/robots/{robot_id}/config

These are request and response operations. A write succeeds only after the robot reports the result. A robot must opt into remote configuration where applicable.

Related

• Agent API
• Telemetry
• Operations