Passer au contenu principal
Vous avez livré une politique pii-shield plus stricte lundi, un coéquipier a élargi une regex mercredi, et maintenant le trafic réel génère des faux positifs. Vous avez besoin de voir ce qui a changé, qui l’a changé, et de revenir en arrière — sans deviner le JSON précédent ni redéployer quoi que ce soit. C’est ce que vous donne le versioning des guardrails : une ligne d’historique par changement, un diff entre deux quelconques, et un revert en un clic. Cette page est l’atterrissage ciblé sur la surface de versioning. Pour le moteur de guardrail lui-même — types de règles, étapes, actions — commencez par la vue d’ensemble des guardrails ou la référence Guardrails complète.

​
1. Ce que le versioning des guardrails enregistre

Chaque mutation sur un guardrail — create, update, delete et revert — écrit une ligne d’historique en append-only dans la même transaction que le changement. La ligne capture un instantané de la config visible par l’utilisateur à ce moment-là :
  • le nom du guardrail,
  • s’il était activé,
  • s’il était le défaut de l’espace de travail,
  • le corps rules complet.
Chaque ligne porte un numéro de version monotone (commençant à 1), l’opération qui l’a produite, l’auteur, et un timestamp. Parce que la ligne est écrite de façon transactionnelle avec la modification, l’historique ne peut jamais dériver de la politique active — si la modification est commitée, sa ligne d’historique l’est aussi.
L’historique est append-only. Un revert ne rembobine ni ne réécrit les lignes passées ; il ajoute une nouvelle version (voir §4). Vous voyez toujours la séquence complète de qui a fait quoi, dans l’ordre.

​
2. Un exemple concret — trouver la mauvaise modification et la rétablir

