Robots

A robot is an individual device enrolled in a fleet that runs missions and reports telemetry.

What it represents

Each robot belongs to a fleet and has an identity, capabilities, and a current status. The API lets you list the robots in a fleet, read a robot's detail, and read its last-known position and current mission. Live position, heading, battery, mode, and health are covered under telemetry; the work a robot performs is described under operations.

Authentication

All robot endpoints are called with an API key. The read endpoints require robots:read; editing a robot, pushing settings, cancelling a mission, and the live robot commands require robots:write. Setting a mission run's status uses missions:write, and the operator overrides use operations:control. See Authentication.

List robots in a fleet

GET /v1/orgs/{org_id}/fleets/{fleet_id}/robots

Returns a summary for each robot in the fleet. Optional query filters narrow the result:

Filter	Description
`status`	Match a robot status string (for example `running`).
`capability`	Only robots that provide this service capability.
`robot_type`	Match the robot type (for example `robot`, `simulator`, `device`).
`available`	`true` or `false`: whether the robot is free to take new work.
`online`	`true` or `false`: whether the robot is currently reporting.

Response:

{
  "items": [
    {
      "robot_id": "a1b2…",
      "name": "Mower 1",
      "type": "robot",
      "status": "running",
      "online": true,
      "available": false,
      "availability_reason": null,
      "capabilities": ["mowing"],
      "current_operation_ref": "op-uuid",
      "current_mission_ref": "mission-uuid"
    }
  ],
  "next_cursor": null
}

available is true when the robot is online, has no current assignment, and is not running a mission. When availability cannot be determined (for example, no live data is flowing), available is null and availability_reason explains why. current_operation_ref and current_mission_ref are references; resolve them through operations and mission history.

Get one robot

GET /v1/orgs/{org_id}/fleets/{fleet_id}/robots/{robot_id}

Returns the robot's detail: identity, status, capabilities, a lightweight health summary, and references to any current operation and mission. No credentials or secrets are ever returned. A robot id that does not belong to the fleet in the path returns 404.

Response:

{
  "robot_id": "a1b2…",
  "name": "Mower 1",
  "type": "robot",
  "status": "running",
  "online": true,
  "available": false,
  "availability_reason": null,
  "capabilities": ["mowing"],
  "current_operation_ref": "op-uuid",
  "current_mission_ref": "mission-uuid",
  "health": {
    "faulted": false,
    "estop_active": false,
    "accepting_missions": true,
    "mode": "auto",
    "battery_soc_pct": 80.0,
    "fuel_level_pct": null,
    "range_remaining_m": null
  },
  "metadata": {
    "agent_version": "1.4.2",
    "software_version": "2026.6.0",
    "vehicle_make": "Acme",
    "vehicle_model": "RX-1"
  },
  "updated_at": "2026-06-18T17:00:00Z"
}

Robot usage and health

GET /v1/robots/{robot_id}/details

Returns a robot's lifetime usage totals (its "odometer") and the latest per-device system health. This is slow-moving summary data, not live telemetry. Permission: robots:read.

Response:

{
  "usageStats": {
    "updatedAt": "2026-06-18T16:00:00Z",
    "totalDistanceM": 1500.5,
    "autoDistanceM": 1000.0,
    "manualDistanceM": 500.5,
    "uptimeTotalS": 86400.0,
    "driveTimeTotalS": 3600.0,
    "autoTimeTotalS": 2400.0,
    "missionCountTotal": 12,
    "chargeCyclesTotal": 5,
    "rebootCount": 2,
    "lastRebootAt": "2026-06-17T22:00:00Z"
  },
  "systemHealth": [
    {
      "deviceId": "compute-0",
      "updatedAt": "2026-06-18T16:00:00Z",
      "cpuPct": 45.2,
      "memPct": 62.1,
      "diskPct": 78.5,
      "cpuTemp": 65.3,
      "signalStrength": -75.0,
      "signalQuality": 85.0
    }
  ]
}

usageStats is null when the robot has no usage row, and systemHealth is null when no device has reported health.

Detailed robot records (top-level)

The nested list above returns compact, reference-style summaries. Two top-level endpoints instead return the full robot record with inline live telemetry (position, velocity, battery, mode, e-stop), which is handy when you want everything in one call.

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

GET /v1/robots requires fleet_id and returns a JSON array; the single-robot form returns one object of the same shape. Permission: robots:read.

