Vai al contenuto principale
Quando vuoi gestire i guardrails come codice — creare una policy PII in CI, fare il diff di due versioni prima di una release o portare il feed dei match nella tua dashboard — parli con le rotte /api/guardrail/*. Questa pagina è il riferimento API guardrail rotta per rotta: ogni endpoint, il ruolo di workspace che richiede e l’auth che si aspetta. Per cosa è un guardrail e come si compongono le regole, leggi Guardrails. Questa pagina è il complemento a livello di wire.

​
1. Auth e scope

Ogni rotta /api/guardrail/* è management plane: si autentica con il tuo session o access token di console (la stessa identità con cui accedi alla console), non con una chiave di relay.
La tua chiave di relay sk-orca-... autentica le chiamate al modello /v1/* — non funziona su /api/guardrail/*. Le rotte di configurazione usano il tuo session/access token utente, con scope sul workspace attivo.
  • Le rotte sono workspace-scoped — vedono solo i guardrails del workspace attivo. Nulla attraversa un confine di tenant.
  • Ogni rotta è RBAC-gated dal tuo ruolo di workspace (Viewer / Developer / Admin / Owner). Le letture sono aperte a Viewer+; la sandbox e tutte le scritture richiedono Developer+; gli endpoint di falso positivo richiedono Admin (Admin o Owner).
La maggior parte dei team non chiama mai queste rotte direttamente — la console le guida tutte. Ricorri alla superficie REST quando vuoi i guardrails nel source control, in CI o collegati al tuo tooling.

​
2. Una chiamata concreta — elenca i tuoi guardrails

Una lettura è il punto più semplice da cui partire. Autenticato come qualsiasi membro del workspace (Viewer+): 
curl https://api.orcarouter.ai/api/guardrail/ \
  -H "Authorization: Bearer <your-access-token>" \
  -H "X-Workspace-Id: <workspace-id>"
Ottieni in risposta i guardrails del workspace con i conteggi delle chiavi collegate. Per filtrare invece la tua prima richiesta end-to-end — crea una policy, collega una chiave, invia una chiamata — segui il quickstart in 5 passi, che fa tutto dalla console.

​
3. Il modello dei ruoli in una tabella

L’azione che compi, non la rotta, sceglie il livello.
AzioneRuolo minimo
Lettura (list/get, cronologia, match, eval run), eseguire un evalViewer+
Eseguire un test in sandboxDeveloper+
Creare, aggiornare, eliminare, ripristinare, caricare/eliminare corpusDeveloper+
Marcare / smarcare un match come falso positivoAdmin
Le letture mappano al permesso guardrails:read (detenuto da Viewer in su); le scritture mappano a guardrails:write (Developer in su). Marcare un falso positivo richiede in aggiunta il ruolo Admin. Vedi Scope, chiavi e policy per come si combinano ruoli e permessi.

​
4. Rotte per area

Metodo & pathRuolo
GET /api/guardrail/Viewer+
GET /api/guardrail/metaViewer+
GET /api/guardrail/my-permissionsqualsiasi membro
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 restituisce il vocabolario del motore — tipi di regola, fasi, azioni, entità PII, preset e categorie di preset — così uno strumento può costruire un form senza hard-coding degli enum. test esegue la policy corrente su testo di esempio in una sandbox: nulla viene persistito, nulla va upstream.
Metodo & pathRuolo
GET /api/guardrail/:id/historyViewer+
GET /api/guardrail/:id/history/diffViewer+
GET /api/guardrail/:id/history/:versionViewer+
POST /api/guardrail/:id/revertDeveloper+
Ogni create, update e delete scrive una riga di cronologia nella stessa transazione. revert copia in avanti una vecchia versione come una nuova versione — la cronologia non viene mai mutata.
Metodo & pathRuolo
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+
Esegui un guardrail contro un corpus red-team integrato o un set JSONL personalizzato che carichi, poi leggi i fallimenti per campione. Utile per mettere a punto la rubrica di un judge o provare che una policy intercetta attacchi noti prima di rilasciarla.
Metodo & pathRuolo
GET /api/guardrail/matchqualsiasi membro
GET /api/guardrail/match/groupedqualsiasi membro
GET /api/guardrail/match/statsqualsiasi membro
GET /api/guardrail/match/exportqualsiasi membro
GET /api/guardrail/match/cap-statusqualsiasi membro
GET /api/guardrail/match/:idqualsiasi membro
POST /api/guardrail/match/:id/mark-fpAdmin
DELETE /api/guardrail/match/:id/mark-fpAdmin
Un match registra il tipo di regola, l’azione, la fase e una stringa di dettaglio — più la sottostringa corrispondente solo se “Log raw content” è attivo per quel guardrail (disattivato di default). Le rotte di lettura non portano middleware di permesso aggiuntivo, quindi qualsiasi membro attivo del workspace può raggiungerle; le due rotte mark-fp sono solo Admin (Admin o Owner) e rate-limited.

​
5. Risoluzione: quale guardrail si applica

Le rotte qui sopra gestiscono le policy; la risoluzione decide quale gira su una data chiamata di relay. È un modello explicit-or-default senza fallback silenzioso su un collegamento esplicito:
  1. guardrail_id esplicito sulla chiave → quel guardrail si applica, se esiste ed è abilitato. Un collegamento disabilitato è l’interruttore di spegnimento — non ricade.
  2. Nessun collegamento → il guardrail default abilitato del workspace (is_default).
  3. Nessuno dei due → nessuna applicazione. La richiesta è byte-identica a un workspace che non ha mai abilitato la feature.
Questo è l’unico comportamento che differisce dal Firewall: una policy del firewall collegata e disabilitata ricade sul default del workspace, mentre un guardrail collegato e disabilitato si risolve in nessuno. Vedi Guardrails vs Firewall.
Imposta guardrail_id su una chiave tramite l’editor della chiave o l’API dei token; 0/null significa “nessun collegamento esplicito.”

​
6. Cosa restituisce un block

Quando scatta una regola con azione block, la chiamata di relay (/v1/*, sulla tua chiave di relay) — non queste rotte di management — restituisce:
CampoValore
Stato HTTP400
Codice di erroreguardrail_blocked
Costo in quotaun block in fase di input scatta prima del pre-consume, quindi non viene addebitata quota
Retrymarcato skip-retry
Il messaggio nomina il guardrail e la regola che è scattata. Per il catalogo completo dei codici e i percorsi di triage, vedi Codici di errore e Perché la mia richiesta è stata bloccata?.

​
7. Azioni, fasi e tipi di regola in sintesi

La rotta meta restituisce questi come enum; eccoli qui per riferimento rapido.
  • Azioni: block (rifiuta, HTTP 400), mask (redige il match, inoltra il testo ripulito), flag (solo log — osserva senza modificare il traffico), annotate (non bloccante — registra il match e inietta una nota leggibile dall’uomo upstream così il modello ne è informato prima di rispondere), spotlight (non bloccante — avvolge la porzione non attendibile corrispondente in delimitatori e dice al modello di trattarla come dato, non come istruzioni; una difesa da prompt-injection, in pratica in fase di input).
  • Fasi: input (la richiesta), output (la risposta del modello) o both.
  • Tipi di regola: keyword, regex, pii, max_chars, external, llm_judge, grounding.
Le regole in fase di output sono applicate sia sulle risposte streaming che non-streaming: un block taglia lo stream, e un mask riscrive le porzioni corrispondenti in banda man mano che i chunk scorrono. Su uno stream, i byte già scaricati non possono essere ritirati, quindi un match viene gestito solo una volta che abbastanza di esso è stato bufferizzato — per la garanzia più forte, scansiona in fase di input, che sanifica la richiesta prima che il modello la veda mai. Prova prima la tua esatta combinazione fase/stream nella sandbox.
Per gli override PII per entità, le entità personalizzate, l’LLM judge e i campi di grounding contestuale, vedi il riferimento approfondito in Guardrails.

​
8. Riferimenti correlati

API Firewall

Il pari del piano-azioni — /api/workspace/firewall/* e le rotte del gateway.

API Compliance

/api/compliance/* — pack, report firmati, residency, readiness.

Codici di errore

Ogni codice *_blocked, il suo stato HTTP e cosa farci.

Guardrails (approfondimento)

Tipi di regola, entità PII, preset, eval e il feed dei match per intero.
Vedi anche Guardrails vs Firewall, Come OrcaRouter ispeziona il traffico e il Glossario.