Skip to content

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 operations also require the applicable operation permission.

Read robots

For automation, use Agent API tools:

  • query-entities with kind: "robot" to list and filter robots.
  • get-entity with kind: "robot" for identity, live state, capability descriptors, and current settings.
  • get-runtime-status with robot_id for current mission and operation state.

The top-level compatibility endpoints remain available:

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

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

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

Endpoint Purpose
POST …/robots/{robot_id}/go-to Assign a one-shot geographic destination.
POST …/robots/{robot_id}/stop Pause robot activity.
POST …/robots/{robot_id}/resume Resume robot activity.
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 …/robots/{robot_id}/mission-run-status Request a mission-run state change.
POST …/robots/{robot_id}/release Release the robot from operation ownership.
POST …/robots/{robot_id}/force-reset Clear server-side assignment state.

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

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, and release. It starts all dispatches before collecting acknowledgement results.

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

Mode, action invocation, settings update, and force reset require 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.