Skip to main content

Pages

Pages are durable documents a space publishes outside its post feed: an about page, a code of conduct, documentation, or another long-lived resource. Two endpoints cover them:

  • GET /v1/spaces/{space}/pages — list a space's published pages.
  • GET /v1/spaces/{space}/pages/{page} — fetch one page.

Only enabled pages in a publicly resolvable space are served. A missing or private space, a missing page, and a disabled page all return the same 404 Not Found.

Listing a space's pages​

GET /v1/spaces/{space}/pages returns a cursor-paginated envelope ordered by sortOrder ascending, then id ascending:

curl 'https://api.dfos.com/v1/spaces/field-notes/pages?limit=20'

Each item is a lean navigation projection:

  • id — the stable page_... entity ID.
  • slug — the mutable URL alias.
  • title — the page title.
  • sortOrder — its position in the space's page navigation.
  • updatedAt — the last update time in ISO 8601 UTC.

The response has the standard items, nextCursor, previousCursor, and optional totalCount fields. Pass nextCursor back as after to move forward, or previousCursor as before to move backward:

curl 'https://api.dfos.com/v1/spaces/field-notes/pages?limit=20&after=eyJzb3J0T3JkZXIiOjAsImlkIjoicGFnZV84bTJxN3Y0ayJ9'

Treat cursors as opaque and keep limit constant while walking them. See Conventions.

Fetching a single page​

GET /v1/spaces/{space}/pages/{page} accepts either the page's stable id or its slug:

curl 'https://api.dfos.com/v1/spaces/field-notes/pages/page_8m2q7v4k'
curl 'https://api.dfos.com/v1/spaces/field-notes/pages/about'

Both addresses return the same body. Store id as the durable identifier; slug is a mutable alias and may change. A page ID used under the wrong space returns the same 404 Not Found as an unknown page.

The full page adds its markdown body, optional cover, and optional bodyMedia. Inline media remains in the markdown as attachment://<mediaId> tokens. Resolve each token by matching <mediaId> to the id of its bodyMedia entry.

Media URLs have the same two classes as post media:

  • Public images use permanent, unsigned CDN URLs and have no urlExpiresAt.
  • Private audio, video, and files use time-limited signed URLs and include urlExpiresAt.

Never persist a signed URL. Re-fetch the page after urlExpiresAt to obtain a fresh one. See Compatibility → Media URLs.