# TeamSpeak ServerQuery Reference

ServerQuery is a text-based management interface built into TeamSpeak servers. It allows full remote administration — managing clients, channels, groups, permissions, bans and more.

This reference was captured from a live TS3 server running version `3.13.7 [Build: 1655727713]` on Linux.

**Credentials:** The ServerQuery admin password is printed to the server console on first startup. The default login name is `serveradmin`. If you lost the password, restart the server with `serveradmin_password=yournewpassword` to reset it.

---

## Protocol

ServerQuery can be accessed via raw TCP (port `10011`), SSH (port `10022`), or WebQuery (REST API). The commands and responses are the same across all transports — only the connection method differs. This reference was created using the raw TCP interface on a TeamSpeak 3 server. Raw TCP is a deprecated feature and no longer exists in TeamSpeak 6 — it was removed in favor of SSH and WebQuery due to the lack of encryption. 

Connect with any raw TCP client (e.g. `telnet`, `plink -raw`). On connect the server sends a banner:

```
TS3
Welcome to the TeamSpeak 3 ServerQuery interface, type "help" for a list of commands and "help <command>" for information on a specific command.
```

After that, send one command per line. Every response ends with `error id=0 msg=ok` on success or `error id=N msg=<text>` on failure. Most commands require authentication via [`login`](#login) first. Instance-level commands ([`serverlist`](#serverlist), [`serverstart`](#serverstart), [`hostinfo`](#hostinfo), [`instanceinfo`](#instanceinfo), etc.) work without [`use`](#use), but virtual-server commands require selecting one first with [`use`](#use).

**Command syntax:**
- Parameters use `key=value` pairs separated by spaces: `command key1=value1 key2=value2`
- Flags have no value and are prefixed with `-`: `clientlist -uid -away`
- Pipe-separated lists pass multiple entries at once: `clientkick clid=1|clid=2`

**Response syntax:**
- Single-entry responses: `key1=value1 key2=value2`
- Multi-entry (list) responses: entries separated by `|`: `key=val1|key=val2`

### String Escaping

All string values are escaped. Apply these substitutions when encoding outgoing values and reverse them when decoding incoming values:

| Escape | Character | Description |
|---|---|---|
| `\\` | `\` | Backslash |
| `\/` | `/` | Forward slash |
| `\s` | ` ` | Space |
| `\p` | `\|` | Pipe |
| `\n` | LF | Newline (ASCII 10) |
| `\r` | CR | Carriage return (ASCII 13) |
| `\t` | TAB | Horizontal tab (ASCII 9) |
| `\a` | BEL | Bell (ASCII 7) |
| `\b` | BS | Backspace (ASCII 8) |
| `\f` | FF | Form feed (ASCII 12) |
| `\v` | VT | Vertical tab (ASCII 11) |

### Types

| Type | Description |
|---|---|
| `string` | Escaped text string |
| `int` | Signed 32-bit integer |
| `uint` | Unsigned 32-bit integer |
| `ulong` | Unsigned 64-bit integer |
| `bool` | `0` or `1` |
| `unix_ts` | Unix timestamp (seconds since epoch) |
| `float` | Floating-point number |
| `flag` | Command flag (no value, prefixed with `-`) |

---

## Error Codes

| ID | Message | Description |
|---|---|---|
| `0` | `ok` | Success |
| `256` | `command not found` | Unknown command name |
| `512` | `unable to bind network port` | Port already in use |
| `1024` | `check failed` / `invalid serverID` | Not logged in, authentication failed, or no virtual server selected ([`use`](#use) not called) |
| `1025` | `unable to open network port` | Virtual server port unavailable (e.g. already in use); triggered by [`serverstart`](#serverstart) |
| `1280` | `database error` | General database failure |
| `1281` | `database empty result set` | List command returned no entries |
| `1282` | `database duplicate entry` | Unique constraint violation |
| `1283` | `database no modifications` | Update had no effect |
| `1538` | `invalid parameter` | Required parameter missing or malformed |
| `1540` | `parameter list size mismatch` | Pipe-separated parameter lists have different lengths |
| `2048` | `insufficient client permissions` | Missing required permission |
| `2049` | `virtual server limit reached` | Instance virtual server limit exceeded |
| `2568` | `insufficient permission modify power` | Permission modify power too low |

---

## Connection & Authentication

### `login`
Authenticate with the server instance. Positional shorthand: `login <username> <password>`

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `client_login_name` | string | yes | Query login username |
| `client_login_password` | string | yes | Query login password |

**Response:** none

---

### `logout`
Deselect the active virtual server and log out.

**Response:** none

---

### `use`
Select a virtual server to interact with.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `sid` | int | one of sid/port | Virtual server ID |
| `port` | int | one of sid/port | Virtual server UDP port |
| `-virtual` | flag | no | Connect as virtual (invisible) client |
| `client_nickname` | string | no | Override query client nickname |

**Response:** none

---

### `whoami`
Display information about the current session.

**Response:**
| Field | Type | Description |
|---|---|---|
| `virtualserver_status` | string | `online` or `offline` |
| `virtualserver_id` | int | Current virtual server ID |
| `virtualserver_unique_identifier` | string | Server UID |
| `virtualserver_port` | int | Server UDP port |
| `client_id` | int | Your session client ID |
| `client_channel_id` | int | Your current channel ID |
| `client_nickname` | string | Your current nickname |
| `client_database_id` | int | Your database ID |
| `client_login_name` | string | Your query login name |
| `client_unique_identifier` | string | Your UID |
| `client_origin_server_id` | int | Origin server ID |

---

## Server Information

### `version`
Display server version.

**Response:**
| Field | Type | Description |
|---|---|---|
| [`version`](#version) | string | Version string (e.g. `3.13.7`) |
| `build` | uint | Build number |
| `platform` | string | OS platform (e.g. `Linux`, `Windows`) |

---

### `serverinfo`
Display virtual server properties.

**Response:**
| Field | Type | Description |
|---|---|---|
| `virtualserver_id` | int | Server ID |
| `virtualserver_unique_identifier` | string | Server UID |
| `virtualserver_name` | string | Server name |
| `virtualserver_welcomemessage` | string | Welcome message |
| `virtualserver_platform` | string | OS platform |
| `virtualserver_version` | string | TS server version |
| `virtualserver_maxclients` | int | Max simultaneous clients |
| `virtualserver_password` | string | Password (empty if none) |
| `virtualserver_clientsonline` | int | Voice clients online |
| `virtualserver_queryclientsonline` | int | Query clients online |
| `virtualserver_channelsonline` | int | Channels currently online |
| `virtualserver_created` | unix_ts | Server creation time |
| `virtualserver_uptime` | int | Uptime in seconds |
| `virtualserver_codec_encryption_mode` | int | 0=disabled, 1=supported, 2=forced |
| `virtualserver_hostmessage` | string | Host message |
| `virtualserver_hostmessage_mode` | int | 0=none, 1=log, 2=modal, 3=modalquit |
| `virtualserver_default_server_group` | int | Default server group ID |
| `virtualserver_default_channel_group` | int | Default channel group ID |
| `virtualserver_default_channel_admin_group` | int | Default channel admin group ID |
| `virtualserver_flag_password` | bool | Whether server has a password |
| `virtualserver_hostbanner_url` | string | Host banner click URL |
| `virtualserver_hostbanner_gfx_url` | string | Host banner image URL |
| `virtualserver_hostbanner_gfx_interval` | int | Banner refresh interval (seconds) |
| `virtualserver_hostbutton_tooltip` | string | Host button tooltip |
| `virtualserver_hostbutton_url` | string | Host button click URL |
| `virtualserver_hostbutton_gfx_url` | string | Host button image URL |
| `virtualserver_complain_autoban_count` | int | Complaints before autoban |
| `virtualserver_complain_autoban_time` | int | Autoban duration (seconds) |
| `virtualserver_complain_remove_time` | int | Complain expiry (seconds) |
| `virtualserver_min_clients_in_channel_before_forced_silence` | int | Min clients before forced silence |
| `virtualserver_priority_speaker_dimm_modificator` | float | Priority speaker volume reduction (dB) |
| `virtualserver_antiflood_points_tick_reduce` | int | Flood protection tick reduction |
| `virtualserver_antiflood_points_needed_command_block` | int | Points to block commands |
| `virtualserver_antiflood_points_needed_ip_block` | int | Points to block IP |
| `virtualserver_client_connections` | int | Total voice client connections |
| `virtualserver_query_client_connections` | int | Total query client connections |
| `virtualserver_port` | int | UDP port |
| `virtualserver_autostart` | bool | Start automatically with instance |
| `virtualserver_machine_id` | string | Machine ID (empty if default) |
| `virtualserver_needed_identity_security_level` | int | Minimum identity security level |
| `virtualserver_log_client` | bool | Log client events |
| `virtualserver_log_query` | bool | Log query events |
| `virtualserver_log_channel` | bool | Log channel events |
| `virtualserver_log_permissions` | bool | Log permission events |
| `virtualserver_log_server` | bool | Log server events |
| `virtualserver_log_filetransfer` | bool | Log file transfer events |
| `virtualserver_min_client_version` | unix_ts | Minimum client build date |
| `virtualserver_name_phonetic` | string | Phonetic name (TTS) |
| `virtualserver_icon_id` | int | CRC32 icon ID |
| `virtualserver_max_download_total_bandwidth` | ulong | Max download bandwidth (bytes/s) |
| `virtualserver_max_upload_total_bandwidth` | ulong | Max upload bandwidth (bytes/s) |
| `virtualserver_download_quota` | ulong | Download quota |
| `virtualserver_upload_quota` | ulong | Upload quota |
| `virtualserver_month_bytes_downloaded` | ulong | Bytes downloaded this month |
| `virtualserver_month_bytes_uploaded` | ulong | Bytes uploaded this month |
| `virtualserver_total_bytes_downloaded` | ulong | Total bytes downloaded |
| `virtualserver_total_bytes_uploaded` | ulong | Total bytes uploaded |
| `virtualserver_reserved_slots` | int | Reserved client slots |
| `virtualserver_total_packetloss_speech` | float | Avg packet loss — speech traffic |
| `virtualserver_total_packetloss_keepalive` | float | Avg packet loss — keepalive traffic |
| `virtualserver_total_packetloss_control` | float | Avg packet loss — control traffic |
| `virtualserver_total_packetloss_total` | float | Avg packet loss — all traffic |
| `virtualserver_total_ping` | float | Avg ping of connected clients (ms) |
| `virtualserver_ip` | string | Bound IP addresses (comma-separated) |
| `virtualserver_weblist_enabled` | bool | Listed on public server list |
| `virtualserver_ask_for_privilegekey` | bool | Prompt for privilege key on connect |
| `virtualserver_hostbanner_mode` | int | Banner mode: 0=no adjust, 1=ignore aspect, 2=keep aspect |
| `virtualserver_channel_temp_delete_delay_default` | int | Default temp channel delete delay (seconds) |
| `virtualserver_min_android_version` | unix_ts | Minimum Android client build date |
| `virtualserver_min_ios_version` | unix_ts | Minimum iOS client build date |
| `virtualserver_nickname` | string | Server query client nickname |
| `virtualserver_antiflood_points_needed_plugin_block` | int | Points to block plugin commands |
| `virtualserver_capability_extensions` | string | Capability extensions |
| `virtualserver_file_storage_class` | string | File storage backend class |
| `virtualserver_status` | string | Server status (e.g. "online") |
| `connection_filetransfer_bandwidth_sent` | int | Current file transfer bandwidth sent (bytes/s) |
| `connection_filetransfer_bandwidth_received` | int | Current file transfer bandwidth received (bytes/s) |
| `connection_filetransfer_bytes_sent_total` | long | Total file transfer bytes sent |
| `connection_filetransfer_bytes_received_total` | long | Total file transfer bytes received |
| `connection_packets_sent_speech` | long | Speech packets sent |
| `connection_bytes_sent_speech` | long | Speech bytes sent |
| `connection_packets_received_speech` | long | Speech packets received |
| `connection_bytes_received_speech` | long | Speech bytes received |
| `connection_packets_sent_keepalive` | long | Keepalive packets sent |
| `connection_bytes_sent_keepalive` | long | Keepalive bytes sent |
| `connection_packets_received_keepalive` | long | Keepalive packets received |
| `connection_bytes_received_keepalive` | long | Keepalive bytes received |
| `connection_packets_sent_control` | long | Control packets sent |
| `connection_bytes_sent_control` | long | Control bytes sent |
| `connection_packets_received_control` | long | Control packets received |
| `connection_bytes_received_control` | long | Control bytes received |
| `connection_packets_sent_total` | long | Total packets sent |
| `connection_bytes_sent_total` | long | Total bytes sent |
| `connection_packets_received_total` | long | Total packets received |
| `connection_bytes_received_total` | long | Total bytes received |
| `connection_bandwidth_sent_last_second_total` | int | Avg bandwidth sent last second (bytes/s) |
| `connection_bandwidth_sent_last_minute_total` | int | Avg bandwidth sent last minute (bytes/s) |
| `connection_bandwidth_received_last_second_total` | int | Avg bandwidth received last second (bytes/s) |
| `connection_bandwidth_received_last_minute_total` | int | Avg bandwidth received last minute (bytes/s) |

> **Note:** If called without [`use`](#use), the server responds with a default template entry (`virtualserver_status=template`) instead of an error.

---

### `serveredit`
Change virtual server properties. All parameters are optional; omit any you do not want to change.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `virtualserver_name` | string | no | Server name |
| `virtualserver_welcomemessage` | string | no | Welcome message |
| `virtualserver_maxclients` | int | no | Max simultaneous clients |
| `virtualserver_password` | string | no | Connection password (empty to remove) |
| `virtualserver_codec_encryption_mode` | int | no | 0=disabled, 1=supported, 2=forced |
| `virtualserver_hostmessage` | string | no | Host message |
| `virtualserver_hostmessage_mode` | int | no | 0=none, 1=log, 2=modal, 3=modalquit |
| `virtualserver_default_server_group` | int | no | Default server group ID |
| `virtualserver_default_channel_group` | int | no | Default channel group ID |
| `virtualserver_default_channel_admin_group` | int | no | Default channel admin group ID |
| `virtualserver_hostbanner_url` | string | no | Host banner click URL |
| `virtualserver_hostbanner_gfx_url` | string | no | Host banner image URL |
| `virtualserver_hostbanner_gfx_interval` | int | no | Banner refresh interval (seconds) |
| `virtualserver_hostbutton_tooltip` | string | no | Host button tooltip |
| `virtualserver_hostbutton_url` | string | no | Host button click URL |
| `virtualserver_hostbutton_gfx_url` | string | no | Host button image URL |
| `virtualserver_complain_autoban_count` | int | no | Complaints before autoban |
| `virtualserver_complain_autoban_time` | int | no | Autoban duration (seconds) |
| `virtualserver_complain_remove_time` | int | no | Complain expiry (seconds) |
| `virtualserver_min_clients_in_channel_before_forced_silence` | int | no | Min clients in channel before forced silence |
| `virtualserver_priority_speaker_dimm_modificator` | float | no | Priority speaker volume reduction (dB) |
| `virtualserver_antiflood_points_tick_reduce` | int | no | Flood protection tick reduction per tick |
| `virtualserver_antiflood_points_needed_command_block` | int | no | Points to trigger command block |
| `virtualserver_antiflood_points_needed_ip_block` | int | no | Points to trigger IP block |
| `virtualserver_port` | int | no | UDP port |
| `virtualserver_autostart` | bool | no | Start automatically with instance |
| `virtualserver_machine_id` | string | no | Machine ID |
| `virtualserver_needed_identity_security_level` | int | no | Minimum identity security level |
| `virtualserver_log_client` | bool | no | Log client events |
| `virtualserver_log_query` | bool | no | Log query events |
| `virtualserver_log_channel` | bool | no | Log channel events |
| `virtualserver_log_permissions` | bool | no | Log permission events |
| `virtualserver_log_server` | bool | no | Log server events |
| `virtualserver_log_filetransfer` | bool | no | Log file transfer events |
| `virtualserver_min_client_version` | unix_ts | no | Minimum client build date |
| `virtualserver_name_phonetic` | string | no | Phonetic name (TTS) |
| `virtualserver_icon_id` | int | no | CRC32 icon ID |
| `virtualserver_max_download_total_bandwidth` | ulong | no | Max download bandwidth (bytes/s) |
| `virtualserver_max_upload_total_bandwidth` | ulong | no | Max upload bandwidth (bytes/s) |
| `virtualserver_download_quota` | ulong | no | Download quota (bytes) |
| `virtualserver_upload_quota` | ulong | no | Upload quota (bytes) |

**Response:** none

---

### `hostinfo`
Display server instance connection info.

**Response:**
| Field | Type | Description |
|---|---|---|
| `instance_uptime` | int | Instance uptime (seconds) |
| `host_timestamp_utc` | unix_ts | Current UTC time |
| `virtualservers_running_total` | int | Running virtual servers |
| `virtualservers_total_maxclients` | int | Total max clients across all servers |
| `virtualservers_total_clients_online` | int | Total clients online |
| `virtualservers_total_channels_online` | int | Total channels online |
| `connection_filetransfer_bandwidth_sent` | ulong | File transfer bandwidth sent (bytes/s) |
| `connection_filetransfer_bandwidth_received` | ulong | File transfer bandwidth received (bytes/s) |
| `connection_filetransfer_bytes_sent_total` | ulong | Total file transfer bytes sent |
| `connection_filetransfer_bytes_received_total` | ulong | Total file transfer bytes received |
| `connection_packets_sent_total` | ulong | Total UDP packets sent |
| `connection_bytes_sent_total` | ulong | Total bytes sent |
| `connection_packets_received_total` | ulong | Total UDP packets received |
| `connection_bytes_received_total` | ulong | Total bytes received |
| `connection_bandwidth_sent_last_second_total` | ulong | Bandwidth sent last second |
| `connection_bandwidth_sent_last_minute_total` | ulong | Bandwidth sent last minute (avg) |
| `connection_bandwidth_received_last_second_total` | ulong | Bandwidth received last second |
| `connection_bandwidth_received_last_minute_total` | ulong | Bandwidth received last minute (avg) |

---

### `instanceinfo`
Display server instance configuration.

**Response:**
| Field | Type | Description |
|---|---|---|
| `serverinstance_database_version` | int | Database schema version |
| `serverinstance_filetransfer_port` | int | File transfer TCP port |
| `serverinstance_max_download_total_bandwidth` | ulong | Max download bandwidth |
| `serverinstance_max_upload_total_bandwidth` | ulong | Max upload bandwidth |
| `serverinstance_guest_serverquery_group` | int | Guest ServerQuery group ID |
| `serverinstance_serverquery_flood_commands` | int | Commands before flood block |
| `serverinstance_serverquery_flood_time` | int | Flood measurement window (seconds) |
| `serverinstance_serverquery_ban_time` | int | Flood ban duration (seconds) |
| `serverinstance_template_serveradmin_group` | int | Template server admin group ID |
| `serverinstance_template_serverdefault_group` | int | Template server default group ID |
| `serverinstance_template_channeladmin_group` | int | Template channel admin group ID |
| `serverinstance_template_channeldefault_group` | int | Template channel default group ID |
| `serverinstance_permissions_version` | int | Permissions schema version |
| `serverinstance_pending_connections_per_ip` | int | Pending connections per IP limit |
| `serverinstance_serverquery_max_connections_per_ip` | int | Max query connections per IP |

---

### `instanceedit`
Change server instance configuration. All parameters are optional; omit any you do not want to change.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `serverinstance_filetransfer_port` | int | no | File transfer TCP port |
| `serverinstance_max_download_total_bandwidth` | ulong | no | Max download bandwidth (bytes/s) |
| `serverinstance_max_upload_total_bandwidth` | ulong | no | Max upload bandwidth (bytes/s) |
| `serverinstance_guest_serverquery_group` | int | no | Guest ServerQuery group ID |
| `serverinstance_serverquery_flood_commands` | int | no | Commands before flood block |
| `serverinstance_serverquery_flood_time` | int | no | Flood measurement window (seconds) |
| `serverinstance_serverquery_ban_time` | int | no | Flood ban duration (seconds) |
| `serverinstance_template_serveradmin_group` | int | no | Template server admin group ID |
| `serverinstance_template_serverdefault_group` | int | no | Template server default group ID |
| `serverinstance_template_channeladmin_group` | int | no | Template channel admin group ID |
| `serverinstance_template_channeldefault_group` | int | no | Template channel default group ID |
| `serverinstance_pending_connections_per_ip` | int | no | Pending connections per IP limit |
| `serverinstance_serverquery_max_connections_per_ip` | int | no | Max query connections per IP |

**Response:** none

---

### `serverlist`
List virtual servers.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `-uid` | flag | no | Include `virtualserver_unique_identifier` |
| `-all` | flag | no | Include offline servers |
| `-short` | flag | no | Shorter output |
| `-onlyoffline` | flag | no | Only offline servers |

**Response** *(entries separated by `|`)*:
| Field | Type | Description |
|---|---|---|
| `virtualserver_id` | int | Server ID |
| `virtualserver_port` | int | UDP port |
| `virtualserver_status` | string | `online` or `offline` |
| `virtualserver_clientsonline` | int | Voice clients online |
| `virtualserver_queryclientsonline` | int | Query clients online |
| `virtualserver_maxclients` | int | Max clients |
| `virtualserver_uptime` | int | Uptime in seconds |
| `virtualserver_name` | string | Server name |
| `virtualserver_autostart` | bool | Auto-start enabled |
| `virtualserver_machine_id` | string | Machine ID |
| `virtualserver_unique_identifier` | string | Server UID (`-uid` only) |

---

### `serveridgetbyport`
Get virtual server ID by UDP port.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `virtualserver_port` | int | yes | UDP port to look up |

**Response:**
| Field | Type | Description |
|---|---|---|
| `server_id` | int | Virtual server ID |

---

### `serverrequestconnectioninfo`
Display connection statistics for the selected virtual server.

**Response:**
| Field | Type | Description |
|---|---|---|
| `connection_filetransfer_bandwidth_sent` | ulong | File transfer bandwidth sent (bytes/s) |
| `connection_filetransfer_bandwidth_received` | ulong | File transfer bandwidth received (bytes/s) |
| `connection_packets_sent_total` | ulong | Total packets sent |
| `connection_bytes_sent_total` | ulong | Total bytes sent |
| `connection_packets_received_total` | ulong | Total packets received |
| `connection_bytes_received_total` | ulong | Total bytes received |
| `connection_bandwidth_sent_last_second_total` | ulong | Bandwidth sent last second |
| `connection_bandwidth_sent_last_minute_total` | ulong | Bandwidth sent last minute (avg) |
| `connection_bandwidth_received_last_second_total` | ulong | Bandwidth received last second |
| `connection_bandwidth_received_last_minute_total` | ulong | Bandwidth received last minute (avg) |

---

### `serverstart`
Start a virtual server.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `sid` | int | yes | Virtual server ID |

**Response:** none

---

### `serverstop`
Stop a virtual server.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `sid` | int | yes | Virtual server ID |
| `reasonmsg` | string | no | Message sent to clients before disconnect |

**Response:** none

---

### `serverprocessstop`
Shut down the entire TS server process.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `reasonmsg` | string | no | Message sent to clients before disconnect |

**Response:** none

---

### `servercreate`
Create a new virtual server.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `virtualserver_name` | string | yes | Server name |
| `virtualserver_port` | int | no | UDP port (auto-assigned if omitted) |
| `virtualserver_maxclients` | int | no | Max clients |
| `virtualserver_password` | string | no | Connection password |
| `virtualserver_autostart` | bool | no | Auto-start with instance |
| `virtualserver_welcomemessage` | string | no | Welcome message |
| `virtualserver_default_server_group` | int | no | Default server group ID |
| `virtualserver_default_channel_group` | int | no | Default channel group ID |

**Response:**
| Field | Type | Description |
|---|---|---|
| `sid` | int | New virtual server ID |
| `virtualserver_port` | int | Assigned UDP port |
| `token` | string | Initial server admin privilege key |

---

### `serverdelete`
Delete a virtual server (must be stopped first).

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `sid` | int | yes | Virtual server ID |

**Response:** none

---

### `serversnapshotcreate`
Create a full snapshot of the virtual server.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `password` | string | no | Encrypts the snapshot data |

**Response:**
| Field | Type | Description |
|---|---|---|
| `version` | int | Snapshot format version |
| `salt` | string | Encryption salt (only when password used) |
| `data` | string | Base64-encoded snapshot data |

---

### `serversnapshotdeploy`
Restore a virtual server from a snapshot.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `-mapping` | flag | no | Return old→new channel ID mapping in response |
| `-keepfiles` | flag | no | Preserve files for channels present in both backup and server |
| `password` | string | no | Decryption password (if snapshot was encrypted) |
| `version` | int | yes | Snapshot format version |
| `salt` | string | no | Encryption salt (if encrypted) |
| `data` | string | yes | Base64-encoded snapshot data |

**Response:** none, or with `-mapping`:
| Field | Type | Description |
|---|---|---|
| `ocid` | int | Old channel ID |
| `ncid` | int | New channel ID |

---

### `servertemppasswordadd`
Add a temporary server password.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `pw` | string | yes | Temporary password |
| `desc` | string | yes | Description |
| `duration` | int | yes | Validity in seconds |
| `tcid` | int | yes | Auto-join channel ID (0=default channel) |
| `tcpw` | string | yes | Password of auto-join channel (empty if none) |

**Response:** none

---

### `servertemppassworddel`
Delete a temporary server password.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `pw` | string | yes | Password to delete |

**Response:** none

---

### `servertemppasswordlist`
List active temporary server passwords.

**Response** *(entries separated by `|`)*:
| Field | Type | Description |
|---|---|---|
| `nickname` | string | Creator's nickname |
| `uid` | string | Creator's UID |
| `desc` | string | Description |
| `pw_clear` | string | The password in clear text |
| `start` | unix_ts | Creation time |
| `end` | unix_ts | Expiry time |
| `tcid` | int | Auto-join channel ID |

---

### `bindinglist`
List IP address bindings.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `subsystem` | string | no | `voice`, `query`, or `filetransfer` (default: `voice`) |

**Response** *(entries separated by `|`)*:
| Field | Type | Description |
|---|---|---|
| `ip` | string | Bound IP address |

---

## Clients

### `clientlist`
List clients currently online.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `-uid` | flag | no | Add `client_unique_identifier` |
| `-away` | flag | no | Add `client_away`, `client_away_message` |
| `-voice` | flag | no | Add voice/mute/hardware/recording/priority status |
| `-times` | flag | no | Add `client_idle_time`, `client_created`, `client_lastconnected` |
| `-groups` | flag | no | Add `client_servergroups`, `client_channel_group_id` |
| `-info` | flag | no | Add `client_version`, `client_platform` |
| `-country` | flag | no | Add `client_country` |
| `-ip` | flag | no | Add `connection_client_ip` (requires `b_client_remoteaddress_view`) |
| `-icon` | flag | no | Add `client_icon_id` |
| `-badges` | flag | no | Add `client_badges` |

**Response** *(entries separated by `|`)*:
| Field | Type | Flag | Description |
|---|---|---|---|
| `clid` | int | always | Session client ID |
| `cid` | int | always | Current channel ID |
| `client_database_id` | int | always | Permanent database ID |
| `client_nickname` | string | always | Nickname |
| `client_type` | int | always | 0=voice, 1=query |
| `client_unique_identifier` | string | `-uid` | Unique identifier |
| `client_away` | bool | `-away` | Away status |
| `client_away_message` | string | `-away` | Away message |
| `client_flag_talking` | bool | `-voice` | Currently talking |
| `client_input_muted` | bool | `-voice` | Microphone muted |
| `client_output_muted` | bool | `-voice` | Speakers muted |
| `client_input_hardware` | bool | `-voice` | Has input device |
| `client_output_hardware` | bool | `-voice` | Has output device |
| `client_is_recording` | bool | `-voice` | Is recording |
| `client_is_priority_speaker` | bool | `-voice` | Priority speaker |
| `client_talk_power` | int | `-voice` | Talk power value |
| `client_is_talker` | bool | `-voice` | Has talker status |
| `client_is_channel_commander` | bool | `-voice` | Channel commander mode |
| `client_idle_time` | int | `-times` | Idle time (ms) |
| `client_created` | unix_ts | `-times` | First connect time |
| `client_lastconnected` | unix_ts | `-times` | Last connect time |
| `client_servergroups` | string | `-groups` | Comma-separated group IDs |
| `client_channel_group_id` | int | `-groups` | Channel group ID |
| `client_channel_group_inherited_channel_id` | int | `-groups` | Channel from which group is inherited |
| `client_version` | string | `-info` | Client version string |
| `client_platform` | string | `-info` | Client OS platform |
| `client_country` | string | `-country` | Two-letter country code |
| `connection_client_ip` | string | `-ip` | Client IP address |
| `client_icon_id` | int | `-icon` | CRC32 icon ID |
| `client_badges` | string | `-badges` | Raw badges string |

---

### `clientinfo`
Display detailed info about a specific client.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `clid` | int | yes | Session client ID |

**Response:**
| Field | Type | Description |
|---|---|---|
| `cid` | int | Current channel ID |
| `client_database_id` | int | Permanent database ID |
| `client_nickname` | string | Nickname |
| `client_type` | int | `0`=voice, `1`=query |
| `client_unique_identifier` | string | Unique identifier |
| `client_away` | bool | Away status |
| `client_away_message` | string | Away message |
| `client_input_muted` | bool | Microphone muted |
| `client_output_muted` | bool | Speakers muted |
| `client_input_hardware` | bool | Has input device |
| `client_output_hardware` | bool | Has output device |
| `client_is_recording` | bool | Is recording |
| `client_is_priority_speaker` | bool | Priority speaker |
| `client_idle_time` | int | Idle time (ms) |
| `client_created` | unix_ts | First connect time |
| `client_lastconnected` | unix_ts | Last connect time |
| `client_servergroups` | string | Comma-separated server group IDs |
| `client_channel_group_id` | int | Channel group ID |
| `client_version` | string | Client version string |
| `client_platform` | string | Client OS platform |
| `client_country` | string | Two-letter country code |
| `client_icon_id` | int | CRC32 icon ID |
| `client_badges` | string | Raw badges string |
| `client_flag_avatar` | string | MD5 hash of client avatar; empty if none |
| `client_version_sign` | string | Cryptographic version signature |
| `client_security_hash` | string | Security hash |
| `client_login_name` | string | Query login name (empty for voice clients) |
| `client_totalconnections` | int | Total connection count |
| `client_outputonly_muted` | bool | Output-only mute mode |
| `client_default_channel` | string | Default channel path |
| `client_meta_data` | string | Client-set metadata |
| `client_talk_power` | int | Talk power value |
| `client_talk_request` | bool | Has pending talk request |
| `client_talk_request_msg` | string | Talk request message |
| `client_description` | string | Client description |
| `client_is_talker` | bool | Has talker status |
| `client_month_bytes_uploaded` | ulong | Bytes uploaded this month |
| `client_month_bytes_downloaded` | ulong | Bytes downloaded this month |
| `client_total_bytes_uploaded` | ulong | Total bytes uploaded |
| `client_total_bytes_downloaded` | ulong | Total bytes downloaded |
| `client_nickname_phonetic` | string | Phonetic nickname (TTS) |
| `client_needed_serverquery_view_power` | int | Required view power to see this client |
| `client_default_token` | string | Default privilege key |
| `client_channel_group_inherited_channel_id` | int | Channel from which group is inherited |
| `client_myteamspeak_id` | string | MyTeamSpeak account ID |
| `client_integrations` | string | MyTeamSpeak integrations |
| `client_myteamspeak_avatar` | string | MyTeamSpeak avatar |
| `client_signed_badges` | string | Comma-separated signed badge UUIDs |
| `client_base64HashClientUID` | string | Base64 hash of UID |
| `connection_filetransfer_bandwidth_sent` | ulong | File transfer bandwidth sent (bytes/s) |
| `connection_filetransfer_bandwidth_received` | ulong | File transfer bandwidth received (bytes/s) |
| `connection_packets_sent_total` | ulong | Total packets sent |
| `connection_bytes_sent_total` | ulong | Total bytes sent |
| `connection_packets_received_total` | ulong | Total packets received |
| `connection_bytes_received_total` | ulong | Total bytes received |
| `connection_bandwidth_sent_last_second_total` | ulong | Bandwidth sent last second |
| `connection_bandwidth_sent_last_minute_total` | ulong | Bandwidth sent last minute |
| `connection_bandwidth_received_last_second_total` | ulong | Bandwidth received last second |
| `connection_bandwidth_received_last_minute_total` | ulong | Bandwidth received last minute |
| `connection_connected_time` | int | Connected duration (ms) |
| `connection_client_ip` | string | Client IP address |

> **Note:** `clientlist -ip` returns `connection_client_ip` but no other `connection_*` fields. [`serverinfo`](#serverinfo) returns a full set of server-level `connection_*` stats; [`clientinfo`](#clientinfo) returns a per-client subset.

---

### `clientedit`
Change a client's properties.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `clid` | int | yes | Session client ID |
| `client_nickname` | string | no | New nickname |
| `client_is_talker` | bool | no | Grant/revoke talker status |
| `client_description` | string | no | Description (max 200 chars) |
| `client_is_channel_commander` | bool | no | Channel commander status |
| `client_icon_id` | int | no | CRC32 icon ID |

**Response:** none

---

### `clientupdate`
Change your own query client properties.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `client_nickname` | string | no | New nickname |

**Response:** none

---

### `clientmove`
Move one or more clients to a channel.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `clid` | int | yes | Client ID (repeatable with `\|`) |
| `cid` | int | yes | Target channel ID |
| `cpw` | string | no | Target channel password |
| `-continueonerror` | flag | no | Skip errors and continue |

**Response:** none

---

### `clientkick`
Kick one or more clients from channel or server.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `clid` | int | yes | Client ID (repeatable with `\|`) |
| `reasonid` | int | yes | `4`=kick from channel, `5`=kick from server |
| `reasonmsg` | string | no | Message shown to kicked client (max 40 chars) |
| `-continueonerror` | flag | no | Skip errors and continue |

**Response:** none

---

### `clientpoke`
Send a poke message to a client.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `clid` | int | yes | Session client ID |
| `msg` | string | yes | Poke message text |

**Response:** none

---

### `clientfind`
Find clients by nickname pattern.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `pattern` | string | yes | Nickname pattern (case-insensitive) |

**Response** *(entries separated by `|`)*:
| Field | Type | Description |
|---|---|---|
| `clid` | int | Session client ID |
| `client_nickname` | string | Nickname |

---

### `clientgetdbidfromuid`
Get database ID from UID.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `cluid` | string | yes | Client UID |

**Response:**
| Field | Type | Description |
|---|---|---|
| `cluid` | string | Client UID |
| `cldbid` | int | Client database ID |

---

### `clientgetids`
Get all session IDs for a UID.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `cluid` | string | yes | Client UID |

**Response** *(entries separated by `|`)*:
| Field | Type | Description |
|---|---|---|
| `cluid` | string | Client UID |
| `clid` | int | Session client ID |
| `client_nickname` | string | Nickname |

---

### `clientgetnamefromdbid`
Get nickname from database ID.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `cldbid` | int | yes | Client database ID |

**Response:**
| Field | Type | Description |
|---|---|---|
| `cluid` | string | Client UID |
| `cldbid` | int | Client database ID |
| `name` | string | Nickname |

---

### `clientgetnamefromuid`
Get nickname from UID.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `cluid` | string | yes | Client UID |

**Response:**
| Field | Type | Description |
|---|---|---|
| `cluid` | string | Client UID |
| `cldbid` | int | Client database ID |
| `name` | string | Nickname |

---

### `clientgetuidfromclid`
Get UID from session client ID.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `clid` | int | yes | Session client ID |

**Response:**
| Field | Type | Description |
|---|---|---|
| `clid` | int | Session client ID |
| `cluid` | string | Client UID |
| `nickname` | string | Nickname |

---

### `clientsetserverquerylogin`
Set your own query login credentials.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `client_login_name` | string | yes | Desired login name |

**Response:**
| Field | Type | Description |
|---|---|---|
| `client_login_password` | string | Generated password |

---

## Client Database

### `clientdblist`
List known client identities.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `start` | int | no | Skip first N entries |
| `duration` | int | no | Return at most N entries |
| `-count` | flag | no | Also return `count` (total entries) |

**Response** *(entries separated by `|`)*:
| Field | Type | Description |
|---|---|---|
| `cldbid` | int | Database ID |
| `client_unique_identifier` | string | UID |
| `client_nickname` | string | Last known nickname |
| `client_created` | unix_ts | First connection time |
| `client_lastconnected` | unix_ts | Last connection time |
| `client_totalconnections` | int | Total connections |
| `client_flag_avatar` | string | Avatar MD5 hash |
| `client_description` | string | Description |
| `count` | int | Total entries (`-count` only) |

---

### `clientdbinfo`
Display detailed database info for a client.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `cldbid` | int | yes | Client database ID |

**Response:**
| Field | Type | Description |
|---|---|---|
| `client_unique_identifier` | string | UID |
| `client_nickname` | string | Last known nickname |
| `client_database_id` | int | Database ID |
| `client_created` | unix_ts | First connection time |
| `client_lastconnected` | unix_ts | Last connection time |
| `client_totalconnections` | int | Total connections |
| `client_flag_avatar` | string | Avatar MD5 hash |
| `client_description` | string | Description |
| `client_month_bytes_uploaded` | ulong | Bytes uploaded this month |
| `client_month_bytes_downloaded` | ulong | Bytes downloaded this month |
| `client_total_bytes_uploaded` | ulong | Total bytes uploaded |
| `client_total_bytes_downloaded` | ulong | Total bytes downloaded |
| `client_base64HashClientUID` | string | Base64 hash of UID |
| `client_lastip` | string | Last known IP address |

> **Note:** [`clientdbinfo`](#clientdbinfo) is the only command returning `client_lastip`. Does not return `connection_*` stats.

---

### `clientdbedit`
Edit a client's database entry.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `cldbid` | int | yes | Client database ID |
| `client_description` | string | no | Description |

**Response:** none

---

### `clientdbdelete`
Delete a client's database entry.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `cldbid` | int | yes | Client database ID |

**Response:** none

---

### `clientdbfind`
Search for clients by nickname or UID.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `pattern` | string | yes | SQL-style pattern (supports `%` wildcard) |
| `-uid` | flag | no | Search by UID instead of nickname |

**Response** *(entries separated by `|`)*:
| Field | Type | Description |
|---|---|---|
| `cldbid` | int | Client database ID |

---

## Channels

### `channellist`
List channels on the virtual server.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `-topic` | flag | no | Add `channel_topic` |
| `-flags` | flag | no | Add `channel_flag_default`, `channel_flag_password`, `channel_flag_permanent`, `channel_flag_semi_permanent` |
| `-voice` | flag | no | Add `channel_codec`, `channel_codec_quality`, `channel_needed_talk_power` |
| `-limits` | flag | no | Add `total_clients_family` |
| `-icon` | flag | no | Add `channel_icon_id` |
| `-secondsempty` | flag | no | Add `seconds_empty` |
| `-banners` | flag | no | Add `channel_banner_gfx_url`, `channel_banner_mode` |

**Response** *(entries separated by `|`)*:
| Field | Type | Flag | Description |
|---|---|---|---|
| `cid` | int | always | Channel ID |
| `pid` | int | always | Parent channel ID (0=root) |
| `channel_order` | int | always | Sort position (ID of channel above, 0=top) |
| `channel_name` | string | always | Channel name |
| `total_clients` | int | always | Clients currently in channel |
| `channel_topic` | string | `-topic` | Channel topic |
| `channel_flag_default` | bool | `-flags` | Is default channel |
| `channel_flag_password` | bool | `-flags` | Has password |
| `channel_flag_permanent` | bool | `-flags` | Is permanent |
| `channel_flag_semi_permanent` | bool | `-flags` | Is semi-permanent |
| `channel_codec` | int | `-voice` | Codec (4=Opus Voice, 5=Opus Music) |
| `channel_codec_quality` | int | `-voice` | Codec quality (0-10) |
| `channel_needed_talk_power` | int | `-voice` | Required talk power |
| `total_clients_family` | int | `-limits` | Clients in channel family |
| `channel_icon_id` | int | `-icon` | CRC32 icon ID |
| `seconds_empty` | int | `-secondsempty` | Seconds empty (-1 if not empty) |
| `channel_banner_gfx_url` | string | `-banners` | Banner image URL |
| `channel_banner_mode` | int | `-banners` | 0=no adjust, 1=ignore aspect, 2=keep aspect |

---

### `channelinfo`
Display detailed info about a channel.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `cid` | int | yes | Channel ID |

**Response:**
| Field | Type | Description |
|---|---|---|
| `cid` | int | Channel ID |
| `pid` | int | Parent channel ID |
| `channel_name` | string | Channel name |
| `channel_topic` | string | Topic |
| `channel_description` | string | Description |
| `channel_password` | string | Password (hashed, empty if none) |
| `channel_codec` | int | Codec (4=Opus Voice, 5=Opus Music) |
| `channel_codec_quality` | int | Codec quality (0-10) |
| `channel_maxclients` | int | Max clients (-1=unlimited) |
| `channel_maxfamilyclients` | int | Max family clients (-1=unlimited/inherited) |
| `channel_order` | int | Sort position |
| `channel_flag_permanent` | bool | Is permanent |
| `channel_flag_semi_permanent` | bool | Is semi-permanent |
| `channel_flag_default` | bool | Is default channel |
| `channel_flag_password` | bool | Has password |
| `channel_codec_latency_factor` | int | Codec latency factor |
| `channel_codec_is_unencrypted` | bool | Is unencrypted |
| `channel_security_salt` | string | Security salt |
| `channel_delete_delay` | int | Auto-delete delay when empty (seconds) |
| `channel_unique_identifier` | string | Channel UID (UUID) |
| `channel_flag_maxclients_unlimited` | bool | No client limit |
| `channel_flag_maxfamilyclients_unlimited` | bool | No family client limit |
| `channel_flag_maxfamilyclients_inherited` | bool | Inherit family limit from parent |
| `channel_filepath` | string | File storage path |
| `channel_needed_talk_power` | int | Required talk power |
| `channel_forced_silence` | bool | Forced silence active |
| `channel_name_phonetic` | string | Phonetic name (TTS) |
| `channel_icon_id` | int | CRC32 icon ID |
| `channel_banner_gfx_url` | string | Banner image URL |
| `channel_banner_mode` | int | 0=no adjust, 1=ignore aspect, 2=keep aspect |
| `seconds_empty` | int | Seconds empty (-1 if not empty) |

---

### `channelcreate`
Create a new channel.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `channel_name` | string | yes | Channel name |
| `cpid` | int | no | Parent channel ID (0 = root) |
| `channel_topic` | string | no | Topic |
| `channel_description` | string | no | Description |
| `channel_password` | string | no | Password |
| `channel_codec` | int | no | 4=Opus Voice, 5=Opus Music |
| `channel_codec_quality` | int | no | 0-10 |
| `channel_maxclients` | int | no | Max clients (-1=unlimited) |
| `channel_maxfamilyclients` | int | no | Max family clients |
| `channel_order` | int | no | Sort position (ID of channel above) |
| `channel_flag_permanent` | bool | no | Make permanent |
| `channel_flag_semi_permanent` | bool | no | Make semi-permanent |
| `channel_flag_default` | bool | no | Set as default channel |
| `channel_flag_maxclients_unlimited` | bool | no | Unlimited clients |
| `channel_flag_maxfamilyclients_unlimited` | bool | no | Unlimited family clients |
| `channel_flag_maxfamilyclients_inherited` | bool | no | Inherit family limit |
| `channel_codec_is_unencrypted` | bool | no | Disable encryption |
| `channel_delete_delay` | int | no | Auto-delete delay (seconds) |
| `channel_needed_talk_power` | int | no | Required talk power |
| `channel_name_phonetic` | string | no | Phonetic name (TTS) |
| `channel_icon_id` | int | no | CRC32 icon ID |
| `channel_banner_gfx_url` | string | no | Banner image URL |
| `channel_banner_mode` | int | no | 0=no adjust, 1=ignore aspect, 2=keep aspect |

**Response:**
| Field | Type | Description |
|---|---|---|
| `cid` | int | ID of the newly created channel |

---

### `channeledit`
Edit an existing channel.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `cid` | int | yes | Channel ID |
| `cpid` | int | no | New parent channel ID |
| `channel_name` | string | no | Channel name |
| `channel_topic` | string | no | Topic |
| `channel_description` | string | no | Description |
| `channel_password` | string | no | Password (empty to remove) |
| `channel_codec` | int | no | 4=Opus Voice, 5=Opus Music |
| `channel_codec_quality` | int | no | 0-10 |
| `channel_maxclients` | int | no | Max clients (-1=unlimited) |
| `channel_maxfamilyclients` | int | no | Max family clients |
| `channel_order` | int | no | Sort position (ID of channel above) |
| `channel_flag_permanent` | bool | no | Make permanent |
| `channel_flag_semi_permanent` | bool | no | Make semi-permanent |
| `channel_flag_default` | bool | no | Set as default channel |
| `channel_flag_maxclients_unlimited` | bool | no | Unlimited clients |
| `channel_flag_maxfamilyclients_unlimited` | bool | no | Unlimited family clients |
| `channel_flag_maxfamilyclients_inherited` | bool | no | Inherit family limit |
| `channel_codec_is_unencrypted` | bool | no | Disable encryption |
| `channel_delete_delay` | int | no | Auto-delete delay (seconds) |
| `channel_needed_talk_power` | int | no | Required talk power |
| `channel_name_phonetic` | string | no | Phonetic name (TTS) |
| `channel_icon_id` | int | no | CRC32 icon ID |
| `channel_banner_gfx_url` | string | no | Banner image URL |
| `channel_banner_mode` | int | no | 0=no adjust, 1=ignore aspect, 2=keep aspect |

**Response:** none

---

### `channeldelete`
Delete a channel.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `cid` | int | yes | Channel ID |
| `force` | bool | yes | `1` = delete even if clients are inside (they get moved to default) |

**Response:** none

---

### `channelmove`
Move a channel to a new parent.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `cid` | int | yes | Channel ID |
| `cpid` | int | yes | New parent channel ID |
| `order` | int | no | Sort position (ID of channel above, 0=top) |

**Response:** none

---

### `channelfind`
Find channels by name pattern.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `pattern` | string | yes | Case-insensitive substring to match |

**Response** *(entries separated by `|`)*:
| Field | Type | Description |
|---|---|---|
| `cid` | int | Channel ID |
| `channel_name` | string | Channel name |

---

## Text & Notifications

### `sendtextmessage`
Send a text message.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `targetmode` | int | yes | `1`=private (to client), `2`=channel, `3`=server |
| `target` | int | yes* | Target client ID (*only used when `targetmode=1`) |
| `msg` | string | yes | Message text |

**Response:** none

---

### `gm`
Send a global text message to all clients on all virtual servers.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `msg` | string | yes | Message text |

**Response:** none

---

### `servernotifyregister`
Register for server event notifications. See [Event Notifications (Push)](#event-notifications-push) for the full list of events and their fields.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `event` | string | yes | `server`, `channel`, `textserver`, `textchannel`, `textprivate`, `tokenused` |
| `id` | int | no | Channel ID (only for `event=channel`) |

**Response:** none

---

### `servernotifyunregister`
Unregister all previously registered event notifications.

**Response:** none

---

## Server Groups

### `servergrouplist`
List all server groups.

**Response** *(entries separated by `|`)*:
| Field | Type | Description |
|---|---|---|
| `sgid` | int | Server group ID |
| `name` | string | Group name |
| `type` | int | `0`=template, `1`=regular, `2`=query |
| `iconid` | int | CRC32 icon ID |
| `savedb` | bool | Persisted in database |
| `sortid` | int | Sort order |
| `namemode` | int | Name display mode |
| `n_modifyp` | int | Required modify power |
| `n_member_addp` | int | Required add-member power |
| `n_member_removep` | int | Required remove-member power |

---

### `servergroupadd`
Create a new server group.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | Group name |
| `type` | int | no | `0`=template, `1`=regular (default), `2`=query |

**Response:**
| Field | Type | Description |
|---|---|---|
| `sgid` | int | ID of the new group |

---

### `servergroupdel`
Delete a server group.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `sgid` | int | yes | Group ID |
| `force` | bool | yes | `1` = delete even if members exist |

**Response:** none

---

### `servergroupcopy`
Copy a server group.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `ssgid` | int | yes | Source group ID |
| `tsgid` | int | yes | Target group ID (`0` = create new) |
| `name` | string | yes | Name for new group (ignored if `tsgid != 0`) |
| `type` | int | yes | `0`=template, `1`=regular, `2`=query |

**Response:**
| Field | Type | Description |
|---|---|---|
| `sgid` | int | ID of the resulting group |

---

### `servergrouprename`
Rename a server group.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `sgid` | int | yes | Server group ID |
| `name` | string | yes | New name |

**Response:** none

---

### `servergrouppermlist`
List permissions assigned to a server group.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `sgid` | int | yes | Server group ID |
| `-permsid` | flag | no | Use permission names instead of numeric IDs |

**Response** *(entries separated by `|`)*:
| Field | Type | Description |
|---|---|---|
| `sgid` | int | Server group ID |
| `permid` | int | Permission ID (without `-permsid`) |
| `permsid` | string | Permission name (with `-permsid`) |
| `permvalue` | int | Permission value |
| `permnegated` | bool | Whether negated |
| `permskip` | bool | Whether skipped |

---

### `servergroupaddclient`
Add client(s) to a server group.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `sgid` | int | yes | Server group ID |
| `cldbid` | int | yes | Client database ID (repeatable with `\|`) |
| `-continueonerror` | flag | no | Skip errors and continue |

**Response:** none

---

### `servergroupdelclient`
Remove client(s) from a server group.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `sgid` | int | yes | Server group ID |
| `cldbid` | int | yes | Client database ID (repeatable with `\|`) |
| `-continueonerror` | flag | no | Skip errors and continue |

**Response:** none

---

## Channel Groups

### `channelgrouplist`
List all channel groups.

**Response** *(entries separated by `|`)*:
| Field | Type | Description |
|---|---|---|
| `cgid` | int | Channel group ID |
| `name` | string | Group name |
| `type` | int | `0`=template, `1`=regular, `2`=query |
| `iconid` | int | CRC32 icon ID |
| `savedb` | bool | Persisted in database |
| `sortid` | int | Sort order |
| `namemode` | int | Name display mode |
| `n_modifyp` | int | Required modify power |
| `n_member_addp` | int | Required add-member power |
| `n_member_removep` | int | Required remove-member power |

---

### `channelgroupadd`
Create a new channel group.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | Group name |
| `type` | int | no | `0`=template, `1`=regular (default), `2`=query |

**Response:**
| Field | Type | Description |
|---|---|---|
| `cgid` | int | ID of the new group |

---

### `channelgroupdel`
Delete a channel group.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `cgid` | int | yes | Channel group ID |
| `force` | bool | yes | `1` = delete even if members exist |

**Response:** none

---

### `channelgroupcopy`
Copy a channel group.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `scgid` | int | yes | Source channel group ID |
| `tcgid` | int | yes | Target channel group ID (`0` = create new) |
| `name` | string | yes | Name for new group (ignored if `tcgid != 0`) |
| `type` | int | yes | `0`=template, `1`=regular, `2`=query |

**Response:**
| Field | Type | Description |
|---|---|---|
| `cgid` | int | ID of the resulting group |

---

### `channelgrouprename`
Rename a channel group.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `cgid` | int | yes | Channel group ID |
| `name` | string | yes | New name |

**Response:** none

---

### `channelgrouppermlist`
List permissions assigned to a channel group.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `cgid` | int | yes | Channel group ID |
| `-permsid` | flag | no | Use permission names instead of numeric IDs |

**Response** *(entries separated by `|`)*:
| Field | Type | Description |
|---|---|---|
| `cgid` | int | Channel group ID |
| `permid` | int | Permission ID (without `-permsid`) |
| `permsid` | string | Permission name (with `-permsid`) |
| `permvalue` | int | Permission value |
| `permnegated` | bool | Whether negated |
| `permskip` | bool | Whether skipped |

---

### `channelgroupclientlist`
Find channel group assignments.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `cid` | int | no | Filter by channel ID |
| `cldbid` | int | no | Filter by client database ID |
| `cgid` | int | no | Filter by channel group ID |

**Response** *(entries separated by `|`)*:
| Field | Type | Description |
|---|---|---|
| `cid` | int | Channel ID |
| `cldbid` | int | Client database ID |
| `cgid` | int | Channel group ID |

---

### `setclientchannelgroup`
Set a client's channel group in a specific channel.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `cgid` | int | yes | Channel group ID |
| `cid` | int | yes | Channel ID |
| `cldbid` | int | yes | Client database ID |

**Response:** none

---

## Permissions

Permissions control what clients and groups are allowed to do. Each permission has a numeric `permid` and a human-readable `permsid` name (e.g. `b_client_ban_create`). Permissions can be assigned to server groups, channel groups, clients globally, clients per-channel, and channels directly — each assignment has three attributes:

- **`permvalue`** — the numeric value of the permission (for boolean permissions `1`=granted, `0`=denied; for power-based permissions a numeric level)
- **`permnegated`** — if `1`, the value is inverted (turns a grant into a deny)
- **`permskip`** — if `1`, this assignment is skipped during the effective permission calculation (used to let sub-admins bypass certain checks)

Use [`permissionlist`](#permissionlist) to get all permission IDs and names, and [`permoverview`](#permoverview) to inspect the effective permissions for a specific client in a channel.

### `permissionlist`
List all available permissions with their IDs and descriptions.

**Response** *(entries separated by `|`)*:
| Field | Type | Description |
|---|---|---|
| `permid` | int | Permission ID |
| `permname` | string | Permission name (e.g. `b_virtualserver_info_view`) |
| `permdesc` | string | Human-readable description |

---

### `permoverview`
Display a client's effective permission overview in a channel.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `cid` | int | yes | Channel ID |
| `cldbid` | int | yes | Client database ID |
| `permid` | int | yes | Permission ID to filter (use `0` for all) |

**Response** *(entries separated by `|`)*:
| Field | Type | Description |
|---|---|---|
| `t` | int | Source type: `0`=server group, `1`=global client, `2`=channel, `3`=channel group, `4`=channel client |
| `id1` | int | Group/client ID |
| `id2` | int | Channel ID (for type 2/4) |
| `p` | int | Permission ID |
| `v` | int | Permission value |
| `n` | bool | Negated |
| `s` | bool | Skip |

---

### `permfind`
Find all assignments of a specific permission.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `permid` | int | one of | Permission ID |
| `permsid` | string | one of | Permission name |

**Response** *(entries separated by `|`)*:
| Field | Type | Description |
|---|---|---|
| `t` | int | Source type: `0`=server group, `1`=global client, `2`=channel, `3`=channel group, `4`=channel client |
| `id1` | int | Group/client ID |
| `id2` | int | Channel ID (for type 2/4) |
| `p` | int | Permission ID |
| `v` | int | Permission value |
| `n` | bool | Negated |
| `s` | bool | Skip |

---

### `permget`
Get current value of a permission for your own connection.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `permid` | int | one of | Permission ID |
| `permsid` | string | one of | Permission name |

**Response:**
| Field | Type | Description |
|---|---|---|
| `permsid` | string | Permission name |
| `permid` | int | Permission ID |
| `permvalue` | int | Effective value |

---

### `permidgetbyname`
Get numeric permission ID from name.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `permsid` | string | yes | Permission name (repeatable with `\|`) |

**Response** *(entries separated by `|`)*:
| Field | Type | Description |
|---|---|---|
| `permsid` | string | Permission name |
| `permid` | int | Permission ID |

---

### `permreset`
Reset all permissions to server defaults (requires server admin).

**Response:** none

---

## Permission Assignments

### `channeladdperm`
Assign permissions to a channel. Multiple permissions can be set in one call using `|`.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `cid` | int | yes | Channel ID |
| `permid` | int | one of | Permission ID |
| `permsid` | string | one of | Permission name |
| `permvalue` | int | yes | Permission value |
| `-continueonerror` | flag | no | Skip errors and continue |

**Response:** none

---

### `channeldelperm`
Remove permissions from a channel. Multiple permissions can be removed in one call using `|`.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `cid` | int | yes | Channel ID |
| `permid` | int | one of | Permission ID |
| `permsid` | string | one of | Permission name |

**Response:** none

---

### `channelpermlist`
List permissions assigned to a channel.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `cid` | int | yes | Channel ID |
| `-permsid` | flag | no | Use permission names instead of numeric IDs |

**Response** *(entries separated by `|`)*:
| Field | Type | Description |
|---|---|---|
| `cid` | int | Channel ID |
| `permid` | int | Permission ID (without `-permsid`) |
| `permsid` | string | Permission name (with `-permsid`) |
| `permvalue` | int | Permission value |
| `permnegated` | bool | Whether negated |
| `permskip` | bool | Whether skipped |

---

### `channelclientaddperm`
Assign permissions to a specific client in a specific channel.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `cid` | int | yes | Channel ID |
| `cldbid` | int | yes | Client database ID |
| `permid` | int | one of | Permission ID |
| `permsid` | string | one of | Permission name |
| `permvalue` | int | yes | Permission value |
| `-continueonerror` | flag | no | Skip errors and continue |

**Response:** none

---

### `channelclientdelperm`
Remove permissions from a client in a specific channel.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `cid` | int | yes | Channel ID |
| `cldbid` | int | yes | Client database ID |
| `permid` | int | one of | Permission ID (repeatable with `\|`) |
| `permsid` | string | one of | Permission name (repeatable with `\|`) |

**Response:** none

---

### `channelclientpermlist`
List permissions assigned to a client in a specific channel.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `cid` | int | yes | Channel ID |
| `cldbid` | int | yes | Client database ID |
| `-permsid` | flag | no | Use permission names instead of numeric IDs |

**Response** *(entries separated by `|`)*:
| Field | Type | Description |
|---|---|---|
| `cid` | int | Channel ID |
| `cldbid` | int | Client database ID |
| `permid` | int | Permission ID (without `-permsid`) |
| `permsid` | string | Permission name (with `-permsid`) |
| `permvalue` | int | Permission value |
| `permnegated` | bool | Whether negated |
| `permskip` | bool | Whether skipped |

---

### `clientaddperm`
Assign permissions to a client globally (database-level).

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `cldbid` | int | yes | Client database ID |
| `permid` | int | one of | Permission ID |
| `permsid` | string | one of | Permission name |
| `permvalue` | int | yes | Permission value |
| `permskip` | bool | yes | `1`=skip, `0`=apply normally |
| `-continueonerror` | flag | no | Skip errors and continue |

**Response:** none

---

### `clientdelperm`
Remove permissions from a client globally.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `cldbid` | int | yes | Client database ID |
| `permid` | int | one of | Permission ID (repeatable with `\|`) |
| `permsid` | string | one of | Permission name (repeatable with `\|`) |

**Response:** none

---

### `clientpermlist`
List permissions assigned to a client globally.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `cldbid` | int | yes | Client database ID |
| `-permsid` | flag | no | Use permission names instead of numeric IDs |

**Response** *(entries separated by `|`)*:
| Field | Type | Description |
|---|---|---|
| `cldbid` | int | Client database ID |
| `permid` | int | Permission ID (without `-permsid`) |
| `permsid` | string | Permission name (with `-permsid`) |
| `permvalue` | int | Permission value |
| `permnegated` | bool | Whether negated |
| `permskip` | bool | Whether skipped |

---

## Bans

### `banlist`
List ban rules.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `start` | int | no | Skip first N entries |
| `duration` | int | no | Return at most N entries |

**Response** *(entries separated by `|`)*:
| Field | Type | Description |
|---|---|---|
| `banid` | int | Ban rule ID |
| `ip` | string | Banned IP (regex, empty if none) |
| `name` | string | Banned nickname pattern (empty if none) |
| `uid` | string | Banned UID (empty if none) |
| `mytsid` | string | Banned MyTS ID (empty if none) |
| `lastnickname` | string | Last known nickname |
| `created` | unix_ts | Ban creation time |
| `duration` | int | Duration in seconds (0=permanent) |
| `invokername` | string | Name of who created the ban |
| `invokercldbid` | int | Database ID of who created the ban |
| `invokeruid` | string | UID of who created the ban |
| `reason` | string | Ban reason |
| `enforcements` | int | Number of times this ban was enforced |

---

### `banadd`
Add a ban rule. At least one of `ip`, `name`, `uid`, or `mytsid` must be specified.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `ip` | string | one of | IP regex to ban |
| `name` | string | one of | Nickname regex to ban |
| `uid` | string | one of | UID to ban |
| `mytsid` | string | one of | MyTS ID to ban (or `empty` to match clients without one) |
| `time` | int | no | Ban duration in seconds (0=permanent) |
| `banreason` | string | no | Reason text |
| `lastnickname` | string | no | Last known nickname (informational) |

**Response:**
| Field | Type | Description |
|---|---|---|
| `banid` | int | Created ban rule ID |

---

### `banclient`
Ban client(s) by session ID. Creates up to 3 ban rules per client (IP + UID + mytsid).

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `clid` | int | yes | Session client ID (repeatable with `\|`) |
| `time` | int | no | Duration in seconds (0=permanent) |
| `banreason` | string | no | Reason text |
| `-continueonerror` | flag | no | Skip errors and continue |

**Response** *(one entry per ban rule created)*:
| Field | Type | Description |
|---|---|---|
| `banid` | int | Created ban rule ID |

---

### `bandel`
Delete a ban rule.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `banid` | int | yes | Ban rule ID |

**Response:** none

---

### `bandelall`
Delete all ban rules.

**Response:** none

---

## Privilege Keys (Tokens)

### `privilegekeylist`
List all privilege keys. Returns `error id=1281` when no keys exist.

**Response** *(entries separated by `|`)*:
| Field | Type | Description |
|---|---|---|
| `token` | string | Token string |
| `token_type` | int | `0`=server group, `1`=channel group |
| `token_id1` | int | Server group ID (type 0) or channel group ID (type 1) |
| `token_id2` | int | Channel ID (type 1 only) |
| `token_created` | unix_ts | Creation time |
| `token_description` | string | Description |

---

### `privilegekeyadd`
Create a privilege key.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `tokentype` | int | yes | `0`=server group, `1`=channel group |
| `tokenid1` | int | yes | Server group ID (type 0) or channel group ID (type 1) |
| `tokenid2` | int | yes* | Channel ID (*required when `tokentype=1`) |
| `tokendescription` | string | no | Description |
| `tokencustomset` | string | no | Custom properties: `ident=x value=y\|ident=z value=w` |

**Response:**
| Field | Type | Description |
|---|---|---|
| `token` | string | The generated privilege key |

---

### `privilegekeydelete`
Delete a privilege key.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `token` | string | yes | Token string |

**Response:** none

---

### `privilegekeyuse`
Use a privilege key (deleted after use).

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `token` | string | yes | Token string |

**Response:** none

---

## API Keys

### `apikeyadd`
Create an API key.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `scope` | string | yes | `read`, `write`, or `manage` |
| `lifetime` | int | no | Lifetime in days (0=unlimited) |
| `cldbid` | int | no | Client DB ID (admin only, defaults to self) |

**Response:**
| Field | Type | Description |
|---|---|---|
| `apikey` | string | The API key string (only returned on creation) |
| `id` | int | Key ID |
| `sid` | int | Virtual server ID (`0`=instance-wide) |
| `cldbid` | int | Owner's database ID |
| `scope` | string | `read`, `write`, or `manage` |
| `time_left` | int | Seconds until expiry |
| `created_at` | unix_ts | Creation time |
| `expires_at` | unix_ts | Expiry time |

---

### `apikeylist`
List API keys. Returns `error id=1281` when no keys exist.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `cldbid` | int | no | Filter by owner's database ID |
| `start` | int | no | Skip first N entries |
| `duration` | int | no | Return at most N entries |
| `-count` | flag | no | Also return `count` (total entries) |

**Response** *(entries separated by `|`)*:
| Field | Type | Description |
|---|---|---|
| `id` | int | Key ID |
| `sid` | int | Virtual server ID (`0`=instance-wide) |
| `cldbid` | int | Owner's database ID |
| `scope` | string | `read`, `write`, or `manage` |
| `time_left` | int | Seconds until expiry |
| `created_at` | unix_ts | Creation time |
| `expires_at` | unix_ts | Expiry time |

---

### `apikeydel`
Delete an API key.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `id` | int | yes | API key ID |

**Response:** none

---

## Query Logins

### `queryloginadd`
Create a query login.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `client_login_name` | string | yes | Desired login name |
| `cldbid` | int | no | Client DB ID (required when server selected; defaults to self) |

**Response:**
| Field | Type | Description |
|---|---|---|
| `cldbid` | int | Client database ID |
| `sid` | int | Virtual server ID |
| `client_login_name` | string | Login name |
| `client_login_password` | string | Generated password |

---

### `querylogindel`
Delete a query login.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `cldbid` | int | yes | Client database ID |

**Response:** none

---

### `queryloginlist`
List query logins. Returns `error id=1281` when no logins exist.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `pattern` | string | no | SQL-style filter pattern |
| `start` | int | no | Skip first N entries |
| `duration` | int | no | Return at most N entries |
| `-count` | flag | no | Also return `count` (total entries) |

**Response** *(entries separated by `|`)*:
| Field | Type | Description |
|---|---|---|
| `cldbid` | int | Client database ID |
| `sid` | int | Virtual server ID |
| `client_login_name` | string | Login name |

---

## Logging

### `logview`
View server log entries.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `lines` | int | no | Number of lines to return |
| `reverse` | bool | no | `1`=newest first |
| `instance` | bool | no | `1`=instance log, `0`=virtual server log |
| `begin_pos` | int | no | Start reading from this byte offset |

**Response:**
| Field | Type | Description |
|---|---|---|
| `last_pos` | int | Byte position after last returned line |
| `file_size` | int | Total log file size (bytes) |
| `l` | string | Log line (ServerQuery-encoded; format: `YYYY-MM-DD HH:MM:SS.ffffff\pLEVEL\p...`) |

---

### `logadd`
Write a custom entry to the server log.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `loglevel` | int | yes | `1`=error, `2`=warning, `3`=debug, `4`=info |
| `logmsg` | string | yes | Log message text |

**Response:** none

---

## Complaints

### `complainlist`
List complaints on the virtual server.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `tcldbid` | int | no | Filter by target client database ID |

**Response** *(entries separated by `|`)*:
| Field | Type | Description |
|---|---|---|
| `tcldbid` | int | Target client database ID |
| `tname` | string | Target client nickname |
| `fcldbid` | int | Complaining client database ID |
| `fname` | string | Complaining client nickname |
| `message` | string | Complaint message |
| `timestamp` | unix_ts | Time of complaint |

---

### `complainadd`
Submit a complaint about a client.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `tcldbid` | int | yes | Target client database ID |
| `message` | string | yes | Complaint text |

**Response:** none

---

### `complaindel`
Delete a specific complaint.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `tcldbid` | int | yes | Target client database ID |
| `fcldbid` | int | yes | Complaining client database ID |

**Response:** none

---

### `complaindelall`
Delete all complaints about a client.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `tcldbid` | int | yes | Target client database ID |

**Response:** none

---

## Custom Properties

### `custominfo`
Display custom properties for a client.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `cldbid` | int | yes | Client database ID |

**Response** *(entries separated by `|`)*:
| Field | Type | Description |
|---|---|---|
| `cldbid` | int | Client database ID |
| `ident` | string | Property identifier |
| `value` | string | Property value |

---

### `customsearch`
Search for clients by custom property value.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `ident` | string | yes | Property identifier to search |
| `pattern` | string | yes | SQL-style pattern (supports `%` wildcard) |

**Response** *(entries separated by `|`)*:
| Field | Type | Description |
|---|---|---|
| `cldbid` | int | Client database ID |
| `ident` | string | Property identifier |
| `value` | string | Matched value |

---

## Offline Messages

### `messagelist`
List offline messages.

**Response** *(entries separated by `|`)*:
| Field | Type | Description |
|---|---|---|
| `msgid` | int | Message ID |
| `cluid` | string | Sender UID |
| `subject` | string | Subject line |
| `timestamp` | unix_ts | Send time |
| `flag_read` | bool | Whether read |

---

### `messageadd`
Send an offline message.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `cluid` | string | yes | Recipient UID |
| `subject` | string | yes | Subject line |
| `message` | string | yes | Message text |

**Response:** none

---

### `messagedel`
Delete an offline message.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `msgid` | int | yes | Message ID |

**Response:** none

---

### `messageget`
Retrieve an offline message.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `msgid` | int | yes | Message ID |

**Response:**
| Field | Type | Description |
|---|---|---|
| `msgid` | int | Message ID |
| `cluid` | string | Sender UID |
| `subject` | string | Subject line |
| `message` | string | Message text |
| `timestamp` | unix_ts | Send time |
| `flag_read` | bool | Whether read |

---

### `messageupdateflag`
Mark a message as read or unread.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `msgid` | int | yes | Message ID |
| `flag` | bool | yes | `1`=read, `0`=unread |

**Response:** none

---

## File Transfer

File transfer uses a separate TCP connection on port 30033 (configurable via `serverinstance_filetransfer_port`). The flow is: call [`ftinitupload`](#ftinitupload) or [`ftinitdownload`](#ftinitdownload) to get an `ftkey` and `port`, then connect to that port and transfer raw data. Responses marked with `ip` indicate the filetransfer subsystem is not reachable via the current query connection IP.

> **Note:** Response fields for file transfer commands are derived from server help text and example output — they have not been captured from a live transfer session.

---

### `ftinitupload`
Initialize a file upload. Returns a transfer key and port to connect to for the actual data transfer.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `clientftfid` | int | yes | Arbitrary client-side transfer ID |
| `name` | string | yes | File path (ServerQuery-encoded, e.g. `\/image.iso`) |
| `cid` | int | yes | Channel ID |
| `cpw` | string | yes | Channel password (empty string if none) |
| `size` | int | yes | File size in bytes |
| `overwrite` | bool | yes | `1` = overwrite existing file |
| `resume` | bool | yes | `1` = resume interrupted upload |
| `proto` | int | no | Protocol version: `0` or `1` (default `0`) |

**Response:**
| Field | Type | Description |
|---|---|---|
| `clientftfid` | int | Client-side transfer ID (echoed back) |
| `serverftfid` | int | Server-side transfer ID |
| `ftkey` | string | Transfer key required to authenticate the data connection |
| `port` | int | TCP port to connect to for data transfer |
| `seekpos` | int | Byte offset to start writing from (for resume) |
| `proto` | int | Protocol version the server will use |
| `ip` | string | Transfer IP (only present if different from query connection IP) |

---

### `ftinitdownload`
Initialize a file download. Returns a transfer key and port to connect to for the actual data transfer.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `clientftfid` | int | yes | Arbitrary client-side transfer ID |
| `name` | string | yes | File path (ServerQuery-encoded, e.g. `\/image.iso`) |
| `cid` | int | yes | Channel ID |
| `cpw` | string | yes | Channel password (empty string if none) |
| `seekpos` | int | yes | Byte offset to start reading from (`0` for full download) |
| `proto` | int | no | Protocol version: `0` or `1` (default `0`) |

**Response:**
| Field | Type | Description |
|---|---|---|
| `clientftfid` | int | Client-side transfer ID (echoed back) |
| `serverftfid` | int | Server-side transfer ID |
| `ftkey` | string | Transfer key required to authenticate the data connection |
| `port` | int | TCP port to connect to for data transfer |
| `size` | int | Total file size in bytes |
| `proto` | int | Protocol version the server will use |
| `ip` | string | Transfer IP (only present if different from query connection IP) |

---

### `ftlist`
List all running file transfers on the virtual server.

**Response** *(entries separated by `|`)*:
| Field | Type | Description |
|---|---|---|
| `clid` | int | Client ID initiating the transfer |
| `path` | string | Server-side destination path |
| `name` | string | File name |
| `size` | int | Total file size in bytes |
| `sizedone` | int | Bytes transferred so far |
| `clientftfid` | int | Client-side transfer ID |
| `serverftfid` | int | Server-side transfer ID |
| `sender` | bool | `1` = upload (client sending), `0` = download (client receiving) |
| `status` | int | Transfer status |
| `current_speed` | float | Current transfer rate (bytes/s) |

---

### `ftgetfilelist`
List files and directories in a channel's file repository.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `cid` | int | yes | Channel ID |
| `cpw` | string | yes | Channel password (empty string if none) |
| `path` | string | yes | Directory path (e.g. `\/`) |

**Response** *(entries separated by `|`)*:
| Field | Type | Description |
|---|---|---|
| `cid` | int | Channel ID |
| `path` | string | Directory path |
| `name` | string | File or directory name |
| `size` | int | File size in bytes (`0` for directories) |
| `datetime` | unix_ts | Last modified time |
| `type` | int | `0`=directory, `1`=file |

---

### `ftgetfileinfo`
Get detailed info about one or more files. Multiple files can be queried by piping entries: `cid=2 cpw= name=\/a.png|cid=2 cpw= name=\/b.png`.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `cid` | int | yes | Channel ID |
| `cpw` | string | yes | Channel password (empty string if none) |
| `name` | string | yes | File path |

**Response** *(entries separated by `|`)*:
| Field | Type | Description |
|---|---|---|
| `cid` | int | Channel ID |
| `path` | string | Directory path |
| `name` | string | File or directory name |
| `size` | int | File size in bytes (`0` for directories) |
| `datetime` | unix_ts | Last modified time |
| `type` | int | `0`=directory, `1`=file |

---

### `ftstop`
Stop a running file transfer.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `serverftfid` | int | yes | Server-side transfer ID |
| `delete` | bool | yes | `1` = delete the incomplete file |

**Response:** none

---

### `ftdeletefile`
Delete one or more files from a channel's file repository. Multiple files can be deleted by piping: `name=\/a.png|name=\/b.png`.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `cid` | int | yes | Channel ID |
| `cpw` | string | yes | Channel password (empty string if none) |
| `name` | string | yes | File path |

**Response:** none

---

### `ftcreatedir`
Create a directory in a channel's file repository.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `cid` | int | yes | Channel ID |
| `cpw` | string | yes | Channel password (empty string if none) |
| `dirname` | string | yes | Directory path to create (ServerQuery-encoded, e.g. `\/My\sDirectory`) |

**Response:** none

---

### `ftrenamefile`
Rename or move a file within or between channel file repositories.

**Parameters:**
| Name | Type | Required | Description |
|---|---|---|---|
| `cid` | int | yes | Source channel ID |
| `cpw` | string | yes | Source channel password (empty string if none) |
| `oldname` | string | yes | Current file path |
| `newname` | string | yes | New file path |
| `tcid` | int | no | Target channel ID (if moving to another channel) |
| `tcpw` | string | no | Target channel password |

**Response:** none

---

## Event Notifications (Push)

Use [`servernotifyregister`](#servernotifyregister) / [`servernotifyunregister`](#servernotifyunregister) to subscribe and unsubscribe. After registering, the server pushes notification lines starting with `notify`. They use the same `key=value` format as regular responses. Fields share names with the corresponding list/info commands; partial-population rules apply (only changed/relevant fields are sent).

---

### `notifycliententerview`

Fired when a client enters the bot's visible view (connects or moves into a subscribed channel).

| Field | Type | Description |
|---|---|---|
| `cfid` | int | Source channel ID; 0 if the client just connected |
| `ctid` | int | Target channel ID the client entered |
| `reasonid` | int | 0 = connected or self-moved |
| `clid` | int | Session client ID (part of ClientInfo) |
| `client_*` | — | All client fields (same as [`clientlist`](#clientlist) with all flags) |
| `client_unread_messages` | int | Unread messages (only in this notification, not in clientinfo/clientlist) |

---

### `notifyclientleftview`

Fired when a client leaves the bot's visible view (disconnects, kicked, banned, or moves out).

| Field | Type | Description |
|---|---|---|
| `cfid` | int | Channel the client left |
| `ctid` | int | Destination channel; 0 if disconnected |
| `reasonid` | int | 1=kicked from channel, 4=kicked, 5=client kicked, 6=banned, 8=disconnected |
| `clid` | int | Client ID of the departing client |
| `reasonmsg` | string | Reason message provided by invoker or client |
| `invokerid` | int | Present on kick/ban |
| `invokername` | string | Present on kick/ban |
| `invokeruid` | string | Present on kick/ban |
| `bantime` | int | Ban duration in seconds; 0 = permanent (only on reasonid=6) |

---

### `notifyclientmoved`

Fired when a client moves to a different channel.

| Field | Type | Description |
|---|---|---|
| `ctid` | int | Target channel ID |
| `reasonid` | int | 0 = self-moved, 1 = moved by another client |
| `clid` | int | Client ID of the client that was moved |
| `invokerid` | int | Present when reasonid=1 |
| `invokername` | string | Present when reasonid=1 |
| `invokeruid` | string | Present when reasonid=1 |

---

### `notifytextmessage`

Fired when a text message is received in a registered scope.

| Field | Type | Description |
|---|---|---|
| `targetmode` | int | 1 = private message, 2 = channel message, 3 = server message |
| `msg` | string | Message content |
| `target` | int | Recipient client ID (private messages only) |
| `invokerid` | int | Sender's client ID |
| `invokername` | string | Sender's nickname |
| `invokeruid` | string | Sender's UID |

---

### `notifychanneledited`

Fired when channel properties are changed. Only the modified fields are included.

| Field | Type | Description |
|---|---|---|
| `cid` | int | Channel ID |
| `reasonid` | int | 10 = edited by client or query |
| `invokerid` | int | Invoker client ID |
| `invokername` | string | Invoker nickname |
| `invokeruid` | string | Invoker UID |
| `channel_*` | — | Only the changed channel properties |

> **Note:** A separate undocumented event `notifychanneldescriptionchanged cid=N` fires when only the description changes.

---

### `notifychannelcreated`

Fired when a new channel is created.

| Field | Type | Description |
|---|---|---|
| `cid` | int | New channel ID |
| `cpid` | int | Parent channel ID; 0 for top-level |
| `invokerid` | int | Creator's client ID |
| `invokername` | string | Creator's nickname |
| `invokeruid` | string | Creator's UID |
| `channel_*` | — | Properties set at creation time |

---

### `notifychanneldeleted`

Fired when a channel is deleted.

| Field | Type | Description |
|---|---|---|
| `cid` | int | ID of the deleted channel |
| `invokerid` | int | Deleter's client ID |
| `invokername` | string | Deleter's nickname |
| `invokeruid` | string | Deleter's UID |

---

### `notifychannelmoved`

Fired when a channel is moved to a different parent channel.

| Field | Type | Description |
|---|---|---|
| `cid` | int | Channel ID |
| `cpid` | int | New parent channel ID |
| `order` | int | New sort order among siblings |
| `reasonid` | int | 1 = moved by client or query |
| `invokerid` | int | Invoker's client ID |
| `invokername` | string | Invoker's nickname |
| `invokeruid` | string | Invoker's UID |

> **Note:** Not fired on simple reorder within the same parent (drag-and-drop to change position only). Use [`notifychanneledited`](#notifychanneledited) with `channel_order` for that case.

---

### `notifyserveredited`

Fired when virtual server properties are changed.

| Field | Type | Description |
|---|---|---|
| `reasonid` | int | 10 = edited by client or query |
| `invokerid` | int | Invoker's client ID |
| `invokername` | string | Invoker's nickname |
| `invokeruid` | string | Invoker's UID |
| `virtualserver_*` | — | Only the changed server properties |

---

### `notifytokenused`

Fired when a client uses a privilege key.

| Field | Type | Description |
|---|---|---|
| `clid` | int | Client ID of the user |
| `cldbid` | int | Database ID of the user |
| `cluid` | string | UID of the user |
| `token` | string | The privilege key string that was used |
| `tokencustomset` | string | Custom data string associated with the token |
| `token1` | string | Server group ID or channel group ID granted |
| `token2` | string | Channel ID for channel group tokens; 0 for server group tokens |

---

## Deprecated Aliases

`tokenadd`, `tokendelete`, `tokenlist`, `tokenuse` are deprecated aliases for [`privilegekeyadd`](#privilegekeyadd), [`privilegekeydelete`](#privilegekeydelete), [`privilegekeylist`](#privilegekeylist), [`privilegekeyuse`](#privilegekeyuse).