Skip to content

Changelog

View as Markdown

Every change that reached Colophon's main branch and that you can see or use, newest first. Each entry is dated the day it landed, labelled with its type and the areas it touches, and links to the docs. Colophon hasn't made its first release yet, so entries are grouped by month rather than by version. Subscribe with RSS.

November 2026

ImprovementPerformanceAPI

Saves commit together again: live-list hints are sent after the commit

Every save, publish or membership change used to send its live-list hint from inside its own database transaction. PostgreSQL lets only one transaction that sends a notification commit at a time, so concurrent writes lost group commit: in load tests on a slower machine, changes to members, schedules and tokens queued 100–380 ms for that one lock.

Now a write only records its hint, and each Colophon process sends the committed hints every 100 ms, each distinct hint once, in a short transaction of its own. Concurrent saves commit in groups again. A statement that changes 1,000 rows queues one hint, not 1,000.

What you notice: a Studio list or an open event stream may hear about a change up to 100 ms later than before. Nothing else changes for clients. The change frames on GET /api/v1/projects/{project}/environments/{environment}/events keep their shape, commits close together may fold into one frame, and the last commit is always reported. A client should still refetch on each frame rather than count frames, and treat resync as “reload what you show”.

event: change
data: {"k":"entries","c":"posts","e":"<environment id>"}

Read more: Live events

FeatureSDKCLI

Preview helpers for your site in the SDK, and a colophon preview command

Connecting your site to draft preview is now a few lines. @colophon-cms/sdk adds helpers built on the standard Request and Response types, so they work in SvelteKit, Astro, Next.js or any other framework:

  • createPreviewHandler exchanges the one-time code for a preview token, keeps it in your own HttpOnly cookie and redirects to the page;
  • previewTokenFromRequest and previewClient read drafts from /preview/v1 with that token;
  • previewHeaders sends private, no-store, noindex and a frame-ancestors rule so only your Studio can frame the page;
  • listenForDraftUpdates reloads the page after each save in the Studio; exitPreviewHandler ends preview.
import { createPreviewHandler } from '@colophon-cms/sdk';
const enter = createPreviewHandler({ baseUrl: 'http://localhost:8080', project: PROJECT_ID });

A static site can read previews straight from the browser: /preview/v1 answers CORS for the environment’s preview origin, never with credentials.

From the terminal, colophon preview prints a one-time address for an entry’s saved draft, or for a publish request with --changeset:

Terminal window
colophon preview <entry id> --project <project> --minutes 30

The address works once, within a minute. The SDK is prepared for its first npm release.

Read more: TypeScript SDK · The colophon CLI · Preview

FeatureStudio

Preview the saved draft on your own site, beside the editor or in a new tab

Editors can now see a draft as their website will show it, before it is published.

An owner sets the site’s preview address once, in Settings → Website connections → Preview on your site. The address must contain {code}, and may also use {collection}, {id}, {slug} and {locale}, so it can open the right page directly.

In the entry editor, the Preview menu offers Side by side (your site beside the fields; on a narrow screen, switch between Edit and Preview) and Open on my site (a new tab). The pane shows your last saved version, never unsaved keystrokes, and refreshes after each save the server accepted. It keeps the preview open while you work and ends it when you close the pane.

A publish request’s page has Preview on your site too, showing exactly what that request will publish, bound to its current content.

Every state is spelled out: not set up yet, opening, the site didn’t confirm, unsaved changes, a save that failed, or a browser that blocks the site’s cookie inside the pane. In that last case, open the preview in a new tab instead, which always works.

Your site needs a preview route; the SDK’s preview helpers provide one.

Read more: Preview

FeatureSelf-hosting

A production path without containers: a hardened systemd unit and a Caddyfile

If you would rather not run Docker, or your database is managed elsewhere, Colophon now ships a path for one Linux host: colophon-server under systemd, Caddy in front for HTTPS, and PostgreSQL and object storage wherever you keep them.

The systemd unit keeps secrets out of files and the environment: the database URL, cache URL and storage key are systemd credentials, read through the COLOPHON_*_FILE settings. The service runs as a dynamic user with no privileges, a read-only file system and a narrow system-call filter, and shuts down gracefully so in-flight requests finish. The Caddyfile proxies your domain to the server on loopback and passes live events through as they are written.

LoadCredential=database_url:/etc/colophon/credentials/database_url
Environment=COLOPHON_DATABASE_URL_FILE=%d/database_url

The non-secret settings live in an environment file; set COLOPHON_PUBLIC_URL to your https:// address and COLOPHON_TRUSTED_PROXIES=127.0.0.1/32 so rate limits count each visitor rather than the proxy. The steps start from a release’s static binaries; until the first release is published, build them from source.

These files are checked in CI by systemd-analyze verify and caddy validate. They have not yet been followed end to end on a real host.

Read more: Installation · Security

ImprovementPerformanceAPI

Creating API tokens no longer starves reads, and schedule and release lists read only what they show

Two load fixes for busy projects.

Token creation. A project may hold at most 100 active API tokens, so each POST /api/v1/projects/{project}/tokens takes the project’s creation lock, counts, then writes. That lock used to be held across eight round trips to the database, about 100 ms each on a small server, while queued creators each held a pooled connection and other reads waited. It is now held for two statements: the lock, then one statement that counts and writes the token and its permissions. The count stays exact: twenty creators racing for the last slot still make exactly one token, and the rest get 422 too_many_tokens. The answer to a creation is now exactly what reading the token back returns.

Schedule and release lists. GET …/schedules and GET …/releases, and the check that finds which publish requests stop an entry’s deletion, now choose their rows first and look up titles and names afterwards. Before, once a project had grown past the database’s statistics, a 120-row schedule list could read 16,203 publish-request rows and take three seconds, and a 100-release page read 10,150. Each list now reads about as many rows as it returns.

Nothing to change on your side.

Read more: Authentication & API tokens · Scheduling

SecuritySelf-hosting

Sign-in tokens and device codes in a URL never reach the logs

Every log line written while handling a request carries the request’s path. Two routes carry a secret in that path: spending a magic link (POST /audience/v1/{project}/magic-link/{token}) and the CLI’s device approval page (GET /auth/device/{code}). With debug logging on, or whenever a warning was logged during such a request, the live token or code was written to the log store.

Now the logged path writes those segments as their names, so the line reads POST /audience/v1/<project id>/magic-link/{token} at every log level. Every other segment is kept as sent, so ids stay searchable. A path that matches no route but looks like one of these, such as one with a trailing slash, is redacted the same way.

Nothing changes for clients; the routes keep their shape. If you kept debug logs from before this change, treat magic-link tokens and device codes in them as exposed. They expire on their own within minutes, so the risk is to old logs that were shared, not to accounts today.

Read more: Monitoring · Security

SecuritySelf-hosting

Database guards trust roles, not session settings, and deleting a project is an operator's job

Colophon’s PostgreSQL schema protects a project’s owner role, its last owner and the audit log with triggers. Some of those guards stood aside when a session setting was present, and any session can set one, including the server’s own database login. Now the guards stand aside only for the dedicated database roles that do sanctioned work: the retention sweep and project deletion.

Also fixed in the database:

  • The guard functions pin their search_path, and the check that a project exists answers only inside its trigger.
  • Sign-in throttle rows are row-level secured by realm, so staff keys and each project’s site-user keys are visible only in their own context.
  • The retention sweep keeps pace with the two tables unauthenticated requests grow (magic links and sign-in throttle keys).
  • Deleting a project now removes its audience roles, site users and their sessions, magic links, listed origins and upload versions. It runs from the database owner’s login, as an operator task; the server’s login can no longer call it.

Rollback floor: these changes are additive, so an older build would still start on the newer schema and simply ignore them. Once you run a build with these fixes, never roll back to one without them; fix forward instead.

Read more: Security · Backups and restore

FeatureAPI

Preview drafts on your own site through a short-lived, read-only preview API

Your site can now show unpublished drafts to the people who are working on them. First tell Colophon where previews open, as a signed-in person (here with the personal token colophon login keeps):

Terminal window
curl -X PUT http://localhost:8080/api/v1/projects/{project}/environments/{environment}/preview-target \
-H "Authorization: Bearer $COLOPHON_TOKEN" -H 'Content-Type: application/json' \
-d '{"url_template":"https://example.com/api/preview?code={code}"}'

A person then opens a preview of an entry (with its translations) or of a publish request with POST …/previews; project API tokens can’t. The answer holds a site address carrying a one-time code that works once, within 60 seconds. Your site exchanges it at POST /preview/v1/{project}/{environment}/exchange for a bearer token that lasts 15 minutes by default.

With that token, /preview/v1 answers exactly like /content/v1 (list, get, query and a session route for a preview banner), with the drafts laid over the latest release and a preview object on each row. A publish request’s preview is bound to the exact content under review: if it changes, reads answer 409 preview_stale.

Preview answers are private, no-store, never indexed and never cached, and every read re-checks that the person who opened it may still read this content. They can renew the preview, ask for a fresh code or end it now.

Read more: Preview · Delivery API

SecurityAPI

GraphQL refuses documents that are too deep or too large before running them

A GraphQL document’s cost used to be measured only as it ran. A short document full of nested fragments could keep a server busy for minutes, and a value nested deeply enough could exhaust the server’s stack while parsing.

Now every document sent to POST /api/v1/projects/{project}/environments/{environment}/collections/{collection}/graphql is measured before it runs, with its fragments expanded:

  • deeper than 16 levels: too_deep
  • more than 512 fields: too_complex
  • fragments that spread one another in a cycle: fragment_cycle
  • brackets nested more than 64 deep, checked before parsing: too_deep

Each refusal is a 422 in the usual error envelope, pointing at the query, and nothing runs:

{"error": {"code": "validation_failed",
"message": "…",
"details": {"reason": "too_deep", "pointer": "/query"},
"request_id": "…"}}

The limits leave room for every read the schema allows (a two-level reference read is 6 deep) and for a full introspection query.

Read more: GraphQL · Errors

SecurityAPI

A replaced or deleted image no longer stays cached for a year at its plain address

An upload’s plain address, /media/v1/{project}/{environment}/{asset}, always serves the upload’s current version, and a replace or a delete changes what that is. It was nevertheless marked immutable for a year, so a browser or CDN that had seen the old bytes could keep showing a replaced image, or one you had deleted, long after the change.

Now caching follows what the address names:

  • a version’s own address, …/{asset}/{sha} and its renditions, stays public and immutable with a one-year max-age: those bytes never change;
  • the plain addresses, …/{asset} and …/{asset}/{name}, answer public, max-age=60, must-revalidate with the version’s ETag, and a matching If-None-Match gets a 304 with no body.
GET /media/v1/{project}/production/{asset}
If-None-Match: "…"
HTTP/1.1 304 Not Modified
Cache-Control: public, max-age=60, must-revalidate

A change at the plain address now reaches caches within a minute. For pages that must show exactly what was published, use the versioned url that delivery rows carry in media.

Read more: Media library · Delivery API

ImprovementAPIStudio

The media library pages, searches, filters and keeps alt text, titles, credits and tags

The upload list used to stop at the newest 100, so the 101st upload was invisible in the Media page and in every image picker. Now GET /api/v1/projects/{project}/environments/{environment}/assets pages with limit (1–100) and cursor, answering next_cursor. It also searches file names, titles and alt text with q, and filters by state and tag.

