Przejdź do głównej treści
Gdy chcesz zarządzać guardrails jako kodem — utworzyć politykę PII w CI, porównać dwie wersje przed wydaniem lub wciągnąć strumień dopasowań do własnego dashboardu — rozmawiasz z trasami /api/guardrail/*. Ta strona to referencja API guardrail trasa po trasie: każdy endpoint, rola przestrzeni roboczej, której wymaga, i uwierzytelnienie, którego oczekuje. Po to, czym guardrail jest i jak komponują się reguły, przeczytaj Guardrails. Ta strona to towarzysz na poziomie sieci.

​
1. Uwierzytelnienie i zakres

Każda trasa /api/guardrail/* to płaszczyzna zarządzania: uwierzytelnia się twoją sesją konsoli lub tokenem dostępu (tą samą tożsamością, którą logujesz się do konsoli), nie kluczem relay.
Twój klucz relay sk-orca-... uwierzytelnia wywołania modelu /v1/* — nie działa na /api/guardrail/*. Trasy konfiguracji używają twojej sesji użytkownika / tokenu dostępu, w zakresie aktywnej przestrzeni roboczej.
  • Trasy są w zakresie przestrzeni roboczej — widzą tylko guardrails aktywnej przestrzeni roboczej. Nic nie przekracza granicy najemcy.
  • Każda trasa jest bramkowana RBAC przez twoją rolę przestrzeni roboczej (Viewer / Developer / Admin / Owner). Odczyty otwarte dla Viewer+; piaskownica i wszystkie zapisy wymagają Developer+; endpointy fałszywie pozytywne wymagają Admin (Admin lub Owner).
Większość zespołów nigdy nie wywołuje tych tras bezpośrednio — konsola napędza je wszystkie. Sięgnij po powierzchnię REST, gdy chcesz guardrails w kontroli źródeł, w CI lub wpiętych w twoje własne narzędzia.

​
2. Jedno konkretne wywołanie — wylistuj swoje guardrails

Odczyt to najprostsze miejsce na początek. Uwierzytelniony jako dowolny członek przestrzeni roboczej (Viewer+): 
curl https://api.orcarouter.ai/api/guardrail/ \
  -H "Authorization: Bearer <your-access-token>" \
  -H "X-Workspace-Id: <workspace-id>"
Dostajesz z powrotem guardrails przestrzeni roboczej z ich licznikami dołączonych kluczy. Aby zamiast tego prześwietlić swoje pierwsze żądanie od końca do końca — utworzyć politykę, dołączyć klucz, wysłać wywołanie — podążaj za 5-krokowym szybkim startem, który robi to wszystko z konsoli.

​
3. Model ról w jednej tabeli

Akcja, którą podejmujesz, nie trasa, wybiera poziom.
AkcjaMinimalna rola
Odczyt (list/get, historia, dopasowania, przebiegi eval), uruchom evalViewer+
Uruchom test piaskownicyDeveloper+
Utwórz, zaktualizuj, usuń, cofnij, wgraj/usuń korpusDeveloper+
Oznacz / odznacz dopasowanie jako fałszywie pozytywneAdmin
Odczyty mapują się na uprawnienie guardrails:read (posiadane przez Viewer i wyżej); zapisy mapują się na guardrails:write (Developer i wyżej). Oznaczenie fałszywie pozytywnego dodatkowo wymaga roli Admin. Zobacz Zakres, klucze i polityki po to, jak role i uprawnienia się łączą.

​
4. Trasy wedle obszaru

Metoda i ścieżkaRola
GET /api/guardrail/Viewer+
GET /api/guardrail/metaViewer+
GET /api/guardrail/my-permissionsdowolny członek
GET /api/guardrail/:idViewer+
GET /api/guardrail/:id/tokensViewer+
POST /api/guardrail/testDeveloper+
POST /api/guardrail/Developer+
PUT /api/guardrail/Developer+
DELETE /api/guardrail/:idDeveloper+
meta zwraca słownictwo silnika — typy reguł, etapy, akcje, encje PII, presety i kategorie presetów — aby narzędzie mogło zbudować formularz bez twardego kodowania enumów. test uruchamia bieżącą politykę na przykładowym tekście w piaskownicy: nic nie jest persystowane, nic nie idzie nadrzędnie.
Metoda i ścieżkaRola
GET /api/guardrail/:id/historyViewer+
GET /api/guardrail/:id/history/diffViewer+
GET /api/guardrail/:id/history/:versionViewer+
POST /api/guardrail/:id/revertDeveloper+
Każde utworzenie, aktualizacja i usunięcie zapisuje wiersz historii w tej samej transakcji. revert kopiuje starą wersję naprzód jako nową wersję — historia nigdy nie jest mutowana.
Metoda i ścieżkaRola
POST /api/guardrail/:id/evalViewer+
GET /api/guardrail/:id/eval/runsViewer+
GET /api/guardrail/eval/runs/:run_idViewer+
GET /api/guardrail/eval/corporaViewer+
POST /api/guardrail/eval/corporaDeveloper+
GET /api/guardrail/eval/corpora/:idViewer+
DELETE /api/guardrail/eval/corpora/:idDeveloper+
Uruchom guardrail wobec dołączonego korpusu red-team lub własnego zestawu JSONL, który wgrasz, a potem odczytaj awarie per próbka. Przydatne do strojenia rubryki sędziego lub udowodnienia, że polityka łapie znane ataki, zanim ją wdrożysz.
Metoda i ścieżkaRola
GET /api/guardrail/matchdowolny członek
GET /api/guardrail/match/groupeddowolny członek
GET /api/guardrail/match/statsdowolny członek
GET /api/guardrail/match/exportdowolny członek
GET /api/guardrail/match/cap-statusdowolny członek
GET /api/guardrail/match/:iddowolny członek
POST /api/guardrail/match/:id/mark-fpAdmin
DELETE /api/guardrail/match/:id/mark-fpAdmin
Dopasowanie rejestruje typ reguły, akcję, etap i łańcuch detali — plus dopasowany podłańcuch tylko jeśli „Log raw content” jest włączone dla tego guardraila (domyślnie wyłączone). Trasy odczytu nie niosą dodatkowego middleware uprawnień, więc dowolny aktywny członek przestrzeni roboczej może do nich sięgnąć; dwie trasy mark-fp są tylko-Admin (Admin lub Owner) i mają limit tempa.

​
5. Rozwiązywanie: który guardrail ma zastosowanie

Trasy powyżej zarządzają politykami; rozwiązywanie decyduje, która działa na danym wywołaniu relay. To model jawny-lub-domyślny bez cichego fallbacku na jawnym dołączeniu:
  1. Jawny guardrail_id na kluczu → ten guardrail ma zastosowanie, jeśli istnieje i jest włączony. Wyłączone dołączenie to przełącznik wyłączający — nie wraca do domyślnego.
  2. Brak dołączenia → włączony domyślny guardrail przestrzeni roboczej (is_default).
  3. Żaden → brak egzekwowania. Żądanie jest bajt-identyczne z przestrzenią roboczą, która nigdy nie włączyła tej funkcji.
To jedno zachowanie, które różni się od Firewalla: wyłączona dołączona polityka firewalla wraca do domyślnej przestrzeni roboczej, podczas gdy wyłączony dołączony guardrail rozwiązuje się do żadnego. Zobacz Guardrails vs Firewall.
Ustaw guardrail_id na kluczu przez edytor klucza lub API tokenów; 0/null oznacza „brak jawnego dołączenia”.

​
6. Co zwraca block

Gdy reguła z akcją block odpala, wywołanie relay (/v1/*, na twoim kluczu relay) — nie te trasy zarządzania — zwraca:
PoleWartość
Status HTTP400
Kod błęduguardrail_blocked
Koszt kwotyblokada na etapie wejścia odpala przed wstępną konsumpcją, więc nie nalicza się kwota
Ponawianieoznaczone skip-retry
Komunikat nazywa guardrail i regułę, która odpaliła. Po pełny katalog kodów i ścieżki triażu zobacz Kody błędów i Dlaczego moje żądanie zostało zablokowane?.

​
7. Akcje, etapy i typy reguł w skrócie

Trasa meta zwraca je jako enumy; tu są dla szybkiej referencji.
  • Akcje: block (odrzuć, HTTP 400), mask (zredaguj dopasowanie, prześlij oczyszczony tekst), flag (tylko log — obserwuj bez zmiany ruchu), annotate (nieblokujące — zarejestruj dopasowanie i wstrzyknij czytelną dla człowieka notatkę nadrzędnie, aby model został o nim poinformowany przed odpowiedzią), spotlight (nieblokujące — owiń dopasowany niezaufany fragment w ograniczniki i powiedz modelowi, by traktował go jako dane, nie instrukcje; obrona przed prompt injection, w praktyce na etapie wejścia).
  • Etapy: input (żądanie), output (odpowiedź modelu) lub both.
  • Typy reguł: keyword, regex, pii, max_chars, external, llm_judge, grounding.
Reguły etapu wyjścia są egzekwowane na obu odpowiedziach — strumieniowanych i niestrumieniowanych: block ucina strumień, a mask przepisuje dopasowane fragmenty w paśmie, gdy chunki płyną. Na strumieniu już-spłukane bajty nie mogą być wycofane, więc dopasowanie jest obsługiwane dopiero, gdy wystarczająca jego część zbuforuje się — po najmocniejszą gwarancję skanuj na etapie wejścia, który sanityzuje żądanie, zanim model je w ogóle zobaczy. Najpierw udowodnij swoją dokładną kombinację etap/strumień w piaskownicy.
Po nadpisania PII per encja, encje własne, sędziego LLM i pola ugruntowania kontekstowego zobacz głęboką referencję w Guardrails.

​
8. Powiązane referencje

API Firewall

Odpowiednik na płaszczyźnie akcji — /api/workspace/firewall/* i trasy bramy.

API Compliance

/api/compliance/* — packi, podpisane raporty, rezydencja, gotowość.

Kody błędów

Każdy kod *_blocked, jego status HTTP i co z nim zrobić.

Guardrails (głębokie nurkowanie)

Typy reguł, encje PII, presety, ewaluacje i strumień dopasowań w pełni.
Zobacz też Guardrails vs Firewall, Jak OrcaRouter prześwietla ruch oraz Słownik.