Content API

The content API delivers a site’s published content as JSON, for a frontend you build yourself (see Headless sites), a static site generator, a mobile app or a sync job. It is read-only: it answers what an anonymous visitor to the site may see, never drafts (except through a preview token), never CRM records, and nothing a key’s holder could not see on a rendered page. Its only writes are form posts and analytics events, each behind a capability.

engine-cms serves the same API.

A first requestCopy Anchor Link

# config/engine.yaml
server:
  api:
    content:
      enabled: true

engine-dmo api keys create --name "Astro frontend (production)" --kind secret --site main --project .

curl -H "Authorization: Bearer $MERIDIAN_KEY" \
  "https://cms.example.org/api/content/v1/sites/main/resolve?path=%2Fwhats-on%2Fsummer-fair"

The answer to resolve tells the frontend what the path is (a document, an index, a redirect, gone or not found), with the document’s representation and the page’s metadata. Headless sites walks through building a frontend on it.

ConfigurationCopy Anchor Link

The API answers on any host that reaches the engine. You may give it a host of its own (such as api.example.org) so a CDN can cache and limit it without path rules.

KeysCopy Anchor Link

• Sent as Authorization: Bearer <key>, never in a query string.
• A key names the sites it reads. A request for another site is key_not_for_site.
• Shown once. The engine keeps only a hash; lists show the prefix and the last four characters.
• Rotation needs no downtime. Any number of keys can be live for a site, each with an optional expiry. rotate issues a new key like an existing one and keeps the old one working for a grace period.
• An exposed secret key (one sent from a browser with an Origin header) is refused, marked exposed in api keys list and the admin, and reported in engine-dmo doctor. It is not revoked automatically: rotate it.
• CORS. A publishable key’s origins are its allowlist; a key with none allows the frontend origin of each headless site it reads, and nothing else. An allowed origin gets Access-Control-Allow-Origin naming it, with ETag, RateLimit, RateLimit-Policy and Retry-After exposed. Every site operation answers Vary: Origin. A preflight (OPTIONS) answers 204 for an allowed origin with GET, HEAD (and POST with Content-Type for a form), the Authorization and If-None-Match headers, and a ten minute Access-Control-Max-Age. Meridian-Preview is never allowed from a browser.
• A key carries no person. It cannot reach any staff or member capability.

Keys are managed by staff holding api.keys.manage (seeing them needs api.keys.view), in the admin under Settings, API keys (<admin_path>/api/keys) or from the command line. Each change is audited with the key’s id, never its value.

engine-dmo api keys create --kind publishable --name "Site search widget" --site main \
  --capability forms --origin https://www.example.org --expires 2160h --project .
engine-dmo api keys list [--site main] --project .
engine-dmo api keys rotate --id <key-id> --grace 24h --project .
engine-dmo api keys revoke --id <key-id> --confirm --project .

rotate --grace is how long the old key keeps working (default 24h; 0 ends it now). revoke needs --confirm; requests with a revoked key answer invalid_key.

OperationsCopy Anchor Link

Every path is under /api/content/v1. Every read takes locale (a locale the site enables; the site’s default when absent, invalid_parameter for any other).

engine-dmo api openapi prints the generic contract from this binary; with --types, the document /openapi.json serves, your types included. engine-dmo api schema --site <key> [--format jsonschema|openapi] prints a site’s types alone.

ResolveCopy Anchor Link

GET /api/content/v1/sites/main/resolve?path=%2Fja%2Fwhats-on%2Fsummer-fair

The locale comes from the path by the site’s strategy. Redirects are matched first, in the rendered site’s precedence. The answer is always HTTP 200; what to send the visitor is in the body:

Every answer also carries site, path and locale.

page is the page metadata the rendered site’s head() and jsonld() would print:

analytics is {view, collect}: a signed view token for the document and the path to report it to. See Headless sites.

engine-dmo api resolve <path> [--site key] [--host host] --project . prints the same answer from the command line, recording no miss.

The document representationCopy Anchor Link

{
  "id": "0191f0c2-7a51-7c3e-9d0a-5b2f6c1e4a88",
  "type": "event",
  "variant": null,
  "site": "main",
  "locale": "en-GB",
  "requested_locale": "en-GB",
  "fallback": false,
  "uri": "/whats-on/summer-fair",
  "url": "https://www.example.org/whats-on/summer-fair",
  "slug": "summer-fair",
  "title": "Summer fair",
  "published_at": "2026-08-14T09:12:00Z",
  "updated_at": "2026-09-02T16:40:11Z",
  "translations": {
    "ja-JP": { "uri": "/ja/whats-on/summer-fair", "url": "https://www.example.org/ja/whats-on/summer-fair" }
  },
  "tags": [ { "key": "family", "label": "Family", "kind": "topic", "parent": null } ],
  "fields": {
    "summary": "Stalls, music and a dog show on the green.",
    "location": { "lat": 52.0629, "lon": -1.3398, "precision": "exact" },
    "ticketPrice": { "amount": "5.00", "currency": "GBP", "formatted": "£5.00" }
  }
}

