Skip to content

Post robot task (beta)

Beta
POST
/v1/robots/tasks
curl --request POST \
--url https://api.example.yas/v1/robots/tasks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "partnerId": "partner", "schemaVersion": "2026-11", "sourceSystem": "partner-export", "robotId": "rbt_example", "taskInstanceId": "task_1001", "taskId": "patrol_12", "taskType": "patrol", "keywords": [ "shared_space", "night" ], "executeStart": "2026-10-15T10:00:00.000Z", "timezone": "Asia/Hong_Kong", "status": "complete" }'

Beta. Create or replace one task with the server key. Send partnerId, schemaVersion, sourceSystem, robotId, taskInstanceId, executeStart, and timezone. The robot must already exist for this partnerId. An unknown robotId is 404. A later call with the same partnerId, robotId, and taskInstanceId replaces the stored body. Leave an optional field out and it is cleared. Examples for taskType are patrol and charging. Examples for keywords are shared_space, night, and heavy_traffic. Other words are stored. Leave keywords out and it is cleared. An empty list stores no words. 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
taskInstanceId
required

Id of this run of the task. The same partner, robot, and task instance replaces the stored body.

string
executeStart
required

When the task started, as ISO-8601.

string format: date-time
timezone
required

IANA timezone. Example: Asia/Hong_Kong.

string
taskId

Partner task definition id. Example: patrol_12.

string
taskType

What the robot was doing. Examples: patrol, charging.

string
keywords

Words that describe this task. YAS uses them later to group similar tasks. Examples: shared_space, night, heavy_traffic. Other words are stored.

Array<string>
<= 32 items
executeEnd

When the task ended, as ISO-8601.

string format: date-time
status

Task status. Any other value is rejected.

string
Allowed values: planned running complete failed cancelled
closer

Who ended the task: robot, operator, or partner.

string
Allowed values: robot operator partner
isArrived

True when the robot reached the goal.

boolean
routeId

Route id.

string
distanceM

Mission distance in metres.

number
durationSeconds

Mission length in seconds.

number
startSoc

State of charge at the start, as a percent.

number
endSoc

State of charge at the end, as a percent.

number
interventionCount

How many interventions happened during the task.

integer
abnormalReason

Why the task was abnormal.

string
siteId

Site id.

string
sharedSpace

True when the task runs in a space shared with people.

boolean
outcome

How the task ended: complete, interrupted, or aborted.

string
Allowed values: complete interrupted aborted
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",
"taskInstanceId": "task_1001",
"taskId": "patrol_12",
"taskType": "patrol",
"keywords": [
"shared_space",
"night"
],
"executeStart": "2026-10-15T10:00:00.000Z",
"timezone": "Asia/Hong_Kong",
"status": "complete"
}

Task stored. A later call with the same task instance replaces it. updatedAt is ISO-8601 UTC.

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

Example

{
"robotId": "rbt_example",
"taskInstanceId": "task_1001",
"updatedAt": "2026-10-15T10:45:00.000Z"
}
400A required field is missing, or `status`, `closer`, or `outcome` 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"
}