API Reference

The editor's overview

One read to pick a site up: its brief, its content rule and counts, the ten most recent posts, 30-day traffic, the lint summary, running tests with anything wrong with them, the Search Console connection, and an attention list of what to deal with first, each with the command that looks into it.

Read the editorial brief

The brief as named fields (niche, audience, voice, topics, publish_criteria, style_rules, cadence, goals, notes), as one markdown document, and the fields still empty.

Write the editorial brief

Sets the fields sent and keeps the rest. An empty string clears a field; an unknown field is refused by name.

What a site publishes

A published note has exactly one home site: the site it is pinned to, else the first site whose content rule it matches, else the primary site. Its page is served there, its sitemap entry and canonical URL are there, and a request for it on another site of the account redirects. Returns the site's rule and the notes that live on it, each with its URL and why (pinned, rule or default). Set the rule with PUT /api/sites/:id {"content_facets": [...]} — taxonomy value ids or "Facet=Value" names.

Pin a note to a site

The exception to the rules: this note lives on this site. {"site": ""} removes the pin. GET the same path to see where a note lives and why.

Site traffic

Views, unique visitors, average engaged seconds, read rate and click-through rate for the period, the previous period for comparison, a daily series, top content, referrers, campaigns (utm_*) and devices. Views are reported by a beacon from the reader's browser: crawlers, link previews and the owner's own signed-in visits are not counted, and no cookies are set — a visitor is a hash that rotates daily. The site may be "all".

Every article with its numbers

All public notes that live on the site with views, visitors, read rate and click-through for the period — including the ones nobody read, which a top-content list cannot show.

One article's readership

Totals and trend for one note, its referrers, the pages of the site that sent readers to it, and where they went next.

Notes that need an editor

Every note with something wrong, worst first, and a count per check. Checks come in three groups: draft (the note reads like an unedited AI chat: a prompt for an opening, assistant boilerplate, speaker labels), content (a heading that repeats the title, numbered steps that all read "1.", unconverted markdown, encoding damage, thin or empty bodies) and publish (a published note without a meta description, cover image, slug or taxonomy value). unedited is true when a note has two or more draft findings.

Repair encoding damage

Fixes text that was decoded with the wrong code page on import ("SautΘ" → "Sauté", "jalape±o" → "jalapeño") in titles and bodies. Only characters inside a word are touched, so "5 ± 2" and "Θ(n)" are left alone. A dry run unless dry_run is false; each repaired note keeps its previous text as a revision. Words whose character was lost outright are listed as unrecoverable.

Test an article's title

An experiment with target_type "note" and target_id tests that article's title and description instead of a page block. Each variant carries overrides ({"title", "description"}); the control carries none. A visitor is assigned one variant and sees its wording wherever the article is named. goal says what counts: click (shown in a list → article opened), read (article opened → read to the end), lead or purchase. Crawlers are never assigned, so search engines always see the real title. The CLI command does the experiment, both variants and the start in one step.

Check a theme with code

A theme can re-implement blocks (blocks: {"<slug>": {"template", "css", "js"}} — same props, its own markup, styles and script), add markup to <head> and run a site script. This validates an unsaved theme and answers with errors and warnings; POST/PUT /api/themes take the same fields. GET /api/themes/reference documents the package layout, the template helpers and what props carry.

Redirect old addresses

Replaces the site's redirects. POST adds or changes one {from, to}; DELETE ?from= removes one; GET lists them. A from path ending in /* matches everything beneath it and * in to receives the rest. Redirects answer only requests nothing else does, with a 301.

Site icon and share image

favicon_media_id and share_image_media_id name images in the media library (an id, or the exact media name; "" removes). The icon links in every page's head are generated from the favicon. A page's og:image is, in order: the one set on the page or the article's featured image, the first picture the page shows (the first image in an article's body), then the site's share image. Pages also carry og:site_name, twitter:card/title/description/image and image dimensions.

Connect Search Console

Connects a site to its Google Search Console property with a service account: create one in Google Cloud, add its email as a user of the property in Search Console, and send its JSON key here. The connection is tested before it is saved; the key is stored encrypted and never returned. GET the same path for the status and setup steps; DELETE removes it.

Search performance

Clicks, impressions, click-through rate and average position from Search Console, by query, page, date, country or device. GET /api/notes/:id/search is the same report for one article's URL.

List notes

Returns notes owned by the account, most recently edited first. Each note carries published_at (when it first went public), home_site_id and url (where it lives publicly).

Retrieve a note

Returns one note including its full body as Lexical JSON. Add ?format=markdown to also get body_markdown, the body rendered as markdown.

Create or update a note

Upserts the note at that id. The write replaces the record, so send the whole thing. Author in markdown with body_markdown — the server converts it to the editor's document format (headings, lists, links, emphasis, code blocks, tables) exactly as the app would.

Publish or unpublish

Toggles whether the note is served at its public URL. Publishing is what makes it indexable.

Read search and share metadata

What the public page's <head> is built from: the stored slug, meta_description, og_title and og_description; the cover image used for og:image; the canonical url; `effective`, the values emitted once fallbacks apply (meta description → first body text, Open Graph copy → title and description); and `warnings` for anything a crawler or share card would clip or miss.

Set search and share metadata

Partial update: only the fields sent change. An empty string clears a field back to its fallback (for slug, back to serving by id). Answers with the same shape as GET, warnings included, so one call writes and verifies.

List child notes

Direct children only. Use /descendants for the whole subtree.

Move a note

Reparents the note. Pass a null parent to move it to the top level.

Delete a note

Permanent. Check what references it first.

