Guardrail-API-Referenz

Wenn Sie Guardrails als Code verwalten möchten — eine PII-Policy in CI erstellen, zwei Versionen vor einem Release diffen oder den Matches-Feed in Ihr eigenes Dashboard ziehen — sprechen Sie mit den /api/guardrail/*-Routen. Diese Seite ist die Route-für-Route-Guardrail-API-Referenz: jeder Endpunkt, die Workspace-Rolle, die er erfordert, und die Auth, die er erwartet. Was ein Guardrail ist und wie Regeln komponieren, lesen Sie unter Guardrails. Diese Seite ist der Begleiter auf Wire-Ebene.

1. Auth und Scope

Jede /api/guardrail/*-Route ist Management-Plane: Sie authentifiziert mit Ihrem Konsolen-Session- oder Access-Token (dieselbe Identität, mit der Sie sich in die Konsole einloggen), nicht mit einem Relay-Key.

Ihr sk-orca-...-Relay-Key authentifiziert /v1/*-Modellaufrufe — er funktioniert nicht auf /api/guardrail/*. Konfigurationsrouten verwenden Ihr User-Session-/Access-Token, gescoped auf den aktiven Workspace.

Routen sind workspace-bezogen — sie sehen immer nur die Guardrails des aktiven Workspaces. Nichts überquert eine Tenant-Grenze.
Jede Route ist RBAC-gegated durch Ihre Workspace-Rolle (Viewer / Developer / Admin / Owner). Lesen ist für Viewer+ offen; die Sandbox und alle Schreibvorgänge erfordern Developer+; die False-Positive-Endpunkte erfordern Admin (Admin oder Owner).

Die meisten Teams rufen diese Routen nie direkt auf — die Konsole steuert sie alle. Greifen Sie zur REST-Surface, wenn Sie Guardrails in der Versionskontrolle, in CI oder in Ihr eigenes Tooling verdrahtet haben möchten.

2. Ein konkreter Aufruf — Ihre Guardrails auflisten

Ein Lesevorgang ist der einfachste Einstiegspunkt. Authentifiziert als jedes beliebige Workspace-Mitglied (Viewer+):

curl https://api.orcarouter.ai/api/guardrail/ \
  -H "Authorization: Bearer <your-access-token>" \
  -H "X-Workspace-Id: <workspace-id>"

Sie erhalten die Guardrails des Workspaces mit ihren angehängten-Key-Zählern zurück. Um stattdessen Ihren ersten Request end-to-end zu screenen — eine Policy erstellen, einen Key anhängen, einen Aufruf senden — folgen Sie dem 5-Schritte-Quickstart, der alles aus der Konsole erledigt.

3. Das Rollenmodell in einer Tabelle

Die Aktion, die Sie vornehmen, nicht die Route, wählt die Stufe.

Aktion	Mindestrolle
Lesen (list/get, History, Matches, Eval-Runs), einen Eval ausführen	Viewer+
Sandbox-Test ausführen	Developer+
Erstellen, aktualisieren, löschen, zurücksetzen, Corpus hochladen/löschen	Developer+
Einen Match als False Positive markieren / entmarkieren	Admin

Lesevorgänge mappen auf die guardrails:read-Permission (gehalten von Viewer aufwärts); Schreibvorgänge mappen auf guardrails:write (Developer aufwärts). Das Markieren eines False Positive erfordert zusätzlich die Admin-Rolle. Siehe Scope, Keys & Policies dafür, wie Rollen und Permissions kombinieren.

4. Routen nach Bereich

Guardrails (CRUD + Sandbox)

Methode & Pfad	Rolle
`GET /api/guardrail/`	Viewer+
`GET /api/guardrail/meta`	Viewer+
`GET /api/guardrail/my-permissions`	jedes Mitglied
`GET /api/guardrail/:id`	Viewer+
`GET /api/guardrail/:id/tokens`	Viewer+
`POST /api/guardrail/test`	Developer+
`POST /api/guardrail/`	Developer+
`PUT /api/guardrail/`	Developer+
`DELETE /api/guardrail/:id`	Developer+

meta gibt das Engine-Vokabular zurück — Regeltypen, Stages, Aktionen, PII-Entitäten, Presets und Preset-Kategorien — sodass ein Tool ein Formular bauen kann, ohne die Enums hart zu codieren. test führt die aktuelle Policy über Beispieltext in einer Sandbox aus: nichts wird persistiert, nichts geht upstream.

Versionshistorie

Methode & Pfad	Rolle
`GET /api/guardrail/:id/history`	Viewer+
`GET /api/guardrail/:id/history/diff`	Viewer+
`GET /api/guardrail/:id/history/:version`	Viewer+
`POST /api/guardrail/:id/revert`	Developer+

Jeder Create, Update und Delete schreibt eine History-Zeile in derselben Transaktion. revert kopiert eine alte Version als neue Version vorwärts — die History wird nie mutiert.

Eval & Corpora

Methode & Pfad	Rolle
`POST /api/guardrail/:id/eval`	Viewer+
`GET /api/guardrail/:id/eval/runs`	Viewer+
`GET /api/guardrail/eval/runs/:run_id`	Viewer+
`GET /api/guardrail/eval/corpora`	Viewer+
`POST /api/guardrail/eval/corpora`	Developer+
`GET /api/guardrail/eval/corpora/:id`	Viewer+
`DELETE /api/guardrail/eval/corpora/:id`	Developer+

Führen Sie ein Guardrail gegen ein gebündeltes Red-Team-Corpus oder ein eigenes JSONL-Set aus, das Sie hochladen, und lesen Sie dann die Fehlschläge pro Sample. Nützlich zum Tunen einer Judge-Rubrik oder um zu beweisen, dass eine Policy bekannte Angriffe abfängt, bevor Sie ausliefern.

Matches-Feed

Methode & Pfad	Rolle
`GET /api/guardrail/match`	jedes Mitglied
`GET /api/guardrail/match/grouped`	jedes Mitglied
`GET /api/guardrail/match/stats`	jedes Mitglied
`GET /api/guardrail/match/export`	jedes Mitglied
`GET /api/guardrail/match/cap-status`	jedes Mitglied
`GET /api/guardrail/match/:id`	jedes Mitglied
`POST /api/guardrail/match/:id/mark-fp`	Admin
`DELETE /api/guardrail/match/:id/mark-fp`	Admin

Ein Match zeichnet den Regeltyp, die Aktion, das Stage und einen Detail-String auf — plus den gematchten Teilstring nur, wenn „Log raw content” für dieses Guardrail an ist (standardmäßig aus). Die Read-Routen tragen keine zusätzliche Permission-Middleware, sodass jedes aktive Workspace-Mitglied sie erreichen kann; die beiden mark-fp-Routen sind Admin-only (Admin oder Owner) und ratenbegrenzt.

5. Auflösung: welches Guardrail gilt

Die obigen Routen verwalten Policies; die Auflösung entscheidet, welche auf einem gegebenen Relay-Aufruf läuft. Es ist ein Explizit-oder-Default-Modell ohne stillen Fallback bei einem expliziten Attachment:

Explizite guardrail_id auf dem Key → dieses Guardrail gilt, sofern es existiert und aktiviert ist. Ein deaktiviertes Attachment ist der Aus-Schalter — es fällt nicht zurück.
Kein Attachment → das aktivierte Default-Guardrail des Workspaces (is_default).
Keines von beiden → keine Durchsetzung. Der Request ist byte-identisch zu einem Workspace, der das Feature nie aktiviert hat.

Dies ist das eine Verhalten, das sich von der Firewall unterscheidet: Eine deaktivierte angehängte Firewall-Policy fällt auf den Workspace-Default zurück, während ein deaktiviertes angehängtes Guardrail zu keinem auflöst. Siehe Guardrails vs. Firewall.

Setzen Sie guardrail_id auf einem Key über den Key-Editor oder die Token-API; 0/null bedeutet „kein explizites Attachment”.

6. Was ein Block zurückgibt

Wenn eine Regel mit block-Aktion feuert, gibt der Relay-Aufruf (/v1/*, auf Ihrem Relay-Key) — nicht diese Management-Routen — zurück:

Feld	Wert
HTTP-Status	`400`
Fehlercode	`guardrail_blocked`
Kontingentkosten	ein Block im Input-Stage feuert vor dem Pre-Consume, sodass kein Kontingent berechnet wird
Retry	als skip-retry markiert

Die Nachricht benennt das Guardrail und die Regel, die gefeuert hat. Für den vollständigen Code-Katalog und die Triage-Pfade siehe Fehlercodes und Warum wurde mein Request blockiert?.

7. Aktionen, Stages und Regeltypen auf einen Blick

Die meta-Route gibt diese als Enums zurück; hier sind sie zum schnellen Nachschlagen.

Aktionen: block (ablehnen, HTTP 400), mask (den Treffer redigieren, den bereinigten Text weiterleiten), flag (nur loggen — beobachten, ohne den Traffic zu ändern), annotate (nicht blockierend — den Treffer aufzeichnen und einen menschenlesbaren Hinweis upstream injizieren, sodass dem Modell davon erzählt wird, bevor es antwortet), spotlight (nicht blockierend — den gematchten nicht vertrauenswürdigen Bereich in Delimiter einschließen und dem Modell sagen, ihn als Daten, nicht als Anweisungen zu behandeln; eine Prompt-Injection-Verteidigung, in der Praxis Input-Stage).
Stages: input (der Request), output (die Antwort des Modells) oder both.
Regeltypen: keyword, regex, pii, max_chars, external, llm_judge, grounding.

Output-Stage-Regeln werden auf sowohl streaming als auch nicht-streaming Antworten durchgesetzt: Ein block schneidet den Stream ab, und ein mask schreibt gematchte Bereiche in-band um, während Chunks fließen. In einem Stream können bereits geflushte Bytes nicht zurückgezogen werden, sodass auf einen Match erst reagiert wird, wenn genug davon gepuffert hat — für die stärkste Garantie scannen Sie im Input-Stage, das den Request bereinigt, bevor das Modell ihn je sieht. Beweisen Sie Ihre exakte Stage-/Stream-Kombination zuerst in der Sandbox.

Für Per-Entität-PII-Overrides, eigene Entitäten, den LLM-Judge und kontextuelle Grounding-Felder siehe die Tiefenreferenz in Guardrails.

8. Verwandte Referenzen

Firewall-API

Das Aktionsplane-Pendant — /api/workspace/firewall/* und die Gateway-Routen.

Compliance-API

/api/compliance/* — Packs, signierte Reports, Residency, Readiness.

Fehlercodes

Jeder *_blocked-Code, sein HTTP-Status und was dagegen zu tun ist.

Guardrails (Deep Dive)

Regeltypen, PII-Entitäten, Presets, Evals und der Matches-Feed in voller Tiefe.

Siehe auch Guardrails vs. Firewall, Wie OrcaRouter Traffic inspiziert und das Glossar.

​1. Auth und Scope

​2. Ein konkreter Aufruf — Ihre Guardrails auflisten

​3. Das Rollenmodell in einer Tabelle

​4. Routen nach Bereich

​5. Auflösung: welches Guardrail gilt

​6. Was ein Block zurückgibt

​7. Aktionen, Stages und Regeltypen auf einen Blick

​8. Verwandte Referenzen

Firewall-API

Compliance-API

Fehlercodes

Guardrails (Deep Dive)

1. Auth und Scope

2. Ein konkreter Aufruf — Ihre Guardrails auflisten

3. Das Rollenmodell in einer Tabelle

4. Routen nach Bereich

5. Auflösung: welches Guardrail gilt

6. Was ein Block zurückgibt

7. Aktionen, Stages und Regeltypen auf einen Blick

8. Verwandte Referenzen