Skip to main content
POST
Find similar products
Find products similar to a base product. The endpoint selects the similar-product intent automatically, so you do not send an intent field.

Identifying the base product

For the most deterministic result, provide the base product ID in chatMetadata.productId. The API can also attempt to resolve a product from its title or from the natural-language content. productIds is not used to select the base product for this operation.

Request example

Behaviour

  • The base product is excluded from the returned similar products.
  • pageSize controls the requested number of similar products.
  • If the request matches multiple possible base products, the stream may ask the shopper to confirm which product they mean.
  • If the base product cannot be resolved, the stream returns a no-product response rather than running a similarity search.

Streaming response

The response uses text/event-stream. Each data: line contains one JSON message:
Set operationHideAiMessage to true to omit chatStream messages. Set operationReturnFullProductInfo to true to return full product objects instead of ID-only objects in responsePayload.

Authorizations

Authorization
string
header
required

A short-lived HS256 operation token. Its tenantId claim must exactly match the Tenantid header. Mint this token on a trusted server; never expose the tenant signing credential in browser code.

Tenantid
string
header
required

The preezie tenant identifier. This value identifies the catalogue and is not a secret.

Body

application/json
content
string
required

Natural-language request that guides the selected operation.

Minimum string length: 1
Example:

"Show me lightweight black running shoes"

sessionId
string

Conversation session identifier. Reuse it for related requests.

Example:

"session-123"

visitorId
string

Stable identifier for the shopper or visitor.

Example:

"visitor-456"

websiteUrl
string<uri>
deprecated

Legacy top-level URL field. Use chatMetadata.websiteUrl for the current page context.

chatMetadata
object

Optional context from the current product or page.

requestOrigin
enum<string>
default:Operation

Source of the request. Use Operation for these endpoints.

Available options:
Operation
productIds
string[]

Explicit product identifiers consumed by operations such as comparison. For similarity and bundling, identify the base product with chatMetadata.productId instead.

pageSize
integer

Maximum number of product results requested. When omitted, the tenant's configured default is used.

Required range: x >= 1
operationHideAiMessage
boolean
default:false

When true, suppresses chatStream events and returns only non-chat stream events.

operationReturnFullProductInfo
boolean
default:false

When false, products in a conversation response payload are reduced to {"id": "..."} objects. When true, the full product objects are returned.

Response

A server-sent event stream. Each message is written as data: <JSON> followed by a blank line. The JSON payload contains one response key. operationHideAiMessage removes chatStream events; operationReturnFullProductInfo controls whether product payloads contain IDs only or full product objects.

A sequence of SSE messages whose data values follow the StreamEvent schema.