Para agentes de IA: markdown desta página — /docs-content-en/note.md índice da documentação — /llms.txt

Os artigos da documentação estão disponíveis atualmente em inglês.

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 called 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: creating knowledge bases is available to Bitrix24 account employees, changing and deleting to users with the knowledge-base management right, editing a document to users with the edit right. The Bitrix24 account administrator has full access. When rights are insufficient, the API returns 403 BITRIX_ACCESS_DENIED.

A read-only key gets 403 WRITE_BLOCKED_READONLY_KEY on any method that changes data. Reading — listing and getting a knowledge base, the document tree, getting and searching documents, file metadata — is available to any key.

OAuth applications add the Authorization: Bearer USER_SESSION_TOKEN header together with X-Api-Key on 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:

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

Full example

A document with a picture. An attachment is added in two steps. Uploading saves the file and links it to the document but does not insert it into the content. To make the attachment visible, get the ready-to-insert assetMarkdown fragment and add it to the document 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 fileId
FID=$(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.id')

# 3. Ready-to-insert attachment fragment
MD=$(curl -s "$BASE/note/documents/$DID/files/$FID" \
  -H "X-Api-Key: YOUR_API_KEY" | jq -r '.data.assetMarkdown')

# 4. 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
404 ENTITY_NOT_FOUND The knowledge base, document, or file does not exist, was deleted, or was archived
502 BITRIX_UNAVAILABLE Bitrix24 is unavailable

Full list of general API errors — Errors.

See also