Skip to main content

Task Manager

Availability

These endpoints require an Agent version that supports Task Manager REST access. Older versions may return 404. This page describes the Local API hosted by Agent.

The Local API lets an external application list configured robot tasks, request a run or cancellation, and inspect the latest run status. It uses the Gateway /apigateway/v2 prefix and Local API Gateway authentication. DisableLocalApi also disables these routes.

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.

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 do not accept a name instead of an ID.

Configure task definitions with the existing Task Manager UI or Task Manager CLI.

HTTP Outcomes​

  • List and status return 200.
  • Run and cancel return 202 with a command acknowledgment.
  • 401: the required local Gateway bearer token is missing or invalid.
  • 403: Local API Gateway is disabled.
  • 404: the robot or task does not exist.
  • 409: an active run conflicts with a run request, or cancellation targets an idle task.

Run And Cancellation Results​

Run/cancel responses acknowledge the request. They contain the task ID, command, acceptance 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.

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.

A previous run result can remain available after an Agent restart while its history is retained. 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.

Local Scope​

Use a local robot ID returned by the Agent's robot listing. You can also address a configured local-fleet member when its Agent supports these endpoints.