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. Publications carry documents; run-produced artifacts ship through Outlets — a separate plane that can serve the same site (esy.com consumes both).

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.
`beehiivPublicationId` + API key	Optional email channel: articles can become Beehiiv drafts, per article and opt-in.
`isPublic`	Whether the publication is exposed through the public read API.

slug and sectionPath are different on purpose: the slug is a stable id (it appears in read URLs and the webhook payload), while sectionPath is the route segment on the consumer site (e.g. /learn). A consumer maps the slug to its own section path — it never puts the slug in the page URL.

The web destination and the newsletter are independent delivery channels: a publication can publish to a site, to email via Beehiiv, or both — a newsletter-only publication is simply one with the web fields left blank. Publishing to the web never emails anyone; sending is a separate, per-article, draft-first action.

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.