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

Upload a file to a chat folder

POST /v1/chats/:chatId/files/uploads

This method is rolling out in im 26.1500.0. It is not available on every Bitrix24 account yet. Until the method arrives, the API returns 422 METHOD_NOT_YET_AVAILABLE with error.release.

Uploads one file into the chat folder without posting a message. To publish it, call the publish route with data.file.id in uploadIds.

Parameters

Parameter Type Required Description
ParameterchatId (path) Typenumber Requiredyes DescriptionChat ID. Get it from: POST /v1/chats or the chatId field of a GET /v1/chats/recent row

Request fields (body)

Field Type Required Description
Fieldfilename Typestring Requiredyes DescriptionFile name with extension
Fieldcontent Typestring Requiredyes DescriptionBase64 content, up to 4 MiB after decoding

Other fields and query parameters are rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/chats/42/files/uploads \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename":"a.txt","content":"YWJj"}'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/chats/42/files/uploads \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"filename":"a.txt","content":"YWJj"}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/42/files/uploads', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"filename": "a.txt", "content": "YWJj"}),
})
const { success, data, error } = await res.json()
console.log(success ? data : error)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/42/files/uploads', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"filename": "a.txt", "content": "YWJj"}),
})
const { success, data, error } = await res.json()
console.log(success ? data : error)

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata.file Typeobject DescriptionFile in the chat folder. Token-bearing URLs are set to null
Fielddata.file.id Typenumber DescriptionUploaded file ID. Pass it in uploadIds when publishing
Fielddata.file.name Typestring DescriptionFile name
Fielddata.file.size Typenumber DescriptionFile size in bytes
Fielddata.chatId Typenumber DescriptionChat ID
Fielddata.dialogId Typestring DescriptionDialog ID. No messageId

Response example

JSON 
{
  "success": true,
  "data": {
    "file": {
      "id": 7701,
      "name": "a.txt",
      "size": 3
    },
    "chatId": 42,
    "dialogId": "chat42"
  }
}

Error response example

400 — the content exceeds 4 MiB:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "`content` exceeds the 4 MiB file limit."
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionInvalid body or unexpected parameters
HTTP400 CodeINVALID_CHAT_ID DescriptionchatId in the path is not a positive integer
HTTP401 CodeTOKEN_MISSING DescriptionNo Bitrix24 access tokens
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the im scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionNo access to the chat in Bitrix24
HTTP413 CodePAYLOAD_TOO_LARGE DescriptionJSON body exceeds 40 MiB. Reduce the request
HTTP422 CodeMETHOD_NOT_YET_AVAILABLE DescriptionThe method is not available on the Bitrix24 account yet — see the notice at the top of the page
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 refused the file
HTTP429 CodeLARGE_BODY_BACKEND_BUSY DescriptionToo many large bodies are being accepted right now. Retry according to Retry-After
HTTP429 CodeQUEUE_TIMEOUT DescriptionThe Bitrix24 queue is overloaded. Retry according to Retry-After

For the generic 422 BITRIX_ERROR, the error.b24Code field is present only when the code is recognized. The platform does not retry an upload after an unknown outcome.

Full list of common API errors — Errors.

See also