Knowledge Baseadvanced

KB API Sync Behavior and Limits

After an API push: embeddings rebuild automatically within ~10 minutes, translations run automatically every 15 minutes, and sections stay editor-only.

3 min read

KB API Sync Behavior and Limits

When you push an article via the KB API, embeddings rebuild automatically in the background (allow up to about 10 minutes), and translation sync runs automatically every 15 minutes. Active non-default languages can be translated automatically, and enabling a language can consume AI credits. Some things can’t be set from the KB article sync API at all: sections and some layout-builder settings.

This reference covers what happens after an API push and where the /api/v1/kb/* article sync surface ends. For the overall pattern, see Doc-as-code with the KB API.

Embeddings

Embeddings are marked for rebuild by the API push, then processed by a background scheduler. They typically update on the next scheduler cycle, but allow up to about 10 minutes for the article to appear in retrieval after pushing.

The in-app editor behaves the same way: it also marks the article for embedding and lets the same scheduler drain it. The API keeps saves fast and bulk pushes simple: the article is stored immediately, and retrieval catches up asynchronously in the background.

Translations

Translation sync runs automatically every 15 minutes and picks up articles changed since the last run, including API pushes, so the push script doesn’t need to trigger it. The only manual control is Re-translate all in the Translation Sync card, and only superadmins see it. POST /api/kb/translations/sync is an in-app route that takes a signed-in session, not an API key.

Separately, active non-default languages can be translated automatically. Enabling a language may start translation work for that language and can consume AI credits, so only enable languages you intend to support.

What you can’t do from the API

  • Role definition management isn’t on v1: /api/v1/kb/roles is read-only, so creating and renaming roles stays in the editor. Applying roles to an article is supported through the dedicated GET /api/v1/kb/articles/:id/roles and PUT /api/v1/kb/articles/:id/roles flow.
  • Section management isn’t on v1. Sections are configured in the editor.
  • Public portal look-and-feel settings are not part of the article push API. Branding, theme, and related portal settings are managed through /api/v1/kb/settings, with separate multipart upload endpoints for the logo, favicon, and share image.
  • Layout builder fields layoutConfigV3 and templateConfig still aren’t API-settable.
  • Handbook procedures aren’t part of the /api/v1/kb/* article sync surface. If you’re reading Handbook procedures, categories, or access rules, use the supported /api/v1/handbook* endpoints instead. In multi-Handbook tenants, include or select the intended handbook so reads don’t fall back to the default partition.

These are bounded — the doc-as-code pattern is for articles. Sections and role definition management stay outside the article push flow, while portal look-and-feel is handled through the KB settings API.

See also

Tags

Reference
Back to Knowledge Base