API Reference

SightRadar Face Recognition API

An AWS-Rekognition-compatible REST API for face indexing and search, where you only pay for what you use — billed per photo. New here? Start with the quickstart — provision a key, index a face, run a search, and check your wallet in four calls.

Quickstart Download OpenAPI spec View OpenAPI spec

Official SDKs: Python SDK Node / TypeScript SDK

Endpoint reference

All 19 endpoints of the SightRadar Face Recognition API, version 1.0.0. Base URL https://api.sightradar.com. Authenticate with Authorization: Bearer frs_<prefix>_<secret> — see the quickstart to get a key. The interactive playground for these same endpoints is below.

Collections

Create and manage face collections (the registry of your indexed photos).

GET/v1/collections

List collections

Lists your collections, newest paging via limit/offset. Free.

GET https://api.sightradar.com/v1/collections

Parameters

Field	Type	Description
`limit`in query	`integer`	—
`offset`in query	`integer`	—

Response body

Field	Type	Description
`collections`	`object[]`	—

Status codes

200 Your collections.
401 Missing or invalid API key.

POST/v1/collections

Create a collection

Creates a new face collection owned by your account. Free (0 credits).

POST https://api.sightradar.com/v1/collections

Request body (application/json)

Field	Type	Description
`collection_id`required	`string`	Your chosen identifier for the collection.

Response body

Field	Type	Description
`collection_id`	`string`	—
`status`	`"active" \| "deleting" \| "deleted"`	—
`photo_count`	`integer`	—
`face_count`	`integer`	—
`selfie_count`	`integer`	—
`created_at`	`string`	—

Status codes

200 Collection created.
400 collection_id missing.
401 Missing or invalid API key.
409 Collection already exists in a non-active state.

GET/v1/collections/{id}

Describe a collection

Returns the collection with LIVE face/selfie counts merged from the engine. Free.

GET https://api.sightradar.com/v1/collections/{id}

Parameters

Field	Type	Description
`id`requiredin path	`string`	Collection id.

Response body

Field	Type	Description
`collection_id`	`string`	—
`status`	`"active" \| "deleting" \| "deleted"`	—
`photo_count`	`integer`	—
`face_count`	`integer`	—
`selfie_count`	`integer`	—
`created_at`	`string`	—

Status codes

200 Collection detail.
401 Missing or invalid API key.
404 Resource not found.

DELETE/v1/collections/{id}

Delete a collection (cascade)

Schedules a durable cascade delete — all faces and selfies are removed asynchronously. Returns 202 with a workflow id. Free.

DELETE https://api.sightradar.com/v1/collections/{id}

Parameters

Field	Type	Description
`id`requiredin path	`string`	Collection id.

Response body

Field	Type	Description
`status`	`string`	—
`workflow_id`	`string`	—
`message`	`string`	—

Status codes

202 Deletion scheduled.
401 Missing or invalid API key.
404 Resource not found.

GET/v1/collections/{id}/metrics

Collection metrics

Live face/selfie counts straight from the engine's vector store. Free.

GET https://api.sightradar.com/v1/collections/{id}/metrics

Parameters

Field	Type	Description
`id`requiredin path	`string`	—

Response body

Field	Type	Description
`collection_id`	`string`	—
`status`	`string`	—
`photo_count`	`integer`	—
`face_count`	`integer`	—
`selfie_count`	`integer`	—

Status codes

200 Counts.
401 Missing or invalid API key.
404 Resource not found.
502 Engine metrics unavailable.

Faces

Index, search, detect, and compare faces (billable operations).

POST/v1/collections/{id}/index

Index faces from a photo

Detects all quality-gated faces in an image and stores them in the collection (Rekognition `IndexFaces`). **Billable: 62 credits.**

Provide the image as JSON `{url}` / `{gcsKey}`, a multipart `file`, or raw image bytes. Optional `photoId` is the per-image key (defaults to a content hash).

