# IDBird Redaction API

> Stateless redaction of EU identity documents. Send a passport or ID scan;
> receive it back with the machine-readable zone (MRZ), personal
> identification numbers, portrait photo and signature destroyed at the pixel
> level. The document's own number stays readable by default (opt-in
> redaction). Processed exclusively within the EU. Nothing is stored.
> Redacted images are always PNG, base64-encoded in a JSON envelope.

Machine-readable spec: /openapi.yaml (OpenAPI 3.1). Human reference: /docs.html.
This file is a complete, current, plain-text mirror of the contract.

## The coverage contract

An HTTP 200 means the document was PROCESSED, not that everything was found.
- `findings` (always present) maps detector names to match counts, e.g.
  {"NETHERLANDS_BSN_NUMBER": 1, "MRZ_TD3_LINE_2": 1}. Detected VALUES are
  never returned, logged, or stored.
- `warnings` (always present) names every gap in expected coverage; an empty
  array means full expected coverage.
Callers MUST branch on `warnings` before archiving output: `nothing_detected`
means the image is returned unchanged; `mrz_not_found` and
`country_detector_no_match` mean specific content may still be visible.

## Authentication and limits

- Every request: `Authorization: Bearer idb_…` (keys provisioned by the
  IDBird team; revocation effective on the next request).
- Rate limit: 30 requests/minute per key by default -> 429 `rate_limited`
  with Retry-After (seconds).
- Daily allowance: each key has a daily budget of API calls per UTC day. One
  fully-processed request = one call; a multi-page PDF still counts once.
  Exhausted -> 429 `daily_quota_exceeded`, Retry-After points at next UTC
  midnight. Rejected and failed requests are never billed.

## POST /v1/redact

Multipart form fields:
- `document` (required): JPEG, PNG, BMP, or PDF up to 5 pages, max 10 MiB.
  Type detected from content; filename and declared content type ignored.
- `country_hint` (optional): ISO 3166-1 alpha-2 issuing country (EL accepted
  for GR). With hint: only that country's detectors (most precise). Without:
  auto mode — all fully supported countries' detectors + `no_country_hint`
  warning.
- `redact_photo` (optional): true (default) | false | both.
- `redact_documentnumber` (optional): false (default) | true. Governs only
  the document number printed in the visual zone; the MRZ copy of it is
  always destroyed.

Response, single page (image is always the most-redacted artifact):
{"image": "<base64 PNG>", "warnings": [], "findings": {...}}

Response, multi-page PDF (aggregate warnings/findings at top level):
{"pages": [{"page": 1, "image": "<base64 PNG>", "findings": {...}}, ...],
 "warnings": [], "findings": {...}}

With redact_photo=both, each page also carries `image_photo_visible`: a
sibling copy with the portrait intact and every other redaction applied.

Example:
curl https://api.idbird.eu/v1/redact \
  -H "Authorization: Bearer idb_..." \
  -F document=@scan.jpg -F country_hint=NL

## POST /v1/inspect

Same inputs and detection as /v1/redact; returns only detected information
types with match counts — no image, never any values. Dry run: empty
`findings` means a redaction would find nothing. Billed and rate-limited like
a redaction. Multi-page PDFs add a per-page `pages` findings array.
Response: {"findings": {...}, "warnings": [...]}

## Photo redaction modes (redact_photo)

The portrait is redacted BY DEFAULT. MRZ, personal identification numbers
and the signature are destroyed in EVERY returned copy regardless of mode.
- true (default): portrait destroyed like everything else.
- false: single copy keeps the portrait visible; response carries
  `photo_not_redacted`.
- both: `image` stays fully redacted; `image_photo_visible` carries the
  portrait-intact sibling.

## Document number redaction (redact_documentnumber)

The document's own number (passport / ID-card number) printed in the visual
zone is KEPT BY DEFAULT — it is typically needed by the receiving party.
Personal identification numbers (BSN, NIR, DNI, PESEL, CPR, …) are always
destroyed, and the MRZ — which also encodes the document number — is always
fully destroyed regardless of this flag.
- false (default): the visual-zone document number stays readable; when one
  was detected the response carries `document_number_not_redacted`.
- true: the document number is destroyed like everything else.
Note: for BE and DE the only country-specific detectors ARE document-number
detectors (no printed personal number has a detector there), so default
requests protect MRZ, portrait and signature.

## Warnings (always present; empty = full expected coverage)

- nothing_detected — nothing recognizable found; image returned UNCHANGED.
  Do not archive as redacted without review.
- no_country_hint — auto mode ran (no country_hint given).
- country_detectors_unavailable — no country-specific number detection exists
  for the hinted country; MRZ-level redaction only. The printed national
  number may remain visible.
- country_detector_no_match — no national identifier detected; if the
  document visibly carries one, it may remain.
- mrz_not_found — no machine-readable zone detected (absent on this side,
  cropped, or unreadable). Expected for ID-card fronts.
- missing_face_finding — no portrait detected.
- missing_signature_finding — no signature detected.
- photo_not_redacted — redact_photo=false was requested.
- document_number_not_redacted — a document number was detected and left
  visible (the default; send redact_documentnumber=true to destroy it).

## Errors

Envelope: {"error": {"code": "...", "message": "..."}} — stable codes, static
messages. On any backend failure no image is ever returned.

- 401: invalid_api_key
- 404: not_found
- 405: method_not_allowed
- 413: payload_too_large (over 10 MiB)
- 415: unsupported_media_type (content-sniffed, not extension-based)
- 422: country_hint_invalid, country_not_supported, file_required,
       redact_photo_invalid, redact_documentnumber_invalid, too_many_pages,
       pdf_encrypted, unreadable_image, image_normalization_failed
- 429: rate_limited (back off seconds), daily_quota_exceeded (retry after
       UTC midnight or raise the allowance) — both carry Retry-After
- 500: internal_error
- 502: dlp_unavailable (redaction backend temporarily unavailable; retry
       with backoff)

## Country support

- Country-specific detection: NL, FR, ES, AT, BE, HR, CZ, DK, FI, DE, IE,
  IT, PL, PT, SE. Coverage varies: most have personal-number detectors;
  BE and DE have document-number detectors only.
- MRZ-level only (responses carry country_detectors_unavailable): BG, CY,
  EE, GR (alias EL), HU, LV, LT, LU, MT, RO, SK, SI
- All other codes: rejected with country_not_supported.

## Input requirements

- Formats: JPEG, PNG, BMP, PDF up to 5 pages (not password-protected); each
  PDF page is processed individually.
- Max upload: 10 MiB.
- Orientation: sideways/upside-down scans corrected automatically when
  reliably detectable; metadata is not trusted.
- Quality: sharp, well-lit, uncropped documents detect best. Noisy or
  low-resolution input surfaces as mrz_not_found / nothing_detected.
- Latency: roughly 2–8 seconds per page end-to-end; use client timeouts of
  30 s or more for multi-page PDFs.