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

API-reference

IDBird Redaction API er bevidst lille: to endpoints, én request-form, én fejlkonvolut. Denne side er hele overfladen. Den maskinlæsbare specifikation og den interaktive reference ligger på api.idbird.eu.

Basis-URL og autentificering

Hver anmodning bærer en Bearer-API-nøgle udstedt af IDBird-teamet. Nøgler gemmes kun som SHA-256-hash og tjekkes live ved hver anmodning — tilbagekaldelse virker fra næste kald.

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

Endpoints

`POST`	`/v1/redact`	Maskér et dokument og modtag det rensede billede plus findings og warnings.
`POST`	`/v1/inspect`	Tørløb: kun findings og warnings — der returneres aldrig et billede.
`GET`	`/up`	Sundhedstjek, uden autentificering.

Request

Begge endpoints accepterer den samme multipart/form-data-anmodning.

Felt	Påkrævet	Beskrivelse
`document`	ja	Filen: JPEG, PNG, BMP eller PDF (som standard op til 5 sider), maks. 10 MiB. Typen aflæses af filens indhold — filnavn og Content-Type-header ignoreres.
`country_hint`	nej	ISO 3166-1 alpha-2-kode for udstedelseslandet, uafhængig af store/små bogstaver (EL accepteres som alias for GR). Udelades den, køres automatisk tilstand — med hint er detektionen skarpere.
`photo_redaction`	nej	redact (standard) fjerner fotoet. keep lader det være synligt og tilføjer warningen photo_not_redacted. both returnerer to billeder: fuldt maskeret og med synligt foto.

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

Svar

Feltet image er altid en base64-kodet PNG og altid det mest maskerede resultat af anmodningen. findings indeholder detektornavne og antal — aldrig værdier. warnings og findings er altid til stede, tomme når alt er rent.

POST /v1/redact — én side

{
  "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 — flersidet PDF (pages erstatter image, tæller fra 1)

{
  "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 — kun findings, aldrig et billede

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

Warning-koder

HTTP 200 betyder behandlet, ikke beskyttet. Warnings kommer i fast, dokumenteret rækkefølge; tjek dem før arkivering. De otte mulige koder:

Fejl

Alle fejl bruger én konvolut med en stabil kode og en statisk engelsk besked — sikker at matche på, fri for dokumentindhold:

{
  "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.

Grænser og fakturering

Rate-limit: 30 anmodninger pr. minut pr. nøgle; 429 med Retry-After-header ved overskridelse.
Dagligt kontingent: som standard 50 kald pr. nøgle pr. dag (UTC); forhøjes pr. nøgle af IDBird-teamet med øjeblikkelig virkning.
Én fuldt behandlet anmodning er ét fakturerbart kald — flersidet PDF inklusive. Afviste (4xx) og fejlede (5xx) anmodninger faktureres aldrig, og kontingentet tjekkes før behandling: En anmodning over grænsen koster intet.

Landedækning

Nationalt nummer + MRZ + foto + underskrift

NL Nederlandene
DE Tyskland
FR Frankrig
ES Spanien
AT Østrig
BE Belgien
HR Kroatien
CZ Tjekkiet
DK Danmark
FI Finland
IE Irland
IT Italien
PL Polen
PT Portugal
SE Sverige

MRZ + foto + underskrift

BG Bulgarien
CY Cypern
EE Estland
GR Grækenland
HU Ungarn
LV Letland
LT Litauen
LU Luxembourg
MT Malta
RO Rumænien
SK Slovakiet
SI Slovenien

Dokumenter fra ethvert andet udstedelsesland afvises blankt — aldrig halvt maskeret i stilhed.

Maskinlæsbar dokumentation

OpenAPI 3.1-specifikationen er hæftet til implementeringen med en CI-test: Hver fejlkode og hver warning, tjenesten kan udsende, skal være dokumenteret — og intet mere. Dokumentationen kan ikke drive væk.

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