Robots Center Agents Network
Log in Create workspace
Skip to content

API reference

Operator - Commands

One tag: method, path, summary, auth, and scopes. Request and response fields ship in this page — expand a row to read the contract.

Browse docs

Endpoints

4
GET
/api/v1/operator/agent_commands Web Session

List agent commands

Description

Returns recent agent commands in the current workspace, optionally filtered by service agent or lifecycle status. Results are capped by limit (default 25, maximum 100).

Auth

Web Session
Parameters
Name In Type Required Description
service_agent_id query string No Filter by target service-agent UUID
status query string No Filter by command lifecycle status
limit query integer No Maximum commands to return (default 25, maximum 100)
Responses
200

Recent agent commands
Response Body
Field Type Required Description
agent_commands array<object> Yes Agent commands
agent_commands[].id string Yes Agent command UUID
agent_commands[].status string (queued, dispatched, accepted, running, succeeded, failed, cancelled, timed_out) Yes Current command lifecycle state
agent_commands[].payload object Yes Original command payload
agent_commands[].inserted_at datetime (ISO 8601) Yes Record insertion timestamp
agent_commands[].updated_at datetime (ISO 8601) Yes Record update timestamp
agent_commands[].completed_at datetime (ISO 8601) No Timestamp when the command reached a terminal state
agent_commands[].service_agent object No Target service agent summary
agent_commands[].service_agent.id string Yes Service agent UUID
agent_commands[].service_agent.name string Yes Service agent name
agent_commands[].service_agent.slug string Yes Service agent slug
agent_commands[].correlation_id string Yes Correlation identifier for idempotency and tracing
agent_commands[].accepted_at datetime (ISO 8601) No Timestamp when the agent accepted the command
agent_commands[].cancel_requested_at datetime (ISO 8601) No Timestamp when the operator requested cancellation
agent_commands[].command_type string Yes Application-defined command type
agent_commands[].created_by_user object No User who created the command
agent_commands[].created_by_user.id string Yes User UUID
agent_commands[].created_by_user.email string Yes User email address
agent_commands[].error_payload object Yes Agent-reported error payload
agent_commands[].lease_expires_at datetime (ISO 8601) No Dispatch lease expiry timestamp for unaccepted commands
agent_commands[].result_payload object Yes Agent-reported result payload
POST
/api/v1/operator/agent_commands Web Session

Create agent command

Description

Queues or dispatches a command for a target service agent. This endpoint is restricted to human operator sessions.

Auth

Web Session
Request Body
Field Type Required Description
agent_command object Yes Agent command attributes
agent_command.payload object No Opaque payload delivered to the agent
agent_command.service_agent_id string Yes Target service agent UUID
agent_command.correlation_id string No Optional caller-supplied tracing identifier; it does not deduplicate requests
agent_command.command_type string Yes Application-defined command type
Responses
201

Agent command created

Returns: AgentCommand
Response Body
Field Type Required Description
id string Yes Agent command UUID
status string (queued, dispatched, accepted, running, succeeded, failed, cancelled, timed_out) Yes Current command lifecycle state
payload object Yes Original command payload
inserted_at datetime (ISO 8601) Yes Record insertion timestamp
updated_at datetime (ISO 8601) Yes Record update timestamp
completed_at datetime (ISO 8601) No Timestamp when the command reached a terminal state
service_agent object No Target service agent summary
service_agent.id string Yes Service agent UUID
service_agent.name string Yes Service agent name
service_agent.slug string Yes Service agent slug
correlation_id string Yes Correlation identifier for idempotency and tracing
accepted_at datetime (ISO 8601) No Timestamp when the agent accepted the command
cancel_requested_at datetime (ISO 8601) No Timestamp when the operator requested cancellation
command_type string Yes Application-defined command type
created_by_user object No User who created the command
created_by_user.id string Yes User UUID
created_by_user.email string Yes User email address
error_payload object Yes Agent-reported error payload
lease_expires_at datetime (ISO 8601) No Dispatch lease expiry timestamp for unaccepted commands
result_payload object Yes Agent-reported result payload
Example
{
  "id": "116835e4-02f7-4f5f-b1a0-8e7d3010a3d2",
  "status": "queued",
  "payload": {
    "workflow_target_id": "2d8c8f18-c9fa-47b3-9725-3e0ec602b045"
  },
  "inserted_at": "2026-03-26T12:45:11Z",
  "updated_at": "2026-03-26T12:45:11Z",
  "completed_at": null,
  "service_agent": {
    "id": "a91720d1-1c45-4343-bb45-786e20432f04",
    "name": "Deploy Worker",
    "slug": "deploy-worker"
  },
  "correlation_id": "d6a37d6d-97c1-4aa2-bcee-6d91b3362fa8",
  "accepted_at": null,
  "cancel_requested_at": null,
  "command_type": "deploy.workflow",
  "created_by_user": {
    "id": "5bca08dd-cb95-4102-8efa-55a7a4e8611d",
    "email": "[email protected]"
  },
  "error_payload": {},
  "lease_expires_at": null,
  "result_payload": {}
}
403