POST https://api.sightradar.com/v1/collections/{id}/index

Parameters

Field	Type	Description
`id`requiredin path	`string`	—
`photoId`in query	`string`	Per-image key (also accepted in body).
`Idempotency-Key`in header	`string`	Opt-in idempotency. A replay under the same key returns 409 before any charge.

Request body (application/json)

Field	Type	Description
`url`	`string`	Public image URL.
`gcsKey`	`string`	Google Cloud Storage object key.
`photoId`	`string`	Optional per-image key.

Also accepts: multipart/form-data, application/octet-stream

Response body

Field	Type	Description
`collection_id`	`string`	—
`photo_id`	`string`	—
`indexed`	`integer`	Faces stored.
`detected_face_count`	`integer`	—
`rejected_face_count`	`integer`	Detected but quality-gated out.
`faces`	`object[]`	—
`model_version`	`string`	—

Status codes

200 Faces indexed.
400 Cannot decode image, or no url/gcsKey/body provided.
401 Missing or invalid API key.
402 Wallet balance too low for this operation.
409 A request with this Idempotency-Key is in flight or already processed.
413 Image exceeds the 30 MB encoded size cap.
429 Per-key RPS or per-customer concurrency limit exceeded.
502 Engine error (the credit hold is refunded automatically).

POST/v1/collections/{id}/search

Search a collection

Search by a selfie image OR a precomputed 512-d embedding. Returns the matching photo ids ranked by similarity. **Billable: 62 credits.**

POST https://api.sightradar.com/v1/collections/{id}/search

Parameters

Field	Type	Description
`id`requiredin path	`string`	—
`Idempotency-Key`in header	`string`	Opt-in idempotency. A replay under the same key returns 409 before any charge.

Request body (application/json)

Field	Type	Description
`embedding`	`number[]`	—
`url`	`string`	—
`gcsKey`	`string`	—
`threshold`	`number`	Min cosine similarity (0-1).
`limit`	`integer`	Max matches.

Also accepts: multipart/form-data

Response body

Field	Type	Description
`collection_id`	`string`	—
`matches`	`object[]`	—
`photo_ids`	`string[]`	—
`reason`	`string`	Present when no match: no_face \| low_quality_selfie \| point_not_found.
`model_version`	`string`	—

Status codes

200 Search result.
400 Cannot decode image, or no url/gcsKey/body provided.
401 Missing or invalid API key.
402 Wallet balance too low for this operation.
409 A request with this Idempotency-Key is in flight or already processed.
429 Per-key RPS or per-customer concurrency limit exceeded.
502 Engine error (the credit hold is refunded automatically).

POST/v1/collections/{id}/search-by-id

Search by a stored selfie point id

Search using a previously-registered selfie's `pointId` (Rekognition `SearchFaces` by FaceId). **Billable: 62 credits.**

POST https://api.sightradar.com/v1/collections/{id}/search-by-id

Parameters

Field	Type	Description
`id`requiredin path	`string`	—
`Idempotency-Key`in header	`string`	Opt-in idempotency. A replay under the same key returns 409 before any charge.

Request body (application/json)

Field	Type	Description
`pointId`required	`string`	A point_id returned by /selfies.
`threshold`	`number`	Min cosine similarity (0-1).
`limit`	`integer`	Max matches to return.

Response body

Field	Type	Description
`collection_id`	`string`	—
`matches`	`object[]`	—
`photo_ids`	`string[]`	—
`reason`	`string`	Present when no match: no_face \| low_quality_selfie \| point_not_found.
`model_version`	`string`	—

Status codes

200 Search result.
400 pointId missing.
401 Missing or invalid API key.
402 Wallet balance too low for this operation.
429 Per-key RPS or per-customer concurrency limit exceeded.
502 Engine error (the credit hold is refunded automatically).

POST/v1/detect

Detect faces (no storage)

Detect + quality-gate faces in an image WITHOUT storing anything (Rekognition `DetectFaces`). **Billable: 62 credits.**

