База знаний 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 к каждому вызову.

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

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

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

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

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

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

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

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}"

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

Коды ошибок

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

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

• Базы знаний
• Документы
• Файлы