Для AI-агентов: markdown этой страницы — /docs-content/note.md индекс документации — /llms.txt

База знаний 2.0

Программный доступ к Базе знаний 2.0 Битрикс24: базы знаний, документы с содержимым в Markdown и вложения к ним.

Скоуп: note | Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: X-Api-Key

Терминология. Сущность, которая в путях называется collection (/v1/note/collections), в интерфейсе Битрикс24 называется базой знаний. Идентификаторы путей остаются на collection.

Разделы документации

  • Базы знаний — создать, список, получить, переименовать, архивировать, удалить, дерево документов
  • Документы — создать, получить, обновить, архивировать, удалить, полнотекстовый поиск
  • Файлы — загрузить вложение и получить готовый фрагмент для вставки в документ

Доступ

Требуется скоуп note. Дополнительно действует контроль доступа Базы знаний: создание баз знаний доступно сотрудникам портала, изменение и удаление — пользователям с правом управления базой знаний, редактирование документа — пользователям с правом редактирования. Администратор портала имеет полный доступ. При нехватке прав API возвращает 403 BITRIX_ACCESS_DENIED.

Ключ в режиме «только чтение» получает 403 WRITE_BLOCKED_READONLY_KEY на любом методе, изменяющем данные. Чтение — список и получение базы знаний, дерево документов, получение и поиск документов, метаданные файла — доступно любому ключу.

OAuth-приложения добавляют заголовок Authorization: Bearer USER_SESSION_TOKEN вместе с X-Api-Key к каждому вызову.

Быстрый старт

Список доступных баз знаний:

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

Ответ содержит массив баз знаний в data и курсор следующей страницы в meta.nextCursor. Показаны основные поля. Полный список — Список баз знаний:

JSON 
{
  "success": true,
  "data": [
    { "id": 9, "name": "Документация продукта", "position": 100, "policyLevel": "private" }
  ],
  "meta": { "nextCursor": null }
}

Полный пример

Документ с картинкой. Вложение добавляется в два шага. Загрузка сохраняет файл, привязывает его к документу и возвращает готовый фрагмент assetMarkdown, но в содержимое его не вставляет. Чтобы вложение стало видимым, добавьте фрагмент в Markdown документа.

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

# 1. Документ (пустой) → запоминаем 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": "Архитектура"}' | jq -r '.data.id')

# 2. Файл (Base64) → запоминаем готовый фрагмент вложения
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. Вставляем фрагмент в содержимое документа
curl -s -X PATCH "$BASE/note/documents/$DID" \
  -H "X-Api-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d "{\"markdown\": \"# Архитектура\n\n$MD\", \"overwrite\": true}"

Справочник эндпоинтов

Метод Путь Bitrix24 метод Описание
POST /v1/note/collections note.collection.add Создать базу знаний
GET /v1/note/collections note.collection.list Список баз знаний
GET /v1/note/collections/:id note.collection.get Получить базу знаний
PATCH /v1/note/collections/:id note.collection.update Переименовать базу знаний
POST /v1/note/collections/:id/archive note.collection.archive Архивировать базу знаний
DELETE /v1/note/collections/:id note.collection.delete Удалить базу знаний
GET /v1/note/collections/:collectionId/documents note.document.tree.list Дерево документов базы знаний
POST /v1/note/documents note.document.add Создать документ
GET /v1/note/documents/:id note.document.get Получить документ
PATCH /v1/note/documents/:id note.document.update Обновить документ
POST /v1/note/documents/:id/archive note.document.archive Архивировать документ
DELETE /v1/note/documents/:id note.document.delete Удалить документ
GET /v1/note/documents/search note.document.search.list Поиск документов
POST /v1/note/documents/search note.document.search.list Поиск документов POST-запросом — алиас канонической GET-формы
POST /v1/note/documents/:documentId/files note.file.add Загрузить файл
GET /v1/note/documents/:documentId/files/:id note.file.get Получить метаданные файла

Коды ошибок

HTTP Код Когда
403 SCOPE_DENIED Ключу не хватает скоупа note
403 WRITE_BLOCKED_READONLY_KEY Ключ в режиме «только чтение» вызвал метод записи
403 BITRIX_ACCESS_DENIED Нет права на операцию с базой знаний или документом, либо база знаний архивирована и её пытаются переименовать
404 ENTITY_NOT_FOUND Объект не существует или база знаний удалена. Для методов записи над документом — также архивный документ или документ в корзине. Чтение архивных баз знаний и документов, а также документов в корзине работает: состояние видно по isArchived и isTrashed
502 BITRIX_UNAVAILABLE Битрикс24 недоступен

Полный список общих ошибок API — Ошибки.

Смотрите также