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

# Client SDK

The Client SDK is generated specifically for your project using the [Frontic CLI](/reference/frontic-cli). Every block, listing, page, and context endpoint your project exposes becomes a typed method on the generated client.

<Frame>
  <img src="https://mintcdn.com/frontic/34vlQbUxJTTktEkF/images/hero-sdk.png?fit=max&auto=format&n=34vlQbUxJTTktEkF&q=85&s=1352b1d7173879da7b0afdc6b2600df9" alt="Client SDK Hero" width="1910" height="665" data-path="images/hero-sdk.png" />
</Frame>

<Card title="Generate Client SDK" icon="code" href="/reference/frontic-cli">
  Run `frontic generate` to produce the typed client for your project — see the CLI reference for the full command.
</Card>

<Tip>
  Looking for the raw HTTP surface — for a non-JS backend, a custom proxy, or curl debugging? See the [Fetch API reference](/reference/fetch-api). The SDK is a typed wrapper over those endpoints.
</Tip>

## Initialization

The generated client supports two initialization patterns.

### Direct import

For the simplest case — no proxy, no global config:

```ts theme={"theme":"css-variables"}
import client from "./.frontic/generated-client";

const data = await client.block("ProductCard", "<product-id>");
```

### Factory with configuration

For projects that need a global proxy URL (e.g. browser-side requests routed through your own server to avoid CORS):

```ts theme={"theme":"css-variables"}
import { createClient } from "./.frontic/generated-client";

const client = createClient({
  proxyUrl: "https://www.demo-shop.com/api/frontic",
  // or with relative path (does NOT work on server side):
  proxyUrl: "/api/frontic",
});

const data = await client.block("ProductCard", "<product-id>");
```

## Configuration

### `createClient(config?)`

Create a configured client instance.

#### Parameters

<ParamField path="config" type="object">
  Global configuration options.

  <Expandable title="Properties">
    <ParamField path="proxyUrl" type="string">
      Proxy URL used for all requests (e.g. `/api/frontic`). The client concatenates this with the original API path. The proxy should forward requests to the URL in the `fs-target-url` header. Useful for preventing browser CORS issues.
    </ParamField>
  </Expandable>
</ParamField>

#### Returns

<ResponseField name="client" type="Client">
  A configured client instance with all client methods.
</ResponseField>

## Methods

Every method below shares the same `config` object as a final argument, used to override per-request behaviour. The shared options are listed once here and referenced from each method.

### Shared `config` object

Every method takes an optional `config` object as its final argument. Not every field applies to every method — the table below in each method's section calls out which ones are honoured.