POST https://api.sightradar.com/v1/detect

Parameters

Field	Type	Description
`Idempotency-Key`in header	`string`	Opt-in idempotency. A replay under the same key returns 409 before any charge.

Request body (application/json)

Field	Type	Description
`url`	`string`	Public image URL.
`gcsKey`	`string`	Google Cloud Storage object key.
`photoId`	`string`	Optional per-image key.

Also accepts: multipart/form-data, application/octet-stream

Response body

Field	Type	Description
`detected_face_count`	`integer`	—
`gated_face_count`	`integer`	—
`faces`	`object[]`	—

Status codes

200 Detection result.
400 Cannot decode image, or no url/gcsKey/body provided.
401 Missing or invalid API key.
402 Wallet balance too low for this operation.
429 Per-key RPS or per-customer concurrency limit exceeded.
502 Engine error (the credit hold is refunded automatically).

POST/v1/compare

Compare two faces

Compare the best face in two images (Rekognition `CompareFaces`). Returns cosine similarity (0-1) and a match boolean at the configured threshold. **Billable: 62 credits.**

POST https://api.sightradar.com/v1/compare

Parameters

Field	Type	Description
`Idempotency-Key`in header	`string`	Opt-in idempotency. A replay under the same key returns 409 before any charge.

Request body (application/json)

Field	Type	Description
`sourceUrl`	`string`	—
`sourceGcsKey`	`string`	—
`targetUrl`	`string`	—
`targetGcsKey`	`string`	—
`source_embedding`	`number[]`	—
`target_embedding`	`number[]`	—

Response body

Field	Type	Description
`face_found`	`boolean`	—
`similarity`	`number,null`	Cosine similarity (0-1).
`match`	`boolean`	—
`threshold`	`number`	—

Status codes

200 Comparison result.
400 Bad body or missing source/target.
401 Missing or invalid API key.
402 Wallet balance too low for this operation.
429 Per-key RPS or per-customer concurrency limit exceeded.
502 Engine error (the credit hold is refunded automatically).

Selfies

POST/v1/collections/{id}/selfies

Register a selfie

Register a single-face selfie (Rekognition `IndexFaces` MaxFaces=1). Returns a `point_id` you can later pass to `search-by-id`. **Billable: 62 credits.**

POST https://api.sightradar.com/v1/collections/{id}/selfies

Parameters

Field	Type	Description
`id`requiredin path	`string`	—
`userId`in query	`string`	Required (also accepted in body).
`selfieId`in query	`string`	Optional; defaults to a content hash.
`Idempotency-Key`in header	`string`	Opt-in idempotency. A replay under the same key returns 409 before any charge.

Request body (application/json)

Field	Type	Description
`url`	`string`	Public image URL.
`gcsKey`	`string`	Google Cloud Storage object key.
`photoId`	`string`	Optional per-image key.
`userId`required	`string`	—
`selfieId`	`string`	—

Also accepts: multipart/form-data

Response body

Field	Type	Description
`face_found`	`boolean`	—
`reason`	`string`	no_face when face_found=false.
`collection_id`	`string`	—
`user_id`	`string`	—
`selfie_id`	`string`	—
`point_id`	`string`	Pass to search-by-id.
`embedding`	`number[]`	512-d L2-normalized vector.
`det_score`	`number`	—
`quality_passed`	`boolean`	—
`model_version`	`string`	—

Status codes

200 Selfie processed (check face_found).
400 userId missing or bad image.
401 Missing or invalid API key.
402 Wallet balance too low for this operation.
429 Per-key RPS or per-customer concurrency limit exceeded.
502 Engine error (the credit hold is refunded automatically).

Batch

Asynchronous bulk processing with webhook callbacks.

POST/v1/batches

Submit a batch job

Fire-and-forget bulk processing of up to 1000 **URL-only** photos. base64 is rejected in batch — use real-time endpoints for inline images. Results arrive per-photo via your registered webhook, or poll `GET /v1/batches/{id}`.

