For AI agents: markdown of this page — /docs-content-en/note/files.md documentation index — /llms.txt

Files

Attachments to Knowledge Base 2.0 documents. The Upload file method saves the file content, links the file to the document, and returns the ready-to-insert assetMarkdown fragment. The attachment appears in the document text only after you insert that fragment into the content via PATCH /v1/note/documents/:id. Getting the metadata returns the same object by document and file ID.

Scope: note | Base URL: https://vibecode.bitrix24.com/v1 | Authorization: X-Api-Key

Upload file

POST /v1/note/documents/:documentId/files

Saves the file content in Base64 and attaches it to a Knowledge Base document. The file itself is not inserted into the document content — to make the attachment appear in the text, insert assetMarkdown into the content and save the document via PATCH /v1/note/documents/:id. A ready-to-use assetMarkdown already arrives in the upload response, so no second request is needed for it; GET /v1/note/documents/:documentId/files/:id returns the same object later.

Parameters

Parameter Type Required Description
ParameterdocumentId (path) Typeinteger Requiredyes DescriptionDocument the file is attached to. Get the identifier from POST /v1/note/documents

Request fields (body)

Field Type Required Description
FieldfileName Typestring Requiredyes DescriptionFile name with extension. The extension determines the attachment type
FieldfileContent Typestring Requiredyes DescriptionFile content encoded in Base64

The request size is limited to 40 MB. Bitrix24 sets the exact file size limit and enforces it on its side.

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/note/documents/77/files \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "diagram.png",
    "fileContent": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
  }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/note/documents/77/files \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "diagram.png",
    "fileContent": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/note/documents/77/files', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ fileName: 'diagram.png', fileContent: 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=' }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/note/documents/77/files', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ fileName: 'diagram.png', fileContent: 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=' }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.id Typenumber DescriptionIdentifier of the uploaded file, also the fileId. Passed to GET /v1/note/documents/:documentId/files/:id
Fielddata.documentId Typenumber DescriptionThe document the file is attached to
Fielddata.name Typestring DescriptionOriginal file name
Fielddata.size Typenumber DescriptionFile size in bytes
Fielddata.mimeType Typestring DescriptionMIME type of the file, detected on save
Fielddata.assetType Typestring DescriptionAttachment category: image, video, or file
Fielddata.assetMarkdown Typestring DescriptionReady-to-use [[<assetType> fileId=<id>]] snippet to insert into the content

The response mirrors the shape of GET /v1/note/documents/:documentId/files/:id. Fields are passed through from Bitrix24 as is: if the Bitrix24 account does not return a field, the platform does not fill it in. data.id is always present.

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 5001,
    "documentId": 77,
    "name": "diagram.png",
    "size": 6321,
    "mimeType": "image/png",
    "assetType": "image",
    "assetMarkdown": "[[image fileId=5001]]"
  }
}

Error response example

404 — document not found:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Record with ID = `999999` not found"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionfileName or fileContent is missing, or documentId has the wrong type
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionNo permission to edit the document
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode
HTTP404 CodeENTITY_NOT_FOUND DescriptionThe document does not exist, is archived, or is in the trash
HTTP413 Code— DescriptionThe request size exceeds 40 MB
HTTP422 CodeBITRIX_ERROR DescriptionThe file size exceeds the limit, the file type is not allowed, or the Base64 data is corrupted. See the text in error.message
HTTP403 CodeSCOPE_DENIED DescriptionThe key is missing the note scope
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no configured tokens

Full list of common API errors — Errors.

See also