Skip to content

Post robot events (beta)

Beta
POST
/v1/robots/events
curl --request POST \
--url https://api.example.yas/v1/robots/events \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "partnerId": "partner", "schemaVersion": "2026-11", "sourceSystem": "partner-export", "events": [ { "robotId": "rbt_example", "eventId": "evt_1001", "eventStart": "2026-10-15T10:00:00.000Z", "timezone": "Asia/Hong_Kong", "type": "mode_change", "nativeCode": "100", "nativeDescription": "Autonomous moving" } ] }'

Beta. Post 1 to 500 events with the server key. Each event needs robotId, eventId, eventStart, timezone, type, and nativeCode. type is mode_change, alarm, intervention, navigation, incident, task_state, software_change, or proximity. For a proximity event, send distanceM, objectMotion, and subject when you know them. 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, or an unknown type, objectMotion, subject, resolution, or consequence is 400. More than 500 events is 413. A repeated partnerId, robotId, and eventId keeps the first body. Fields for another type are stored and are not a 400. accepted is new rows. duplicates is rows already stored. eventIds lists every id in order. accepted plus duplicates equals the number of events.

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
events
required

Events in this call. Send 1 to 500.

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

Robot id. The robot must already exist.

string
eventId
required

Partner event id. The same partner, robot, and event id keeps the first body.

string
eventStart
required

When the episode started, as ISO-8601.

string format: date-time
timezone
required

IANA timezone. Example: Asia/Hong_Kong.

string
type
required

Kind of event.

string
Allowed values: mode_change alarm intervention navigation incident task_state software_change proximity
nativeCode
required

Partner code for this event.

string
nativeDescription

Partner text for nativeCode.

string
taskInstanceId

Task instance this event belongs to, when there is one.

string
siteId

Site id.

string
zoneId

Zone id inside the site.

string
eventEnd

When the episode ended, as ISO-8601.

string format: date-time
updateTime

When this body was last updated, as ISO-8601.

string format: date-time
durationSeconds

Length of the episode in seconds. This is not the response lag.

number
reasonCode

Partner reason code.

string
modeBefore

Operating mode before the event.

string
modeDuring

Operating mode during the event.

string
modeAfter

Operating mode after the event.

string
taskStatus

Task status the partner recorded on this event.

string
sourceRecordId

Id of the source record in the partner system.

string
confidence

Confidence from 0 to 1.

number
<= 1
missing

True when the robot did not identify the episode and a person or system filled the first stored body. A repeat of this event id still keeps that first body.

boolean
duplicate

True when the partner marks this row as a duplicate of another event.

boolean
annotated

True when a person added detail after the first body was stored.

boolean
operatorAction

What the operator did. Examples: take_over, clear_path.

string
guided

True when a person guided the robot through the episode.

boolean
repositioned

True when the robot was moved by hand or by a remote command.

boolean
reset

True when the robot was reset during the episode.

boolean
consequence

What followed an incident or a near contact.

string
Allowed values: none near_miss contact damage injury
obstacleClass

Obstacle class. Example: cart.

string
stopReason

Why the robot stopped. Examples: obstacle, estop.

string
rerouteAttempts

How many times the robot tried another path.

integer
recoveryType

How the robot recovered. Examples: reroute, wait.

string
contactOrNearContact

True when there was contact or a near contact.

boolean
incidentClass

Incident class. Example: collision.

string
injuryOrDamage

True when someone was hurt or something was damaged.

boolean
evidenceRef

Pointer to evidence held by the partner. YAS does not fetch it.

string
resolution

How the episode ended.

string
Allowed values: recovered takeover unresolved aborted
version

Software version after the change.

string
changeReason

Why the software changed.

string
rollback

True when this change rolled software back.

boolean
mapOrConfigUpdate

True when this change updated a map or a config.

boolean
distanceM

Metres to the object or person. This is not distance travelled.

number
objectMotion

Whether the object was still or moving.

string
Allowed values: static dynamic unknown
subject

Whether the nearby thing was a person.

string
Allowed values: human non_human unknown
responseSeconds

Seconds from detection to the first action. Omit the field when unknown. Do not send null.

number

Example

{
"partnerId": "partner",
"schemaVersion": "2026-11",
"sourceSystem": "partner-export",
"events": [
{
"robotId": "rbt_example",
"eventId": "evt_1001",
"eventStart": "2026-10-15T10:00:00.000Z",
"timezone": "Asia/Hong_Kong",
"type": "mode_change",
"nativeCode": "100",
"nativeDescription": "Autonomous moving"
}
]
}

Events stored. accepted is new rows. duplicates is rows already stored for that partner, robot, and event id. eventIds lists every id in order.

Media typeapplication/json
object
accepted
required
integer
duplicates
required
integer
eventIds
required
Array<string>

Example

{
"accepted": 1,
"duplicates": 0,
"eventIds": [
"evt_1001"
]
}
400The events list is empty, a required field is missing, or `type`, `objectMotion`, `subject`, `resolution`, or `consequence` 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 500 events. Nothing is stored.
Media typeapplication/json
object
error
required

Stable error code. No stack trace.

string

Example

{
"error": "payload_too_large"
}