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
| Route | Query | Returns |
|---|---|---|
GET /content-api/site | The site | |
GET /content-api/pages | locale, parentId, template, withContent | Page list |
GET /content-api/page | slug, locale | One page in one locale. 404 when missing or hidden |
GET /content-api/navigations/{key} | locale | A navigation. 404 when it doesn't exist |
GET /content-api/redirects | Redirects | |
GET /content-api/release | The release being served | |
GET /content-api/openapi.json | The 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" }
}urlis the site's public address (its primary domain), the one used in canonical URLs and hreflang.nullbefore a domain is connected.seoholds the site's SEO defaults per locale. Pages already have them merged into theirresolvedSeo.analyticsisnullunless 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. indexisfalsefor pages kept out of search.templateis the page'scontent.template, ornull.parentId=pg_newslists that page's children;parentId=(empty) lists top-level pages only.template=articlelists pages of one template.withContent=1adds each page'scontent(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" }
}contentis the page's own JSON: whatever your templates read. See Content model.seois what the page itself sets.resolvedSeois 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 theirhrefis that page's URL in the requested locale. Rich-text links to pages carrydata-brease-page="<pageId>"and are filled in the same way. alternatesare the page's URLs in its other locales.
Navigation
{
"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: theETagof an earlier response, for a304.
Response:
x-brease-release: the number of the release served.ETag. Send it back asIf-None-Matchto get a304when nothing changed.Cache-Control: private, no-storewithVary: 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:
| Scope | Reads | Use it for |
|---|---|---|
| Production | The live release and earlier published ones (and the release being published, while its build runs) | Production builds and the live site |
| Preview | Also drafts: a draft's commit and draft branches | Preview 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" } }| Status | code | When |
|---|---|---|
| 401 | unauthorized | Missing, invalid, revoked or expired token |
| 404 | not_found | No such page, navigation, locale or route; hidden pages too |
| 422 | validation | A query Brease can't answer, e.g. withContent matching more than 100 pages |
| 429 | rate_limited | Too many requests; wait for Retry-After seconds |
| 500 | internal | Something 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.