CMS

• Sells as: the cms product (a product-scoped API key). This capability has no separate product-face contract — its public product route reuses the capability contract below; see the Edge route table's Product face row.

Shared GENERIC CMS engine. Threaded article comments with moderation + a store-authoritative collaborative-edit lock/session engine (multi-worker coherent — the correctness fix over the platform's per-process lock dict) + a user-submission submit/review FSM + (v1.1) a generic typed content model: caller-defined content types, localized immutable revisions, collections, image assets, a publish outbox and a public read of published content. Engagement state is keyed by a caller-supplied (article_id, user_id); everything is org-scoped (organization_id, I6). The engine still never fetches or owns vagary-platform's per-vertical news documents (I4/I5 — those stay platform domain).

• Group: Content & media
• Contract: contracts/cms/v1/openapi.yaml
• Console: Manage the cms product in the console →
• Runbook: operational checklist for cms — internal (Vagary Labs ops; not part of this public site): docs/runbooks/capability-operations.md#cms
• Public base: https://api.vagarylabs.com (the consolidated API gateway — one host, per-brand sibling api.<zone>)
• Auth: a product API key (vgk_…) issued from the console — Authorization: Bearer vgk_…
• Product face (customer-keyed):
  • https://api.vagarylabs.com/product/v1/cms/comments

Edge route table

The routes this capability actually serves on the public edge — live-synced from GET https://api.vagarylabs.com/product/v1/_meta/catalog (snapshot v1). The metric is the request-granularity billing counter; the scope is the key permission required.

Product face (customer-keyed)

Method	Path	Metric	Scope
POST	/product/v1/cms/comments	cms_operations	write

Endpoints

Method	Path	Summary
POST	/v1/comments	Add a threaded comment (nested reply via parent_id; max depth 5; max length 5000 chars).
GET	/v1/comments	List top-level comments (with nested replies attached) for an article, oldest first.
GET	/v1/comments/flagged	The admin moderation queue — status='flagged', non-deleted, newest first.
GET	/v1/comments/count	Non-deleted, non-rejected comment count for an article.
DELETE	/v1/comments/{comment_id}	Soft-delete a comment (admin any; a user only their own).
POST	/v1/comments/{comment_id}/moderate	Admin moderation — approve
GET	/v1/locks/{article_id}	Check the current edit-lock for an article (evicts an expired lock).
POST	/v1/locks/{article_id}	Acquire an edit lock (store-authoritative, atomic per org+article; granted to the holder or when expired).
DELETE	/v1/locks/{article_id}	Release an edit lock (only the holder may release).
POST	/v1/locks/{article_id}/force-release	Force-release a lock (admin).
GET	/v1/locks	All currently-held locks for the org (evicts expired).
POST	/v1/edit-sessions	Save an edit-session audit record (a held lock must be owned by this user).
GET	/v1/edit-sessions	Edit history for an article, newest first.
POST	/v1/submissions	Submit an article for editorial review (duplicate non-rejected URL refused).
GET	/v1/submissions	List submissions (optionally by status).
POST	/v1/submissions/{submission_id}/review	Approve or reject a pending submission.
GET	/v1/submissions/user/{user_id}	List a user's submissions.
GET	/v1/submissions/{submission_id}	Get a single submission by id.
POST	/v1/content/types	Define a content type (a JSON Schema 2020-12 for entry fields). A change appends an immutable new version; an identical definition returns the current version unchanged.
GET	/v1/content/types	The latest version of every content type in the org.
GET	/v1/content/types/{type_key}	One content type — the latest version, or a pinned version.
POST	/v1/content/entries	Create an entry of a type, optionally with its first revision (validated against the type schema).
GET	/v1/content/entries	List entries in the org.
GET	/v1/content/entries/{entry_id}	One entry with its workflow state, review, published pointer and latest revision per locale.
DELETE	/v1/content/entries/{entry_id}	Archive an entry. It stops being served; a pending review is closed. Revisions are kept. Publishing again restores it.
POST	/v1/content/entries/&#123;entry_id&#125;/revisions	Append an immutable revision for one locale. Refused while another user holds the edit lock on cms-entry:<entry_id>. Supersedes a pending review.
GET	/v1/content/entries/&#123;entry_id&#125;/revisions	Revisions of an entry, newest first.
POST	/v1/content/entries/&#123;entry_id&#125;/submit	Submit a draft for review. Opens a request in the submissions FSM, decided through /v1/submissions/{submission_id}/review.
POST	/v1/content/entries/&#123;entry_id&#125;/publish	Publish the latest revision of every locale atomically and write a cms.entry.published outbox event. An entry in review needs an approved review; a require_review type needs one to publish at all.
GET	/v1/content/collections	Collections in the org.
PUT	/v1/content/collections/&#123;collection_key&#125;	Create or update a collection's metadata.
GET	/v1/content/collections/&#123;collection_key&#125;/items	Every item of a collection in rank order, with whether each is live and inside its featured window.
PUT	/v1/content/collections/&#123;collection_key&#125;/items	Replace the ordered item set atomically and write a cms.collection.updated outbox event.
POST	/v1/content/assets	Upload a PNG, JPEG, WebP or GIF image of at most 1 MiB, content-addressed by SHA-256 (re-uploading the same bytes returns the existing asset).
GET	/v1/content/assets	Asset metadata in the org, newest first (never the bytes).
GET	/v1/content/public/&#123;organization_id&#125;/collections/&#123;collection_key&#125;	PUBLIC — a collection's live items in rank order, limited to published, non-archived entries inside their featured window, each in the requested locale with fallback.
GET	/v1/content/public/&#123;organization_id&#125;/assets/&#123;sha256&#125;	PUBLIC — image bytes, only while referenced by a published, non-archived entry. Immutable caching.
GET	/v1/content/public/&#123;organization_id&#125;/&#123;type_key&#125;/&#123;entry_key&#125;	PUBLIC — the published content of an entry. Locale fallback goes exact tag, shorter prefixes, then the entry's default locale. Drafts, entries in review, archived entries and unpublished locales are never served.
GET	/health	Liveness + store/tenancy posture (never the DSN).
GET	/metrics	Prometheus metrics.

Schemas

Error

Field	Type	Description
error	string	stable machine code (e.g. validation_error, not_found, max_depth)
reason	string	human-readable one-line explanation (no secrets/PII)
detail	object
request_id	string

CommentCreate

Field	Type	Description
article_id	string
user_id	string
content	string
parent_id	string	parent comment id for a nested reply
site_id	string	optional within-org sub-scope (site_ids array)
organization_id	string	only honored for a trusted first-party caller (anti-spoof)

CommentCreated

Field	Type	Description
comment_id	string
created	boolean

Comment

Field	Type	Description
comment_id	string
article_id	string
user_id	string
content	string
parent_id	string
depth	integer
status	string
deleted	boolean
site_ids	array
created_at	number	epoch seconds
replies	array

CommentList

Field	Type	Description
comments	array

CommentCount

Field	Type	Description
article_id	string
count	integer

CommentDelete

Field	Type	Description
user_id	string
is_admin	boolean
organization_id	string

DeleteResult

Field	Type	Description
deleted	boolean
reason	string

---

Generated by scripts/gen-capability-docs.py from contracts/cms/v1/openapi.yaml — the contract IS the source of truth; edit the contract, not this page. The Edge route table section is synced from the live edge catalog snapshot (v1) — re-sync with python3 scripts/sync-edge-catalog.py.