> ## 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.

# Overview

The **Fetch API** is the public HTTP surface every Frontic project exposes. It's what the [Client SDK](/reference/client-sdk) and [Nuxt Module](/reference/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

<CardGroup cols={2}>
  <Card title="Fetch a Block" icon="cube" href="/reference/fetch-api/block">
    **POST /block/{slug}/{key}** — single record by key
  </Card>

  <Card title="Fetch a Listing" icon="cubes" href="/reference/fetch-api/listing">
    **POST /listing/{slug}** — search, filter, sort, paginate a collection
  </Card>

  <Card title="Fetch a Page" icon="file" href="/reference/fetch-api/page">
    **GET /page/{url}** — page by full URL
  </Card>

  <Card title="Fetch a Tree" icon="list-tree" href="/reference/fetch-api/menu-tree">
    **GET /tree/{slug}** — hierarchical records (Preview)
  </Card>

  <Card title="Get Context" icon="key" href="/reference/fetch-api/get-context">
    **GET /context/token** — resolve a contextKey
  </Card>

  <Card title="List Contexts" icon="list" href="/reference/fetch-api/list-contexts">
    **GET /context** — available context variations for the project
  </Card>

  <Card title="Update Context" icon="pen" href="/reference/fetch-api/update-context">
    **PATCH /context** — change the active region/locale on a contextKey
  </Card>
</CardGroup>

## 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](#fetch-api-secrets) for the project.

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

### 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:

| Caller                                | How                                                                                                                                                 |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Raw HTTP / curl                       | Set the header on every request: `fs-secret: <your-secret>`.                                                                                        |
| [Client SDK](/reference/client-sdk)   | Use `createClient({ proxyUrl: "/api/frontic" })` and inject `fs-secret` server-side in your proxy. The browser-side SDK never sees the secret.      |
| [Nuxt module](/reference/nuxt-module) | Set [`fetchApiSecret`](/reference/nuxt-module#configuration) 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.

| 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](#fetch-api-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:

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](/api-builder/overview#request-context) for the full lifecycle.

## Response shape

Block, listing, and tree endpoints return JSON shaped by your project's [Detail Block](/api-builder/blocks) or [Search Listing](/api-builder/listings) configuration. The exact shape is project-specific — generate the [Client SDK](/reference/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:

| 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](/admin/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](/reference/fetch-api/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](/reference/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.