## Move a document subtree

`POST /v1/note/documents/:id/move`

Moves the document and all its descendants. An omitted collectionId keeps the current collection. An omitted or null parentId places the document at the root. The parent must belong to the target collection. Bitrix24 refuses cycles and moves that widen access.

Requires the note scope and a key with write access. Archived collections are read-only. Permissions are enforced by Bitrix24.

## Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` (path) | integer | yes | [GET /v1/note/documents/:id](/docs/note/documents/get) |
| `position` (body) | integer / null | no | Signed safe integer. Omitted/null: last position. |
| `collectionId` (body) | integer / null | no | Positive safe integer. [List collections](/docs/note/collections/list). Omitted/null: current. |
| `parentId` (body) | integer / null | no | Positive safe integer. [Document tree](/docs/note/collections/tree). Omitted/null: root. |

## Examples

### curl — personal key

```bash

curl -X POST https://vibecode.bitrix24.com/v1/note/documents/85/move \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"collectionId": 35, "position": -20}'

```

### curl — OAuth application

```bash

curl -X POST https://vibecode.bitrix24.com/v1/note/documents/85/move \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"collectionId": 35, "position": -20}'

```

### JavaScript — personal key

```javascript

const response = await fetch('https://vibecode.bitrix24.com/v1/note/documents/85/move', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({"collectionId": 35, "position": -20}),
})
const result = await response.json()
if (!response.ok) throw new Error(result.error.message)
console.log(result.data)

```

### JavaScript — OAuth application

```javascript

const response = await fetch('https://vibecode.bitrix24.com/v1/note/documents/85/move', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Content-Type': 'application/json', 'Authorization': 'Bearer USER_SESSION_TOKEN' },
  body: JSON.stringify({"collectionId": 35, "position": -20}),
})
const result = await response.json()
if (!response.ok) throw new Error(result.error.message)
console.log(result.data)

```

## Response fields

| Field | Type | Description |
|---|---|---|
| `success` | boolean | `true` |
| `data` | object | [GET /v1/note/documents/:id](/docs/note/documents/get) |

The response is read back after the move. If the read fails, the change may already have been saved: read the object again before retrying.

## Response example

```json

{
  "success": true,
  "data": {
    "id": 85,
    "collectionId": 35,
    "parentId": null,
    "title": "Return processing procedure",
    "markdown": "Steps for processing a product return",
    "position": 1000,
    "createdBy": 1373,
    "updatedBy": 1373,
    "createdAt": "2026-10-02T19:43:23Z",
    "updatedAt": "2026-10-02T19:43:24Z",
    "contentUpdatedAt": "2026-10-02T19:43:23Z",
    "isArchived": false,
    "isTrashed": false,
    "isOrphan": false
  }
}

```

## Error response example

400 — invalid path id:

```json

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "id must be a positive integer"
  }
}

```

## Errors

| HTTP | Code | Condition |
|---|---|---|
| 400 | `INVALID_PARAMS` | Invalid id, destination or body. |
| 401 | `MISSING_API_KEY` | Missing key. |
| 401 | `TOKEN_MISSING` | No Bitrix24 credentials. |
| 403 | `SCOPE_DENIED` | `note` |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | READONLY |
| 403 | `BITRIX_ACCESS_DENIED` | Bitrix24 access refusal, including writes to an archived collection. |
| 404 | `ENTITY_NOT_FOUND` | Object not visible or missing; document archived. |
| 422 | `BITRIX_ERROR` | Cycle, access widening or another business refusal. |
| 429 | `OPERATION_TIME_LIMIT` | Bitrix24 operation limit. |
| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 unavailable. |
| 503 | `BITRIX_TIMEOUT` | Bitrix24 timeout. |

[ All errors ](/docs/errors)

## See also

- [GET /v1/note/documents/:id](/docs/note/documents/get)

- [Note](/docs/note)