List pages

All landing pages except the home page, which has its own endpoint.

Retrieve the home page

The page served at the account root. Provisioned on first access, so this never 404s.

Create or update a page

Upserts the page. Blocks are replaced wholesale — read, modify, write back.

List a page's blocks

The blocks in order — position, instance_id, type, a one-line summary, style — with anything that looks wrong: an unknown block type, props the block does not have.

Add a block

Adds one block, starting from its type's default props with yours merged on top. The page row is locked for the change, so concurrent writers cannot erase each other. Returns the page's blocks afterwards.

Change a block

:block is a position, an instance_id, or a type the page has exactly one of. props and style merge; a null prop or an empty style value removes it. template_override sets the block's own template (empty string resets it).

Move a block

Body {at} is the 1-based position to move it to.

Remove a block

A block that is part of an A/B test is refused unless ?force=true.

A site's template pages

kind is header or footer (the parts every page of the site shares) or note or product (the layout every article or product page renders through). Provisioned on first use; ?site_id= picks a site other than the primary. Edit them like any page.

Render blocks without saving

Renders an arbitrary block array. Returns html (a body fragment), css (content-widget styles plus the theme) and head (the theme's font links) — the pieces of a page, not a document. The theme is the one named by theme_id, else that of site_id, else the primary site's; theme {tokens, custom_css} previews an unsaved theme.

Make a page the home page

Promotes this page to the account root. The previous home page becomes an ordinary page.

List block types

System types plus any this account owns, templates included.

The block catalog

Every block type without its template: slug, name, category, description and prop schema. ?slug= returns one block with its default props. System blocks are defined by files shipped with the server.

Create or update a block type

Defines a reusable block. The template is Go html/template with the block's props in scope.

Entity fields available to templates

What a block template can read off a linked record — useful when authoring prop schemas that point at products, notes or media.

List sites

Every site with its home page id, page and domain counts, and its theme ("" means the default built-in).

Update a site

A patch: only the fields sent change. Setting theme restyles every page, article and product page on the site.

List themes

Built-in themes, then the account's own, each with its full token set. Also returns token_spec and used_by (theme id → site names).

What a theme can style

The token spec (key, type, allowed values, default), the CSS variables tokens become, the class names the built-in block templates use, and the per-block override props. Read this before writing a theme's custom CSS or a custom block template.

Create a theme

Starts from the defaults, or from another theme with copy_from.

Update a theme

A patch. tokens merges onto the stored set, so one token can change on its own; a token or value the spec does not allow is a 400. Built-in themes cannot be updated.

A theme's stylesheet

The complete CSS a page under this theme carries: tokens, block styles, then the theme's custom CSS. Returned as text/css.

Delete a theme

Sites using it return to the default theme.

List media

Note the array key is media_items.

Create a media record

Step one of an upload: reserve the id and set the name. The record exists with no file until you upload one.

Upload the file

Step two: multipart/form-data with the bytes in a field named file. Images get thumbnail variants generated synchronously; other types are stored as-is.

Regenerate thumbnails

Re-derives image variants from the stored original. Rejects non-images with 400.

List products

Create or update a product

List attached files

The media records a buyer receives after purchase.

Attach a file

Links a media record to the product as a deliverable. Buyers get signed, expiring links.

Set taxonomy values

Assigns facet values so the product appears under the right catalogue filters.

List contacts

Create or update a contact

List interactions

The contact's activity log, newest first: contact_created, note_added, form_submitted, message_sent, message_received, event_scheduled (dated when the meeting was set up; start_time in metadata), order_placed, list_joined. Each row says who acted (user or contact) and what it is about (subject_type, subject_id). The newest entry is also projected onto the contact as last_activity / last_activity_kind.

List transactions

What this contact has paid you — useful for building an account view.

Add an internal note

Freeform note attached to a contact. Never shown publicly.

List contact lists

Includes a member count per list.

Create or update a list

List members

Add a contact to a list

Remove a contact from a list

Removes the membership. The contact itself is untouched.

Add many contacts at once

One request for a whole selection — every contact, everyone at a company, or a copy of another list. The list may be given by id, slug or name. Adding is idempotent: contacts already on the list are left as they are.

Remove many contacts at once

The bulk counterpart of the DELETE above, taking the same selection as the bulk add: contact_ids, or all with search / company / from_list. Contacts are not deleted, only taken off the list.

List orders

Update fulfilment status

For physical goods — mark an order shipped once it leaves.

Revenue summary

Aggregate revenue, subscriber and order figures behind the seller dashboard.

List experiments

Retrieve results

Impressions and conversions per variant. Conversions count against the same records the rest of the platform uses, so a result is expressed in orders rather than clicks.

List variants

List access rules

Create or update an access rule

List subscription tiers

List collections

Bundles of items sold or granted together.

List facets

Create or update a facet

Reorder facet values

Sets the order values appear in filter UI.

Set a note's taxonomy values

Replaces the note's full set of values; GET the same path reads it. Products use /api/products/:id/taxonomy with the same body.

Browse a public catalogue

Unauthenticated faceted search over an account's public products and notes — what the Content Browser block calls. Returns items, pagination and facet counts.

Search across everything

One query over notes, pages, products, contacts, media and more. This is what the app's command palette calls.

The current account

Resolves the credential to an account. Handy as a health check for an integration.

List API keys

Metadata only — the key itself is shown once, at creation.

Create an API key

Returns the raw key exactly once. Store it before you close the response.

Revoke an API key

Immediate. Requests using it start failing with 401.

Storefront settings

Branding, custom domain and which items appear on the public storefront.