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

GET /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.

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.

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 fetch the OpenAPI spec at /api/doc.json from your Fetch subdomain 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 the 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
`400`	`INVALID_POST_BODY`, `INVALID_PARAMETERS`, `INVALID_FILTER_TYPE`, `MISSING_PARAMETER`, `WRONG_PARAMETER_TYPE`	The request body or query failed validation. `details` lists what’s wrong and where.
`401`	`AUTHENTICATION_FAILED`	`fs-secret` missing or wrong on a key-protected project.
`403`	`FETCH_API_LIMIT_EXCEEDED`, `FEATURE_NOT_AVAILABLE`	Plan limit hit. See Limits.
`404`	`BLOCK_NOT_EXISTS`, `URL_NOT_FOUND`, `PAGE_NOT_FOUND`, `ROUTE_NOT_FOUND`	The slug or url didn’t resolve. 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`	various	Semantic violation, e.g. `NO_UPDATES_PROVIDED`.
`500`	(none)	Unexpected error.

OpenAPI spec

Each project’s Fetch API publishes a live OpenAPI spec at:

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

It enumerates every block, listing, and page endpoint defined in the project, plus the shared context endpoints. The Frontic CLI’s frontic generate consumes this spec to produce the typed Client SDK; you can also use it as input to OpenAPI generators in other languages.

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