## List bots

`GET /v1/bots`

Returns the list of bots registered by the current API key in the Bitrix24 account.

The request **does not go** to Bitrix24 — it returns rows from the Vibecode DB filtered by your API key. Automatically disabled bots (`PORTAL_DELETED` / `AUTH_FAILURES`) do not appear in the list — to see them, switch the status manually via `PATCH /v1/bots/:botId { disabled: false }`.

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|---------|
| `limit` | number | no | Maximum number of bots in the response. Default 50, maximum 200 |
| `offset` | number | no | Offset for pagination. Default 0 |
| `type` | string | no | Filter by bot type: `bot`, `personal`, `supervisor`, `openline` |

## Examples

### curl — personal key

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

### curl — OAuth application

```bash
curl https://vibecode.bitrix24.com/v1/bots \
  -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', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
console.log('My bots:', data.bots)
```

### JavaScript — OAuth application

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

## Response fields

| Field | Type | Description |
|------|-----|---------|
| `bots` | array | Array of bot objects |
| `bots[].id` | number | Bot ID in the Bitrix24 account |
| `bots[].code` | string | Unique bot code |
| `bots[].name` | string | Bot display name in chat |
| `bots[].type` | string | Type: `bot`, `personal`, `supervisor`, `openline` |
| `bots[].eventMode` | string | Event mode: `fetch` or `webhook` |
| `users` | array | Always an empty array. Kept for backward compatibility — to get Bitrix24 users, use `GET /v1/users` |
| `hasNextPage` | boolean | `true` if there are more records beyond the current page — increase `offset` |

## Response example

```json
{
  "success": true,
  "data": {
    "bots": [
      {
        "id": 42,
        "code": "support_bot",
        "name": "Support",
        "type": "bot",
        "eventMode": "fetch"
      },
      {
        "id": 58,
        "code": "analytics_bot",
        "name": "Analyst",
        "type": "openline",
        "eventMode": "webhook"
      }
    ],
    "users": [],
    "hasNextPage": false
  }
}
```

## Error response example

403 — no `imbot` scope:

```json
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'imbot' scope"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 403 | `SCOPE_DENIED` | The API key does not have the `imbot` scope |

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

## See also

- [Get a bot](/docs/bots/management)
- [Register a bot](/docs/bots/management)
- [Bot platform](/docs/bots)
- [Limits and optimization](/docs/optimization)