Search Recommendations

Return a paginated recommendation result set for product listing and search pages.

This is the unified retrieval endpoint for category or collection PLPs, facets-only listing requests, and shopper-entered text search. Use it for storefront surfaces that need sorting, pagination, optional facets, totals, and optional redirect metadata. Send query for shopper-entered search text; omit query or send null for category or collection retrieval without a search term. Use limit: 0 when you only need facet data.

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

Search or product listing request.

TypeScript Definitions

Use the request body type in TypeScript.

user*

End-user identifiers used for personalization and session continuity.

query?|

Shopper-entered search text. Omit, set to null, or send an empty string for listing requests without text. Queries are capped at 128 characters.

placement?|

Optional stable storefront surface identifier, such as plp.main or search.results.

context?|

Optional page context for search and listing requests.

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.

limit*integer

Maximum number of items to return. Public maximum is 500. Use 0 for facets-only requests.

Range0 <= value <= 500

filters?|

Optional public filter expression over configured filterable fields. Clients can constrain the result by fields configured for their integration, such as collection, availability, price, or other catalog attributes. Field handling matches Recommendation Query behavior: fields that cannot be applied are ignored rather than rejected, and applied filters are reported in the response.

group_by_product?boolean

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

Defaultfalse

metadata?|

Optional caller-provided string metadata.

collection?|

Optional collection or category key used to select collection-specific merchandising configuration. Use filters or facet_filters when you need to constrain returned products.

sort*array<string>

Sort key array. Send exactly one configured sort key, such as featured, price_asc, or another storefront-enabled sort option.

Items1 <= items <= 1

pagination?|

Omit (or send null) on the first request to get page 1. For pages 2..last_page, set page to the desired page and cursor to the recommendation_id returned by the first response.

facets?|

Facet fields to compute. Omit or set to null when the page does not need facets. You can combine facets with product results, or send limit: 0 for a facets-only request.

facet_filters?|

Selected facet refinements from the UI. Unknown or non-filterable keys are ignored and omitted from applied_filters.

redirect?|

Optional redirect matching request. Send { "enabled": true } on search pages that can use a configured redirect path when a shopper query maps to one. Omit for normal result rendering.

Response Body

`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    },    "query": null,    "limit": 24,    "sort": [      "featured"    ],    "filters": {      "collection": "dresses"    },    "facets": {      "keys": [        "*"      ],      "max_values": 20    },    "projection": [      "name",      "handle",      "images",      "price",      "variant_identifier"    ]  }'

{
  "recommendation_id": "reco_01J1P7VJYQJ8J9E9AT2X1WW8KQ",
  "expires_in": 3600,
  "pagination": {
    "page": 1,
    "has_more": true,
    "last_page": 6
  },
  "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",
      "price": 10500
    },
    {
      "type": "product",
      "product_identifier": "gid://shopify/Product/2002",
      "variant_identifier": "gid://shopify/ProductVariant/3002",
      "name": "Vega Solitaire Ring",
      "handle": "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": {
      "collection": "dresses"
    },
    "facet_filters": []
  },
  "meta": {}
}

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

Example success

Search response with list and range facets

Search response with redirect metadata

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`