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
Parameterid Inpath Typenumber Requiredyes DescriptionFile ID. Get it via GET /v1/files

Request fields (body)

Field Type Required Description
FieldtargetFolderId Typenumber Requiredyes DescriptionDestination 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 application

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 application

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
Fieldsuccess Typeboolean Descriptiontrue on a successful move
Fielddata.id Typenumber DescriptionFile ID (does not change after the move)
Fielddata.name Typestring DescriptionFile name
Fielddata.code Typestring | null DescriptionSymbolic file code
Fielddata.folderId Typenumber DescriptionDestination folder ID — equals the supplied targetFolderId
Fielddata.storageId Typenumber DescriptionStorage ID
Fielddata.type Typestring DescriptionObject type — always "file"
Fielddata.deletedType Typenumber DescriptionDeletion status: 0 — active
Fielddata.globalContentVersion Typenumber DescriptionFile version counter
Fielddata.fileId Typenumber DescriptionInternal file ID in Bitrix24
Fielddata.size Typenumber DescriptionFile size in bytes
Fielddata.createdBy Typenumber DescriptionID of the user who created the file
Fielddata.updatedBy Typenumber DescriptionID of the user who performed the move
Fielddata.deletedBy Typenumber | null DescriptionID of the user who deleted the file; null — not deleted
Fielddata.createdAt Typestring DescriptionFile creation date (ISO 8601) — does not change
Fielddata.updatedAt Typestring DescriptionDate of the last change (ISO 8601)
Fielddata.deletedAt Typestring | null DescriptionDeletion date or null
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

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://vibecode.bitrix24.com/v1/files/9251/download",
    "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
HTTP400 CodeMISSING_PARAMS DescriptiontargetFolderId not provided
HTTP400 CodeINVALID_PARAMS DescriptiontargetFolderId is not a positive integer
HTTP400 CodeINVALID_ID DescriptionThe file id is not a positive integer
HTTP400 CodeOPERATION_FAILED DescriptionMoving between different storages is not supported — use POST /v1/files/:id/copyto
HTTP401 CodeTOKEN_MISSING DescriptionNo authorization tokens for the portal
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the disk scope
HTTP404 CodeENTITY_NOT_FOUND DescriptionFile with the given id not found
HTTP422 CodeBITRIX_ERROR DescriptionA file with the same name already exists in the target folder — rename the file via PATCH /v1/files/:id before moving
HTTP429 CodeRATE_LIMITED DescriptionRequest 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