Each upload keeps its own words. PATCH …/assets/{asset} changes alt (up to 300 characters), title, credit and tags (up to 10, lowercase with dashes), under If-Match; a stale ETag answers 409 stale_version. Tags take the place of folders.

Terminal window
curl -X PATCH http://localhost:8080/api/v1/projects/{project}/environments/production/assets/{asset} \
-H "Authorization: Bearer $COLOPHON_TOKEN" -H 'If-Match: "v3"' \
-H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
-d '{"alt": "Harbour at dawn", "tags": ["harbour", "cover"]}'

In the Studio, the Media page shows the whole library with search and filters, uploads many files at once through a queue, and opens each upload’s details: alt text, title, credit and tags (with a conflict state if someone else changed them), its versions, where it’s used, replace (with a reminder to republish), both addresses to copy, and delete.

Read more: Media library

ImprovementPerformanceSelf-hosting

The static Linux server runs allocation-heavy requests five times faster

The Linux build of colophon-server is a static binary linked against musl, so one file runs on any Linux and the container image needs no C library. musl’s own memory allocator takes a single lock for every thread, and it showed: on the same CI runner, validating a realistic rich-text post ran at 4,589 requests a second (p99 29.1 ms) against 23,340 (p99 10.3 ms) for a glibc build of the same code.

The static Linux server now allocates through mimalloc. Measured the same way, it matched glibc: 24,367 requests a second against 23,891, p99 9.6 ms against 10.0 ms. Memory after the run was 38.2 MB resident against glibc’s 32.5 MB. These are observations on one CI runner type, not capacity figures.

Nothing to configure. Only the static Linux server and the container image change; macOS, Windows and glibc builds keep their system allocator, and the colophon CLI, a short-lived client, keeps musl’s.

Read more: Installation

ImprovementSelf-hosting

Colophon is released under the MIT licence

Colophon now has a licence: MIT. The repository’s LICENSE file holds the standard MIT text, every Rust component of the server, worker and colophon CLI declares license = "MIT", and the npm packages prepared for the first release (@colophon-cms/sdk, @colophon-cms/rich-text and @colophon-cms/cli) say "license": "MIT".

Why it matters: until a licence is settled, nobody can safely run, change or build on the code. MIT lets you self-host Colophon, modify it and ship it inside your own products, commercial or not. The only condition is that copies keep the copyright and licence notice. There is no warranty.

What to do: nothing, if you are running Colophon. If you redistribute it, for example in a container image or as part of a larger product, include the LICENSE file. Colophon’s own dependencies keep their own licences; the build only admits licences on its allowlist, MIT among them.

{
"name": "@colophon-cms/sdk",
"license": "MIT"
}

Read more: Introduction

FeatureSelf-hostingCLI

Run Colophon with one Docker Compose command, with secrets kept in files

Docker is now all you need. The quick start’s compose file starts Colophon with PostgreSQL, Valkey and Garage, generates every password and key on first start, and publishes only 127.0.0.1:8080. One image carries the server, the colophon CLI and the Studio, on a distroless base, running as a non-root user. The image is prepared for the first release; until it is published, build it from a clone of the repository and name it in COLOPHON_IMAGE.

Terminal window
docker compose up -d --wait
docker compose logs colophon | grep "Setup code"

Then open http://localhost:8080/studio/, create the first account and enter the setup code; the Studio’s first-run screen shows that command too.

Two pieces help any install, container or not:

  • Every secret setting also takes <KEY>_FILE, a path to a mounted secret, for example COLOPHON_DATABASE_URL_FILE or COLOPHON_S3_SECRET_KEY_FILE. Setting both a value and its file stops the server at start-up, and no error ever prints a secret’s contents.
  • colophon admin init-roles --app-password-file FILE creates the database roles the server needs, sending passwords as SCRAM verifiers. It refuses the development password and anything under 16 characters, and is safe to rerun.

Read more: Quick start · Installation · Configuration

SecuritySelf-hostingAPI

Website connections reach only public https addresses unless you opt in

A server listening on a loopback address used to be treated as a development machine, so its webhooks, CDN purges and probes could reach private and loopback addresses. A production server behind a reverse proxy listens on loopback too, which meant a project member could aim a destination at services on the private network.

Now a destination must be https and resolve to a public address, checked when it is saved and again before every attempt, whatever address the server listens on. The worker also ignores proxy settings from its environment, so a delivery can’t go around the check through a proxy.

For local development only, opt in explicitly; the server says so in its start-up log:

Terminal window
COLOPHON_ALLOW_PRIVATE_DESTINATIONS=1

The other development shortcuts got the same treatment. COLOPHON_DEV_MAIL=1, which hands sign-in links back in responses, and the development identity provider’s public client secret are refused at start-up unless the server listens on loopback and COLOPHON_PUBLIC_URL names localhost, a *.localhost name or a loopback address.

Read more: Website connections · Configuration

SecurityAPISelf-hosting

Anonymous live streams have their own budget and can't crowd out editors

The public live stream, GET /content/v1/{project}/{environment}/events, needs no credential. Its streams used to count against the same per-project and per-server limits as the Studio’s own live updates, so enough anonymous streams could stop editors from getting live updates, and one client could take the whole budget.

Now anonymous streams are counted on their own, and each client address has a cap (IPv6 counted by its /64). Editors’ streams never compete with them. Hints still travel the same way, so a published change costs the same to announce.

Setting Default Over it
COLOPHON_EVENTS_PUBLIC_PER_ADDRESS 8 429 rate_limited with Retry-After
COLOPHON_EVENTS_PUBLIC_PER_PROJECT 256 503 unavailable
COLOPHON_EVENTS_PUBLIC_MAX_STREAMS 2048 per server 503 unavailable

A site that fans one upstream stream out to its own visitors holds one stream per site server, well inside the per-address cap. Behind a reverse proxy, set COLOPHON_TRUSTED_PROXIES so each visitor is counted by their own address rather than the proxy’s.

Read more: Live events · Configuration

BreakingAPISDK

Delivery rows name the exact image versions a release published

Old behaviour: sites built image addresses that always served an upload’s newest version, with no size. Replacing an image changed published pages at once, without anyone publishing.

New behaviour: a release records the version of every upload its entries name, in asset fields and rich text. Each /content/v1 row now carries media, keyed by asset id: url (that version’s immutable address, cacheable for a year), current_url (follows replacements), type, width, height and renditions (w320, w1280 when the original is wider). A replaced image reaches url at the entry’s next publish; pinned reads with ?generation= and rollbacks show that release’s images. Absolute addresses use COLOPHON_MEDIA_URL, which defaults to COLOPHON_PUBLIC_URL. Cached delivery answers are refetched once.

What to do: use url for “what was published” or current_url for “always the newest”, and republish entries whose images you replaced. With the SDK, mediaFor(row) gives the renderer each image’s width, height, srcset and sizes:

import { mediaFor } from '@colophon-cms/sdk';
import { renderToHtml } from '@colophon-cms/rich-text';
const html = renderToHtml(row.content.body, { assetUrl, media: mediaFor(row) });

Read more: Delivery API · Media library · TypeScript SDK

FixAPIStudio

The releases list pages past the newest 100, and the OpenAPI document matches the routes

GET /api/v1/projects/{project}/environments/{environment}/releases used to stop at the newest 100 releases with next_cursor always null, although the OpenAPI document described a cursor. It now pages for real: ?limit= takes 1–100 (default 100, what it answered before, so callers that never page see no change) and ?cursor= takes the next_cursor of the previous page. A release published while you walk the pages lands above the first page, so a walk never skips or repeats one.

Terminal window
curl "http://localhost:8080/api/v1/projects/{project}/environments/{environment}/releases?limit=50&cursor=<next_cursor>" \
-H "Authorization: Bearer $COLOPHON_TOKEN"

The MCP server’s list_releases tool takes the cursor too, and the Studio’s Releases page has Show older releases.

The OpenAPI document now says only what each route does. A list that pages names the parameter its next_cursor goes back in; a list that always answers in one page says what that page holds and types next_cursor as always null. A release’s receipt lists every release field directly, with the release, delivery and observation fields marked required. The SDK’s generated types follow the corrected document.

Read more: Management API · API reference

BreakingAPIStudio

Images inside rich text must name real uploads from the media library

Old behaviour: the server checked only a rich-text image’s shape. Any assetId was saved, so an image could name nothing at all, publishing never checked it, and its upload could be deleted while a page still showed it. The Studio’s old image dialog inserted a random placeholder id.

New behaviour: each image is tracked like an asset field: checked at publish, kept from deletion while used, and listed under “Where it’s used”. A save naming an id that isn’t an upload of the environment is refused at that image:

{"error": {"code": "validation_failed", "message": "…",
"details": {"reason": "asset_not_found",
"pointer": "/body/doc/content/3/attrs/assetId"},
"request_id": "…"}}

A document may name at most 200 distinct images (too_many_images). In the Studio, images come from the media library: pick, search or upload one, then give alt text, which is required. A pasted or dropped image is uploaded and inserted.

What to do: drafts holding placeholder images are refused at their next save. Open each one: the Studio marks the image in place with Replace and Remove. Revisions saved before this change pin their images only once saved again.

Read more: Rich text and images · Media library

FeatureSDK

The SDK checks it fits the server, and the rich-text renderer becomes its own package

@colophon-cms/sdk now says plainly when the server it talks to is too old or too new. Before its first call it reads GET /version once and judges it by the same rule as the colophon CLI: the server must serve API v1, share the SDK’s minor version before 1.0, and be at least the oldest server the SDK supports. The new compat option decides what happens: 'warn' (the default) logs the reason and never delays a call, 'throw' fails every call with an incompatible_server error, 'off' never asks.

import { Client } from '@colophon-cms/sdk';
const client = new Client({ baseUrl: 'http://localhost:8080', compat: 'throw' });
const fit = await client.compatibility();
if (!fit.compatible) console.error(fit.reason); // which side to upgrade, and to what

The renderer the Studio uses is now @colophon-cms/rich-text, a package with no dependencies whose renderToHtml turns stored rich text into escaped HTML, so your site renders exactly what editors previewed.

Both packages are prepared for their first npm release, not yet published: every push checks the files they would ship, their size (the browser client is about 4.5 KB compressed), their type declarations, and a scratch project that installs and compiles them.

Read more: TypeScript SDK · Rich text and images

BreakingSelf-hosting

A database on another machine needs sslmode=verify-full, and on/off settings are strict

Old behaviour: the server had no TLS for PostgreSQL: a remote URL without sslmode connected in plain text, and one asking for TLS could not connect. On/off settings with values such as yes or on were quietly read as “off”.

New behaviour: the server and the colophon admin commands refuse to start when COLOPHON_DATABASE_URL or COLOPHON_MIGRATION_DATABASE_URL names another machine with anything but sslmode=verify-full. require accepts any certificate, so anyone on the network path could answer as your database; verify-ca here accepts any publicly trusted certificate, for any name. channel_binding=require is refused on any host, because the driver would silently ignore it. The error names the problem and the fix, never the URL. A loopback host or a Unix socket needs no certificate, as before.

