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

Visual page editor

An embedded site opts in by passing visual to createInkling. The keys are content-type names. The editor uses the site's existing page templates and ordinary content fields. Types without a definition keep the field editor.

import { createInkling } from "inkling"
import { renderVisual, type VisualPages } from "inkling/visual"

const visual = {
  homepage: {
    sections: [{
      id: "intro", label: "Introduction", selector: "main > #intro",
      fields: ["heading", "image"],
    }],
    fields: { heading: "#intro h1", image: "#intro img" },
  },
} satisfies VisualPages

const inkling = await createInkling({ adminBase: "/admin", visual })

// In the site's page renderer, after loading the correct entry:
const body = renderVisual(html, visual.homepage, entry.data.__layout, editing)

renderVisual(html, definition, layout, editing = false) returns HTML. It moves declared sibling sections and removes hidden ones on the public page. With editing: true, hidden sections remain visible to the editor, and fields and sections receive selection attributes. Enable this mode only inside a valid preview request with visual=1. The admin fetches that page into a sandboxed canvas; it does not run the site's scripts or submit forms. An isolated, hash-pinned editor bridge handles selection in the preview, including Safari. If its controls cannot start, the canvas offers Reload preview.

Unsaved previews

Selecting a shared header or footer element keeps the same page open and shows its controls beside the canvas. Other page elements remain selectable. Unsaved page edits are preserved; unsaved shared edits require Save and switch, Keep editing, or Discard and switch. The sidebar lists configured singleton pages under Pages and their item lists under Content.

Double-click text or an image to open its editing controls. Right-click, or use the visible Actions button, for Edit, Ask Inky, and the selected section's available move, hide, or collection actions. These actions preserve the explicit save flow. Ask Inky opens beside the selected element on desktop and names that target in the conversation; narrow screens use the corner panel.

POST /api/entries/:id/preview requires permission to edit the entry. Send an optional JSON body { title, slug, data } to preview unsaved changes. Without a body, the link reads the saved entry. The response contains token, expiresAt, url, and siteUrl from the content type's preview URL template. Previewing an existing entry does not save or publish it.

The host reads the preview query parameter and fetches GET /preview/:token, substituting that single entry for this request only. Send no-store and X-Robots-Tag: noindex, nofollow on the rendered page. Links last up to one hour. Unsaved snapshots also expire after a restart or eviction: the store holds at most 100 snapshots, 16 MiB total, and 1 MiB per snapshot. Deleting the source entry invalidates its preview.

Refresh after saving

inkling.contentVersion() returns a process-local counter that changes after content mutations, including scheduled publication. Clear host delivery caches when it changes. Capture the version before an asynchronous read and cache the response only if the version still matches. Set public page cache headers to revalidate after edits. Separate processes should use realtime or webhooks for invalidation.

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.

Shared website parts

Pass a website manifest to createInkling() to connect the header, footer, logo, announcement, and other shared details to their existing sources. The admin provides one Header & footer screen and selectable shared parts inside visual page previews. Inky receives the same map.

const website = {
  previewUrl: "/",
  parts: [{
    id: "navigation", label: "Top navigation",
    description: "The menu across every page", selector: "header nav",
    source: {
      kind: "menu", name: "main", label: "Main navigation",
      defaults: [{ label: "Home", url: "/" }],
    },
  }, {
    id: "contact", label: "Contact details",
    description: "The address in every footer", selector: "footer address",
    source: { kind: "entry", type: "house", fields: ["street", "email"] },
  }, {
    id: "logo", label: "Logo", description: "Your website logo",
    selector: ".brand", source: { kind: "settings", fields: ["logoId"] },
  }],
}
const inkling = await createInkling({ adminBase: "/admin", website })

GET /api/website requires content read access. Entry sources require an existing singleton. Each save uses the usual entry, menu, or settings route and its permissions; only changed fields belonging to that part are sent. Shared entry drafts remain drafts. The preview is same-origin and refreshes after saving. A missing menu starts with declared fallback links and is first created when an editor saves; the template must read the declared menu name. The shared menu editor edits a flat list. Nested menus remain available in All menus for sites that render them.

Choose a page searches published entries whose content type has a preview address. Menu delivery resolves their entryId references to url using that address template, excluding draft, deleted, or out-of-scope destinations. Existing address links are preserved.

Give independently editable elements their own parts: a badge image inside an announcement can map just its image field. Selection uses the closest matching element. Switching shared parts with unsaved work offers Save and switch, Keep editing, or Discard and switch. A failed save preserves the current controls and shows its error beside the save actions.

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.

Test Inky checks streamed tool calling with a synthetic marker, without reading or changing content. It verifies the connection and transport, not the quality of every future answer. Stream failures remain in the conversation; an interrupted stream cannot silently report success. Applying a proposal refreshes a clean open editor. Unsaved manual edits must be saved or discarded before applying a proposal.

Working through the ChatGPT connector uses the editor's own ChatGPT account. Using ChatGPT plan usage to power Inky on a remotely hosted website requires an approved OpenAI integration; the local open-source sign-in flow is not a hosted website login. See the current integration requirements. A normal OpenAI API key uses separate API billing.

What Inky can do

Forty-five tools: nineteen read, twenty-five 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.