Fetch a Listing

curl -X POST 'https://fetch-<project-token>.frontic.com/listing/<listing-slug>' \
  -H 'fs-context: <context-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "param": { "categoryId": "shoes" },
    "filter": [
      { "type": "equals", "field": "color", "value": "Red" },
      { "type": "range", "field": "price", "from": 5000, "to": 25000 }
    ],
    "sort": [{ "field": "publishedAt", "order": "desc" }],
    "search": "running",
    "page": 1,
    "limit": 24
  }'

{
  "items": [
    {
      "name": "Aurora Trail Runner",
      "price": { "amount": 12900, "currency": "eur", "precision": 2 }
    }
  ],
  "_meta": {
    "total": 138,
    "page": 1,
    "limit": 24,
    "facets": {
      "color": [
        { "value": "Red", "count": 12 },
        { "value": "Black", "count": 28 }
      ]
    }
  }
}

{
  "error": "Validation failed",
  "code": "INVALID_PARAMETERS",
  "details": [
    {
      "message": "The sorting field \"unknownField\" is not allowed.",
      "propertyPath": "sort"
    }
  ]
}

POST

listing

{slug}

curl -X POST 'https://fetch-<project-token>.frontic.com/listing/<listing-slug>' \
  -H 'fs-context: <context-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "param": { "categoryId": "shoes" },
    "filter": [
      { "type": "equals", "field": "color", "value": "Red" },
      { "type": "range", "field": "price", "from": 5000, "to": 25000 }
    ],
    "sort": [{ "field": "publishedAt", "order": "desc" }],
    "search": "running",
    "page": 1,
    "limit": 24
  }'

{
  "items": [
    {
      "name": "Aurora Trail Runner",
      "price": { "amount": 12900, "currency": "eur", "precision": 2 }
    }
  ],
  "_meta": {
    "total": 138,
    "page": 1,
    "limit": 24,
    "facets": {
      "color": [
        { "value": "Red", "count": 12 },
        { "value": "Black", "count": 28 }
      ]
    }
  }
}

{
  "error": "Validation failed",
  "code": "INVALID_PARAMETERS",
  "details": [
    {
      "message": "The sorting field \"unknownField\" is not allowed.",
      "propertyPath": "sort"
    }
  ]
}

Fetch a Search Listing — a searchable, filterable, sortable, paginated collection. The body controls every aspect of the query: parameters that scope the listing (e.g. a category ID), free-text search, structured filter expressions, sort, and pagination via page + limit.

Path Parameters

string

required

Your project’s Fetch token, embedded in the subdomain.

string

required

The listing’s slug, e.g. <listing-slug>. Per project — see your listing’s detail view in the API Builder.

Headers

See Headers on the overview for the full set. Listings honour fs-context, fs-domain, fs-version, and fs-secret (only when the project has fetch keys configured).

Request Body

All body fields are optional unless the listing’s parameter definition declares one as required. Only six top-level keys are accepted; any other key returns 400 Bad Request.

object

Listing parameters. Shape is defined per listing in the API Builder. Required keys must be present; values are typed (string or array of strings).

array

Structured filter expressions. Each entry is one of three shapes:

equals / contains

{ "type": "equals", "field": "<filter-field>", "value": "<value>" }

range

{ "type": "range", "field": "<numeric-field>", "from": <number>, "to": <number> }

or / not (nested)

{ "type": "or", "filter": [/* nested filter array */] }

For range, supply from, to, or both. Filter field values must be among the listing’s configured filter fields.

string | object | array

Sort instructions. Accepts three shapes:

field name (defaults to asc)

"<sort-field>"

sort object

{ "field": "<sort-field>", "order": "asc" }

array of sort objects (applied left-to-right)

[
  { "field": "publishedAt", "order": "desc" },
  { "field": "name", "order": "asc" }
]

order is "asc" or "desc". field values must be among the listing’s configured sort fields.

string

Free-text search query. Must be non-empty after trim. Searches across the listing’s configured search fields.

integer

default:"1"

Page number (1-based).

integer

Items per page. Capped by the listing’s configured perPageMax.

Response

Returns the listing’s records as defined by the per-item block, plus pagination metadata. Exact shape depends on the listing definition — generate the Client SDK for typed access.

Status codes

Code	When
`200`	Listing rendered (may have zero items)
`400`	Body validation failed — unknown filter field, sort field not in allowed sorts, `limit` above the configured max, search empty, etc. The `details` array spells out each violation.
`401`	`fs-secret` missing or wrong (only when the project has fetch keys configured)
`404`	Listing slug doesn’t exist for the resolved context
`403`	Project’s plan limit for Fetch API requests exceeded

curl -X POST 'https://fetch-<project-token>.frontic.com/listing/<listing-slug>' \
  -H 'fs-context: <context-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "param": { "categoryId": "shoes" },
    "filter": [
      { "type": "equals", "field": "color", "value": "Red" },
      { "type": "range", "field": "price", "from": 5000, "to": 25000 }
    ],
    "sort": [{ "field": "publishedAt", "order": "desc" }],
    "search": "running",
    "page": 1,
    "limit": 24
  }'

{
  "items": [
    {
      "name": "Aurora Trail Runner",
      "price": { "amount": 12900, "currency": "eur", "precision": 2 }
    }
  ],
  "_meta": {
    "total": 138,
    "page": 1,
    "limit": 24,
    "facets": {
      "color": [
        { "value": "Red", "count": 12 },
        { "value": "Black", "count": 28 }
      ]
    }
  }
}

{
  "error": "Validation failed",
  "code": "INVALID_PARAMETERS",
  "details": [
    {
      "message": "The sorting field \"unknownField\" is not allowed.",
      "propertyPath": "sort"
    }
  ]
}

Overview

CLI & SDKs

MCP Server

Data Model

Ingest API

Fetch API

Path Parameters

Headers

Request Body

Response

Status codes

​Path Parameters

​Headers

​Request Body

​Response

​Status codes

Path Parameters

Headers

Request Body

Response

Status codes