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>",
  "tuning": {
    "textualWeight": 123,
    "visualWeight": 123,
    "multipleFactor": 123,
    "minimumMatch": 123,
    "missingEmbeddingScore": 123,
    "highSignalWeight": 123,
    "canonicalWeight": 123,
    "matchBoostExponent": 123
  },
  "pagination": {
    "page": 123,
    "limit": 123
  },
  "identity": {
    "deviceId": "<string>",
    "sessionId": "<string>",
    "customerId": "<string>"
  }
}
'

{
    "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

https://app.uselayers.com/api/storefront/v1

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>",
  "tuning": {
    "textualWeight": 123,
    "visualWeight": 123,
    "multipleFactor": 123,
    "minimumMatch": 123,
    "missingEmbeddingScore": 123,
    "highSignalWeight": 123,
    "canonicalWeight": 123,
    "matchBoostExponent": 123
  },
  "pagination": {
    "page": 123,
    "limit": 123
  },
  "identity": {
    "deviceId": "<string>",
    "sessionId": "<string>",
    "customerId": "<string>"
  }
}
'

{
    "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.

tuning

object

Parameters to fine-tune the search results.

Show Properties

textualWeight

decimal

Weight given to textual similarity (0-1). Must be provided together with visualWeight.

visualWeight

decimal

Weight given to visual similarity (0-1). Must be provided together with textualWeight.

multipleFactor

integer

Multiplier applied to the search results.

minimumMatch

decimal

Minimum match score threshold (0-1) for including results.

missingEmbeddingScore

decimal

Neutral score used for products missing certain embedding types (text or image) in hybrid search scoring. A value of 0.5 represents “average match quality” on the 0-1 scale where 0 is best and 1 is worst. This ensures products with both text and image matches rank appropriately higher than products with only one embedding type, while products with poor matches rank lower than those without embeddings.

highSignalWeight

decimal

Weight given to high-signal attribute matches (such as vendor or product type) in search scoring. High-signal attributes are force-chunked attributes that receive separate embedding treatment. Products matching only on high-signal attributes receive a penalty to rank lower than products with text matches, while high-signal matches can still boost products that have both types of matches.

canonicalWeight

decimal

Weight applied to canonical product matches in search scoring. Controls how strongly canonical product relationships influence result ranking.

matchBoostExponent

decimal

Exponent applied to match scores to adjust the scoring curve. Higher values amplify differences between good and poor matches, while lower values compress the score distribution.

pagination

Pagination Object

Show pagination

page

int

The current page of results to fetch.

limit

int

The max results to fetch per page

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.

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
Hybrid Scoring: Combines text and image similarity using configurable weights
Tuning Parameters: Control the balance between textual and visual similarity

Default Tuning Parameters

The Content Search endpoint uses different default tuning parameters than product search:

textualWeight: 0.7 (higher emphasis on text content)
visualWeight: 0.3 (lower emphasis on images)
topK: 3 (number of top candidates to consider)
minimumMatch: 0.0 (no minimum similarity threshold)

These defaults can be overridden using the tuning parameter in the request 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
    },
    "tuning": {
      "textualWeight": 0.8,
      "visualWeight": 0.2,
      "topK": 5,
      "minimumMatch": 0.3
    }
  }'

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

Utilities

Content Search: Execute Search

Authorization

Headers

Path Parameters

Body

Response

Search Behavior

Default Tuning Parameters

Error Handling

Usage Example

Browse

Product Search

Content Search

Blocks

Analytics

Utilities

​Authorization

​Headers

​Path Parameters

​Body

​Response

​Search Behavior

​Default Tuning Parameters

​Error Handling

​Usage Example

Authorization

Headers

Path Parameters

Body

Response

Search Behavior

Default Tuning Parameters

Error Handling

Usage Example