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

Move file

POST /v1/files/:id/moveto

Moves a file to another folder within the same storage. On success the folderId field in the response contains the ID of the target folder; the file's id, createdAt, and createdBy do not change.

Parameters

Parameter In Type Required Description
id path number yes File ID. Get it via GET /v1/files

Request fields (body)

Field Type Required Description
targetFolderId number yes Destination folder ID. Get it via GET /v1/folders

Examples

curl — personal key

Terminal 
curl -X POST \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"targetFolderId":649}' \
  https://vibecode.bitrix24.com/v1/files/9251/moveto

curl — OAuth app

Terminal 
curl -X POST \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"targetFolderId":649}' \
  https://vibecode.bitrix24.com/v1/files/9251/moveto

JavaScript — personal key

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/files/9251/moveto',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ targetFolderId: 649 }),
  }
)
const body = await res.json()
if (!body.success) throw new Error(body.error.code)
console.log('File moved, new folder:', body.data.folderId)

JavaScript — OAuth app

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/files/9251/moveto',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ targetFolderId: 649 }),
  }
)
const body = await res.json()

Response fields

Field Type Description
success boolean true on a successful move
data.id number File ID (does not change after the move)
data.name string File name
data.code string | null Symbolic file code
data.folderId number Destination folder ID — equals the supplied targetFolderId
data.storageId number Storage ID
data.type string Object type — always "file"
data.deletedType number Deletion status: 0 — active
data.globalContentVersion number File version counter
data.fileId number Internal file ID in Bitrix24
data.size number File size in bytes
data.createdBy number ID of the user who created the file
data.updatedBy number ID of the user who performed the move
data.deletedBy number | null ID of the user who deleted the file; null — not deleted
data.createdAt string File creation date (ISO 8601) — does not change
data.updatedAt string Date of the last change (ISO 8601)
data.deletedAt string | null Deletion date or null
data.downloadUrl string File download URL
data.detailUrl string URL of the file card in Bitrix24

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 9251,
    "name": "verify-move-test.txt",
    "code": null,
    "storageId": 1,
    "type": "file",
    "folderId": 649,
    "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:34:16.000Z",
    "deletedAt": null,
    "downloadUrl": "https://example.bitrix24.com/disk/downloadFile/34867/?...",
    "detailUrl": "https://example.bitrix24.com/company/personal/user/1/disk/file/verify-move-test.txt/"
  }
}

Error response example

422 — a file with the same name already exists in the target folder:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "A file with this name already exists (DISK_OBJ_22000)."
  }
}

Errors

HTTP Code Description
400 MISSING_PARAMS targetFolderId not provided
400 INVALID_PARAMS targetFolderId is not a positive integer
400 INVALID_ID The file id is not a positive integer
400 OPERATION_FAILED Moving between different storages is not supported — use POST /v1/files/:id/copyto
401 TOKEN_MISSING No authorization tokens for the portal
403 SCOPE_DENIED The key lacks the disk scope
404 ENTITY_NOT_FOUND File with the given id not found
422 BITRIX_ERROR A file with the same name already exists in the target folder — rename the file via PATCH /v1/files/:id before moving
429 RATE_LIMITED Request limit exceeded — wait 1-2 seconds and retry

Full list of common API errors — Error codes.

Known specifics

Identifier persistence. After the move, the file's id, createdAt, and createdBy do not change — all external references to the file by ID keep working.

See also

Copy file

POST /v1/files/:id/copyto

Creates a copy of the file in the specified folder. The original stays in place; the copy gets a new identifier.

Parameters

Parameter In Type Required Description
id path number yes ID of the file to copy. Get it via GET /v1/files

Request fields (body)

Field Type Required Description
targetFolderId number yes Destination folder ID. Get it via GET /v1/folders

Examples

curl — personal key

Terminal 
curl -X POST \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"targetFolderId": 649}' \
  https://vibecode.bitrix24.com/v1/files/9250/copyto

curl — OAuth app

Terminal 
curl -X POST \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"targetFolderId": 649}' \
  https://vibecode.bitrix24.com/v1/files/9250/copyto

JavaScript — personal key

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/files/9250/copyto',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ targetFolderId: 649 }),
  }
)
const body = await res.json()
if (!body.success) {
  console.error(body.error.code, body.error.message)
} else {
  console.log('Copy created, ID:', body.data.id)
}

JavaScript — OAuth app

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/files/9250/copyto',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ targetFolderId: 649 }),
  }
)
const body = await res.json()

Response fields

Returns the object of the created copy.

Field Type Description
success boolean true on a successful copy
data.id number ID of the created copy (differs from the original ID)
data.name string File name
data.code string | null System file code
data.storageId number Storage ID
data.type string Object type — always "file"
data.folderId number Destination folder ID
data.deletedType number Deletion type: 0 — not deleted
data.globalContentVersion number Global content version
data.fileId number Internal identifier of the file content
data.size number Size in bytes
data.createdBy number ID of the user who created the copy
data.updatedBy number ID of the user who updated the copy
data.deletedBy number | null ID of the user who deleted it. Always null for a new copy
data.createdAt string (ISO 8601) Copy creation date
data.updatedAt string (ISO 8601) Copy update date
data.deletedAt string | null Deletion date. Always null for a new copy
data.downloadUrl string Direct file download URL
data.detailUrl string URL of the file card in Bitrix24

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 9253,
    "name": "doc-copy-test.txt",
    "code": null,
    "storageId": 1,
    "type": "file",
    "folderId": 649,
    "deletedType": 0,
    "globalContentVersion": 1,
    "fileId": 34869,
    "size": 4,
    "createdBy": 1,
    "updatedBy": 1,
    "deletedBy": null,
    "createdAt": "2026-05-06T09:35:13.000Z",
    "updatedAt": "2026-05-06T09:35:13.000Z",
    "deletedAt": null,
    "downloadUrl": "https://...",
    "detailUrl": "https://..."
  }
}

Error response example

400 — targetFolderId not provided:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_PARAMS",
    "message": "targetFolderId is required."
  }
}

Errors

HTTP Code Description
400 MISSING_PARAMS Required targetFolderId parameter not provided
400 INVALID_PARAMS targetFolderId is not a positive integer
400 INVALID_ID The id in the path is not a positive integer
400 OPERATION_FAILED Bitrix24 returned an empty result — the copy was not performed
401 TOKEN_MISSING No authorization tokens found for the portal
403 SCOPE_DENIED The API key lacks the disk scope
422 BITRIX_ERROR A file with the same name already exists in the destination folder

Full list of common API errors — Error codes.

Known specifics

  • The copy gets a new ID. The original stays in its source folder unchanged. The copy identifier (the data.id field) does not match the original identifier — use data.id for further work with the copy.
  • Copying works between storages. Unlike the move operation (POST /v1/files/:id/moveto), copying is allowed even when the source file and the destination folder belong to different storages.
  • Name conflict. If a file with the same name already exists in the destination folder, the operation fails with a 422 error. Rename the original or choose a different folder.

See also