Query Recommendations

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.

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

Single recommendation query request.

TypeScript Definitions

Use the request body type in TypeScript.

placement?|

Optional stable configured recommendation slot identifier such as pdp.similar or home.for_you. Send it when the result should use placement-specific configuration; omit or set null only for unplaced recommendation calls.

user*

End-user identifiers used for personalization and session continuity.

profile*string

Recommendation intent. Supported values:

similar: related-item recommendations where product or variant context should influence retrieval, such as PDP similar products, cart add-ons, or checkout recommendations. Send seed when the surface has product or variant anchors; without seed, the request is unanchored.
ymal: you-might-also-like recommendations that can blend anchor-related results with broader complementary signals.

Value in"similar" | "ymal"

request_id?|

Optional client-generated identifier for request/response correlation and tracing.

limit*integer

Maximum number of recommendation items to return. Public maximum is 100.

Range1 <= value <= 100

group_by_product?boolean

When true, return one card per product instead of allowing multiple variants of the same product.

Defaultfalse

context?|

Optional context object for configured recommendation-query behavior.

seed?|

Optional product or variant anchors for the recommendation. Omit seed for surfaces without a concrete product or variant anchor, such as home page or 404/not-found recommendations. Send product_identifiers for product anchors such as a PDP, or variant_identifiers for variant anchors such as cart or checkout line items.

filters?|

Optional public filter expression over configured filterable fields. Clients can constrain the recommendation result by fields configured for their integration, such as collection, availability, discount percentage, or other catalog attributes. For example, {"collection": "black-friday"} can restrict a broad product recommendation pool to a collection. Filter handling matches Search API behavior: fields that cannot be applied are ignored rather than rejected, and applied filters are reported in the response.

projection?array<string>|

Product fields to include in returned items. Omit or set to null to return only product_identifier and variant_identifier. Use ['*'] for all fields or an explicit list of up to 20 fields, such as name, handle, images, or variant_identifier.

metadata?|

Optional caller-provided string metadata.

Response Body

`application/json`

curl -X POST "https://api.psykhe.dev/v2/recommendations/query?psykhe_api_client=acme-production" \  -H "Content-Type: application/json" \  -d '{    "user": {      "device_id": "device-or-session-token",      "user_id": null    },    "profile": "similar",    "limit": 12,    "group_by_product": true,    "seed": {      "product_identifiers": [        "gid://shopify/Product/123"      ]    },    "filters": {      "collection": "black-friday",      "availability": {        "$eq": "in_stock"      }    },    "projection": [      "name",      "handle",      "images",      "variant_identifier"    ],    "context": {      "category_diversification": false    },    "metadata": {      "session_index": "4"    }  }'

{
  "recommendation_id": "reco_01J1P7VJYQJ8J9E9AT2X1WW8KQ",
  "items": [
    {
      "type": "product",
      "product_identifier": "gid://shopify/Product/2001",
      "variant_identifier": "gid://shopify/ProductVariant/3001",
      "name": "Regulus Cut Engagement Ring",
      "handle": "regulus-cut-engagement-ring"
    }
  ],
  "count": 1,
  "applied_filters": {
    "filters": null,
    "facet_filters": []
  },
  "metadata": {
    "profile": "similar",
    "seed_state": "provided"
  }
}

{
  "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
}

Authorization

Query Parameters

Request Body

Response Body

200application/json

400application/json

401application/json

403application/json

413application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`