Архивы базы знаний через API

Для загрузки структуры документации в базу знаний проекта используйте ZIP с папками, Markdown и изображениями. Форматы, ограничения и режимы распознавания те же, что при загрузке через кабинет. Для изменения нужны права can_manage_knowledge_base, для проверки состояния — can_view_knowledge_base; API-токен храните на сервере интеграции.

Отправить архив

POST /api/knowledge-base/archive-imports?project_id=PROJECT_ID принимает multipart/form-data:

file — ZIP;
folder_id — папка назначения, необязательно;
duplicate_resolution — ask, rename или replace; по умолчанию ask;
locale — ru или en, по умолчанию ru;
image_recognition_mode — режим обработки изображений. Явно передайте none, если AI-распознавание запускать не нужно.

Обязателен заголовок Idempotency-Key. Сохраните его до отправки и используйте тот же ключ для повторения того же запроса после сетевого сбоя. Новый архив или другую настройку импорта отправляйте с новым ключом.

curl --fail-with-body \
  "https://api.senler.io/api/knowledge-base/archive-imports?project_id=$PROJECT_ID" \
  --header "Authorization: Bearer $SENLER_API_TOKEN" \
  --header "Idempotency-Key: $IMPORT_KEY" \
  --form "file=@documentation.zip" \
  --form "locale=ru" \
  --form "duplicate_resolution=ask" \
  --form "image_recognition_mode=none"

Ответ 202 Accepted означает, что архив принят, а не что материалы уже готовы. Сохраните id операции и проверяйте status_url. В одном проекте одновременно выполняется один импорт архива.

Дождаться результата

Состояние возвращает GET /api/knowledge-base/archive-imports/OPERATION_ID?project_id=PROJECT_ID&include_result=true:

receiving, pending, processing — передача или обработка продолжается; сведения о ходе находятся в progress;
awaiting_resolution — нужно разрешить конфликт имён;
completed — импорт завершён, результат находится в result;
failed — импорт не завершён, причина находится в error.

Если ответ на загрузку потерялся, сначала найдите операцию через GET /api/knowledge-base/archive-imports?project_id=PROJECT_ID&idempotency_key=IMPORT_KEY&include_result=true. Не создавайте новый импорт только из-за таймаута запроса.

При конфликте выполните PATCH /api/knowledge-base/archive-imports/OPERATION_ID/resolution?project_id=PROJECT_ID с JSON {"duplicate_resolution":"rename"} или {"duplicate_resolution":"replace"}. Используется уже переданный ZIP. replace заменяет конфликтующие материалы: перед выбором проверьте состав замены.

Если продолжать импорт не нужно, выполните DELETE /api/knowledge-base/archive-imports/OPERATION_ID?project_id=PROJECT_ID. Отмена доступна только в состоянии awaiting_resolution: сохранённый ZIP удаляется, а проект освобождается для следующего импорта. Успешный ответ — 204 No Content. Уже выполняющуюся обработку этим запросом остановить нельзя.

Проверяйте также result_is_current: true подтверждает, что результат всё ещё актуален; false означает, что после импорта его ресурсы изменились, исчезли или была активирована другая версия. Без запроса результата поле равно null. Старый ответ completed сам по себе не доказывает актуальность текущей базы.

Для проверки того же ZIP без ключа запроса используйте GET /api/knowledge-base/archive-imports/content. Передайте в query project_id, archive_sha256 (SHA-256 файла ZIP, 64 строчных шестнадцатеричных символа), duplicate_resolution, locale, image_recognition_mode и include_result=true. Укажите тот же folder_id, что при загрузке; отсутствие означает корень проекта. Поиск учитывает и содержимое, и настройки импорта. Ответ может указывать на ещё выполняющуюся операцию: считать материалы готовыми можно только при status: "completed" и result_is_current: true. 404 означает, что подходящий импорт не найден.

Обновить материалы целиком

Для фонового импорта в базу знаний проекта с image_recognition_mode: "none" файлы сначала подготавливаются, затем новая версия публикуется целиком. Прежняя версия остаётся доступна до успешной публикации. Ошибка подготовки не оставляет смесь старых и новых материалов. Это правило не распространяется на импорт с включённым AI-распознаванием или на документацию приложения.

GET /api/knowledge-base/archive-publications/capabilities?project_id=PROJECT_ID возвращает atomic_publication: true и quota_accounting: "net_replacement". Последнее означает проверку лимита по итоговому объёму хранилища после замены. Нельзя таким способом заменить папку с таблицами базы знаний или с вложенной отдельно опубликованной ZIP-папкой.

При успешной публикации в result.summary.publication находятся version_id, previous_version_id и activated_at. Сохраните их вместе с результатом операции. Готовые описания изображений из архива импортируются без нового AI-распознавания.

Восстановить сохранённую версию

Передайте сохранённый previous_version_id в POST /api/knowledge-base/archive-publications/VERSION_ID/activate?project_id=PROJECT_ID. Если он равен null, предыдущей сохранённой версии нет. Повторно передавать ZIP не требуется; новое распознавание изображений не запускается.

Восстановление доступно только для версии, которая ещё сохранена на сервере. 409 означает, что версия недоступна для восстановления либо папка изменена параллельно. 413 означает превышение лимита хранилища после восстановления. Повторная активация уже текущей версии не меняет данные.