Articles in the Knowledge Base move through three statuses. Authors transition them via the buttons in The Editor; the status is also visible as a coloured badge on every article row of the admin landing, and as a plain Status: line in the editor header.
Primary status values
The kb_article.status column stores one of three string values, enforced by a CHECK constraint at the schema level.
DRAFT — grey badge. Visible in admin only. The default state for new articles: set automatically by Create draft on /admin/new, or by the agent API import endpoint when publish: false.
PUBLISHED — green badge. Visible on the public reader, in the chat-widget, and in admin. Set by clicking Publish in the editor, or by the agent API when publish: true. Publishing revalidates /, /a/[slug], and /admin.
ARCHIVED — amber badge. Visible in admin only. Set by clicking Archive in the editor (the button is only shown while the status is PUBLISHED) or by POST /api/kb/admin/articles/[id]/archive.
The pending-draft chip
A separate state lives alongside status: an article can have a draft stashed in the kb_article_draft table even while its public status remains PUBLISHED. This happens whenever an author edits a published article and clicks Save Draft without clicking Publish.
Amber draft pending chip — shown next to the Status: line in the editor header. The article has both a live published version and an unpublished draft. The next time you click Publish, the draft replaces the public version.
No chip — no pending draft. The editor body matches the stored version exactly.
The pending draft body sits in kb_article_draft.body_json. Publish deletes the draft row in the same transaction as the status update — that's how the chip clears immediately after publishing.
Status transitions
(no row) → DRAFT — Create draft, or agent import with publish: false. A kb_article row is created; nothing is published.
DRAFT → (no row) — Delete on the article's row in /admin, after confirming the prompt. The article, its draft, and its slug aliases are removed permanently in one transaction. Refused for PUBLISHED and ARCHIVED articles.
DRAFT → PUBLISHED — Publish. Body sanitised on write, draft row deleted, paths revalidated.
PUBLISHED → PUBLISHED + draft pending — Save Draft after edits. A kb_article_draft row is written; the public body is unchanged.
PUBLISHED + draft pending → PUBLISHED (chip cleared) — Publish. The draft body replaces the public body; the draft row is deleted.
PUBLISHED → ARCHIVED — Archive. The public reader returns 404 for /a/; the chat-widget hides the article.
ARCHIVED → PUBLISHED — Publish in the editor, or re-import via the agent API with publish: true. The article re-appears for readers.
Un-archiving needs no special button: open the archived article via Edit on /admin and click Publish. Publish always sets the status to PUBLISHED regardless of the current status. The slug is preserved, so old links keep working.
Visibility matrix
Which status reaches which reader surface.
Public reader (/, /a/, /f/) — DRAFT hidden; PUBLISHED visible; ARCHIVED hidden.
Chat-widget Help tab (folder tree, search, suggestions, article view) — DRAFT hidden; PUBLISHED visible; ARCHIVED hidden.
Admin landing (/admin) — all three visible, each with its badge. The Show chips All / Draft / Published narrow the article rows; there is no Archived-only chip, so archived rows appear under All.
Search API (/api/kb/search) — DRAFT excluded; PUBLISHED included; ARCHIVED excluded.
Public folder tree API (/api/kb/folders) — DRAFT excluded; PUBLISHED included; ARCHIVED excluded.
Related articles panel — DRAFT never appears as a target; PUBLISHED included; ARCHIVED excluded.
The asymmetry is deliberate: archives are almost the same as deletes from a reader's perspective, but the article stays in the database, the slug remains reserved (so a future publish under the same slug works), and managers can audit the historical content. Drafts, by contrast, have no history to protect, which is why they alone can be hard-deleted.
Related
Manage articles and folders — where status badges appear and how to trigger transitions.
The Editor — the buttons that change status.
The Knowledge Base — the reader surfaces affected by status.