Concepts · Publications

Publications

A Publication is a headless destination. It owns a set of published documents, knows where they go live (a site and a section), organizes them with its own categories, and exposes them through a public read API plus a revalidation webhook. Author once in Compose; render anywhere.

Three orthogonal axes

Publishing in Esy is described by three independent ideas. Keeping them separate is what makes the same document renderable on many surfaces.

Axis	What it is	Example
`kind`	The universal document type. Independent of where it publishes.	essay, article
`publication`	The headless destination a document is filed into — the site, section, and webhook.	Esy Research, clip.art Learn
`category`	A publication-owned taxonomy for grouping its documents.	Policy, Energy

What a publication holds

Field	Meaning
`name`	Human label, e.g. “Esy Research”.
`slug`	Stable id used in public read URLs and the webhook payload.
`acceptedKinds`	Which document kinds may be filed here.
`siteUrl` + `sectionPath`	Where documents go live, e.g. https://esy.com + /research.
`revalidateUrl`	The consumer’s webhook Esy pings on publish/unpublish.
`isPublic`	Whether the publication is exposed through the public read API.

Public publications

Public publications (the ones served by the read API below) are provisioned by Esy. Any account can create private publications to organize its own documents; exposing one publicly is handled by the Esy team while the public surface is in early access.

The public read contract

Once a publication is public, consumers read its published documents with no authentication. The shape is a stable, additively-versioned DTO — this is the contract every consumer maps from.

GET /v1/publications/public/esy-research/articles/{slug}json

{
  "slug": "the-economics-of-desalination",
  "title": "The economics of desalination",
  "description": "Cost drivers, energy intensity, and where the curve bends.",
  "category": "policy",
  "categoryLabel": "Policy",
  "categories": [
    { "slug": "policy", "label": "Policy" },
    { "slug": "energy", "label": "Energy" }
  ],
  "kind": "article",
  "content": "<article>…</article>",
  "publishedAt": "2026-06-20T14:02:11.004Z",
  "tags": ["water", "energy"],
  "relatedSlugs": ["the-cost-of-carbon-capture"],
  "author": { "name": "Jane Rivera" }
}

See the Publications API for every endpoint, and the connect a consumer site guide for receiving and verifying revalidation webhooks.

How a document reaches a reader

An author files a document into a publication and assigns categories in Compose.
On publish, the document joins the publication’s public article list.
Esy POSTs the publication’s revalidateUrl so the consumer can refresh just the affected pages.
The consumer re-fetches the public read API and renders the new content.