Saltar al contenido principal
Lanzaste una política pii-shield más estricta el lunes, un compañero amplió un regex el miércoles, y ahora el tráfico real está arrojando falsos positivos. Necesitas ver qué cambió, quién lo cambió y revertir — sin adivinar el JSON anterior ni redesplegar nada. Eso es lo que te da el versionado de guardrails: una fila de historial por cambio, un diff entre dos cualesquiera, y revert de un clic. Esta página es el aterrizaje enfocado para la superficie de versionado. Para el motor de guardrails en sí — tipos de regla, etapas, acciones — empieza en la Visión general de guardrails o la referencia completa de Guardrails.

​
1. Qué registra el versionado de guardrails

Cada mutación en un guardrail — create, update, delete y revert — escribe una fila de historial de solo-anexado en la misma transacción que el cambio. La fila captura una instantánea de la config visible para el usuario en ese momento:
  • el name del guardrail,
  • si estaba enabled,
  • si era el valor por defecto del espacio de trabajo,
  • el cuerpo completo de rules.
Cada fila lleva un número de version monotónico (empezando en 1), la operation que la produjo, el author y una marca de tiempo. Como la fila se escribe transaccionalmente con la edición, el historial nunca puede desincronizarse con la política en vivo — si la edición se confirma, también lo hace su fila de historial.
El historial es solo-anexado. Un revert no rebobina ni reescribe filas pasadas; anexa una nueva versión (ver §4). Siempre ves la secuencia completa de quién hizo qué, en orden.

​
2. Un ejemplo concreto — encuentra la edición mala y revíértela

Digamos que el guardrail 42 se ha desviado. Creas todo esto desde la consola en tu propia sesión — la clave de relay sk-orca-... es solo para llamadas /v1/*, nunca para leer o cambiar política.
1

Lista el historial

Abre History en la fila del guardrail en /console/guardrails. El feed es el más nuevo primero. Ves v5 update (miércoles, por un compañero), v4 update (lunes, por ti), v3 update, y así hacia atrás hasta v1 create. Leer el historial está abierto a cualquier Member del espacio de trabajo.
2

Haz diff del cambio sospechoso

Elige las dos versiones que enmarcan la regresión — v4 y v5 — y mira el diff. El cuerpo de rules se muestra lado a lado, así que el regex ampliado salta como la línea que cambió.
3

Revierte

Restaura v4. El nombre, el flag enabled, el flag default y las rules del guardrail en vivo se vuelven a esa instantánea, y se anexa una fila fresca v6 revert. El cambio está en vivo en la siguiente solicitud — sin redespliegue, sin cambio de SDK. Revertir requiere el rol Developer+.
El mismo flujo sobre la API REST, todo en tu sesión / token de acceso (nunca la clave de relay), con alcance de espacio de trabajo vía 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 respuesta del revert devuelve el guardrail en vivo post-revert para que tu UI pueda refrescarse sin un round-trip extra. La siguiente llamada /v1/* examinada por este guardrail ve la política restaurada.

​
3. Historial, diff y el feed de versiones

GET /api/guardrail/:id/history devuelve el rastro de versiones, el más nuevo primero. Cada entrada es una instantánea con su número de versión, operación (create / update / delete / revert), autor y marca de tiempo. El feed tiene alcance de espacio de trabajo — un llamador en otro espacio de trabajo obtiene el mismo envoltorio not-found que un guardrail inexistente, así que la existencia nunca se filtra.
GET /api/guardrail/:id/history/:version obtiene una instantánea por su número de versión — útil para inspeccionar el cuerpo exacto de rules que estaba en vivo en un punto en el tiempo antes de decidir si revertir a él.
GET /api/guardrail/:id/history/diff?from=N&to=M devuelve ambas instantáneas — from y to — para que la consola pueda renderizar una comparación lado a lado del nombre, los flags y las rules. Ambas versiones deben pertenecer a tu espacio de trabajo, o la llamada devuelve el envoltorio not-found uniforme.
Las lecturas — lista de historial, una sola versión y diff — están abiertas a cualquier Member del espacio de trabajo. Son inspección pura: nada del tráfico cambia, y no se hace ninguna llamada a modelo o proveedor.

​
4. Revert restaura como una nueva versión

Un revert no es un rebobinado. POST /api/guardrail/:id/revert con un cuerpo to_version:
  1. Carga la instantánea de la versión objetivo.
  2. Restaura el nombre, el flag enabled, el flag default y las rules del guardrail en vivo a esa instantánea — de forma atómica, en una transacción.
  3. Anexa una fila de historial revert fresca que captura el estado ahora en vivo.
Así que revertir v5 de vuelta a v4 produce una nueva v6 cuyo contenido equivale a v4. Tu historial lee v1 → v2 → … → v5 → v6(revert) — cada paso preservado, nada mutado. Revierte esa instantánea más antigua de nuevo más tarde y obtienes una v7, y así sucesivamente.
Un estado deshabilitado o no-default restaurado va y vuelve intacto. Si la versión a la que reviertes tenía enabled: false o no era el valor por defecto del espacio de trabajo, revertir vuelve el guardrail en vivo exactamente a eso — no mantiene silenciosamente la política activada. Haz diff primero para saber si un revert también cambiará esos flags.
Como la vinculación vive en el gateway, un revert surte efecto en cada clave API vinculada a este guardrail de una vez — y el valor por defecto del espacio de trabajo, si es este — en la siguiente llamada. Ver vincular a una clave y el valor por defecto del espacio de trabajo para cómo resuelve la vinculación.

​
5. Roles y retención

AcciónRutaRol
Listar / leer versiones, diffGET …/history, …/history/diff, …/history/:versionMember
Revertir a una versiónPOST …/revertDeveloper+
Todas las rutas de historial son /api/guardrail/* y se autentican con tu sesión / token de acceso bajo X-Workspace-Id — nunca una clave de relay sk-orca-.... Revertir lleva la misma restricción Developer+ que crear o actualizar un guardrail, ya que cambia el tráfico en vivo.
El historial se retiene en las 50 versiones más recientes por guardrail. Las filas más antiguas se podan automáticamente a medida que sigues editando, así que un flujo de bucle de edición charlatán nunca hace crecer el rastro sin límite. El endpoint de lista devuelve hasta las 50 más nuevas, las más nuevas primero.
Empareja el versionado con afinado flag-primero: lanza una regla nueva como flag, observa el feed de coincidencias, y si se porta mal, haz diff y revierte en segundos en vez de reconstruir la política antigua a mano.

​
6. Dónde ir a continuación

Pruebas y eval antes de lanzar

Prueba una política en el sandbox y contra un corpus antes de que se convierta en una versión que tendrías que revertir.

Afinar falsos positivos

El bucle flag-luego-promover que el versionado hace seguro.

Acciones: block, mask, flag

Qué hace cada regla una vez que una versión está en vivo.

Referencia de Guardrails

El motor completo — tipos de regla, etapas, presets y la API completa.
El versionado aquí cubre la política de contenido de guardrail. El firewall tiene su propia superficie de cambios para la política de herramientas; para cómo difieren las dos capas de aplicación, ver guardrails vs. firewall.