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
  },
  "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
    },
    "shoppingChannel": "<string>",
    "custom": {}
  }
}
'

{
    "query": "sustainable fashion tips",
    "contentType": "article",
    "resultsPerPage": 20,
    "totalResults": 12,
    "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"
        }
    ]
}

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
  },
  "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
    },
    "shoppingChannel": "<string>",
    "custom": {}
  }
}
'

{
    "query": "sustainable fashion tips",
    "contentType": "article",
    "resultsPerPage": 20,
    "totalResults": 12,
    "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"
        }
    ]
}

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. Currently supports "article". When omitted, all content types are searched.

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.

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.

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.

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.

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.

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. Each item includes:

Show Article Properties

__typename

string

The content type identifier. Currently returns "Article".

content_type

string

The content type. Currently "article".

content_id

number

The unique identifier for the content item.

title

string

The article title.

handle

string

The article URL handle.

summary_text

string

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

author

string

The article author name.

Search Behavior

Content Search uses AI-powered semantic matching to find relevant articles:

Text Analysis: Analyzes article title, body content, author, and tags
Image Analysis: Analyzes the article’s featured image and images within the body

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": "article",
    "resultsPerPage": 20,
    "totalResults": 12,
    "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"
        }
    ]
}

Usage Example

cURL

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 '{
    "content_type": "article",
    "pagination": {
      "page": 1,
      "limit": 20
    },
    "context": {
      "geo": {
        "country": "US"
      },
      "shoppingChannel": "web"
    },
    "identity": {
      "sessionId": "abc123",
      "deviceId": "device-uuid"
    }
  }'

Article Sync: Articles are automatically synced from Shopify via webhooks and bulk operations. Only published articles without the seo.hidden metafield are included in search results.

Browse

Product Search

Content Search

Blocks

Analytics

Facets

Utilities

Content Search: Execute Search

Authorization

Headers

Path Parameters

Body

Response

Search Behavior

Error Handling

Usage Example

Browse

Product Search

Content Search

Blocks

Analytics

Facets

Utilities

​Authorization

​Headers

​Path Parameters

​Body

​Response

​Search Behavior

​Error Handling

​Usage Example

Authorization

Headers

Path Parameters

Body

Response

Search Behavior

Error Handling

Usage Example