Similar Items

Find documents similar to a given document using embedding cosine similarity. Uses the same BGE-small embeddings computed at index time — no additional configuration required beyond enabling semantic search.

POST /v1/indices/{uid}/similar Any key

Find documents similar to a source document by embedding cosine similarity.

Request body

ParameterTypeDescription
document_id requiredstringPrimary key of the source document to find similar items for.
limit optionalnumberMaximum number of similar documents to return. Max 200.
Default: 10
offset optionalnumberNumber of results to skip for pagination.
Default: 0
filter optionalstringFilter expression to scope candidates. Same syntax as search filters.
attributes_to_retrieve optionalstring[]Restrict which fields are returned in each hit. Returns all fields if omitted.
show_ranking_score optionalbooleanInclude _similarityScore (cosine similarity) on each hit.
Default: false

Example

text
curl -X POST https://search.example.com/v1/indices/products/similar \
  -H "Authorization: Bearer sk_search_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "document_id": "prod_abc123",
    "limit": 5,
    "show_ranking_score": true
  }'

SDK

text
const results = await idx.similar('prod_abc123', {
  limit: 5,
  show_ranking_score: true,
});

Response 200 OK

text
{
  "hits": [
    {
      "id": "prod_xyz789",
      "title": "14K Gold Curved Barbell 8mm",
      "price": 24.99,
      "_similarityScore": 0.9342
    },
    {
      "id": "prod_def456",
      "title": "Rose Gold Curved Barbell 6mm",
      "price": 22.50,
      "_similarityScore": 0.9187
    }
  ],
  "total_hits": 2,
  "processing_time_ms": 12,
  "limit": 5,
  "offset": 0,
  "document_id": "prod_abc123"
}

Response fields

ParameterTypeDescription
hits requiredobject[]Array of similar documents, sorted by cosine similarity descending.
total_hits requirednumberTotal number of similar documents found (before limit/offset).
processing_time_ms requirednumberServer-side processing time in milliseconds.
limit requirednumberThe limit that was applied.
offset requirednumberThe offset that was applied.
document_id requiredstringThe source document ID that was queried.

With filters

Use the filter parameter to scope candidates. For example, find similar products only within the same category:

text
const results = await idx.similar('prod_abc123', {
  limit: 10,
  filter: 'category = "earrings"',
  show_ranking_score: true,
});

Prerequisites

Similar items requires semantic search to be enabled on the index. The endpoint uses the same BGE-small-en-v1.5 embeddings that are computed automatically when documents are indexed with semantic search enabled.

text
// Enable semantic search in index settings
await idx.updateSettings({
  semantic: { enabled: true },
});
Note
If semantic search is not enabled, the similar endpoint returns a 400 error. Enable it via settings, then re-index your documents so embeddings are computed.

How it works

When you call the similar endpoint, Skirre:

  1. Looks up the source document by primary key and extracts its embedding vector.
  2. Scans candidate documents (respecting any filter you provide).
  3. Computes cosine similarity between the source embedding and each candidate.
  4. Excludes the source document from results.
  5. Returns candidates sorted by similarity score, with limit/offset applied.

The source document is always excluded from the results. If the source document has no embedding (e.g. it was indexed before semantic search was enabled), the endpoint returns a 400 error.