POST https://api.sightradar.com/v1/batches

Request body (application/json)

Field	Type	Description
`collection_id`required	`string`	—
`op`required	`"index" \| "match"`	—
`webhook_endpoint_id`	`string`	Optional; an endpoint id from POST /v1/webhooks.
`photos`required	`object[]`	—

Response body

Field	Type	Description
`batch_id`	`string`	—
`total_photos`	`integer`	—
`status`	`string`	—
`message`	`string`	—

Status codes

202 Batch accepted.
400 Validation error (missing fields, base64 in batch, too large).
401 Missing or invalid API key.

GET/v1/batches/{id}

Get batch status

Poll a batch's progress (webhook-down fallback). Free.

GET https://api.sightradar.com/v1/batches/{id}

Parameters

Field	Type	Description
`id`requiredin path	`string`	—

Response body

Field	Type	Description
`batch_id`	`string`	—
`collection_id`	`string`	—
`op`	`string`	—
`status`	`string`	—
`total_photos`	`integer`	—
`succeeded`	`integer`	—
`failed`	`integer`	—
`pending`	`integer`	—
`claimed`	`integer`	—
`created_at`	`string`	—

Status codes

200 Batch status.
401 Missing or invalid API key.
404 Resource not found.

Webhooks

GET/v1/webhooks

List webhook endpoints

GET https://api.sightradar.com/v1/webhooks

Response body

Field	Type	Description
`webhooks`	`object[]`	—

Status codes

200 Your webhook endpoints.
401 Missing or invalid API key.

POST/v1/webhooks

Register a webhook endpoint

Register an HTTPS URL to receive per-photo batch results. We sign each delivery with HMAC-SHA256 over `timestamp.body`. If you omit `secret`, one is generated and returned **once**.

POST https://api.sightradar.com/v1/webhooks

Request body (application/json)

Field	Type	Description
`url`required	`string`	Public HTTPS URL.
`secret`	`string`	Optional signing secret; generated if omitted.

Response body

Field	Type	Description
`webhook_endpoint_id`	`string`	—
`url`	`string`	—
`status`	`string`	—
`secret`	`string`	Returned ONCE only when generated.
`note`	`string`	—

Status codes

200 Endpoint registered.
400 Invalid or non-HTTPS/private URL.
401 Missing or invalid API key.
503 Webhook encryption key not configured.

Wallet & Usage

Check your credit balance, usage, and auto-recharge config.

GET/v1/wallet

Get credit balance

Returns your current credit balance. Free.

GET https://api.sightradar.com/v1/wallet

Response body

Field	Type	Description
`balance_credits`	`integer`	—

Status codes

200 Balance.
401 Missing or invalid API key.

GET/v1/usage

Usage report

Per-operation usage aggregation over the last N days (default 30, max 365). Free.

GET https://api.sightradar.com/v1/usage

Parameters

Field	Type	Description
`days`in query	`integer`	—

Response body

Field	Type	Description
`days`	`integer`	—
`by_op`	`object[]`	—
`total_calls`	`integer`	—
`total_credits`	`integer`	—

Status codes

200 Usage breakdown.
401 Missing or invalid API key.

Health

Liveness and readiness probes (unauthenticated).

GET/healthzno auth

Liveness probe

Process is up and serving. No dependencies. Unauthenticated.

GET https://api.sightradar.com/healthz

Response body

Field	Type	Description
`status`	`string`	—

Status codes

200 Service is alive.

GET/readyzno auth

Readiness probe

Verifies the Postgres connection. 200 = ready, 503 = not ready. Unauthenticated.

GET https://api.sightradar.com/readyz

Response body

Field	Type	Description
`status`	`string`	—
`postgres`	`string`	—

Status codes

200 Ready to serve traffic.
503 Not ready (Postgres down or unconfigured).

Interactive playground

Try any endpoint against the live API with your own key.