<ParamField path="config" type="object">
  Per-request overrides. Optional.

  <Expandable title="Properties">
    <ParamField path="requestUrl" type="string">
      Full URL of the page making the request. Drives domain-based [Request Context](/api-builder/overview#request-context) resolution and is also used for tracking. Sent as `fs-request-url`.
    </ParamField>

    <ParamField path="contextKey" type="string">
      A token that identifies the visitor's persistent context state (region, locale). 36–50 characters. Takes precedence over `contextDomain`. Sent as `fs-context`.
    </ParamField>

    <ParamField path="contextDomain" type="string">
      The domain whose configured region and locale should resolve the request. A `contextKey` (if set) takes precedence. Sent as `fs-domain`.
    </ParamField>

    <ParamField path="proxyUrl" type="string">
      Proxy URL used for this request, overriding any global configuration.
    </ParamField>
  </Expandable>
</ParamField>

### `client.block`

Fetch a [Detail Block](/api-builder/blocks) by its key.

#### Parameters

<ParamField path="name" type="string" required>
  The block name. Example: `'ProductCard'`.
</ParamField>

<ParamField path="key" type="string" required>
  The record key. Example: `'sku-12345'`.
</ParamField>

<ParamField path="config" type="object">
  See [shared `config` object](#shared-config-object).
</ParamField>

#### Returns

<ResponseField name="data" type="Block<ApiName>">
  The block payload, fully typed against the project's API surface.
</ResponseField>

#### Example

```ts Client SDK theme={"theme":"css-variables"}
const data = await client.block("ProductCard", "<product-id>", {
  requestUrl: "https://demo-shop.com/snowboards",
  contextKey: "<context-key>",
});
```

### `client.listing`

Fetch a [Search Listing](/api-builder/listings) with optional parameters and query options.

#### Parameters

<ParamField path="name" type="string" required>
  The listing name. Example: `'CategoryListing'`.
</ParamField>

<ParamField path="parameters" type="object">
  Listing parameters. Shape depends on the listing's parameter definition.
  Example: `{ categoryId: '<category-id>' }`.
</ParamField>

<ParamField path="config" type="object">
  Per-request overrides plus listing-specific query options.

  <Expandable title="Properties">
    <ParamField path="query" type="object">
      Query options applied to the listing.

      <Expandable title="query properties">
        <ParamField path="filter" type="array | object">
          One or more filter expressions, e.g. `{ type: 'equals', field: 'color', value: 'Red' }`.
        </ParamField>

        <ParamField path="sort" type="array | object">
          Sort expression(s), e.g. `{ field: 'publishedAt', order: 'asc' }`.
        </ParamField>

        <ParamField path="search" type="string">
          Free-text search query.
        </ParamField>

        <ParamField path="limit" type="number">
          Maximum number of results.
        </ParamField>

        <ParamField path="page" type="number">
          Page index for pagination.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="requestUrl" type="string">
      See [shared `config` object](#shared-config-object).
    </ParamField>

    <ParamField path="contextKey" type="string">
      See [shared `config` object](#shared-config-object).
    </ParamField>

    <ParamField path="proxyUrl" type="string">
      See [shared `config` object](#shared-config-object).
    </ParamField>
  </Expandable>
</ParamField>

#### Returns

<ResponseField name="data" type="Listing<ApiName>">
  The listing payload — items, pagination metadata, applied filters, available facets.
</ResponseField>

#### Example

```ts Client SDK theme={"theme":"css-variables"}
const data = await client.listing(
  "CategoryListing",
  { categoryId: "<category-id>" },
  {
    query: {
      filter: { type: "equals", field: "color", value: "Red" },
      sort: { field: "publishedAt", order: "asc" },
    },
    requestUrl: "https://demo-shop.com/sunglasses",
    contextKey: "<context-key>",
  },
);
```

### `client.tree`

Fetch a [Menu Tree](/api-builder/trees) — a hierarchical collection of records assembled from a Data Storage and rendered through a Detail Block.

#### Parameters

<ParamField path="name" type="string" required>
  The tree's API name. Example: `'CategoryNavigation'`.
</ParamField>

<ParamField path="config" type="object">
  Tree-specific query options plus the [shared `config` object](#shared-config-object).

  <Expandable title="Properties">
    <ParamField path="query" type="object">
      <Expandable title="query properties">
        <ParamField path="key" type="string">
          Optional starting node. When provided, the response returns the node with this key plus its descendants. Example: `{ key: 'shop' }`.
        </ParamField>

        <ParamField path="depth" type="number">
          Optional level limit. Controls how many levels of `$items` are included. Example: `{ depth: 2 }`.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

#### Returns

<ResponseField name="tree" type="Tree<ApiName>">
  An `items` array of root-level nodes, each carrying its subtree on `$items`. Every node's shape (beyond `$items`) is defined by the tree's connected Detail Block.
</ResponseField>

#### Example

```ts Client SDK theme={"theme":"css-variables"}
// Full tree
const tree = await client.tree("CategoryNavigation");

// Subtree from a specific node, 2 levels deep
const subtree = await client.tree("CategoryNavigation", {
  query: { key: "shop", depth: 2 },
});
```

### `client.page`

Fetch a [Page](/api-builder/pages) by its slug.

#### Parameters

<ParamField path="slug" type="string" required>
  The URL slug of the page (without protocol). Example: `demo-shop.com/uk/women/shoes/running`.
</ParamField>

<ParamField path="config" type="object">
  See [shared `config` object](#shared-config-object).
</ParamField>

#### Returns

<ResponseField name="page" type="Page">
  The page payload — `data`, page `type`, and any alternate `urls`.
</ResponseField>

#### Example

```ts Client SDK theme={"theme":"css-variables"}
const pageData = await client.page("demo-shop.com/uk/women/shoes", {
  requestUrl: "https://demo-shop.com/uk/women/shoes",
  contextKey: "<context-key>",
});
```

### `client.sitemap`

Fetch a Sitemap.

#### Parameters

<ParamField path="domain" type="string" required>
  The project domain for which you want the sitemap.
</ParamField>

<ParamField path="index" type="number">
  The index of a nested sitemap (only if the sitemap was split up).
</ParamField>

<ParamField path="config" type="object">
  The [shared `config` object](#shared-config-object).
</ParamField>

#### Returns

<ResponseField name="" type="string">
  The XML content of the sitemap.
</ResponseField>

#### Example

```ts Client SDK theme={"theme":"css-variables"}
const sitemap = await client.sitemap("demo-shop.com/uk");

const nestedSitemap = await client.sitemap("demo-shop.com/uk", 1);
```

### `client.context`

Fetch a context by its token.

#### Parameters

<ParamField path="token" type="string" required>
  The `contextKey` to look up. Example: `'ae0d4981-c363-4d5a-a49e-1f053d49f2f7'`.
</ParamField>

<ParamField path="config" type="object">
  See [shared `config` object](#shared-config-object).
</ParamField>

#### Returns

<ResponseField name="context" type="Context">
  The context — `region`, `locale`, `scope`, `token`.
</ResponseField>

#### Example

```ts Client SDK theme={"theme":"css-variables"}
const context = await client.context("<context-key>");
```

### `client.contextList`

List the available contexts (region + currency + locales) for the project, optionally filtered by an existing context token.

#### Parameters

<ParamField path="token" type="string">
  The `contextKey` whose project + scope context variations are returned. Optional.
</ParamField>

<ParamField path="config" type="object">
  See [shared `config` object](#shared-config-object).
</ParamField>

#### Returns

<ResponseField name="contexts" type="Context[]">
  Array of context options (region, currency, supported locales with URLs).
</ResponseField>

<ResponseField name="token" type="string">
  The active `contextKey`, returned in the `fs-context` response header.
</ResponseField>

#### Example

```ts Client SDK theme={"theme":"css-variables"}
const [contexts, token] = await client.contextList("<context-key>");
```

### `client.contextUpdate`

Update an existing context's region and locale on the Frontic server. Subsequent requests using the same `contextKey` reflect the change.

#### Parameters

<ParamField path="context" type="object" required>
  The context fields to update.

  <Expandable title="Properties" defaultOpen>
    <ParamField path="region" type="string" required>
      The region key, e.g. `eu`.
    </ParamField>

    <ParamField path="locale" type="string" required>
      The locale key, e.g. `de-DE`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="token" type="string" required>
  The `contextKey` to update.
</ParamField>

<ParamField path="config" type="object">
  See [shared `config` object](#shared-config-object).
</ParamField>

#### Returns

<ResponseField name="context" type="Context">
  The updated context.
</ResponseField>

#### Example

```ts Client SDK theme={"theme":"css-variables"}
await client.contextUpdate(
  { region: "eu", locale: "de-DE" },
  "<context-key>",
);
```

#### Response

```json Response theme={"theme":"css-variables"}
{
  "region": "eu",
  "locale": "de-DE",
  "scope": "public",
  "token": "ae0d4981-c363-4d5a-a49e-1f053d49f2f7"
}
```