Task Manager
Local endpoints require an Agent version that supports Task Manager REST access. Older versions
may return 404. Cloud commands require an Agent that supports the corresponding task commands.
The API lets an external application list configured robot tasks, request a run or cancellation,
and inspect the latest run status. Cloud and Local use the Gateway /apigateway/v2 prefix and
the same response fields and task HTTP outcomes described below. Authentication, robot scope,
data freshness and connectivity depend on the host.
Operations
GET /robots/{robotId}/tasks: list task summaries.POST /robots/{robotId}/tasks/{taskId}/run: request a run.POST /robots/{robotId}/tasks/{taskId}/cancel: request cancellation of the run.GET /robots/{robotId}/tasks/{taskId}/status: retrieve the latest run status.
Each listed summary contains taskId, name, description and enabled.
The list response wraps the summaries in a tasks array:
{
"tasks": [
{
"taskId": "task-1",
"name": "Wait",
"description": "Wait for twenty seconds.",
"enabled": true
}
]
}
taskId is the stable ID returned by the task listing. Keep it for run, cancellation and status
requests. Task names are display values; these routes require a task ID and reject a task name
used in its place.
Configure task definitions with the existing Task Manager UI or Task Manager CLI.
Authentication And Robot Scope
- Cloud
- Local
Use Cloud API Gateway authentication and a robot ID returned by the Cloud robot listing. The caller must have access to the robot.
Task listings and status reflect the latest task metrics reported to Cloud and can lag the Agent's
current state. A missing task catalog produces an empty tasks array. Run and cancel send a command
to the selected robot and wait for its acknowledgment.
Use Local API Gateway authentication and a robot ID returned by the Agent's
robot listing. DisableLocalApi also disables these routes. You can address a configured local-fleet
member when its Agent supports these endpoints.
Local requests read the selected Agent's task catalog and current or retained run state. A previous run result can remain available after an Agent restart while its history is retained.
HTTP Outcomes
- List and status return
200. - Run and cancel return
202with a command acknowledgment. 401: the required Gateway bearer token is missing or invalid.404: the robot or task does not exist.409: an active run conflicts with a run request, or cancellation targets an idle task.
An existing task without run information returns 200 with latestRun: null. An unknown task ID
returns 404.
Additional host-specific outcomes:
- Cloud
- Local
400: the Agent rejected the command as an invalid request.404: the robot is not accessible to the caller.409: the Agent refused the command for any reason other than an invalid request or an unknown task.503: the robot is offline.504: the Agent acknowledgment did not arrive before the command timeout.
403: Local API Gateway is disabled.
Run And Cancellation Results
Successful run/cancel responses acknowledge acceptance with accepted: true. They contain the
task ID, command, run ID and message. runId is null when unavailable. An accepted run request
is not proof that execution has finished. An accepted cancellation is not proof that a robot has
physically stopped.
Example accepted run acknowledgment:
{
"taskId": "task-1",
"command": "run",
"accepted": true,
"runId": "run-1",
"message": "Task execution request accepted."
}
message is display text. Do not parse it to determine task or run identity or execution state.
The status response contains taskId and latestRun. latestRun is null when no run information
is available, for example when a task has never run or its history has expired. Otherwise it
includes the run ID/state, UTC timestamps, current subtask position/name when known, state label
and terminal reason. States are running, completed, canceled and failed.
Current subtask fields are null when that information is unavailable.
Task completion means the runner reached the end of its configured flow. Individual steps can have unsuccessful or timeout outcomes, so completion alone does not prove successful navigation.