Skip to main content
POST
/
recs
Get Recommendations
curl --request POST \
  --url https://api.joinrefine.io/recs \
  --header 'Content-Type: application/json' \
  --header 'REFINE_API_KEY: <api-key>' \
  --data '{
  "organizationId": "f2c320fc-1234-4567-8901-84c87f6b4c52",
  "catalogId": "1e2f3d4c-5678-9012-3456-9baaf2a08e3f",
  "productId": "GUCCI12345",
  "topK": 12,
  "visualWeight": 0.5,
  "filters": [
    {
      "field": "price",
      "operator": "eq",
      "value": "<string>"
    }
  ],
  "includeMetadata": true
}'
{
  "status": "success",
  "results": [
    {
      "productId": "GUCCI98765",
      "metadata": {
        "name": "GG Denim Shirt",
        "price": 180,
        "brand": "Gucci",
        "color": "blue"
      }
    }
  ]
}

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"

productId
string
required

Product ID to get recommendations for (cannot be empty)

Example:

"GUCCI12345"

topK
integer
required

Number of recommendations to return

Example:

12

visualWeight
number

Weight for visual similarity (0,1]. Default: 1.0

Required range: 0 < x <= 1
Example:

0.5

filters
object[]

Optional filters to apply

includeMetadata
boolean

Whether to include product metadata. Default: true

Example:

true

Response

Product recommendations

status
enum<string>
Available options:
success
Example:

"success"

results
object[]
I