Web API

AdaptixC2 Server exposes a REST API for managing the teamserver. The API runs over HTTPS and uses JSON for data transfer.

Base URL: https://{host}:{port}{endpoint}

• {host} — server IP address or domain

• {port} — teamserver port

• {endpoint} — base path defined in the profile configuration

If authentication fails, the web server will respond with a 404 page by default.

Authentication

The API uses JWT (JSON Web Tokens) for authentication. To obtain tokens, log in via /login.

POST /login

Authenticate a user and obtain JWT tokens.

---

Request Body:

{
  "username": "string",
  "password": "string",
  "version": "string"
}

Field	Type	Required	Description
username	string	Yes	Operator name
password	string	Yes	Operator password
version	string	No	Client version

---

Response (200 OK):

{
  "access_token": "string",
  "refresh_token": "string",
  "version": "v2.0"
}

Errors:

• Invalid credentials — returns 404 (configurable error page)

POST /refresh

Refresh the access token using the refresh token.

---

Request

Send the refresh token in the header:

Authorization: Bearer <refresh_token>

---

Response (200 OK):

{
  "access_token": "string"
}

OTP

OTP (One-Time Password) — one-time tokens with a short TTL (60 sec). Used for:

• Secure file transfers (upload/download)

• Establishing WebSocket connections (/connect)

• Creating WebSocket channels (/channel)

Every OTP route reads the token from the query parameter ?otp=.

• TTL: OTP token is valid for 60 seconds after generation

• One-time use: Each token can be used only once

• Type isolation: A connect token cannot be used on /channel and vice versa

• Security: The token contains no data — just a random 256-bit identifier

POST /otp/generate

Generate a one-time token. Requires an Access Token.

---

Request (JSON)

Universal request format:

{
  "type": "string",
  "data": { ... }
}

Field	Type	Required	Description
type	string	Yes	OTP type (see below)
data	object	Depends on type	Type-specific JSON data

---

Response (200 OK):

{
  "ok": true,
  "message": "<otp_token>"
}

Response (error):

{
  "ok": false,
  "message": "error description"
}

connect

Client WebSocket connection

{
  "type": "connect",
  "data": {
    "client_type": 1,
    "console_team_mode": false,
    "subscriptions": ["agents", "listeners"]
  }
}

data field	Type	Default	Description
client_type	uint8	1 (UI)	Client type: 1=UI, 2=WEB, 3=CLI
console_team_mode	bool	false	Team-console mode
subscriptions	string[]	[]	Subscription categories

channel_tunnel

WebSocket channel for a tunnel

{
  "type": "channel_tunnel",
  "data": {
    "tunnel_id": 1,
    "channel_id": 2,
    "mode": "tcp|udp",
    "host": "string",
    "port": "string"
  }
}

data field	Type	Required	Description
tunnel_id	int64	Yes	Tunnel ID
channel_id	int64	Yes	Channel ID
mode	string	For SOCKS5	Mode: tcp or udp
host	string	For SOCKS	Target host
port	string	For SOCKS	Target port (1-65535)

channel_terminal

WebSocket channel for a terminal

{
  "type": "channel_terminal",
  "data": {
    "agent_id": 1,
    "terminal_id": 1,
    "program": "string",
    "size_h": 24,
    "size_w": 80,
    "oem_cp": 65001
  }
}

data field	Type	Required	Description
agent_id	int64	Yes	Agent ID
terminal_id	int64	Yes	Terminal ID
program	string	Yes	Program to run
size_h	int	Yes	Terminal height (rows)
size_w	int	Yes	Terminal width (columns)
oem_cp	int	Yes	OEM Code Page

channel_agent_build

WebSocket channel for agent build

{
  "type": "channel_agent_build",
  "data": {
    "agent_name": "string",
    "listeners_name": ["listener1", "listener2"]
  }
}

data field	Type	Required	Description
agent_name	string	Yes	Agent name to build
listeners_name	string[]	Yes	List of listener names

download

File download

{
  "type": "download",
  "data": {
    "id": 1
  }
}

data field	Type	Description
id	int64	File id of a finished download

tmp_upload

Temporary file upload

{
  "type": "tmp_upload",
  "data": {
    "id": 1
  }
}

data field	Type	Description
id	int64	Id of a temporary upload already registered on the server

Full channel creation flow example (tunnel)

1. Make sure the client is connected via /connect

2. POST /otp/generate (Authorization: Bearer <access_token>) Body: {"type": "channel_tunnel", "data": {"tunnel_id": "...", "channel_id": "...", ...}} → obtain otp_token

3. GET /channel?otp=<otp_token> → WebSocket upgrade

POST /otp/upload/temp?otp=

Upload bytes into a temporary upload that was already registered. The token type must be tmp_upload, and its id must still be in the server's temporary-upload map.

---

Request

multipart/form-data

Field	Type	Description
file	file	The file

---

Response (200 OK): an empty body.

A wrong token type, an unknown id, a missing file field, or a save error is a 404 text body with the error string. A bad or expired token is rejected by the OTP middleware before this handler runs.

GET /otp/download/sync?otp=

Download a finished file. The token type must be download. The server returns the file only when that download's state is finished.

---

Response (200 OK)

the file bytes, with:

• Content-Disposition: attachment; filename="<on-disk name>"

• Content-Type: application/octet-stream

• Content-Length: <size>

The filename is the base name of the stored path, not a separate display name. If the id is unknown or the download is not finished, the response is 404 with a text error (File not found: … or Download not finished).

Client Management

POST /sync

Asks the server to push the current state to this operator's already open WebSocket. The handler does not read the body.

---

Request

Header Authorization: Bearer <access_token>

---

Response (200 OK):

{
  "ok": true,
  "message": "sync started"
}

POST /subscribe

Subscribe the client to event categories.

---

Request

Header Authorization: Bearer <access_token>

{
  "categories": ["string"],
  "console_team_mode": true|false
}

Field	Type	Required	Description
categories	string[]	Yes	List of categories to subscribe to
console_team_mode	boolean	No	Team-console mode

---

Response (200 OK):

{
  "ok": true,
  "message": "subscribe started"
}

GET /connect?otp=

Establish a WebSocket connection for real-time updates. Requires an OTP token of type connect.

---

Response: WebSocket upgrade

All connection parameters (client_type, subscriptions, etc.) are passed when generating the OTP, not when connecting.

GET /channel?otp=

Create a WebSocket channel. The token type must start with channel_ (channel_tunnel, channel_terminal, or channel_agent_build). A token whose type is exactly channel is rejected.

---

Response: WebSocket upgrade

The channel type and initialization data are passed when generating the OTP, not when connecting.

Listener

GET /listener/list

Get the list of all listeners.

---

Request

Header Authorization: Bearer <access_token>

---

Response (200 OK):

JSON array of ListenerData. An empty server returns null, not [], because the handler marshals a nil slice.