On/off settings now take only 1, true, 0 or false; anything else stops the server at start-up with a message naming the setting.

What to do: change a remote database URL to verify-full, adding sslrootcert if your database uses a private certificate authority:

Terminal window
COLOPHON_DATABASE_URL="postgres://colophon_app@db.internal:5432/colophon?sslmode=verify-full&sslrootcert=/etc/colophon/db-ca.pem"

If you copied a hosted provider’s URL with sslmode=require&channel_binding=require, replace both parameters with sslmode=verify-full.

Read more: Database TLS · Configuration

SecurityAPISelf-hosting

Sign-in pauses the guesser, not the account, and password work has a ceiling

Several fixes to staff and site-user sign-in, all on main:

  • Guessing no longer locks out the owner. Eight misses used to pause the account itself, and a pause answered differently from a wrong password. Now misses pause the (account, client address) pair for fifteen minutes; IPv6 clients count by their /64. Fifty misses in an hour from addresses the account never signed in from pause those addresses only; the owner’s own addresses keep working.
  • A pause looks like a miss. 409 too_many_attempts is gone: a paused attempt answers 400 sign_in_failed, as a wrong password or a missing account does. A site user’s 403 account_disabled now comes only with the right password.
  • Password hashing is bounded. At most COLOPHON_PASSWORD_CONCURRENCY hashes run at once (one per core by default); a short queue waits, the rest answer 503 unavailable with Retry-After, and no hash holds a database connection, so a sign-in flood can’t starve delivery.
  • Small bodies before sign-in. Sign-up, sign-in, the device flow and magic-link requests read at most 16 KiB; more answers 413 payload_too_large.

If clients branch on too_many_attempts, treat sign_in_failed as the only refusal. Behind a reverse proxy, set COLOPHON_TRUSTED_PROXIES, or every client looks like the proxy.

Read more: Authentication & API tokens · Errors · Security

FixStudio

The Studio no longer shows stale lists after a live update, or closes an entry when a refresh fails

Two Studio bugs that showed up on slow connections and under load are fixed.

Lists could stay stale until a reload. When a live change arrived while a page was still loading a list for the first time, the Studio joined the read already in flight instead of sending a new one. If that read had left before the change committed, its old answer stood: a release’s deliveries, for example, kept saying “pending” after the job had finished. Now every live change, resync and catch-up cancels matching reads in flight and reads again, so the list always reflects the change that triggered it.

An open entry could vanish. After a save, the Studio refreshes the entry. If that refresh failed, for example because a burst of requests hit the rate limit, the editor was replaced by the error screen, heading and all. Now the error screen appears only when there is nothing to show yet; a failed refresh leaves the editor, and your work, where they are.

Nothing to configure: both fixes are in the Studio served by the server.

Read more: Live events · Writing in the Studio

ImprovementPerformance

Opening an entry no longer slows down as a project fills up with entries

Every read of a draft also lists its translations (the localizations on GET /api/v1/projects/{project}/environments/{environment}/collections/{collection}/entries/{entry}). In a project that had just been filled with entries, PostgreSQL could plan that lookup as a comparison of every entry with every other one. In load tests a single entry read then took 0.5–0.7 seconds, and the entries load test failed with 2–4 second latencies.

The lookup is now two direct reads: the entry by its key, then, only if it belongs to a group of translations, that group by its key. An entry without translations, the usual case, costs one key lookup, and a translated entry’s read grows with the size of its own group, never with the size of the project.

What you notice: entry pages in the Studio, and draft reads over the API, stay as quick in a project of thousands of entries as in a small one, including right after a large import, before the database has refreshed its statistics. A test now fills a project with 1,500 entries and reads translations twenty times each within 250 ms; it took 1.1 seconds before the fix.

Nothing to change on your side.

Read more: Languages

FixAPI

Collections with a hyphen in their name get a cache tag, so CDN purges reach their lists

Delivery answers carry a Cache-Tag header so a CDN connection can purge exactly what a release changed. A list page’s tags include one for its collection, but that tag was only made for names of lowercase letters, digits and underscores. Collection names may also contain hyphens, so a collection such as release-notes got no collection tag. After a release, the purge missed its list pages, and a CDN kept serving the old list until it expired (up to 30 seconds).

The rule for a collection tag is now exactly the rule for a collection’s name, hyphens included. A name no collection could have still gets no tag, so text from a URL never reaches the header.

GET /content/v1/{project}/{environment}/release-notes HTTP/1.1
Host: localhost:8080
HTTP/1.1 200 OK
Cache-Tag: …, colophon:p:<project id>:e:<environment id>:c:release-notes

Nothing to change on your side: the next release purges these lists along with everything else, and the tags do not depend on the generation, so purges cover answers cached from earlier releases too.

Read more: Website connections · Delivery API

FeatureAPIStudioSelf-hosting

Sign in with email and password; an identity provider is now optional

Colophon no longer needs an OpenID Connect provider. Built-in email-and-password accounts are the default way to sign in to the Studio, and OIDC is an adapter you add only if you want single sign-on.

POST /auth/signup makes an account (password at least 8 characters) and starts its session; an existing email answers 409 email_taken. POST /auth/signin answers 204 with the session cookies. A wrong password and a missing account get the same 400 sign_in_failed, so the form never reveals who has an account. GET /auth/providers answers {"data": {"sso": false}} when no provider is configured, and the Studio hides the single sign-on button accordingly.

Operators can make accounts from the terminal. colophon admin account creates or resets one, and --admin makes it an administrator; colophon admin bootstrap --issuer password --subject <email> makes the first administrator without a provider.

Terminal window
export COLOPHON_MIGRATION_DATABASE_URL=postgres://…
COLOPHON_ACCOUNT_PASSWORD='…' colophon admin account \
--email editor@example.com --admin

Re-running the command replaces the password, so it doubles as a recovery tool.

Read more: Authentication & API tokens · Installation

ImprovementSelf-hosting

Queued work is bounded per project and per installation, and dead rows are swept hourly

Two bounds now stop queued work growing without end. A project holds at most 10,000 unfinished jobs across delivery, uploads, bulk edits and schema migrations, and an installation holds at most 1 GiB of pending job data such as keys, manifests and migration plans. A request that would pass either bound is refused before anything is stored: 503 unavailable with Retry-After and details.reason work_full or payload_full. Work drains as workers finish it, so retrying after the delay is the fix.

The worker also sweeps dead state every hour (COLOPHON_TABLE_SWEEP_MS), at most 500 rows a table per pass, oldest first: finished jobs, schedules, probe observations and idempotency records after 30 days; the audit log, settled budget records, and sessions, personal tokens, invitations and setup codes 90 days after they lapse.

Why it matters: a stuck destination or a runaway script can’t fill the database, and a long-running installation stays the size of its content. History is never swept: revisions, publications, tombstones, comments, tasks and the deletion ledger stay, and open or uncertain budget records are kept.

{"error": {"code": "unavailable", "message": "…", "request_id": "…",
"details": {"reason": "work_full"}}}

Read more: Errors · Configuration

FeatureAPI

Published content has a public live stream, so open pages refresh without a rebuild

A site can now hear when something is published. GET /content/v1/{project}/{environment}/events is an anonymous server-sent-events stream: it sends hello once, then a change frame each time a release lands in that environment. Draft saves never reach it, and a burst of release activity folds into one frame.

The frame carries nothing but its own existence: no ids, no collections, no content. A reader only learns to re-read the delivery API with whatever credentials it already has, so gated entries cannot leak through the stream. The answer is Cache-Control: no-store, and the stream ends after its lifetime so clients reconnect.

The intended shape is one stream per site server, not per visitor: your server listens once and tells its open browser tabs to refresh, which keeps the CMS’s stream count proportional to sites, not readers.

Terminal window
curl -N http://localhost:8080/content/v1/{project}/{environment}/events
event: hello
data: {}
event: change
data: {}

On each change, fetch the page’s data again from /content/v1; the new answer names the new generation.

Read more: Live events

FeatureAPIStudio

Replace an upload with new bytes, and every earlier version stays addressable

An upload can now be replaced. POST /api/v1/projects/{project}/environments/{environment}/assets/{asset}/replace takes the new file with the same headers as an upload and answers 202. The worker checks the new bytes like any upload, and only if they pass does the asset’s current version move to them; a refused file leaves the current version serving. Only a usable asset takes a replacement.

Why it matters: each verified version is stored under its own SHA-256 and never overwritten, so bytes a release published can’t be silently replaced or deleted while anything pins them. GET …/assets/{asset} lists every verified version, oldest first, and the media origin serves both kinds of address: /media/v1/{project}/{environment}/{asset} for the current version, and …/{asset}/{sha} for one exact version, with its renditions under …/{sha}/{name}.

The same day, the Studio gained a Media page in the project sidebar: every upload with its thumbnail, state, dimensions and size, uploading, and a confirmed delete that names the entries still using a file.

Terminal window
curl -X POST http://localhost:8080/api/v1/projects/{project}/environments/production/assets/{asset}/replace \
-H "Authorization: Bearer $COLOPHON_TOKEN" -H "Content-Type: image/webp" \
-H "X-Colophon-File-Name: hero.webp" -H "Idempotency-Key: $(uuidgen)" \
--data-binary @hero.webp

Read more: Media library

FeatureAPIStudio

Site users and gated content: visitors sign up, and each entry says who may read it

A project can now have an audience: site visitors with accounts of their own, separate from staff. They sign up and sign in with email and password at /audience/v1/{project}/signup and /signin, getting a session as a cookie or as the session token for a bearer header; /me and /signout complete the set. Staff manage audience roles, users and their sessions under /api/v1/projects/{project}/audience/… with the audience.manage permission. Signup may choose only a role marked self_assign.

Every entry now carries a visibility, set with ?visibility= on a create or save: public (the default), authenticated, or role:<name>. A release publishes the gate its revision carried, and PostgreSQL row-level security enforces it in delivery. Anonymous readers see public rows only; a gated row answers 404, like one never published. A visitor’s read bypasses the shared cache (Colophon-Cache: bypass, Cache-Control: private), so gated content never enters it.

In the Studio, the sidebar’s People group now holds Members and a new Audience page (visitors, roles, disabling, sign-in activity), and visitor sign-ups and sign-ins are recorded in the audit log.

Terminal window
curl http://localhost:8080/content/v1/{project}/production/posts \
-H "Authorization: Bearer $SITE_SESSION"

Read more: Delivery API · Authentication & API tokens · Members and roles

SecurityAPI

An API token can never approve a publish request that a token submitted

A project API token can no longer approve a publish request (changesets in the API) that any API token submitted. An approval sent to POST /api/v1/projects/{project}/environments/{environment}/changesets/{changeset}/reviews answers 403 with details.reason agent_self_review, at the single review and at every named review stage alike.

Why it matters: a token holding both review and publish permissions could otherwise submit, approve and publish its own work with no person involved. Checking only for the same token would not help, because a second token costs nothing to make, so the rule looks at the kind of credential on both sides. It runs on the server, inside the review’s own transaction, so it holds for MCP clients, scripts and any other HTTP client alike.

What a token may still do: ask for changes on any publish request ("decision": "request_changes"), approve a person’s publish request when its permissions include content.review, and publish a request a person approved when it holds content.publish. People reviewing their own requests are not affected.

