For AI agents: markdown of this page — /docs-content-en/entities/sites/template-areas-update.md documentation index — /llms.txt

Update site template areas

PATCH /v1/sites/:id/template-areas

Binds pages to areas of the site layout or removes the binding from individual areas. The areas you pass are changed, and the site's other bindings are kept.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionSite ID. List: GET /v1/sites
Parameterscope (query) Typestring Requiredno DescriptionInternal landing scope: KNOWLEDGE / GROUP / MAINPAGE. Specify it if the site belongs to the corresponding scope. Otherwise 404 ENTITY_NOT_FOUND is returned. Omit it for an ordinary site

Request fields (body)

Field Type Required Description
Fieldareas Typeobject Requiredyes DescriptionAreas to change, at least one. The key is the area number: a signed integer from -2147483648 to 2147483647, including 0. The value is the ID of the page to place in the area, or null to remove the binding from this area. Page list: GET /v1/pages

The body accepts no other fields: an extra field returns 400 INVALID_PARAMS. To remove the bindings from all areas at once, use DELETE /v1/sites/:id/template-areas.

Examples

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/sites/225/template-areas" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"areas": {"1": 2383, "2": 2385}}'

curl — OAuth application

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/sites/225/template-areas" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"areas": {"1": 2383, "2": 2385}}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/sites/225/template-areas', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ areas: { 1: 2383, 2: 2385 } }),
})

const { success, data } = await res.json()
console.log('Site areas:', data.areas)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/sites/225/template-areas', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ areas: { 1: 2383, 2: 2385 } }),
})

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

Response fields

The response contains all of the site's bindings after the change, not only the ones you passed.

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.areas Typeobject DescriptionThe site's area bindings. The key is the area number as a decimal string, the value is the page ID. Get a page: GET /v1/pages/:id. If no bindings remain after the change, it is an empty object {}

Response example

JSON 
{
  "success": true,
  "data": {
    "areas": {
      "1": 2383,
      "2": 2385
    }
  }
}

Error response example

409 — another write to this site's areas is in progress at the same time:

JSON 
{
  "success": false,
  "error": {
    "code": "TEMPLATE_AREAS_BUSY",
    "message": "Another template-area update is in progress; retry"
  }
}

Errors

HTTP Code Description
HTTP409 CodeTEMPLATE_AREAS_BUSY DescriptionAnother API request is changing this site's areas at the same time. Retry the request after that write completes
HTTP404 CodeENTITY_NOT_FOUND DescriptionEntity not found or not visible — a site with this ID was not found, is not available to the user, or belongs to a different scope: the wrong scope was passed
HTTP404 CodeENTITY_NOT_FOUND DescriptionArea page not found or not visible — a page from the areas value was not found or is not available to the user
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionThe body has no areas, or areas is an empty object
HTTP400 CodeINVALID_PARAMS DescriptionArea keys must be distinct signed 32-bit integers; page IDs must be positive safe integers; null removes an area — an area number is not an integer or is out of range, two keys resolve to the same number (1 and 01), or a value is neither a page ID nor null
HTTP400 CodeINVALID_PARAMS Descriptionid must be a positive safe integer — id is not a positive integer
HTTP400 CodeINVALID_PARAMS DescriptionUnsupported body field — the body contains a field other than areas
HTTP400 CodeINVALID_PARAMS DescriptionBody must be a JSON object — the body is not a JSON object, for example an array was passed
HTTP400 CodeINVALID_PARAMS DescriptionUnsupported query parameter — a query parameter the method does not accept was passed
HTTP400 CodeINVALID_SCOPE Descriptionscope is not KNOWLEDGE, GROUP or MAINPAGE
HTTP409 CodeLANDING_MODULE_NOT_ENABLED DescriptionThe Sites module is not available on the Bitrix24 account. Ask the account administrator to enable it — while the module is disabled, a retry returns the same refusal
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 did not save the template areas; settings permission may be missing — after the write, the site's areas did not match the expected ones. Check whether the user has permission to change the site settings
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 did not confirm the template-area change — Bitrix24 did not confirm the write
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned invalid template areas — Bitrix24 returned the areas in an unexpected form
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key works in read-only mode. The request is rejected before it reaches Bitrix24
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the landing scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

  • The area number is not checked against the layout. Any number in the allowed range is accepted, even if the site layout has fewer areas. For the number of areas in each layout, see Layout templates.
  • Keys are returned in decimal notation. The key 007 becomes 7 in the response, and +3 becomes 3.
  • The page can come from another site. Any page visible to the user can be placed in an area, including a page from a different site. One page can occupy several areas.

See also