## Поиск сайтов
`POST /v1/sites/search`
Поиск сайтов с фильтрацией и авто-пагинацией. Аналогичен `GET /v1/sites` с фильтрами, но через POST — удобнее для сложных запросов с большим количеством условий.
## Поля запроса (body)
| Параметр | Тип | По умолч. | Описание |
|----------|-----|-----------|---------|
| `filter` | object | — | Фильтрация по ключевым полям сайта.
[Синтаксис фильтрации](/docs/filtering) |
| `limit` | number | `50` | Количество записей (до 5000) |
| `offset` | number | `0` | Пропустить N записей. Вместе с фильтром по диапазону дат шире 14 дней отклоняется — см. `UNSTABLE_OFFSET_PAGINATION` в разделе «Ошибки» |
| `select` | string[] | — | Выборка полей: `["id", "title", "type"]` |
| `autoWindow` | boolean | `true` | Разбивать выборку по недельным окнам при фильтре по диапазону дат шире 14 дней. `false` отключает разбиение |
| `scope` | string | — | Внутренняя область лендингов: `KNOWLEDGE` / `GROUP` / `MAINPAGE`. Без параметра возвращаются обычные сайты-лендинги. Принимается на верхнем уровне тела (`"scope": "KNOWLEDGE"`) или внутри `filter.scope` — обе формы дают одинаковый запрос к Битрикс24 |
> **Фильтр по типу и область (`scope`).** Битрикс24 привязывает `filter.type` к текущей области — в области по умолчанию доступны только `PAGE` / `STORE` / `SMN` / `VIBE`. Если фильтруете `{"filter": {"type": "KNOWLEDGE"}}` или `"GROUP"` и **не** передали `scope`, Вайбкод сам подставит соответствующую область (`type=KNOWLEDGE` → `scope=KNOWLEDGE`), и поиск вернёт именно базы знаний / страницы групп. Явный `scope` в приоритете. Если тип задан списком/оператором (`{"type": {"$in": ["KNOWLEDGE", "PAGE"]}}`), где одну область выбрать нельзя, в `meta.warnings` придёт подсказка с кодом `TYPE_REQUIRES_SCOPE`. `MAINPAGE` — область, а не тип сайта (её сайты имеют тип `VIBE`), поэтому из фильтра не выводится.
## Примеры
### curl — личный ключ
```bash
curl -X POST "https://vibecode.bitrix24.tech/v1/sites/search" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"filter": { "type": "PAGE", "active": true },
"limit": 10,
"select": ["id", "title", "type", "active"]
}'
```
### curl — OAuth-приложение
```bash
curl -X POST "https://vibecode.bitrix24.tech/v1/sites/search" \
-H "X-Api-Key: YOUR_APP_KEY" \
-H "Authorization: Bearer USER_SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"filter": { "type": "PAGE", "active": true },
"limit": 10,
"select": ["id", "title", "type", "active"]
}'
```
### JavaScript — личный ключ
```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/sites/search', {
method: 'POST',
headers: {
'X-Api-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
filter: { type: 'PAGE', active: true },
limit: 10,
select: ['id', 'title', 'type', 'active'],
}),
})
const { success, data, meta } = await res.json()
console.log('Найдено:', meta.total)
```
### JavaScript — OAuth-приложение
```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/sites/search', {
method: 'POST',
headers: {
'X-Api-Key': 'YOUR_APP_KEY',
'Authorization': 'Bearer USER_SESSION_TOKEN',
'Content-Type': 'application/json',
},
body: JSON.stringify({
filter: { type: 'PAGE', active: true },
limit: 10,
select: ['id', 'title', 'type', 'active'],
}),
})
const { success, data, meta } = await res.json()
```
## Поля ответа
| Поле | Тип | Описание |
|------|-----|---------|
| `data` | array | Массив сайтов с ключевыми полями |
| `meta.total` | number | Сколько записей подошло под фильтр |
| `meta.hasMore` | boolean | Есть ли ещё записи за пределами `limit` |
| `meta.durationMs` | number | Длительность запроса в миллисекундах |
| `meta.autoWindowed` | boolean | `true`, если выборка была разбита по временны́м окнам |
| `meta.windowCount` | number | Число окон. Приходит при `autoWindowed: true` |
| `meta.batchWaves` | number | Число волн параллельных запросов. Приходит при `autoWindowed: true` |
Поля `meta` лежат рядом с `data`, а не внутри него. Обходить страницы нужно по `meta.hasMore`: длина `data`, равная `limit`, последней страницы не исключает.
URL любого сайта из массива `data` — его `id`:
```
https://.bitrix24.ru/sites/site//
```
`` — домен портала. Доступ ограничен правами сотрудника в Битрикс24.
## Пример ответа
```json
{
"success": true,
"data": [
{
"id": 157,
"title": "Промо-лендинг",
"code": "/promo/",
"type": "PAGE",
"active": true,
"domainId": 5,
"createdById": 1,
"dateCreate": "12.09.2024 10:23:14",
"dateModify": "04.11.2025 08:51:20"
}
],
"meta": {
"total": 10,
"hasMore": false,
"durationMs": 99
}
}
```
С фильтром по диапазону дат шире 14 дней в `meta` дополнительно приходят `autoWindowed`, `windowCount` и `batchWaves`:
```json
{
"success": true,
"data": [ /* ... */ ],
"meta": {
"total": 2,
"hasMore": false,
"autoWindowed": true,
"windowCount": 339,
"batchWaves": 4,
"durationMs": 3136
}
}
```
## Пример ответа при ошибке
403 — нет скоупа:
```json
{
"success": false,
"error": {
"code": "SCOPE_DENIED",
"message": "This endpoint requires 'landing' scope"
}
}
```
## Ошибки
| HTTP | Код | Описание |
|------|-----|---------|
| 400 | `UNSTABLE_OFFSET_PAGINATION` | `offset` больше нуля вместе с фильтром по диапазону дат шире 14 дней. Два разных алгоритма выдачи дают несогласованные результаты, поэтому запрос отклоняется. Возьмите всё одним запросом с `limit` до 5000, либо передайте `autoWindow: false` с сортировкой по `id`, либо режьте диапазон дат на части сами |
| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `landing` |
| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |
Полный список общих ошибок API — [Ошибки](/docs/errors).
## Известные особенности
**Разбиение по временны́м окнам.** Фильтр по диапазону дат шире 14 дней автоматически разбивается на недельные окна, которые выполняются параллельными волнами — так выборка обходит потолок в 5000 записей на один вызов. В `meta` тогда приходят `autoWindowed: true`, число окон `windowCount` и число волн `batchWaves`. Отключает разбиение параметр `autoWindow: false`. При активном разбиении `offset` больше нуля отклоняется с `UNSTABLE_OFFSET_PAGINATION`.
**Видимость по правам пользователя.** Поиск возвращает только те сайты, к которым у владельца API-ключа есть право «просмотр». Если ожидается результат, но `data` пустой — проверьте права пользователя.
**Удалённые сайты.** По умолчанию исключаются. Чтобы включить их в результат, передайте `{"filter": {"deleted": "Y"}}`. Значения — `Y` или `N`.
**Постраничный переход через `offset` поддерживается.** Вайбкод возвращает запрошенное окно `[offset, offset + limit)`. Значение `meta.total` — точное число записей под фильтром, а `meta.hasMore` показывает, есть ли записи за пределами окна.
**Сортировка.** Поле `sort` в теле: `{"sort": "-id"}` — по убыванию, `{"sort": "id"}` — по возрастанию (принимается и алиас `order`). Без параметра — по возрастанию `id`.
## Смотрите также
- [Список сайтов](/docs/entities/sites/list)
- [Получить сайт](/docs/entities/sites/get)
- [Синтаксис фильтрации](/docs/filtering)
- [Batch](/docs/batch)
- [Лимиты и оптимизация](/docs/optimization)