Disons que le guardrail 42 a dérivé. Vous rédigez tout cela depuis la console sur votre propre session — la clé de relais sk-orca-... ne sert qu’aux appels /v1/*, jamais à lire ou changer la politique.
1

Lister l'historique

Ouvrez History sur la ligne du guardrail dans /console/guardrails. Le flux est du plus récent au plus ancien. Vous voyez v5 update (mercredi, par un coéquipier), v4 update (lundi, par vous), v3 update, et ainsi de suite jusqu’à v1 create. Lire l’historique est ouvert à tout Member de l’espace de travail.
2

Differ le changement suspect

Choisissez les deux versions qui encadrent la régression — v4 et v5 — et visualisez le diff. Le corps des règles est affiché côte à côte, donc la regex élargie saute aux yeux comme la ligne qui a changé.
3

Revert

Restaurez v4. Le nom, le flag enabled, le flag default et les règles du guardrail actif sont rétablis à cet instantané, et une nouvelle ligne v6 revert est ajoutée. Le changement est actif dès la prochaine requête — aucun redéploiement, aucun changement de SDK. Revenir en arrière nécessite le rôle Developer+.
Le même flux via l’API REST, le tout sur votre session / token d’accès (jamais la clé de relais), à portée d’espace de travail via X-Workspace-Id : 
# 1. List versions (Member)
curl https://api.orcarouter.ai/api/guardrail/42/history \
  -H "Authorization: Bearer <session-token>" \
  -H "X-Workspace-Id: <ws-id>"

# 2. Diff v4 against v5 (Member) — returns both snapshots to render side by side
curl "https://api.orcarouter.ai/api/guardrail/42/history/diff?from=4&to=5" \
  -H "Authorization: Bearer <session-token>" \
  -H "X-Workspace-Id: <ws-id>"

# 3. Revert to v4 — appends a new "revert" version (Developer+)
curl -X POST https://api.orcarouter.ai/api/guardrail/42/revert \
  -H "Authorization: Bearer <session-token>" \
  -H "X-Workspace-Id: <ws-id>" \
  -H "Content-Type: application/json" \
  -d '{"to_version": 4}'
La réponse du revert renvoie le guardrail actif post-revert afin que votre UI puisse se rafraîchir sans aller-retour supplémentaire. Le prochain appel /v1/* filtré par ce guardrail voit la politique restaurée.

​
3. Historique, diff, et le flux de versions

GET /api/guardrail/:id/history renvoie la trace de versions, du plus récent au plus ancien. Chaque entrée est un instantané avec son numéro de version, son opération (create / update / delete / revert), son auteur et son timestamp. Le flux est à portée d’espace de travail — un appelant dans un autre espace de travail obtient la même enveloppe not-found qu’un guardrail manquant, donc l’existence ne fuit jamais.
GET /api/guardrail/:id/history/:version récupère un instantané par son numéro de version — pratique pour inspecter le corps exact des règles qui était actif à un instant donné avant de décider de revenir à lui.
GET /api/guardrail/:id/history/diff?from=N&to=M renvoie les deux instantanés — from et to — afin que la console puisse rendre une comparaison côte à côte du nom, des flags et des règles. Les deux versions doivent appartenir à votre espace de travail, ou l’appel renvoie l’enveloppe not-found uniforme.
Les lectures — liste d’historique, version unique et diff — sont ouvertes à tout Member de l’espace de travail. Ce sont de pures inspections : rien sur le trafic ne change, et aucun appel de modèle ou de fournisseur n’est fait.

​
4. Le revert restaure comme une nouvelle version

Un revert n’est pas un rembobinage. POST /api/guardrail/:id/revert avec un corps to_version :
  1. Charge l’instantané de la version cible.
  2. Restaure le nom, le flag enabled, le flag default et les règles du guardrail actif à cet instantané — atomiquement, en une transaction.
  3. Ajoute une nouvelle ligne d’historique revert capturant l’état désormais actif.
Donc revenir de v5 à v4 produit une nouvelle v6 dont le contenu égale v4. Votre historique se lit v1 → v2 → … → v5 → v6(revert) — chaque étape préservée, rien muté. Revenez à cet ancien instantané de nouveau plus tard et vous obtenez une v7, et ainsi de suite.
Un état désactivé ou non-défaut restauré fait l’aller-retour intact. Si la version vers laquelle vous revenez avait enabled: false ou n’était pas le défaut de l’espace de travail, revenir remet le guardrail actif à exactement cela — il ne garde pas silencieusement la politique activée. Differ d’abord pour savoir si un revert basculera aussi ces flags.
Parce que la liaison vit sur la passerelle, un revert déplace chaque clé API attachée à ce guardrail d’un coup — et le défaut de l’espace de travail, si c’est lui — au prochain appel. Voir attacher à une clé et le défaut de l’espace de travail pour la façon dont l’attachement se résout.

​
5. Rôles et rétention

ActionRouteRôle
Lister / lire les versions, diffGET …/history, …/history/diff, …/history/:versionMember
Revert vers une versionPOST …/revertDeveloper+
Toutes les routes d’historique sont /api/guardrail/* et s’authentifient avec votre session / token d’accès sous X-Workspace-Id — jamais une clé de relais sk-orca-.... Revenir en arrière porte le même contrôle Developer+ que créer ou mettre à jour un guardrail, puisque cela change le trafic réel.
L’historique est conservé aux 50 versions les plus récentes par guardrail. Les lignes plus anciennes sont élaguées automatiquement à mesure que vous continuez de modifier, donc un workflow de boucle d’édition bavarde ne fait jamais croître la trace sans limite. L’endpoint de liste renvoie jusqu’aux 50 plus récentes, du plus récent au plus ancien.
Associez le versioning à l’ajustement flag-first : livrez une nouvelle règle en flag, surveillez le flux des correspondances, et si elle se comporte mal, diffez et revenez en arrière en quelques secondes au lieu de reconstruire l’ancienne politique à la main.

​
6. Où aller ensuite

Test & éval avant de livrer

Prouvez une politique dans le sandbox et contre un corpus avant qu’elle ne devienne une version que vous devriez rétablir.

Ajuster les faux positifs

La boucle flag-puis-promouvoir que le versioning rend sûre.

Actions : block, mask, flag

Ce que fait chaque règle une fois qu’une version est active.

Référence Guardrails

Le moteur complet — types de règles, étapes, presets et API complète.
Le versioning ici couvre la politique de contenu des guardrails. Le firewall a sa propre surface de changement pour la politique d’outils ; pour la façon dont les deux couches d’application diffèrent, voir guardrails vs. firewall.