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

Upload file

POST /v1/files/upload

Uploads a file to Bitrix24 Drive. The contents are passed as Base64 in the JSON request body. To upload, you must specify a folder (folderId) or a storage (storageId).

Request fields

Field Type Required Description
Fieldfilename Typestring Requiredyes DescriptionFile name with extension, for example report.pdf. The name must be available in the destination folder
Fieldcontent Typestring Requiredyes DescriptionFile contents in Base64
FieldfolderId Typenumber Requiredconditional DescriptionDestination folder ID. Folder list: GET /v1/folders. Required if storageId is not specified
FieldstorageId Typenumber Requiredconditional DescriptionStorage ID (upload to root). Storage list: GET /v1/storages. Required if folderId is not specified

You must specify one of the two parameters: folderId or storageId.

Names in the examples are placeholders. Before uploading again, choose an available name, for example by adding a date and a unique suffix. Uploading under a name that is already taken does not replace the existing file.

Examples

curl — personal key

Terminal 
curl -X POST \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"folderId":27,"filename":"report.txt","content":"SGVsbG8gV29ybGQ="}' \
  https://vibecode.bitrix24.com/v1/files/upload

curl — OAuth application

Terminal 
curl -X POST \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"folderId":27,"filename":"report.txt","content":"SGVsbG8gV29ybGQ="}' \
  https://vibecode.bitrix24.com/v1/files/upload

JavaScript — personal key

javascript 
const content = Buffer.from('Hello World').toString('base64')

const res = await fetch('https://vibecode.bitrix24.com/v1/files/upload', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    folderId: 27,
    filename: 'report.txt',
    content,
  }),
})
const body = await res.json()
console.log(body.data.id, body.data.downloadUrl)

JavaScript — OAuth application

javascript 
const content = Buffer.from('Hello World').toString('base64')

const res = await fetch('https://vibecode.bitrix24.com/v1/files/upload', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    folderId: 27,
    filename: 'report.txt',
    content,
  }),
})
const body = await res.json()
console.log(body.data.id, body.data.downloadUrl)

Upload to storage root

If you need to upload a file to the storage root rather than to a folder, pass storageId instead of folderId. The storage ID is available in the id field from GET /v1/storages, and the root folder is in the rootFolderId field.

Terminal 
curl -X POST \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"storageId":1,"filename":"backup.txt","content":"SGVsbG8gV29ybGQ="}' \
  https://vibecode.bitrix24.com/v1/files/upload

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.id Typenumber DescriptionID of the created file
Fielddata.name Typestring DescriptionFile name
Fielddata.code Typestring | null DescriptionSymbolic file code
Fielddata.storageId Typenumber DescriptionID of the storage where the file resides
Fielddata.type Typestring DescriptionObject type — always "file"
Fielddata.folderId Typenumber DescriptionID of the folder where the file resides
Fielddata.deletedType Typenumber DescriptionDeletion type: 0 — not deleted
Fielddata.globalContentVersion Typenumber DescriptionFile content version
Fielddata.fileId Typenumber DescriptionFile ID in the internal Bitrix24 storage
Fielddata.size Typenumber DescriptionFile size in bytes
Fielddata.createdBy Typenumber DescriptionID of the user who created the file. List: GET /v1/users
Fielddata.updatedBy Typenumber DescriptionID of the user who last changed the file
Fielddata.deletedBy Typenumber | null DescriptionID of the user who deleted the file, or null if the file is not deleted
Fielddata.createdAt Typestring DescriptionCreation date and time (ISO 8601)
Fielddata.updatedAt Typestring DescriptionDate and time of the last change (ISO 8601)
Fielddata.deletedAt Typestring | null DescriptionDeletion date and time, or null if the file is not deleted
Fielddata.downloadUrl Typestring DescriptionVibecode API address that downloads the file, GET /v1/files/:id/download. Send the X-Api-Key header when you follow it
Fielddata.detailUrl Typestring DescriptionURL of the file card in Bitrix24

Response example

On a successful upload, the response is HTTP status 201 Created.

JSON 
{
  "success": true,
  "data": {
    "id": 9251,
    "name": "report.txt",
    "code": null,
    "storageId": 1,
    "type": "file",
    "folderId": 27,
    "deletedType": 0,
    "globalContentVersion": 1,
    "fileId": 34867,
    "size": 11,
    "createdBy": 1,
    "updatedBy": 1,
    "deletedBy": null,
    "createdAt": "2026-05-06T09:32:39.000Z",
    "updatedAt": "2026-05-06T09:32:39.000Z",
    "deletedAt": null,
    "downloadUrl": "https://vibecode.bitrix24.com/v1/files/9251/download",
    "detailUrl": "https://example.bitrix24.com/company/personal/user/1/disk/file/report.txt"
  }
}

Error response example

400 — filename and content not specified:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_PARAMS",
    "message": "filename and content (base64) are required."
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_PARAMS Descriptionfilename and content not provided, or neither folderId nor storageId specified
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not provided
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not recognized — no such key exists on the platform
HTTP401 CodeTOKEN_MISSING DescriptionAccess tokens for the Bitrix24 portal are unavailable
HTTP422 CodeBITRIX_ERROR DescriptionThe name is already taken in the destination folder. error.b24Code is DISK_OBJ_22000. Choose another name before retrying
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the disk scope
HTTP404 CodeENTITY_NOT_FOUND DescriptionFolder or storage with the given ID not found
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned an error while uploading the file
HTTP429 CodeRATE_LIMITED DescriptionRequest limit exceeded

Full list of common API errors — Errors.

Known specifics

Contents are passed as Base64. The file is encoded in Base64 and passed as a string in the content field. Passing a file via multipart/form-data is not supported.

Maximum size. The request body limit for this route is 70 MB. Since Base64 increases the size by about a third, that corresponds to a source file of roughly 50 MB — enough for a call recording or typical attachments. Bitrix24 additionally enforces its own Drive file-size cap: exceeding it returns 422 BITRIX_ERROR. Files in the hundreds of MB are not meant to be uploaded through this endpoint.

See also