Skip to content

Post robot maintenance (beta)

Beta
POST
/v1/robots/maintenance
curl --request POST \
--url https://api.example.yas/v1/robots/maintenance \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "partnerId": "partner", "schemaVersion": "2026-11", "sourceSystem": "partner-export", "robotId": "rbt_example", "maintenanceId": "mnt_1001", "timezone": "Asia/Hong_Kong", "component": "drive", "downtimeStart": "2026-10-15T12:00:00.000Z" }'

Beta. Create or replace one maintenance record with the server key. Send partnerId, schemaVersion, sourceSystem, robotId, maintenanceId, and timezone. The robot must already exist for this partnerId. An unknown robotId is 404. A later call with the same partnerId, robotId, and maintenanceId replaces the stored body. Leave an optional field out and it is cleared. updatedAt is ISO-8601 UTC.

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

Robot id. The robot must already exist.

string
maintenanceId
required

Id of this service visit. The same partner, robot, and maintenance id replaces the stored body.

string
timezone
required

IANA timezone. Example: Asia/Hong_Kong.

string
taskInstanceId

Task instance this visit relates to, when there is one.

string
eventId

Event id this visit relates to, when there is one.

string
complaint

What was reported.

string
diagnosis

What was found.

string
component

Part that was serviced. Example: drive.

string
partReplacement

Part that was replaced.

string
correctiveAction

What was done.

string
downtimeStart

When downtime started, as ISO-8601.

string format: date-time
downtimeEnd

When downtime ended, as ISO-8601.

string format: date-time
labourHours

Labour hours for this visit.

number
cost

Cost amount. Pair it with currency.

number
currency

Currency code. Example: HKD.

string
recurrence

True when this fault has happened before.

boolean
warranty

True when the visit was under warranty.

boolean
firmwareVersion

Firmware version at the time of this call.

string
metadata

Extra fields from the partner. Stored as sent.

object
key
additional properties
any

Example

{
"partnerId": "partner",
"schemaVersion": "2026-11",
"sourceSystem": "partner-export",
"robotId": "rbt_example",
"maintenanceId": "mnt_1001",
"timezone": "Asia/Hong_Kong",
"component": "drive",
"downtimeStart": "2026-10-15T12:00:00.000Z"
}

Maintenance stored. A later call with the same maintenance id replaces it. updatedAt is ISO-8601 UTC.

Media typeapplication/json
object
robotId
required
string
maintenanceId
required
string
updatedAt
required
string format: date-time

Example

{
"robotId": "rbt_example",
"maintenanceId": "mnt_1001",
"updatedAt": "2026-10-15T13:00:00.000Z"
}
400A required field is missing.
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"
}