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

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, put assetMarkdown into it 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
documentId (path) integer yes Document the file is attached to. Get the identifier from POST /v1/note/documents

Request fields (body)

Field Type Required Description
fileName string yes File name with extension. The extension determines the attachment type
fileContent string yes File 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: base64Content }),
})

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: base64Content }),
})

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

Response fields

Field Type Description
success boolean Always true on success
data.id number Identifier of the uploaded file, also the fileId. Passed to GET /v1/note/documents/:documentId/files/:id
data.documentId number The document the file is attached to
data.name string Original file name
data.size number File size in bytes
data.mimeType string File content type in MIME form, detected on save
data.assetType string Attachment category: image, video, or file
data.assetMarkdown string Ready-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 arrive from Bitrix24 as they are: if an account did not return one of them, the platform does not invent it, and 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
400 INVALID_PARAMS fileName or fileContent is missing, or documentId has the wrong type
403 BITRIX_ACCESS_DENIED No permission to edit the document
403 WRITE_BLOCKED_READONLY_KEY The key is in read-only mode
404 ENTITY_NOT_FOUND The document does not exist, is archived, or is in the trash
413 — The request size exceeds 40 MB
422 BITRIX_ERROR The file size exceeds the limit, the file type is not allowed, or the Base64 is corrupted. See the text in error.message
403 SCOPE_DENIED The key is missing the note scope
401 TOKEN_MISSING The key has no configured tokens

Full list of common API errors — Errors.

See also