# Core concepts

> Collections, faceprints, similarity, the four face operations, and how real-time and batch processing differ.

Source: https://sightradar.com/docs/concepts

## Collections

A **collection** is a namespace for faceprints. You choose its id (`event-2026-wedding`, `tenant-42`). Searches never cross collections, and deleting a collection is the whole retention story for whatever it contained.

Creating, listing, describing and deleting collections is free. You do not have to create a collection before writing to it: the first `index` or `batches` call to a new id creates it. Creating an id that already exists and is active returns the existing collection unchanged; creating one that is soft-deleted or purged returns `409`. A delete is soft by default: the collection stops accepting index and search immediately, but nothing is erased until a grace window elapses, and `POST /v1/collections/{id}/restore` undoes it. Once a collection is fully purged (`status: deleted`), `POST /v1/collections/{id}/recreate` brings the id back as a new, empty collection, unless it was erased under `?compliance=true`. Pass `?immediate=true` (or `?compliance=true` for an audited, compliance-class erasure) to skip the grace window. See [deleting data](/docs/guides/deleting-data).

## Faceprints and photos

Indexing a photo runs face detection, drops faces that fail the quality gate (too small or a low detector score), and stores one **faceprint** per remaining face: a 512-dimensional L2-normalised embedding. The photo itself is never stored. You keep the image in your own storage and address it by the `photoId` you supplied at index time (or the content hash SightRadar assigns when you do not).

Each stored face has a `point_id`. Search results are grouped back to `photo_id`, because "which photos is this person in" is the question almost every product asks.

## Similarity and thresholds

Every match carries a **score**: cosine similarity between faceprints, from 0 to 1. Higher means more alike. There is no universal cut-off. A wedding gallery can tolerate a looser threshold than a KYC flow, and the right value depends on your photos. Calibrate it from your own labelled pairs and treat any carried-over number (including a Rekognition percentage) as a starting guess. The [threshold guide](/docs/guides/thresholds) walks through it.

## The four operations

|                        | Index                                           | Search                           | Compare                                                            | Detect                                         |
| ---------------------- | ----------------------------------------------- | -------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------- |
| Input                  | one photo                                       | one selfie, or a 512-d embedding | two images, or embeddings                                          | one photo                                      |
| Output                 | stored faces with `point_id` and a ratio `bbox` | ranked `photo_id`s with scores   | one similarity and a `match` boolean at the 0.42 default threshold | faces with a ratio `bbox` and `quality_passed` |
| Stores anything?       | faceprints only                                 | no                               | no                                                                 | no                                             |
| Rekognition equivalent | IndexFaces                                      | SearchFacesByImage               | CompareFaces                                                       | DetectFaces                                    |

**Selfie registration** (`POST /v1/collections/{id}/selfies`) is Index constrained to a single face, keyed by your `userId`. It returns a `point_id` you can pass to `search-by-id`, which skips the model run and is billed at the cheaper search tier. See [selfie registration](/docs/guides/selfie-registration).

## Real-time versus batch

**Real-time** endpoints are synchronous: you get the answer in the HTTP response, and they accept a URL, a `gcsKey` from a connected storage bucket, multipart or raw bytes up to 30 MB.

**Batch** (`POST /v1/batches`) takes up to 1,000 URL-only photos per call, processes them asynchronously at the lower batch rate, and delivers one signed webhook per photo. Poll `GET /v1/batches/{id}/photos` when you want an authoritative pull. See [batch and webhooks](/docs/guides/batch-and-webhooks).

## Idempotency

Billable calls are idempotent on request: send an `Idempotency-Key` header and a retry under the same key is never re-charged and never re-runs the model. A replayed selfie registration returns `200` with the stored `point_id` and an `Idempotent-Replay: true` header; every other replayed operation returns `409` before any charge. Without the header, an identical re-run is a new call and is billed again.

## Model versions

Responses carry `model_version`. Faceprints are specific to the model that produced them, which is also why no provider can import another provider's face vectors; migration always means re-indexing from source images.
