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
Parameterid Inpath Typenumber Requiredyes DescriptionFolder ID. Obtain via GET /v1/folders

Request fields (body)

Field Type Required Description
FieldtargetFolderId Typenumber Requiredyes DescriptionTarget 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
Fieldsuccess Typeboolean Descriptiontrue on a successful move
Fielddata.id Typenumber DescriptionFolder ID — unchanged after the move
Fielddata.name Typestring DescriptionFolder name
Fielddata.code Typestring | null DescriptionSymbolic code of the folder
Fielddata.parentId Typenumber DescriptionParent folder ID — equals the passed targetFolderId
Fielddata.storageId Typenumber DescriptionStorage ID
Fielddata.type Typestring DescriptionObject type — always "folder"
Fielddata.realObjectId Typenumber DescriptionInternal object ID
Fielddata.deletedType Typenumber DescriptionDeletion status: 0 — active
Fielddata.createdBy Typenumber DescriptionID of the user who created the folder — unchanged
Fielddata.updatedBy Typenumber DescriptionID of the user who performed the move
Fielddata.deletedBy Typenumber DescriptionID of the user who deleted the folder. null — not deleted
Fielddata.createdAt Typestring DescriptionCreation date (ISO 8601) — unchanged
Fielddata.updatedAt Typestring DescriptionLast modification date (ISO 8601)
Fielddata.deletedAt Typestring | null DescriptionDeletion date or null
Fielddata.detailUrl Typestring DescriptionURL 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
HTTP400 CodeMISSING_PARAMS DescriptiontargetFolderId was not passed
HTTP400 CodeINVALID_PARAMS DescriptiontargetFolderId is not a positive integer
HTTP400 CodeINVALID_ID DescriptionFolder id is not a positive integer
HTTP400 CodeOPERATION_FAILED DescriptionMoving between different storages is not supported — use POST /v1/folders/:id/copyto
HTTP401 CodeTOKEN_MISSING DescriptionNo authorization tokens for the portal
HTTP403 CodeSCOPE_DENIED DescriptionThe key is missing the disk scope
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo folder found with the given id
HTTP422 CodeBITRIX_ERROR DescriptionA folder with this name already exists in the target folder — rename it via PATCH /v1/folders/:id before moving
HTTP429 CodeRATE_LIMITED DescriptionRequest 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