Overview

The Fetch API is the public HTTP surface every Frontic project exposes. It’s what the Client SDK and Nuxt Module call under the hood - documented here for use cases that don’t fit a JavaScript SDK: server-side integrations in other languages, raw curl debugging, building proxies or middleware, or understanding exactly what the SDK does. For a frontend app, prefer the SDK or Nuxt module - they handle types, auth, and context management for you. For everything else, the endpoints below are the canonical surface.

Base URL

Each Frontic project gets its own Fetch subdomain that embeds the project’s identifier. The URL pattern is:

https://fetch-{project-token}.frontic.com

Find the project token in the admin app under Settings → General. The same token appears in the URL of generated SDK files (.frontic/generated-client.ts). A complete request URL is the base plus the route - e.g. https://fetch-{project-token}.frontic.com/listing/<listing-slug>.

Available Endpoints

Fetch a Block

POST /block// - single record by key

Fetch a Listing

POST /listing/ - search, filter, sort, paginate a collection

Fetch a Page

GET /page/ - page by full URL

Fetch a Tree

POST /tree/ - hierarchical records (Preview)

Get Context

GET /context/token - resolve a contextKey

List Contexts

GET /context - available context variations for the project

Update Context

PATCH /context - change the active region/locale on a contextKey

Authentication

The Fetch API does not use the standard Authorization header. Auth is split across two concerns:

Context resolution - every request needs to resolve to a (scope, region, locale) triple. Send either fs-context (a contextKey) or fs-domain (a configured project domain). If neither is sent, the project’s default region and locale apply.
Secret-based access control - the fs-secret header gates the API when fetch secrets are configured for the project.

The “Authorization required” label that appears in the playground above is inherited from the docs site’s global API config - it doesn’t apply to the Fetch API. Use the fs-* headers below.

Fetch API secrets

Fetch secrets turn your project’s Fetch API from open (anyone with the URL can call it) into secret-protected (every request must include fs-secret). Whether you need them depends on how your frontend reaches the API:

Server-side or proxied calls - keep the Fetch API closed and require a secret. Your server holds it; it never reaches the browser.
Direct browser calls - the open default is fine if your frontend talks to the Fetch API straight from the browser. There’s nothing for the browser to keep secret anyway. If that’s not acceptable for your project, route those calls through a server-side proxy and apply a secret there instead.

Manage secrets in the admin app under your project’s Settings. Adding at least one secret flips the Fetch API into secret-required mode; removing every secret flips it back. Secrets are stage-scoped: the admin app edits develop, so a new secret protects develop at once and reaches preview and public only when Release Control carries it forward - a storefront pointed at public keeps answering unprotected until that release lands. The value travels unchanged, so one secret then works against all three stages. The same Add API Key dialog also creates Ingest API keys and the project’s Bypass Token, which identifies Frontic to your own storefront rather than protecting the Fetch API.

Using the secret

How you attach fs-secret depends on what’s calling the API:

Caller	How
Raw HTTP / curl	Set the header on every request: `fs-secret: <your-secret>`.
Client SDK, server-side	Pass `createClient({ secret })` from a server-only env var, or `secret` per request. See Server-side with a secret.
Client SDK, in the browser	Use `createClient({ proxyUrl: "/api/frontic" })` without a secret, and add `fs-secret` in your server-side proxy. The browser never sees the secret.
Nuxt module	Set `fetchApiSecret` once, from a server-only env var. The module attaches the header server-side on every path, and no call site passes a secret.

To rotate, add the new secret first, redeploy your servers/proxies with the new value, then remove the old one - keep both active for the cut-over.

Headers

Most endpoints support the same set; per-endpoint pages list which are honoured. None of the context-resolution headers are required - without them, Frontic falls back to the project’s default region and locale. In production you’ll almost always want to send one of fs-context or fs-domain so the response is shaped for the right visitor.

Header	Required	Purpose
`fs-context`	No (recommended)	The visitor’s context token (`contextKey`). Resolves to the stored region/locale/scope. Takes precedence over `fs-domain`.
`fs-domain`	No (recommended)	A configured project domain (e.g. `demo-shop.com/de`). Used to resolve the context when no `fs-context` is set.
`fs-version`	No	Target a specific release stage - `develop`, `preview`, or `public` (default).
`fs-secret`	Conditional	Required when the project has fetch secrets configured. Otherwise unused.
`fs-use-semantic-search`	No	`true` or `1` adds semantic matching to a Search Listing’s `search` term, so results match by meaning as well as by keywords. Early access: it only has an effect for Teams with semantic search enabled, on listings with searchable fields, and on the `preview` and `public` stages. Otherwise the search stays keyword-only.

Response headers

Frontic adds the following on every successful response:

Header	Value
`fs-context`	The active `contextKey`. If the request didn’t send one, Frontic generated and stored a fresh context - read this header to keep the same context across subsequent calls. If the request sent a token that didn’t yet exist, it’s persisted and echoed back.

