Skip to main content
POST
/
search
/
products
Search
curl --request POST \
  --url https://api.buybase.ai/search/products \
  --header 'Content-Type: application/json' \
  --header 'authorization: <authorization>' \
  --data '
{
  "query": {
    "text": "<string>",
    "image_url": "<string>"
  },
  "profile_id": "<string>",
  "store_id": "<string>",
  "store_domain": "<string>",
  "query_weight": 123,
  "style_weight": 123,
  "similarity_threshold": 123,
  "max_result_count": 123,
  "exclude_variant_ids": [
    {}
  ],
  "price_min": 123,
  "price_max": 123
}
'
{
  "results": [
    {
      "id": "7924157309120",
      "title": "Classic Cotton T-Shirt",
      "handle": "classic-cotton-t-shirt",
      "description": "A comfortable everyday essential made from 100% organic cotton",
      "product_type": "t-shirt",
      "images": [ 
          "https://cdn.shopify.com/s/files/1/0680/5936/5568/files/tshirt_black_front.jpg",
          "https://cdn.shopify.com/s/files/1/0680/5936/5568/files/tshirt_black_back.jpg"
      ],
      "options": [
        {
          "name": "Size", 
          "values": [
            "S", "M", "L", "XL"
          ]
        },
        {
          "name": "Color", 
          "values": [
            "Black", "White", "Navy"
          ]
        }
      ],
      "variants": [
        {
          "id": 46002863112384,
          "title": "S / Black",
          "option1": "S",
          "option2": "Black",
          "option3": null,
          "price": "29.95",
          "available": true,
          "checkout_url": "https://fashion-store.com/cart/46002863112384:1",
          "checkout_url_with_shipping": "https://fashion-store.com/cart/46002863112384:1?checkout[email]=user@example.com&checkout[shipping_address][first_name]=John&checkout[shipping_address][last_name]=Doe&checkout[shipping_address][address1]=123 Main St&checkout[shipping_address][city]=New York&checkout[shipping_address][province]=NY&checkout[shipping_address][country]=US&checkout[shipping_address][zip]=10001"
        }
      ],
      "store_id": "store456",
      "store_name": "Fashion Store",
      "store_domain": "fashion-store.com"
    }
  ],
  "product_ids": ["7924157309120"],
  "code": "SEARCH_SUCCESS"
}

Documentation Index

Fetch the complete documentation index at: https://docs.buybase.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Headers

​
authorization
string
required
Your API key for authorization.

​
Body Parameters

​
query
object
required
​
profile_id
string
Optional ID of a profile to influence search results in a personalized way and provide checkout URLs with shipping forms pre-filled with the profile’s attached shipping address.
​
store_id
string
The ID of the store to search in.
​
store_domain
string
The domain of the store to search in.
​
query_weight
number
default:"1"
Weight to apply to the query which represents the text, image, or both (0-1).
When using a style profile, defaults to 0.7.
​
style_weight
number
default:"0.3"
Weight to apply to the style profile (0-1).
Only applies if profile_id is provided and the profile has a style attached.
​
similarity_threshold
number
default:"0.25"
Minimum similarity threshold for matching products (0-1).
​
max_result_count
integer
default:"2"
Maximum number of results to return.
​
exclude_variant_ids
array
Array of variant IDs to exclude from results.
​
price_min
number
Minimum price filter for the search results.
​
price_max
number
Maximum price filter for the search results.

​
Response

​
results
array
An array of product details, each containing:
​
product_ids
array
Array of product IDs returned in the results.
​
code
string
A code indicating the result of the search operation. Possible values:
  • SEARCH_SUCCESS: Search completed successfully with results
  • NO_RESULTS_FOUND: Search completed but no results found
  • INVALID_REQUEST: Invalid request parameters
  • STORE_NOT_FOUND: Store ID or brand not found
  • PROFILE_NOT_FOUND: Profile ID not found
  • INTERNAL_ERROR: Server error occurred
​
error
string
Error message if the request fails.
​
message
string
Additional details about the error if the request fails.
{
  "results": [
    {
      "id": "7924157309120",
      "title": "Classic Cotton T-Shirt",
      "handle": "classic-cotton-t-shirt",
      "description": "A comfortable everyday essential made from 100% organic cotton",
      "product_type": "t-shirt",
      "images": [ 
          "https://cdn.shopify.com/s/files/1/0680/5936/5568/files/tshirt_black_front.jpg",
          "https://cdn.shopify.com/s/files/1/0680/5936/5568/files/tshirt_black_back.jpg"
      ],
      "options": [
        {
          "name": "Size", 
          "values": [
            "S", "M", "L", "XL"
          ]
        },
        {
          "name": "Color", 
          "values": [
            "Black", "White", "Navy"
          ]
        }
      ],
      "variants": [
        {
          "id": 46002863112384,
          "title": "S / Black",
          "option1": "S",
          "option2": "Black",
          "option3": null,
          "price": "29.95",
          "available": true,
          "checkout_url": "https://fashion-store.com/cart/46002863112384:1",
          "checkout_url_with_shipping": "https://fashion-store.com/cart/46002863112384:1?checkout[email]=user@example.com&checkout[shipping_address][first_name]=John&checkout[shipping_address][last_name]=Doe&checkout[shipping_address][address1]=123 Main St&checkout[shipping_address][city]=New York&checkout[shipping_address][province]=NY&checkout[shipping_address][country]=US&checkout[shipping_address][zip]=10001"
        }
      ],
      "store_id": "store456",
      "store_name": "Fashion Store",
      "store_domain": "fashion-store.com"
    }
  ],
  "product_ids": ["7924157309120"],
  "code": "SEARCH_SUCCESS"
}