Skip to main content
POST
/
search
Search Products
curl --request POST \
  --url https://api.joinrefine.io/search \
  --header 'Content-Type: application/json' \
  --header 'REFINE_API_KEY: <api-key>' \
  --data '
{
  "organizationId": "f2c320fc-1234-4567-8901-84c87f6b4c52",
  "catalogId": "1e2f3d4c-5678-9012-3456-9baaf2a08e3f",
  "query": "blue denim jacket",
  "topK": 24,
  "visual_weight": 0.8,
  "similarity_threshold": 0.25,
  "filters": [
    {
      "field": "price",
      "operator": "eq",
      "value": "<string>"
    }
  ],
  "user_analytics": {
    "session_id": "01HWEXYZ123456789",
    "ip_address": "24.161.52.129",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
  }
}
'
{
  "status": "success",
  "results": [
    {
      "productId": "GUCCI12345",
      "score": 0.8834,
      "metadata": {
        "name": "GG Denim Jacket",
        "brand": "Gucci",
        "price": 198,
        "color": "blue",
        "rank": "BOOST"
      }
    }
  ]
}

Authorizations

​
REFINE_API_KEY
string
header
required

API key for authentication

Body

application/json
​
organizationId
string<uuid>
required

Organization ID

Example:

"f2c320fc-1234-4567-8901-84c87f6b4c52"

​
catalogId
string<uuid>
required

Catalog ID

Example:

"1e2f3d4c-5678-9012-3456-9baaf2a08e3f"

​
query
string
required

Search query (automatically converted to lowercase)

Example:

"blue denim jacket"

​
topK
integer
required

Number of results to return

Example:

24

​
visual_weight
number<float>
required

Weight for visual similarity (0,1]

Required range: 0 < x <= 1
Example:

0.8

​
similarity_threshold
number<float>
required

Minimum similarity score for results [0,1]

Required range: 0 <= x <= 1
Example:

0.25

​
filters
object[]

Optional filters to apply

​
user_analytics
object

Optional analytics data

Response

Search results

​
status
enum<string>
Available options:
success
Example:

"success"

​
results
object[]