REST API модуля «База знаний»

Справочник REST-методов модуля ithive.knowledgebase для интеграций, входящих вебхуков и AI-агентов.

Базовый URL

https://{портал}/rest/{user_id}/{webhook_code}/{method}.json

Пример:

https://76569.dev.wehive.digital/rest/1/{webhook_code}/knowledgebase.article.list.json

Scope и аутентификация

  • Scope: knowledgebase
  • Аутентификация: входящий вебхук Bitrix24 с правом scope knowledgebase или OAuth/сессия авторизованного пользователя
  • Все методы knowledgebase.* требуют авторизованного пользователя REST. Без авторизации — ошибка UNAUTHORIZED.

Авторизация ≠ право на операцию: наличие вебхука само по себе не даёт, например, право создавать статьи или удалять разделы.

Права доступа

Права проверяются через IblockRights — фасад над правами инфоблока Базы знаний (задачи element_read, element_edit, element_delete, section_edit, section_element_bind, iblock_rights_edit и legacy-буквы W/X).

Сводка по группам методов

Группа методов Кто может (как в коде)
article.list Авторизованный; список строится с учётом прав инфоблока на чтение элементов
article.get Чтение через Post::getById; при отсутствии доступа — ACCESS_DENIED или ARTICLE_NOT_FOUND
article.add IblockRights::canBindElementToSection для каждого раздела привязки
article.update, article.delete, article.deletePermanent canEditElement / canDeleteElement
article.clearTrash Авторизованный (массовая очистка корзины через TrashService::purge())
article.getVersions element_read или canEditElement
article.deleteVersion, article.restoreVersion Логика Post::deleteVersion / Post::restoreVersion
article.incrementView element_read на статью
section.* canAddSubsectionInSection, canEditSection, canEditIblockRights (для корневых разделов)
comment.* element_read на статью; getFeed — только темы статей, доступных на чтение
hash.getByElement element_read
hash.create, hash.setActive, hash.delete canEditElement; публичная ссылка не запрещена модулем и статьёй

В шапках отдельных методов формулировка «Кто может вызывать» даёт краткий итог по коду; детали — в этом разделе.

Формат ответа

Внутренний конверт модуля (в result обёртки Bitrix REST):

Поле Описание
result Данные или null при ошибке
total Количество записей (для list-методов; в webhook часто на верхнем уровне Bitrix)
next Смещение следующей страницы или null
error null или { code, message, details }

Пагинация

Для list-методов:

Параметр По умолчанию Описание
limit 50 Размер страницы, максимум 500
offset 0 Смещение
fetchAll false Вернуть все записи одним ответом. Защитный лимит 5000; при превышении — FETCH_ALL_LIMIT_EXCEEDED
filter - Mongo-style фильтр ($eq, $in, $gte, …)

Пакетные вызовы

Отдельного метода knowledgebase.batch нет. Несколько knowledgebase.* за один HTTP-запрос — штатный batch Битрикс24 (/rest/{user_id}/{webhook_code}/batch.json).

Идентификаторы в параметрах

Сущность Основной параметр Алиасы
Статья id articleId, elementId
Раздел id sectionId
Публичная ссылка elementId —
Комментарии articleId —

Поиск и фильтры статей

  • По умолчанию article.list возвращает только активные статьи (ACTIVE = Y).
  • Поиск по названию и тексту: filter[search] или top-level параметр search (если search не задан в filter).
  • Поля Mongo-фильтра: id, name, sectionId, active, createdBy, modifiedBy.

Фильтр разделов

section.list загружает дерево разделов и фильтрует в памяти. Поля: id, name, depth, parentId, left, right, count.

Корзина статей

Массовая очистка — метод knowledgebase.article.clearTrash. Период задаётся параметром olderThanDays (алиасы: days, period, OLDER_THAN_DAYS, DAYS, PERIOD):

Значение Поведение
параметр не передан, пустая строка, "all", 0 или любое <= 0 Очистить всю корзину
30, 90, 180, 360 Окончательно удалить статьи, помещённые в корзину не менее N дней назад (как в UI «Очистить корзину»)

Отдельного REST-метода для счётчиков по периодам нет — выбор периода передаётся в clearTrash.

Что отсутствует в текущем коде

  • knowledgebase.schema — служебного метода схемы для AI (аналог helpdesk.schema) не реализовано

Разделы справочника

Раздел Описание
Статьи article.*
Разделы section.*
Комментарии comment.*
Публичные ссылки hash.*
Коды ошибок Полный перечень

Всего методов в данном справочнике: 23.

Предыдущая
Установка, обновление и удаление модуля
Следующая
Коды ошибок