Categories

Categories are publication-scoped primary groupings for posts. A post can have one category, set through /post/save. Active categories with visible posts are available through the public category routes.

Authentication

All routes require a bearer token and the stated publication capability. Use a publication selector for lists and creates. An existing category_id identifies the publication; an accompanying selector must match.

Routes

Route	Methods	Capability	Required input	Optional input and behavior	Success result
/category/list	GET, POST	taxonomy.list	Publication selector	Pagination	Paginated categories.
/category/get	POST	taxonomy.list	category_id, or publication selector plus slug	—	category.
/category/save	POST	taxonomy.save	Create: publication selector and name; update: category_id	name, slug, description, summary, active, featured_media_id, seo, metadata	Saved category.
/category/merge	POST	taxonomy.merge	source_category_id, target_category_id	—	Merge result.
/category/delete	POST	taxonomy.delete	category_id	Matching publication selector	Deleted category.

Category object

{
  "category_id": "CATEGORY_UUID",
  "publication_id": "PUBLICATION_UUID",
  "slug": "release-notes",
  "name": "Release notes",
  "description": "Product release announcements.",
  "summary": "Release notes and deployment announcements.",
  "active": true,
  "featured_media_id": "MEDIA_UUID",
  "seo": null,
  "metadata": null
}

Save a category

Field	Required	Type	Description
category_id	No	UUID	Updates this category. Omit to create.
publication_id / publication_slug	Required on create	UUID / String	Selects the publication.
name	Required on create	String	Display name. Omit it on update to retain the stored value.
slug	No	String	Unique in the publication. Omit or send an empty value to derive it from name.
description	No	String or null	Longer category copy.
summary	No	String or null	Short listing text, at most 280 characters.
active	No	Boolean	Defaults to true when creating.
featured_media_id	No	UUID or null	Ready media from this publication.
seo, metadata	No	Object, Array, or null	Integration-defined JSON data.

{
  "publication_slug": "engineering-notes",
  "name": "Release notes",
  "summary": "Release notes and deployment announcements.",
  "active": true
}

active: false removes the category and posts assigned to it from public reads without changing post lifecycle state. /category/merge moves all source-category posts to the target category and removes the source. Delete is permanent and returns 409 while posts still use the category.