# 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:

```json
{ "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](https://m7.org/docs/api/api.blog.service.m7.org/README.md#pagination). 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

```bash
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"}'
```

```json
{
  "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.

```json
{
  "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`.
