Request-Tags (Preview)

Mit Request-Tags ordnen Sie einzelne Anfragen über den Header X-Noirdoc-Tags einem Mandat, einer Kostenstelle, einem Team oder einem Mandanten Ihrer Anwendung zu – ohne für jedes Mandat einen eigenen API-Schlüssel auszustellen. Jedes Tag führt eigene Verbrauchszähler und kann ein eigenes Euro-Budget, eigene Modell- und Anbieter-Einschränkungen sowie einen eigenen Noirdoc-Shield-Modus (shield_mode) tragen.

1. Standard-Tag-Vorlage oder Tags im Portal anlegen

   Nach der Freischaltung verwalten Admins Ihrer Organisation Tags unter Models → Tags.

   Im Bereich Standard-Tag-Vorlage legen Sie fest, wie das Gateway mit noch unbekannten Tag-Namen im Header X-Noirdoc-Tags umgeht:

   • Unbekannte Tags bei erster Verwendung automatisch anlegen (Standard: eingeschaltet): Sendet Ihre Anwendung ein neues Tag, legt das Gateway es bei der ersten weitergeleiteten Anfrage automatisch an und übernimmt Budget, Modell- und Anbieter-Einschränkungen sowie shield_mode aus der Vorlage.
   • Automatische Anlage ausgeschaltet: Unbekannte Tags im Header X-Noirdoc-Tags lehnt das Gateway mit Statuscode 403 und Fehlercode tag_not_found ab. Legen Sie gültige Tags vorab über Neues Tag oder per POST /v1/tags an.

   Für Tag-Namen gelten folgende Regeln:

   • Format: 1 bis 64 Zeichen aus a-z, A-Z, 0-9 sowie _, ., : und -, beginnend mit einem Buchstaben oder einer Ziffer (^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,63}$).
   • Reservierter Name: _default ist für den Vorlagen-Endpunkt /v1/tags/_default reserviert und darf nicht als Tag-Name verwendet werden.
   • Obergrenze: Jede Organisation kann bis zu 1.000 Request-Tags anlegen (tag_limit_exceeded).

   Ergebnis: Ihre Organisation hat eine Standard-Tag-Vorlage oder vorab angelegte Tags.

2. Budget, Einschränkungen und Noirdoc Shield je Tag festlegen

   Für die Standard-Tag-Vorlage und für jedes einzelne Tag können Sie dieselben Leitplanken setzen wie für einen API-Schlüssel (siehe Budgets je Schlüssel, Modelle & Anbieter einschränken und Noirdoc Shield einrichten):

   • Ausgabenlimit (€) und Zurücksetzen: Nie, Täglich (00:00 UTC), Wöchentlich (montags 00:00 UTC) oder Monatlich (am 1. des Monats um 00:00 UTC). Leer bedeutet kein eigenes Limit für dieses Tag.
   • Noirdoc Shield (shield_mode): Standard ("inherit", gibt an Header und Organisations-Standard weiter), Aktiv ("on", schaltet Shield für Anfragen mit diesem Tag ein) oder Aus ("off", schaltet Shield aus, sofern weder die Organisations-Richtlinie enforced noch Schlüssel oder ein weiteres mitgesendetes Tag Shield aktivieren).
   • Erlaubte Modelle: Alle Modelle oder Nur ausgewählte Modelle.
   • Anbieter-Einschränkungen: Datenresidenz, Nur ohne CLOUD-Act-Exposition, Nur §203-abgedeckte Provider und eine Auswahl erlaubter Provider.

   Ergebnis: Unter Models → Tags zeigt die Tabelle für jedes Tag Status (Aktiv oder Inaktiv), Verbrauch im laufenden Zeitraum, Gesamtausgaben und den Zeitpunkt der letzten Verwendung.

3. X-Noirdoc-Tags mit Anfragen senden

   Übergeben Sie im Header X-Noirdoc-Tags 1 bis 5 durch Komma getrennte Tag-Namen. Mehrfach genannte Tags in derselben Anfrage fasst das Gateway zusammen. Vor dem Weiterleiten an den Anbieter entfernt das Gateway den Header.

   Auch GET /v1/models wertet X-Noirdoc-Tags aus und gibt nur Modelle zurück, die sowohl für den Schlüssel als auch für alle genannten Tags erlaubt sind. Ebenso akzeptiert POST /v1/shield/inspect den Header X-Noirdoc-Tags für Kostenzuordnung und Tag-Budgets.

   Ergebnis: Das Gateway prüft Budget und Einschränkungen der genannten Tags und verbucht die Anfrage nach der Antwort auf jedes Tag.

   curl Python TypeScript

   Shell

   curl https://api.noirdoc.de/v1/chat/completions \
     -H "Authorization: Bearer $NOIRDOC_API_KEY" \
     -H "X-Noirdoc-Tags: mandat-2026-042,team-arbeitsrecht" \
     -H "Content-Type: application/json" \
     -d '{
       "model": "qwen3.8-27b",
       "max_tokens": 500,
       "messages": [{"role": "user", "content": "Hallo"}]
     }'

   Python

   import os
   from openai import OpenAI
   
   client = OpenAI(
       base_url="https://api.noirdoc.de/v1",
       api_key=os.environ["NOIRDOC_API_KEY"],
   )
   
   response = client.chat.completions.create(
       model="qwen3.8-27b",
       max_tokens=500,
       messages=[{"role": "user", "content": "Hallo"}],
       extra_headers={
           "X-Noirdoc-Tags": "mandat-2026-042,team-arbeitsrecht",
       },
   )

   TypeScript

   import OpenAI from "openai";
   
   const client = new OpenAI({
     baseURL: "https://api.noirdoc.de/v1",
     apiKey: process.env.NOIRDOC_API_KEY,
   });
   
   const response = await client.chat.completions.create(
     {
       model: "qwen3.8-27b",
       max_tokens: 500,
       messages: [{ role: "user", content: "Hallo" }],
     },
     {
       headers: {
         "X-Noirdoc-Tags": "mandat-2026-042,team-arbeitsrecht",
       },
     },
   );

