لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/note.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

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
MethodPOST Path/v1/note/collections Bitrix24 methodnote.collection.add DescriptionCreate a knowledge base
MethodGET Path/v1/note/collections Bitrix24 methodnote.collection.list DescriptionList knowledge bases
MethodGET Path/v1/note/collections/:id Bitrix24 methodnote.collection.get DescriptionGet a knowledge base
MethodPATCH Path/v1/note/collections/:id Bitrix24 methodnote.collection.update DescriptionRename a knowledge base
MethodPOST Path/v1/note/collections/:id/archive Bitrix24 methodnote.collection.archive DescriptionArchive a knowledge base
MethodDELETE Path/v1/note/collections/:id Bitrix24 methodnote.collection.delete DescriptionDelete a knowledge base
MethodGET Path/v1/note/collections/:collectionId/documents Bitrix24 methodnote.document.tree.list DescriptionKnowledge base document tree
MethodPOST Path/v1/note/documents Bitrix24 methodnote.document.add DescriptionCreate a document
MethodGET Path/v1/note/documents Bitrix24 methodnote.document.list DescriptionList documents with continuation
MethodGET Path/v1/note/documents/:id Bitrix24 methodnote.document.get DescriptionGet a document
MethodPATCH Path/v1/note/documents/:id Bitrix24 methodnote.document.update DescriptionUpdate a document
MethodPOST Path/v1/note/documents/:id/archive Bitrix24 methodnote.document.archive DescriptionArchive a document
MethodDELETE Path/v1/note/documents/:id Bitrix24 methodnote.document.delete DescriptionDelete a document
MethodGET Path/v1/note/documents/search Bitrix24 methodnote.document.search.list DescriptionSearch documents
MethodPOST Path/v1/note/documents/search Bitrix24 methodnote.document.search.list DescriptionSearch documents via POST — an alias of the canonical GET form
MethodPOST Path/v1/note/documents/:documentId/files Bitrix24 methodnote.file.add DescriptionUpload a file
MethodGET Path/v1/note/documents/:documentId/files/:id Bitrix24 methodnote.file.get DescriptionGet file metadata

Error codes

HTTP Code When
HTTP403 CodeSCOPE_DENIED WhenThe key lacks the note scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY WhenA read-only key called a write method
HTTP403 CodeBITRIX_ACCESS_DENIED WhenNo permission for the operation on the knowledge base or document, or the knowledge base is archived and you are trying to rename it
HTTP404 CodeENTITY_NOT_FOUND WhenThe 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
HTTP502 CodeBITRIX_UNAVAILABLE WhenBitrix24 is unavailable

Full list of general API errors — Errors.

See also