Recommendation APIAPI ReferenceRecommendations
Explore Recommendations
Return ranked recommendation.
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
Query Parameters
psykhe_api_client?string
Tenant identifier issued in the PSYKHE AI Dashboard (e.g. acme-production). Optional but strongly recommended on every request alongside psykhe_api_key - it powers per-tenant observability, correlation, and customer-scoped routing. Not used for authentication; psykhe_api_key alone identifies the caller.
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?psykhe_api_client=acme-production" \ -H "Content-Type: application/json" \ -d '{ "user": { "device_id": "device-uuid-1", "user_id": null }, "limit": 20, "sort": [ "featured" ], "filters": { "categories": "dresses" }, "facets": { "keys": [ "*" ] }, "projection": [ "title", "price", "primaryImage.src", "hoverImage.src" ] }'{
"recommendation_id": "reco_01J1P7VJYQJ8J9E9AT2X1WW8KQ",
"expires_in": 3600,
"pagination": {
"page": 2,
"has_more": true,
"last_page": 6
},
"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
}