Agent commands are operator-created realtime work items targeted at one service agent. The REST record moves through queued, dispatched, accepted, running, succeeded, failed, cancelled, or timed_out while delivery and reports travel through the agent channel.
REST records, realtime delivery
POST creates the durable command, while the target consumes it over its authenticated socket topic. correlation_id connects application work, and result_payload or error_payload describes the terminal report.
Cancellation is cooperative
A cancellation request records cancel_requested_at and prevents work where possible, but an already accepted command may finish concurrently. Always re-read the command's final status.
Before you begin
A signed-in browser session with a selected workspace backed by an active membership is required; an archived workspace remains readable but rejects mutations. Every /api/v1/operator endpoint rejects API credentials and bearer tokens, regardless of their scopes.
Owners, admins, and members can create or cancel commands; auditors are read-only. The target service agent must belong to the current workspace.
The agent runtime needs a realtime connection with agent_commands:read to receive command events and agent_commands:write to acknowledge, report progress, complete, or fail them.
How it works
Confirm the target
Filter commands by service_agent_id and status, check recent failures, and ensure the intended agent is online before dispatching. Use a stable application command_type and a bounded JSON payload.
Track to terminal state
After dispatch, retain the command ID and correlation ID. Follow realtime updates or poll until succeeded, failed, cancelled, or timed_out, then inspect result_payload or error_payload instead of assuming delivery equals success.
Examples
These examples are illustrative. Replace the sample values with your own.
Keep credentials in environment variables or a secret manager, never in client-side code.
List recent commands
The limit is capped at 100; this example reads the most recent 25 commands in the selected workspace.
javascript
const response = await fetch("/api/v1/operator/agent_commands?limit=25", {
credentials: "same-origin",
headers: {"Accept": "application/json"}
});
const body = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${body.detail}`);
console.log(body);
What to expect
200 OK with {"agent_commands": []} when no commands exist. Populated rows include service_agent, command_type, status, correlation_id, lifecycle timestamps, and terminal payloads.
Troubleshooting
A command stays queued
Check the service agent's availability and socket authentication. The REST create can succeed even when the agent is not currently connected, so inspect realtime and queue health next.
Create or cancel returns 403
Auditor memberships cannot operate commands, archived workspaces reject all mutations, and machine credentials never authenticate the operator route.
Endpoint reference
Ready to integrate? Open an endpoint for its required permissions, request fields,
response format, and status codes. The examples above explain the workflow;
these details define each individual request.
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)
