Proxy-Endpunkte — Noirdoc Docs

Funktionsweise

Noirdoc stellt eine Catch-All-Route unter ANY /v1/{path} bereit, die jede HTTP-Methode akzeptiert. Der Proxy nimmt Ihre Anfrage entgegen, leitet sie an den passenden Upstream-Provider weiter und gibt dessen Antwort zurueck.

Ist die Maskierung aktiv, werden personenbezogene Daten vor der Weiterleitung pseudonymisiert und in der Antwort wiederhergestellt. Standardmaessig ist die Maskierung deaktiviert.

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/embeddings`	POST	OpenAI-kompatible Text-Embeddings
`/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/skills`	ANY	Anthropic Skills-Verwaltung (Passthrough)
`/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."}
    ]
  }'

Ist die Maskierung aktiv, sieht das Modell <<PERSON_1>> und <<IBAN_1>> anstelle der echten Werte; die Antwort wird vor der Rueckgabe wiederhergestellt. Standardmaessig ist die Maskierung aus — siehe Maskierung.

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."
  }'

Embeddings

Text-Embeddings über den OpenAI-kompatiblen Pfad /v1/embeddings. Wichtig: Embeddings-Anfragen werden in dieser Phase nicht maskiert — der Eingabetext erreicht den Provider im Klartext. Details, Beispiele und Fehlercodes: Embeddings.

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.

Läuft die Anfrage über die verwalteten Plattform-Modelle (kein eigener Provider-Key), liefert der Endpunkt die für die Plattform freigeschalteten Modelle. Siehe Schnellstart.

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 }
  ]
}

Maskierung pro Anfrage (X-Noirdoc-Mask)

Der Request-Header X-Noirdoc-Mask: on|off steuert die PII-Maskierung pro Anfrage, sofern die Maskierungs-Richtlinie der Organisation das erlaubt (Standard: default_off — Maskierung ist aus, bis sie aktiviert wird). Der Header wird vor der Weiterleitung entfernt und erreicht den Provider nie. Details und Beispiele: Maskierung.

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 Embeddings