Skip to main content
POST
cURL

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

x-shop
string
required

Shopify store URL. Resolves the shop for the request (headless does not accept ?shop=).

Example:

"shop.myshopify.com"

Body

Request body

Visual (image) search. Accepts a multipart file, a base64 image, a data: URL, or an http(s) image URL. Images are strictly validated (jpeg/png/webp, 1KB-5MB, 100x100 to 4096x4096) before search.

image
string

Raw base64 OR a data: URL. Exactly one of image / image_url is required. (Also accepted as a multipart image file upload.)

image_url
string

An http(s) image URL (fetched server-side, SSRF-guarded) OR a data: base64 URL. Exactly one of image / image_url is required.

facets
object

Applied filters (object or array form).

locale
string
default:en

BCP-47 locale.

market
integer

Shopify market id.

view
enum<string>
default:product_details

Product render mode.

Available options:
product_details,
product_ids
pagination
object

Page-based pagination.

visitor_id
string

Anonymous device/browser UID (the gl_s_uid cookie). The primary personalization key; stays stable when a customer logs in.

client_id
string

Per-session / per-device identifier.

customer_id
string

Shopify customer id. Present only when the shopper is logged in; enables customer-level personalization.

Response

Image search results

Visual search results with pagination and image-analysis metadata.

status
string

Response status.

Example:

"ok"

products
object[]

Product objects (or { product_id } when view=product_ids).

pagination
object

Page-based pagination.

search_metadata
object

Image-search diagnostics.