Public read API
These unauthenticated routes expose active public publications and their published content. They return JSON except the RSS feed and XML sitemap.
Publication selector
Every route requires exactly one active publication selector:
{ "publication_slug": "engineering-notes" }
publication_id is also accepted. The public read API does not resolve browser hosts or paths; use /domain/resolve and /redirect/resolve where those lookups are needed.
Routes
| Route | Methods | Required fields | Optional fields | Success result |
|---|---|---|---|---|
/read/publication |
GET, POST |
Publication selector | — | public_publication. |
/read/home |
GET, POST |
Publication selector | category_slug, pagination |
Paginated public posts. |
/read/archive |
GET, POST |
Publication selector | year, month, pagination |
Archive facets and public posts. |
/read/search |
GET, POST |
Publication selector, q |
Pagination | Query and public posts. |
/read/categories |
GET, POST |
Publication selector | Pagination | Paginated categories. |
/read/category |
GET, POST |
Publication selector, category_slug |
Pagination | public_category and public posts. |
/read/tags |
GET, POST |
Publication selector | Pagination | Paginated tags. |
/read/tag |
GET, POST |
Publication selector, tag_slug |
Pagination | public_tag and public posts. |
/read/authors |
GET, POST |
Publication selector | Pagination | Paginated authors. |
/read/author |
GET, POST |
Publication selector, author_slug |
Pagination | public_author and public posts. |
/read/post |
GET, POST |
Publication selector, post_slug |
One of tag_slug or author_slug to scope adjacent-post navigation |
public_post. |
/read/page |
GET, POST |
Publication selector, page_slug |
— | public_page. |
/read/feed |
GET, POST |
Publication selector | site_url, post_path_prefix, limit |
RSS 2.0 XML. |
/read/sitemap |
GET, POST |
Publication selector | site_url, post_path_prefix, page_path_prefix |
XML sitemap. |
Public list routes use the pagination contract in the service guide. Lists include only published, public, unarchived posts; posts under inactive categories are also excluded. limit defaults to 50 and is capped at 200 for these JSON lists.
Publication and content reads
curl -sS https://api.blog.service.m7.org/v1/read/post \
-H 'Content-Type: application/json' \
-d '{"publication_slug":"engineering-notes","post_slug":"release-notes"}'
{
"status": 1,
"comment": "post loaded",
"data": {
"public_post": {
"slug": "release-notes",
"title": "Release notes",
"excerpt": "A summary.",
"body": "<h1>Release notes</h1>",
"body_format": "html",
"source_body_format": "markdown",
"visibility": "public",
"published_at": "2026-08-19 00:00:00.000000",
"category": { "slug": "updates", "name": "Updates" },
"tags": [{ "slug": "release-notes", "name": "Release Notes" }],
"authors": [{ "slug": "ada-lovelace", "name": "Ada Lovelace" }]
},
"prev_post": {
"slug": "earlier-in-the-list",
"title": "A newer post",
"excerpt": "A summary.",
"published_at": "2026-08-20 00:00:00.000000",
"category": { "slug": "updates", "name": "Updates" }
},
"next_post": {
"slug": "later-in-the-list",
"title": "An older post",
"excerpt": "A summary.",
"published_at": "2026-08-18 00:00:00.000000",
"category": { "slug": "updates", "name": "Updates" }
}
}
}
/read/post and /read/page return rendered HTML in body; source_body_format tells whether the stored body was Markdown or HTML. They permit published public and unlisted content, but not private content. Draft, review, scheduled, archived, disabled-publication, and inactive-category content returns 404.
Both detail models include editor_notes, ordered by revision date, newest
first. Each entry contains plain-text text, the original revision_at, and
the actual note added_at and updated_at. Consumer applications should
render note text as escaped text and distinguish the revision date from the
note's later addition or edit. Only the latest nonempty note for each saved
revision is included. Cleared notes, private autosaves, prior note text, actor
identifiers, and revision snapshots are excluded. Public lists and navigation
summaries do not include notes.
/read/post also returns prev_post and next_post navigation summaries. They follow the public archive order, newest first: prev_post is the immediately newer public post and next_post is the immediately older public post. Either field is null when no matching public post exists. Navigation summaries include only slug, title, excerpt, published_at, and category; they never include the post body or media. They only consider published, public, unarchived posts in active categories. With one optional tag_slug or author_slug, navigation is limited to posts assigned to that tag or author; the selected tag or author must belong to the publication and be assigned to the requested post. Supplying both selectors returns 400.
Lists, archives, and search
/read/home accepts category_slug to select one active category. /read/archive accepts year from 1000 through 9998 and, only with year, month from 1 through 12. It returns archive and archive_periods alongside the normal paginated posts.
/read/search requires string q: one to 120 characters and at most eight distinct terms. All terms must match a post title, excerpt, or body. The result's query is the normalized query; results are ordered by relevance and then published date.
Each public post summary includes slug, title, nullable excerpt, nullable featured_media_id, nullable featured_media, nullable category, and ordered tags and authors. Public categories, tags, and authors include a post_count. Category summaries also include description, nullable summary, and optional featured media. Public author summaries include bio, external_url, and socials.
Feed and sitemap
/read/feed streams application/rss+xml; charset=UTF-8; /read/sitemap streams application/xml; charset=UTF-8. Both need a canonical site URL. Send site_url as an absolute http or https URL without a query string or fragment, or omit it to use a verified publication domain.
{
"publication_slug": "engineering-notes",
"site_url": "https://notes.example.com",
"post_path_prefix": "/posts",
"page_path_prefix": ""
}
If no site_url is supplied and the publication has no verified domain, these routes return 422. Path prefixes are optional, must be path-only values, and default to /posts for feed post links, /posts for sitemap post links, and an empty path for sitemap page links. Feed limit defaults to 50 and is capped at 100.