[
  {
    "l_name": "http-443",
    "l_reg_name": "BeaconHTTP",
    "l_protocol": "http",
    "l_type": "external",
    "l_bind_host": "0.0.0.0",
    "l_bind_port": "443",
    "l_agent_addr": "10.0.0.5:443",
    "a_create_time": 1718500000,
    "l_status": "Listen",
    "l_tags": "prod",
    "l_data": "{\"host_bind\":\"0.0.0.0\",\"port_bind\":\"443\"}",
    "l_watermark": "c04c4e57"
  }
]

GET /listener/catalog

Registered listener types (not running instances).

---

Request

Header Authorization: Bearer <access_token>

---

Response (200 OK):

axs — the contents of ax_config.axs (the listener fields UI definition).

[
  {
    "name": "GopherTCP",
    "protocol": "tcp",
    "type": "external",
    "axs": "function ListenerUI(mode_create) { ... }"
  }
]

POST /listener/create

Create a new listener.

---

Request

Header Authorization: Bearer <access_token>

{
  "name": "string",
  "type": "string",
  "config": "string",
  "tags": "string"
}

Field	Type	Description
name	string	Unique listener name (a-zA-Z0-9_-)
type	string	Listener type (depends on the extender)
config	string	JSON listener configuration
tags	string	Tags (free-form, e.g. "prod,eu"); optional

---

Response:

{
  "ok": true,
  "message": "Listener started"
}

POST /listener/edit

Edit a listener configuration.

---

Request

Header Authorization: Bearer <access_token>

{
  "name": "string",
  "type": "string",
  "config": "string",
  "tags": "string"
}

Field	Type	Description
name	string	Listener name
type	string	Listener type
config	string	JSON listener configuration
tags	string	New tags (empty string clears); optional

---

Response:

{
  "ok": true,
  "message": "Listener Edited"
}

POST /listener/stop

Stop and delete listener.

---

Request

Header Authorization: Bearer <access_token>

{
  "name": "string",
  "type": "string"
}

---

Response:

{
  "ok": true,
  "message": "Listener stopped"
}

POST /listener/pause

Pause a listener.

---

Request

Header Authorization: Bearer <access_token>

{
  "name": "string",
  "type": "string"
}

---

Response:

{
  "ok": true,
  "message": "Listener paused"
}

POST /listener/resume

Resume a listener.

---

Request

Header Authorization: Bearer <access_token>

{
  "name": "string",
  "type": "string"
}

---

Response:

{
  "ok": true,
  "message": "Listener resumed"
}

POST /listener/tags

Set arbitrary tags on a listener.

---

Request

Header Authorization: Bearer <access_token>

{
  "name": "string",
  "tags": "string"
}

---

Response:

{
  "ok": true,
  "message": ""
}

Agent

GET /agent/list

Get the list of all agents.

---

Request

Header Authorization: Bearer <access_token>

---

Response (JSON)

[
  {
    "a_crc": "beacon",
    "a_id": 12,
    "a_uid": "AQIDBAUGBwg=",
    "a_name": "beacon",
    "a_session_key": "AQIDBAUGBwgJCgsMDQ4PEA==",
    "a_listener": "http-443",
    "a_async": true,
    "a_external_ip": "203.0.113.10",
    "a_internal_ip": "10.0.0.20",
    "a_gmt_offset": 0,
    "a_sleep": 5,
    "a_jitter": 10,
    "a_pid": "4120",
    "a_tid": "512",
    "a_arch": "x64",
    "a_elevated": true,
    "a_process": "explorer.exe",
    "a_os": 1,
    "a_os_desc": "Windows 10",
    "a_domain": "CORP",
    "a_computer": "WS01",
    "a_username": "alice",
    "a_impersonated": "",
    "a_oemcp": 437,
    "a_acp": 1251,
    "a_create_time": 1718500000,
    "a_last_tick": 1718500100,
    "a_killdate": 0,
    "a_workingtime": 0,
    "a_tags": "finance",
    "a_mark": "",
    "a_color": "",
    "a_target": 0,
    "a_custom_data": null
  }
]

GET /agent/catalog

Registered agent types (not live sessions).

---

Request

Header Authorization: Bearer <access_token>

---

Response (JSON)

[
  {
    "name": "gopher",
    "listeners": ["GopherTCP"],
    "fields": ["os", "arch", "format"],
    "choices": { "os": ["linux", "windows"], "arch": ["amd64"] }
  }
]

GET /agent/generate

Generate an agent payload.

---

Request

Header Authorization: Bearer <access_token>

{
  "agent": "string",
  "listener_name": ["string"],
  "config": "string",
  "save_to_store": true,
  "description": "string"
}

Field	Type	Required	Description
agent	string	Yes	Agent type name
listener_name	string[]	Yes	List of listener names
config	string	Yes	JSON agent configuration
save_to_store	boolean	No	Register the payload in the Payload Store (default true)
description	string	No	Description for the Payload Store entry

---

Response (JSON)

{
  "ok": true,
  "message": "<base64_filename>:<base64_content>"
}

message format: file name and content are base64-encoded and separated by a colon.

The client generates payloads through this endpoint (REST + Bearer token, 180-second timeout) when the WebSocket build-channel OTP is unavailable.

POST /agent/remove

Remove agent data

---

Request

Header Authorization: Bearer <access_token>

{
  "agent_id_array": [1]
}

---

Response:

{
  "ok": true,
  "message": ""
}

POST /agent/command/execute

Execute a command on an agent.

---

Request

Header Authorization: Bearer <access_token>

{
  "id": 1,
  "ui": true|false,
  "cmdline": "string",
  "data": "string",
  "ax_hook_id": "string",
  "ax_handler_id": "string",
  "wait_answer": true|false
}

Field	Type	Description
id	int64	Agent ID
ui	boolean	Command from the UI
cmdline	string	Command line
data	string	JSON with command arguments
ax_hook_id	string	Hook ID (optional)
ax_handler_id	string	Handler ID (optional)
wait_answer	boolean	When true, the HTTP call waits until TsAgentCommand returns. The agent output is not included in this response

---

Response:

{
  "ok": true,
  "message": ""
}

POST /agent/command/raw

Execute a raw command on an agent through the server-side AxScript engine. The command is parsed and executed on the server side without client-side hooks.

---

Request

Header Authorization: Bearer <access_token>

{
  "id": 1,
  "cmdline": "string"
}

Field	Type	Description
id	int64	Agent ID
cmdline	string	Command line to execute

---

Response

{
  "ok": true,
  "message": ""
}

GET /agent/console/list

Cursor pagination of the console history for the specified agent. Returns messages with Id < after_id (newest first). When around_id > 0 — loads N messages around the given ID (used to jump to context from search results).

---

Request (JSON)

Header Authorization: Bearer <access_token>

Query Parameters:

Parameter	Type	Default	Description
agent_id	int64	(required)	Agent ID (decimal)
limit	int	200	Max entries (cap 2000)
after_id	int64	0	Cursor: return messages with Id < after_id. 0 = the newest ones.
around_id	int64	0	Load N messages around this ID (overrides after_id).

