Reference

Look it up

The delivery surface your sites call, the shapes your content can take, and every variable that configures it.

Delivery API

Authenticated with X-Api-Key. Read-only, published content only. Responses are private-cacheable and vary on the credentials that shape them.

Query parameters

Socket frames

Open ws://host/realtime?ticket=… after exchanging a credential for a ticket. A browser cannot set headers on a handshake and query strings reach access logs, so the ticket is single-use and dies in 30 seconds.

→ client
{ "action": "subscribe", "topic": "content:post" }
{ "action": "unsubscribe", "topic": "content:post" }
{ "action": "ping" }

← server
{ "topic": "content:post", "event": "entry.published", "data": { "id": "…", "slug": "hello", "type": "post" } }

Server frames also include ready, subscribed, pong, and error. A key hears only entry.published, entry.unpublished, and entry.deleted, and frames never carry content — re-read through /content when one arrives.

Field types

Eighteen. Each one declares how it validates, what its empty value is, and what the editor renders.

Roles

A strict ladder. Every request re-reads the user, so a demotion takes effect on the next click rather than at token expiry.

Admins cannot create, edit, or promote above their own rank. API keys are stored only as SHA-256 and the plaintext is shown exactly once.

Agent keys

How a program signs in — an MCP server, a build script, an automation — instead of holding somebody's password. Mint one under Agent keys, ticking what it may do. Anyone can mint one for themselves; it can never exceed them.

The three are never interchangeable: an agent key is refused on the delivery API and a delivery key is refused on the admin API, so a website key that ends up in a repository is not a way in.

An agent key can do nothing administrative — no adding a user, minting an API key, connecting a social account, installing a plugin, or spending the AI provider's budget — whatever you tick and whatever role you hold. Those capabilities are not merely off by default; there is no key that can hold them. It expires (90 days by default, 365 at most), it is revocable on its own without changing a password or signing anyone out, and demoting the account narrows every key it minted on the next request. Minting asks for the password again, so a borrowed browser cannot quietly make one.

AI providers and agent tools

Every AI surface — the field assistant, Inky, and the visitor bubble — runs on one connected provider. Credentials are entered in the admin and stored sealed; none of them is an environment variable.

Model names are typed, not chosen from a closed list — the suggestions are a starting point. Inky needs a model that can call tools; the field assistant does not.

What Inky can do

Thirty-eight tools: thirteen read, twenty-four propose, one moves the admin. Nothing writes. A proposal is a record the admin renders as a diff and applies through the same route your own edit takes — so it is validated, revisioned where a revision exists, and recorded in Activity as your change rather than a machine's.

Each tool names the permission its proposal will need, and the list is filtered to what your role could actually apply. An author is never offered the site settings; an editor is never offered delivery keys. The panel greys a single card it knows will be refused rather than the whole tray.

What still needs your hands

Four things, and Inky takes you to the screen rather than describing the route: uploading a file, creating an account (a password has to be typed), pressing Connect on a social network (the consent screen is on the network's own domain), and pasting a client secret. Inky will ask for a client ID in conversation but is told never to ask for a secret — it is a password, and a chat window carries it further than it needs to go.

Visitor bubble

Social

Setting networks up, connecting accounts, and sending posts to them. Nine networks — X, Facebook, Instagram, Threads, LinkedIn, TikTok, YouTube, Pinterest, Google Business — each with a publisher behind it. Session-gated like the rest of the admin API, with three permissions rather than two: an author writes a post, an editor decides when it goes out, an admin sets up networks and connects the accounts.

A post refused for a network's own rules comes back as 400 with { code: "SOCIAL_INVALID", details: { fields } }, the same shape the entry editor already marks inputs from. This is checked when the post is saved, not when it is sent: a scheduled post that turns out to be unpostable at 6am on a Saturday is a notification nobody reads, and caption length, one-video-per-post, and images-or-a-video are all knowable when it is written.

Configuration

.env is required at runtime, and .env.example documents every variable in place — it is the source of truth, and this table is the summary.

Core

Storage

Plugins, bootstrap, and AI

Provider credentials themselves are never environment variables — they are entered in the admin and stored sealed.

Commands

Bun is the runtime, package manager, and bundler. There is no node or npm step.

There is no build step for the API. Type-check and test are the whole verification path, and both must be clean.

Errors

Every error the API raises renders as JSON with a stable code.

{
  "error": "Validation failed",
  "code": "VALIDATION_FAILED",
  "details": {
    "fields": [{ "key": "summary", "message": "Required" }]
  }
}

Field errors name the key, so the editor can mark the specific input rather than showing one message for the whole form.