For AI agents: markdown of this page — /docs-content-en/entities/pages/search.md documentation index — /llms.txt

Search pages

POST /v1/pages/search

Returns a list of pages matching a filter in the request body. Compared with GET /v1/pages, it is more convenient for complex conditions: parameters are passed in JSON, and you can use MongoDB-style nested operators (>=, <=, !, in).

Request fields (body)

Field Type Default Description
filter object — Filter by the page's key fields.
Filtering syntax. Example: {"filter": {"siteId": 3}}
select string[] — List of fields to return. Without select the response contains the full set of page fields in camelCase (as in the card)
limit number 50 Number of records (up to 5000)
offset number 0 Skip N records
scope string — Internal landing area: KNOWLEDGE / GROUP / MAINPAGE. Without the parameter, pages of regular landing sites are returned. Accepted at the top level of the body ("scope": "KNOWLEDGE") or inside filter.scope — both forms produce the same request to Bitrix24

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/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 application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/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 — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/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(`Found ${meta.total} pages in ${meta.durationMs} ms`)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/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()

Response fields

Field Type Description
success boolean Always true on success
data array Array of found pages
data[].id number Page identifier
data[].title string Page title
data[].code string Symbolic code of the page
data[].siteId number Site identifier
data[].active boolean Whether the page is active
data[].description string | null Arbitrary description
data[].createdById number Identifier of the employee who created it
data[].dateCreate datetime Creation date. A string in the account locale format, not ISO 8601
data[].dateModify datetime Last modification date. Same format
meta.total number Total number of records matching the filter
meta.hasMore boolean Whether there are more records beyond limit
meta.durationMs number Request execution time (ms)

The URL of any page from the data array is built from its id and siteId:

https://<portal>.bitrix24.com/sites/site/<siteId>/view/<id>/

<siteId> — ID of the site the page belongs to (the siteId field of each item). <portal> — the Bitrix24 portal domain. Access is restricted by the employee's permissions in Bitrix24.

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 3,
      "title": "Title change",
      "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
  }
}

Error response example

422 — a nonexistent field in the filter:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Unknown field definition `nonsense` (nonsense) for \\Bitrix\\Landing\\Internals\\Landing Entity."
  }
}

Errors

HTTP Code Description
422 BITRIX_ERROR An unknown field was passed in filter, or another parameter that Bitrix24 does not support
403 SCOPE_DENIED The API key does not have the landing scope
401 TOKEN_MISSING The API key has no configured tokens
429 RATE_LIMITED Rate limit exceeded: 300 requests per minute per portal, all API keys of the portal share one limit. The exact value arrives in the x-ratelimit-limit header (the cap is divided across replicas). Retry after the delay in the Retry-After header

Full list of general API errors — Errors.

Known specifics

When to choose search versus list. Both endpoints return the same set of pages for the same filter. Use POST /v1/pages/search when the filter is more complex than equality (for example, id in [3, 7, 9]) — escaping nested operators is easier in a JSON body. For simple filter[field]=value cases, GET /v1/pages is enough.

Date format in the filter — the account locale format, and a format from another locale silently returns an empty list. Pass a date in the filter exactly as the account returns it in the response: not as ISO 8601, but in the account's own locale format — DD.MM.YYYY HH:MM:SS (06.06.2026 00:00:00) in the RU locale, MM/DD/YYYY hh:mm:ss (06/06/2026 00:00:00) in the EN locale. A value in another locale's format, or in ISO, is not recognized by Bitrix24, which returns an empty list with code 200 — there is no error, so the mismatch is easy to miss. The only reliable way to learn the format of a specific account is to read dateModify of any page (GET /v1/pages?limit=1) and pass the date the same way. The same format is used in the filter, in the list and in the card — see Field reference.

meta.durationMs. Unlike list, search always returns the request duration in milliseconds — useful when debugging performance.

Pagination via offset is supported. Vibecode returns the requested [offset, offset + limit) window. The meta.total value is the exact number of records matching the filter, and meta.hasMore shows whether there are records beyond the window.

See also