---

Response (200 OK):

{
  "items": [
    {
      "time": 1718500000,
      "type": 105,
      "a_id": 12,
      "a_msg_type": 5,
      "a_message": "CORP\\alice",
      "a_text": "CORP\\alice"
    }
  ],
  "total": 1543,
  "oldest_id": 42,
  "has_more": true
}

• total — total number of records in the DB for this agent.

• oldest_id — ID of the oldest message in the response (used as the cursor for the next request).

• has_more — true if the DB has records older than oldest_id.

Each items element is the original sync packet, stored as it was sent over WebSocket. The example is TYPE_AGENT_CONSOLE_OUT (type 105). Other stored packets are TYPE_AGENT_CONSOLE_TASK_SYNC (106) and TYPE_AGENT_CONSOLE_TASK_UPD (107); those add a_task_id, a_cmdline, a_client, and completion fields.

Errors (HTTP 400):

• agent_id is required — parameter missing.

• agent_id must be an integer — invalid format.

GET /agent/console/search

Full-text search over the agent console history. Searches the a_cmdline, a_message, a_text, a_client fields of the JSON packets.

---

Request (JSON)

Header Authorization: Bearer <access_token>

Query Parameters:

Parameter	Type	Default	Description
agent_id	int64	(required)	Agent ID
q	string	(required)	Search string
limit	int	50	Max results (cap 200)
offset	int	0	Result pagination offset

---

Response (200 OK):

{
  "ok": true,
  "total": 3,
  "limit": 50,
  "offset": 0,
  "items": [
    {
      "id": 42,
      "snippet": "...matching text around the hit...",
      "packet": {
        "time": 1718500000,
        "type": 105,
        "a_id": 12,
        "a_msg_type": 5,
        "a_message": "CORP\\alice",
        "a_text": "CORP\\alice"
      }
    }
  ]
}

• snippet — highlighted text fragment (up to 200 characters) around the match.

• packet — the original JSON sync packet (valid JSON; invalid packets are skipped).

POST /agent/set/tag

Set a tag on agents.

---

Request

Header Authorization: Bearer <access_token>

{
  "agent_id_array": [1],
  "tag": "string"
}

---

Response:

{
  "ok": true,
  "message": ""
}

POST /agent/set/mark

Set a mark on agents.

---

Request

Header Authorization: Bearer <access_token>

{
  "agent_id_array": [1],
  "mark": "string"
}

---

Response:

{
  "ok": true,
  "message": ""
}

POST /agent/set/color

Set the color of agents.

---

Request

Header Authorization: Bearer <access_token>

{
  "agent_id_array": [1],
  "bc": "string",
  "fc": "string",
  "reset": true|false
}

Field	Type	Description
agent_id_array	int64[]	Array of agent IDs
bc	string	Background color (hex or name)
fc	string	Foreground color (hex or name)
reset	boolean	Reset color to default

---

Response:

{
  "ok": true,
  "message": ""
}

POST /agent/update/data

Update agent data.

---

Request

Header Authorization: Bearer <access_token>

{
  "agent_id": 1,
  "internal_ip": "string",
  "external_ip": "string",
  "gmt_offset": 0,
  "acp": 0,
  "oemcp": 0,
  "pid": "string",
  "tid": "string",
  "arch": "string",
  "elevated": true|false,
  "process": "string",
  "os": 0,
  "os_desc": "string",
  "domain": "string",
  "computer": "string",
  "username": "string",
  "impersonated": "string",
  "tags": "string",
  "mark": "string",
  "color": "string"
}

All fields except agent_id are optional. Send only the fields you want to update.

Field	Type	Description
agent_id	int64	Agent ID (required)
internal_ip	string	Internal IP
external_ip	string	External IP
gmt_offset	int	GMT offset
acp	int	ANSI Code Page
oemcp	int	OEM Code Page
pid	string	Process ID
tid	string	Thread ID
arch	string	Architecture (x86/x64)
elevated	boolean	Elevated privileges
process	string	Process name
os	int	OS code
os_desc	string	OS description
domain	string	Domain
computer	string	Computer name
username	string	User name
impersonated	string	Impersonated user
tags	string	Tags
mark	string	Mark
color	string	Color (format: "bg-fg")

---

Response:

{
  "ok": true,
  "message": ""
}

GET /agent/command_group/list?agent_id=

Command groups of an agent with their state (enabled/disabled). Groups are registered by the agent type's AxScript via ax.create_commands_group; overrides are stored per agent.

---

Request

Header Authorization: Bearer <access_token>

Query Parameters:

Parameter	Type	Default	Description
agent_id	int64	(required)	Agent ID.

---

Response (200 OK):

{
  "ok": true,
  "message": [
    {"name": "beacon", "description": "Beacon commands", "enabled": true},
    {"name": "bof", "description": "BOF commands", "enabled": false}
  ]
}

message — array of groups {name, description, enabled} (per-agent overrides applied).

POST /agent/command_group/set

Enable/disable a command group for a specific agent. Disabled groups are hidden from the console autocomplete and filtered out by the Commander.

---

Request

Header Authorization: Bearer <access_token>

{
  "agent_id": 42,
  "group": "bof",
  "enabled": false
}

Field	Type	Description
agent_id	int64	Agent ID.
group	string	Group name (required).
enabled	bool	New state.

---

Response:

{
  "ok": true,
  "message": ""
}

Groups

GET /group/list

List of groups in the given scope.

---

Request

Header Authorization: Bearer <access_token>

---

Response

[
  {
    "group_id": 1,
    "parent_group_id": 0,
    "group_name": "Domain Controllers",
    "scope": "agents",
    "members": [12, 34, 56]
  }
]

POST /group/create

Create a new group.

---

Request

Header Authorization: Bearer <access_token>

{
  "scope": "agents",
  "name": "Domain Controllers",
  "parent_id": 0
}

Field	Type	Description
scope	string	"agents" or "tasks".
name	string	Group name.
parent_id	int64	Parent ID or 0 for a root group.

---

Response

{
  "ok": true,
  "message": ""
}

POST /group/rename

Rename a group.

---

Request

Header Authorization: Bearer <access_token>

{
  "group_id": 1,
  "name": "New Name"
}

---

Response

{
  "ok": true,
  "message": ""
}

POST /group/delete

Delete a group.

---

Request

Header Authorization: Bearer <access_token>

{
  "group_id": 1
}

---

Response

{
  "ok": true,
  "message": ""
}

POST /group/members

Change the membership of a group.

---

Request

Header Authorization: Bearer <access_token>

{
  "group_id": 1,
  "add": [78, 90],
  "remove": [12]
}

---

Response

{
  "ok": true,
  "message": ""
}

POST /group/move_member

Move an agent between groups

---

Request

Header Authorization: Bearer <access_token>

{
  "agent_id": 78,
  "from_group_id": 3,
  "to_group_id": 7
}

---

Response

{
  "ok": true,
  "message": ""
}

