Robot integration
Connecting a robot
From zero to fetching a signed manifest, in the order you actually need to do it.
Robots talk to one URL: api.waveform.vision/v1/.... The integration has four steps, executed in this order:
- Register the robot as an admin user.
POST /v1/robotscreates the row incore.robot_devices. - Issue a device token for that robot.
POST /v1/robots/<id>/tokensreturns an HS256 JWT — exactly once. Cache it on the device. - Resolve the area the robot operates at.
POST /v1/areas/resolvetakes a bbox or site id and returns the canonicalarea_id. - Fetch the manifest.
GET /v1/areas/<area_id>/nav-packwith the robot’s token returns the latest signed pack scoped to its profile.
All-in-one example
Here it is end-to-end, with the response of each call feeding the next. (Bash + curl for clarity; you’d normally do steps 1–2 once per robot, steps 3–4 on every fetch.)
bash
# Variables you'll have at hand
ADMIN_TOKEN=<platform-admin-cognito-jwt>
SITE_ID=<your_site_uuid>
# 1. Register
ROBOT=$(curl -s -X POST https://api.waveform.vision/v1/robots \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"fleet_id":"depot-north","display_name":"r1"}')
ROBOT_ID=$(echo "$ROBOT" | jq -r '.data.robot_id')
# 2. Issue token
TOKEN_PAYLOAD=$(curl -s -X POST "https://api.waveform.vision/v1/robots/$ROBOT_ID/tokens" \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"scopes":["nav_pack:read"]}')
DEVICE_TOKEN=$(echo "$TOKEN_PAYLOAD" | jq -r '.data.token')
# 3. Resolve the area
AREA_ID=$(curl -s -X POST https://api.waveform.vision/v1/areas/resolve \
-H "Authorization: Bearer $DEVICE_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"site_ids\":[\"$SITE_ID\"]}" \
| jq -r '.data.area_id')
# 4. Fetch the manifest (the robot does this every operation)
curl -s "https://api.waveform.vision/v1/areas/$AREA_ID/nav-pack" \
-H "Authorization: Bearer $DEVICE_TOKEN"Use an SDK
The HTTP surface is hand-friendly, but on a real robot you’ll want a typed client. See the Python SDK for an admin runner and the Swift SDK for iOS / macOS consumers.