API referenceBatch
Submit a batch job
Fire-and-forget bulk processing of up to 1000 URL-only photos. (POST /v1/batches)
Last updated
POST
/v1/batches- Auth
- Bearer API key
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}.
Example request
curl -X POST "https://api.sightradar.com/v1/batches" \
-H "Authorization: Bearer $SR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"collection_id":"event-2026","op":"index","photos":[{"url":"https://example.com/photo.jpg","external_id":"photo-1"}]}'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 | A new batch starts as processing; it becomes completed once no photo is pending or claimed. |
message | string |
Status codes
| Status | Meaning |
|---|---|
202 | Batch accepted. |
400 | Validation error: missing fields, op not index|match, empty photos, base64 in batch, or more than 1000 photos ({"error":"batch too large","max":1000,"received":N}). Per-photo URL problems are NOT rejected here; they surface per photo as image_fetch_failed (the URL could not be fetched: the host answered 404 or 410, or the host is not allowed or does not resolve), image_access_denied (403 or an expired signed URL), image_too_large, image_corrupt (the bytes are not a decodable image) or image_invalid. A 5xx or timeout from the image host is retried and ends as retry_exhausted if it persists. The real-time endpoints report a URL the host answers 4xx for differently: a 400 whose reason_code is invalid_url. |
401 | Missing or invalid API key. |