Knowledge-base archives via API

To upload a documentation structure into a project's knowledge base, use a ZIP containing folders, Markdown and images. The formats, limits and recognition modes are the same as for cabinet uploads. Changes require can_manage_knowledge_base, and status checks require can_view_knowledge_base; keep the API token on your integration's server.

Send an archive

POST /api/knowledge-base/archive-imports?project_id=PROJECT_ID accepts multipart/form-data:

• file — the ZIP;
• folder_id — optional destination folder;
• duplicate_resolution — ask, rename or replace; defaults to ask;
• locale — ru or en; defaults to ru;
• image_recognition_mode — image processing mode. Explicitly pass none when AI recognition should not run.

The Idempotency-Key header is required. Save it before sending and reuse the same key when retrying the same request after a network failure. Use a new key for a new archive or different import settings.

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"

A 202 Accepted response means the archive was accepted, not that materials are ready. Save the operation id and check status_url. A project can have one archive import running at a time.

Wait for the result

Check status with GET /api/knowledge-base/archive-imports/OPERATION_ID?project_id=PROJECT_ID&include_result=true:

• receiving, pending, processing — transfer or processing is ongoing; progress contains its details;
• awaiting_resolution — a name conflict needs resolution;
• completed — import finished, with its result in result;
• failed — import did not finish, with the reason in error.

If the upload response was lost, first find the operation with GET /api/knowledge-base/archive-imports?project_id=PROJECT_ID&idempotency_key=IMPORT_KEY&include_result=true. Do not create a new import just because a request timed out.

For a conflict, call PATCH /api/knowledge-base/archive-imports/OPERATION_ID/resolution?project_id=PROJECT_ID with JSON {"duplicate_resolution":"rename"} or {"duplicate_resolution":"replace"}. It uses the ZIP already transferred. replace replaces conflicting materials: check the replacement scope before choosing it.

If the import is no longer needed, call DELETE /api/knowledge-base/archive-imports/OPERATION_ID?project_id=PROJECT_ID. Cancellation is available only in awaiting_resolution: the stored ZIP is removed and the project is released for the next import. Success returns 204 No Content. This request cannot stop processing already in progress.

Also check result_is_current: true confirms the result is still current; false means its resources changed, disappeared, or another version was activated after import. Without requesting the result, the field is null. An old completed response alone does not prove the current knowledge base is up to date.

To check the same ZIP without the request key, use GET /api/knowledge-base/archive-imports/content. Pass query parameters project_id, archive_sha256 (the ZIP file's SHA-256, 64 lowercase hexadecimal characters), duplicate_resolution, locale, image_recognition_mode and include_result=true. Use the same folder_id as in the upload; omitting it means the project root. The search matches both the content and import settings. The response may refer to an operation still running: consider materials ready only when status: "completed" and result_is_current: true. 404 means no matching import was found.

Update materials as a whole

For background imports into a project's knowledge base with image_recognition_mode: "none", files are prepared first and then the entire new version is published. The previous version stays available until publication succeeds. A preparation error does not leave a mix of old and new materials. This rule does not apply to imports with AI recognition enabled or to application documentation.

GET /api/knowledge-base/archive-publications/capabilities?project_id=PROJECT_ID returns atomic_publication: true and quota_accounting: "net_replacement". The latter means the storage limit is checked against the final size after replacement. This mode cannot replace a folder containing knowledge-base tables or a nested ZIP folder published separately.

After successful publication, result.summary.publication contains version_id, previous_version_id and activated_at. Save them with the operation result. Prepared image descriptions included in the archive are imported without new AI recognition.

Restore a retained version

Pass the saved previous_version_id to POST /api/knowledge-base/archive-publications/VERSION_ID/activate?project_id=PROJECT_ID. If it is null, there is no retained previous version. You do not need to resend the ZIP, and no new image recognition starts.

Restoring is available only for a version still retained on the server. 409 means the version is unavailable for restoration or the folder changed concurrently. 413 means restoring would exceed the storage limit. Activating the already current version again does not change data.