Skip to content

Post robot status summaries (beta)

Beta
POST
/v1/robots/summaries/status
curl --request POST \
--url https://api.example.yas/v1/robots/summaries/status \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "partnerId": "partner", "schemaVersion": "2026-11", "sourceSystem": "partner-export", "records": [ { "robotId": "rbt_example", "recordedAt": "2026-10-15T10:00:05.000Z", "timezone": "Asia/Hong_Kong", "periodSeconds": 5, "cloudLink": "up", "wifiRssiDbm": -62, "speedAvgMps": 0.4 } ] }'

Beta. Post 1 to 1000 status records with the server key. Each record covers 1 to 5 seconds and needs robotId, recordedAt, timezone, and periodSeconds. Connectivity, movement, and pose fields are optional. xM, yM, and zM are metres in the map frame. Prefer a mapId you already completed. A missing map is still stored. YAS counts online and active time from operatingMode. Online counts only an explicit idle, autonomous, manual, or charging. A window that omits operatingMode is not online and not active. idle and charging are online and not active. Active time is autonomous or manual. moving is recorded on its own and is not added to those totals. The robot must already exist for this partnerId. An unknown robotId is 404; nothing in the call is stored. An empty list, a missing field, periodSeconds outside 1 to 5, or an unknown operatingMode is 400. More than 1000 records is 413. Records have no id. Post the same window again and YAS stores another row. accepted equals the number of records.

Media typeapplication/json
object
partnerId
required

Partner id. It must match the server key.

string
schemaVersion
required

Schema version of this body. Example: 2026-11.

string
sourceSystem
required

Name of the system that sent this body. Example: partner-export.

string
firmwareVersion

Firmware version at the time of this call.

string
metadata

Extra fields from the partner. Stored as sent.

object
key
additional properties
any
records
required

Status windows in this call. Send 1 to 1000.

Array<object>
>= 1 items <= 1000 items
object
robotId
required

Robot id. The robot must already exist.

string
recordedAt
required

When this window ended, as ISO-8601 UTC.

string format: date-time
timezone
required

IANA timezone. Example: Asia/Hong_Kong.

string
periodSeconds
required

Length of this window in seconds. Allowed range is 1 to 5.

integer
>= 1 <= 5
powerOk

True when main power was present during the window.

boolean
controllerState

Controller state. Example: ready.

string
cloudLink

Cloud link during the window. Example: up.

string
wifiRssiDbm

Wi-Fi signal strength in dBm.

number
accessPointOrZone

Access point or zone name.

string
latencyMs

Round-trip latency in milliseconds.

number
packetLossPct

Packet loss as a percent.

number
reconnectCount

How many times the link reconnected in the window.

integer
offlineReason

Why the robot was offline. Send this when operatingMode is offline.

string
distanceM

Distance travelled in this window, in metres.

number
speedAvgMps

Average speed in metres per second.

number
speedMaxMps

Highest speed in this window, in metres per second.

number
localisationQuality

Localisation quality from 0 to 1.

number
<= 1
mapId

Map this pose uses. Prefer a map already completed. A missing map is still stored.

string
xM

X in the map frame. One unit is one metre.

number
yM

Y in the map frame. One unit is one metre.

number
zM

Z in the map frame when the partner has height. One unit is one metre.

number
operatingMode

How the robot was working. offline is not online. idle and charging are online and not active. autonomous and manual are online and active. Omit the field and the window is not online and not active.

string
Allowed values: offline idle autonomous manual charging
moving

True when the robot was in motion during the window. This is separate from operatingMode and is not added to online or active time.

boolean
sharedSpace

True when the robot was in a space shared with people.

boolean

Example

{
"partnerId": "partner",
"schemaVersion": "2026-11",
"sourceSystem": "partner-export",
"records": [
{
"robotId": "rbt_example",
"recordedAt": "2026-10-15T10:00:05.000Z",
"timezone": "Asia/Hong_Kong",
"periodSeconds": 5,
"cloudLink": "up",
"wifiRssiDbm": -62,
"speedAvgMps": 0.4
}
]
}

Status records stored. accepted equals the number of records.

Media typeapplication/json
object
accepted
required
integer

Example

{
"accepted": 1
}
400The records list is empty, a required field is missing, `periodSeconds` is outside 1 to 5, or `operatingMode` is not one of the allowed values.
Media typeapplication/json
object
error
required

Stable error code. No stack trace.

string

Example

{
"error": "invalid_body"
}
401The server key is missing or wrong.
Media typeapplication/json
object
error
required

Stable error code. No stack trace.

string

Example

{
"error": "invalid_credentials"
}
403A server key may be limited to vehicles, robots, or both. A call outside that limit is 403 `forbidden` and stores nothing. `identity_mismatch` means `partnerId` does not match the server key.
Media typeapplication/json
object
error
required

Stable error code. No stack trace.

string

Example

{
"error": "forbidden"
}
404Unknown `robotId`. Nothing in this call is stored.
Media typeapplication/json
object
error
required

Stable error code. No stack trace.

string

Example

{
"error": "not_found"
}
413More than 1000 records. Nothing is stored.
Media typeapplication/json
object
error
required

Stable error code. No stack trace.

string

Example

{
"error": "payload_too_large"
}