Context resolution

Every request resolves to a single (scope, region, locale) triple before any data is read:

If fs-context is set and points to an existing context, the stored values are used.
Else if fs-domain is set, the configured domain mapping resolves scope / region / locale.
Otherwise, the project’s default region and locale apply.

When fs-context is sent but doesn’t match an existing context (and is a valid 36–50-character token), Frontic creates one on the fly using the resolved (scope, region, locale) and stores it under that token. Subsequent requests with the same token re-use the stored context. See Request Context for the full lifecycle.

Response shape

Block, listing, and tree endpoints return JSON shaped by your project’s Detail Block or Search Listing configuration. The exact shape is project-specific - generate the Client SDK to get typed responses, or keep the OpenAPI spec it is built from to inspect it raw. The Page endpoint and the context endpoints return fixed shapes documented on each page.

Errors

Errors return a JSON body in one of two shapes. A deliberate error - a missing record, a failed validation - carries a code:

{
  "error": "Key not found",
  "code": "KEY_NOT_FOUND",
  "details": [],
  "correlationId": "…"
}

error - a human-readable message.
code - a machine-readable error code. Branch on this, not on error.
details - structured context for the error. Its shape varies by code, and it is empty for most.
correlationId - identifies the request. Include it when you contact support. Empty when the request failed before it could be identified, for example with an unknown project or an invalid token.

An unexpected server error (500) carries only error and correlationId - no code, no details. The presence of code is how you tell the two apart. Both shapes are described in your project’s OpenAPI spec, so the generated Client SDK and the Nuxt module type them for you. Common HTTP statuses you’ll see:

HTTP	Codes (examples)	Meaning
`401`	`AUTHENTICATION_FAILED`	`fs-secret` missing or wrong on a key-protected project.
`404`	`KEY_NOT_FOUND`, `BLOCK_NOT_EXISTS`, `URL_NOT_FOUND`, `ROUTE_NOT_FOUND`, `PAGE_NOT_EXISTS`, `TOKEN_NOT_FOUND`, `SITEMAP_NOT_FOUND`, `NO_UPDATES_PROVIDED_EXCEPTION`	The record, slug, url or token didn’t resolve, or an Update Context body carried neither `region` nor `locale`. Note: the Page endpoint never returns 404 directly - it returns `200` with the not-found state encoded in the body’s `route.code`. See Fetch a Page.
`405`	`METHOD_NOT_ALLOWED`	Wrong HTTP verb for the endpoint.
`422`	`INVALID_PARAMETERS`, `INVALID_POST_BODY`, `MISSING_PARAMETER`, `WRONG_PARAMETER_TYPE`, `INVALID_FILTER_TYPE`, `UNKNOWN_FILTER_FIELD`, `INVALID_TOKEN`, `DATA_VIOLATION`, `FETCH_API_LIMIT_EXCEEDED`	The request was understood but rejected: validation failed, a filter or sort names something the listing doesn’t expose, or a plan limit was hit. `details` lists what’s wrong and where.
`500`	(none)	Unexpected error. The body carries `error` and `correlationId` only.

Validation failures answer 422, not 400 - including a malformed body. Plan limits answer 422 as well, not 403.

OpenAPI spec

Your project’s OpenAPI spec enumerates every block, listing, tree, and page endpoint defined in the project, with its response shape, plus the shared context endpoints and the error bodies. frontic generate fetches it from Frontic’s API, scoped to the selected project, and builds the typed Client SDK from it. To keep a copy, run it with --persist-oas: it writes fetch-api.spec.yaml next to the generated files, which you can inspect or feed to OpenAPI generators in other languages. The Fetch subdomain also serves an OpenAPI document at https://fetch-{project-token}.frontic.com/api/doc.json. That one is generic: it describes the Fetch API’s routes with the block or listing name as a path parameter, not your project’s endpoints or their response shapes, and the Client SDK isn’t built from it.

CLI & SDKs

MCP Server

Data Model

Ingest API

Fetch API

Overview

Base URL

Available Endpoints

Fetch a Block

Fetch a Listing

Fetch a Page

Fetch a Tree

Get Context

List Contexts

Update Context

Authentication

Fetch API secrets

Using the secret

Headers

Response headers

Context resolution

Response shape

Errors

OpenAPI spec

​Base URL

​Available Endpoints

Fetch a Block

Fetch a Listing

Fetch a Page

Fetch a Tree

Get Context

List Contexts

Update Context

​Authentication

​Fetch API secrets

​Using the secret

​Headers

​Response headers

​Context resolution

​Response shape

​Errors

​OpenAPI spec

Base URL

Available Endpoints

Authentication

Fetch API secrets

Using the secret

Headers

Response headers

Context resolution

Response shape

Errors

OpenAPI spec