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 die Praefixe /portal und /admin.

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. Im Managed Service verwalten Sie Ihre Keys ueber das Portal. Bei Self-Hosting koennen Keys auch ueber Umgebungsvariablen konfiguriert werden.

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

{
  "error": {
    "type": "auth_error",
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or has been revoked."
  }
}

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 pseudonymisiert die Anfrage, leitet sie weiter, stellt die Antwort wieder her und gibt sie unveraendert durch.

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

Noirdoc erzwingt Rate Limits auf Proxy-Endpunkten. Wenn Sie das Limit ueberschreiten, antwortet die API mit HTTP 429 Too Many Requests. Die Antwort enthaelt einen Retry-After-Header, der angibt, wie viele Sekunden Sie vor einem erneuten Versuch warten sollten.

Streaming

Proxy-Endpunkte unterstützen Streaming, sofern der Upstream-Provider dies unterstützt. Setzen Sie "stream": true im Request-Body, und Noirdoc gibt eine text/event-stream-Antwort zurueck. Pseudonymisierung und Wiederherstellung erfolgen in Echtzeit auf jedem gestreamten Chunk. Details finden Sie unter Streaming.

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 (Managed Service)
/admin/*	Multi-Tenant-Administration	JWT Admin (Managed Service)

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