Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.frontic.com/llms.txt

Use this file to discover all available pages before exploring further.

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 project into secret-required mode; removing every secret flips it back. Secrets are project-level and aren’t tied to a release stage — the same secret works against develop, preview, and public.

​
Using the secret

How you attach fs-secret depends on what’s calling the API:
CallerHow
Raw HTTP / curlSet the header on every request: fs-secret: <your-secret>.
Client SDKUse createClient({ proxyUrl: "/api/frontic" }) and inject fs-secret server-side in your proxy. The browser-side SDK never sees the secret.
Nuxt moduleSet fetchApiSecret from a server-only env var. The module’s built-in proxy adds the header automatically.
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.
HeaderRequiredPurpose
fs-contextNo (recommended)The visitor’s context token (contextKey). Resolves to the stored region/locale/scope. Takes precedence over fs-domain.
fs-domainNo (recommended)A configured project domain (e.g. demo-shop.com/de). Used to resolve the context when no fs-context is set.
fs-versionNoTarget a specific release stage — develop, preview, or public (default).
fs-secretConditionalRequired when the project has fetch secrets configured. Otherwise unused.

​
Response headers

Frontic adds the following on every successful response:
HeaderValue
fs-contextThe 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:
  1. If fs-context is set and points to an existing context, the stored values are used.
  2. Else if fs-domain is set, the configured domain mapping resolves scope / region / locale.
  3. 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

Public errors return JSON with error (human message), code (a machine-readable error code), and details (an array of field-level violations where applicable). Common HTTP statuses you’ll see:
HTTPCodes (examples)Meaning
400INVALID_POST_BODY, INVALID_PARAMETERS, INVALID_FILTER_TYPE, MISSING_PARAMETER, WRONG_PARAMETER_TYPEThe request body or query failed validation. details lists what’s wrong and where.
401AUTHENTICATION_FAILEDfs-secret missing or wrong on a key-protected project.
403FETCH_API_LIMIT_EXCEEDED, FEATURE_NOT_AVAILABLEPlan limit hit. See Limits.
404BLOCK_NOT_EXISTS, URL_NOT_FOUND, PAGE_NOT_FOUND, ROUTE_NOT_FOUNDThe 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.
405METHOD_NOT_ALLOWEDWrong HTTP verb for the endpoint.
422variousSemantic 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.