Skip to main content
POST
/
search
/
image
Image Search: Execute Search
curl --request POST \
  --url https://app.uselayers.com/api/storefront/v1/search/image \
  --header 'Accept: <accept>' \
  --header 'Content-Type: <content-type>' \
  --header 'X-Storefront-Access-Token: <x-storefront-access-token>' \
  --data '
{
  "image_data": "<string>",
  "image_id": "<string>",
  "attributes": [
    "<string>"
  ],
  "filter_group": {},
  "pagination": {
    "page": 123,
    "limit": 123
  },
  "facets": [
    "<string>"
  ],
  "retrieveFacetCount": true,
  "includeFacetRanges": true,
  "sort_order_code": "<string>",
  "defaultSelectedOptions": [
    {
      "optionCode": "<string>",
      "value": "<string>"
    }
  ],
  "discountEntitlements": [
    {
      "entitled": {
        "all": true,
        "products": [
          "<string>"
        ],
        "variants": [
          {}
        ],
        "collections": [
          "<string>"
        ]
      },
      "discount": {
        "type": "<string>",
        "value": 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": {}
  }
}
'
{
    "results": [
        {
            "id": 7003338965178,
            "title": "SUPREME SEALLINE SEE POUCH SMALL",
            "body_html": "The Supreme Sealline See Pouch Small is a versatile and waterproof storage solution that seamlessly marries utility and style. With its clear window for easy visibility and the iconic Supreme branding, it's a sought-after accessory for those who appreciate keeping their essentials dry while making a fashion statement, whether at the beach or in the city..",
            "vendor": "SUPREME",
            "product_type": "Accessories",
            "created_at": "2022-02-05T01:22:05.000000Z",
            "handle": "supreme-pouch-44370ss18a32-sm",
            "updated_at": "2023-10-25T20:47:04.000000Z",
            "published_at": "2022-02-05T01:22:05.000000Z",
            "tags": [
                "consignment",
            ],
            "images": [
                {
                    "alt": "SUPREME POUCH",
                    "src": "https://cdn.shopify.com/s/files/1/0588/3677/9194/products/ss18_supreme_tnf_pouch_blk_2-l_5fb1316e-22f7-4702-9953-57f3fbdda5be.jpg?v=1644047927",
                    "width": 800,
                    "height": 534,
                    "variant_ids": []
                }
            ],
            "metafields": {
                "product": {
                    "alias": "SEALLINE SEE POUCH SMALL",
                    "colorway": "BLACK",
                    "styleCode": "SS18A30 BLACK",
                    "yearOfRelease": 2018,
                    "searchColor": [
                        "black"
                    ]
                }
            },
            "available": true,
            "price_range": {
                "from": 30,
                "to": 30
            }
        }
    ],
    "totalResults": 1000,
    "page": 1,
    "totalPages": 20,
    "facets": {
        "vendor": {
            "ADIDAS": 30,
            "JORDAN": 336,
            "NEW BALANCE": 15,
            "NIKE": 384,
            "REEBOK": 4,
            "SUPREME": 624,
            "VANS": 32
        }
    },
    "attributionToken": "2y10smI2dB7XZXXFJsLUELltgueq8NRdcRD3U8djkLqxQmaVMvg1lSCf2"
}

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

​
Body

​
image_data
string
required
Base64 Encoded PNG or JPEG Image Data. Required if image_id is not provided.
​
image_id
string
required
UUID identifier returned from the Image Upload API. Required if image_data is not provided. Using image_id is recommended for better performance and support for larger images.
​
attributes
string[]
Product attributes to include in the response. By default, all attributes are included. Available attributes include: id, title, handle, body_html, vendor, product_type, tags, images, available, created_at, updated_at, published_at, price_range, options, original_options, metafields, named_tags, calculated, category, featured_media, is_gift_card, has_variants_that_require_components, combined_listing_parent_product_id, combined_listing_role, first_or_matched_variant, and variants. See the Product Schema for detailed descriptions.
​
filter_group
object
Refer to our dedicated Filter Expressions guide to learn more about filter expressions.
​
pagination
Pagination Object
​
facets
string[]
Facets to be included. Accepts both exact facet codes (e.g., "vendor", "options.Size") and wildcard patterns (e.g., "options.*", "metafields.product.*").Wildcard patterns expand to all matching attribute codes. For example, "options.*" expands to all option facets like "options.Size" and "options.Color". Wildcards must match at least one attribute code to be valid.Examples:
// Exact facet codes
"facets": ["vendor", "options.Size", "options.Color"]

// Wildcard pattern
"facets": ["options.*"]

// Mixed exact and wildcard
"facets": ["vendor", "options.*", "metafields.product.*"]
​
retrieveFacetCount
boolean
If the count of each facet value should be calculated
​
includeFacetRanges
boolean
If you want a min/max range for numeric facets such as price.
​
sort_order_code
string
Code of the sort order to apply. Use "relevance" for the default relevance-based ranking, or any custom sort order code configured in your store. Retrieve available sort order codes from the Sort Orders API.
​
defaultSelectedOptions
array
Specify which product variants should be selected by default in the first_or_matched_variant field.Behavior:
  • Uses OR logic - selects the first variant matching ANY of the specified option values
  • Falls back to the first variant by position if no match is found
  • Automatically skipped when any option or variant filters are applied (filters take precedence)
  • Only affects the first_or_matched_variant field in the response
​
discountEntitlements
array
Apply discounts to products, variants, or collections. When provided, price-based sorting and filtering will use discounted prices. See the Discount Entitlements guide for detailed usage.
​
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 of Objects
​
totalResults
number
The total number of results.
​
page
number
The current page number.
​
totalPages
number
The total number of pages.
​
facetRanges
object
If includeFacetRanges is true then an object with keys of the facet attribute code and value is an object with min/max.
​
facets
object
If retrieveFacetCount is true then an object with keys and values of the specified attributes. Empty values and literal "null" strings are automatically excluded from facet results.
​
attributionToken
string
A unique request identifier (ULID) for this API call. Use this token to correlate requests with analytics events via the Beacon API.
​
_meta
object
Metadata about the search request. Currently reserved for future use in image search responses.
​
_workflow
array of objects
An ordered trace of processing steps the engine performed. See the Text Search documentation for the full list of possible step types.

​
Response headers

HeaderDescription
x-request-idA unique identifier (ULID) for the request. This matches the attributionToken in the response body.
x-layers-buildThe Layers build version that served the request.
X-Layers-Results-CacheIndicates whether the response was served from the results cache. Returns HIT or MISS.
LinkContains rel="preload" directives for product images (up to 6 items). See Early hints for details. Only included when early hints are enabled (enabled by default).

​
Error responses

​
422 Unprocessable Entity

A 422 error is returned when the image_id refers to an image that failed to process. This can occur when:
  • The uploaded image is corrupted or invalid
  • The image format is unsupported
  • The image file cannot be read or decoded
Error Response Structure: 
{
    "error": "Image processing failed",
    "message": "Image is corrupted or invalid"
}
The message field provides specific details about why the image processing failed.

​
Usage examples

First, upload an image to get an image_id: 
curl -X POST "https://app.uselayers.com/api/storefront/v1/images/upload" \
  -H "X-Storefront-Access-Token: YOUR_TOKEN" \
  -F "image=@/path/to/your/image.jpg"
Then use the returned image_id for searching: 
{
    "image_id": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
        "page": 1,
        "limit": 20
    },
    "context": {
        "geo": {
            "country": "US"
        },
        "shoppingChannel": "web"
    },
    "identity": {
        "sessionId": "abc123",
        "deviceId": "device-uuid"
    }
}

​
Using base64 image data (legacy)

{
    "image_data": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...",
    "pagination": {
        "page": 1,
        "limit": 20
    },
    "context": {
        "shoppingChannel": "web"
    }
}

{
    "results": [
        {
            "id": 7003338965178,
            "title": "SUPREME SEALLINE SEE POUCH SMALL",
            "body_html": "The Supreme Sealline See Pouch Small is a versatile and waterproof storage solution that seamlessly marries utility and style. With its clear window for easy visibility and the iconic Supreme branding, it's a sought-after accessory for those who appreciate keeping their essentials dry while making a fashion statement, whether at the beach or in the city..",
            "vendor": "SUPREME",
            "product_type": "Accessories",
            "created_at": "2022-02-05T01:22:05.000000Z",
            "handle": "supreme-pouch-44370ss18a32-sm",
            "updated_at": "2023-10-25T20:47:04.000000Z",
            "published_at": "2022-02-05T01:22:05.000000Z",
            "tags": [
                "consignment",
            ],
            "images": [
                {
                    "alt": "SUPREME POUCH",
                    "src": "https://cdn.shopify.com/s/files/1/0588/3677/9194/products/ss18_supreme_tnf_pouch_blk_2-l_5fb1316e-22f7-4702-9953-57f3fbdda5be.jpg?v=1644047927",
                    "width": 800,
                    "height": 534,
                    "variant_ids": []
                }
            ],
            "metafields": {
                "product": {
                    "alias": "SEALLINE SEE POUCH SMALL",
                    "colorway": "BLACK",
                    "styleCode": "SS18A30 BLACK",
                    "yearOfRelease": 2018,
                    "searchColor": [
                        "black"
                    ]
                }
            },
            "available": true,
            "price_range": {
                "from": 30,
                "to": 30
            }
        }
    ],
    "totalResults": 1000,
    "page": 1,
    "totalPages": 20,
    "facets": {
        "vendor": {
            "ADIDAS": 30,
            "JORDAN": 336,
            "NEW BALANCE": 15,
            "NIKE": 384,
            "REEBOK": 4,
            "SUPREME": 624,
            "VANS": 32
        }
    },
    "attributionToken": "2y10smI2dB7XZXXFJsLUELltgueq8NRdcRD3U8djkLqxQmaVMvg1lSCf2"
}