Proxy-Endpunkte — Noirdoc Docs

Funktionsweise

Noirdoc stellt eine Catch-All-Route unter ANY /v1/{path} bereit, die jede HTTP-Methode akzeptiert. Der Ablauf ist bei jeder Anfrage identisch:

Die eingehende Anfrage wird auf personenbezogene Daten gescannt und pseudonymisiert.
Die pseudonymisierte Anfrage wird an den konfigurierten Upstream-LLM-Provider weitergeleitet.
Die Antwort des Providers wird de-pseudonymisiert und an Ihre Anwendung zurueckgegeben.

Der Proxy ist transparent — Ihr Client-Code muss nicht wissen, dass Noirdoc dazwischen steht.

Unterstützte Pfade

Die folgenden Upstream-Pfade werden ueber den Proxy unterstützt:

Pfad	Methode	Beschreibung
`/v1/chat/completions`	POST	OpenAI-kompatible Chat Completions
`/v1/responses`	POST	OpenAI Responses API
`/v1/messages`	POST	Anthropic Messages API
`/v1/models`	GET	Verfuegbare Modelle des Providers auflisten
`/v1/files`	POST	Datei hochladen
`/v1/files`	GET	Hochgeladene Dateien auflisten
`/v1/files/{file_id}`	GET	Datei-Metadaten abrufen
`/v1/files/{file_id}/content`	GET	Dateiinhalt abrufen
`/v1/pseudonymize`	POST	Eigenstaendige PII-Pseudonymisierung
`/v1/detect`	POST	Eigenstaendige PII-Erkennung

Anfragen an nicht unterstützte Pfade geben einen 404-Fehler mit dem Code unsupported_endpoint zurueck.

Chat Completions

Der am haeufigsten verwendete Endpunkt. Senden Sie eine Chat-Konversation und erhalten Sie eine modellgenerierte Antwort.

curl -X POST https://api.noirdoc.de/v1/chat/completions \
  -H "Authorization: Bearer px-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [
      {"role": "system", "content": "Du bist ein hilfreicher Assistent."},
      {"role": "user", "content": "Fasse den Vertrag für Max Mustermann, IBAN DE89370400440532013000, zusammen."}
    ]
  }'

Noirdoc pseudonymisiert die Benutzernachricht, bevor sie den Provider erreicht. Das Modell sieht <<PERSON_1>> und <<IBAN_1>> anstelle der echten Werte. Die Antwort wird vor der Rueckgabe de-pseudonymisiert.

Anthropic Messages

Wenn Ihr Tenant mit einem Anthropic-Provider konfiguriert ist, senden Sie Nachrichten ueber den Pfad /v1/messages. Verwenden Sie den x-api-key-Header, um die Anfrage an Anthropic weiterzuleiten:

curl -X POST https://api.noirdoc.de/v1/messages \
  -H "x-api-key: px-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Fasse die Patientenakte von Maria Huber zusammen."}
    ]
  }'

Responses API

Leitet Anfragen an die OpenAI Responses API weiter:

curl -X POST https://api.noirdoc.de/v1/responses \
  -H "Authorization: Bearer px-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "input": "Erklaere den Schadensfall von Dr. Weber vom 15.03.2024."
  }'

Azure OpenAI

Fuer Azure OpenAI verwenden Sie den api-key-Header und geben die API-Version als Query-Parameter an:

curl -X POST "https://api.noirdoc.de/v1/chat/completions?api-version=2025-04-01-preview" \
  -H "api-key: px-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [
      {"role": "user", "content": "Erstelle eine Zusammenfassung des Kundengespraechs mit Frau Mueller."}
    ]
  }'

Models

Verfuegbare Modelle des konfigurierten Providers auflisten:

curl https://api.noirdoc.de/v1/models \
  -H "Authorization: Bearer px-your-key"

Die Antwort entspricht dem Standardformat des jeweiligen Providers.

Files

