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>",
    "companyLocationId": "<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"
        }
    ]
}

POST

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>",
    "companyLocationId": "<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"
        }
    ]
}

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

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

Show pagination

page

int

The current page of results to fetch.

limit

int

The max results to fetch per page

tuning

object

Override default ranking weights for content search.

Show Properties

textualWeight

number

Weight for textual (semantic text) similarity in ranking, between 0 and 1. Required when visualWeight is provided.

visualWeight

number

Weight for visual (image) similarity in ranking, between 0 and 1. Required when textualWeight is provided.

topK

integer

Number of candidate results to retrieve before re-ranking, between 1 and 100.

rankingWeightOverrides

object

Override the default ranking model weights for this request. Each key is a signal group name and the value is a weight between 0 and 1. Content search supports the following groups:

semantic — controls how much text and image similarity contribute to the score.
freshness — controls how much publication recency contributes to the score.

When provided, the weights are normalized so they sum to 1.

identity

object

User identity information for tracking and personalization. Automatically managed by the Storefront Pixel; required for headless integrations.

Show Properties

deviceId

string

Persistent browser identifier that remains constant across sessions. Used to recognize returning visitors for long-term personalization. Automatically generated and managed by the Storefront Pixel.

sessionId

string

Temporary session identifier. Typically corresponds to the Shopify session ID and expires after inactivity or when the browser is closed.

customerId

string

Shopify customer ID for authenticated users. Only present when the user is signed in to their account.

companyLocationId

string

Shopify B2B company location GID (e.g. gid://shopify/CompanyLocation/123456789) for the authenticated buyer. Layers resolves the catalog assigned to the company location and uses it to scope results: only products in the catalog are returned, prices come from the catalog’s price list, and excluded collections return 404. Omit for retail (DTC) traffic. See B2B catalogs.

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.

Show Properties

geo

object

Geographic location information for regional personalization and merchandising. Automatically determined by the platform for client-side requests based on IP address. For server-side API calls (headless integrations), you should provide this explicitly.

Show Properties

country

string

Country code or name (e.g., “US”, “Canada”).

province

string

State or province name (e.g., “California”, “Ontario”).

city

string

City name (e.g., “Los Angeles”, “Toronto”).

productsInCart

array

Products currently in the customer’s cart. Used to surface complementary products and influence relevance scoring.

Show Array Item Properties

title

string

required

Product title.

price

number

Product price.

type

string

Product type or category.

productId

string

Product identifier. Accepts a numeric ID (e.g., "8234567890123") or a Shopify GID (e.g., "gid://shopify/Product/8234567890123").

variantId

string

Product variant identifier.

options

object

Product variant options (e.g., {"Size": "11", "Color": "Red"}).

productsPurchased

array

Products the customer has previously purchased. Informs recommendations and prevents over-promotion of owned items.

Show Array Item Properties

title

string

required

Product title.

price

number

Product price at time of purchase.

type

string

Product type or category.

productId

string

Product identifier. Accepts a numeric ID (e.g., "8234567890123") or a Shopify GID (e.g., "gid://shopify/Product/8234567890123").

variantId

string

Product variant identifier.

options

object

Product variant options (e.g., {"Size": "11", "Color": "Red"}).

priorSearches

array

Recent search queries and their outcomes. Helps understand customer intent and refine relevance models.

Show Array Item Properties

searchQuery

string

required

The search query text.

hadClick

boolean

required

Whether the customer clicked on any results from this search.

hasResults

boolean

required

Whether the search returned any results.

fromPage

string

The page the search was initiated from (e.g., the referring page URL or page type).

marketing

object

UTM parameters and marketing campaign information for attribution tracking.

Show Properties

source

string

Marketing source (e.g., “google”, “facebook”).

medium

string

Marketing medium (e.g., “cpc”, “email”, “social”).

campaign

string

Campaign name.

term

string

Search term or keyword.

customer

object

Aggregated customer behavior and purchase patterns for personalization.

Show Properties

signedIn

boolean

Whether the customer is currently authenticated.

returning

boolean

Whether this is a returning customer.

numberOfOrders

integer

Total number of orders placed.

averageOrderValue

number

Average order value in store currency.

daysBetweenOrders

integer

Average days between orders.

daysSinceLastOrder

integer

Days since the most recent order.

daysSinceOldestOrder

integer

Days since the first order.

totalSpent

number

Total amount spent in store currency.

market

string

Explicitly set the Shopify Market for this request. Used for market-specific product availability filtering and contextual pricing. Accepts a two-letter country code (e.g., "US", "CA"), a numeric Shopify Market ID (e.g., "12345"), or a Shopify Market GID (e.g., "gid://shopify/Market/12345").When not provided, the market is automatically resolved from the geo.country field (or the shopper’s detected country for client-side requests). If no matching market is found, the store’s primary market is used as the fallback.Behavior depends on the store’s market application mode:

Strict — Products are filtered to only those available in the resolved market, and market-specific pricing is applied
Pricing only — The full catalog remains visible, but variant prices are swapped to market-specific values where available
Off — Market resolution is skipped entirely; base catalog and base pricing are used for all shoppers

shoppingChannel

string

default:"web"

The shopping channel the customer is browsing from. Used for channel-specific merchandising, sorting, and analytics segmentation. Automatically detected from request headers when not provided (e.g., mobile app requests via Tapcart or Canvas are detected as "app").Accepted values:

"web" — Standard web browser (default)
"app" — Mobile app (e.g., Tapcart, Canvas)

custom

object

Custom contextual data specific to your implementation. Structure is flexible and can contain any key-value pairs relevant to your use case.

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:

Show Content item properties

__typename

string

The content type identifier. Returns "Article" for blog articles or "Page" for Shopify pages.

content_type

string

The content type: "article" or "page".

content_id

number

The unique identifier for the content item.

title

string

The content title.

handle

string

The URL handle for the content item.

summary_text

string

The content summary with HTML tags stripped (except images).

author

string

The author name. For pages, this may be null.

Response headers

Header	Description
`x-request-id`	A unique identifier (ULID) for the request. Use it to correlate requests across your infrastructure or when contacting support.
`x-layers-build`	The Layers build version that served the request.

Supported content types

Content search indexes two types of Shopify content:

Content type	`__typename`	Description
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 group	Default weight	What 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
Freshness	30%	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.

​Authorization

​Headers

​Path parameters

​Body

​Response

​Response headers

​Supported content types

​Search behavior

​Error handling

​Usage example

Authorization

Headers

Path parameters

Body

Response

Response headers

Supported content types

Search behavior

Error handling

Usage example