Skip to main content
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 }
      ]
    }
  }
}
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

​
project-token
string
required
Your project’s Fetch token, embedded in the subdomain.
​
slug
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.
​
param
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).
​
filter
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.
​
sort
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.
​
search
string
Free-text search query. Must be non-empty after trim. Searches across the listing’s configured search fields.
​
page
integer
default:"1"
Page number (1-based).
​
limit
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

CodeWhen
200Listing rendered (may have zero items)
400Body 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.
401fs-secret missing or wrong (only when the project has fetch keys configured)
404Listing slug doesn’t exist for the resolved context
403Project’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 }
      ]
    }
  }
}