Skip to main content

Task Manager

Availability

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​

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.

HTTP Outcomes​

  • List and status return 200.
  • Run and cancel return 202 with 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:

  • 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.

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.