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

Move folder

POST /v1/folders/:id/moveto

Moves a folder into another parent folder within the same storage. On success, the parentId field in the response holds the ID of the target folder. The id, createdAt, and createdBy fields do not change. Moving between different storages is not supported — use copyto.

Parameters

Parameter In Type Required Description
id path number yes Folder ID. Obtain via GET /v1/folders

Request fields (body)

Field Type Required Description
targetFolderId number yes Target folder ID. Obtain 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/folders/9303/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/folders/9303/moveto

JavaScript — personal key

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/folders/9303/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('Folder moved, new parent:', body.data.parentId)

JavaScript — OAuth application

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/folders/9303/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 Folder ID — unchanged after the move
data.name string Folder name
data.code string | null Symbolic code of the folder
data.parentId number Parent folder ID — equals the passed targetFolderId
data.storageId number Storage ID
data.type string Object type — always "folder"
data.realObjectId number Internal object ID
data.deletedType number Deletion status: 0 — active
data.createdBy number ID of the user who created the folder — unchanged
data.updatedBy number ID of the user who performed the move
data.deletedBy number ID of the user who deleted the folder. null — not deleted
data.createdAt string Creation date (ISO 8601) — unchanged
data.updatedAt string Last modification date (ISO 8601)
data.deletedAt string | null Deletion date or null
data.detailUrl string URL of the folder card in Bitrix24

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 9303,
    "name": "Documents",
    "code": null,
    "storageId": 1,
    "type": "folder",
    "realObjectId": 9303,
    "parentId": 649,
    "deletedType": 0,
    "createdAt": "2026-06-25T12:54:43.000Z",
    "updatedAt": "2026-06-25T12:54:43.000Z",
    "deletedAt": null,
    "createdBy": 1,
    "updatedBy": 1,
    "deletedBy": null,
    "detailUrl": "https://<portal>.bitrix24.com/company/personal/user/1/disk/path/Archive/Documents"
  }
}

Error response example

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

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

Errors

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

For the full list of common API errors, see Errors.

Known specifics

Identifier persistence. After the move, the folder's id, createdAt, and createdBy do not change — all external references to the folder by ID keep working. The folder moves together with all its nested content.

See also