Recommendation APIAPI ReferenceRecommendations
Explore Recommendations
Return ranked recommendation. Unified endpoint for category/collection browse pages (PLP) and search experiences.
Return ranked recommendation.
Unified endpoint for category/collection browse pages (PLP) and search experiences.
X-PSYKHE-API-KEY<token>
Public API key (pk_...). Preferred auth transport.
In: header
Request Body
application/json
Single search recommendation request.
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X post "https://api.psykhe.dev/v2/recommendations/search" \ -H "Content-Type: application/json" \ -d '{ "user": { "device_id": "device-uuid-1", "user_id": null }, "limit": 100, "sort": [ "featured" ], "collection": "engagement-rings/regulus-cut", "group_by_product": true, "filters": null, "projection": [ "title", "price", "primaryImage.src", "hoverImage.src" ], "pagination": { "cursor": "019c4877-2b48-7684-8432-f059b61c1e81", "page": 2 } }'{
"recommendation_id": "reco_01J1P7VJYQJ8J9E9AT2X1WW8KQ",
"expires_in": 3600,
"pagination": {
"page": 2,
"has_more": true
},
"items": [
{
"type": "product",
"product_identifier": "prod_2001",
"variant_identifier": "var_2001_gold",
"title": "Regulus Cut Engagement Ring",
"price": 10500
},
{
"type": "product",
"product_identifier": "prod_2002",
"variant_identifier": "var_2002_platinum",
"title": "Vega Solitaire Ring",
"price": 12500
}
],
"count": 2,
"total": 286,
"facets": [
{
"key": "color",
"label": "Color",
"type": "list",
"selection_mode": "multi",
"collapsed": false,
"values": [
{
"value": "gold",
"label": "Gold",
"count": 34,
"selected": false
}
]
}
],
"applied_filters": {
"filters": null,
"facet_filters": []
},
"meta": {
"cache": false
}
}{
"errors": [
{
"code": "validation_error",
"message": "Invalid request",
"context": null,
"extra": null
}
],
"meta": null,
"data": null
}{
"errors": [
{
"code": "unauthorized",
"message": "Unauthorized",
"context": null,
"extra": null
}
],
"meta": null,
"data": null
}{
"errors": [
{
"code": "forbidden",
"message": "Forbidden",
"context": null,
"extra": null
}
],
"meta": null,
"data": null
}{
"errors": [
{
"code": "payload_too_large",
"message": "Payload too large",
"context": null,
"extra": null
}
],
"meta": null,
"data": null
}{
"errors": [
{
"code": "internal_error",
"message": "Internal server error",
"context": null,
"extra": null
}
],
"meta": null,
"data": null
}