content is omitted and tag_names is added — so list payloads stay compact.
Identifiers
string
required
Always
"article".uuid
required
Server-generated identifier. Stable for the lifetime of the article.
string
required
URL-safe handle. Lowercase letters, numbers, and dashes only (
/^[a-z0-9-]+$/), maximum 200 characters. Unique per organization (and per-language for translations) — reusing a slug already taken by another article in your org is rejected. You set this on create; you can change it via PATCH, but inbound deep links to the old slug will 404.Content
string
required
Human title. Indexed for search.
string
required
The source body — markdown is the canonical input. External image URLs are rehosted on write (see overview). Omitted from list payloads.
string | null
Plain-text mirror of
content used for retrieval, embeddings, and previews. Derived server-side from the markdown you send — you don’t supply it, and any value sent in the request body is ignored.string
required
ISO 639-1 two-letter language code for the primary body. Translations carry their own
language on the satellite resource.Supported codes:
en, ja, de, fr, ko, zh, nl, sv, es, it, no. Sending any other value returns invalid_payload. Defaults to en when omitted on create.Status & visibility
enum
required
Lifecycle state. One of:
draft— not indexed, not visiblepublished— indexed and surfaced according tovisibilityunpublished— taken down from public surfaces; embeddings removedarchived— soft-deleted; not indexed, hidden from UI
enum
required
Who can see the article when
status === "published". One of:public— KB site visitors and chatbotsinternal— authenticated org agents onlychatbot_only— surfaced to chatbots; not rendered in the KB UI
datetime | null
ISO-8601 timestamp of the first transition to
published. Auto-set by the server on that first publish and sticky thereafter — it is not re-stamped on later re-publishes, and stays set even after the article is unpublished or archived. null until the article has been published at least once.Indexing
enum
required
State of the embedding pipeline for this article. One of:
not_started— never enqueuedpending— queued, not yet picked upprocessing— embedding in flightindexed— embeddings written; article searchablefailed— pipeline error; the article is not searchable
article.indexed / article.indexing_failed webhooks to detect completion. The underlying error string is not surfaced via the API.datetime | null
ISO-8601 timestamp of the most recent successful index write.
null until the first index completes.Categorization
uuid | null
The knowledge base this article belongs to. Required on create — every new article must be scoped to a knowledge base. The id must belong to your organization; a foreign or nonexistent
knowledge_base_id is rejected. May be null on older articles created before this was enforced.uuid | null
The category (folder) this article sits inside.
null for articles that live at the root of a knowledge base. The id must belong to your organization; a foreign or nonexistent category_id is rejected. See Article Categories.Timestamps
datetime
required
ISO-8601 timestamp of insertion.
datetime
required
ISO-8601 timestamp of the most recent write.
List projection
List endpoints (GET /articles) drop content and add tag_names — the resolved tag names attached to the article. Use the detail endpoint to fetch the full body.
string[]
Resolved names of every tag assigned to the article. Only present on list responses.
Related articles
Relations are returned byGET /articles/{id}/relations. Each entry carries the related article’s id and resolved title — slugs aren’t included; use GET /articles/{relatedId} if you need the full record.