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