Dateien hochladen und verwalten. Noirdoc scannt hochgeladene Dateien gemaess den File-Handling-Einstellungen des Tenants auf personenbezogene Daten. Je nach Konfiguration werden Dateien mit PII pseudonymisiert, blockiert oder durchgelassen.

curl -X POST https://api.noirdoc.de/v1/files \
  -H "Authorization: Bearer px-your-key" \
  -F "file=@dokument.pdf" \
  -F "purpose=assistants"

Hilfs-Endpunkte

Noirdoc bietet eigenstaendige Hilfs-Endpunkte, die nichts an einen LLM-Provider weiterleiten. Nutzen Sie diese, um Text unabhaengig zu pseudonymisieren oder personenbezogene Daten zu erkennen.

POST /v1/pseudonymize

Pseudonymisiert Text und gibt die Zuordnung der erkannten Entitaeten zurueck.

curl -X POST https://api.noirdoc.de/v1/pseudonymize \
  -H "Authorization: Bearer px-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Max Mustermann, geboren am 15.03.1985, wohnt in Berlin.",
    "language": "de"
  }'

Antwort:

{
  "original": "Max Mustermann, geboren am 15.03.1985, wohnt in Berlin.",
  "pseudonymized": "<<PERSON_1>>, geboren am <<DATE_1>>, wohnt in <<LOCATION_1>>.",
  "entities": [
    {"type": "PERSON", "text": "Max Mustermann", "start": 0, "end": 14},
    {"type": "DATE", "text": "15.03.1985", "start": 28, "end": 38},
    {"type": "LOCATION", "text": "Berlin", "start": 49, "end": 55}
  ],
  "mapping": {
    "<<PERSON_1>>": "Max Mustermann",
    "<<DATE_1>>": "15.03.1985",
    "<<LOCATION_1>>": "Berlin"
  }
}

Request-Body:

Feld	Typ	Erforderlich	Beschreibung
`text`	string	Ja	Der zu pseudonymisierende Text
`language`	string	Ja	Sprachcode (`de`, `en` usw.)

POST /v1/detect

Erkennt personenbezogene Daten im Text, ohne sie zu pseudonymisieren. Nützlich, um vorab zu pruefen, welche Entitaeten in einem Text enthalten sind.

curl -X POST https://api.noirdoc.de/v1/detect \
  -H "Authorization: Bearer px-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Frau Dr. Anna Schmidt, Tel. 030-12345678, lebt in Muenchen.",
    "language": "de"
  }'

Antwort:

{
  "text": "Frau Dr. Anna Schmidt, Tel. 030-12345678, lebt in Muenchen.",
  "entities": [
    {"type": "PERSON", "text": "Dr. Anna Schmidt", "start": 5, "end": 21},
    {"type": "PHONE_NUMBER", "text": "030-12345678", "start": 28, "end": 40},
    {"type": "LOCATION", "text": "Muenchen", "start": 51, "end": 59}
  ]
}

Header-Format-Uebersicht

Das verwendete Header-Format bestimmt, an welchen Provider die Anfrage weitergeleitet wird:

Provider	Header-Format
OpenAI / OpenRouter	`Authorization: Bearer px-...`
Anthropic	`x-api-key: px-...`
Azure OpenAI	`api-key: px-...`

Provider-Routing

Noirdoc bestimmt den Upstream-Provider anhand mehrerer Signale: dem Auth-Header-Format, dem Endpunkt-Pfad, dem Modell-Identifier und optionalen Query-Parametern (z. B. api-version für Azure). In den meisten Faellen genuegt der Auth-Header oder der Modellname, um den richtigen Provider zu bestimmen.

Wenn kein Provider für das angeforderte Modell konfiguriert ist, gibt die API einen 502-Fehler mit dem Code provider_not_configured zurueck.

Nächste Schritte

Sehen Sie alle Fehlercodes, die der Proxy zurueckgeben kann
Erfahren Sie mehr ueber Streaming für Echtzeit-Antworten

Zurück Übersicht Weiter Fehlercodes