Agent Commands Api Send

Agent Commands Api Send
Send a command to an agent

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.

Request
URI
POST
https://{api_host}/api/v1/agents/{agentPk}/commands
COPY
Path Parameters
integer
agentPk
Required  

Agent primary key

agentPk example
2

Request Body

The command to send: its type, which must be one the agent accepts, and an optional numericValue or stringValue of up to 1024 characters.

SendAgentCommandRequest of type(s) application/json
Required  

Show optional properties

{
    "type": "string"
}
{
    "type": "ActionSetHeartbeatInterval",
    "numericValue": 60
}
string
type
Required  

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 deleted
  • ActionConfigSyncForce: No behaviour is documented for this value. The server only forwards it to the agent
  • ActionRebuildCache: No behaviour is documented for this value. The server only forwards it to the agent
  • ActionCollectDiagnostics: No behaviour is documented for this value. The server only forwards it to the agent
  • ActionAgentDisable: 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 changes
  • ActionGetFileCatalog: No behaviour is documented for this value. The server only forwards it to the agent; the protocol definition comments it as the full catalog
  • ActionGetUpdatedFileCatalog: No behaviour is documented for this value. The server only forwards it to the agent; the protocol definition comments it as the incremental changes
Enumeration: ActionConfigSync, ActionConfigSyncForce, ActionRebuildCache, ActionCollectDiagnostics, ActionAgentDisable, ActionAgentEnable, ActionSetHeartbeatInterval, ActionGetFileCatalog, ActionGetUpdatedFileCatalog
integer As int32 As int32
numericValue
Optional

ActionSetHeartbeatInterval: seconds (must be positive). ActionGetFileCatalog: maximum catalog size in bytes.

string
stringValue
Optional
Constraints: maxLength: 1024

String argument, when the command takes one

Authentication
This operation uses the following authentication methods.
Responses
202

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.

Returns AgentCommandStatusDto of type(s) application/json
{
    "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"
}
integer As int64 As int64
agentPk
Required  

Identifier of the Agent the command was issued to

string
type
Required  

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 deleted
  • ActionConfigSyncForce: No behaviour is documented for this value. The server only forwards it to the agent
  • ActionRebuildCache: No behaviour is documented for this value. The server only forwards it to the agent
  • ActionCollectDiagnostics: No behaviour is documented for this value. The server only forwards it to the agent
  • ActionAgentDisable: 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 changes
  • ActionGetFileCatalog: No behaviour is documented for this value. The server only forwards it to the agent; the protocol definition comments it as the full catalog
  • ActionGetUpdatedFileCatalog: No behaviour is documented for this value. The server only forwards it to the agent; the protocol definition comments it as the incremental changes
Enumeration: ActionConfigSync, ActionConfigSyncForce, ActionRebuildCache, ActionCollectDiagnostics, ActionAgentDisable, ActionAgentEnable, ActionSetHeartbeatInterval, ActionGetFileCatalog, ActionGetUpdatedFileCatalog
string
status
Required  

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 SENT
  • SENT: The agent acknowledged the command; the result is awaited and becomes SUCCEEDED or FAILED, or TIMED_OUT after the result timeout
  • SUCCEEDED: The agent reported result status code 0
  • FAILED: The agent reported a result status code other than 0
  • DISPATCH_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 reason
  • TIMED_OUT: No result arrived from the agent within the result timeout after the command was SENT
Enumeration: PENDING, SENT, SUCCEEDED, FAILED, DISPATCH_FAILED, TIMED_OUT
integer As int64 As int64
commandId
Required  

Console-generated batch id echoed by the agent in its result

integer As int32 As int32
numericValue
Optional

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

string
stringValue
Optional

Text argument of at most 1024 characters given when the command was issued; null when none was given

string
requestedBy
Required  

Username of the administrator who issued the command; null when no signed-in user was available

string As date-time As date-time
requestedAt
Required  

Time the Console accepted the command request

string As date-time As date-time
sentAt
Optional

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

string As date-time As date-time
completedAt
Optional

Time the command reached SUCCEEDED, FAILED, DISPATCH_FAILED or TIMED_OUT; null while it is PENDING or SENT

integer As int32 As int32
resultStatusCode
Optional

Agent-reported status code; 0 means success

string
resultMessage
Optional

Agent-reported response text, or the dispatch error

integer As int64 As int64
executionTimeMs
Optional

Execution time in milliseconds reported by the agent with its result; null until a result is recorded


400

400 Bad Request: COMMAND_TYPE_REQUIRED, COMMAND_TYPE_NOT_ALLOWED, INVALID_NUMERIC_VALUE or MALFORMED_REQUEST

Returns ApiErrorResponse of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

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.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

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

401 Unauthorized: UNAUTHENTICATED when the VTP_SESSION cookie is missing, unknown, expired or revoked

Returns Unauthenticated of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

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.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

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

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)

Returns ApiErrorResponse of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

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.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

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

404 Not Found: AGENT_NOT_FOUND or AGENT_HOST_NOT_FOUND

Returns ApiErrorResponse of type(s) application/json
"ApiErrorResponse Object"
errorCode
Required  

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.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

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

409 Conflict: AGENT_NOT_ENROLLED, AGENT_SESSION_UNAVAILABLE or COMMAND_IN_FLIGHT (the same command type is still pending or sent)

Returns ApiErrorResponse of type(s) application/json
"ApiErrorResponse Object"
errorCode
Required  

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.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


Code Samples
COPY
                    curl -X POST -H 'Authorization: <value>' -H 'Content-Type: application/json' -d '{"type":"string"}' https://{api_host}/api/v1/agents/{agentPk}/commands