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

Documentation articles are currently available in English.

Knowledge Base 2.0

Programmatic access to Bitrix24 Knowledge Base 2.0: knowledge bases, documents with Markdown content, and their attachments.

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

Terminology. The entity named collection in paths (/v1/note/collections) is called a knowledge base in the Bitrix24 interface. Path identifiers remain collection.

Documentation sections

  • Knowledge bases — create, list, get, rename, archive, delete, document tree
  • Documents — create, get, update, archive, delete, full-text search
  • Files — upload an attachment and get a ready-to-insert fragment for the document

Access

The note scope is required. Knowledge Base access control also applies: any employee of the Bitrix24 account can create knowledge bases; changing and deleting a knowledge base requires permission to manage it; editing a document requires permission to edit it. The Bitrix24 account administrator has full access. Without sufficient permissions, the API returns 403 BITRIX_ACCESS_DENIED.

A read-only key gets 403 WRITE_BLOCKED_READONLY_KEY on any method that changes data. Read operations — listing and getting knowledge bases, the document tree, getting and searching documents, and file metadata — are available to any key.

OAuth applications add the Authorization: Bearer USER_SESSION_TOKEN header along with X-Api-Key to every call.

Quick start

List available knowledge bases:

Terminal 
curl https://vibecode.bitrix24.com/v1/note/collections \
  -H "X-Api-Key: YOUR_API_KEY"

The response contains an array of knowledge bases in data and the next-page cursor in meta.nextCursor. Only the main fields are shown. The full list is in Knowledge bases list:

JSON 
{
  "success": true,
  "data": [
    { "id": 9, "name": "Product documentation", "position": 100, "policyLevel": "private" }
  ],
  "meta": { "nextCursor": null }
}

Full example

A document with an image. An attachment is added in two steps. Uploading saves the file, links it to the document, and returns the ready-to-insert assetMarkdown fragment, but does not insert it into the content. To make the attachment visible, add the fragment to the document's Markdown.

Terminal 
BASE='https://vibecode.bitrix24.com/v1'

# 1. Document (empty) → remember the id
DID=$(curl -s -X POST "$BASE/note/documents" \
  -H "X-Api-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"collectionId": 42, "title": "Architecture"}' | jq -r '.data.id')

# 2. File (Base64) → remember the ready-to-insert attachment fragment
MD=$(curl -s -X POST "$BASE/note/documents/$DID/files" \
  -H "X-Api-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d "{\"fileName\": \"arch.png\", \"fileContent\": \"$(base64 -w0 arch.png)\"}" | jq -r '.data.assetMarkdown')

# 3. Insert the fragment into the document content
curl -s -X PATCH "$BASE/note/documents/$DID" \
  -H "X-Api-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d "{\"markdown\": \"# Architecture\n\n$MD\", \"overwrite\": true}"

Endpoint reference

Method Path Bitrix24 method Description
POST /v1/note/collections note.collection.add Create a knowledge base
GET /v1/note/collections note.collection.list List knowledge bases
GET /v1/note/collections/:id note.collection.get Get a knowledge base
PATCH /v1/note/collections/:id note.collection.update Rename a knowledge base
POST /v1/note/collections/:id/archive note.collection.archive Archive a knowledge base
DELETE /v1/note/collections/:id note.collection.delete Delete a knowledge base
GET /v1/note/collections/:collectionId/documents note.document.tree.list Knowledge base document tree
POST /v1/note/documents note.document.add Create a document
GET /v1/note/documents/:id note.document.get Get a document
PATCH /v1/note/documents/:id note.document.update Update a document
POST /v1/note/documents/:id/archive note.document.archive Archive a document
DELETE /v1/note/documents/:id note.document.delete Delete a document
GET /v1/note/documents/search note.document.search.list Search documents
POST /v1/note/documents/search note.document.search.list Search documents via POST — an alias of the canonical GET form
POST /v1/note/documents/:documentId/files note.file.add Upload a file
GET /v1/note/documents/:documentId/files/:id note.file.get Get file metadata

Error codes

HTTP Code When
403 SCOPE_DENIED The key lacks the note scope
403 WRITE_BLOCKED_READONLY_KEY A read-only key called a write method
403 BITRIX_ACCESS_DENIED No permission for the operation on the knowledge base or document, or the knowledge base is archived and you are trying to rename it
404 ENTITY_NOT_FOUND The object does not exist or the knowledge base is deleted. For write methods on a document — also when the document is archived or in the trash. Reading archived knowledge bases and documents, as well as documents in the trash, works: the state is visible in isArchived and isTrashed
502 BITRIX_UNAVAILABLE Bitrix24 is unavailable

Full list of general API errors — Errors.

See also