{"error": {"code": "forbidden", "request_id": "…",
"message": "an API token can't approve a changeset an API token submitted; it needs a person's approval",
"details": {"reason": "agent_self_review"}}}

Read more: MCP server · Authentication & API tokens

FeatureAPI

API tokens can carry limits: requests a minute, and writes and jobs a day

A project API token can now carry limits, set when it is created or later with PATCH /api/v1/projects/{project}/tokens/{token}. Every ceiling is optional:

  • requests_per_minute (1–100,000): past it, the token’s requests answer 429 rate_limited with Retry-After.
  • documents_per_day (1–1,000,000) counts entry creates, saves, translations and imported items over a rolling day; max_concurrent_jobs (1–64) caps the delivery jobs its publishes hold at once. Past either, the write is refused with 403 and details.reason budget_exceeded before it commits.
  • tokens_per_day and cost_per_day_micros are ceilings for model-provider usage; they are stored and reported, and no Colophon feature consumes them today.

Why it matters: a looping script or agent can’t flood the API or rewrite a project overnight. Budgets are counted in PostgreSQL inside the transaction that accepts the work, so parallel requests can’t overspend them. People are never limited this way.

GET …/tokens/{token} shows the limits and current usage; {"limits": null} removes them. Token management takes a person’s credential:

Terminal window
curl -X PATCH http://localhost:8080/api/v1/projects/{project}/tokens/{token} \
-H "Authorization: Bearer $PERSONAL_TOKEN" -H "Content-Type: application/json" \
-d '{"limits": {"requests_per_minute": 60, "documents_per_day": 500}}'

Read more: Rate limits · Authentication & API tokens

FeatureAPI

Bulk edits as a manifest of exact entries, applied one item at a time

POST /api/v1/projects/{project}/environments/{environment}/bulk takes a manifest for one collection: up to 100 items and 1 MiB a chunk, up to 10,000 items a job. Each item names a stable key, the entry, the expected_revision the change is based on, and an op: update with new content, set one field, move a value, or delete. Later chunks go to …/bulk/{job}/items under If-Match, and seal starts the run.

Why it matters: a worker applies each item in its own transaction, as the person or token that submitted it, rechecking permissions and the base revision. An entry edited since gets conflict, never an overwrite. Outcomes are applied, conflict, refused or skipped, and a retried chunk adds nothing twice. Revoking the submitting token, or removing the member, stops the run. An interrupted client reads GET …/bulk/{job}/items in key order and carries on from there; POST …/bulk/{job}/cancel skips what is still pending.

Bulk jobs change drafts only; publishing stays a publish request.

{"collection": "posts", "seal": true, "items": [
{"key": "retag-1", "entry": "<entry id>", "expected_revision": "<revision id>",
"op": {"op": "set", "path": "section", "value": "News"}}
]}

Read more: Management API

FeatureCLI

Every CLI command's JSON output is one versioned envelope, and lists stream line by line

Every colophon command’s --json now prints one object of a fixed shape: {"version": 2, "command": "content list", "data": …} on success, and the same object with error in place of data on failure. An API refusal is carried whole (code, message, details, request_id), so a script reads exactly what the server said, and the exit code still names the class of failure: 2 usage, 3 denied, 4 conflict, 5 unavailable, 6 internal.

List commands take --jsonl and print one envelope per item, following next_cursor page by page without holding more than a page in memory: content list, content query, release list, migration list, migration items, comment list and task list.

New the same day: colophon content query runs a query document against a collection; colophon release list and colophon release show GENERATION read releases and their receipts; and colophon mcp serves the MCP server on standard input and output, configured by COLOPHON_SERVER, COLOPHON_TOKEN and COLOPHON_PROJECT.

Terminal window
colophon content list posts --project my-site --jsonl | jq -r '.data.id'
colophon release show 12 --project my-site --json

Read more: The colophon CLI

FeatureAPIStudioCLI

Comments pinned to the version you read, and tasks for the editorial team

Editors can now discuss an entry and hand work to each other inside Colophon.

A comment is anchored to one saved version (revision) of an entry, and optionally to a field such as author or sections/2/byline. Revisions never change, so a comment always refers to exactly what its author was reading, even after the draft moves on. Comments are kept word for word: they can be resolved and reopened, never edited or deleted. A task names an entry (and optionally a revision or a publish request), has a title, an assignee and a status of open, done or cancelled, and is changed under If-Match, so two people can’t overwrite each other’s update (409 task_moved).

Both follow the entry’s own permissions, including “only their own” roles, and stay readable after the entry is deleted.

In the Studio, the entry editor has a Comments tab for the version on screen, and the project has a Tasks page. From the terminal:

Terminal window
colophon comment create posts {entry} --project my-site --revision {revision} --field title --body "Shorter, please?"
colophon task create --project my-site --entry {entry} --title "Check the quotes" --assignee {identity}
colophon task list --project my-site --assignee me --status open

The API routes are …/entries/{entry}/comments (with /resolve and /reopen) and …/tasks.

Read more: Comments and tasks

FeatureSelf-hosting

Encrypted backups with continuous WAL archiving, and a staged restore that holds unsent work

The backup tooling shipped with Colophon now captures encrypted base backups of the whole PostgreSQL cluster, with continuous WAL archiving (a segment at least every minute) aimed at a 15-minute recovery point. Backups run as a replication-only database role, are encrypted from a passphrase file, and are checked with pg_verifybackup at capture and again after decryption. The daily run creates and verifies a backup, copies the deletion ledger beside it, keeps the newest verified backup of each of the last 7 days and 4 weeks, and writes an audit line. A backup that fails verification is never pruned.

A restore runs on clean, separate infrastructure in six stages, each gated on the last: decrypt, verify the schema against the binary, start a new recovery epoch so old cache generations and worker leases can’t act, replay deletions made after the backup, hold every unfinished delivery job, then serve.

Why it matters: a restore can’t fire a webhook twice or bring a deleted entry back. The database steps are CLI commands:

Terminal window
colophon admin migrate-status # current, behind, or exit 4: the schema is newer than this binary
colophon admin restore jobs # what was held, for you to reconcile
colophon admin restore resume # only after reconciling

Read more: Backups and restore

FeatureAPI

Read drafts with GraphQL, through the same query engine as REST

Each collection now answers GraphQL at POST /api/v1/projects/{project}/environments/{environment}/collections/{collection}/graphql, with a body of {"query", "operationName"?, "variables"?} and a query of at most 8 KiB. The schema is built for each request from your content types and your role: entries(where, orderBy, first, after) returns nodes, pageInfo { endCursor hasNextPage } and applied { query queryHash }, and entry(id) returns one draft or null. Collections the role can’t read are not in the schema.

Why it matters: this is not a second read path. Every call compiles to the same bounded query document that POST …/entries/query runs, through the same permission checks, so both answer the same rows with the same queryHash. where and orderBy take only fields the content type marks as indexed, and a refusal arrives as a GraphQL error whose extensions.code and extensions.pointer are the codes REST uses.

GraphQL is read-only: writes stay on REST with If-Match and Idempotency-Key, and public reads stay on /content/v1.

{
entries(where: { section: { eq: "News" } }, orderBy: [{ field: rating, dir: DESC }], first: 10) {
nodes { id title author { title } }
pageInfo { endCursor hasNextPage }
}
}

Read more: GraphQL

FeatureAPICLI

Export a collection as JSON Lines and import it back, or bring entries from Strapi and Sanity

GET /api/v1/projects/{project}/environments/{environment}/collections/{collection}/export streams every draft of a collection as JSON Lines (application/jsonlines), one content document per line. POST …/import takes that file back, or a JSON array, a Strapi v4 or v5 export, or Sanity’s NDJSON, mapping each document onto your content type’s fields. Up to 512 items land in one transaction, or none do. An item carrying the id of a live entry updates that entry’s draft; the rest are created.

Why it matters: moving content between projects, or in from another CMS, no longer needs a script per source. ?dry_run=true runs the whole import and rolls it back, answering a plan per item (would_create, would_update, skipped, or invalid with its refusal) plus any unmapped fields, and needs no Idempotency-Key. A real import requires one, so a retry can’t import twice. ?type= takes one Sanity _type from a mixed file. An export needs a role that reads every field.

From the terminal:

Terminal window
colophon content export posts --project my-site > posts.jsonl
colophon content import posts --project my-site --file posts.jsonl --dry-run
colophon content import posts --project other-site --file sanity.ndjson --type post

Read more: Management API · The colophon CLI

FeatureAPIStudio

The Studio's lists update live as other people work, over a server-sent events stream

When a colleague saves an entry, opens a publish request or publishes a release, your Studio now shows it without a reload or a poll: entry lists, publish requests, receipts, tasks and the rest refresh themselves within moments of the change committing. A save on an entry you have open is still a conflict for you to resolve, never a silent overwrite.

The same stream is open to your own tools. Any member or project API token can subscribe:

Terminal window
curl -N http://localhost:8080/api/v1/projects/{project}/environments/{environment}/events \
-H "Authorization: Bearer $COLOPHON_TOKEN"

It sends hello, then a change frame naming only what kind of thing changed, such as {"k":"entries","c":"posts"}, never an id or any content. Refetch through the API you already use, so what you see is what your role may read. If hints may have been missed, the stream sends resync: reload what you show. It never replays.

Streams are bounded: past 8 for one credential the answer is 429 rate_limited with Retry-After, and past the project’s or server’s limit, 503. A stream ends cleanly after 30 minutes so clients reconnect, and a member removed from the project, or a revoked token, loses the stream within minutes.

Read more: Live events

FeatureAPI

An OpenAPI 3.1 document describes every route, served at /openapi.json

Colophon now serves an OpenAPI 3.1 document for its whole HTTP surface: the management API under /api/v1, sign-in under /auth, /me, public delivery under /content/v1, media under /media/v1, the health checks, /version and the document itself. It is emitted from the same route table the server’s router is built from, so a route can’t exist without being described, and a described route can’t be missing. A copy is kept in the repository, and a test fails when the two differ.

Why it matters: you can generate a typed client, browse the API in any OpenAPI viewer, and check a request’s shape before writing code. Every failure points at the one error envelope, and each kind of credential has its own security scheme.

How to use it: GET /openapi.json needs no sign-in. It answers with Cache-Control: public, max-age=300 and an ETag; send that back in If-None-Match and an unchanged document answers 304 Not Modified.

Terminal window
curl -s -D - -o openapi.json http://localhost:8080/openapi.json | grep -i etag
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8080/openapi.json \
-H 'If-None-Match: "<etag from above>"' # 304

Read more: API reference

FeatureAPI

Filter, sort and select fields with one query document, on drafts and published content

Collections can now be queried with a small JSON document posted to …/query: filters (eq, in, lt, lte, gt, gte, contains), sort, fields, limit and depth. The same document runs on published content at /content/v1 (pinned to a release with ?generation=) and, for signed-in callers, on current drafts at POST /api/v1/projects/{project}/environments/{environment}/collections/{collection}/entries/query.

Terminal window
curl -X POST "http://localhost:8080/content/v1/{project}/{environment}/posts/query" \
-H "Content-Type: application/json" \
-d '{"filters": [{"field": "category", "op": "eq", "value": "travel"}],
"sort": [{"field": "published_on", "dir": "desc"}],
"fields": ["title", "author"], "limit": 10, "depth": 1}'

