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

Update page template areas

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

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

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionPage ID. List: GET /v1/pages
Parameterscope (query) Typestring Requiredno DescriptionInternal landing scope: KNOWLEDGE / GROUP / MAINPAGE. Specify it if the page's 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. Key — area number: a signed integer from -2147483648 to 2147483647, including 0. Value — ID of the page to place in the area, or null to remove the binding from that 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/pages/:id/template-areas.

Examples

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/pages/2381/template-areas" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"areas": {"1": 2387}}'

curl — OAuth application

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/pages/2381/template-areas" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"areas": {"1": 2387}}'

JavaScript — personal key

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

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/pages/2381/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: 2387 } }),
})

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

Response fields

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

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

Response example

JSON 
{
  "success": true,
  "data": {
    "areas": {
      "1": 2387
    }
  }
}

Error response example

409 — another write of this page'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 page's areas at the same time. Retry the request once that write completes
HTTP404 CodeENTITY_NOT_FOUND DescriptionEntity not found or not visible — the page with this ID is not found, is not accessible 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 is not found or is not accessible 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 unavailable on this Bitrix24 account. Ask a Bitrix24 account administrator to enable it — until then 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 page's areas did not match the expected ones. Check whether the user has permission to change the page 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 refused before any call to the Bitrix24 account
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 page layout has fewer areas. For the number of areas in each layout, see Layout templates.
  • Keys come back in decimal notation. The key 007 becomes 7 in the response, and +3 becomes 3.
  • The page can be from another site. Any page the user can see can be placed in an area, including one from a different site. One page can occupy several areas.

See also