لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/entities/pages/favorite.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

Save a block to "My blocks"

POST /v1/pages/:pageId/blocks/:blockId/favorite

Saves a page block as a template in the "My blocks" section of the Bitrix24 account block catalog. Every editor of the account sees the template — it is not a personal bookmark.

Parameters

Parameter Type Required Description
ParameterpageId (path) Typenumber Requiredyes DescriptionPage ID. List: GET /v1/pages
ParameterblockId (path) Typenumber Requiredyes DescriptionID of the block on this page that becomes the template. List: GET /v1/pages/:pageId/blocks. A block from another page returns 404
Parameterscope (query) Typestring Requiredno DescriptionInternal landing scope: KNOWLEDGE — knowledge base, GROUP — group knowledge base, MAINPAGE — home page. Omit for a regular site

Request fields (body)

Field Type Required Description
Fieldname Typestring Requiredyes DescriptionTemplate name in "My blocks". An empty string or a whitespace-only string is rejected
Fieldsections Typearray of string Requiredno DescriptionCatalog sections the template goes into, for example ["text"]. Section codes are the data keys in the GET /v1/block-repository response. An empty array [] is accepted, empty strings in the array are not

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/pages/42/blocks/50/favorite" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Reusable block","sections":["text"]}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/pages/42/blocks/50/favorite" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Reusable block","sections":["text"]}'

JavaScript — personal key

javascript 
const response = await fetch("https://vibecode.bitrix24.com/v1/pages/42/blocks/50/favorite", {
  method: "POST",
  headers: {"X-Api-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
  body: JSON.stringify({"name": "Reusable block", "sections": ["text"]}),
})
const result = await response.json()
if (!response.ok) throw new Error(result.error.message)
console.log(result.data)

JavaScript — OAuth application

javascript 
const response = await fetch("https://vibecode.bitrix24.com/v1/pages/42/blocks/50/favorite", {
  method: "POST",
  headers: {"X-Api-Key": "YOUR_APP_KEY", "Authorization": "Bearer USER_SESSION_TOKEN", "Content-Type": "application/json"},
  body: JSON.stringify({"name": "Reusable block", "sections": ["text"]}),
})
const result = await response.json()
if (!response.ok) throw new Error(result.error.message)
console.log(result.data)

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.blockId Typenumber DescriptionTemplate ID in "My blocks". Differs from the source block's blockId in the path. Pass this ID to template deletion
Fielddata.code Typestring DescriptionTemplate code in the form sourceCode@blockId. The template appears in the block catalog under this code

Response example

JSON 
{
  "success": true,
  "data": {
    "blockId": 29441,
    "code": "03.1.three_cols_big_with_text_and_titles@29441"
  }
}

Error response example

400 — template name not provided:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "message": "name is required."
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS Descriptionname is required. — name is missing, empty or whitespace-only
HTTP400 CodeINVALID_PARAMS Descriptionsections must be an array of non-empty strings. — sections is not an array, or the array contains a non-string, an empty string or a whitespace-only string
HTTP400 CodeINVALID_PARAMS DescriptionBody contains an unsupported field. — the body has a field other than name and sections, for example preview
HTTP404 CodeENTITY_NOT_FOUND DescriptionPage, block or card not found. — the block does not belong to page pageId or does not exist
HTTP400 CodeINVALID_PARAMS DescriptionpageId and blockId must be positive safe integers. — pageId or blockId is not a positive integer
HTTP400 CodeINVALID_PARAMS DescriptionBody must be a JSON object. — the body is not a JSON object
HTTP400 CodeINVALID_SCOPE Descriptionscope is not KNOWLEDGE, GROUP or MAINPAGE
HTTP422 CodeBITRIX_NO_EFFECT DescriptionBitrix24 did not return a saved block ID. — Bitrix24 did not return the ID of the saved template
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the action. The error text comes from Bitrix24
HTTP502 CodeBITRIX_ERROR DescriptionBitrix24 returned an invalid block code. — the source block has no catalog block code
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the landing scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only, the request is rejected before reaching Bitrix24
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe Bitrix24 user the key was issued for has no permission for this action
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeINVALID_API_KEY DescriptionThe key in X-Api-Key was not found or has been revoked
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP409 CodeLANDING_MODULE_NOT_ENABLED DescriptionThe Sites module is not available on the Bitrix24 account
HTTP409 CodePORTAL_ADDRESS_CHANGED DescriptionThe on-premise Bitrix24 moved to a new address, while the key webhook was issued for the old one. Reissue the key webhook
HTTP429 CodeRATE_LIMITED DescriptionBitrix24 request limit exceeded. Retry in 1-2 seconds
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 did not respond or returned a server error
HTTP503 CodeBITRIX_TIMEOUT DescriptionBitrix24 did not respond in time

Full list of common API errors — Errors.

Known specifics

  • Every call creates a new template. Repeating the call with the same block and the same name does not update the previous template — it adds another one with a new blockId. Delete unneeded templates with DELETE /v1/block-repository/favorites/:blockId.
  • The source block does not change. The template is a copy of the block at the time of the call. Later edits to the block on the page do not reach the template.

See also