#База знаний 2.0

⚠️ Методы в процессе раскатки — выходят в обновлении note 26.100.0. Доступны не на всех порталах Битрикс24. Если на вашем портале метод ещё не доступен, API вернёт 422 METHOD_NOT_YET_AVAILABLE — это не ошибка интеграции, а признак того, что обновление пока не приехало на портал.

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

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

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

#Эндпоинты

#Базы знаний — [подробнее](/docs/note/collections)

Метод	Назначение
`POST /v1/note/collections`	Создать базу знаний
`PATCH /v1/note/collections/:id`	Переименовать базу знаний
`POST /v1/note/collections/:id/archive`	Архивировать (каскадно по документам)
`DELETE /v1/note/collections/:id`	Удалить в корзину

#Документы — [подробнее](/docs/note/documents)

Метод	Назначение
`POST /v1/note/documents`	Создать документ (с опциональным Markdown)
`PATCH /v1/note/documents/:id`	Обновить заголовок и/или содержимое
`POST /v1/note/documents/:id/archive`	Архивировать документ с поддеревом
`DELETE /v1/note/documents/:id`	Удалить документ с поддеревом в корзину

#Файлы — [подробнее](/docs/note/files)

Метод	Назначение
`POST /v1/note/documents/:documentId/files`	Загрузить файл (Base64) и привязать к документу
`GET /v1/note/documents/:documentId/files/:id`	Метаданные файла и готовый фрагмент для вставки

#Доступ

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

Ключ в режиме «только чтение» получает 403 WRITE_BLOCKED_READONLY_KEY на любом методе, изменяющем данные. Чтение (GET /v1/note/documents/:documentId/files/:id) доступно и такому ключу.

#Типовой сценарий: документ с картинкой

Вложение добавляется в два шага. POST /v1/note/documents/:documentId/files сохраняет файл и привязывает его к документу, но не вставляет в содержимое. Чтобы вложение стало видимым, получите готовый фрагмент assetMarkdown через GET /v1/note/documents/:documentId/files/:id и добавьте его в Markdown документа через PATCH /v1/note/documents/:id.

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) → запоминаем 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. Готовый фрагмент вложения
MD=$(curl -s "$BASE/note/documents/$DID/files/$FID" \
  -H "X-Api-Key: YOUR_API_KEY" | jq -r '.data.assetMarkdown')

# 4. Вставляем фрагмент в содержимое документа
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}"

#Замечания

Формат документа. Если в POST /v1/note/documents передать непустой markdown, документ создаётся с готовым содержимым. Без markdown создаётся пустой документ для совместного редактирования. Передача markdown в PATCH /v1/note/documents/:id полностью заменяет содержимое.
Размер Markdown. Максимум 1 048 576 байт (1 МиБ). Превышение возвращает 422 BITRIX_ERROR с пояснением в error.message.
Каскадные операции. Архивирование базы знаний переводит все её документы в режим чтения. Удаление базы знаний перемещает её документы в корзину. Архивирование и удаление документа затрагивают всё его поддерево.
Восстановление из корзины выполняется только в интерфейсе Битрикс24 — отдельного метода восстановления в API нет.
OAuth-приложения к каждому вызову добавляют заголовок Authorization: Bearer USER_SESSION_TOKEN вместе с X-Api-Key.