PSYKHE AIPSYKHE AI
Recommendation APIAPI ReferenceRecommendations

Query Slot Recommendations

Return one bounded recommendation result grouped into configured recommendation slots.

POST
/v2/recommendations/query/slots

Return one bounded recommendation result grouped into configured recommendation slots.

The request limit applies to each slot. A slot can be empty when there are not enough eligible products or when that slot fails. Products do not repeat across slots. Non-empty slots keep their configured relative order and are returned before empty slots.

Authorization

X-PSYKHE-API-KEY<token>

Required public API key (pk_...). Send it in this request header.

In: header

Query Parameters

psykhe_api_client*string

Required client identifier issued in the PSYKHE AI Dashboard (e.g. acme-production). Send it with each request alongside the API key.

Request Body

application/json

Slot recommendation query 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/query/slots?psykhe_api_client=acme-production" \  -H "Content-Type: application/json" \  -d '{    "user": {      "device_id": "device-or-session-token"    },    "placement": "pdp.complete_the_look",    "limit": 5,    "seed": {      "product_identifiers": [        "product-123"      ]    },    "projection": [      "name"    ]  }'
{
  "recommendation_id": "string",
  "slots": [
    {
      "items": [
        {
          "type": "product",
          "product_identifier": "string",
          "variant_identifier": "string",
          "category": "string"
        }
      ]
    }
  ]
}
{
  "errors": [
    {
      "code": "validation_error",
      "message": "Invalid projection field",
      "context": {
        "field": "projection"
      },
      "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
}

Query Recommendations POST

Return one bounded recommendation result set for a configured recommendation slot. Recommendation queries are for page-slot recommendations such as similar products. They return a single result set with no pagination, facets, totals, or redirects. Each request returns the current recommendation result for that slot.

Getting Started

Minimum setup for the PSYKHE AI Tracking API using Snowplow.