Erkennen & Pseudonymisieren

Beide Endpunkte verwenden dieselbe Erkennung wie die Maskierung auf den Chat-Endpunkten. Die Anfrage erreicht keinen Anbieter. Die Maskierungsrichtlinie Ihrer Organisation spielt für diese Endpunkte keine Rolle. So prüfen Sie, was die Maskierung in Ihren Texten erfassen würde, bevor Sie sie einschalten. Eine Anleitung dazu steht unter Maskierung einschalten.

Anfrage

Beide Endpunkte nehmen denselben JSON-Body an:

Feld	Typ	Pflicht	Inhalt
`text`	String	ja	der zu prüfende Text
`language`	String	nein	Sprache des Textes: `de` (Standard) oder `en`

Die Maskierung auf den Chat-Endpunkten erkennt immer mit der Sprache de. Mit dem Standardwert prüfen Sie also mit derselben Spracheinstellung wie die Maskierung.

Fehlt text, antwortet das Gateway mit Statuscode 422 und einem Feld detail, das das fehlende Feld nennt.

Erkennen

POST /v1/detect

Authentifizierung: ja, API-Schlüssel
Maskierung: nein, nur Erkennung
Format: JSON
Anbieter: keiner

/v1/detect gibt die erkannten Stellen im Text zurück. Den Text selbst ändert der Endpunkt nicht.

Feld	Inhalt
`entities`	Liste der erkannten Stellen
`entities[].entity_type`	Art der Angabe, zum Beispiel `PERSON`, `EMAIL`, `IBAN`
`entities[].text`	der erkannte Text
`entities[].start`, `entities[].end`	Position im Text (Zeichenindex, `end` exklusiv)
`entities[].score`	Sicherheit der Erkennung zwischen 0 und 1
`entities[].source`	Erkenner, der die Stelle gefunden hat
`entity_count`	Anzahl der Einträge in `entities`

Shell

curl https://api.noirdoc.de/v1/detect \
  -H "Authorization: Bearer $NOIRDOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Anna Weber, DE89 3704 0044 0532 0130 00"
  }'

Python

import os
import httpx

API_KEY = os.environ["NOIRDOC_API_KEY"]
TEXT = "Anna Weber, DE89 3704 0044 0532 0130 00"

response = httpx.post(
    "https://api.noirdoc.de/v1/detect",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"text": TEXT},
)
print(response.json()["entity_count"])

TypeScript

const res = await fetch("https://api.noirdoc.de/v1/detect", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NOIRDOC_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    text: "Anna Weber, DE89 3704 0044 0532 0130 00",
  }),
});
const { entities } = await res.json();

JSON

{
  "entities": [
    {
      "entity_type": "PERSON",
      "text": "Anna Weber",
      "start": 0,
      "end": 10,
      "score": 0.93,
      "source": "presidio"
    },
    {
      "entity_type": "IBAN",
      "text": "DE89 3704 0044 0532 0130 00",
      "start": 12,
      "end": 39,
      "score": 1.0,
      "source": "presidio"
    }
  ],
  "entity_count": 2
}

Pseudonymisieren

POST /v1/pseudonymize

Authentifizierung: ja, API-Schlüssel
Maskierung: ja, im Ergebnis
Format: JSON
Anbieter: keiner

/v1/pseudonymize erkennt dieselben Stellen und ersetzt sie durch Platzhalter der Form <<TYP_N>>. Gleicher Text bekommt denselben Platzhalter, unabhängig von Groß- und Kleinschreibung.

Feld	Inhalt
`original`	der gesendete Text
`pseudonymized`	der Text mit Platzhaltern
`entities`	die erkannten Stellen, wie bei `/v1/detect`
`mapping`	Zuordnung Platzhalter → Originaltext

Das Gateway speichert diese Zuordnung nicht. Sie steht nur in der Antwort. Das Pseudonym-Label Ihrer Organisation (Models → Datenschutz) gilt auf diesem Endpunkt nicht; die Platzhalter tragen immer den Typ der Angabe.

Shell

curl https://api.noirdoc.de/v1/pseudonymize \
  -H "Authorization: Bearer $NOIRDOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Anna Weber, DE89 3704 0044 0532 0130 00"
  }'

Python

response = httpx.post(
    "https://api.noirdoc.de/v1/pseudonymize",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"text": TEXT},
)
print(response.json()["pseudonymized"])

TypeScript

const url = "https://api.noirdoc.de/v1/pseudonymize";
const res = await fetch(url, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NOIRDOC_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    text: "Anna Weber, DE89 3704 0044 0532 0130 00",
  }),
});
const { pseudonymized, mapping } = await res.json();

JSON

{
  "original": "Anna Weber, DE89 3704 0044 0532 0130 00",
  "pseudonymized": "<<PERSON_1>>, <<IBAN_1>>",
  "entities": ["…"],
  "mapping": {
    "<<PERSON_1>>": "Anna Weber",
    "<<IBAN_1>>": "DE89 3704 0044 0532 0130 00"
  }
}

Fehler auf diesen Endpunkten

Status	Ursache
401	Schlüssel fehlt oder ist ungültig, siehe Authentifizierung & Header
422	Der Body ist kein gültiges JSON oder `text` fehlt; Feld `detail` statt Fehlerobjekt