Skip to main content
Categories are returned as a flat list. The tree structure lives in parent_id — assemble it client-side when you need a nested view.

Fields

string
required
Always "article_category".
uuid
required
Server-generated identifier.
uuid | null
The knowledge base this category belongs to. Required on create — every new category must be scoped to a knowledge base. Must reference a knowledge base in your organization; a foreign or nonexistent id returns 422 "A referenced resource does not exist."
uuid | null
The parent category, or null if this is a root. When set, must reference a category in your organization; a foreign or nonexistent id returns 422 "A referenced resource does not exist." Trees of arbitrary depth are allowed; in practice keep it shallow.
string
required
Display name shown in the KB UI and category pickers.
string
required
URL-safe handle. Unique across the org.
string | null
Optional one-liner shown in the dashboard and on the public KB index.
string
required
Lucide-style icon handle. Drives the icon shown in navigation, breadcrumbs, and row chips. Defaults to "folder-closed" if you don’t set it on create.
Supported values: folder-closed, folder-open, book-open, file-text, help-circle, lightbulb, message-square, settings, star, zap, shield, globe, archive. Any other value returns invalid_payload.
integer
required
Position among siblings sharing the same parent_id. Lower comes first. Must be an integer — a non-integer value is rejected with invalid_payload. Re-order by PATCHing the sort_order field on every sibling that moves.
datetime
required
ISO-8601 timestamp of insertion.

Example

Building a tree from the flat list

The API returns categories flat. Construct a tree by indexing on id and grouping by parent_id.
For a single subtree, pass ?parent_id=<id> to get just the direct children. To enumerate a whole branch, fetch the full list once and walk the tree in memory — it’s almost always cheaper than recursive API calls.