Mehrere Tags und Zusammenspiel mit dem Schlüssel

Wenn Sie ein oder mehrere Tags in X-Noirdoc-Tags mitsenden, kombiniert das Gateway die Regeln der Organisation, des API-Schlüssels und aller genannten Tags:

• Erlaubte Modelle und Anbieter (Schnittmenge): Ein Modell und ein Anbieter kommen nur infrage, wenn sie für die Organisation (§ 203 StGB), für den aufrufenden API-Schlüssel und für jedes mitgesendete Tag erlaubt sind. Schließt ein Tag das Modell oder alle seine Anbieter aus, antwortet das Gateway mit 403 model_not_allowed_for_tag bzw. provider_not_allowed_for_tag.
• Noirdoc Shield (shield_mode und Vorrangfolge): Ob Shield eine Anfrage prüft, folgt der Reihenfolge Organisations-Richtlinie enforced > API-Schlüssel shield_mode ("on" / "off") > Request-Tag shield_mode > Header X-Noirdoc-Shield > Organisations-Standard (default_on / default_off), siehe Richtlinie und Vorrangfolge. Sind mehrere Tags in X-Noirdoc-Tags angegeben, gewinnt "on" vor "off", sobald mindestens ein angehängtes Tag auf "on" steht; "inherit" gibt an die nächste Stufe weiter.
• Reihenfolge der Budgetprüfung: Vor der Anfrage prüft das Gateway zuerst das Guthaben der Organisation (insufficient_credit), danach das Budget des API-Schlüssels (key_budget_exhausted) und anschließend die Budgets der Tags in der Reihenfolge aus X-Noirdoc-Tags. Ist das Budget eines Tags erschöpft oder kleiner als die Kostenschätzung der Anfrage, antwortet das Gateway mit 402 tag_budget_exhausted; message nennt das betroffene Tag.
• Volle Kostenbuchung je Tag: Nach der Antwort bzw. Prüfung bucht das Gateway die vollen Kosten der Anfrage – von Noirdoc verwaltete Modelle mit Preis sowie die Prüfgebühr von Noirdoc Shield (0,40 € je 1 Mio. geprüfter Eingabe-Tokens, auch bei POST /v1/shield/inspect und bei aktivem Shield auf eigenen Anbietern/BYOK) – sowohl auf den API-Schlüssel als auch auf jedes in X-Noirdoc-Tags genannte Tag. Damit können Sie unabhängige Dimensionen – etwa ein Mandatsbudget (mandat-2026-042) und ein Abteilungsbudget (team-arbeitsrecht) – gleichzeitig überwachen. Anfragen über eigene Anbieter (BYOK) ohne aktives Shield zählen wie beim Schlüssel-Budget mit 0 €.

Tags per API verwalten (/v1/tags)

Neben der Oberfläche unter Models → Tags können Sie Tags und die Standard-Tag-Vorlage über den Endpunkt /v1/tags verwalten – zum Beispiel automatisch beim Anlegen einer neuen Akte in Ihrer Kanzlei- oder Fachsoftware.

Berechtigung des API-Schlüssels

Standardmäßig darf ein API-Schlüssel /v1/tags nicht aufrufen (403 insufficient_key_permissions). Aktivieren Sie unter Models → API-Schlüssel beim Erstellen oder Bearbeiten des Schlüssels die Option Tag-Verwaltung erlauben (/v1/tags).

Endpunkte im Überblick

curl -X PUT https://api.noirdoc.de/v1/tags/mandat-2026-042 \
  -H "Authorization: Bearer $NOIRDOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Akte 2026/042 – Arbeitsrecht",
    "budget_limit_eur": 25.0,
    "budget_reset": "monthly",
    "shield_mode": "on",
    "allowed_residencies": ["DE", "EU"],
    "require_no_cloud_act": true,
    "require_section203": true
  }'

Fehler