POST /group/reparent

Move a group under a new parent.

---

Request

Header Authorization: Bearer <access_token>

{
  "group_id": 5,
  "new_parent_id": 1
}

---

Response

{
  "ok": true,
  "message": ""
}

Tasks

GET /agent/task/list

Paginated list of agent tasks (or all agents) with filtering and sorting. Includes both running and completed tasks (only those with Sync = true). For still-running JOB tasks, the output (Message / ClearText / MessageType) is overlaid with the accumulated live output from RunningJobs — progress is visible before the task finishes.

---

Request

Header Authorization: Bearer <access_token>

Query Parameters:

Parameter	Type	Default	Description
agent_id	int64	omitted (all)	Agent ID. Omit it, or leave it empty, to list every agent. A non-integer value is rejected
completed	string	omitted	1/true or 0/false. Omit it to return both running and finished tasks
limit	int	100	Max entries (cap 1000)
offset	int	0	Pagination offset
q	string	""	Filter expression (see below)
sort	string	"StartDate"	Sort column
order	string	"desc"	Direction: asc or desc

Sortable columns (sort): TaskId, TaskType, AgentId, Client, User, Computer, StartDate, FinishDate, CommandLine, Completed, Message. Unrecognized values are ignored (falls back to StartDate DESC).

Filter expression (q): mini-DSL for filtering by the fields TaskId, AgentId, Client, User, Computer, CommandLine, Message, ClearText (substring/LIKE):

• Words — regular terms (shell ⇒ LIKE '%shell%' against at least one column).

• & — AND (whitespace between terms also acts as AND).

• | — OR.

• ^(expr) — NOT.

• (expr) — grouping.

• Nesting depth up to 16, string length up to 512 chars.

Examples: shell, shell & ^(failed), download | upload, (admin | system) & ^(test).

---

Response

{
  "items": [
    {
      "a_task_type": 1,
      "a_task_id": 1,
      "a_id": 12,
      "a_client": "operator",
      "a_user": "alice",
      "a_computer": "WS01",
      "a_cmdline": "shell whoami",
      "a_start_time": 1700000000,
      "a_finish_time": 1700000005,
      "a_msg_type": 7,
      "a_message": "CORP\\alice",
      "a_text": "CORP\\alice",
      "a_completed": true
    }
  ],
  "total": 1234,
  "offset": 0,
  "limit": 100
}

a_task_type: 0 local, 1 task, 2 browser, 3 job, 4 tunnel, 5 proxy data.

Errors (HTTP 400):

• invalid filter: ... — syntax error in q.

• agent <id> not found — the agent does not exist (only if agent_id is non-empty).

POST /agent/task/cancel

Cancel tasks — both queued and already dispatched to the agent

---

Request

Header Authorization: Bearer <access_token>

{
  "agent_id": 1,
  "tasks_array": [1]
}

Field	Type	Description
agent_id	int64	Agent ID
tasks_array	int64[]	Array of task IDs to cancel

---

Response

{
  "ok": true,
  "message": ""
}

POST /agent/task/delete

Remove task from Task Manager

---

Request

Header Authorization: Bearer <access_token>

{
  "agent_id": 1,
  "tasks_array": [1]
}

---

Response

{
  "ok": true,
  "message": ""
}

POST /agent/task/save

Save data to Task Manager

---

Request

Header Authorization: Bearer <access_token>

{
  "agent_id": 1,
  "command_line": "string",
  "message_type": 0,
  "message": "string",
  "clear_text": "string"
}

Field	Type	Description
agent_id	int64	Agent ID
command_line	string	Command line
message_type	int	Message type
message	string	HTML message
clear_text	string	Text message

---

Response

{
  "ok": true,
  "message": ""
}

POST /agent/task/hook

Send the result of a task hook

---

Request

Header Authorization: Bearer <access_token>

{
  "a_id": 1,
  "a_task_id": 1,
  "a_hook_id": "string",
  "a_job_index": 0,
  "a_msg_type": 0,
  "a_message": "string",
  "a_text": "string",
  "a_completed": true|false
}

Field	Type	Description
a_id	int64	Agent ID
a_task_id	int64	Task ID
a_hook_id	string	Hook ID
a_job_index	int	Job index
a_msg_type	int	Message type
a_message	string	HTML message
a_text	string	Text message
a_completed	boolean	Task is complete

---

Response

{
  "ok": true,
  "message": ""
}

Chat

GET /chat/history

Paginated message history (newest first).

---

Request

Header Authorization: Bearer <access_token>

Parameter	Type	Default	Description
limit	int	50	Number of messages. A value outside 1..200 is replaced with 50.
before_id	int64	—	Load messages older than this ID (for pagination).

---

Response

{
  "ok": true,
  "messages": [
    {
      "id": 42,
      "username": "admin",
      "message": "Hello team!",
      "date": 1718500000,
      "edited": false,
      "deleted": false,
      "reactions": {"👍": ["user1", "user2"]},
      "reply_to_id": 0,
      "reply_to_name": "",
      "deleted_date": 0
    }
  ],
  "total": 1543
}

GET /chat/search

Full-text search over messages.

---

Request

Header Authorization: Bearer <access_token>

Parameter	Type	Default	Description
q	string	—	Search string (LIKE match).
limit	int	50	Max results. A value outside 1..200 is replaced with 50.
before_id	int64	—	Pagination (older than this ID).

---

Response

POST /chat/clear

Hard-delete all messages from the chat.

---

Request

Header Authorization: Bearer <access_token>

---

Response

{
  "ok": true,
  "message": ""
}

POST /chat/send

Send message to chat

---

Request

Header Authorization: Bearer <access_token>

{
  "message": "string",
  "reply_to_id": 0,
  "reply_to_name": ""
}

Field	Type	Description
message	string	Message text (Markdown supported).
reply_to_id	int64	ID of the message being replied to. 0 = no reply.
reply_to_name	string	Author name of the original message (for the preview). Empty when reply_to_id = 0.

---

Response

{
  "ok": true,
  "message": "<id>"
}

POST /chat/<id>/edit

Edit a message (only the author can edit)

---

Request

Header Authorization: Bearer <access_token>

{
   "message": "New message text"
}

---

Response

{
  "ok": true,
  "message": ""
}

POST /chat/<id>/delete

Soft-delete a message (only the author can delete).

---

Request

Header Authorization: Bearer <access_token>

---

Response

{
  "ok": true,
  "message": ""
}

POST /chat/<id>/react

Toggle the user's reaction on a message. Supported reactions: 👍 ❤️ 🔥 👀 🚀 😂 ✅ ✓ ❌ 💩

---

Request

Header Authorization: Bearer <access_token>

{
  "emoji": "👍"
}

---

Response

{
  "ok": true,
  "message": ""
}

GET /chat/todo

Get the current contents of the Shared ToDo.

---

Request

Header Authorization: Bearer <access_token>

---

Response

