Agent Commands Api Send
Queues a console command for delivery to the agent and answers 202 with its state. ActionUnenroll cannot be issued here; use the enrollment reset. Requires the ADMIN role.
Agent primary key
2
The command to send: its type, which must be one the agent accepts, and an optional numericValue or stringValue of up to 1024 characters.
Show optional properties
{
"type": "string"
}
{
"type": "ActionSetHeartbeatInterval",
"numericValue": 60
}
Command types an administrator can issue from the console.
ActionConfigSync: Tells the agent to pull its Group's configuration now instead of at its next heartbeat; the Console sends it itself when a Group is published, its protection, enforcement mode or heartbeat interval changes, agents are moved, or the Group is deletedActionConfigSyncForce: No behaviour is documented for this value. The server only forwards it to the agentActionRebuildCache: No behaviour is documented for this value. The server only forwards it to the agentActionCollectDiagnostics: No behaviour is documented for this value. The server only forwards it to the agentActionAgentDisable: Sent by the Console to every active agent of a Group when its Agent Protection flag is set (agentDisabledStatus true)ActionAgentEnable: Sent by the Console to every active agent of a Group when its Agent Protection flag is cleared (agentDisabledStatus false)ActionSetHeartbeatInterval: numericValue is the new heartbeat interval in seconds and must be a positive number (400 INVALID_NUMERIC_VALUE otherwise); the Console also sends it when a Group's heartbeat interval changesActionGetFileCatalog: No behaviour is documented for this value. The server only forwards it to the agent; the protocol definition comments it as the full catalogActionGetUpdatedFileCatalog: No behaviour is documented for this value. The server only forwards it to the agent; the protocol definition comments it as the incremental changes
ActionSetHeartbeatInterval: seconds (must be positive). ActionGetFileCatalog: maximum catalog size in bytes.
String argument, when the command takes one
202 Accepted the command and its state. Its later state is reported by GET /api/v1/agents/{agentPk}/commands, which lists the latest state per command type (a later command of the same type replaces the earlier one) with status, sentAt, completedAt, resultStatusCode and resultMessage.
{
"agentPk": 2,
"type": "ActionSetHeartbeatInterval",
"status": "SENT",
"commandId": 7,
"numericValue": 60,
"requestedBy": "bob.example",
"requestedAt": "2026-01-15T09:30:00Z",
"sentAt": "2026-01-15T09:30:01Z"
}
Identifier of the Agent the command was issued to
Command types an administrator can issue from the console.
ActionConfigSync: Tells the agent to pull its Group's configuration now instead of at its next heartbeat; the Console sends it itself when a Group is published, its protection, enforcement mode or heartbeat interval changes, agents are moved, or the Group is deletedActionConfigSyncForce: No behaviour is documented for this value. The server only forwards it to the agentActionRebuildCache: No behaviour is documented for this value. The server only forwards it to the agentActionCollectDiagnostics: No behaviour is documented for this value. The server only forwards it to the agentActionAgentDisable: Sent by the Console to every active agent of a Group when its Agent Protection flag is set (agentDisabledStatus true)ActionAgentEnable: Sent by the Console to every active agent of a Group when its Agent Protection flag is cleared (agentDisabledStatus false)ActionSetHeartbeatInterval: numericValue is the new heartbeat interval in seconds and must be a positive number (400 INVALID_NUMERIC_VALUE otherwise); the Console also sends it when a Group's heartbeat interval changesActionGetFileCatalog: No behaviour is documented for this value. The server only forwards it to the agent; the protocol definition comments it as the full catalogActionGetUpdatedFileCatalog: No behaviour is documented for this value. The server only forwards it to the agent; the protocol definition comments it as the incremental changes
Latest state of a command for one agent.
PENDING: Recorded by the Console and not yet delivered; becomes SENT or DISPATCH_FAILED, and a command still PENDING after the result timeout (default 300 seconds) becomes DISPATCH_FAILED; a new command of the same type is refused while it is PENDING or SENTSENT: The agent acknowledged the command; the result is awaited and becomes SUCCEEDED or FAILED, or TIMED_OUT after the result timeoutSUCCEEDED: The agent reported result status code 0FAILED: The agent reported a result status code other than 0DISPATCH_FAILED: The Console could not deliver the command, or the agent dispatched no command, or the command stayed PENDING past the result timeout; resultMessage holds the reasonTIMED_OUT: No result arrived from the agent within the result timeout after the command was SENT
Console-generated batch id echoed by the agent in its result
Numeric argument given when the command was issued; ActionSetHeartbeatInterval requires it as a positive number of seconds; sent to the agent as 0 when absent; null when none was given
Text argument of at most 1024 characters given when the command was issued; null when none was given
Username of the administrator who issued the command; null when no signed-in user was available
Time the Console accepted the command request
Time the agent acknowledged the command; null while the command is PENDING and when it ended as DISPATCH_FAILED; also null on a SUCCEEDED or FAILED command when the agent answered before the acknowledgement was recorded
Time the command reached SUCCEEDED, FAILED, DISPATCH_FAILED or TIMED_OUT; null while it is PENDING or SENT
Agent-reported status code; 0 means success
Agent-reported response text, or the dispatch error
Execution time in milliseconds reported by the agent with its result; null until a result is recorded
400 Bad Request: COMMAND_TYPE_REQUIRED, COMMAND_TYPE_NOT_ALLOWED, INVALID_NUMERIC_VALUE or MALFORMED_REQUEST
{
"errorCode": "string",
"message": "string",
"path": "string",
"timestamp": "string",
"reason": "string"
}
Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.
401 Unauthorized: UNAUTHENTICATED when the VTP_SESSION cookie is missing, unknown, expired or revoked
{
"errorCode": "string",
"message": "string",
"path": "string",
"timestamp": "string",
"reason": "string"
}
Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.
403 Forbidden: FORBIDDEN or CSRF_ERROR. CSRF_ERROR when the X-XSRF-TOKEN header is missing or wrong on a POST, PUT, PATCH or DELETE (only POST /api/v1/auth/login is exempt, and a request without a valid session gets 401 UNAUTHENTICATED instead); PASSWORD_CHANGE_REQUIRED when the account must change its password first (only GET /api/v1/auth/session, POST /api/v1/auth/logout and POST /api/v1/auth/change-password are exempt); LICENSE_REQUIRED or LICENSE_EXPIRED while the license pool is restricted (no license, or expired past grace) (exempt: every route under /api/v1/auth, GET /api/v1/user/preferences, GET /api/v1/licensing/summary and POST /api/v1/licensing/licenses)
{
"errorCode": "string",
"message": "string",
"path": "string",
"timestamp": "string",
"reason": "string"
}
Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.
404 Not Found: AGENT_NOT_FOUND or AGENT_HOST_NOT_FOUND
"ApiErrorResponse Object"
Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.
409 Conflict: AGENT_NOT_ENROLLED, AGENT_SESSION_UNAVAILABLE or COMMAND_IN_FLIGHT (the same command type is still pending or sent)
"ApiErrorResponse Object"
Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.
curl -X POST -H 'Authorization: <value>' -H 'Content-Type: application/json' -d '{"type":"string"}' https://{api_host}/api/v1/agents/{agentPk}/commands