Route reference

What the four share#

• JSON responses, cache-control: no-store.
• Any unexpected method gets 405.
• The order of checks is the same everywhere: rate → declared size → identity → received size → shape → business rules.
• Error messages carry no technical detail. Detail goes to the server logs.
• No response contains a secret: no token, no hash, no session content.

POST /api/auth#

Opens a session from the site key. It is the only route that evaluates an identity.

curl -i -X POST https://the-site.com/api/auth \
  -H "content-type: application/json" \
  -d '{"key":"the-site-key"}'

set-cookie: inline_session=…; HttpOnly; Secure; SameSite=Strict; Path=/; Max-Age=28800
set-cookie: inline_edit=1; Secure; SameSite=Strict; Path=/; Max-Age=28800

{ "ok": true }

Cost: about 350 ms, the time argon2id takes. Deliberate — it is what makes brute force impractical. Body capped at 2,000 bytes, key at 256 characters: beyond that, nothing is computed.

DELETE /api/auth

Closes the session: both cookies are cleared. Always answers 200.

GET /api/content#

Reads the repository's real state and the reference version for the optimistic lock. The overlay calls it on load.

curl -s "https://the-site.com/api/content?path=src/content/pages/en/home.json" \
  --cookie "inline_session=…"

{
  "content": "{\n  \"meta\": { … }\n}\n",
  "version": "3f2a1c…"
}

POST /api/save#

Validates and publishes a page. It is the most controlled route in the project.

{
  "path": "src/content/pages/en/home.json",
  "content": "{ … the whole JSON file, as text … }",
  "version": "3f2a1c…",
  "message": "content(en): home — hero.title"
}

{ "version": "9b7e42…" }

POST /api/upload#

Receives an image already cropped and converted by the browser, checks it, renames it and stores it in the repository.

file   the image file (JPEG, PNG or WebP), 20 MB max
name   desired name, 200 characters max — indicative, always rewritten

{ "src": "bakehouse-at-dawn.webp", "width": 1600, "height": 900 }

The router#

A site declares its routes once, and the host plugs into them. The declaration is one line: the only decision that belongs to the site is its locales.

import { createRouter } from 'inline-core/server';
import { LOCALES } from './locales';

export const api = createRouter({ locales: LOCALES });

createRouter returns the four routes in three shapes. Each host takes the one it needs — none is preferred, and the package knows about none of them.

env carries whatever the host exposes: the variables, and any bindings — including RATE_LIMIT. An unserved method gets a 405, an unknown path a 404, and always as JSON: the caller is the overlay, and an error page teaches it nothing.

The factories#

They are still exported, for wiring by hand: createRouter only gathers them. A site on 2.0.x has nothing to change.

import {
  createAuthRoute,      // ()                     → onRequest, onRequestPost, onRequestDelete
  createContentRoute,   // ({ locales })          → onRequest, onRequestGet
  createSaveRoute,      // ({ locales })          → onRequest, onRequestPost
  createUploadRoute,    // ()                     → onRequest, onRequestPost
} from 'inline-core/server';

SiteConfig holds one thing: locales. If that interface grows, it is a sign a package decision has leaked into the sites.

Rate budgets#

Caps#