Queries stay fast and predictable because they are bounded: you can only filter or sort on fields the content type marks "index": true (field_not_indexed otherwise), with at most 8 filters and 4 sort keys. depth (0–2) replaces each top-level single reference with the linked entry’s id, title and content. Every answer echoes the canonical query and its query_hash in applied, and next_cursor only works for that same query (foreign_cursor).

On drafts, results respect field-level permissions: filtering or sorting on a field your role can’t read is 422 field_not_readable, and hidden_fields names what a row left out.

Read more: Delivery API · Management API

FeatureAPI

Agents can reach the MCP server over HTTP, signed in with a project API token

The API itself now serves Colophon’s MCP server at POST /api/v1/projects/{project}/environments/{environment}/mcp, over MCP’s Streamable HTTP transport (protocol 2025-11-25). An agent host that supports remote servers points at that URL with a project API token; nothing else needs installing.

Why it matters: it is the same server as the local colophon mcp process, not a second one. Tools, answers and refusals are identical on both, and every tool call runs through the API’s own routes under the same token, so the boundary holds: agents read, query and write drafts, comments and tasks, and open publish requests, but never approve, publish or drive a migration.

How it works: the first initialize answers with an Mcp-Session-Id header, which later requests send back with MCP-Protocol-Version: 2025-11-25; DELETE on the same URL ends the session. Only project API tokens may connect: a browser session or personal token answers 403 with reason api_token_required. Sessions are capped per token (429) and per project and server (503), expire when idle, and stop working when the token is revoked.

Terminal window
curl -X POST http://localhost:8080/api/v1/projects/{project}/environments/production/mcp \
-H "Authorization: Bearer $COLOPHON_TOKEN" \
-H "Accept: application/json" -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"demo","version":"1"}}}'

Read more: MCP server

FeatureAPIStudio

Review stages: several named approvals before a publish request can go live

An environment can now name an ordered list of review stages, such as Editor, Legal and Fact-check. A publish request (changesets in the API) publishes only once every stage has an approval on its current content, in any order. A request for changes at any stage blocks it until a newer approval clears it, and any edit to the content makes earlier approvals stale, as before. A stage marked different_reviewer can’t be approved by the person who made the request. An environment with no stages keeps the single review it always had.

In the Studio, Settings → Review stages edits the list, and a publish request’s page shows each stage in order with its state (pending, changes_requested, approved or approval_expired) and who decided it. Every review names the stage it decides.

Through the API, replace the whole list under its ETag (you need permission to change the schema):

Terminal window
curl -X PUT http://localhost:8080/api/v1/projects/{project}/environments/{environment}/review-stages \
-H "Authorization: Bearer $COLOPHON_TOKEN" -H 'If-Match: "sha256:…"' \
-H "Idempotency-Key: stages-2026-11-0001" -H "Content-Type: application/json" \
-d '{"stages": [{"key": "editor", "name": "Editor"},
{"key": "legal", "name": "Legal", "different_reviewer": true}]}'

A review then sends {"decision": "approve", "stage": "legal"}; leaving out stage where stages exist is 422 stage_required.

Read more: Publishing

FeatureAPIStudioCLI

Change a content type that existing entries don't fit: plan, dry run, approve, apply

A content-type change that stored entries wouldn’t pass (422 needs_migration) no longer has to stop at a refusal. You can plan a migration: Colophon dry-runs the new definition against every draft and open publication of the collection and lists each entry as ok or needs_input, with the problem it would hit. Nothing is written until the plan is approved and applied.

Approve and apply bind to the plan’s hash (its ETag), so you apply exactly what you looked at; if the plan has moved, the answer is 409 plan_moved. Applying answers 202 and a worker converts the entries one at a time, resuming after a crash without doing any twice. The plan ends done, or blocked with its reason, and republish_required lists the published entries to publish again. While it runs, the type can’t be changed elsewhere (migration_in_progress). For an entry the target can’t derive, give it a replacement with PUT …/migrations/{migration}/items/{entry}.

In the Studio, the type builder’s refusal offers Plan a migration for this change, and a Migrations section shows each plan’s counts, items and a resolve dialog. From the terminal:

Terminal window
colophon migration plan posts --project my-site --file posts-v4.json
colophon migration show {migration} --project my-site
colophon migration approve {migration} --project my-site --if-match <plan hash>
colophon migration apply {migration} --project my-site --if-match <plan hash>

Read more: Management API · The colophon CLI

FeatureSDK

A TypeScript SDK whose types come from the OpenAPI document

@colophon-cms/sdk is a TypeScript client for Colophon. Its types are generated from the committed OpenAPI document, with a check that fails when they drift; the client on top is small and hand-written. It covers what a site, tool or agent calls most: entries and revisions, content types, publish requests, releases and receipts, comments, tasks, and public delivery.

Why it matters: the types know which writes need a precondition, so saveEntry won’t compile without ifMatch and idempotencyKey, and a retried save can neither overwrite someone’s edit nor apply twice. Every failure is an ApiError with the error envelope’s code, requestId and details. The client attaches the credential you give it and never signs in by itself.

How to use it: the package is prepared for the first npm release; until then, build it from a checkout of the repository with npm run build -w @colophon-cms/sdk.

import { Client, newIdempotencyKey } from '@colophon-cms/sdk';
const client = new Client({ baseUrl: 'http://localhost:8080', token });
const env = client.environment(projectId); // production by default
const { data: draft, response } = await env.getEntry('posts', entryId);
await env.saveEntry('posts', entryId, { ...draft.content, title: 'New title' },
{ ifMatch: response.etag!, idempotencyKey: newIdempotencyKey() });
const site = client.delivery(projectId).atGeneration(42); // every read from one release

Read more: TypeScript SDK

FeatureAPIStudio

Upload images: verified before anyone sees them, served from a public media address

Colophon now stores images. An upload (PNG, JPEG or WebP, up to 20 MiB) lands in quarantine and answers 202 with state quarantined. A worker then checks the real file signature, decodes it within size limits, strips its metadata and promotes it to usable, or marks it rejected with a reason. A verified image also gets w320 and w1280 renditions when it is wider than those.

Terminal window
curl -X POST http://localhost:8080/api/v1/projects/{project}/environments/{environment}/assets \
-H "Authorization: Bearer $COLOPHON_TOKEN" -H "Idempotency-Key: upload-harbour-0001" \
-H "Content-Type: image/jpeg" -H "X-Colophon-File-Name: harbour.jpg" \
--data-binary @harbour.jpg

Content types gain an asset field: one upload’s id, or a bounded list with "many": true. A draft may name an image that is still being checked, but a release refuses one that isn’t usable (409 asset_not_usable), so readers only ever get verified bytes. Those are served without sign-in at GET /media/v1/{project}/{environment}/{asset} and …/{asset}/w320.

In the Studio, an image field is a picker: Choose an image opens the project’s uploads, shows each one’s state, and uploads a new file in place.

Deleting is staged: DELETE …/assets/{asset} answers 202 (requested, not gone), and is refused 409 still_referenced while a draft or any release names the image.

Read more: Media library

FeatureAPIStudio

Roll back to an earlier release, reviewed like any other publish

You can now restore what an earlier release published. A rollback is not a jump back in time: it opens an ordinary publish request (changesets in the API) that republishes every entry that release had live, and takes down entries that are live now but weren’t then. It is submitted, approved on its exact content and published like any other, and publishing it makes a new release with the next generation number. Your history stays whole, and the review rule still applies.

In the Studio, a release’s receipt has Roll back to this release for anyone who may update content, on any release before the current one. It opens the restore, and its page says which release it restores.

Through the API:

Terminal window
curl -X POST http://localhost:8080/api/v1/projects/{project}/environments/{environment}/releases/{generation}/rollback \
-H "Authorization: Bearer $COLOPHON_TOKEN" -H "Idempotency-Key: rollback-to-12-0001" \
-H "Content-Type: application/json" -d '{"title": "Rollback to release 12"}'

The answer is 201 with the publish request, whose rollback_generation names the release it restores. A generation outside the earlier releases is 422 invalid_generation; if nothing would change, 422 already_at. Content taken down since that release is not brought back.

Read more: Rollback · Publishing

FeatureStudio

A website starter: pages built from sections, a menu and a theme, with a Look tab

The Studio can now add a ready-made website structure to a project. On Content types, choose A website: a dialog lists what it will add and what is already there, then Add to this project creates a pages collection, a navigation single type, a theme single type and a seeded Home page.

Nothing here is new machinery. A page’s sections field is an ordinary page-sections field with six layouts (hero, rich text, features, testimonial, call to action, and questions and answers), the menu links to pages through reference fields that can’t dangle, and the theme’s colours, corner radii, shadows and fonts are an entry like any other. So pages and the theme get drafts, history, publish requests and releases, and republishing the theme changes the whole site’s look in one release. Running the starter again only adds what is missing.

Pages and the theme entry gain a Look tab beside Content and History. It shows the page exactly as the shared site renderer builds it, from the draft on screen (saved or not), the menu and the theme, and redraws as you type. Click a section to jump to its form. On the theme, the Look tab checks each colour pair’s contrast against WCAG AA.

Read more: Concepts · Preview

FeatureAPIStudio

Delete a collection you no longer need, once nothing of it remains

A collection can now be deleted for good, together with every version of its definition, and its name is free to use again. In the Studio, the content type’s page has a two-step Delete collection… button.

Deletion is only allowed while nothing of the collection remains, so no revision, publish request or release ever points at a type that has gone. The answer is 409 with a reason you can act on:

  • still_referenced: another content type has a reference field that links here; the message names it.
  • collection_not_empty: the collection still has entries; the message counts them.
  • collection_has_history: deleted entries left revisions that use its definition. Revisions are never rewritten, so a collection that has ever held an entry stays.

The request needs If-Match with the type’s ETag and an Idempotency-Key, so a retry after a lost answer replays the deletion instead of answering 404.

Terminal window
curl -X DELETE http://localhost:8080/api/v1/projects/{project}/environments/{environment}/content-types/drafts-old \
-H 'If-Match: "v3"' -H 'Idempotency-Key: delete-drafts-old-0001' \
-H "Authorization: Bearer $COLOPHON_TOKEN"

The answer is 200 with {"data": {"slug": "drafts-old", "removed": true}}.

Read more: Management API

FeatureAPIStudio

Two-way links: a reference field can be mirrored on the entries it points to

A reference field can now name an inverse: a reference field on the target collection that points back. When you link a post to a writer, the writer’s posts field gains the post in the same save; unlink it and the writer loses it; delete the post and it leaves every mirror.

This is the link editors reach for first (posts and writers, products and categories), and you no longer keep both sides by hand. Both sides commit together or not at all. The forward link stays the truth: if a mirror can’t be written, for example because the far field no longer points back, the forward save still succeeds and the link is simply one-way.

In the Studio, open the reference field’s settings and pick the field under Mirrored on … by. To offer one, first add a link back to this type on the other collection. In a definition:

{ "id": "writers", "label": "Writers", "type": "reference",
"to": "writers", "many": true, "inverse": "posts" }

