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
required

Weight for visual similarity (0,1]

Required range: 0 < x <= 1
Example:

0.8

similarity_threshold
number
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[]
I