# Custom commands API

> KickBot API and MCP reference for custom commands: list, create, update, upsert by name and delete chat commands, with every field and limit.

Source: https://kickbot.com/docs/api/reference/commands

Use these actions to manage the chat commands that reply with a set message, for example `!discord`.

Each action is a REST endpoint under `https://kickbot.com/api/v1` and an MCP tool with the same name. The MCP area name is `commands`. Use it to load only this area: `https://kickbot.com/api/v1/mcp?areas=commands`.

A team member needs the **Custom commands** permission in Manage Team. Owners and admins have every permission. Write actions also need a read and write key or connection. See [Permissions and security](https://kickbot.com/docs/api/start/permissions-and-security).

How the feature works in the dashboard: [Custom commands](https://kickbot.com/docs/chat-bot/custom-commands), [Command variables](https://kickbot.com/docs/chat-bot/command-variables).

## Actions

| Tool | REST | Access |
|---|---|---|
| [`list_commands`](#list_commands) | `GET /commands` | Read |
| [`get_command`](#get_command) | `GET /commands/{id}` | Read |
| [`create_command`](#create_command) | `POST /commands` | Write |
| [`update_command`](#update_command) | `PATCH /commands/{id}` | Write |
| [`set_command_by_name`](#set_command_by_name) | `PUT /commands/by-name/{name}` | Write |
| [`delete_command`](#delete_command) | `DELETE /commands/{id}` | Write |

## list_commands

**List custom commands.** List all chat commands: custom ones and the built-in ones (built_in = true, which can be edited and disabled but not renamed or deleted).

```http
GET /api/v1/commands
```

No input fields.

## get_command

**Get a command.** Get one command by id.

```http
GET /api/v1/commands/{id}
```

| Field | Type | Required | Description |
|---|---|---|---|
| `id` (in the path) | integer | Yes | The item id. |

## create_command

**Create a custom command.** Create a custom chat command. Needs the Kick channel connected to KickBot. Use set_command_by_name instead if the command may already exist.

```http
POST /api/v1/commands
```

Needs a read and write key or connection.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string | Yes | Trigger word without "!", for example "discord" for !discord. Up to 20 characters, no spaces. |
| `response` | string | Yes | What KickBot replies, up to 500 characters. Variables use double curly braces: {{sender.username}}, {{sender.followers}}, {{sender.followage}}, {{sender.url}}, {{streamer.username}}, {{streamer.followers}}, {{streamer.url}}, {{param}} (the word after the command), {{taggedUser.username}}, {{taggedUser.followers}}, {{taggedUser.followage}}, {{stream.title}}, {{stream.category}}, {{stream.viewers}}, {{randomRange(1,100)}}, {{randomItem("a","b","c")}}, {{request("https://api.example.com").value}} (text from a URL). |
| `mod_only` | boolean | No | Moderators can use the command. |
| `sub_only` | boolean | No | Subscribers can use the command. |
| `vip_only` | boolean | No | VIPs can use the command. |
| `everyone_only` | boolean | No | Everyone can use the command. Default true. |
| `enabled` | boolean | No | Default true. Free plans can have 5 enabled custom commands; over the limit a new command is created disabled (the response then has a `note`). |
| `user_cooldown` | integer | No | Seconds before the same viewer can use it again, 0-300. Default 0. |
| `global_cooldown` | integer | No | Seconds before anyone can use it again, 0-300. Default 0. |

## update_command

**Update a command.** Change some fields of a command. Only the fields you send change. Built-in commands keep their name.

```http
PATCH /api/v1/commands/{id}
```

Needs a read and write key or connection.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string | No | Trigger word without "!", for example "discord" for !discord. Up to 20 characters, no spaces. |
| `response` | string | No | What KickBot replies, up to 500 characters. Variables use double curly braces: {{sender.username}}, {{sender.followers}}, {{sender.followage}}, {{sender.url}}, {{streamer.username}}, {{streamer.followers}}, {{streamer.url}}, {{param}} (the word after the command), {{taggedUser.username}}, {{taggedUser.followers}}, {{taggedUser.followage}}, {{stream.title}}, {{stream.category}}, {{stream.viewers}}, {{randomRange(1,100)}}, {{randomItem("a","b","c")}}, {{request("https://api.example.com").value}} (text from a URL). |
| `mod_only` | boolean | No | Moderators can use the command. |
| `sub_only` | boolean | No | Subscribers can use the command. |
| `vip_only` | boolean | No | VIPs can use the command. |
| `everyone_only` | boolean | No | Everyone can use the command. Default true. |
| `enabled` | boolean | No | Default true. Free plans can have 5 enabled custom commands; over the limit a new command is created disabled (the response then has a `note`). |
| `user_cooldown` | integer | No | Seconds before the same viewer can use it again, 0-300. Default 0. |
| `global_cooldown` | integer | No | Seconds before anyone can use it again, 0-300. Default 0. |
| `id` (in the path) | integer | Yes | The item id. |

## set_command_by_name

**Create or update a command by name.** Idempotent setup: if a command with this name exists, update it with the fields you send; if not, create it (unset fields use the defaults). Safe to run again.

```http
PUT /api/v1/commands/by-name/{name}
```

Needs a read and write key or connection.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` (in the path) | string | Yes | Trigger word without "!", for example "discord" for !discord. Up to 20 characters, no spaces. |
| `response` | string | No | What KickBot replies, up to 500 characters. Variables use double curly braces: {{sender.username}}, {{sender.followers}}, {{sender.followage}}, {{sender.url}}, {{streamer.username}}, {{streamer.followers}}, {{streamer.url}}, {{param}} (the word after the command), {{taggedUser.username}}, {{taggedUser.followers}}, {{taggedUser.followage}}, {{stream.title}}, {{stream.category}}, {{stream.viewers}}, {{randomRange(1,100)}}, {{randomItem("a","b","c")}}, {{request("https://api.example.com").value}} (text from a URL). |
| `mod_only` | boolean | No | Moderators can use the command. |
| `sub_only` | boolean | No | Subscribers can use the command. |
| `vip_only` | boolean | No | VIPs can use the command. |
| `everyone_only` | boolean | No | Everyone can use the command. Default true. |
| `enabled` | boolean | No | Default true. Free plans can have 5 enabled custom commands; over the limit a new command is created disabled (the response then has a `note`). |
| `user_cooldown` | integer | No | Seconds before the same viewer can use it again, 0-300. Default 0. |
| `global_cooldown` | integer | No | Seconds before anyone can use it again, 0-300. Default 0. |

## delete_command

**Delete a custom command.** Delete a custom command. Built-in commands cannot be deleted; disable them with update_command.

```http
DELETE /api/v1/commands/{id}
```

Needs a read and write key or connection. This can delete or replace data, and you may not be able to undo it.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` (in the path) | integer | Yes | The item id. |