POST
/
search
/
image
Search API: Catalog Image 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>"
  ],
  "tuning": {
    "textualWeight": 123,
    "visualWeight": 123,
    "multipleFactor": 123,
    "minimumMatch": 123
  },
  "filter_group": {},
  "pagination": {
    "page": 123,
    "limit": 123
  },
  "facets": [
    "<string>"
  ],
  "retrieveFacetCount": true,
  "includeFacetRanges": true,
  "identity": {
    "sessionId": "<string>",
    "customerId": "<string>"
  },
  "context": {
    "path": "<string>",
    "referrer_path": "<string>",
    "marketing_source": "<string>",
    "marketing_medium": "<string>",
    "marketing_campaign": "<string>",
    "marketing_term": "<string>",
    "marketing_content": "<string>",
    "cart_empty": true,
    "cart_value": 123,
    "num_cart_items": 123,
    "signed_in": true,
    "num_orders": 123,
    "geo_city": "<string>",
    "geo_state": "<string>",
    "geo_country": "<string>"
  }
}'
{
    "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": 1644047925,
            "handle": "supreme-pouch-44370ss18a32-sm",
            "updated_at": 1698280024,
            "published_at": 1644047925,
            "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"
}

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 in the response.
tuning
object
Parameters to fine-tune the search results.
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.
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.
identity
object
Information used to current identify the customer/session.
context
object
Anonymous contextual information of the session/customer.

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.
attributionToken
string
The attribution token.

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
    }
}

Using Base64 Image Data (Legacy)

{
    "image_data": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...",
    "pagination": {
        "page": 1,
        "limit": 20
    }
}
{
    "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": 1644047925,
            "handle": "supreme-pouch-44370ss18a32-sm",
            "updated_at": 1698280024,
            "published_at": 1644047925,
            "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"
}