Skip to content

APIs overview

View as Markdown

Colophon is one server with several HTTP surfaces. The Studio, the colophon CLI, the TypeScript SDK and AI agents all use the same management API with the same permission checks; your website reads the delivery API. All of them are on the same address as the Studio, for example http://localhost:8080 in the quick start.

You want to Use Path Credential
Show published content on a website or in an app Delivery API GET /content/v1/{project}/{environment}/{collection} and /{entry}, POST …/{collection}/query None. Anyone may read what is published. A site user’s session adds gated content.
Read drafts, write entries, publish, manage content types and website connections from a script or tool Management API /api/v1/projects/{project}/environments/{environment}/… A project API token, or a person’s sign-in
Manage people, roles, tokens and the activity log Management API, as a person /api/v1/projects/{project}/members, /roles, /tokens, /audit A person’s sign-in only; API tokens are refused
Query drafts with GraphQL GraphQL (read-only) POST /api/v1/projects/{project}/environments/{environment}/collections/{collection}/graphql Same as the management API
Hear that content changed, without polling Live events (server-sent events) Published: GET /content/v1/{project}/{environment}/events. Everything: GET /api/v1/projects/{project}/environments/{environment}/events Published: none. Everything: same as the management API
Show a draft on your own site before it is published Preview API /preview/v1/{project}/{environment}/… A preview token your site gets from a one-time code
Serve uploaded images Media GET /media/v1/{project}/{environment}/{asset} None
Let an AI agent draft and propose MCP server POST /api/v1/projects/{project}/environments/{environment}/mcp, or colophon mcp over stdio An API token

The short version: websites read the delivery API with no credential; everything that reads drafts or writes goes through the management API with a token. A token never belongs in a browser.

Published content only, from the release you ask for (the latest by default). Answers carry the release number (Colophon-Generation), an ETag for conditional requests, and cache headers a CDN understands. A draft can never appear here: the delivery path reads with a database role that can’t see drafts.

Terminal window
curl "http://localhost:8080/content/v1/$PROJECT/production/recipes"

→ Delivery API

Everything the Studio can do, under /api/v1. Writes are protected against the two classic failures of a network: a lost answer (Idempotency-Key makes a retry return the first result) and a lost update (If-Match refuses a save made on a version that is no longer current).

Terminal window
curl "http://localhost:8080/api/v1/projects/$PROJECT/environments/production/collections/recipes/entries" \
-H "Authorization: Bearer $COLOPHON_TOKEN"

→ Management API · Authentication & API tokens

A read-only GraphQL endpoint per collection over drafts, for tools that prefer GraphQL. It runs the same query engine and permission checks as the management API’s entries/query, and its schema names only the collections the caller may read. There are no mutations, and published content stays on REST.

→ GraphQL

Server-sent event streams that say that something changed, so a page or tool can fetch again. The public stream on /content/v1 says only that published content changed; the signed-in stream on /api/v1 says which kind of thing changed and in which collection. Neither sends content, and neither replays what you missed.

→ Live events

An entry can be published for everyone (the default), for any signed-in site user, or for one audience role. Delivery answers gated entries only to a request carrying that site user’s session, as Authorization: Bearer <session token> or the colophon_audience cookie, and such answers are never put in the shared cache. Site users are your website’s visitors, set up under Audience in the Studio; they are never project members. A project API token is not a site user’s session and does not unlock gated entries.

  • Versions in the path. /api/v1, /content/v1, /preview/v1, /media/v1. GET /version names the server’s version and the API versions it serves.
  • JSON in, JSON out. Successful answers are {"data": …}, and lists are {"data": […], "next_cursor": …}. Pass next_cursor back as ?cursor= for the next page; it is null on the last page.
  • One error shape. Every failure is {"error": {"code", "message", "details"?, "request_id"}}. Branch on code and details.reason, never on message. → Errors
  • Request ids. Every response has an x-request-id header, and every error body repeats it.
  • Projects by id. The {project} in a path is the project’s id (a UUID), shown in the Studio under Settings → General → Technical details. {environment} is an environment’s name; every project has production.
  • Rate limits. Requests are counted per client address and per credential, and an over-limit request is 429 with Retry-After. → Rate limits
  • The contract. The server describes itself in OpenAPI 3.1 at GET /openapi.json, generated from the same route table it serves, so the document and the routes can’t drift. → API reference

Was this page helpful?

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