REST API

The REST API lets any program steer the robot with plain HTTP: a script that sets the eyes, a dashboard that shows the battery, a test that reads a sensor. It runs inside the robot program next to the MessagePack API and takes the same command path as the brain, so the watchdog, HULKs' motion safety and the death switch apply to it in the same way. On the robot, health, identity, the death switch status, the state and the LEDs (per group and per single LED) have been checked live.

ROBOT=<robot-address>
TOKEN=$(ssh nao@$ROBOT cat .config/nao-rs/rest-token)
curl -H "Authorization: Bearer $TOKEN" http://$ROBOT:7702/v1/state

Access

LAN only. The API answers clients on loopback, the private IPv4 networks (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), link-local (169.254.0.0/16, fe80::/10) and IPv6 unique local addresses (fc00::/7). Anyone else gets 403 not_on_lan. Tailscale addresses (100.64.0.0/10) are not allowed by default; start the robot program with NAO_RS_REST_ALLOW=100.64.0.0/10 to allow them.

Token. The robot program creates a token on its first start, 32 random bytes, in ~/.config/nao-rs/rest-token of the user it runs as (nao on the robot), mode 0600. Send it as Authorization: Bearer <token>. GET requests may pass it as ?access_token=<token> instead, so a browser can open a camera stream in an img element. Three endpoints need no token: GET /v1/health, GET /v1/openapi.json and POST /v1/safety/stop.

Rate limit. 50 requests per second per client address, bursts up to twice that; above it, 429 rate_limited with the time to wait.

Settings

Set in the robot program's environment:

Control

Reading is free for every client with the token. Commanding needs control, and only one controller exists at a time:

1. POST /v1/control with {"client": "<name>"} returns a lease.
2. Send the lease id in the Nao-Lease header with every command. Without it: 428 missing_lease.
3. Send a heartbeat (POST /v1/control/heartbeat) or any command at least every 100 ms. After 0.5 s of silence the robot stands, after 3 s it sits, and after 10 s the lease ends.
4. DELETE /v1/control releases it.

WebSocket control

GET /v1/control/ws upgrades to a WebSocket that holds control for as long as it is open, like the brain's TCP connection; closing it gives control back. Pass the token as ?access_token= or in the header, and send {"type": "hello", "client": "<name>"} within 5 s.

The same watchdog applies: send something at least every 100 ms. Limits: 100 messages per second, 64 KiB per message.

websocat "ws://$ROBOT:7702/v1/control/ws?access_token=$TOKEN"
{"type": "hello", "client": "pad", "id": 1}
{"type": "leds", "group": "eyes", "setting": {"color": "#0050ff"}, "id": 2}
{"type": "volume", "volume": {"percent": 40}, "id": 3}

Safety

POST /v1/safety/stop trips the death switch in two ways at once: it writes the switch page directly (reason Api) and sends the guard's UDP stop, so it works even when the robot program hangs. It needs no token and no lease. GET /v1/safety shows the switch. Nothing in the API can re-arm it: that stays naoctl rearm on the robot. See Safety model.

The switch's reason (in GET /v1/safety and the safety event) is one of the SwitchReason values, the same names as the death switch's reason codes. A page without its magic value reads as tripped with PageLost. A page cut short is not read at all: the switch shows available: false, with an unavailable_reason, and the drivers treat it as tripped. See Page integrity.

Errors

Every error has the same shape and a stable code:

{"error": {"code": "missing_lease", "message": "this command needs control: take a lease with POST /v1/control and send its id in the `Nao-Lease` header"}}

field names the input at fault when there is one. Each operation's page lists the statuses it returns.

Streams

The number of open streams is limited; one too many gets 503 too_many_streams.

Try it without a robot

The nao-rs repository has a pretend robot that serves the same API:

cargo run -p nao_rs_rest --example mock_robot   # prints where it put the token
curl localhost:7702/v1/health

It has no motors and no death switch page; its stop sends the UDP stop to localhost, where no guard listens.

Reference

Security