## Поиск страниц
`POST /v1/pages/search`
Возвращает список страниц по фильтру в теле запроса. По сравнению с [`GET /v1/pages`](./list.md) удобнее для сложных условий: параметры передаются в JSON, можно использовать вложенные операторы (`>=`, `<=`, `!`, `in`) в стиле MongoDB.
## Поля запроса (body)
| Поле | Тип | По умолч. | Описание |
|------|-----|-----------|---------|
| `filter` | object | — | Фильтр по ключевым полям страницы.
[Синтаксис фильтрации](/docs/filtering). Пример: `{"filter": {"siteId": 3}}` |
| `select` | string[] | — | Список полей для возврата. Без `select` ответ содержит полный набор полей страницы в camelCase (как в карточке) |
| `limit` | number | `50` | Количество записей (до 5000) |
| `offset` | number | `0` | Пропустить N записей |
| `scope` | string | — | Внутренняя область лендингов: `KNOWLEDGE` / `GROUP` / `MAINPAGE`. Без параметра возвращаются страницы обычных сайтов-лендингов. Принимается на верхнем уровне тела (`"scope": "KNOWLEDGE"`) или внутри `filter.scope` — обе формы дают одинаковый запрос к Битрикс24 |
## Примеры
### curl — личный ключ
```bash
curl -X POST "https://vibecode.bitrix24.tech/v1/pages/search" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"filter": { "siteId": 3 },
"select": ["id", "title", "code", "siteId", "active", "dateModify"],
"limit": 10
}'
```
### curl — OAuth-приложение
```bash
curl -X POST "https://vibecode.bitrix24.tech/v1/pages/search" \
-H "X-Api-Key: YOUR_APP_KEY" \
-H "Authorization: Bearer USER_SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"filter": { "siteId": 3 },
"select": ["id", "title", "code", "siteId", "active", "dateModify"],
"limit": 10
}'
```
### JavaScript — личный ключ
```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/pages/search', {
method: 'POST',
headers: {
'X-Api-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
filter: { siteId: 3 },
select: ['id', 'title', 'code', 'siteId', 'active', 'dateModify'],
limit: 10,
}),
})
const { success, data, meta } = await res.json()
console.log(`Найдено ${meta.total} страниц за ${meta.durationMs} мс`)
```
### JavaScript — OAuth-приложение
```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/pages/search', {
method: 'POST',
headers: {
'X-Api-Key': 'YOUR_APP_KEY',
'Authorization': 'Bearer USER_SESSION_TOKEN',
'Content-Type': 'application/json',
},
body: JSON.stringify({
filter: { siteId: 3 },
select: ['id', 'title', 'code', 'siteId', 'active', 'dateModify'],
limit: 10,
}),
})
const { success, data, meta } = await res.json()
```
## Поля ответа
| Поле | Тип | Описание |
|------|-----|---------|
| `success` | boolean | Всегда `true` при успехе |
| `data` | array | Массив найденных страниц |
| `data[].id` | number | Идентификатор страницы |
| `data[].title` | string | Название страницы |
| `data[].code` | string | Символьный код страницы |
| `data[].siteId` | number | Идентификатор сайта |
| `data[].active` | boolean | Активна ли страница |
| `data[].description` | string \| null | Произвольное описание |
| `data[].createdById` | number | Идентификатор создавшего сотрудника |
| `data[].dateCreate` | datetime | Дата создания. Строка в формате локали портала, не ISO 8601 |
| `data[].dateModify` | datetime | Дата последнего изменения. Тот же формат |
| `meta.total` | number | Общее количество записей, соответствующих фильтру |
| `meta.hasMore` | boolean | Есть ли ещё записи за пределами `limit` |
| `meta.durationMs` | number | Время выполнения запроса (мс) |
URL любой страницы из массива `data` строится из её `id` и `siteId`:
```
https://.bitrix24.ru/sites/site//view//
```
`` — ID сайта, которому принадлежит страница (поле `siteId` каждого элемента). `` — домен портала. Доступ ограничен правами сотрудника в Битрикс24.
## Пример ответа
```json
{
"success": true,
"data": [
{
"id": 3,
"title": "Смена названия",
"code": "promo-page",
"siteId": 3,
"active": true,
"description": null,
"createdById": 1,
"dateCreate": "22.04.2020 14:39:17",
"dateModify": "06.05.2024 15:43:27"
},
{
"id": 7,
"title": "Test page",
"code": "test",
"siteId": 3,
"active": true,
"description": null,
"createdById": 1,
"dateCreate": "25.05.2020 17:34:17",
"dateModify": "10.10.2022 15:25:30"
}
],
"meta": {
"total": 13,
"hasMore": true,
"durationMs": 171
}
}
```
## Пример ответа при ошибке
422 — несуществующее поле в фильтре:
```json
{
"success": false,
"error": {
"code": "BITRIX_ERROR",
"message": "Unknown field definition `nonsense` (nonsense) for \\Bitrix\\Landing\\Internals\\Landing Entity."
}
}
```
## Ошибки
| HTTP | Код | Описание |
|------|-----|---------|
| 422 | `BITRIX_ERROR` | Передан неизвестный филд в `filter` или иной параметр, не поддерживаемый Битрикс24 |
| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `landing` |
| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |
Полный список общих ошибок API — [Ошибки](/docs/errors).
## Известные особенности
**Когда выбирать `search`, а когда `list`.** Оба эндпоинта возвращают одинаковый набор страниц по фильтру. Используйте `POST /v1/pages/search`, когда фильтр сложнее равенства (например, `id in [3, 7, 9]`) — JSON-тело удобнее экранирует вложенные операторы. Для простых `filter[field]=value` достаточно `GET /v1/pages`.
**Формат дат в фильтре — формат локали портала, и чужой формат молча даёт пустой список.** Дату в фильтре передавайте в том же виде, в каком портал отдаёт её в ответе: **не** в ISO 8601, а в формате своей локали — `ДД.ММ.ГГГГ ЧЧ:ММ:СС` (`06.06.2026 00:00:00`) на RU-локали, `MM/DD/YYYY hh:mm:ss` (`06/06/2026 00:00:00`) на EN-локали. Значение в формате другой локали или в ISO Битрикс24 **не распознаёт и возвращает пустой список с кодом 200** — ошибки не будет, поэтому подмену легко не заметить. Единственный надёжный способ узнать формат конкретного портала — прочитать `dateModify` любой страницы (`GET /v1/pages?limit=1`) и передавать дату так же. Один и тот же формат используется в фильтре, в списке и в карточке — см. [Справочник полей](/docs/entities/pages/fields).
**`meta.durationMs`.** В отличие от list, search всегда возвращает длительность запроса в миллисекундах — полезно при отладке производительности.
**Постраничный переход через `offset` поддерживается.** Вайбкод возвращает запрошенное окно `[offset, offset + limit)`. Значение `meta.total` — точное число записей под фильтром, а `meta.hasMore` показывает, есть ли записи за пределами окна.
## Смотрите также
- [Список страниц](/docs/entities/pages/list)
- [Получить страницу](/docs/entities/pages/get)
- [Синтаксис фильтрации](/docs/filtering)
- [Лимиты и оптимизация](/docs/optimization)