• Envelope keys are snake_case. Field values are under fields by the schema’s own field names, so a field never collides with an envelope key.
• locale is the language the content is in; requested_locale what was asked for. fallback is true when the whole document fell back along the site’s locale chain.
• translations lists the other locales published on this site.
• tags are public vocabulary tags only, labelled in the response locale.
• The representation carries no organisation, no parent document and no analytics impression or click tokens. On engine-dmo, the member report’s referral figures for a listing delivered through the API come only from the events the frontend reports with the resolve answer’s analytics token (see Analytics); the tracked member links a rendered page writes are not available.
• variant is the entry variant where the type declares variants, and fields holds that variant’s fields.
• Site overrides are applied for the site in the path.
• Every field of the type is present under fields, null when empty, and every key of a delivered object is present, null when it has no value: test values, not keys.

Field valuesCopy Anchor Link

The exact schema of every shape is in engine-dmo api openapi under components.schemas (Field.<type>), and your own types’ in engine-dmo api schema.

Expansion and sparse fieldsCopy Anchor Link

• expand=area,organiser replaces the named relations with full representations, to two levels (expand=area.parent) and at most 100 expanded documents per response. An expanded document obeys the same visibility.
• fields=title,heroImage,area.title limits fields, inside expansions too. The envelope is always present. A name that is not a field is invalid_parameter naming it.
• occurrences_window=180d delivers that many days of recurrence occurrences (default 90), up to the range the engine has materialised.

QueriesCopy Anchor Link

GET /api/content/v1/sites/main/documents
  ?type=event
  &locale=en-GB
  &tag=family
  &where[free]=true
  &where[startDate][gte]=2026-11-01
  &near=52.0629,-1.3398&radius=10
  &order=distance
  &per_page=24&page=2
  &facets=category
  &fields=title,startDate,heroImage

The answer is {items, pagination, facets, next_cursor}: items are full representations, pagination is {page, pages, total, per_page} (null when iterating by cursor), and facets maps each field to its values with counts. Only published documents of types on the site, available in the locale with its fallback, are ever returned.

SearchCopy Anchor Link

GET /sites/{site}/search calls the site’s search service, with its query log, visibility and facets. Parameters: q (below the configured minimum length it is browse), type and tag (each may repeat), near and radius, sort (relevance, name, distance or recent), page and per_page (20 by default, at most 100). The answer is {query, sort, backend, degraded, total, items, pagination, facets}; each item is {id, type, title, summary, uri, url, tags, position, distance, highlight}. degraded: true means the search backend is down and the answer is browse mode, so the frontend can say so.

CachingCopy Anchor Link

• Published responses carry Cache-Control: public, max-age=0, s-maxage=<s_maxage>, stale-while-revalidate=<stale_while_revalidate> and a strong ETag; a request with a matching If-None-Match is answered 304. They do not vary by key (the site is in the path), so a CDN may cache them despite the Authorization header. They vary by Origin.
• Cache tags in the configured header (Cache-Tag, comma separated, or Surrogate-Key, space separated) name what the response holds: site:<key>, type:<key>, doc:<id>, and the like. The change feed and the frontend webhooks carry the tags to purge.
• Time-bounded values: a response holding opening_hours days or recurrence occurrences caps s-maxage at its earliest valid_until, so a cached week of opening times is never served past the midnight it describes.
• Preview, form, events and change feed responses are private, no-store.

ErrorsCopy Anchor Link

Every failure is an RFC 9457 problem with Content-Type: application/problem+json:

{
  "type": "urn:meridian:content-api:problem:unindexed_filter",
  "code": "unindexed_filter",
  "title": "...",
  "status": 400,
  "detail": "...",
  "parameter": "where[price]"
}

Rate limitsCopy Anchor Link

Rate limits are operational and fail open if they cannot be counted, except failed authentication, which fails closed.

VersioningCopy Anchor Link

The path carries the major version, /api/content/v1/. Changes within a version are additive: new operations, parameters, envelope keys and field shape keys may appear, so a client must ignore keys it does not know. info.version in the OpenAPI document names the contract’s revision. Your own types are part of the contract: removing or renaming a field of a type a frontend reads changes what the API delivers, so plan schema changes with the frontend.

Static exportCopy Anchor Link

engine-dmo export content --site <key> --out ./content --project . writes the API’s own answers to disk for a static build: site.json, strings/<locale>.json, sitemap.json, redirects.json, pages/<path>.json (the resolve outcome of every index and every published path in every enabled locale, the root as pages/index.json) and manifest.json, which records the change feed’s cursor when the export began. --since <cursor> writes only what changed after a previous export’s cursor, removes the files of paths that went away and lists them in deleted.json; a cursor older than the change retention fails and asks for a full export. Images are not exported: they stay on the engine’s (or your CDN’s) origin.