Passer au contenu principal
Lorsque vous voulez gérer les guardrails comme du code — créer une politique PII en CI, comparer deux versions avant une release, ou tirer le flux de correspondances dans votre propre dashboard — vous parlez aux routes /api/guardrail/*. Cette page est la référence de l’API guardrail route par route : chaque endpoint, le rôle d’espace de travail qu’il requiert, et l’auth qu’il attend. Pour savoir ce qu’est un guardrail et comment les règles se composent, lisez Guardrails. Cette page est le compagnon au niveau du protocole.

​
1. Auth et portée

Chaque route /api/guardrail/* est un plan de gestion : elle s’authentifie avec votre session de console ou token d’accès (la même identité avec laquelle vous vous connectez à la console), pas une clé de relais.
Votre clé de relais sk-orca-... authentifie les appels de modèle /v1/* — elle ne fonctionne pas sur /api/guardrail/*. Les routes de configuration utilisent votre token de session/accès utilisateur, scopé à l’espace de travail actif.
  • Les routes sont à portée d’espace de travail — elles ne voient jamais que les guardrails de l’espace de travail actif. Rien ne franchit une frontière de tenant.
  • Chaque route est gardée par RBAC selon votre rôle d’espace de travail (Viewer / Developer / Admin / Owner). Les lectures sont ouvertes à Viewer+ ; le sandbox et toutes les écritures requièrent Developer+ ; les endpoints de faux positif requièrent Admin (Admin ou Owner).
La plupart des équipes n’appellent jamais ces routes directement — la console les pilote toutes. Tournez-vous vers la surface REST quand vous voulez vos guardrails sous contrôle de version, en CI, ou câblés dans votre propre outillage.

​
2. Un appel concret — lister vos guardrails

Une lecture est l’endroit le plus simple pour commencer. Authentifié en tant que n’importe quel membre de l’espace de travail (Viewer+) : 
curl https://api.orcarouter.ai/api/guardrail/ \
  -H "Authorization: Bearer <your-access-token>" \
  -H "X-Workspace-Id: <workspace-id>"
Vous récupérez les guardrails de l’espace de travail avec leurs comptes de clés attachées. Pour plutôt filtrer votre première requête de bout en bout — créer une politique, attacher une clé, envoyer un appel — suivez le démarrage rapide en 5 étapes, qui fait tout depuis la console.

​
3. Le modèle de rôles en un tableau

L’action que vous entreprenez, pas la route, choisit le niveau.
ActionRôle minimum
Lecture (list/get, historique, correspondances, exécutions d’éval), lancer un évalViewer+
Lancer un test sandboxDeveloper+
Créer, mettre à jour, supprimer, revenir en arrière, upload/supprimer corpusDeveloper+
Marquer / dé-marquer une correspondance comme faux positifAdmin
Les lectures correspondent à la permission guardrails:read (détenue par Viewer et au-dessus) ; les écritures correspondent à guardrails:write (Developer et au-dessus). Marquer un faux positif requiert en plus le rôle Admin. Voir Portée, clés et politiques pour la combinaison des rôles et des permissions.

​
4. Routes par domaine

Méthode & cheminRôle
GET /api/guardrail/Viewer+
GET /api/guardrail/metaViewer+
GET /api/guardrail/my-permissionstout membre
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 renvoie le vocabulaire du moteur — types de règles, étapes, actions, entités PII, presets, et catégories de presets — afin qu’un outil puisse construire un formulaire sans coder en dur les enums. test exécute la politique actuelle sur un texte d’échantillon dans un sandbox : rien n’est persisté, rien ne part en amont.
Méthode & cheminRôle
GET /api/guardrail/:id/historyViewer+
GET /api/guardrail/:id/history/diffViewer+
GET /api/guardrail/:id/history/:versionViewer+
POST /api/guardrail/:id/revertDeveloper+
Chaque create, update et delete écrit une ligne d’historique dans la même transaction. revert copie une ancienne version en avant comme une nouvelle version — l’historique n’est jamais muté.
Méthode & cheminRôle
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+
Exécutez un guardrail contre un corpus red-team intégré ou un ensemble JSONL personnalisé que vous uploadez, puis lisez les échecs par échantillon. Utile pour ajuster une rubrique de juge ou prouver qu’une politique attrape des attaques connues avant de l’expédier.
Méthode & cheminRôle
GET /api/guardrail/matchtout membre
GET /api/guardrail/match/groupedtout membre
GET /api/guardrail/match/statstout membre
GET /api/guardrail/match/exporttout membre
GET /api/guardrail/match/cap-statustout membre
GET /api/guardrail/match/:idtout membre
POST /api/guardrail/match/:id/mark-fpAdmin
DELETE /api/guardrail/match/:id/mark-fpAdmin
Une correspondance enregistre le type de règle, l’action, l’étape, et une chaîne de détail — plus la sous-chaîne correspondante seulement si « Log raw content » est activé pour ce guardrail (désactivé par défaut). Les routes de lecture ne portent aucun middleware de permission supplémentaire, donc tout membre actif de l’espace de travail peut les atteindre ; les deux routes mark-fp sont réservées à Admin (Admin ou Owner) et rate-limitées.

​
5. Résolution : quel guardrail s’applique

Les routes ci-dessus gèrent les politiques ; la résolution décide laquelle s’exécute sur un appel de relais donné. C’est un modèle explicite-ou-défaut sans fallback silencieux sur un attachement explicite :
  1. guardrail_id explicite sur la clé → ce guardrail s’applique, *s’*il existe et est activé. Un attachement désactivé est l’interrupteur d’arrêt — il ne retombe pas sur le défaut.
  2. Aucun attachement → le guardrail par défaut activé de l’espace de travail (is_default).
  3. Ni l’un ni l’autre → aucune application. La requête est identique octet pour octet à un espace de travail qui n’a jamais activé la fonctionnalité.
C’est le seul comportement qui diffère du Firewall : une politique firewall attachée désactivée retombe sur le défaut de l’espace de travail, tandis qu’un guardrail attaché désactivé se résout en aucun. Voir Guardrails vs Firewall.
Définissez guardrail_id sur une clé via l’éditeur de clé ou l’API de token ; 0/null signifie « aucun attachement explicite ».

​
6. Ce que renvoie un block

Lorsqu’une règle à action block se déclenche, l’appel de relais (/v1/*, sur votre clé de relais) — pas ces routes de gestion — renvoie :
ChampValeur
Statut HTTP400
Code d’erreurguardrail_blocked
Coût en quotaun block à l’étape d’entrée se déclenche avant la pré-consommation, donc aucun quota n’est facturé
Retrymarqué skip-retry
Le message nomme le guardrail et la règle qui s’est déclenchée. Pour le catalogue complet des codes et les chemins de triage, voir Codes d’erreur et Pourquoi ma requête a-t-elle été bloquée ?.

​
7. Actions, étapes et types de règles en un coup d’œil

La route meta les renvoie comme enums ; les voici pour référence rapide.
  • Actions : block (rejeter, HTTP 400), mask (redacter la correspondance, transmettre le texte nettoyé), flag (journaliser seulement — observer sans changer le trafic), annotate (non-bloquant — enregistrer la correspondance et injecter une note lisible par un humain en amont afin que le modèle en soit informé avant de répondre), spotlight (non-bloquant — encadrer le segment non fiable correspondant dans des délimiteurs et dire au modèle de le traiter comme des données, pas des instructions ; une défense contre l’injection de prompt, à l’étape d’entrée en pratique).
  • Étapes : input (la requête), output (la réponse du modèle), ou both.
  • Types de règles : keyword, regex, pii, max_chars, external, llm_judge, grounding.
Les règles à l’étape de sortie sont appliquées sur les réponses streaming et non-streaming : un block coupe le flux, et un mask réécrit les segments correspondants en bande à mesure que les chunks circulent. Sur un flux, les octets déjà transmis ne peuvent pas être rétractés, donc une correspondance n’est traitée qu’une fois qu’une partie suffisante a été bufferisée — pour la garantie la plus forte, scannez à l’étape input, qui assainit la requête avant que le modèle ne la voie. Prouvez d’abord votre combinaison exacte étape/flux dans le sandbox.
Pour les overrides PII par entité, les entités personnalisées, le juge LLM, et les champs de grounding contextuel, voir la référence approfondie dans Guardrails.

​
8. Références associées

API Firewall

Le pair du plan d’action — /api/workspace/firewall/* et les routes de passerelle.

API Compliance

/api/compliance/* — packs, rapports signés, résidence, préparation.

Codes d'erreur

Chaque code *_blocked, son statut HTTP, et quoi faire à son sujet.

Guardrails (plongée)

Types de règles, entités PII, presets, évals, et le flux de correspondances en entier.
Voir aussi Guardrails vs Firewall, Comment OrcaRouter inspecte le trafic, et le Glossaire.