Top-k nearest neighbours API

Brute-force k-nearest-neighbour search of a query vector over a matrix by cosine, dot, or euclidean, returning ranked ids and scores. Answers 'Which rows are closest to my query embedding?', 'What are the top-k nearest vectors?'.

Price$0.02per request

MethodPOST

Route/v1/retrieval/topk-nearest

StatusLive

MIME typeapplication/json

Rate limit120/minute

Cache0s public

knnnearest-neighbourtopksearchvectorretrievalannrag

API URLhttps://x402.hexl.dev/v1/retrieval/topk-nearest

Integration docs

Example request

{
  "query": [
    1,
    0
  ],
  "matrix": [
    [
      0,
      1
    ],
    [
      1,
      0
    ],
    [
      0.9,
      0.1
    ]
  ],
  "k": 2,
  "ids": [
    "doc-a",
    "doc-b",
    "doc-c"
  ]
}

Example response

{
  "metric": "cosine",
  "k": 2,
  "results": [
    {
      "index": 1,
      "id": "doc-b",
      "score": 1
    },
    {
      "index": 2,
      "id": "doc-c",
      "score": 0.99388373
    }
  ],
  "totalCandidates": 3
}

Input schema

{
  "type": "object",
  "required": [
    "query",
    "matrix"
  ],
  "properties": {
    "query": {
      "type": "array",
      "items": {
        "type": "number"
      }
    },
    "matrix": {
      "type": "array",
      "items": {
        "type": "array",
        "items": {
          "type": "number"
        }
      }
    },
    "k": {
      "type": "integer"
    },
    "metric": {
      "type": "string",
      "enum": [
        "cosine",
        "euclidean",
        "dot"
      ]
    },
    "ids": {
      "type": "array"
    }
  }
}

Output schema

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