## List sites

`GET /v1/sites`

Returns a list of sites in your Bitrix24 account with filtering and auto-pagination support. By default only non-deleted sites are returned — to retrieve sites from the recycle bin pass `filter[deleted]=Y`.

## Parameters

| Parameter | Type | Default | Description |
|----------|-----|-----------|---------|
| `limit` | number | `50` | Number of records (up to 5000) |
| `offset` | number | `0` | Skip N records |
| `select` | string | — | Field selection: `?select=id,title,type` |
| `filter` | object | — | Filtering by the site's key fields.<br>[Filtering syntax](/docs/filtering). Example: `?filter[type]=PAGE` |
| `scope` | string | — | Internal landing area. Allowed values: `KNOWLEDGE` (knowledge base), `GROUP` (workgroup pages), `MAINPAGE` (home pages). Without the parameter, regular landing sites are returned. Accepted as `?scope=KNOWLEDGE` or `?filter[scope]=KNOWLEDGE` — both forms produce the same request to Bitrix24 |

> **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 `filter[type]=GROUP` and do **not** pass `scope`, Vibecode supplies the matching area itself (`type=KNOWLEDGE` → `scope=KNOWLEDGE`) — filtering by knowledge bases and group pages works without setting `scope` manually. An explicit `scope` always wins. If the type is given as a list or an operator (`?filter[type][]=KNOWLEDGE&filter[type][]=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 type filter: pass `scope=MAINPAGE` explicitly for home pages.

## Examples

### curl — personal key

```bash
curl "https://vibecode.bitrix24.com/v1/sites?limit=10&filter[type]=PAGE" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl "https://vibecode.bitrix24.com/v1/sites?limit=10&filter[type]=PAGE" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/sites?limit=10&filter[type]=PAGE', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
console.log(`Found ${meta.total} sites`)
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/sites?limit=10&filter[type]=PAGE', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data, meta } = await res.json()
```

## Response fields

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data` | array | Array of sites (each record contains the site's key fields) |
| `meta.total` | number | Total number of records matching the filter |
| `meta.hasMore` | boolean | Whether there are more records beyond `limit` |
| `meta.warnings` | array | Hints about how the request was applied. Present when the type filter is given as a list or an operator — code `TYPE_REQUIRES_SCOPE` |

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

```json
{
  "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"
    },
    {
      "id": 3,
      "title": "Services catalog",
      "code": "/services/",
      "type": "PAGE",
      "active": true,
      "domainId": 5,
      "createdById": 1,
      "dateCreate": "22.04.2020 14:39:17",
      "dateModify": "06.05.2024 15:43:34"
    }
  ],
  "meta": {
    "total": 25,
    "hasMore": true
  }
}
```

## Error response example

403 — no scope:

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

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 403 | `SCOPE_DENIED` | The API key does not have the `landing` scope |
| 401 | `TOKEN_MISSING` | The API key has no configured tokens |

The full list of common API errors — [Errors](/docs/errors).

## Known specifics

**Visibility by user permissions.** Only sites for which the API key owner has the "view" permission appear in the list. If your Bitrix24 account has sites but the response is empty, check the permissions of the user the key was issued for.

**Recycle bin.** To retrieve deleted sites, pass `filter[deleted]=Y`. Values — `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.** Supported via `?order[field]=asc|desc` or the short form `?sort=-field` (descending). Without the parameter, results are sorted by ascending `id`.

**Knowledge base and other internal areas.** The `scope` parameter switches the source: `KNOWLEDGE` — knowledge base sites, `GROUP` — sites inside workgroups, `MAINPAGE` — home pages. Without the parameter, regular landing sites are returned (the default source). Example: `GET /v1/sites?scope=KNOWLEDGE` returns knowledge base sites and ignores regular landings.

## See also

- [Get site](/docs/entities/sites/get) — data of a single site by ID
- [Search sites](/docs/entities/sites/search) — POST request for complex filters
- [Create site](/docs/entities/sites/create) — create a new one
- [Filtering syntax](/docs/filtering)
- [Entity API](/docs/entity-api) — select, order, pagination
- [Batch](/docs/batch) — combining several list requests
- [Limits and optimization](/docs/optimization) — rate limits