Authentication
How to authenticate Recommendation API requests.
API key authentication is required for all Recommendation API calls. The API keys are managed in the PSYKHE AI Dashboard.
We have two key types:
- Public key
- Private key
Public key
- Use the public key in the
X-PSYKHE-API-KEYheader, or as thepsykhe_api_keyquery parameter. - For browser/client-side calls, prefer the
psykhe_api_keyquery parameter to avoid sending a custom auth header and reduce extra CORS preflight calls. - For server-to-server calls, prefer the
X-PSYKHE-API-KEYheader. - Public keys are expected to be visible in client-side usage. They identify the client configuration used by PSYKHE AI and should still be rotated regularly.
- Recommended to rotate public keys at least monthly.
Private key
- Private keys are used for ingestion use cases.
- Private keys are not accepted in query parameters and must be sent in the header.
Recommendation API
The Recommendation API provides personalized product recommendations for product listing, search, and recommendation slots.
Search Recommendations POST
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.