# Site template areas

Binds pages to the areas of the site layout — header, footer, sidebar — reads the bindings, changes them one at a time and removes them all at once. The pages themselves stay on the site when a binding is removed.

Bitrix24 API: `landing.template.getSiteRef`, `landing.template.setSiteRef`
Scope: `landing`

## Operations

- [Get site template areas](./template-areas-list.md) — `GET /v1/sites/:id/template-areas`
- [Update site template areas](./template-areas-update.md) — `PATCH /v1/sites/:id/template-areas`
- [Clear site template areas](./template-areas-delete.md) — `DELETE /v1/sites/:id/template-areas`

## Key fields

All three methods return one object — the site bindings after the call.

| Field | Description |
|------|----------|
| `areas` | Area bindings. The key is the area number as a string, the value is the ID of the page placed in that area. A site with no bindings returns an empty object `{}` |
| area number | Signed integer from `-2147483648` to `2147483647`, including `0`. The response returns it in decimal notation: `007` becomes `7` |
| page ID | ID of any page visible to the user, including a page from another site. List of pages: [`GET /v1/pages`](/docs/entities/pages/list) |

## What to know before you start

1. **The layout defines the areas, but the number is not checked against it.** [Layout templates](/docs/entities/site-templates) shows how many areas each layout has. A write accepts any number in the allowed range, even if the layout has fewer areas.
2. **The site layout cannot be changed through the API.** The site `tplId` field is read-only: [`PATCH /v1/sites/:id`](/docs/entities/sites/update) with it returns `400 READONLY_FIELD`. The page layout is changed by [`PATCH /v1/pages/:id`](/docs/entities/pages/update) with the `tplId` field.
3. **A site and a page have separate sets of areas.** [Page template areas](/docs/entities/pages/template-areas) are read and written separately. The site response does not include page areas, and clearing site areas does not affect page areas.
4. **An update is merged with the current set.** `PATCH` changes only the areas passed, and a `null` value removes the binding from one area. All bindings can be removed only with `DELETE`: an empty `areas` returns `400`.
5. **A write is verified by rereading.** After a change, write methods read the areas again and return them. If the change was not saved, the response is `422 BITRIX_ERROR`, not `200`.
6. **One write at a time.** While a write to a site's areas is in progress, a second write to the same areas through the API returns `409 TEMPLATE_AREAS_BUSY` — retry it later. The lock applies only between API requests: it does not account for edits made in the Bitrix24 interface.
7. **A site in a separate scope: knowledge base, group or the `MAINPAGE` scope.** For such a site, pass the `scope` query parameter with the value `KNOWLEDGE`, `GROUP` or `MAINPAGE` — without it the site is not found and the response is `404`. For an ordinary site, do not pass `scope`.

## Typical scenario

1. Find the site: [`GET /v1/sites`](/docs/entities/sites/list).
2. Find pages for the header and footer: [`GET /v1/pages?filter[siteId]=:id`](/docs/entities/pages/list).
3. Check the current bindings: [`GET /v1/sites/:id/template-areas`](./template-areas-list.md).
4. Place pages in areas: [`PATCH /v1/sites/:id/template-areas`](./template-areas-update.md) with `{"areas": {"1": 2383, "2": 2385}}`.
5. Remove all bindings when they are no longer needed: [`DELETE /v1/sites/:id/template-areas`](./template-areas-delete.md).

## Limits

| Limit | Value |
|-------|----------|
| Area number | From `-2147483648` to `2147483647` |
| Concurrent writes | One per site. A second one at the same time returns `409 TEMPLATE_AREAS_BUSY` |
| Request rate | General API limits — [Limits and optimization](/docs/optimization) |

## See also

- [Sites](/docs/entities/sites)
- [Page template areas](/docs/entities/pages/template-areas)
- [Layout templates](/docs/entities/site-templates)
- [System pages](/docs/entities/sites/system-pages)
- [Limits and optimization](/docs/optimization)