Only top-level reference fields may mirror. The named field must exist on the target, be a reference, and point back at this collection; otherwise the definition is refused 422 invalid_inverse at /fields/{n}/inverse.

Read more: Linked entries

FeatureAPIStudio

Write an entry in several languages, one linked version per locale

An entry can now carry a locale tag such as en or pt-BR, and its translations are grouped together, one live entry per tag. Each translation is a full entry with its own draft, slug, history and publish requests, so the French version can be published while the German one is still being written.

In the Studio’s entry editor, Locale sets the entry’s own tag (empty means the project’s default), and the Versions card lists the group and adds one: type fr, choose Add version, and a copy of the current draft opens as its own entry, with a slug such as my-post-fr.

Through the API, ?locale= rides create, save and list, and a new translation is one request:

Terminal window
curl -X POST "http://localhost:8080/api/v1/projects/{project}/environments/{environment}/collections/posts/entries/{entry}/localizations?locale=fr" \
-H "Authorization: Bearer $COLOPHON_TOKEN" -H "Idempotency-Key: translate-post-fr-0001"

Drafts answer with locale and localizations (each sibling’s id and tag). The source needs a tag of its own before it can start a group (locale_required). A tag already in the group is 409 locale_taken, naming the entry that holds it; a malformed tag is 422 invalid_locale. Published rows don’t carry the tag: a site reads each translation as its own entry.

Read more: Languages

October 2026

FeatureAPIStudio

Project API tokens with an exact kill switch, and an append-only audit log

Scripts and integrations can now use a project API token instead of a person’s sign-in. A token is read-only, full-access or custom (its own permission list, like a role), expires in 1 to 366 days, and acts as an identity of its own, so what it writes is attributed to it. The secret, prefixed colophon_api_, is shown once in the create answer and stored only as a hash. No token can manage members, roles or tokens, or read the audit log.

POST /api/v1/projects/{project}/tokens
{"name": "Site build", "kind": "read-only", "expires_in_days": 90}

Send it as Authorization: Bearer colophon_api_…. It works on its own project’s /environments/… routes; elsewhere it gets 403 api_token_not_allowed, another project answers 404, and a revoked or expired token 401. DELETE /api/v1/projects/{project}/tokens/{token} revokes it exactly: requests already running finish, and nothing starts after.

Every change to roles, memberships, invitations and tokens is written to the audit log in the same transaction; the API can only add to it and read it. Owners read it newest first at GET /api/v1/projects/{project}/audit, filtered by action (such as token.revoked) and actor, with limit and cursor. In the Studio, both live in Settings: API tokens and Activity.

Read more: Authentication & API tokens · Studio settings

FeatureAPIStudio

Custom roles, down to single fields and a member's own entries

Roles are now data you can shape. Every project starts with four built-in roles, owner, developer, editor and publisher, with the powers they always had, and owners can add their own in Settings → Roles. A role is a list of permissions: an action such as content.update or content.publish, a subject (one collection, or * for all), an optional field list, and an optional own condition that limits it to entries the member created.

A field list works both ways. A save that changes any other field is refused with 422 field_not_permitted at that field’s pointer; a read leaves the other fields out and names them in hidden_fields. One evaluator decides for the API, the CLI and the Studio, and the Studio hides controls a role can’t use while the server still decides.

POST /api/v1/projects/{project}/roles
{"key": "copy-desk", "name": "Copy desk", "permissions": [
{"action": "content.read", "subject": "*"},
{"action": "content.update", "subject": "articles", "fields": ["title", "summary"]},
{"action": "content.update", "subject": "notes", "condition": "own"}]}

Roles change under If-Match ("v<version>"). Any caller can ask what it may do with GET /api/v1/projects/{project}/environments/{environment}/permissions. The Studio’s role editor is a grid of collections and actions, with a section for field lists and “only their own entries”.

Read more: Members and roles

FeatureAPI

Delete an entry, refused while anything still depends on it

Entries can now be deleted through the API. A deletion leaves a tombstone: the entry disappears from every read, list and history, its URL name and any unique values become free, and its earlier versions and past releases are kept untouched. It needs content.delete on the entry (or the own condition and an entry you created), the draft’s ETag as If-Match, and an Idempotency-Key, so a retry after a lost answer replays the same result.

Terminal window
curl -X DELETE \
http://localhost:8080/api/v1/projects/{project}/environments/{environment}/collections/posts/entries/{entry} \
-H "Authorization: Bearer $COLOPHON_TOKEN" \
-H 'If-Match: <the draft ETag>' \
-H "Idempotency-Key: $(uuidgen)"

The database refuses a deletion that would leave something dangling, and it decides every race. The answer is 409 with a reason:

  • entry_published: readers still get it, so take it down in a publish request first;
  • still_referenced: another entry links to it, listed in details.referenced_by (only collections you can read);
  • entry_in_changeset: an unpublished publish request holds it, scheduled or not, listed in details.changesets.

A successful deletion answers 200 with id, collection, revision_id, deleted_at and deleted_by, and is recorded in the audit log.

Read more: Management API

FeatureStudioSelf-hosting

Set up a new installation from the Studio with a one-time setup code

A new Colophon no longer needs someone with database access to make its first administrator. While nobody is an administrator, the server prints a one-time setup code to its terminal when it starts, never to the structured log or to any response. A signed-in person enters it on the Studio’s home page, which sends it to POST /api/v1/setup, and becomes the administrator.

POST /api/v1/setup
{"code": "XXXXX-XXXXX-XXXXX-XXXXX"}

The code lasts an hour, works once and is stored only as a hash. Attempts are limited (429 rate_limited with Retry-After), and wrong, used and expired codes all get the same 422 setup_code_invalid. Once anyone is an administrator the route answers 409 already_set_up, and later starts print nothing.

Alongside it, the Studio was reworked for editors who aren’t developers. Its words come from one glossary: a changeset is a publish request, a revision a version, a slug a URL name, destinations are website connections. A project’s first page is a short checklist (write, invite, connect the website, publish). Publishing one entry is one button: it publishes at once where the project lets you review your own work, and asks for review otherwise.

Read more: Quick start · Installation

FeatureAPIStudio

Groups, lists, page sections and shared components in content types

Content types can now hold structure, not only flat fields:

  • object groups nested fields, such as an address;
  • list holds up to 100 values of one kind (of), never a list or page sections;
  • blocks is a page builder: up to 100 items, each one of up to 20 named kinds of block with its own fields, marked by _block.

Structures nest at most three deep. A reference inside one is stored and checked like any other, with its path, such as sections/1/author.

{"id": "tags", "label": "Tags", "type": "list", "of": {"type": "text", "max_chars": 30}, "max": 3}

A shared component is a named group of fields that many content types reuse, such as an SEO block. Create one with POST …/components, then use {"type": "component", "component": "seo"} wherever an object can go; the server copies the component’s fields in, so every content type version stays a complete description of its content. Changing a component with PUT …/components/{slug} writes a new version of every content type that uses it, in one transaction and each checked against stored content. If one can’t take the change, nothing changes, and the refusal names that type.

The Studio’s builder makes groups, lists, page sections and components, and the editor fills them in.

Read more: Concepts

FeatureAPI

An MCP server lets AI agents draft content, but never approve or publish it

Colophon now has a Model Context Protocol server, so an agent host can give an AI agent typed tools over your content. It speaks MCP over standard input and output, and it is a plain client of the same /api/v1 the Studio and the CLI use, with a project API token as its only credential: an agent can do exactly what a script with that token can, and what it writes is attributed to the token.

Terminal window
COLOPHON_SERVER=http://localhost:8080
COLOPHON_TOKEN=colophon_api_…
COLOPHON_PROJECT={project}

Its tools read content types and entries, create and update drafts (sending the revision it read as If-Match), make a publish request and ask for its review. Writes carry an Idempotency-Key, and a refusal keeps the API’s reason and field pointer.

Agents stop at proposals. No tool approves, publishes, unpublishes or schedules, or manages roles, members or tokens, whatever the token itself may do. The tool list follows the token’s permissions, read from the new GET /api/v1/projects/{project}/environments/{environment}/permissions, which answers any caller’s own permissions. Listing a tool grants nothing: the API still decides every call.

Read more: MCP server

FeatureAPIStudio

Seven new field types: email, URL, date, time, JSON, Markdown and colour

Content types can now use email, url, date, time, json, markdown and color fields, beside text, rich text, number, yes-or-no, choice and date-time. Any field may carry a description (help text, up to 500 characters), and text fields a min_chars.

Each type keeps one stored form that a browser can reproduce, so what you send round-trips byte for byte:

  • url: http or https only, no credentials, stored as a browser’s new URL(text).href writes it;
  • email: checked for its shape, never for delivery;
  • date is YYYY-MM-DD; time is HH:MM or HH:MM:SS;
  • json: any value up to 64 KiB and 32 levels deep, keys sorted the way JavaScript sorts them;
  • markdown: multi-line text with max_chars, rendered by your site;
  • color: lowercase #rrggbb; an uppercase value is refused, not rewritten.
{"id": "contact", "label": "Contact", "type": "email",
"description": "Shown under the article"}

Changing a field’s type is checked against stored content: a text field can become an email field when every stored value is an address. The Studio’s builder offers every type, and the editor has a control for each.

Read more: Concepts · Writing in the Studio

ImprovementPerformance

Entry requests stop re-reading their content type's definition from scratch

Every entry read, save, list and history request checks content against its collection’s content type, and each one used to parse that definition again. Benchmarks showed the parse costing more than the entry’s own validation: 1.9 µs for a small type, 20.4 µs for a typical page type and 281 µs for a 100-field type, about half of it compiling text patterns.

Each server now keeps parsed content types in memory, keyed by the SHA-256 of the definition text it has just read from the database. A cache hit costs only that hash: 0.12 µs, 0.59 µs and 6.5 µs for the same three types. The definition itself is still read from the database on every request, so a cached parse can never be out of date: a changed content type is new text with a new key, and nothing needs to be invalidated.

The cache holds at most 1,024 types and 32 MiB of definition text, dropping the least recently used first; a definition larger than that is parsed every time and never kept.

Nothing changes in the API. Projects with large content types, many fields or text patterns see the biggest drop in time per request.

Read more: Management API

FeatureAPISelf-hosting

Rate limits counted once across every server, and safe to run several servers

Every request to the management API (/api/, /auth/) now counts against its client address and its credential, and every public delivery request (/content/) against its address at a higher rate. Health checks, /version and the Studio’s files never count. Over a limit, the answer is 429 rate_limited with Retry-After in seconds, before any work is done.

HTTP/1.1 429 Too Many Requests
Retry-After: 2
{"error": {"code": "rate_limited", "message": "…", "request_id": "…"}}

The counts live in Valkey, so several Colophon servers behind one load balancer share them. If Valkey is down or slow, each server applies the same limits on its own until it is back. Sessions, idempotency keys and caches were already shared, so any server can answer any request, and /readyz checks the database on a connection of its own, so a busy server isn’t marked unready by mistake.

Defaults are 300 requests a second (burst 600) per address, 150 (300) per credential and 1,000 (2,000) for delivery; change them with COLOPHON_RATE_LIMIT_PER_ADDRESS, COLOPHON_RATE_LIMIT_PER_CREDENTIAL and COLOPHON_RATE_LIMIT_DELIVERY (for example 300/600, or off). Behind a reverse proxy, list it in COLOPHON_TRUSTED_PROXIES so X-Forwarded-For names the real client; otherwise every visitor shares the proxy’s count.

