v1

latestOpenAPI 3.1.02026-07-241765501.1 MB

Image Search results

Retrieve by image

Retrieve AI optimized search results for products (or optionally other sections) by image with optional multi-item detection (segmentation) support.

post/v2/image_search

Query parameters

keystring required

The key of the index to use.

Example:key_K2pX7vBnU0bgA5xp

sectionstring

The section of the index to use.

search_crop_type'bbox' | 'segment'

How to crop detected segments for visual search. Only relevant when use_segmentation is true.

valuesobject required

A set of aggregations that should be applied to each variation group. The object keys specify the name of the field under which each aggregated value will be returned in the response

dtype'array' | 'object' required

The expected data type of the variations_map objects in the response

fieldsstring[]

A list of specific item fields to return in the response. Allows the request to control which fields are returned.

show_hidden_fieldsboolean

A flag to return all hidden fields in the response.

hidden_fieldsstring[]

A list of specific hidden fields to return in the response. Unlike show_hidden_fields this parameter allows the request to control which hidden fields are returned. Used to return item fields for a particular store or user segment.

variations_return_type'default' | 'all' | 'matched'

groups_max_depthinteger

The maximum depth of the group hierarchy in the response.

groups_startstring

A flag to specify the start of the group hierarchy returned in the response. current returns groups starting from the currently selected one. top returns groups starting from the root category in the hierarchy. group_id:{id}, returns the whole tree starting from group with the provided id.

groups_pathstring[]

Specifies the path from the root group to the current group you are browsing. It is used to construct the parents path in the response.groups for the current browsed group. Max depth allowed for the path is 10. This option is only accepted when groups_start is 'current'.

groups_sort_by'relevance' | 'value' | 'num_matches'

groups_sort_order'ascending' | 'descending'

show_hidden_facetsboolean

A flag to return all facets configured as hidden in response.facets.

hidden_facetsstring[]

A list of specific hidden facets to return in the response. Unlike show_hidden_facets this parameter allows the request to control which hidden facets are returned. Used to return facets for a particular store or user segment.

show_hidden_facet_optionsboolean

A flag to return all hidden facets options in the response.

show_protected_facetsboolean

A flag to return all protected facets in the response. Requires authentication.

facet_optionsobject

A list of specific facet options per facet to return in the response. This parameter accepts up to 5 facets and works only with facets of type multiple. Invalid facet options will be ignored. Used to return facet options for a particular facet like store or user segment.

facet_groups_limitinteger

The maximum limit of the facet groups returned in the response.

show_hidden_sort_optionsboolean

A flag to return all sort options configured as hidden in response.sort_options.

hidden_sort_optionsstring[]

A list of sort_by fields whose hidden sort options should be included in the response. Unlike show_hidden_sort_options this parameter allows you to specify exactly which hidden sort options are returned.

cstring

The ID of the client and version that the request is coming from, such as cio-js-2.90.

Example:cio-js-client-2.35.2

usstring[]

A customer defined context (such as vip-club-member) used to evaluate redirect or refined tag rules. Pass multiple segments by passing multiple us arguments.

[
  "vip-member"
]

use_segmentationboolean

Whether to detect and individually search multiple objects in the image. When true, the image is split into detected objects and each is searched separately; results are merged.

uistring

A customer generated anonymized identifier for a user on a customer website. It should only be sent for logged in customers and helps Constructor to tie multiple client and session IDs together to form a behavioral data profile across devices.

Example:customer-user-id-456

return_segmentsboolean

Whether to include per-segment metadata in the response. Only applicable when use_segmentation is true.

sinteger

An integer representing the users session number (starting with 1), incremented after a 30 minute period of inactivity.

Example:1

istring

A globally unique identifier for the user browser (or mobile application instance) making the request.

Example:user-device-id-123

Response

requestobject required

The request arguments how they were interpreted by the API. This field is of arbitrary type, ie it doesn't have a guaranteed schema, and data from it shouldn't be used programmatically, it is for debugging purposes only.

result_idstring

A unique identifier for this search request, used for analytics and behavioral tracking.

segmentation_usedboolean required

Whether segmentation was actually used to produce results. false when use_segmentation was not requested or when segmentation failed and the system fell back to whole-image search.

whole_image_search_fallbackboolean required

Whether the service fell back to whole-image search after segmentation was requested but failed to produce usable results. Always false when use_segmentation was not requested.