Getting started
Send robot data from your backend with the server key. Create the robot first. The other calls need that robot.
PUT /v1/robots/{robotId}(beta) — Asset record. Send once, then when it changes.POST /v1/robots/maps(beta) — Floor grid or point cloud. Complete the upload.POST /v1/robots/events(beta) — Mode, alarm, intervention, navigation, incident, task state, software change, or proximity.POST /v1/robots/summaries/status(beta) — Every 1–5 seconds. Connectivity, movement, localisation, and pose.POST /v1/robots/summaries/components(beta) — Every 10–60 seconds. Battery, drive, perception, surroundings.POST /v1/robots/tasks(beta) — One record per task.POST /v1/robots/maintenance(beta) — One record per service visit.
A later robot, task, or maintenance call replaces what was stored. Send every field you still want. The map you already completed stays until the next complete succeeds. Events keep the first body for the same partner, robot, and event id.
Status and component records have no id. Post the same window again and YAS stores another row.
xM, yM, and zM are metres in the map frame. Complete the map before the pose when you can. A status row is still stored if that mapId was never completed.
YAS counts time from operatingMode:
- Online is an explicit
idle,autonomous,manual, orcharging. Leave the field out and that window is not online and not active. idleandchargingare online, not active.- Active is
autonomousormanual. movingis separate. It is not added to online or active time.
Use proximity when a person or object is nearby. Use the other event types for an interruption and how it ended.
Field names and payloads are on each operation page.
Map uploads
Section titled “Map uploads”Use the map operation’s JSON example to mint an upload, PUT the file to the returned uploadUrl with Content-Type: application/octet-stream, then call complete with the same partnerId, robotId and mapId. The JSON contentType describes the map format (occupancy_grid or point_cloud); it is separate from the HTTP upload header.
The current file maximum is 50 MiB (or a lower configured Storage limit). The upload credential lasts two hours; complete must finish within 24 hours of minting. Bytes enter private Storage before complete. Complete checks the actual size; a wrong-size file may temporarily occupy Storage but cannot become ready. On 422 invalid_media, mint again rather than overwriting the object.
Minting a replacement leaves the current map usable. Only successful complete replaces it. A later mint supersedes an unfinished upload for the same map; serialize replacements for a map and complete the latest attempt. Repeating successful complete returns ready without changing the map timestamp.
Map uploads require byteLength and the signed upload → complete flow. Requests containing contentBase64 return 400 invalid_body; no inline map upload is supported.
API region
Section titled “API region”For database-heavy calls to the Supabase-hosted API, send x-region: ap-southeast-1 to run near the Singapore database. Check x-sb-edge-region in the response. Pinning disables automatic regional failover; change or remove the header during a regional outage. This header is for API calls, not uploads to returned Storage URLs. See Supabase regional invocation.
