API<REFERENCE<V1<<<<<<<<<<<<

API reference

The IDBird Redaction API is deliberately small: two endpoints, one request shape, one error envelope. This page is the complete surface. The machine-readable spec and interactive reference live at api.idbird.eu.

Base URL & authentication

Every request carries a bearer API key issued by the IDBird team. Keys are stored as a SHA-256 hash only and are checked live on every request — revocation takes effect on the very next call.

https://api.idbird.eu
Authorization: Bearer idb_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Endpoints

`POST`	`/v1/redact`	Redact a document and return the cleaned image plus findings and warnings.
`POST`	`/v1/inspect`	Dry run: return findings and warnings only — no image is ever returned.
`GET`	`/up`	Health check, no authentication.

Request

Both endpoints accept the same multipart/form-data request.

Field	Required	Description
`document`	yes	The file: JPEG, PNG, BMP or PDF (up to 5 pages by default), max 10 MiB. The type is sniffed from the file content — filename and Content-Type header are ignored.
`country_hint`	no	ISO 3166-1 alpha-2 code of the issuing country, case-insensitive (EL is accepted as alias for GR). Omit it to run in auto mode — with a hint, detection is sharper.
`photo_redaction`	no	redact (default) removes the portrait photo. keep leaves it visible and adds the photo_not_redacted warning. both returns two images: fully redacted, and photo visible.

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

Responses

The image field is always a base64-encoded PNG and always the most-redacted artifact of the request. findings contains detector names and counts — never values. warnings and findings are always present, empty when clean.

POST /v1/redact — single page

{
  "image": "iVBORw0KGgoAAAANSUhEUgAA…",
  "warnings": [],
  "findings": {
    "MRZ_TD3_LINE_1": 1,
    "MRZ_TD3_LINE_2": 1,
    "NETHERLANDS_PASSPORT": 1,
    "OBJECT_TYPE/PERSON/FACE": 2,
    "OBJECT_TYPE/PERSON/SIGNATURE": 1
  }
}

POST /v1/redact — photo_redaction=both

{
  "image": "…fully redacted PNG…",
  "image_photo_visible": "…portrait intact, everything else redacted…",
  "warnings": [],
  "findings": {
    "MRZ_TD3_LINE_2": 1,
    "NETHERLANDS_BSN_NUMBER": 1
  }
}

POST /v1/redact — multi-page PDF (pages replaces image, 1-based)

{
  "pages": [
    { "page": 1, "image": "iVBORw0KGgo…", "findings": { "OBJECT_TYPE/PERSON/FACE": 1 } },
    { "page": 2, "image": "iVBORw0KGgo…", "findings": { "MRZ_TD3_LINE_2": 1, "NETHERLANDS_BSN_NUMBER": 1 } }
  ],
  "warnings": [],
  "findings": {
    "MRZ_TD3_LINE_2": 1,
    "NETHERLANDS_BSN_NUMBER": 1,
    "OBJECT_TYPE/PERSON/FACE": 1
  }
}

POST /v1/inspect — findings only, no image, ever

{
  "findings": {
    "NETHERLANDS_BSN_NUMBER": 1,
    "MRZ_TD3_LINE_2": 1
  },
  "warnings": ["no_country_hint"]
}

Warning codes

HTTP 200 means processed, not protected. Warnings are emitted in a fixed, documented order; branch on them before archiving. The eight possible codes:

Errors

All errors use one envelope with a stable code and a static, English message — safe to match on, free of any document content:

{
  "error": {
    "code": "country_not_supported",
    "message": "The issuing country \"US\" is not supported by this service."
  }
}

HTTP	code	message
`401`	`invalid_api_key`	The bearer API key is missing, unknown, or revoked.
`404`	`not_found`	Not found.
`405`	`method_not_allowed`	Method not allowed.
`413`	`payload_too_large`	The document exceeds the 10 MiB limit.
`415`	`unsupported_media_type`	The document must be a JPEG, PNG, BMP or PDF; the type is detected from file content.
`422`	`country_hint_invalid`	The country_hint must be a two-letter ISO 3166-1 alpha-2 code.
`422`	`country_not_supported`	The issuing country "US" is not supported by this service.
`422`	`file_required`	The document file is required.
`422`	`photo_redaction_invalid`	The photo_redaction field must be one of: redact, keep, both.
`422`	`too_many_pages`	The PDF exceeds the 5-page limit; split it and submit the pages separately.
`422`	`pdf_encrypted`	Encrypted PDFs are not supported.
`422`	`unreadable_image`	The document could not be decoded as an image.
`422`	`image_normalization_failed`	The image could not be reduced to the redaction backend request budget without degrading below the quality floor.
`429`	`rate_limited`	Too many requests; retry later.
`429`	`daily_quota_exceeded`	The daily allowance of 50 API call(s) for this key is exhausted for today (UTC).
`500`	`internal_error`	Internal error.
`502`	`dlp_unavailable`	The redaction backend is unavailable; no image was produced.

Limits & billing

Rate limit: 30 requests per minute per key; 429 with a Retry-After header when exceeded.
Daily allowance: 50 calls per key per day by default (UTC); raised per key by the IDBird team with immediate effect.
One fully processed request is one billable call — a multi-page PDF included. Rejected (4xx) and failed (5xx) requests are never billed, and the quota is checked before processing, so an over-quota request costs nothing.

Country coverage

National number + MRZ + photo + signature

NL Netherlands
DE Germany
FR France
ES Spain
AT Austria
BE Belgium
HR Croatia
CZ Czechia
DK Denmark
FI Finland
IE Ireland
IT Italy
PL Poland
PT Portugal
SE Sweden

MRZ + photo + signature

BG Bulgaria
CY Cyprus
EE Estonia
GR Greece
HU Hungary
LV Latvia
LT Lithuania
LU Luxembourg
MT Malta
RO Romania
SK Slovakia
SI Slovenia

Documents from any other issuing country are declined outright — never silently half-redacted.

Machine-readable documentation

The OpenAPI 3.1 spec is pinned to the implementation by a CI test: every reason code and warning the service can emit must be documented, and nothing more. The docs cannot drift.

Interactive reference (Redoc) openapi.yaml llms-full.txt