Read more: Rate limits · Configuration

FeatureAPIStudio

Link entries with reference fields that can never point at nothing

A reference field links an entry to entries of one collection: one, or up to 100 with many. Each version stores its links and the database checks them, so an id that names no entry of that collection is refused with 422 reference_not_found at the field’s pointer.

{"id": "author", "label": "Author", "type": "reference", "to": "authors"}
{"id": "related", "label": "Related", "type": "reference", "to": "articles", "many": true, "max": 5}

Releases keep links whole too. Publishing an entry that links to one nobody has published is refused with 409 references_unpublished, and taking down an entry that a published entry still links to is refused with 409 still_referenced. Doing both in one release works.

An entry’s read now carries referenced_by, the entries that link to it, limited to collections your role can read, so nobody learns of entries they can’t open. Pointing an existing field at a different collection is refused.

In the Studio, a link field is filled by searching titles, an entry shows what it is Linked from, a refused link names the entries in the way and says what to do, and the Studio warns before a take-down that would be refused.

Read more: Linked entries

FeatureAPIStudio

Schedule a publish request for a local time in any time zone

An approved publish request can now go live later. You choose the date and time as a wall clock shows it and an IANA time zone; Colophon keeps both, with the instant they resolve to. A time the clocks show twice or skip at a daylight-saving change is refused with 422 ambiguous_local_time or skipped_local_time, with both possible instants in details.candidates; send "choice": "earlier" or "later" to pick one.

POST /api/v1/projects/{project}/environments/{environment}/changesets/{changeset}/schedule
If-Match: <the publish request's ETag>
{"local_time": "2026-12-01T09:00:00", "time_zone": "Europe/London"}

When it falls due, the worker publishes as the person who scheduled it, with every check a publish makes at that moment. An edit since approval, an expired approval, a role that can no longer publish or a URL name another entry holds blocks the schedule with the reason, and nothing is published. A run that starts more than a minute late is marked delayed, never reported as on time. API tokens can’t schedule.

GET …/schedules lists pending and recently finished schedules; DELETE …/schedules/{schedule} cancels one (409 schedule_ran if it already ran). In the Studio, a publish request has a Schedule panel and the Releases page lists what is scheduled.

Read more: Scheduling

FeatureAPIStudio

Single types for one-of-a-kind content like site settings or a home page

A content type marked "single": true holds at most one entry per environment: a site’s settings, its home page, its footer. The database is what enforces it, so however two creations race, the second is refused with 409 single_exists.

POST /api/v1/projects/{project}/environments/{environment}/content-types
Idempotency-Key: 6f1c…
{"slug": "settings", "definition": {
"name": "Settings", "title_field": "site_name", "single": true,
"fields": [{"id": "site_name", "label": "Site name", "type": "text", "required": true}]}}

You can make an existing collection single while it holds at most one entry; with more, the change is refused with 422 too_many_entries at /single. Making it plural again just clears the flag. Older definitions keep their hashes, because the flag is written only when it is true.

In the Studio, a single type opens straight to its one entry instead of a list.

Read more: Concepts

FeatureAPIStudio

URL names for entries, and a content-type builder that checks your content first

A content type can now have one slug field, which the Studio calls a URL name. A slug is 1 to 120 lowercase letters and digits in groups joined by single hyphens; anything else is refused with invalid_slug, never quietly rewritten. The Studio suggests one from the text field you name as its source. A slug belongs to one entry among drafts and one among what is published, and the database enforces it: a save gets 409 slug_taken, and a release that would publish a taken slug is refused whole.

{"id": "slug", "label": "URL name", "type": "slug", "source": "title"}

Changing a content type is now checked against what you have stored, not only against the old definition. Removing a field, making one required or narrowing a limit goes through when every draft and published version still fits; otherwise PUT …/content-types/{slug} answers 422 needs_migration and names the first 20 entries in the way.

In the Studio, Content types has a place of its own in the navigation, shown to roles that may change them. A type is one row per field; Add a field opens a picker grouped as Basics, Links, Structure and Advanced; each field’s settings open in a dialog, and changes wait behind one save bar.

Read more: Concepts · Studio settings

ImprovementStudio

The Studio starts from your work, and publishes several entries at once

The Studio’s home page is now Your work: for a project, the entries you started that aren’t live, publish requests waiting for review, what is scheduled (and why a blocked schedule stopped), and the latest releases. Inside a collection, Only mine narrows the list to the entries you started.

From a collection’s list you can pick several entries and publish them together as one release, or send them as one publish request for review if your role can’t publish. An entry can be duplicated, an earlier version restored with Restore this version (it becomes the newest version, nothing is lost), and a live entry taken down.

What changed for every screen:

  • refusals come from the API’s reasons and are said in plain words, with what to do next;
  • controls follow your role’s permissions, and navigation shows only what you can read;
  • a release’s receipt says what needs attention and the safe next step;
  • reviewing and publishing work on a phone;
  • Settings has a left panel of pages (General, Roles, Website connections, API tokens, Activity), and making something opens a dialog;
  • the entry page says where the entry stands once, in one line naming its release;
  • About Colophon in the account menu shows which server and version you are using, for a problem report.

Read more: Writing in the Studio · Publishing · History

FeatureAPIStudio

Field rules: unique values, text patterns, defaults and conditional fields

Four rules for fields, checked by the server for the Studio, the CLI, scripts and agents alike:

  • Unique. "unique": true on a top-level text, email, URL, number, date, time or date-time field. A value belongs to one entry among drafts and one among what is published, compared exactly as stored. The database enforces it: a save gets 409 value_taken, and so does a release that would publish a taken value.
  • Pattern. A text field’s pattern must match the whole value, in Rust regex syntax, which runs in time linear in the value, so no pattern can stall writes. A bad pattern is 422 invalid_pattern; a value that doesn’t match, 422 pattern_mismatch.
  • Default. default fills a field a new entry leaves out, on the server and only on creation, so a required field with a default may be left out.
  • Conditional. "when": {"field": "kind", "is": "video"} makes a field apply only while a yes-or-no or choice field holds those values; otherwise content must leave it out (422 not_applicable).
{"id": "duration", "label": "Duration", "type": "number",
"when": {"field": "kind", "is": ["video"]}}

Adding any of these is checked against stored content. The Studio’s builder sets them, its editor shows the allowed form, fills defaults into new entries and shows a conditional field only while it applies.

Read more: Concepts

FeatureAPICLI

Every server and CLI reports its version, and the CLI says when it doesn't fit

Colophon now has one version for the server, the CLI and the packages: 0.1.0-alpha.1, not yet released. GET /version reports the release, its git commit, its build date and the API versions it serves, needs no sign-in and is never rate-limited. Fields may be added to it, never removed or renamed.

Terminal window
curl http://localhost:8080/version
{"version":"0.1.0-alpha.1","commit":"…","build_date":"2026-10-28","api":["v1"]}

colophon --version and colophon-server --version print the same facts on one line.

Before any command that talks to a server, the CLI reads /version and stops with a plain explanation when the two don’t fit: the server must serve the API version the CLI speaks, and before 1.0 both must be on the same minor line, because a minor release may change the API. The message names both versions and says which one to install. colophon logout skips the check, so signing out always works.

Packaging is prepared for the first release but nothing is published yet: an npm launcher package with one binary package per platform, a Homebrew formula template and an install script.

Read more: API reference · The colophon CLI

ImprovementStudio

A redesigned Studio with entry states, title search, and comparisons for history and review

The Studio is rebuilt on a design system of its own: warm paper, black ink and one accent colour, Inter throughout, and light, dark and high-contrast schemes. State colours always come with a word, and motion switches off when your system asks for reduced motion. The sign-in page has the same look.

Every project page now sits in one shell: a sidebar with each collection and its entry count, publish requests waiting for review, and the live release with its label; breadcrumbs; and a command palette (⌘K) that finds entries by title across collections.

  • Entry states. A collection is a table with Draft, Changed and Live filters, worked out by comparing each draft with its published revision.
  • Title search runs on the server (q on the entries list), so it finds entries beyond the first page.
  • History. The editor compares any earlier revision with the draft (GET …/entries/{entry}/revisions/{revision} reads one).
  • Review. A publish request shows, for each entry, a word-level comparison of what readers have now and what they will get; for a take-down, what goes.

Why it matters: an editor can see what state each entry is in, and what a review is about to approve, without opening raw JSON.

Read more: Writing in the Studio · History

FeatureCLI

Sign the colophon CLI in from your browser, then create and list entries

colophon login starts a device sign-in. It prints a short code and a link to the Studio’s /studio/device page, where you, already signed in, see what is asking and approve it. The terminal then receives a personal token that acts with your own memberships for 30 days. The server stores only its hash; the CLI keeps it in credentials.json under COLOPHON_CONFIG_DIR, else $XDG_CONFIG_HOME/colophon, else ~/.config/colophon.

Why it matters: a terminal can’t hold a browser session, and the approval happens where you can see it. Codes last 10 minutes and the token is handed out exactly once.

Terminal window
colophon login --server http://localhost:8080
colophon whoami
colophon content create posts --project my-site --data '{"headline":"Hello"}'
colophon content list posts --project my-site --limit 20

content create writes the same validated draft the Studio would, with an idempotency key so a retry can’t create twice; it exits 2 when the content doesn’t fit its content type and 3 when you aren’t allowed. --profile keeps sign-ins for several servers apart, and colophon logout revokes the token and forgets it.

Read more: The colophon CLI

FeatureAPI

Define your own content types, versioned and checked against the content they hold

A project now defines its own content types. A definition has a name, the field that serves as each entry’s title, and 1 to 100 fields, each with an id, a label, whether it is required, and a type with its limits: text, rich_text, number, boolean, enum or datetime. The server validates every entry save against its collection’s definition.

Definitions are versioned and insert-only, and each revision records the version it was checked against. GET …/content-types/{slug} answers with ETag: "v<version>"; a change is a PUT with that value in If-Match, so two people editing one type can’t overwrite each other (409 stale_version). A change that would leave stored entries invalid is refused with 422 needs_migration, so every stored revision stays valid.

Terminal window
curl -X POST "http://localhost:8080/api/v1/projects/{project}/environments/{environment}/content-types" \
-H 'Authorization: Bearer …' -H 'Idempotency-Key: create-posts-type-01' \
-H 'Content-Type: application/json' \
-d '{"slug":"posts","definition":{"name":"Posts","title_field":"headline",
"fields":[{"id":"headline","label":"Headline","type":"text","required":true}]}}'

Entries then live under …/collections/posts/entries.

Read more: Concepts · Management API

FeatureAPIPerformance

Delivery answers are cached by release, with ETags and a header that says where they came from

/content/v1 answers are now cached in Valkey under keys that name their release generation. The generation itself is always read from PostgreSQL first, so a cached answer can’t come from the wrong release: a new release simply uses new keys. When many readers miss the same key at once, one request fills it and the others share its answer.

