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.

publication_ids
(string | integer)[]

Optional. Numeric Shopify publication (sales channel) ids. When present, only products published on at least one of these channels are returned and the default "published to the Online Store" gate is replaced by this filter; market and B2B filters still apply. A single id may be sent without the array wrapper. Each id must be one the merchant enabled under Settings → Sales channels; unknown ids return 400. The id is the numeric tail of gid://shopify/Publication/.

Maximum array length: 50
Pattern: ^[0-9]+$
Example:
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.