## List commands

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

Returns all registered commands of the bot.

## ⚠️ Possible delay after mutations

Vibecode does not cache this response. However, Bitrix24 itself **keeps its own cache** of the command list and does not always refresh it immediately after registering, updating or deleting a command. For several seconds (sometimes minutes) after a successful mutation, `GET` may return:

- deleted commands (their ids are still visible in the list)
- stale `title` / `params` / `common` / `hidden` values for a just-updated command
- the absence of a just-registered command.

Meanwhile the command itself is already **active** on the Bitrix24 side (the `ONIMBOTV2COMMANDADD` event fires for it, the bot handles it) — the discrepancy is visible only in this `GET`.

### What to do

- **Do not use `GET /commands` as the single source of truth right after a mutation.** Rely on the mutation's own response: `POST` returns the data with the new id, `PATCH` — the updated command, `DELETE` — a success flag.
- **If you need to sync with the list** (for example, to reconcile the interface with the real state), request `GET` again after 10–30 seconds.
- **If the discrepancy persists for more than a minute**, this is no longer a normal delay. Attach `botId`, the mutation time, and exactly what was expected versus what was received to your support request.

This cache cannot be force-flushed on the Bitrix24 side. If the list has not updated — repeat the `GET` after a few seconds.

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|---------|
| `botId` (path) | number | yes | Bot ID |

## 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)
```

### 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 |
|------|-----|---------|
| `data` | array | Array of commands |
| `data[].id` | number | Command ID |
| `data[].command` | string | Command text |
| `data[].title` | string | Title (localized) |
| `data[].params` | string | Parameters description (localized) |
| `data[].common` | boolean | Available in all chats |
| `data[].hidden` | boolean | Hidden from the list |
| `data[].extranetSupport` | boolean | Available to extranet users |

## Response example

```json
{
  "success": true,
  "data": [
    {
      "id": 7,
      "command": "help",
      "title": "Help",
      "params": "topic",
      "common": true,
      "hidden": false,
      "extranetSupport": false
    },
    {
      "id": 8,
      "command": "status",
      "title": "Status",
      "params": "",
      "common": false,
      "hidden": false,
      "extranetSupport": false
    }
  ]
}
```

## 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 |
| 401 | `TOKEN_MISSING` | API key has no configured tokens |

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

## 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)