{
  "ok": true,
  "content": "## Tasks for the week\n- [ ] Check the logs",
  "updated_by": "admin",
  "updated_at": 1718500000
}

POST /chat/todo

Overwrite the contents of the Shared ToDo.

---

Request

Header Authorization: Bearer <access_token>

{
  "content": "## New tasks\n- [x] Update the documentation"
}

---

Response

{
  "ok": true,
  "message": ""
}

Download

GET /download/list

Paginated list of downloads. Supports filtering and sorting

---

Request

Header Authorization: Bearer <access_token>

Query Parameters:

Parameter	Type	Default	Description
agent_id	int64	omitted (all)	Agent ID. Omit it to list every agent. A non-integer value is rejected
limit	int	100	Max entries (cap 1000)
offset	int	0	Pagination offset
q	string	""	Filter expression
sort	string	"Date"	Sort column
order	string	"desc"	Direction: asc or desc

Sortable columns (sort): FileId, AgentId, AgentName, User, Computer, RemotePath, TotalSize, RecvSize, Date, State.

Filter expression (q): mini-DSL with terms/&/|/^()/(...) (see /agent/task/list). Filter columns: FileId, AgentId, AgentName, User, Computer, RemotePath.

---

Response

{
  "items": [
    {
      "t_file_id": 1001,
      "t_agent_id": 12,
      "t_agent_name": "beacon",
      "t_user": "alice",
      "t_computer": "WS01",
      "t_remote_path": "C:\\Users\\alice\\Desktop\\notes.txt",
      "t_local_path": "******",
      "t_total_size": 4096,
      "t_progress": 4096,
      "t_date": 1718500000,
      "t_state": 3,
      "t_tag": "",
      "t_cancellable": false,
      "t_kind": 0
    }
  ],
  "total": 42,
  "offset": 0,
  "limit": 100
}

POST /download/sync

Get the contents of a file.

---

Request

Header Authorization: Bearer <access_token>

{
  "file_id": 1
}

---

Response

{
  "ok": true,
  "filename": "string",
  "content": "<base64_encoded_content>"
}

POST /download/delete

Delete file

---

Request

Header Authorization: Bearer <access_token>

{
  "file_id_array": [123, 456]
}

---

Response

{
  "ok": true,
  "message": ""
}

POST /download/set/tag

Bulk set/clear the tag of a group of downloads.

---

Request

Header Authorization: Bearer <access_token>

{
  "id_array": [123, 456, 789],
  "tag": "credentials-dump"
}

---

Response

{
  "ok": true,
  "message": ""
}

Upload

GET /upload/list

Paginated list of uploads

---

Request

Header Authorization: Bearer <access_token>

Query Parameters:

