Robot interaction

List robots

GET /v1/robots

Requires robots:read. Returns your org's robots with a live-state summary.

curl https://api-prod.avearobotics.com/v1/robots \
  -H "Authorization: Bearer ak_..."

{
  "robots": [
    {
      "id": "5f3a9c2e-...",
      "name": "Sort station A",
      "session_name": "unit-04",
      "active": true,
      "created_at": "2026-06-12T18:03:11Z"
    }
  ],
  "cursor": null
}

Get one robot

GET /v1/robots/{id}

Requires robots:read. {id} is the robot UUID or its session_name.

Send a command

Commands are typed endpoints, one per verb. There is no generic command passthrough.

POST /v1/robots/{id}/go-home
POST /v1/robots/{id}/go-to-start
POST /v1/robots/{id}/start-autonomous
POST /v1/robots/{id}/stop-autonomous

Requires robots:command. The platform relays the command to the robot and waits for the robot to acknowledge execution. The call returns when the robot accepts the command, not when motion completes.

curl -X POST https://api-prod.avearobotics.com/v1/robots/unit-04/go-home \
  -H "Authorization: Bearer ak_..."

{
  "status": "ok",
  "result": {
    "cmd_id": "cmd-a1b2c3d4e5f6",
    "command": "go_home",
    "robot_id": "5f3a9c2e-...",
    "ok": true
  }
}

Response	Meaning
`200`	Robot acknowledged the command
`404 not_found`	No such robot in your org
`422 validation_failed`	The robot's runtime does not support this command
`429 rate_limited`	Too many commands in flight — retry shortly
`500 internal`	Robot ran the command and reported failure
`503 robot_offline`	Robot is not connected
`504 command_timeout`	Robot did not acknowledge in time (about 30 seconds) — it may still execute

Command POSTs support the Idempotency-Key header — send one if you retry, so a retried request cannot dispatch the same command twice. Treat command_timeout as indeterminate: the robot may still run the command.

Commands move real hardware. Confirm the workspace is clear before commanding a robot you cannot see, and keep a physical emergency stop within reach during development. Robot-side action handlers remain responsible for state and safety checks — keep emergency stop on the validated hardware safety path.

Start and stop the runtime stack

POST /v1/robots/{id}/stack/start
POST /v1/robots/{id}/stack/stop
POST /v1/robots/{id}/stack/status

Requires robots:command. These are addressed to the Sentinel daemon on the robot computer, not the runtime — they work even when the runtime container is stopped or crashed. Use them to bring a robot up for a shift, shut it down after, and check the stack state in between.

Episode recording

Recording is controlled through its own endpoints. See Data operations.