Similar items

Find products or documents similar to a given one — taste-match for product detail pages, related-articles for content sites.

GET /recommendations/similar returns items whose embedding is closest to the seed item's embedding, filtered by tenant + index.

Request

GET /recommendations/similar?indexId=<id>&itemId=<id>&limit=10
Authorization: Bearer <api-key>

Param	Type	Required	Notes
`indexId`	string	yes	Source index. Must belong to caller's org.
`itemId`	string	yes	The "anchor" item (product / document ID).
`limit`	number	no	1–50, default 10.
`filterBy`	string	no	Typesense `filter_by` to scope results.

Response

{
  "items": [
    { "id": "sku-1234", "score": 0.91, "data": { ... } },
    { "id": "sku-5678", "score": 0.87, "data": { ... } }
  ],
  "anchorId": "sku-0001",
  "engine": "similar"
}

score is cosine similarity in [0,1]. Below ~0.55 results become noisy — consider raising your threshold for visible carousels.

When to use

Product detail page — "You might also like" rail.
Article page — "Related articles" sidebar.
Empty cart — Seed from the last item the user viewed.

When NOT to use

Cart attach — Use Frequently bought together instead; semantic similarity is not the same as co-purchase intent.
Anonymous homepage — Use Trending since there is no anchor.

Latency

p95 ~80 ms on Pro for a 100k-document collection. Vector dim has a linear impact — 1536 dims is the default Typesense ceiling on the shared cluster.

Code path

packages/api/modules/recommendations/procedures/similar.ts — wraps a Typesense vector-search call against the seed item's embedding, then re-ranks by an optional business-rule filter.