API-Übersicht

Base-URL, Authentifizierung, Antwortformat und Endpunkt-Referenz.

Base-URL

Alle API-Anfragen werden an folgende Basis-URL gesendet:

https://api.noirdoc.de

Die Proxy-Endpunkte befinden sich unter dem /v1-Praefix und folgen der OpenAI-API-Konvention. Verwaltungsendpunkte nutzen das /portal-Praefix.

Authentifizierung

Proxy-API-Keys beginnen mit dem Praefix px- und authentifizieren alle /v1/*-Endpunkte. Der Key kann in einem von drei Header-Formaten uebergeben werden:

Authorization: Bearer px-your-key
x-api-key: px-your-key
api-key: px-your-key

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

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

Keys sind immer an einen Tenant gebunden und werden im Noirdoc-Portal verwaltet.

Wenn ein ungueltiger oder fehlender Key uebergeben wird, antwortet die API mit HTTP 401 im Standardformat:

{
  "detail": "Missing or invalid API key"
}

Content-Types

Alle JSON-Anfragen und -Antworten verwenden:

Content-Type: application/json

Datei-Upload-Endpunkte (/v1/files) akzeptieren multipart/form-data. Streaming-Antworten verwenden text/event-stream (Server-Sent Events), wenn "stream": true im Request-Body gesetzt ist.

Antwortformat

Proxy-Endpunkte liefern Antworten im exakten Format des Upstream-LLM-Providers. Ein Aufruf von /v1/chat/completions gibt beispielsweise das standardmaessige OpenAI-Chat-Completion-Objekt zurueck. Noirdoc ist transparent — es leitet die Anfrage weiter und gibt die Antwort unveraendert durch. Ist die Maskierung aktiv, pseudonymisiert es die Anfrage zuvor und stellt die Antwort wieder her.

Wenn der Proxy selbst einen Fehler feststellt, wird ein einheitliches Fehler-Envelope zurueckgegeben:

{
  "error": {
    "type": "proxy_error",
    "code": "provider_not_configured",
    "message": "No API key configured for provider 'openai'."
  }
}

Das Feld type gruppiert Fehler in Kategorien, code identifiziert den spezifischen Fehler und message liefert eine menschenlesbare Beschreibung. Die vollstaendige Liste aller Codes finden Sie unter Fehlercodes.

Provider-Autoerkennung

Noirdoc erkennt den Ziel-Provider automatisch anhand mehrerer Signale. Die Reihenfolge der Auswertung ist:

1. Auth-Header — das verwendete Header-Format (siehe Tabelle oben)
2. Endpunkt-Pfad — z. B. leitet /v1/messages an Anthropic weiter
3. Modell-Identifier — Modellnamen wie claude-* oder gpt-* werden dem jeweiligen Provider zugeordnet
4. Query-Parameter — z. B. signalisiert api-version Azure OpenAI

In den meisten Faellen genuegt der Auth-Header oder der Modellname, um den richtigen Provider zu bestimmen.

Rate Limiting

Der Proxy erzwingt selbst keine Rate Limits. Antwortet der Upstream-Provider mit 429 Too Many Requests (ggf. mit Retry-After-Header), wird diese Antwort unveraendert an Ihre Anwendung durchgereicht.

Streaming

Proxy-Endpunkte unterstützen Streaming. Setzen Sie "stream": true im Request-Body, und Noirdoc gibt eine text/event-stream-Antwort (Server-Sent Events) zurueck. Bei aktiver Maskierung erfolgen Pseudonymisierung und Wiederherstellung in Echtzeit auf jedem gestreamten Chunk — die vollstaendige Antwort wird nicht zwischengespeichert. Aus Sicht des Clients verhaelt sich das Streaming identisch zum direkten Streaming vom Provider.

curl https://api.noirdoc.de/v1/chat/completions \
  -H "Authorization: Bearer px-..." \
  -H "Content-Type: application/json" \
  -N \
  -d '{
    "model": "<model-id>",
    "stream": true,
    "messages": [{"role": "user", "content": "Schreibe ein kurzes Anschreiben."}]
  }'

Das -N-Flag deaktiviert die Ausgabe-Pufferung. Jedes Event ist eine data:-Zeile mit einem partiellen Antwortobjekt; der Stream endet mit data: [DONE]:

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"content":"Sehr"},"index":0}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"content":" geehrte"},"index":0}]}

data: [DONE]

Endpunktgruppen

Praefix	Zweck	Auth
/v1/*	LLM-Proxy	Proxy-API-Key (px-*)
/v1/pseudonymize	Eigenstaendige PII-Pseudonymisierung	Proxy-API-Key
/v1/detect	Eigenstaendige PII-Erkennung	Proxy-API-Key
/portal/*	Self-Service Key- & Provider-Verwaltung	JWT (Self-Service-Portal)

Nächste Schritte

• Erkunden Sie die Proxy-Endpunkte, um LLM-Anfragen ueber den Proxy zu senden
• Sehen Sie alle Fehlercodes, die die API zurueckgeben kann