Search Products

Request

Security: API Key

Headers

Content-Type

string

required

Content-Type

Allowed value:

application/json

Default:

application/json

as-store-id

string

required

The identifier of your Commerce store

Example:

f58a7bc4fb6d4719901906abde0c6f46

Body

session_id

string

Session unique identifier. It is recommended to use this package to generate UUID.

Example:

47be3249-c1f4-446d-b652-8749be6ed577

query

string

The search query. This parameter is required for the semantic search scenario.

Example:

dress

image_url

string

URL of the image. This parameter is required for the visual search scenario. Note: Either image_url or image_base64 must be provided, but not both.

Example:

https://websites.am-static.com/assets/brands/logo/aftership.svg

image_base64

string

Base64-encoded image data. This parameter is required for the visual search scenario. Note: Either image_url or image_base64 must be provided, but not both.

Example:

/9j/4AAQSkZJRgABAQ...

include_filters

array[string]

Include products that correspond to the specified attribute. For the supported filter key, please refer to the filter key, and for the format of the filter, please refer to the following examples:

Conjunctive filtering: ["tags:Sale", "price:[48,56)"] means tags contain any of ('Sale') and price greater than or equal to 48 and less than 56
Disjunctive filtering: ["tags:Sofa,Couch,Bed"] means tags contain any of ('Sofa', 'Couch', 'Bed')

exclude_filters

array[string]

Exclude products that correspond to the specified attribute. For the supported filter key, please refer to the filter key, and for the format of the filter, please refer to the following examples:

Conjunctive filtering: ["!tags:Sale", "!categories:Furniture"] means tags not contain any of ('Sale') and categories not contain any of ('Furniture')
Disjunctive filtering: ["!tags:Sofa,Couch,Bed"] means tags not contain any of ('Sofa', 'Couch', 'Bed')

faceting

array[string]

To apply multiple filters along certain discrete attributes or facets of the overall data collection. Selecting fewer facets for aggregation may help improve retrieval speed. For supported facets, please refer to filter key.

Example:

tags,categories

sort

string

To specify sort order based on attribute values of the requested resource instances, and for multiple sort attributes, separate the sort attributes by commas (,) in the "sort" request parameter.

Ascending order: For example, use +relevance to control the returned products to be sorted in ascending order of the relevance.
Dscending order: For example, use -price,-relevance to control the returned products to be sorted in descending order of the price, and within each group of products with the same price, products are sorted in descending order of the relevance attribute.

Support sort attributes: relevance, title, price, created_at, updated_at

Default:

-relevance

Example:

-relevance

page

number

The page to query. Maximum page number is bounded by total number of queried products.

>= 1<= 1000

Default:

Example:

limit

number

The number of products each page contains.

<= 100

Default:

Example:

The actual API version that serves the request

Example:

2025-01

as-trace-id

string

A UUID value without hyphens to trace and debug the request

Example:

5ae20644d52348a49a897fff5dd314a3

Body

Meta

Example:

{"code":200,"type":"OK","message":"Everything worked as expected."}

code

number

required

A 1 to 5-digit integer that represents the status of the request.

Example:

200

message

string

A human-readable string message that gives a short description to the specific meta code.

type

string

A human-readable short string which is the type of HTTP status, e.g. OK for a 200 HTTP status, or BadRequest for a 400 HTTP status.

Allowed values:

OKBadRequestUnauthorizedForbiddenNotFoundUnprocessableEntityTooManyRequestsInternalError

errors

array[Error]

data

object

products

array[PartialProduct]

required

Partial Commerce Product object.

faceting

object

pagination

Pagination

required

Auth

Parameters

Body

{
  "session_id": "47be3249-c1f4-446d-b652-8749be6ed577",
  "query": "dress",
  "image_url": "https://websites.am-static.com/assets/brands/logo/aftership.svg",
  "image_base64": "/9j/4AAQSkZJRgABAQ...",
  "include_filters": [
    "tags:Sale"
  ],
  "exclude_filters": [
    "!categories:Furniture"
  ],
  "faceting": "tags,categories",
  "sort": "-relevance",
  "page": 1,
  "limit": 20
}

Response Example

{
  "meta": {
    "code": 200,
    "type": "OK",
    "message": "Everything worked as expected."
  },
  "data": {
    "products": [
      {
        "id": "f74f8af7578042b0991e104533158ad1",
        "source_id": "7962442694953",
        "variants": [
          {
            "source_id": "46493898506537"
          }
        ]
      },
      {
        "id": "b8f033102b974f09b519d8e82e17adf1",
        "source_id": "7962443317545",
        "variants": [
          {
            "source_id": "46493898572073"
          }
        ]
      }
    ],
    "faceting": {
      "categories": {
        "Club & Night Out Dresses": 10,
        "Casual Dresses": 20,
        "Women's Novelty Clothing": 3
      },
      "tags": {
        "womens": 100,
        "grade 3": 20,
        "short sleeve": 3
      },
      "fit": {
        "Fitted": 100
      },
      "color": {
        "Red": 10,
        "Black": 20,
        "White": 20
      },
      "style": {
        "Vintage": 100
      },
      "price": {
        "[0,100)": 20,
        "[100,200)": 60,
        "[200,500]": 20
      }
    },
    "pagination": {
      "limit": 10,
      "page": 1,
      "total": 100
    }
  }
}

Request

Headers

Body

Responses

200

Headers

Body