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
chatId (path) number yes Chat ID
filename (body) string yes File name with extension
content (body) string yes Base64 content, up to 4 MiB after decoding

Requires the im scope and a write-enabled key. The JSON body limit is 40 MiB; large requests may receive 429 LARGE_BODY_BACKEND_BUSY with Retry-After. Other fields and query parameters are rejected with 400 INVALID_PARAMS. The platform does not retry this call after an unknown outcome.

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
success boolean true on success
data.file object File in the chat folder; token-bearing URLs are nulled
data.file.id number Uploaded file ID; pass it in uploadIds when publishing
data.file.name string File name
data.file.size number File size in bytes
data.chatId number Chat ID
data.dialogId string Dialog ID; no messageId

Response example

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

Error response example

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

Errors

HTTP Code Description
400 INVALID_PARAMS, INVALID_CHAT_ID Invalid body, chat ID, or unexpected parameters
401 TOKEN_MISSING No Bitrix24 access tokens
403 SCOPE_DENIED, WRITE_BLOCKED_READONLY_KEY, BITRIX_ACCESS_DENIED Missing scope, write permission, or Bitrix24 access
413 PAYLOAD_TOO_LARGE JSON body exceeds 40 MiB; reduce the request
422 METHOD_NOT_YET_AVAILABLE, BITRIX_ERROR Method has not reached Bitrix24, or the Bitrix24 refused the file
429 LARGE_BODY_BACKEND_BUSY, QUEUE_TIMEOUT Retry according to Retry-After

Any errors[] item is a refusal even when the Bitrix24 responds HTTP 200. Named refusals can become 400 INVALID_PARAMS or 403 BITRIX_ACCESS_DENIED; generic 422 BITRIX_ERROR includes error.b24Code only when a code is recognized. The platform does not retry an upload after an unknown outcome.

Full list of common API errors — Errors.

See also