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

Documents

Knowledge Base 2.0 documents are pages with Markdown content, organized into a tree inside a knowledge base. This section collects the operations for creating, reading, updating, archiving, deleting, and full-text searching documents.

Scope: note | Base URL: https://vibecode.bitrix24.com/v1 | Authorization: X-Api-Key

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
Parameterid (path) Typeinteger Requiredyes DescriptionGET /v1/note/documents/:id
Parameterposition (body) Typeinteger / null Requiredno DescriptionSigned safe integer. Omitted/null: last position.
ParametercollectionId (body) Typeinteger / null Requiredno DescriptionPositive safe integer. List collections. Omitted/null: current.
ParameterparentId (body) Typeinteger / null Requiredno DescriptionPositive safe integer. Document tree. Omitted/null: root.

Examples

curl — personal key

Terminal 

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

Terminal 

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
Fieldsuccess Typeboolean Descriptiontrue
Fielddata Typeobject DescriptionGET /v1/note/documents/:id

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
HTTP400 CodeINVALID_PARAMS ConditionInvalid id, destination or body.
HTTP401 CodeMISSING_API_KEY ConditionMissing key.
HTTP401 CodeTOKEN_MISSING ConditionNo Bitrix24 credentials.
HTTP403 CodeSCOPE_DENIED Conditionnote
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY ConditionREADONLY
HTTP403 CodeBITRIX_ACCESS_DENIED ConditionBitrix24 access refusal, including writes to an archived collection.
HTTP404 CodeENTITY_NOT_FOUND ConditionObject not visible or missing; document archived.
HTTP422 CodeBITRIX_ERROR ConditionCycle, access widening or another business refusal.
HTTP429 CodeOPERATION_TIME_LIMIT ConditionBitrix24 operation limit.
HTTP502 CodeBITRIX_UNAVAILABLE ConditionBitrix24 unavailable.
HTTP503 CodeBITRIX_TIMEOUT ConditionBitrix24 timeout.

All errors

See also