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"
}
],
"correlationId": "9f1c2e7a-4b30-4d8e-9a55-2c6f0b7d1e84"
}
Fetch API
Fetch a Listing
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"
}
],
"correlationId": "9f1c2e7a-4b30-4d8e-9a55-2c6f0b7d1e84"
}
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 honourfs-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 returns400 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:For
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 */] }
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"
}
],
"correlationId": "9f1c2e7a-4b30-4d8e-9a55-2c6f0b7d1e84"
}