Quickstart

From zero to your first face match in four calls. You'll create an API key, index a face from a photo, search the collection with another photo, then check your credit balance. Every call here is a real request against the production API at https://api.sightradar.com.

Get an API key

Sign in to the console and open API Keys → Create key. Copy the key — it starts with frs_ and is shown once. Export it so the snippets below pick it up:

shell

export SR_API_KEY="frs_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export SR_BASE="https://api.sightradar.com"

Every request authenticates with Authorization: Bearer $SR_API_KEY. New accounts start with trial credits, so you can run this whole guide for free.

Create a collection

A collection is the namespace your faces live in (e.g. one per event). This call is free.

curl — create collection

curl -X POST "$SR_BASE/v1/collections" \
  -H "Authorization: Bearer $SR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"collection_id": "quickstart-demo"}'

200 response

{
  "collection_id": "quickstart-demo",
  "status": "active",
  "photo_count": 0,
  "face_count": 0,
  "selfie_count": 0,
  "created_at": "2026-06-22T19:40:00Z"
}

Index a face

Send a photo by URL (or a multipart file, or raw bytes). SightRadar detects every quality-gated face and stores it. Pass a photoId so you can find the photo later. Billable: 62 credits.

curl — index

curl -X POST "$SR_BASE/v1/collections/quickstart-demo/index" \
  -H "Authorization: Bearer $SR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/group-photo.jpg", "photoId": "photo-001"}'

200 response

{
  "collection_id": "quickstart-demo",
  "photo_id": "photo-001",
  "indexed": 3,
  "detected_face_count": 3,
  "rejected_face_count": 0,
  "faces": [
    { "face_index": 0, "point_id": "…", "det_score": 0.84, "min_px": 120, "bbox": {"x":24,"y":22,"w":53,"h":53} }
  ],
  "model_version": "buffalo_l"
}

Search with a selfie

Search the collection with a different photo of the same person. You get back the matching photo_ids, ranked by similarity. Billable: 62 credits.

curl — search

curl -X POST "$SR_BASE/v1/collections/quickstart-demo/search" \
  -H "Authorization: Bearer $SR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/selfie.jpg", "limit": 10}'

200 response

{
  "collection_id": "quickstart-demo",
  "matches": [
    { "photo_id": "photo-001", "score": 0.91 }
  ],
  "photo_ids": ["photo-001"],
  "model_version": "buffalo_l"
}

No face in the selfie? You get "reason": "no_face" with an empty match list (and you are not charged for a failed engine call).

Check your wallet

See how many credits you have left. Billable calls also return an X-Credits-Remaining header, so you can track spend inline.

curl — wallet

curl "$SR_BASE/v1/wallet" \
  -H "Authorization: Bearer $SR_API_KEY"

200 response

{ "balance_credits": 4999876 }

What next?

Bulk imports: use POST /v1/batches to index up to 1,000 photos per call, with per-photo results delivered to your webhook.
Selfie registration: register a selfie once and reuse it across searches with search-by-id.
Auto-recharge: never run out mid-batch — set a threshold in the console's Billing settings.

Explore the full API Reference