Search by biometric vectors

Purpose

Use this call when you already hold the vector representation of a face, for example from the compare call with embedding, and want to search your person lists with it. Each vector is searched separately.

Request

POST <API_BASE_URL>/vector/search. All calls are POST under your API address. Replace <API_BASE_URL> with the API address provided with your access.

Send a permanent API token in the token field of the body, or a user token in the token header. See authentication.

Content type: application/json.

Field	Type	Required	Description
`token`	string (uuid)	if no header	Your permanent API token. Required unless you send a user token in the `token` header.
`embeddings`	string or array of string	yes	One vector or an array of vectors, base64 encoded.
`list_ids`	string or array of string (uuid)	no	The person list or lists to search.
`threshold`	string or number	no	The distance threshold of a match.
`results`	string or number	no	How many matching persons to return per vector.
`person_data`	boolean	no	Include person data in the matches.

Response

HTTP 200. The search finished.

Field	Type	Description
`status`	string	Always `ok` on this body.
`results`	array of array of object	One entry per vector you sent, in the order you sent them. Each entry is a list of matches.

Errors

400: The body failed validation. The answer has status of error and a details list with one entry per offending field (path, expected, actual).
401: The token is missing, expired or unknown.
404: A referenced entity does not exist.

A refusal can also come before the operation runs: an address outside your IP allowlist, a token bound to another address, or a body that is not valid JSON. See response format and errors.

Example

Request:

curl -X POST "<API_BASE_URL>/vector/search" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "<your permanent API token>",
    "embeddings": [
      "<base64 vector>"
    ],
    "list_ids": [
      "<person list id>"
    ],
    "results": 5
  }'

Response:

{
  "status": "ok",
  "results": [
    []
  ]
}