## List layout templates

`GET /v1/site-templates`

Returns all layout templates with the code, title and number of areas of each.

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|----------|
| `scope` (query) | string | no | Internal landing scope: `KNOWLEDGE` — knowledge base, `GROUP` — group knowledge base, `MAINPAGE` — main page. Omit for a regular site |

The method accepts no other query parameters: any extra parameter is rejected with `400 INVALID_PARAMS`. The full list is returned in one response, without pagination. Items are ordered by ascending `id`, not by `sort`: to show templates in sort order, sort the array by `sort` on your side.

## Examples

### curl — personal key

```bash
curl "https://vibecode.bitrix24.com/v1/site-templates" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl "https://vibecode.bitrix24.com/v1/site-templates" \
  -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/site-templates', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { data } = await res.json()
for (const template of data) {
  console.log(`${template.code}: ${template.areaCount} areas`)
}
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/site-templates', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | Always `true` on success |
| `data` | array | Layout templates |
| `data[].id` | number | Template ID. The same value appears in the `tplId` field of [sites](/docs/entities/sites/list) and [pages](/docs/entities/pages/list) that use this layout |
| `data[].code` | string | Permanent symbolic code of the template, for example `header_footer` |
| `data[].title` | string | Template name in the language of the Bitrix24 account |
| `data[].areaCount` | number | Number of layout areas: header, footer, side columns. `0` — a layout without areas |
| `data[].active` | boolean | Whether the template is active |
| `data[].sort` | number | Sort index of the template |

The template HTML markup is not included in the response.

## Response example

Three templates from the full list:

```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "code": "empty",
      "title": "Empty",
      "areaCount": 0,
      "active": true,
      "sort": 100
    },
    {
      "id": 7,
      "code": "header_footer",
      "title": "With header and footer",
      "areaCount": 2,
      "active": true,
      "sort": 400
    },
    {
      "id": 13,
      "code": "header_only",
      "title": "Header only",
      "areaCount": 1,
      "active": true,
      "sort": 350
    }
  ]
}
```

## Error response example

400 — `scope` is not one of the allowed values:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_SCOPE",
    "message": "scope must be KNOWLEDGE, GROUP or MAINPAGE"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 400 | `INVALID_SCOPE` | `scope` is not `KNOWLEDGE`, `GROUP` or `MAINPAGE` |
| 400 | `INVALID_PARAMS` | `Unsupported query parameter` — a query parameter the method does not accept was passed |
| 422 | `BITRIX_ERROR` | `Bitrix24 returned invalid templates` — Bitrix24 returned the template list in an unexpected shape |
| 403 | `SCOPE_DENIED` | The API key does not have the `landing` scope |
| 403 | `BITRIX_ACCESS_DENIED` | The Bitrix24 user on whose behalf the key was issued has no access to sites |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |
| 401 | `INVALID_API_KEY` | The key in `X-Api-Key` was not found or has been revoked |
| 401 | `TOKEN_MISSING` | The API key has no configured tokens |
| 409 | `PORTAL_ADDRESS_CHANGED` | The on-premise Bitrix24 moved to a new address, but the key's webhook was issued for the old one. Reissue the key's webhook |
| 429 | `RATE_LIMITED` | Bitrix24 request rate limit exceeded. Retry the request in 1-2 seconds |
| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 did not respond or responded with a server error |
| 503 | `BITRIX_TIMEOUT` | Bitrix24 did not respond within the allotted time. The read can be retried |

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

## See also

- [Site template areas](/docs/entities/sites/template-areas)
- [Page template areas](/docs/entities/pages/template-areas)
- [Page templates](/docs/entities/page-templates)
- [List sites](/docs/entities/sites/list)
- [List pages](/docs/entities/pages/list)