Skip to content

API: Commands

This section covers command templates and how to send commands to agents via the API.

List Command Plugins

Retrieve a list of available command plugins:

1
2
GET /api/v1/plugins/commands HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Enable a Command Plugin

Enable a previously disabled command plugin. Disabled plugins have their command templates hidden from agents.

1
2
PUT /api/v1/plugins/commands/{PLUGIN_ID}/enable HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Returns the updated plugin object.

Disable a Command Plugin

Disable a command plugin. Its command templates will no longer be offered to agents until re-enabled.

1
2
PUT /api/v1/plugins/commands/{PLUGIN_ID}/disable HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Returns the updated plugin object.

List Command Templates

Get a list of command templates:

1
2
GET /api/v1/command-templates HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Command Template Details

Fetch details for a specific command template:

1
2
GET /api/v1/command-templates/{COMMAND_TEMPLATE_ID} HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Send a Command to an Agent

Issue a command by specifying the template and configuration. Optionally include an execConf block to control execution context.

JSON request:

1
2
3
4
5
6
7
8
9
POST /api/v1/agents/{AGENT_GUID}/commands HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "template": "{COMMAND_TEMPLATE_ID}",
  "configuration": {COMMAND_CONFIGURATION},
  "execConf": {EXECUTION_CONFIGURATION}
}

Multipart request (when the command configuration uses files):

1
2
3
4
5
6
POST /api/v1/agents/{AGENT_GUID}/commands HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
Content-Type: multipart/form-data

requestBody: {"template": "{COMMAND_TEMPLATE_ID}", "configuration": {COMMAND_CONFIGURATION}, "execConf": {EXECUTION_CONFIGURATION}}
{FILE_FIELD_NAME}: <binary file content>

Use the file field name from the command schema. For example, a schema field shown as @files.executable is sent as a multipart file part named executable.

Examples

Example 1 – Basic Command

Run a simple command, such as "whoami", using the "cmd" template:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
POST /api/v1/agents/{AGENT_GUID}/commands HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "template": "cmd",
  "configuration": {
    "command": "whoami"
  }
}

Example 2 – Spawning a New Process

Spawn a new process with the "spawn" template.

Info

payloadId must reference a payload of type SHELLCODE.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
POST /api/v1/agents/{AGENT_GUID}/commands HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "template": "spawn",
  "configuration": {
    "payloadId": 1,
    "encryptedCommunication": true
  },
  "execConf": {
    "execType": "NEW",
    "executable": "C:\\Windows\\System32\\notepad.exe",
    "suspended": false,
    "username": "tuoni",
    "password": "PassW$ord"
  }
}

Search Commands (v2)

Use the paged v2 endpoints to search commands across all visible agents or within one agent:

1
2
GET /api/v2/commands HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

1
2
GET /api/v2/agents/{AGENT_GUID}/commands HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

AGENT_GUID is a UUID. The agent-specific operation returns 404 when that agent does not exist.

Pagination and filters

Parameter Applies to Description
page Both endpoints Zero-based page number; defaults to 0; minimum 0
pageSize Both endpoints Items per page; defaults to 100; minimum 1, maximum 1000
status Both endpoints Lifecycle status to include; repeat for multiple statuses
commandTemplateName Both endpoints Exact, case-sensitive persisted template name; repeat for multiple names
agentGuid All-commands endpoint Agent UUID to include; repeat for multiple agents
createdFrom, createdTo Both endpoints Inclusive creation-time lower and upper bounds in date-time format
sentFrom, sentTo Both endpoints Inclusive effective send-time lower and upper bounds in date-time format
sort Both endpoints Sort criterion; repeat to apply multiple criteria in order

Omitting an array filter includes all values. An explicitly empty array matches no commands.

Supported lifecycle statuses are CREATED, SENT, ONGOING, CANCELED, FAILED, and COMPLETE.

Each sort field accepts the bare field, :ASC, or :DESC form:

Field Accepted values
Command ID ID, ID:ASC, ID:DESC
Agent GUID AGENT_GUID, AGENT_GUID:ASC, AGENT_GUID:DESC
Creation time CREATED, CREATED:ASC, CREATED:DESC
Send time SENT, SENT:ASC, SENT:DESC
Lifecycle status STATUS, STATUS:ASC, STATUS:DESC

