Brease Docs

Delivery API

The read-only REST API that brease-client wraps, with what each route returns.

Base URL: https://api.brease.io. A test environment has its own address, which brease-client takes from BREASE_API_URL. Every request needs the site's delivery token:

curl -H "Authorization: Bearer $BREASE_TOKEN" "https://api.brease.io/content-api/page?slug=about&locale=en"

The API serves releases: immutable snapshots of the site's content made on every publish. Which release a request gets is decided by its headers; without them it's the live one.

Routes

RouteQueryReturns
GET /content-api/siteThe site
GET /content-api/pageslocale, parentId, template, withContentPage list
GET /content-api/pageslug, localeOne page in one locale. 404 when missing or hidden
GET /content-api/navigations/{key}localeA navigation. 404 when it doesn't exist
GET /content-api/redirectsRedirects
GET /content-api/releaseThe release being served
GET /content-api/openapi.jsonThe OpenAPI document

locale defaults to the site's default locale. An unknown locale is a 404.

Site

{
  "name": "Acme",
  "url": "https://www.acme.com",
  "locales": ["en", "de"],
  "defaultLocale": "en",
  "localeStrategy": "PREFIX_EXCEPT_DEFAULT",
  "urlTemplate": null,
  "seo": {
    "en": { "titleTemplate": "%s – Acme", "siteName": "Acme", "description": "…", "defaultImage": "https://…" }
  },
  "analytics": { "ga4": "G-XXXXXXX" }
}
  • url is the site's public address (its primary domain), the one used in canonical URLs and hreflang. null before a domain is connected.
  • seo holds the site's SEO defaults per locale. Pages already have them merged into their resolvedSeo.
  • analytics is null unless the GA4 tag is turned on in Brease.

Page list

[
  {
    "pageId": "pg_about",
    "locale": "en",
    "slug": "about",
    "url": "/about",
    "hidden": false,
    "name": "About",
    "index": true,
    "parentId": null,
    "order": 1,
    "template": "page"
  }
]
  • Without locale, every locale of every page is listed.
  • index is false for pages kept out of search. template is the page's content.template, or null.
  • parentId=pg_news lists that page's children; parentId= (empty) lists top-level pages only. template=article lists pages of one template.
  • withContent=1 adds each page's content (one locale, hidden pages left out, up to 100 pages). Use it with a filter to build news, team or job lists without a request per page.

Page

{
  "pageId": "pg_about",
  "name": "About",
  "locale": "en",
  "slug": "about",
  "url": "/about",
  "hidden": false,
  "content": {
    "template": "page",
    "title": "About us",
    "hero": { "image": { "assetId": "ast_…", "url": "https://…/team.webp", "alt": "Our team", "width": 2400, "height": 1600 } },
    "cta": { "label": "Contact us", "href": "/contact", "pageId": "pg_contact" }
  },
  "seo": { "title": "About us" },
  "resolvedSeo": {
    "title": "About us – Acme",
    "description": "Who we are.",
    "canonical": "https://www.acme.com/about",
    "robots": { "index": true, "follow": true },
    "openGraph": { "title": "About us – Acme", "url": "https://www.acme.com/about", "siteName": "Acme" },
    "twitter": {},
    "structuredData": [],
    "alternates": { "en": "https://www.acme.com/about", "de": "https://www.acme.com/de/ueber-uns" }
  },
  "alternates": { "de": "/de/ueber-uns" }
}
  • content is the page's own JSON: whatever your templates read. See Content model.
  • seo is what the page itself sets. resolvedSeo is final: the site's defaults merged in, the title template applied (unless the page shows its title as written), and canonical and alternate URLs absolute. Render it as is.
  • Links to other pages carry a pageId, and their href is that page's URL in the requested locale. Rich-text links to pages carry data-brease-page="<pageId>" and are filled in the same way.
  • alternates are the page's URLs in its other locales.
{
  "key": "main",
  "locale": "en",
  "items": [
    { "id": "n1", "label": "About", "url": "/about", "pageId": "pg_about", "children": [] },
    { "id": "n2", "label": "Docs", "url": "https://docs.acme.com", "target": "_blank", "children": [] }
  ]
}

Labels are in the requested locale, and page items carry that locale's URL. Items whose page is hidden or missing are dropped.

Redirects

[{ "source": "/old-about", "destination": "/about", "status": 301 }]

Sources may use parameters as in Next.js redirects (/blog/:slug, /docs/:rest*). matchRedirect() in brease-client applies them.

Release

{ "id": "rel_…", "number": 42, "commitSha": "3f2a9c1…", "liveAt": "2026-11-17T09:30:00.000Z" }

Before the site's first publish there is no release, so this route returns 404 not_found and brease.getRelease() throws a BreaseError with status 404.

Headers

Request:

  • x-brease-commit (the full 40-character commit hash): serve the newest release made for that commit, or the live one when there is none. With a production token, only published releases count: a draft's commit gets the live release. See commit pinning.
  • x-brease-branch (a Brease draft branch, brease/draft/…): serve that draft's content, also for later commits on the branch. Preview tokens only; a production token ignores it.
  • If-None-Match: the ETag of an earlier response, for a 304.

Response:

  • x-brease-release: the number of the release served.
  • ETag. Send it back as If-None-Match to get a 304 when nothing changed.
  • Cache-Control: private, no-store with Vary: Authorization, x-brease-commit, x-brease-branch. Shared caches never store responses, so a publish shows at once; cache in your framework instead (see Publishing and caching).

CORS allows any origin for GET and OPTIONS. Keep tokens on the server anyway, preview tokens above all: they can also read draft content.

Tokens

Delivery tokens (brs_live_…) are read-only and identify the site. Each has a scope:

ScopeReadsUse it for
ProductionThe live release and earlier published ones (and the release being published, while its build runs)Production builds and the live site
PreviewAlso drafts: a draft's commit and draft branchesPreview deployments and local development

A production token asking for a draft's commit or branch gets the live release, not an error, so a preview built with it shows live content.

Create and revoke tokens in Developer settings › API tokens; a token is shown once, and can expire after 30 days, 90 days or a year. Onboarding creates a production and a preview token and writes both to the hosting project as BREASE_TOKEN, one per environment (see Connect a site). Tokens created before scopes existed are preview tokens; a site switches to the pair the next time Brease rewrites its variables.

Errors and limits

Errors are JSON with a status code to match:

{ "error": { "code": "not_found", "message": "No page at \"about\" in de" } }
StatuscodeWhen
401unauthorizedMissing, invalid, revoked or expired token
404not_foundNo such page, navigation, locale or route; hidden pages too
422validationA query Brease can't answer, e.g. withContent matching more than 100 pages
429rate_limitedToo many requests; wait for Retry-After seconds
500internalSomething went wrong on Brease's side

Each token can make about 3,000 requests a minute, enough for a large static build. Failed authentication is limited to 10 a minute per IP address. brease-client retries 429 and 5xx responses twice.

On this page