## List commands

`GET /v1/bots/:botId/commands`

Returns the commands registered for the bot together with the system commands of the Bitrix24 account.

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|---------|
| `botId` (path) | number | yes | Bot ID. List: [`GET /v1/bots`](/docs/bots/management/list) |

## Examples

### curl — personal key

```bash
curl https://vibecode.bitrix24.com/v1/bots/42/commands \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl https://vibecode.bitrix24.com/v1/bots/42/commands \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/bots/42/commands', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log('Commands:', data.commands)
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/bots/42/commands', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()
```

## Response fields

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data` | object | Request result |
| `data.commands` | array | The bot's commands and the system commands of the Bitrix24 account |
| `data.commands[].id` | number \| string | Command ID. A number for a bot command, a string such as `def0` for a system command of the Bitrix24 account |
| `data.commands[].botId` | number | ID of the bot that owns the command. `0` for a system command of the Bitrix24 account |
| `data.commands[].command` | string | Command text, starts with `/`, for example `/help` |
| `data.commands[].category` | string | Name of the command group in the command list. For a bot command, the bot name |
| `data.commands[].common` | string | `Y` — the command is available in all chats, `N` — only in a private chat with the bot and in chats with the bot |
| `data.commands[].context` | string | Command context. An empty string if not set |
| `data.commands[].title` | string | Command description in the Bitrix24 account language |
| `data.commands[].params` | string | Hint for the command parameters in the Bitrix24 account language. An empty string if not set |
| `data.commands[].extranet` | string | `Y` — the command is available to extranet users, `N` — it is not |

## Response example

Two of the six system commands of the Bitrix24 account and one bot command are shown:

```json
{
  "success": true,
  "data": {
    "commands": [
      {
        "id": "def0",
        "botId": 0,
        "command": "/me",
        "category": "Chat and calls",
        "common": "Y",
        "context": "",
        "title": "Text will be shown in italics",
        "params": "text",
        "extranet": "Y"
      },
      {
        "id": "def3",
        "botId": 0,
        "command": "/rename",
        "category": "Chats",
        "common": "Y",
        "context": "chat",
        "title": "Change the chat title",
        "params": "new title",
        "extranet": "Y"
      },
      {
        "id": 229,
        "botId": 42,
        "command": "/help",
        "category": "Support",
        "common": "Y",
        "context": "",
        "title": "Help",
        "params": "topic",
        "extranet": "N"
      }
    ]
  }
}
```

## Error response example

404 — bot not found:

```json
{
  "success": false,
  "error": {
    "code": "BOT_NOT_FOUND",
    "message": "Bot 999 not found. Register it first via POST /v1/bots."
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `INVALID_BOT_ID` | `botId` is not a number |
| 404 | `BOT_NOT_FOUND` | No bot found with this ID |
| 403 | `BOT_ACCESS_DENIED` | The bot belongs to a different API key |
| 403 | `SCOPE_DENIED` | API key lacks the `imbot` scope |
| 410 | `BOT_DISABLED` | The bot is disabled and does not process API calls. How to restore it — [Bot disabled](/docs/bots/troubleshooting#bot-disabled-bot_disabled) |
| 401 | `TOKEN_MISSING` | API key has no configured tokens |

Full list of common API errors — [Errors](/docs/errors).

## Known specifics

**Pick the bot's commands out of the shared list.** The system commands of the Bitrix24 account come in every response, and their `botId` is `0`. To get only your bot's commands, filter `data.commands` to the items whose `botId` matches the bot ID.

**The list may lag behind changes.** Vibecode does not cache this response, but Bitrix24 updates the command list with a delay after a command is registered, updated or deleted: from several seconds to several minutes. During this time, `GET` may return:

- deleted commands — their IDs are still visible in the list.
- stale `title`, `params` and `common` values for a command that was just updated.
- a list without a command that was just registered.

The command itself is already active at that point: its call arrives as an `ONIMBOTV2COMMANDADD` event, and the bot handles it. The discrepancy is visible only in this `GET`. The list cache cannot be force-reset.

**How to work with the delay.** Right after a change, rely on the response of the change request itself: `POST` returns the data with the new ID, `PATCH` returns the updated command, `DELETE` returns a success flag. If you need to reconcile the list with the actual state, repeat `GET` after 10–30 seconds.

## See also

- [Register a command](/docs/bots/commands/register)
- [Update a command](/docs/bots/commands/update)
- [Bot platform](/docs/bots)
- [Limits and optimization](/docs/optimization)