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), but translations do not auto-trigger — they need an explicit sync. And some things can’t be set from the API at all: role tagging, sections, KB settings, and Handbook procedures are editor-only.
This reference covers what happens after an API push and where the v1 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.
This is a design difference from the in-app editor, which embeds on every save. The API keeps saves fast and bulk pushes simple: the article is stored immediately, and retrieval catches up asynchronously in the background.
Translations
Translations are queued explicitly via the in-app Sync Translations button. They don’t auto-trigger on every API push. If your pipeline includes translation, the push script should call POST /api/kb/translations/sync after the bulk push (or you click it in the editor afterward).
What you can’t do from the API
- Role tagging isn’t yet exposed on the v1 surface. The push script can read
roles:from frontmatter but can’t apply them; do this in the in-app editor after a push. - Section management isn’t on v1. Sections are configured in the editor.
- Knowledge Base settings (branding, layout, theme) aren’t on the API.
- Handbook procedures have their own internal API that requires Supabase session auth, not API keys.
These are bounded — the doc-as-code pattern is for articles. Sections and branding are tenant-level layout decisions you set once.