[
  {
    "id": "a1b2…",
    "name": "Rover-1",
    "fleet_id": "fleet-uuid",
    "status": "running",
    "online": true,
    "type": "robot",
    "battery_soc_pct": 80.0,
    "gps_fix": "fixedRtk",
    "heading_deg": 90.0,
    "current_mission_id": null,
    "motionTelemetry": {
      "unixTimeMs": 1750262400000,
      "pose": { "latDeg": 45.5, "lonDeg": -122.6, "altitudeM": 30.0, "headingDeg": 90.0 },
      "velocity": { "linearMps": 1.5, "angularRps": 0.0 },
      "gpsFix": "fixedRtk", "gpsSource": "real"
    },
    "statusTelemetry": {
      "unixTimeMs": 1750262400000,
      "battery": { "socPct": 80.0, "powerSupplyStatus": "discharging" },
      "mode": "auto", "estop": { "active": false, "ids": [] },
      "faulted": false, "acceptingMissions": true, "status": "running"
    }
  }
]

status reflects live telemetry when present, falling back to the stored status. online is true when the robot reported within the last couple of seconds. motionTelemetry and statusTelemetry are null when no telemetry is present. For agent integrations, prefer the nested list and position endpoints, which return stable reference-based shapes.

Position and current mission

A robot's last-known position and live mission state are read through dedicated endpoints:

GET …/robots/{robot_id}/position: see Telemetry.
GET …/robots/{robot_id}/mission: see Telemetry.

Edit or transfer a robot

PATCH /v1/robots/{robot_id}

Edits a robot's mutable fields, and transfers it to another fleet when you change its fleet_id. Permission: robots:write (a transfer also requires robots:write on the destination fleet).

All body fields are optional; an omitted field is left unchanged. vehicle_make, vehicle_model, and link accept an explicit null to clear them.

{
  "name": "Mower 1",
  "status": "maintenance",
  "vehicle_make": "Acme",
  "vehicle_model": "RX-1",
  "link": null,
  "type": "robot",
  "fleet_id": "destination-fleet-uuid"
}

A transfer is rejected with 400 while the robot is running a mission. On success the updated robot is returned in the same shape as Get one robot.

Push settings to a robot

POST /v1/orgs/{org_id}/fleets/{fleet_id}/robots/{robot_id}/settings

Sends one or more setting updates to a robot. Permission: robots:write. The robot must belong to the fleet in the path.

{ "settings": [ { "key": "max_speed_mps", "value": 1.5 } ] }

Response:

{ "success": true, "robotId": "a1b2…" }

Cancel a mission on a robot

DELETE /v1/orgs/{org_id}/fleets/{fleet_id}/robots/{robot_id}/missions/{mission_id}

Removes a mission from a robot. Permission: robots:write. The robot must belong to the fleet in the path.

Response:

{ "success": true, "robotId": "a1b2…", "missionId": "mission-uuid" }

Command a robot

Real-time control commands sent straight to a robot, mirroring the controls in the Fleet Manager web app. Each requires the robot to belong to the fleet in the path and returns { "success": true, "robotId": "…" }.

Safety. These commands move and act on physical hardware. Confirm the robot is clear to move and that you have an independent stop control before issuing them.

Method and path	Action	Permission	Body
`POST …/robots/{robot_id}/go-to`	Drive to a target pose.	`robots:write`	`{ "target": <GeoPose> }`
`POST …/robots/{robot_id}/stop`	Pause the robot's activity.	`robots:write`	none
`POST …/robots/{robot_id}/resume`	Resume the robot's activity.	`robots:write`	none
`POST …/robots/{robot_id}/mode`	Set the operating mode.	`robots:write`	`{ "mode": "auto" }` (`manual`, `auto`, `teleop`, or `idle`)
`POST …/robots/{robot_id}/invoke-service`	Call a capability the robot advertises.	`robots:write`	`{ "serviceName": "…", "setting": true }` (`setting` optional)
`POST …/robots/{robot_id}/mission-run-status`	Set the status of a mission run on the robot.	`missions:write`	`{ "missionId": "…", "runId": "…", "status": "paused" }`

A go-to target is a geographic pose (longitude/latitude in decimal degrees, altitude in meters, heading in degrees clockwise from north):

{ "target": { "lonDeg": -122.6, "latDeg": 45.5, "altitudeM": 30.0, "headingDeg": 90.0 } }

A mission-run-status status is a mission status value such as running, paused, aborted, or completed.

Operator overrides

Two override commands clear stuck state. Both require operations:control, take no body, and return { "success": true, "robotId": "…" }.

Method and path	Action
`POST …/robots/{robot_id}/release`	Clear the robot's operator hold across all operations.
`POST …/robots/{robot_id}/force-reset`	Clear the robot's current assignment and mission so it can be re-dispatched. This is a server-side reset only; nothing is sent to the robot.

Managing robots

Enrolling and removing robots is done in the Fleet Manager web app and the robot onboarding flow; those actions are not exposed to API keys.

Robots

What it represents

Authentication

List robots in a fleet

Get one robot

Robot usage and health

Detailed robot records (top-level)

Position and current mission

Edit or transfer a robot

Push settings to a robot

Cancel a mission on a robot

Command a robot

Operator overrides

Managing robots

Related