Every answer carries:

  • a strong ETag; send it back in If-None-Match to get 304 Not Modified;
  • Cache-Control for shared caches: 30 seconds for the latest release, 300 for a read pinned with ?generation=, and browsers always revalidate;
  • Cache-Tag with the entry’s and collection’s tags, which CDN purges use;
  • Colophon-Cache: hit, miss, coalesced (waited for another request’s fill) or bypass (read from PostgreSQL).
HTTP/1.1 200 OK
Colophon-Generation: 12
Colophon-Cache: hit
ETag: "…"
Cache-Control: public, max-age=0, must-revalidate, s-maxage=30

The cache is disposable. When Valkey is down or slower than 100 ms, reads go straight to PostgreSQL, bounded by its connection pool (503 with Retry-After when it’s full), and /readyz reports degraded rather than unready. Nothing is lost.

Read more: Delivery API

FeatureAPIStudio

Drafts that can't be lost: every save is a revision, guarded by If-Match and Idempotency-Key

Entries are drafts, and every save writes a new revision; revisions are insert-only, so nothing is overwritten. An entry’s ETag names its current revision, and a save sends it back in If-Match. If someone saved in between, the answer is 409 with details.reason stale_revision and the current ETag; a save without If-Match is 428.

Creates and saves also need an Idempotency-Key (16 to 128 letters, digits, - or _). A retry after a lost answer replays the recorded result with Idempotent-Replayed: true instead of saving twice; the same key with a different body is 409 idempotency_key_reused.

Terminal window
curl -X PUT "http://localhost:8080/api/v1/projects/{project}/environments/{environment}/collections/{collection}/entries/{entry}" \
-H 'Authorization: Bearer …' -H 'If-Match: "{revision}"' \
-H 'Idempotency-Key: save-hello-world-0001' \
-H 'Content-Type: application/json' -d '{"title":"Hello"}'

GET …/entries/{entry}/revisions lists every revision kept.

The Studio’s editor keeps your edits in this browser first, saves a second after you stop typing, and holds on to them through a closed tab, a dropped network or an expired session. On a conflict it shows both versions and lets you choose: Keep my version saves yours on top (theirs stays in the history), Use their version discards your unsaved changes.

Read more: Writing in the Studio · Management API · History

FeatureAPIStudioSelf-hosting

Members and single-use invitations, and a first administrator made from the terminal

Signing in grants nothing by itself: people reach a project by invitation. Each member has a role (the built-in ones are owner, developer, editor and publisher). Owners change roles and remove people, anyone may leave, and the last owner can’t go (409 last_owner).

An invitation is a single-use link that expires after 72 hours by default. The answer that creates it is the only place the link appears; its token travels after #, so it never reaches a server, and only its hash is stored. Before joining, the invitee sees the project, the role and who invited them.

Terminal window
curl -X POST http://localhost:8080/api/v1/projects/{project}/invitations \
-H 'Authorization: Bearer …' -H 'Content-Type: application/json' \
-d '{"role":"editor","label":"Copy desk"}'

Only an installation’s administrators create projects; anyone else gets 403 administrators_only. The first administrator is made once, from the operator’s terminal, bound to a sign-in identity’s subject (colophon whoami prints yours):

Terminal window
colophon admin bootstrap --subject "{subject}"

Run again for the same person it changes nothing; after that first run, bootstrap is disabled for good.

Read more: Members and roles · Installation

FeatureAPIStudio

Publish requests pin exact revisions, and an approval covers only what was reviewed

A publish request (changesets in the API) names 1 to 100 entries and pins each at its current revision. Its hash is computed from those exact revisions, and an approval counts only while the request keeps the hash it was given on. Edit an entry afterwards and the request turns stale: refreshing it pins the new revision, changes the hash and needs a fresh review. Approvals also expire after seven days.

Why it matters: “approved” means these exact bytes were looked at, not that someone once said yes to an entry.

POST /api/v1/projects/{project}/environments/{environment}/changesets
Idempotency-Key: …
{"title":"Spring launch","entries":["{entry}"]}
POST …/changesets/{changeset}/submit
If-Match: "sha256:…"
POST …/changesets/{changeset}/reviews
If-Match: "sha256:…"
{"decision":"approve","comment":"Checked the prices"}

submit, refresh and reviews each send the hash the caller looked at; if it moved, the answer is 409 stale_changeset with the current hash in ETag. A review’s decision is approve or request_changes, and only the latest decision on the current hash counts. A request moves through open, awaiting_review, changes_requested, approved and approval_expired, and publishes once.

Read more: Publishing

FeatureAPI

One release, one generation number, and a public delivery API that reads any of them

Publishing an approved publish request commits one release in one transaction. The environment’s generation goes up by exactly one, and only from the base the publisher saw: if another release committed first, the answer is 409 generation_moved with the current number in Colophon-Generation. Two releases on one base can never both win.

POST /api/v1/projects/{project}/environments/{environment}/changesets/{changeset}/publish
If-Match: "sha256:…"
Idempotency-Key: …
{"base_generation": 11}

Published content is served at /content/v1 with no sign-in, from a published copy read by a database role that can’t see drafts at all. {project} is the project’s id:

Terminal window
curl http://localhost:8080/content/v1/{project}/{environment}/posts
curl "http://localhost:8080/content/v1/{project}/{environment}/posts/{entry}?generation=12"

Without generation you read the latest release; with it you read that release exactly as it was, so a site build can take every collection from one release. Every answer names its generation in Colophon-Generation, a list’s next_cursor keeps its first page’s generation so paging never mixes two releases, and a generation not yet published is 422 invalid_generation.

Read more: Delivery API · Concepts

FeatureAPIStudio

Sign in to the Studio, and every project is walled off from the others

People can sign in to the Studio through an OpenID Connect provider: GET /auth/login sends the browser to the provider, and GET /auth/callback brings it back signed in. The server keeps each session as a database row and gives the browser only a random token in the colophon_session cookie (HttpOnly, Secure, SameSite=Lax). A session ends 12 hours after sign-in or after 2 hours unused, and POST /auth/logout ends it from the very next request, because nothing caches sessions.

Writes made with that cookie need two more things: an X-CSRF-Token header echoing the readable colophon_csrf cookie, and an Origin that is the server’s public origin or one listed in COLOPHON_TRUSTED_ORIGINS, compared exactly. Anything else is 403 with details.reason csrf_token_invalid or origin_not_allowed.

Projects are isolated. GET /me and GET /api/v1/projects list only the projects you belong to, and a route naming a project you aren’t in answers exactly as one that doesn’t exist, so ids and slugs can’t be probed:

GET /api/v1/projects/{project} HTTP/1.1
Cookie: colophon_session=…
HTTP/1.1 404 Not Found
{"error":{"code":"not_found","message":"…","request_id":"…"}}

Read more: Authentication & API tokens

FeatureAPIStudio

Take an entry down through a publish request, and it answers 410 at every generation

Taking an entry down changes what readers see, so it goes through review like any other change. A publish request (changesets in the API) lists the entry under unpublish, pinning the revision that is live now, so the reviewer approves taking down exactly what readers get:

POST /api/v1/projects/{project}/environments/{environment}/changesets
Idempotency-Key: …
{"title":"Withdraw the old pricing page","unpublish":["{entry}"]}

When its release commits, the entry’s publication closes, a tombstone is recorded and every earlier publication of it is revoked. From then on /content/v1 leaves it out of lists and answers a read of it with 410 gone and Cache-Control: no-store, including reads pinned to an older release with ?generation=: history never gets round a take-down. Answers cached before it are never served again, because cache keys name the environment’s latest take-down.

With a CDN connection, the release reports its purge as pending, accepted or failed, and the Studio says Removal pending at the CDN until it is accepted. Copies a browser already downloaded can’t be recalled. Publishing the entry again makes it readable from that new release on.

Read more: Publishing · Delivery API

FeatureAPIStudio

Website connections announce each release once, purge CDNs and check your site

An environment can have destinations, the Studio’s website connections, of three kinds (POST …/destinations):

  • webhook: each release is announced with a release.committed POST carrying Idempotency-Key and Colophon-Generation. The job is written in the release’s own transaction and sent by a background worker, retried with backoff on 408, 425, 429, 500, 502, 503 and 504, and dropped when a newer release supersedes it, so an older release never lands after a newer one.
  • cdn: each release sends {"tags": [...]}, a purge by tag covering every release since that CDN’s last successful purge.
  • probe: the worker fetches a URL and reads which release it serves, from the Colophon-Generation header or a <meta name="colophon-generation" content="N"> tag.
{"kind":"probe","name":"Home page","url":"https://example.com/"}

Addresses must be https on the public internet. GET …/releases/{generation} is the release’s receipt: one label (published, pending, verified with its count of locations, or needs_attention), the CDN purge state, each destination’s deliveries and every probe observation. “Verified” always says at how many locations, because one probe’s view isn’t the whole internet. The Studio shows it as a receipt timeline.

Read more: Website connections · Publishing

FeatureAPISelf-hostingCLI

Every error has one shape and a request ID, and health checks say what is wrong

Every failed request now answers in one JSON envelope, whether a handler or the server’s own middleware refused it: a stable code to branch on, a message that is safe to show a person, and the request_id. When there is more to say, details carries a stable reason and, for a refused body, a JSON Pointer to the value at fault.

{"error":{"code":"validation_failed","message":"…","details":{"reason":"unknown_node","pointer":"/doc/content/0/type"},"request_id":"…"}}

The same ID comes back in the x-request-id header on every answer and appears in the server’s log lines for that request, so a bug report can quote it. Send your own (up to 64 letters, digits, ., _ or -) and the server keeps it; otherwise it makes one.

Two health endpoints need no sign-in. /livez says the process responds. /readyz reports ready, or degraded when the cache is down (slower, still safe), with a 200; starting, not_ready or draining answer 503, so a load balancer stops sending traffic. colophon doctor reads it for you:

Terminal window
colophon doctor --server http://localhost:8080

It exits 0 when the server is ready and 5 when it is degraded, not ready or unreachable.

Read more: Errors · Monitoring

FeatureAPIStudio

Rich text is stored in one strict, versioned format that the server checks

Rich-text fields are stored as colophon/rich-text version 1: editor JSON limited to an allowlist and wrapped in a versioned envelope. It holds paragraphs, headings (levels 2 to 4), bulleted and numbered lists, quotes, code blocks, horizontal rules, callouts and images, with bold, italic, strike, code and link marks. Nothing executable is ever stored (no HTML, scripts, styles or embeds), and a link may only be https:, http:, mailto:, a site path or a # fragment.

Why it matters: the server has the last word, not the editor. A document deeper than 16 levels, larger than 256 KiB or with more than 10,000 nodes is refused, and every refusal names a code and a JSON Pointer to the value at fault. The Studio’s editor opens a document only if it can write it back byte for byte, and one renderer turns documents into escaped HTML.

Check a document before saving it; the endpoint stores nothing:

Terminal window
curl -X POST http://localhost:8080/api/v1/rich-text/validate \
-H 'Content-Type: application/json' \
-d '{"schema":"colophon/rich-text","version":1,"doc":{"type":"doc","content":[{"type":"paragraph"}]}}'

A valid document comes back in canonical form with its nodes, depth and bytes; an invalid one is 422 validation_failed.

Read more: Rich text and images · Management API

Was this page helpful?

Either answer opens a short issue on GitHub, so you can say what worked or what was missing.