For example, search across agents with several filters and two sort criteria:

1
2
GET /api/v2/commands?page=0&pageSize=50&status=ONGOING&status=COMPLETE&commandTemplateName=cmd&agentGuid={AGENT_GUID}&createdFrom=2026-08-01T00:00:00Z&sentTo=2026-08-13T23:59:59Z&sort=CREATED:DESC&sort=ID:DESC HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Or retrieve the second page of failed commands for one agent:

1
2
GET /api/v2/agents/{AGENT_GUID}/commands?page=1&pageSize=100&status=FAILED&sort=SENT:DESC HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Paged response

A successful request returns the shared paged response. Its items are eventful command records with these fields:

Field Type Description
id integer Unique command ID
commandTemplateId UUID Command-template ID
commandTemplateName string or null Persisted command-template name
configuration object Command configuration; multipart configurations can include an @files object
execConf object Execution configuration
agentGuid UUID Agent that owns the command
created date-time Command creation time
sent date-time or null Command send time
sendFormat string or null Format used to send the command
sends array Individual command send attempts, described below
status string Command lifecycle status
commandUpdates array Updates created for the command
result object or null Composite command result
createEvent object Creation audit metadata
lastUpdateEvent object Latest-update audit metadata

See Eventful Responses and Audit Actors for the audit event and actor fields.

Each entry in sends describes one delivery attempt:

Field Type Description
sendTime date-time Time of the attempt
listenerId integer or null Listener that sent the command
status string SUCCEEDED or FAILED
errorMessage string or null Delivery error, when present
sendFormat string or null Format used for this attempt
event object or null Audit event created for this attempt

The all-commands endpoint returns 200, 401, or 403. The agent-specific endpoint can also return 404 when AGENT_GUID is not found.

Retrieve Agent Commands

Get all commands sent to a specific agent:

1
2
GET /api/v1/agents/{AGENT_GUID}/commands HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Retrieve All Commands

List all commands issued across agents:

1
2
GET /api/v1/commands HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Response is a JSON object keyed by command ID, where each value is a CommandResponse (same shape as GET /api/v1/commands/{COMMAND_ID}):

1
2
3
4
{
  "1": { "id": 1, "agentGuid": "...", "template": "...", ... },
  "2": { "id": 2, "agentGuid": "...", "template": "...", ... }
}

Get Command Result

Fetch the result for a specific command:

1
2
GET /api/v1/commands/{COMMAND_ID} HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Send a Command Update

Send new data to an already-running command. Use JSON for commands that only require a configuration update, or multipart form-data when you also need to attach files.

JSON variant:

1
2
3
4
5
6
7
POST /api/v1/commands/{COMMAND_ID}/update HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "configuration": {COMMAND_UPDATE_CONFIGURATION}
}

Multipart variant (when files are required):

1
2
3
4
5
6
POST /api/v1/commands/{COMMAND_ID}/update HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
Content-Type: multipart/form-data

requestBody: {"configuration": {COMMAND_UPDATE_CONFIGURATION}}
file[]: <binary file content>

Download a Command Configuration File

Download a file that was attached to the original command's configuration.

1
2
GET /api/v1/commands/{COMMAND_ID}/configuration/files/{FILE_ID} HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Returns the file as an octet-stream download.

Download a Command Update Configuration File

Download a file attached to a specific command update.

1
2
GET /api/v1/commands/{COMMAND_ID}/updates/{UPDATE_INDEX}/configuration/files/{FILE_ID} HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

UPDATE_INDEX is the zero-based position of the update in the command's update history.

Returns the file as an octet-stream download.

Download a Command Result File

Download a file returned as part of a command's result.

1
2
GET /api/v1/commands/{COMMAND_ID}/files/{FILE_ID} HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Returns the file as an octet-stream download. UTF-8 filenames are preserved, with a safe ASCII filename fallback for clients that do not support the UTF-8 form.

Stop command

Sends stop signal to a command identified by ID. If command is not yet sent, then the command will be canceled and never sent.

1
2
PUT /api/v1/commands/{COMMAND_ID}/stop HTTP/1.1
Authorization: Bearer {JWT_TOKEN}