Releases

A release is a space's published body of work: a record, a book, a drop — a name, some dates, and the products, credits, media, and events gathered under it. This API serves the public release page and nothing behind it. A release that has not been published has no representation here at all.

• GET /v1/spaces/{space}/releases — a space's published release shelf.
• GET /v1/spaces/{space}/releases/{slug} — one release's public page.
• GET /v1/releases — public releases across every discoverable space.

The two space-scoped endpoints take any space identifier. The shelf returns a summary and the page returns that same summary plus the composition, so a field is never public on one and withheld on the other. The cross-space feed adds one thing, the space an item belongs to.

Listing a space's releases

GET /v1/spaces/{space}/releases is cursor-paginated (see Conventions), newest-published first.

curl 'https://api.dfos.com/v1/spaces/home/releases?limit=20'

A release appears only when it has been published and has a slug to be addressed by. Turning a space's public profile off takes its whole shelf and every release page down with it.

An empty list is a valid answer: a space with no releases and a space that has published none of the ones it has both return the same empty page.

Listing releases across spaces

GET /v1/releases returns every published release across every publicly-discoverable space, newest-published first, cursor-paginated.

curl 'https://api.dfos.com/v1/releases?limit=20'

Each item is the same shelf summary plus the space it belongs to — that space's id, did, domain, displayName, and avatarUrl. Pagination is the whole input surface: no filters, not state, not date.

The space gate here is public discovery, the same predicate as GET /v1/spaces, rather than direct lookup. A space that is directly addressable can still be absent from this feed, and a space turning its public site off drops every one of its releases out of it.

Fetching a release

GET /v1/spaces/{space}/releases/{slug} fetches one release page by its slug — the /r/{slug} segment on the space's site:

curl 'https://api.dfos.com/v1/spaces/home/releases/the-dark-forest-anthology-of-the-internet'

The slug is a mutable alias chosen by the space, and changing it breaks old links with no redirect. Store the id.

Release fields

Field	Value
id	The stable release identifier. Store this one.
slug	The mutable release-page alias.
name, shortDescription	Space-authored. shortDescription is the one-line blurb, or null.
longDescription	Long-form copy, page only, or null. Plain text whose newlines are significant; render with whitespace preserved.
state	upcoming, live, or ended — see State and dates. An open enum; treat an unrecognized value as an opaque string.
cover	The cover image, when the release has one. Always a public, permanently-hosted CDN image; this endpoint never emits a signed or expiring URL.
catalogNumber	The space's own catalog expression, free text, or null. Not unique — never a key.
location	A freeform place string, or null. Never geocoded, never a key.
publishedAt	When the release was published (ISO 8601 UTC). Both listings order by it, newest first.
releasesAt, closesAt	When the release opens and closes (ISO 8601 UTC), either or both null.
productCount	How many of the composed products are publicly purchasable.
products, credits, media, events	Page only — the composition. See What a release page composes.

State and dates

state is where the release sits between its two dates: upcoming before releasesAt, live once it is out, and ended past closesAt. An ended release stays readable — the page does not disappear when the window closes. Either date can be null, which means that edge is simply not set.

There is no draft state on this API. An unpublished release is a 404, not a state value, so nothing here tells you a space has unreleased work.

What a release page composes

Each list is filtered by its own domain's anonymous rule, so a release page can never be a side door onto something a caller could not already reach:

List	Contents
products	The composed products, in the space's curated order. A product with no public purchase page is absent and uncounted.
credits	Credit lines in credit order — a displayName and an optional role. Display text only; a credit never names an account.
media	The media wall in wall order, each entry an optional caption and a public asset. Entries backed by private media are omitted.
events	Public events attached to the release, soonest first, each addressed as (seriesId, recurrenceId). An event a caller may not see is simply absent.

When a release is not found

GET /v1/spaces/{space}/releases/{slug} returns one identical 404 Not Found for every failure: the space has no public profile, the space does not exist, the slug matches nothing, the slug belongs to a different space, or the release is not published. The shelf has one not-found mode, the space itself, with the same 404; beyond that it returns an empty page. See Content visibility.