Skip to main content
POST
/
search
/
content
/
{searchQuery}
/
execute
Content Search: Execute Search
curl --request POST \
  --url https://app.uselayers.com/api/storefront/v1/search/content/{searchQuery}/execute \
  --header 'Accept: <accept>' \
  --header 'Content-Type: <content-type>' \
  --header 'X-Storefront-Access-Token: <x-storefront-access-token>' \
  --data '
{
  "content_type": "<string>",
  "pagination": {
    "page": 123,
    "limit": 123
  },
  "tuning": {
    "textualWeight": 123,
    "visualWeight": 123,
    "topK": 123,
    "rankingWeightOverrides": {}
  },
  "identity": {
    "deviceId": "<string>",
    "sessionId": "<string>",
    "customerId": "<string>"
  },
  "context": {
    "geo": {
      "country": "<string>",
      "province": "<string>",
      "city": "<string>"
    },
    "productsInCart": [
      {
        "title": "<string>",
        "price": 123,
        "type": "<string>",
        "productId": "<string>",
        "variantId": "<string>",
        "options": {}
      }
    ],
    "productsPurchased": [
      {
        "title": "<string>",
        "price": 123,
        "type": "<string>",
        "productId": "<string>",
        "variantId": "<string>",
        "options": {}
      }
    ],
    "priorSearches": [
      {
        "searchQuery": "<string>",
        "hadClick": true,
        "hasResults": true,
        "fromPage": "<string>"
      }
    ],
    "marketing": {
      "source": "<string>",
      "medium": "<string>",
      "campaign": "<string>",
      "term": "<string>"
    },
    "customer": {
      "signedIn": true,
      "returning": true,
      "numberOfOrders": 123,
      "averageOrderValue": 123,
      "daysBetweenOrders": 123,
      "daysSinceLastOrder": 123,
      "daysSinceOldestOrder": 123,
      "totalSpent": 123
    },
    "market": "<string>",
    "shoppingChannel": "<string>",
    "custom": {}
  }
}
'
{
    "query": "sustainable fashion tips",
    "contentType": null,
    "resultsPerPage": 20,
    "totalResults": 14,
    "page": 1,
    "totalPages": 1,
    "results": [
        {
            "__typename": "Article",
            "content_type": "article",
            "content_id": 12345678901,
            "title": "10 Ways to Build a Sustainable Wardrobe",
            "handle": "sustainable-wardrobe-tips",
            "summary_text": "Discover practical tips for creating an eco-friendly wardrobe that's both stylish and sustainable.",
            "author": "Emma Green",
            "tags": ["sustainability", "fashion", "eco-friendly"],
            "image": {
                "url": "https://cdn.shopify.com/s/files/1/0588/3677/9194/articles/sustainable-fashion.jpg",
                "width": 1200,
                "height": 630,
                "altText": "Sustainable Fashion Guide"
            },
            "published_at": "2024-06-01T12:00:00Z"
        },
        {
            "__typename": "Page",
            "content_type": "page",
            "content_id": 98765432101,
            "title": "Our Sustainability Commitment",
            "handle": "sustainability",
            "summary_text": "Learn about our commitment to ethical sourcing and sustainable materials across all product lines.",
            "author": null,
            "tags": [],
            "image": {
                "url": "https://cdn.shopify.com/s/files/1/0588/3677/9194/files/sustainability-hero.jpg",
                "width": 1600,
                "height": 900,
                "altText": "Sustainability page hero"
            },
            "published_at": "2024-03-15T10:00:00Z"
        }
    ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.uselayers.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Authorization

​
X-Storefront-Access-Token
string
required
Token-based authentication header in the form of <YOUR_LAYERS_TOKEN>.

​
Headers

​
Content-Type
string
default:"application/json"
required
​
Accept
string
default:"application/json"
required

​
Path parameters

​
searchQuery
string
required
The url-encoded search query.

​
Body

​
content_type
string
Filter results by content type. Supported values: "article" and "page". When omitted, all content types are searched and results from both articles and pages are returned together.
​
pagination
Pagination Object
​
tuning
object
Override default ranking weights for content search.
​
identity
object
User identity information for tracking and personalization. Automatically managed by the Storefront Pixel; required for headless integrations.
​
context
object
Contextual information about the customer’s session, behavior, and environment. Automatically collected by the Storefront Pixel; must be manually provided for headless integrations. See Contextual Information for implementation guidance.

​
Response

​
results
array
Array of content items matching the search query. Results can include both articles and pages when no content_type filter is applied. Each item includes:
​
query
string
The search query that was executed.
​
contentType
string
The content type filter applied, if any.
​
totalResults
number
The total number of results matching the search query.
​
page
number
The current page number.
​
totalPages
number
The total number of pages.
​
resultsPerPage
number
The number of results per page.

​
Response headers

HeaderDescription
x-request-idA unique identifier (ULID) for the request. Use it to correlate requests across your infrastructure or when contacting support.
x-layers-buildThe Layers build version that served the request.

​
Supported content types

Content search indexes two types of Shopify content:
Content type__typenameDescription
Articles"Article"Blog posts from your Shopify blog. Includes author, tags, and blog association.
Pages"Page"Shopify pages (e.g., About Us, FAQ, Size Guide). Includes featured images when available.
When you omit the content_type parameter, results from both articles and pages are returned together, ranked by a unified scoring model. Use the __typename field to distinguish between content types when rendering results.

​
Search behavior

Content search uses a configurable ranking model to score and rank results. The default model combines three signal groups:
Signal groupDefault weightWhat it measures
Semantic (text)50%How closely the content text matches the meaning of the query
Semantic (image)20%How closely the content’s images match the query
Freshness30%How recently the content was published (newer items score higher)
Scores from each signal group are normalized using min-max scaling across the result set, then combined into a single ranking score using a weighted linear combination. You can override these weights per-request using the tuning.rankingWeightOverrides parameter. For product search testing, use Test text search in Lab.

​
Error handling

When search processing fails (e.g., due to rate limits or service issues), the API returns an empty result set with totalResults: 0 rather than throwing an error. This ensures graceful degradation of the search experience. 
{
    "query": "sustainable fashion tips",
    "contentType": null,
    "resultsPerPage": 20,
    "totalResults": 14,
    "page": 1,
    "totalPages": 1,
    "results": [
        {
            "__typename": "Article",
            "content_type": "article",
            "content_id": 12345678901,
            "title": "10 Ways to Build a Sustainable Wardrobe",
            "handle": "sustainable-wardrobe-tips",
            "summary_text": "Discover practical tips for creating an eco-friendly wardrobe that's both stylish and sustainable.",
            "author": "Emma Green",
            "tags": ["sustainability", "fashion", "eco-friendly"],
            "image": {
                "url": "https://cdn.shopify.com/s/files/1/0588/3677/9194/articles/sustainable-fashion.jpg",
                "width": 1200,
                "height": 630,
                "altText": "Sustainable Fashion Guide"
            },
            "published_at": "2024-06-01T12:00:00Z"
        },
        {
            "__typename": "Page",
            "content_type": "page",
            "content_id": 98765432101,
            "title": "Our Sustainability Commitment",
            "handle": "sustainability",
            "summary_text": "Learn about our commitment to ethical sourcing and sustainable materials across all product lines.",
            "author": null,
            "tags": [],
            "image": {
                "url": "https://cdn.shopify.com/s/files/1/0588/3677/9194/files/sustainability-hero.jpg",
                "width": 1600,
                "height": 900,
                "altText": "Sustainability page hero"
            },
            "published_at": "2024-03-15T10:00:00Z"
        }
    ]
}

​
Usage example

cURL (all content types)
curl -X POST "https://app.uselayers.com/api/storefront/v1/search/content/sustainable%20fashion/execute" \
  -H "X-Storefront-Access-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pagination": {
      "page": 1,
      "limit": 20
    },
    "context": {
      "geo": {
        "country": "US"
      },
      "shoppingChannel": "web"
    },
    "identity": {
      "sessionId": "abc123",
      "deviceId": "device-uuid"
    }
  }'
cURL (pages only)
curl -X POST "https://app.uselayers.com/api/storefront/v1/search/content/return%20policy/execute" \
  -H "X-Storefront-Access-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content_type": "page",
    "pagination": {
      "page": 1,
      "limit": 20
    }
  }'
Content sync: Articles and pages are automatically synced from Shopify via webhooks and bulk operations. Only published content without the seo.hidden metafield is included in search results.