## Список ботов

`GET /v1/bots`

Возвращает список ботов, зарегистрированных текущим API-ключом на портале.

Запрос **не идёт** в Битрикс24 — возвращаются записи из базы Вайбкод, отфильтрованные по вашему API-ключу. Автоматически отключённые боты (`PORTAL_DELETED` / `AUTH_FAILURES`) в список не попадают — чтобы увидеть их, переключите статус вручную через `PATCH /v1/bots/:botId { disabled: false }`.

Из-за фильтрации по ключу бот, зарегистрированный другим ключом того же портала, в списке не появится, хотя его `code` остаётся занятым и повторная регистрация вернёт `409 BOT_ALREADY_EXISTS`. Как вернуть управление таким ботом — [Восстановление доступа к боту](/docs/bots/ownership-recovery).

## Параметры

| Параметр | Тип | Обяз. | Описание |
|----------|-----|:-----:|---------|
| `limit` | number | нет | Максимальное количество ботов в ответе. По умолчанию 50, максимум 200 |
| `offset` | number | нет | Смещение для пагинации. По умолчанию 0 |
| `type` | string | нет | Фильтр по типу бота: `bot`, `personal`, `supervisor`, `openline` |

## Примеры

### curl — личный ключ

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

### curl — OAuth-приложение

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

### JavaScript — личный ключ

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/bots', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
console.log('Мои боты:', data.bots)
```

### JavaScript — OAuth-приложение

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

## Поля ответа

| Поле | Тип | Описание |
|------|-----|---------|
| `bots` | array | Массив объектов ботов |
| `bots[].id` | number | ID бота на Битрикс24-портале |
| `bots[].code` | string | Уникальный код бота |
| `bots[].name` | string | Отображаемое имя бота в чате |
| `bots[].type` | string | Тип: `bot`, `personal`, `supervisor`, `openline` |
| `bots[].eventMode` | string | Режим событий: `fetch` или `webhook` |
| `users` | array | Всегда пустой массив. Сохранён для обратной совместимости — чтобы получить пользователей Битрикс24, используйте `GET /v1/users` |
| `hasNextPage` | boolean | `true`, если ещё есть записи за пределами текущей страницы — увеличьте `offset` |

## Пример ответа

```json
{
  "success": true,
  "data": {
    "bots": [
      {
        "id": 42,
        "code": "support_bot",
        "name": "Техподдержка",
        "type": "bot",
        "eventMode": "fetch"
      },
      {
        "id": 58,
        "code": "analytics_bot",
        "name": "Аналитик",
        "type": "openline",
        "eventMode": "webhook"
      }
    ],
    "users": [],
    "hasNextPage": false
  }
}
```

## Пример ответа при ошибке

403 — нет скоупа `imbot`:

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

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `imbot` |

Полный список общих ошибок API — [Ошибки](/docs/errors).

## Смотрите также

- [Получить бота](/docs/bots/management/get)
- [Зарегистрировать бота](/docs/bots/management/create)
- [Восстановление доступа к боту](/docs/bots/ownership-recovery)
- [Бот-платформа](/docs/bots)
- [Лимиты и оптимизация](/docs/optimization)