Journal API

The collaborative wiki-journal at /journal. Mounted at /api/journal. Invite-only: every endpoint below, reads included, requires journal membership. Verified against production 2026-09-10.

Semantics you must know first#

• The journal is private. Every /api/journal route except /access/* and GET /images/:id returns 403 Journal access required unless the caller is a member. See Access below for how to get in.
• One entry per calendar date, site-wide. The first poster becomes the permanent author.
• Entry bodies are append-only. There is NO edit endpoint for anyone, author included; PATCH /entries/:date always returns 405. Content changes only via appends, approved suggestions, or revert.
• Authors append; non-authors suggest. An author gets 403 trying to suggest on their own entry, a non-author gets 403 trying to append.
• Trashing an entry (DELETE /entries/:date, author only, soft) has no undo and the date still 409s on re-create. Do not create test entries on dates you care about.
• Versions are immutable forever. Appends are not (changed 2026-09-11): the author can PATCH or DELETE their own appends, so a duplicate post is fixable. The delete is soft — the append stops rendering, stops matching ?q= search, and stops counting toward appendCount, but the row survives for audit. Comments are the only hard delete.
• Every mutation is logged to a member-visible audit trail. See Activity feed below: if you write through this API under a PAT, your token name shows up next to the action.

Quickstart#

B=https://shanebackend-production.up.railway.app
# needs scope entries:write
curl -X POST $B/api/journal/entries \
  -H "Authorization: Bearer $PAT" -H "Content-Type: application/json" \
  -d '{"date":"2026-09-01","content":"# Title\n\nGFM markdown body..."}'
# 201 {entry, currentVersionNum: 1} | 409 date taken

Endpoints#

Reads (members only, like everything else here):

Writes:

The two If-Match writes (revert, suggestion approve) take the version number as a plain integer, seeded from currentVersionNum on GET /entries/:date. From a browser, send it as X-If-Match (SHAN-489): shanejli.com requests are same-origin and ride a rewrite through Vercel's edge, which evaluates a real If-Match against the response ETag. Ours are weak validators, a weak validator can never satisfy If-Match's strong comparison, and the edge therefore turns the origin's 200 into a 412 after the write has committed: a success reported as a failure, and a retry that writes it twice. Measured on 2026-09-13, the edge does this to PATCH (so the approve call) and lets POST through, but send X-If-Match on both rather than tracking which methods it intercepts. If-Match stays correct for direct callers hitting Railway with a PAT, and wins if both are sent. Full writeup in Conventions.

Reaction shortcode allowlist: +1 -1 laugh heart hooray rocket eyes confused (raw unicode is 400 Invalid emoji).

Inline notes#

An inline note is a top-level comment pinned to words on the page: anchor is {target, quote, prefix?, suffix?}, strict.

• target is "entry" for the entry body or the id of a live append on the same entry; anything else is 400.
• quote (trimmed, 1..1000) is the text as rendered, not the markdown source: **ring buffer** is quoted as ring buffer. prefix and suffix (each 0..64, default "") are the rendered text just before and after it, and are what pick the right occurrence when the quote appears more than once.
• Compare with whitespace collapsed to single spaces; the site does, so line breaks inside a quote never matter.
• An anchor on a reply (parent_comment_id set) is 400. Reply to a note with parent_comment_id and no anchor, like any comment.
• meta ({kind: "ai", provider, model}) marks a note as an Explain answer; it is only accepted alongside anchor. See AI and Reader Notes API.
• A new note is also filed into Knowledge as a card unless its author turned that off in AI settings; replies are not.
• Anchors are text, not offsets, so a note survives edits that leave its words alone. When the words are edited away the note is kept: the site lists it under the entry as a note on text that changed. GET /entries/:date/comments returns every comment, anchor included (null on ordinary comments and replies).

Reading positions#

Where the signed-in reader left off in each entry, synced across their devices. Browser session only: any PAT gets 403, because an agent has no place in an entry to save. Membership applies as everywhere else.

• A position is {date, progress, anchor, updatedAt}. One per reader per entry, and every PUT replaces it, so a lower progress than before is saved like any other: it is the last place read, not the furthest.
• anchor is measured on the page, not in pixels. block (int 0..100000) indexes the text blocks of the entry body and each append body in document order (paragraphs, headings, list items, code blocks, tables, images, diagrams; the outermost wins; headers, dates and buttons around them are not counted), offset (0..100) is how far down that block the reading line sits as a fraction of its height (past 1 in a gap below it), and text (up to 200 chars) is the block's opening words, used to find it again when an edit moved it. progress is the fallback when it cannot be found.
• progress is 1 once the end of the entry is on screen. The site counts 0.98 and up as read.
• Last write wins, by server time.

Access (invite-only membership)#

The journal is invite-only. Membership is checked on every entry, append, version, suggestion, comment, reaction and inbox route: a non-member gets 403 {"error":"Journal access required","code":"journal_access_required"}, whether they are signed out, signed in without an invite, or holding a perfectly valid PAT.

How a PAT gets access: it does not, on its own. A PAT resolves to the user who minted it, so it inherits exactly that user's membership and nothing more. Invite the human through the browser and their agents work; revoke the human and their agents stop.

Two deliberate exemptions from the gate:

• /access/* — that is the door, so it cannot be behind itself.
• GET /images/:id — an <img> tag sends no Authorization header, so gating inline images would break them for members too. Image ids are unguessable UUIDs; treat an image URL as a capability and don't paste one somewhere public.

Every route under /access is additionally browser-session only. A PAT gets 403 Journal access management requires a browser session, not a PAT — an agent token cannot grant itself access, and there is no scope that unlocks this.

Re-requesting after a rejection flips the same row back to pending rather than creating a second request — there is exactly one request row per user.

Activity feed#

Every journal mutation writes one row to a member-visible audit trail. Read it at GET /activity (site-wide) or GET /entries/:date/activity (one entry). Same membership gate as everything else here, so it is transparent within the journal but not world-public.

Rows carry metadata only, never content bodies — read the body from /versions/:num or /entries/:date if you need it.

{
  "activity": [
    {
      "id": "...", "entryId": "...", "entryDate": "2026-09-11",
      "action": "append.delete", "targetType": "append", "targetId": "...",
      "actorId": "...", "detail": null, "createdAt": "2026-09-11T10:00:00.000Z",
      "actor": {
        "id": "...", "name": "Shane", "avatarUrl": null,
        "agent": { "tokenId": "...", "name": "jira-worker" }
      }
    }
  ],
  "nextCursor": "2026-09-11T10:00:00.000Z_9c4f1e77-0b3a-4e52-9a61-7d2f8c5b0e14"
}

actor.agent is the part that matters for agents. A PAT resolves to the user who minted it, so actor is always the human — but when the write came from a PAT, agent.name is that token's name. Browser writes have agent: null. Name your tokens after the agent that holds them, because that name is what shows up in the feed. Revoking and deleting a token sets agent.name to null but leaves tokenId, so history still shows an agent did it.

action is one of: entry.create, entry.delete, entry.revert, append.create, append.update, append.delete, comment.create, comment.update, comment.delete, suggestion.create, suggestion.approve, suggestion.reject, suggestion.withdraw. Reactions are not logged. detail is a small action-specific object (version numbers, content length, rejection reason) or null — treat it as advisory, not a stable contract.

Pagination keys on createdAt plus the row id: send the previous response's nextCursor back verbatim as ?cursor=. It is the compound form <iso-timestamp>_<row-id>, not a YYYY-MM-DD date like the /entries cursor; a bare date is a 400. Do not rebuild it from a row's createdAt, because the id half is what keeps a tie or a sub-millisecond gap from silently dropping rows. See Pagination.

Content rules#

• Markdown is CommonMark + GFM (tables, task lists, strikethrough, autolinks, footnotes, fenced code with language tag but no highlighting).
• Raw HTML is silently stripped. No math rendering.
• Fenced ```mermaid blocks render as diagrams in entry bodies and appends (client-side; SSR, feeds, and comments show the raw code; invalid mermaid falls back to the code block with an error note). For other diagram tools see Images API.
• Bodies containing an in-flight editor upload placeholder (uploading-... image token) are 400.

Freshness#

The API reflects writes instantly, and so do the site pages: because the content is private, /journal and /journal/:date no longer server-render entries at all — they load from this API in the browser with your session. There are no journal RSS/JSON feeds any more (/journal/feed.xml and /journal/feed.json return 404 — a feed pull carries no viewer to check membership against, so the only correct answer is that the URL no longer exists; the public Blog has feeds instead), the per-date OG image is a generic card with no entry text, and journal URLs are excluded from sitemap.xml and disallowed in robots.txt.