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

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

Upload an image to a block

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

Uploads an image file for a page block and returns its URL. The file is passed in the request body as Base64. Upload by URL is not supported.

Parameters

Parameter Type Required Description
ParameterpageId (path) Typenumber Requiredyes DescriptionPage ID. List: GET /v1/pages
ParameterblockId (path) Typenumber Requiredyes DescriptionID of a block on this page. List: GET /v1/pages/:pageId/blocks
Parameterscope (query) Typestring Requiredno DescriptionSite area: KNOWLEDGE — knowledge base, GROUP — workgroup pages, MAINPAGE — main pages. Omit the parameter for pages of all other sites

Request fields (body)

Field Type Required Description
FieldfileName Typestring Requiredyes DescriptionFile name with an extension, for example pixel.png. An empty string is not accepted
FieldcontentBase64 Typestring Requiredyes DescriptionThe image file content in standard Base64: the alphabet with + and /, length a multiple of 4, no line breaks and no data: prefix. A file URL instead of the content is not accepted. The whole JSON body is up to 40 MiB, which is about 30 MiB of the source file

The body must contain no other fields.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/pages/42/blocks/7/files" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "pixel.png",
    "contentBase64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jRZkAAAAASUVORK5CYII="
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/pages/42/blocks/7/files" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "pixel.png",
    "contentBase64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jRZkAAAAASUVORK5CYII="
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/pages/42/blocks/7/files', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fileName: 'pixel.png',
    contentBase64: 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jRZkAAAAASUVORK5CYII=',
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/pages/42/blocks/7/files', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fileName: 'pixel.png',
    contentBase64: 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jRZkAAAAASUVORK5CYII=',
  }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata.fileId Typenumber DescriptionID of the uploaded file
Fielddata.url Typestring DescriptionURL of the uploaded image. Pass it in src of an image node

Response example

JSON 
{
  "success": true,
  "data": {
    "fileId": 17,
    "url": "https://cdn.example.com/landing/2e8/pixel.png"
  }
}

Error response example

400 — a file URL was passed instead of the file content:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "fileName and non-empty standard contentBase64 are required; URLs are not accepted"
  }
}

Errors

HTTP Code Marker in the response Description
HTTP400 CodeINVALID_PARAMS Marker in the responsepageId and blockId must be positive safe integers DescriptionpageId or blockId is not a positive integer
HTTP400 CodeINVALID_SCOPE Marker in the responsescope must be KNOWLEDGE, GROUP or MAINPAGE Descriptionscope is not KNOWLEDGE, GROUP or MAINPAGE
HTTP400 CodeMISSING_REQUIRED_FIELDS Marker in the responseRequired fields: fileName, contentBase64 DescriptionThe body lacks one of the fields. The message lists both fields
HTTP400 CodeMISSING_REQUIRED_FIELDS Marker in the responseA JSON object is required DescriptionThe body is not a JSON object
HTTP400 CodeINVALID_PARAMS Marker in the responseUnexpected body field DescriptionThe body has a field other than fileName and contentBase64
HTTP400 CodeINVALID_PARAMS Marker in the responsefileName and non-empty standard contentBase64 are required; URLs are not accepted DescriptionfileName is empty or whitespace only, or contentBase64 is empty, contains a file URL or is not standard Base64: the length is not a multiple of 4 or it has a data: prefix
HTTP401 CodeTOKEN_MISSING Marker in the response— DescriptionThe API key has no Bitrix24 access tokens
HTTP403 CodeSCOPE_DENIED Marker in the response— DescriptionThe key has no landing scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY Marker in the response— DescriptionThe key is read-only. The request is rejected before the Bitrix24 account is called
HTTP404 CodeENTITY_NOT_FOUND Marker in the responsePage or block not found DescriptionThe page does not exist, the block does not exist, or the block belongs to another page
HTTP409 CodeLANDING_MODULE_NOT_ENABLED Marker in the response— DescriptionThe Sites module is not enabled on the Bitrix24 account
HTTP409 CodePORTAL_ADDRESS_CHANGED Marker in the response— DescriptionThe on-premise Bitrix24 moved to a new address, but the key's webhook was issued for the old one. Reissue the key's webhook
HTTP413 CodePAYLOAD_TOO_LARGE Marker in the response— DescriptionThe JSON body is larger than 40 MiB
HTTP422 CodeBITRIX_ERROR Marker in the responseb24Code: FILE_ERROR DescriptionThe file content is not an image. The error.message text comes in the Bitrix24 account language
HTTP422 CodeBITRIX_ERROR Marker in the response— DescriptionThe Bitrix24 account did not return the uploaded image
HTTP429 CodeLARGE_BODY_BACKEND_BUSY Marker in the response— DescriptionThe server is already processing several large request bodies. Retry the request after the pause given in the Retry-After header

Full list of common API errors — Errors.

Known specifics

See also