Search sites

POST /v1/sites/search

Searches for sites with filtering and auto-pagination. Equivalent to GET /v1/sites with filters, but via POST — more convenient for complex requests with many conditions.

Request fields (body)

Type filter and area (scope). Bitrix24 binds filter.type to the current area — the default area exposes only PAGE / STORE / SMN / VIBE. If you filter by {"filter": {"type": "KNOWLEDGE"}} or "GROUP" and do not pass scope, Vibecode supplies the matching area itself (type=KNOWLEDGE → scope=KNOWLEDGE), and the search returns exactly the knowledge bases / group pages. An explicit scope wins. If the type is specified using a list or operator ({"type": {"$in": ["KNOWLEDGE", "PAGE"]}}) and no single area can be determined, meta.warnings includes a hint with the code TYPE_REQUIRES_SCOPE. MAINPAGE is an area, not a site type (its sites have type VIBE), so it is not derived from the filter.

Examples

curl — personal key

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

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

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

JavaScript — OAuth application

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

Response fields

The meta fields sit next to data, not inside it. Use meta.hasMore to paginate: even when the length of data equals limit, this can be the last page.

Use a site's id from the data array in the following URL:

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

<portal> is your Bitrix24 account domain. Access is restricted by the employee's permissions in Bitrix24.

Response example

{
  "success": true,
  "data": [
    {
      "id": 157,
      "title": "Promo landing",
      "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
  }
}

With a date-range filter longer than 14 days, meta also includes autoWindowed, windowCount, and batchWaves:

{
  "success": true,
  "data": [ /* ... */ ],
  "meta": {
    "total": 2,
    "hasMore": false,
    "autoWindowed": true,
    "windowCount": 339,
    "batchWaves": 4,
    "durationMs": 3136
  }
}

Error response example

403 — missing required scope:

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

Errors

For the full list of common API errors, see Errors.

Known specifics

Time-window splitting. A date-range filter longer than 14 days is automatically split into weekly windows executed in parallel waves, so the result set bypasses the ceiling of 5000 records per call. meta then includes autoWindowed: true, the number of windows windowCount, and the number of waves batchWaves. The autoWindow: false parameter disables splitting. While splitting is active, an offset greater than zero is rejected with UNSTABLE_OFFSET_PAGINATION.

Visibility by user permissions. The search returns only the sites the API key owner has "view" permission for. If a result is expected but data is empty, check the user's permissions.

Deleted sites. Excluded by default. To include them in the result, pass {"filter": {"deleted": "Y"}}. Values are Y or N.

Pagination via offset is supported. Vibecode returns the requested [offset, offset + limit) window. When present, meta.total is the exact number of records matching the filter. A search across time windows returns the count only after all windows have been read successfully and duplicates removed; the field is omitted when the search stops early at limit or a window returns an incomplete result. The API does not make additional requests solely to obtain a count. data.length is the number of returned records, and meta.hasMore shows whether there are records beyond the window.

See also

• List sites
• Get site
• Filtering syntax
• Batch
• Limits and optimization