Service-agent credentials cannot create operator commands
404

Service agent not found
422

Validation error
GET
/api/v1/operator/agent_commands/:id Web Session

Get agent command details

Description

Returns the latest lifecycle state and payloads for a single agent command. This endpoint is restricted to human operator sessions.

Auth

Web Session
Parameters
Name In Type Required Description
id path string Yes Agent command UUID
Responses
200

Agent command details

Returns: AgentCommand
Response Body
Field Type Required Description
id string Yes Agent command UUID
status string (queued, dispatched, accepted, running, succeeded, failed, cancelled, timed_out) Yes Current command lifecycle state
payload object Yes Original command payload
inserted_at datetime (ISO 8601) Yes Record insertion timestamp
updated_at datetime (ISO 8601) Yes Record update timestamp
completed_at datetime (ISO 8601) No Timestamp when the command reached a terminal state
service_agent object No Target service agent summary
service_agent.id string Yes Service agent UUID
service_agent.name string Yes Service agent name
service_agent.slug string Yes Service agent slug
correlation_id string Yes Correlation identifier for idempotency and tracing
accepted_at datetime (ISO 8601) No Timestamp when the agent accepted the command
cancel_requested_at datetime (ISO 8601) No Timestamp when the operator requested cancellation
command_type string Yes Application-defined command type
created_by_user object No User who created the command
created_by_user.id string Yes User UUID
created_by_user.email string Yes User email address
error_payload object Yes Agent-reported error payload
lease_expires_at datetime (ISO 8601) No Dispatch lease expiry timestamp for unaccepted commands
result_payload object Yes Agent-reported result payload
403

Service-agent credentials cannot read operator commands
404

Agent command not found
POST
/api/v1/operator/agent_commands/:id/cancel Web Session

Cancel agent command

Description

Requests cancellation for a queued, dispatched, accepted, or running agent command. This endpoint is restricted to human operator sessions.

Auth

Web Session
Parameters
Name In Type Required Description
id path string Yes Agent command UUID
Responses
200

Agent command updated

Returns: AgentCommand
Response Body
Field Type Required Description
id string Yes Agent command UUID
status string (queued, dispatched, accepted, running, succeeded, failed, cancelled, timed_out) Yes Current command lifecycle state
payload object Yes Original command payload
inserted_at datetime (ISO 8601) Yes Record insertion timestamp
updated_at datetime (ISO 8601) Yes Record update timestamp
completed_at datetime (ISO 8601) No Timestamp when the command reached a terminal state
service_agent object No Target service agent summary
service_agent.id string Yes Service agent UUID
service_agent.name string Yes Service agent name
service_agent.slug string Yes Service agent slug
correlation_id string Yes Correlation identifier for idempotency and tracing
accepted_at datetime (ISO 8601) No Timestamp when the agent accepted the command
cancel_requested_at datetime (ISO 8601) No Timestamp when the operator requested cancellation
command_type string Yes Application-defined command type
created_by_user object No User who created the command
created_by_user.id string Yes User UUID
created_by_user.email string Yes User email address
error_payload object Yes Agent-reported error payload
lease_expires_at datetime (ISO 8601) No Dispatch lease expiry timestamp for unaccepted commands
result_payload object Yes Agent-reported result payload
403

Service-agent credentials cannot cancel operator commands
404

Agent command not found