Parameter	Type	Default	Description
agent_id	int64	0 (all)	Filter by agent; 0 or empty — all
offset	int	0	Offset from the start of the result set
limit	int	100	Max entries per page (cap 1000)
q	string	empty	Filter mini-DSL (term & term, ^(neg), (group), `
sort	string	Date	Sort column (see table below)
order	string	desc	asc or desc

Sortable columns: FileId, AgentId, AgentName, User, Computer, RemotePath, TotalSize, Progress, Date, State, Tag, Kind, ArtifactName, ArtifactType.

Filterable columns (q): FileId, AgentId, AgentName, User, Computer, RemotePath, Tag, ArtifactName, ArtifactType.

---

Response

{
  "items": [
    {
      "t_file_id": 1234567890,
      "t_agent_id": 42,
      "t_agent_name": "beacon_http",
      "t_user": "DESKTOP\\alice",
      "t_computer": "DESKTOP",
      "t_remote_path": "C:\\Users\\alice\\Desktop\\loader.exe",
      "t_local_path": "******",
      "t_total_size": 1048576,
      "t_progress": 524288,
      "t_date": 1715520000,
      "t_state": 1,
      "t_tag": "",
      "t_cancellable": true,
      "t_kind": 0,
      "t_artifact_name": "",
      "t_artifact_type": ""
    }
  ],
  "total": 17,
  "offset": 0,
  "limit": 100
}

POST /download/delete

Bulk cancel-and-remove uploads.

---

Request

Header Authorization: Bearer <access_token>

{
  "id_array": [1234567890, 9876543210]
}

---

Response

{
  "ok": true,
  "message": ""
}

Screenshot

GET /screen/list

Paginated list of screenshots with filtering and sorting.

---

Request

Header Authorization: Bearer <access_token>

Query Parameters:

Parameter	Type	Default	Description
limit	int	100	Max entries (cap 1000)
offset	int	0	Pagination offset
q	string	""	Filter expression
sort	string	"Date"	Sort column
order	string	"desc"	Direction: asc or desc

Sortable columns (sort): ScreenId, User, Computer, Note, Date.

Filter expression (q): Filter columns: ScreenId, User, Computer, Note.

---

Response

{
  "items": [
    {
      "s_screen_id": 4,
      "s_agent_id": 12,
      "s_user": "alice",
      "s_computer": "WS01",
      "s_local_path": "",
      "s_note": "desktop",
      "s_date": 1718500000,
      "s_content": null
    }
  ],
  "total": 17,
  "offset": 0,
  "limit": 100
}

GET /screen/image?screen_id=

Raw PNG for one screenshot.

---

Request

Header Authorization: Bearer <access_token>

---

Response

body is image/png. An unknown id returns {"ok":false,"message":"..."}.

POST /screen/setnote

Set a note for a screenshot

---

Request

Header Authorization: Bearer <access_token>

{
  "screen_id_array": [1],
  "note": "string"
}

---

Response

{
  "ok": true,
  "message": ""
}

POST /screen/remove

Remove a screenshots

---

Request

Header Authorization: Bearer <access_token>

{
  "screen_id_array": [1]
}

---

Response

{
  "ok": true,
  "message": ""
}

Creds

GET /creds/list

Paginated list of credentials with filtering and sorting.

---

Request

Header Authorization: Bearer <access_token>

Query Parameters:

Parameter	Type	Default	Description
agent_id	int64	omitted (all)	Source agent ID. Omit it to list every agent. A non-integer value is rejected
limit	int	100	Max entries (cap 1000)
offset	int	0	Pagination offset
q	string	""	Filter expression
sort	string	"Date"	Sort column
order	string	"desc"	Direction: asc or desc

Sortable columns (sort): CredId, Username, Password, Realm, Type, Tag, Date, Storage, AgentId, Host.

Filter expression (q): Filter columns: CredId, Username, Password, Realm, Type, Tag, Storage, AgentId, Host.

---

Response (200 OK):

{
  "items": [
    {
      "c_creds_id": 3,
      "c_username": "alice",
      "c_password": "password",
      "c_realm": "CORP",
      "c_type": "plaintext",
      "c_tag": "domain",
      "c_date": 1718500000,
      "c_storage": "lsass",
      "c_agent_id": 12,
      "c_host": "dc01.corp.local"
    }
  ],
  "total": 256,
  "offset": 0,
  "limit": 100
}

POST /creds/add

Store credentials to Creds Manager

---

Request Body:

{
  "creds": [
    {
      "username": "string",
      "password": "string",
      "realm": "string",
      "type": "string",
      "tag": "string",
      "storage": "string",
      "host": "string"
    }
  ]
}

Field	Type	Description
username	string	User name
password	string	Password / hash
realm	string	Domain / realm
type	string	Type (plaintext, ntlm, etc.)
tag	string	Tag
storage	string	Source
host	string	Host

---

Response:

{
  "ok": true,
  "message": ""
}

POST /creds/edit

Edit stored credentials

---

Request:

{
  "cred_id": 1,
  "username": "string",
  "password": "string",
  "realm": "string",
  "type": "string",
  "tag": "string",
  "storage": "string",
  "host": "string"
}

---

Response:

{
  "ok": true,
  "message": ""
}

POST /creds/set/tag

Set creds tag

---

Request Body:

{
  "id_array": [1],
  "tag": "string"
}

---

Response:

{
  "ok": true,
  "message": ""
}

POST /creds/remove

Delete credentials.

---

Request:

{
  "cred_id_array": [1]
}

---

Response:

{
  "ok": true,
  "message": ""
}

Targets

GET /targets/list

Paginated list of targets with filtering and sorting.

---

Request

Header Authorization: Bearer <access_token>

Query Parameters:

Parameter	Type	Default	Description
limit	int	100	Max entries (cap 1000)
offset	int	0	Pagination offset
q	string	""	Filter expression
sort	string	"Date"	Sort column
order	string	"desc"	Direction: asc or desc

Sortable columns (sort): TargetId, Computer, Domain, Address, Tag, Os, OsDesk, Date, Info, Alive.

Filter expression (q): mini-DSL (see /agent/task/list). Filter columns: TargetId, Computer, Domain, Address, Tag, OsDesk, Info.

---

Response (200 OK):

{
  "items": [
    {
      "t_target_id": 2,
      "t_computer": "DC01",
      "t_domain": "corp.local",
      "t_address": "10.0.0.10",
      "t_os": 1,
      "t_os_desk": "Windows Server 2019",
      "t_tag": "dc",
      "t_info": "",
      "t_date": 1718500000,
      "t_alive": true,
      "t_agents": [12]
    }
  ],
  "total": 8,
  "offset": 0,
  "limit": 100
}

t_os uses the same values as a_os: 0 unknown, 1 Windows, 2 Linux, 3 macOS.

POST /targets/add

Store targets to Targets Manager

---

Request:

{
  "targets": [
    {
      "computer": "string",
      "domain": "string",
      "address": "string",
      "os": 0,
      "os_desk": "string",
      "tag": "string",
      "info": "string",
      "alive": true|false
    }
  ]
}

Field	Type	Description
computer	string	Computer name
domain	string	Domain
address	string	IP address
os	int	OS code
os_desk	string	OS description
tag	string	Tag
info	string	Additional information
alive	boolean	Alive status

---

Response:

{
  "ok": true,
  "message": ""
}

POST /targets/edit

Edit stored target

---

Request:

{
  "t_target_id": 1,
  "t_computer": "string",
  "t_domain": "string",
  "t_address": "string",
  "t_os": 0,
  "t_os_desk": "string",
  "t_tag": "string",
  "t_info": "string",
  "t_alive": true|false
}

---

Response:

{
  "ok": true,
  "message": ""
}

POST /targets/set/tag

Set target tag

---

Request:

{
  "id_array": [1],
  "tag": "string"
}

---

Response:

{
  "ok": true,
  "message": ""
}

POST /targets/remove

Remove stored targets

---

Request:

{
  "target_id_array": [1]
}

---

Response:

{
  "ok": true,
  "message": ""
}

Tunnel

GET /tunnel/list

Get a list of tunnels with full information

---

Request

Header Authorization: Bearer <access_token>

---

Response

[
  {
    "p_tunnel_id": 7,
    "p_agent_id": 12,
    "p_computer": "WS01",
    "p_username": "alice",
    "p_process": "explorer.exe",
    "p_type": "socks5",
    "p_info": "socks5 127.0.0.1:1080",
    "p_interface": "127.0.0.1",
    "p_port": "1080",
    "p_client": "operator",
    "p_fhost": "",
    "p_fport": "",
    "p_auth_user": "",
    "p_auth_pass": "",
    "p_date": 1718500000,
    "p_active": true
  }
]

POST /start/socks5

Start socks5 proxy

---

Request:

Header Authorization: Bearer <access_token>

{
  "agent_id": 1,
  "listen": true|false,
  "desc": "string",
  "l_host": "string",
  "l_port": 1080,
  "use_auth": true|false,
  "username": "string",
  "password": "string"
}

Field	Type	Required	Description
agent_id	int64	Yes	Agent ID
listen	boolean	No	Listening mode
desc	string	No	Tunnel description
l_host	string	Yes	Local host to bind
l_port	int	Yes	Local port (1-65535)
use_auth	boolean	No	Use authentication
username	string	When use_auth=true	User name
password	string	When use_auth=true	Password

---

Response:

{
  "ok": true,
  "message": 123
}

POST /start/socks4

Start socks4 proxy

---

Request:

Header Authorization: Bearer <access_token>

{
  "agent_id": 1,
  "listen": true|false,
  "desc": "string",
  "l_host": "string",
  "l_port": 1080
}

Field	Type	Required	Description
agent_id	int64	Yes	Agent ID
listen	boolean	No	Listening mode
desc	string	No	Tunnel description
l_host	string	Yes	Local host
l_port	int	Yes	Local port (1-65535)

---

Response:

{
  "ok": true,
  "message": 123
}

POST /start/lportfwd

Start local port forwarding

---

Request

Header Authorization: Bearer <access_token>

{
  "agent_id": 1,
  "listen": true|false,
  "desc": "string",
  "l_host": "string",
  "l_port": 8080,
  "t_host": "string",
  "t_port": 80
}

Field	Type	Required	Description
agent_id	int64	Yes	Agent ID
listen	boolean	No	Listening mode
desc	string	No	Description
l_host	string	Yes	Local host
l_port	int	Yes	Local port (1-65535)
t_host	string	Yes	Target host
t_port	int	Yes	Target port (1-65535)

---

Response:

{
  "ok": true,
  "message": 123
}

POST /start/rportfwd

Start reverse port forwarding

---

Request

Header Authorization: Bearer <access_token>

{
  "agent_id": 1,
  "listen": true|false,
  "desc": "string",
  "port": 8080,
  "t_host": "string",
  "t_port": 80
}

Field	Type	Required	Description
agent_id	int64	Yes	Agent ID
listen	boolean	No	true — server tunnel, false — client tunnel (target on the client side)
desc	string	No	Description
port	int	Yes	Port on the agent (1-65535)
t_host	string	Yes	Target host
t_port	int	Yes	Target port (1-65535)

Modes:

• listen=true (server-side) — the agent's inbound connections are proxied by the server to t_host:t_port.

• listen=false (client-side) — the t_host:t_port target is dialed by the owning client: on an inbound connection the agent sends TsTunnelConnectionAccept, the server creates a pending channel and delivers the sync packet TYPE_TUNNEL_ACCEPT (0x5a) to the owner; the client dials the target locally (15-second timeout) and attaches to the channel via channel-OTP (mode="reverse"), or rejects it via POST /tunnel/channel/nack. The owner has 45 seconds to attach (reverseAttachTimeout).

---

Response:

{
  "ok": true,
  "message": 123
}

POST /set/info

Set tunnel info

---

Request (JSON)

Header Authorization: Bearer <access_token>

{
  "p_tunnel_id": 123,
  "p_info": "string"
}

---

Response:

{
  "ok": true,
  "message": "Tunnel info updated"
}

POST /tunnel/stop

Stop tunnel

---

Request

Header Authorization: Bearer <access_token>

{
  "p_tunnel_id": 123
}

---

Response:

{
  "ok": true,
  "message": "Tunnel stopped"
}

POST /tunnel/pause

Pause a tunnel

---

Request

Header Authorization: Bearer <access_token>

{
  "p_tunnel_id": 123
}

---

Response:

{
  "ok": true,
  "message": "Tunnel paused"
}

POST /tunnel/resume

Resume a tunnel

---

Request

Header Authorization: Bearer <access_token>

{
  "p_tunnel_id": 123
}

---

Response:

{
  "ok": true,
  "message": "Tunnel resumed"
}

Payloads

GET /payload/list

Paginated payload list.

---

Request

Header Authorization: Bearer <access_token>

Query Parameters:

Parameter	Type	Default	Description
show_hidden	bool	false	Include hidden payloads.
q	string	—	Filter DSL (same as /agent/task/list).
sort	string	Created	Sort column.
order	string	desc	asc / desc.
limit	int	100	Max entries.
offset	int	0	Offset.

---

Response

```json
{
  "items": [
    {
      "p_id": 12,
      "p_name": "beacon_https",
      "p_type": "beacon",
      "p_artifact": "exe",
      "p_arch": "x64",
      "p_listeners": ["http-443"],
      "p_size": 307200,
      "p_sha1": "…",
      "p_sha256": "…",
      "p_md5": "…",
      "p_creator": "admin",
      "p_date": 1718500000,
      "p_hidden": false,
      "p_filename": "beacon_https.exe",
      "p_notes": "",
      "p_tag": "",
      "p_color": "",
      "p_build_id": "",
      "p_watermark": "c04c4e57",
      "p_missing": false
    }
  ],
  "total": 42,
  "offset": 0,
  "limit": 100
}
```

POST /payload/get

Full payload by id

---

Request

Header Authorization: Bearer <access_token>

{
  "payload_id": 12
}

---

Response:

{
  "ok": true,
  "payload": {
    "p_id": 12,
    "p_name": "beacon_https",
    "p_type": "beacon",
    "p_artifact": "exe",
    "p_arch": "x64",
    "p_listeners": ["http-443"],
    "p_size": 307200,
    "p_sha1": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
    "p_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "p_md5": "d41d8cd98f00b204e9800998ecf8427e",
    "p_creator": "admin",
    "p_date": 1718500000,
    "p_hidden": false,
    "p_config": "{\"sleep\":5}",
    "p_build_id": "b1",
    "p_watermark": "c04c4e57",
    "p_filename": "beacon_https.exe",
    "p_notes": "",
    "p_tag": "",
    "p_uid": "uid-1",
    "p_color": "",
    "p_missing": false
  }
}

POST /payload/download

Payload content.

---

Request

Header Authorization: Bearer <access_token>

{
  "payload_id": 12
}

---

Response:

{
  "ok": true,
  "filename": "beacon_https.exe",
  "content": "<base64>"
}

POST /payload/hide

Hide/show payloads

---

Request

Header Authorization: Bearer <access_token>

{
  "id_array": [12, 13],
  "hidden": true
}

POST /payload/update

Update payload metadata.

---

Request

Header Authorization: Bearer <access_token>

{
  "payload_id": 12,
  "name": "beacon_https_v2",
  "notes": "staging build",
  "artifact": "exe",
  "arch": "x64",
  "hidden": false
}

POST /payload/set_color

Payload row colour.

---

Request

Header Authorization: Bearer <access_token>

{
  "id_array": [12],
  "background": "#222222",
  "foreground": "#ff0000",
  "reset": false
}

---

Response:

{
  "ok": true,
  "filename": "beacon_https.exe",
  "content": "<base64>"
}

POST /payload/set/tag

Payload tag.

---

Request

Header Authorization: Bearer <access_token>

{
  "id_array": [12],
  "tag": "staging"
}

POST /payload/remove

Remove payloads. hard=true — delete both the record and the on-disk file; hard=false — record only (the file stays).

---

Request

Header Authorization: Bearer <access_token>

{
  "id_array": [12],
  "hard": true
}

POST /payload/import

Import an external file into the store.

---

Request

Header Authorization: Bearer <access_token>

{
  "name": "custom_agent",
  "agent_type": "beacon",
  "artifact": "exe",
  "arch": "x64",
  "listeners": [],
  "content": "<base64>",
  "config": ""
}

Field	Type	Description
name	string	Name (default imported).
agent_type	string	Agent type (default imported).
artifact	string	Artifact kind.
arch	string	Architecture.
listeners	[]string	Bound listeners.
content	string	Base64 file content (required).
config	string	Build-config JSON.

---

Response:

{
  "ok": true
}

Services

GET /service/list

Get the list of loaded services.

---

Request

Header Authorization: Bearer <access_token>

---

Response

```json
{
  "message": "success",
  "services": "[{\"Name\":\"notifier\",\"AX\":\"function ServiceUI() {}\"}]"
}
```

GET /service/catalog

Registered services with their AxScript command catalogs.

---

Request

Header Authorization: Bearer <access_token>

---

Response

```json
[
  {
    "name": "notifier",
    "title": "Notifier",
    "description": "",
    "rpc": true,
    "commands": [
      { "name": "get_config", "description": "..." }
    ]
  }
]
```

POST /plugin/service/call

Call a service function.

---

Request

Header Authorization: Bearer <access_token>

{
  "service": "string",
  "command": "string",
  "args": "string"
}

---

Response:

{
  "message": "success",
  "result": "ok"
}

POST /plugin/service/call_wait

Synchronous service function call (TsPluginServiceCallWait). Blocks until the CallRPC JSON result or timeout.

---

Request

Header Authorization: Bearer <access_token>

{
  "service": "string",
  "command": "string",
  "args": "string",
  "timeout_ms": 30000
}

---

Response:

{
  "message": "success",
  "result": "{...json from CallRPC...}"
}

POST /plugin/agent/call

Asynchronous call of an agent-plugin function for a specific session (TsPluginAgentCall).

---

Request

Header Authorization: Bearer <access_token>

{
  "agent_id": 42,
  "command": "get_panel",
  "args": "{\"foo\": 1}"
}

---

Response:

{
  "message": "success",
  "result": "ok"
}

POST /plugin/listener/call

Asynchronous call of a listener-plugin function for a specific instance (TsPluginListenerCall).

---

Request

Header Authorization: Bearer <access_token>

{
  "listener": "http-443",
  "command": "get_stats",
  "args": "{}"
}

---

Response:

{
  "message": "success",
  "result": "{...json from CallRPC...}"
}

Events

GET /events/handlers

Paginated handler list with filtering.

---

Request

Header Authorization: Bearer <access_token>

Query Parameters:

Parameter	Type	Default	Description
offset	int	0	Offset
limit	int	50	Max entries (cap 1000; 0 → 50)
q	string	—	Search over id/name/description/group/event/source/last_error
event	string	—	Exact event type (e.g. agent.new)
source	string	—	Source: handler (AxScript) / extender / core
group	string	—	Exact group name
enabled	string	—	true/1 — enabled only; false/0 — disabled only

---

Response

```json
{
  "items": [
    {
      "id": "h_abc123",
      "name": "notify-new-agents",
      "description": "Logs new agents",
      "group": "notifications",
      "event": "agent.new",
      "source": "handler",
      "enabled": true,
      "event_muted": false,
      "filters": { "agent_names": ["win-*"], "os": ["windows"] },
      "last_error": "",
      "last_run_at": 1718500000
    }
  ],
  "total": 12,
  "offset": 0,
  "limit": 50
}
```

POST /events/handlers/register

Register a new handler (or update an existing one when id is passed). The script is dry-compiled: it must define function handler(event) (or onEvent(event)), otherwise the registration is rejected.

---

Request

Header Authorization: Bearer <access_token>

{
  "id": "",
  "name": "notify-new-agents",
  "group": "notifications",
  "description": "Logs new agents",
  "event": "agent.new",
  "script": "function handler(event) { ax.log('new agent: ' + event.agentName); }",
  "enabled": true,
  "filters": { "os": ["windows"] }
}

Field	Type	Description
id	string	Optional. ID of an existing handler — to update it.
name	string	Required. Name (sanitised: letters/digits/-/_).
group	string	Optional. Grouping.
description	string	Optional. Description.
event	string	Required. Event type (see KnownEventTypes, e.g. agent.new).
script	string	Required. JS code with handler(event).
enabled	bool	Optional (default true).
filters	object	Optional. EventFilter (see below).

---

Response:

{
  "ok": true,
  "message": "",
  "data": {
    "id": "h_abc123",
    "name": "notify-new-agents",
    "group": "notifications",
    "description": "Logs new agents",
    "event": "agent.new",
    "script": "function handler(event) { ax.log('new agent'); }",
    "enabled": true,
    "filters": { "os": ["windows"] },
    "created_by": "admin",
    "updated_by": "admin",
    "created_at": 1718500000,
    "updated_at": 1718500000,
    "last_error": "",
    "last_run_at": 0
  }
}

POST /events/handlers/get

Fetch a full handler (including the source script).

---

Request

Header Authorization: Bearer <access_token>

{
  "id": "h_abc123"
}

---

Response:

{
  "ok": true,
  "message": "",
  "data": {
    "id": "h_abc123",
    "name": "notify-new-agents",
    "group": "notifications",
    "description": "Logs new agents",
    "event": "agent.new",
    "script": "function handler(event) { ax.log('new agent'); }",
    "enabled": true,
    "filters": { "os": ["windows"] },
    "created_by": "admin",
    "updated_by": "admin",
    "created_at": 1718500000,
    "updated_at": 1718500000,
    "last_error": "",
    "last_run_at": 0
  }
}

Errors:

• id is required.

• event handler not found.

POST /events/handlers/enable

Enable a handler.

---

Request

Header Authorization: Bearer <access_token>

{
  "id": "h_abc123"
}

---

Response:

{
  "ok": true,
  "message": ""
}

POST /events/handlers/disable

Disable a handler

---

Request

Header Authorization: Bearer <access_token>

{
  "id": "h_abc123"
}

---

Response:

{
  "ok": true,
  "message": ""
}

POST /events/handlers/remove

Remove a handler.

---

Request

Header Authorization: Bearer <access_token>

{
  "id": "h_abc123"
}

---

Response:

{
  "ok": true,
  "message": ""
}

POST /events/mute

Mute an event type: all hook dispatch for this type is suppressed (both AxScript handlers and extender hooks).

---

Request

Header Authorization: Bearer <access_token>

{
  "event": "agent.update"
}

---

Response:

{
  "ok": true,
  "message": ""
}

POST /events/unmute

Unmute an event type.

---

Request

Header Authorization: Bearer <access_token>

{
  "event": "agent.update"
}

---

Response:

{
  "ok": true,
  "message": ""
}

POST /events/mutes

List of muted event types.

---

Request

Header Authorization: Bearer <access_token>

---

Response:

{
  "ok": true,
  "message": "",
  "items": ["agent.update", "task.update"]
}

POST /events/types

Sorted list of all valid event types — system (KnownEventTypes) plus the custom domain.action format.

---

Request

Header Authorization: Bearer <access_token>

---

Response:

["agent.new", "agent.remove", "task.create", "ops.deploy"]

POST /events/emit

Emit a custom event

---

Request

Header Authorization: Bearer <access_token>

{
  "event": "ops.deploy",
  "source": "operator:admin",
  "text": "staging deploy finished"
}

---

Response:

{
  "ok": true,
  "message": ""
}

Logs

GET /logs/list

Paginated reads from the server-side LogManager ring buffer

---

Request

Header Authorization: Bearer <access_token>

Query Parameters:

Parameter	Type	Default	Description
limit	int	200	Max entries in the response. Cap 2000.
offset	int	0	How many most-recent entries to skip (ignored when before_id is set).
before_id	int64	—	Return entries with Id < before_id (cursor pagination for "Load earlier").
source	string	—	Filter by the source field (server, listener, agent, axscript, service).
category	string	—	Filter by category.
q	string	—	Substring: matches source, category, the log-source key, and the entry text (message).

---

Response

```json
{
  "items": [
    {
      "id": 12345,
      "time": 1714322400,
      "status": 1,
      "level": 0,
      "source": "listener",
      "category": "beacon_http",
      "message": "Started listener 'http-1': https://0.0.0.0:8443"
    },
    {
      "id": 12344,
      "time": 1714322399,
      "status": 4,
      "level": 0,
      "source": "server",
      "category": "profile",
      "message": "'Teamserver.cert': failed to stat file: no such file"
    }
  ],
  "total": 5000,
  "offset": 0,
  "limit": 200,
  "has_more": true,
  "oldest_id": 12344,
  "sources": ["server:profile", "listener:beacon_http"],
  "categories": { "server": ["profile", "database"], "listener": ["beacon_http"] }
}
```