## Move a document subtree

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

Moves the document and all descendants. Omitted collectionId keeps the current collection. Omitted or null parentId lands at the root. A parent must belong to the target collection. Bitrix24 refuses cycles and moves that widen sharing.

Requires note scope and a key permitting writes. Archived collections refuse writes. 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. |
| `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 mutation may already be saved: read the object before retrying.

```json

{
  "success": true,
  "data": {
    "id": 85,
    "collectionId": 35,
    "parentId": null,
    "title": "VIBE-PROBE MR-5082 document",
    "markdown": "VIBE-PROBE content",
    "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
  }
}

```

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, sharing 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)