Blog API

The public blog. Mounted at /api/blog. Shipped 2026-09-11 (SHAN-478 Phase 1).

This is the journal's mechanics without the journal's door. The journal is invite-only (SHAN-472): every route under /api/journal runs a membership check and 403s strangers. The blog runs none of it. Every GET below answers an anonymous request with no Authorization header at all.

Model#

A post is a slug plus an append-only chain of versions, exactly like a journal entry and its journal_versions. Two differences from the journal are worth reading before you write a client:

• Keyed by slug, not date. The journal is a diary: one entry per calendar day, date unique. A blog publishes many posts a day, so the natural key is a slug generated from the title. Slugs are stable forever; renaming a post does not move its URL.
• Titles are versioned. A journal entry is titled by its date. A blog post carries a real title, and a rename is an edit like any other, recorded in the revision history and restored by a revert.

status is one of published, draft, trashed. Only published posts are world-readable. A draft is visible to its author and to nobody else, on both the list and the detail route. A trashed post is visible to nobody, including its author. Publishing a draft re-dates publishedAt to the moment it went public, so a post you started three weeks ago does not appear already buried; re-saving an already-published post leaves publishedAt alone.

Reads (public, no auth)#

Pagination on /posts is a keyset cursor: cursor is the previous page's last publishedAt as an ISO 8601 datetime. Note the contrast with the Journal API, whose cursor is an ISO date (YYYY-MM-DD) because entries are keyed by day. Passing a bare date here is a 400, not a silent empty page. nextCursor is null on the last page. /posts/:slug/versions pages on versionNum instead, like the journal's.

Sending a valid Authorization header on any read only ever widens what you see, never narrows it: it adds your own drafts.

Writes (author only)#

All writes require entries:write and share PAT bucket blog-write (30/min). JWT browser sessions bypass the limit. Every mutation is author-scoped: a post you did not write is a 403 on edit and revert, and a 404 on delete.

The PATCH split#

One route, two behaviours, and the difference decides whether you need an If-Match header:

• title or content in the patch is a content edit. It mints a new version, bumps editCount, and requires If-Match: <currentVersionNum>. Omit it and you get a 428. A stale value gets a 409 carrying {currentVersionNum} so you can rebase and retry. Send only one of the two and the other is carried forward from the current version unchanged.
• tags or status alone is metadata. No version, no If-Match, no editCount bump.

A patch may mix both; the content edit runs first, and the metadata update follows.

Remember that If-Match has to be in the CORS allow-headers list to reach the handler from a browser. It already is, for the journal.

Example#

# Publish
curl -X POST https://shanebackend-production.up.railway.app/api/blog/posts \
  -H "Authorization: Bearer $PAT" -H "Content-Type: application/json" \
  -d '{"title":"On Slow Mornings","content":"# On Slow Mornings\n\n...","tags":["essays"]}'
# 201 {"post":{"slug":"on-slow-mornings",...},"currentVersionNum":1}

# Edit the body (concurrency-checked)
curl -X PATCH https://shanebackend-production.up.railway.app/api/blog/posts/on-slow-mornings \
  -H "Authorization: Bearer $PAT" -H "Content-Type: application/json" -H "If-Match: 1" \
  -d '{"content":"# On Slow Mornings\n\nRewritten."}'
# 200 {"post":{...},"currentVersionNum":2}

# Read it back with no credentials at all
curl https://shanebackend-production.up.railway.app/api/blog/posts/on-slow-mornings