Maximal marginal relevance API

Re-orders candidate vectors with Maximal Marginal Relevance to balance query relevance against diversity (lambda), returning the diversified selection. Answers 'How do I diversify my retrieval results?', 'What is the MMR re-ranking of these candidates?'.

Price$0.03per request

MethodPOST

Route/v1/retrieval/mmr-rerank

StatusLive

MIME typeapplication/json

Rate limit120/minute

Cache0s public

mmrrerankdiversityrelevanceretrievalrerankingvectorrag

API URLhttps://x402.hexl.dev/v1/retrieval/mmr-rerank

Integration docs

Example request

{
  "query": [
    1,
    0
  ],
  "candidates": [
    [
      1,
      0
    ],
    [
      0.9,
      0.1
    ],
    [
      0,
      1
    ]
  ],
  "lambda": 0.7,
  "k": 3,
  "ids": [
    "a",
    "b",
    "c"
  ]
}

Example response

{
  "lambda": 0.7,
  "k": 3,
  "selected": [
    {
      "index": 0,
      "id": "a",
      "mmrScore": 0.7,
      "relevance": 1
    },
    {
      "index": 1,
      "id": "b",
      "mmrScore": 0.39755349,
      "relevance": 0.99388373
    },
    {
      "index": 2,
      "id": "c",
      "mmrScore": -0.03312946,
      "relevance": 0
    }
  ],
  "formula": "MMR = λ·rel(d,q) − (1−λ)·max_sim(d, selected)"
}

Input schema

{
  "type": "object",
  "required": [
    "query",
    "candidates"
  ],
  "properties": {
    "query": {
      "type": "array",
      "items": {
        "type": "number"
      }
    },
    "candidates": {
      "type": "array",
      "items": {
        "type": "array",
        "items": {
          "type": "number"
        }
      }
    },
    "k": {
      "type": "integer"
    },
    "lambda": {
      "type": "number"
    },
    "ids": {
      "type": "array"
    }
  }
}

Output schema

{
  "type": "object",
  "additionalProperties": true
}