For AI agents: markdown of this page — /docs-content-en/entities/sites/system-pages-set.md documentation index — /llms.txt

Assign a system page

PUT /v1/sites/:id/system-pages/:type

Assigns a site page to a system role, for example making it the cart or the personal account page. If the role is already taken, the new page replaces the previous one.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionSite ID. List: GET /v1/sites
Parametertype (path) Typestring Requiredyes DescriptionRole: mainpage, catalog, personal, cart, order, payment, compare, feedback. What each one means — System pages
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
FieldpageId Typenumber Requiredyes DescriptionID of a page on the same site. List of the site's pages: GET /v1/pages?filter[siteId]=:id

The body accepts no other fields: an extra field returns 400 INVALID_PARAMS.

Examples

curl — personal key

Terminal 
curl -X PUT "https://vibecode.bitrix24.com/v1/sites/223/system-pages/personal" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pageId": 2373}'

curl — OAuth application

Terminal 
curl -X PUT "https://vibecode.bitrix24.com/v1/sites/223/system-pages/personal" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pageId": 2373}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/sites/223/system-pages/personal', {
  method: 'PUT',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ pageId: 2373 }),
})

const { success, data } = await res.json()
console.log('Site roles:', data.map((row) => `${row.type} → ${row.pageId}`))

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/sites/223/system-pages/personal', {
  method: 'PUT',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ pageId: 2373 }),
})

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

Response fields

The response contains all of the site's bindings after the change, not only the assigned one.

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionAll of the site's bindings
Fielddata[].type Typestring DescriptionRole: mainpage, catalog, personal, cart, order, payment, compare, feedback. What each one means — System pages
Fielddata[].pageId Typenumber DescriptionID of the page assigned to the role. Get the page: GET /v1/pages/:id
Fielddata[].title Typestring DescriptionPage title
Fielddata[].deleted Typeboolean DescriptionThe page is in the trash
Fielddata[].active Typeboolean DescriptionThe page is published

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "type": "cart",
      "pageId": 2371,
      "title": "Docs test cart",
      "deleted": false,
      "active": false
    },
    {
      "type": "personal",
      "pageId": 2373,
      "title": "Docs test personal",
      "deleted": false,
      "active": false
    }
  ]
}

Error response example

400 — the page belongs to another site:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Page must belong to this site"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionPage must belong to this site — the page with pageId is on another site
HTTP400 CodeINVALID_PARAMS DescriptionUnknown system-page type — type is not in the list of roles
HTTP400 CodeINVALID_PARAMS DescriptionpageId must be a positive safe integer — pageId is not a positive integer
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 the method does not accept
HTTP400 CodeINVALID_PARAMS DescriptionBody must be a JSON object — the body is not a JSON object, for example an array was sent
HTTP400 CodeINVALID_PARAMS DescriptionUnsupported query parameter — a query parameter the method does not accept was sent
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionThe body has no pageId
HTTP400 CodeINVALID_SCOPE Descriptionscope is not KNOWLEDGE, GROUP or MAINPAGE
HTTP404 CodeENTITY_NOT_FOUND DescriptionEntity not found or not visible — a site with this ID was not found, is not accessible to the user or belongs to another scope
HTTP404 CodeENTITY_NOT_FOUND DescriptionPage not found or not visible — the page with pageId was not found or is not accessible to the user
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 binding change; site settings permission may be missing — the binding is absent after the write. Check whether the user has permission to change site settings
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 did not confirm the binding change — Bitrix24 did not confirm the write
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned invalid system pages — Bitrix24 returned the list of bindings in an unexpected shape
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only. 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

  • One page can hold several roles. Assigning a page to a second role does not remove it from the first: it appears twice in the response, with different type values.
  • Repeated assignment is safe. Assigning the same page to the same role again returns 200 with the same set of bindings.
  • Publishing is not required. An unpublished page can be assigned too: it has active: false in the response.

See also