#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 {"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 given as a list/operator ({"type": {"$in": ["KNOWLEDGE", "PAGE"]}}), where a single area cannot be chosen, meta.warnings carries a hint with 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('Found:', meta.total)

#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. Pages must be walked by meta.hasMore: a data length equal to limit does not rule out the last page.

The URL of any site from the data array is its id:

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

<portal> is the 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 wider than 14 days, meta additionally returns autoWindowed, windowCount, and batchWaves:

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

#Error response example

403 — no scope:

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

#Errors

The full list of common API errors — Errors.

#Known specifics

Time-window splitting. A date-range filter wider 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 returns 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. The meta.total value is the exact number of records matching the filter, and meta.hasMore shows whether there are records beyond the window.

Sorting. The sort field in the body: {"sort": "-id"} — descending, {"sort": "id"} — ascending (the order alias is also accepted). Without the parameter — ascending by id.

#See also

• List sites — GET request with query parameters (for simple filters)
• Get site — data of a single site by ID
• Filtering syntax
• Batch — combining several searches into one request
• Limits and optimization — rate limits