Referencia de la API de Guardrail

Cuando quieres gestionar guardrails como código — crear una política de PII en CI, comparar dos versiones antes de un lanzamiento, o llevar el feed de matches a tu propio panel — hablas con las rutas /api/guardrail/*. Esta página es la referencia de la API de guardrail ruta por ruta: cada endpoint, el rol de espacio de trabajo que requiere y la autenticación que espera. Para saber qué es un guardrail y cómo se componen las reglas, lee Guardrails. Esta página es el compañero a nivel de protocolo.

1. Autenticación y alcance

Cada ruta /api/guardrail/* es plano de gestión: se autentica con tu sesión de consola o token de acceso (la misma identidad con la que inicias sesión en la consola), no una clave de relay.

Tu clave de relay sk-orca-... autentica las llamadas de modelo /v1/* — no funciona en /api/guardrail/*. Las rutas de configuración usan tu token de sesión / acceso de usuario, acotado al espacio de trabajo activo.

Las rutas tienen alcance de espacio de trabajo — solo ven los guardrails del espacio de trabajo activo. Nada cruza un límite de inquilino.
Cada ruta está gobernada por RBAC según tu rol de espacio de trabajo (Viewer / Developer / Admin / Owner). Las lecturas abren a Viewer+; el sandbox y todas las escrituras requieren Developer+; los endpoints de falso positivo requieren Admin (Admin u Owner).

La mayoría de los equipos nunca llaman a estas rutas directamente — la consola las maneja todas. Recurre a la superficie REST cuando quieras guardrails en control de versiones, en CI, o conectados a tu propia herramienta.

2. Una llamada concreta — lista tus guardrails

Una lectura es el lugar más simple para empezar. Autenticado como cualquier miembro del espacio de trabajo (Viewer+):

curl https://api.orcarouter.ai/api/guardrail/ \
  -H "Authorization: Bearer <your-access-token>" \
  -H "X-Workspace-Id: <workspace-id>"

Recibes de vuelta los guardrails del espacio de trabajo con sus conteos de claves adjuntas. Para examinar tu primera solicitud de extremo a extremo en su lugar — crear una política, adjuntar una clave, enviar una llamada — sigue el inicio rápido de 5 pasos, que lo hace todo desde la consola.

3. El modelo de roles en una tabla

La acción que tomas, no la ruta, elige el nivel.

Acción	Rol mínimo
Leer (lista/get, historial, matches, ejecuciones de eval), ejecutar un eval	Viewer+
Ejecutar test de sandbox	Developer+
Crear, actualizar, eliminar, revertir, subir/eliminar corpus	Developer+
Marcar / desmarcar una coincidencia como falso positivo	Admin

Las lecturas mapean al permiso guardrails:read (que tiene Viewer y superiores); las escrituras mapean a guardrails:write (Developer y superiores). Marcar un falso positivo requiere adicionalmente el rol Admin. Ve Alcance, claves y políticas para saber cómo se combinan roles y permisos.

4. Rutas por área

Guardrails (CRUD + sandbox)

Método y ruta	Rol
`GET /api/guardrail/`	Viewer+
`GET /api/guardrail/meta`	Viewer+
`GET /api/guardrail/my-permissions`	cualquier miembro
`GET /api/guardrail/:id`	Viewer+
`GET /api/guardrail/:id/tokens`	Viewer+
`POST /api/guardrail/test`	Developer+
`POST /api/guardrail/`	Developer+
`PUT /api/guardrail/`	Developer+
`DELETE /api/guardrail/:id`	Developer+

meta devuelve el vocabulario del motor — tipos de regla, etapas, acciones, entidades PII, presets y categorías de preset — para que una herramienta pueda construir un formulario sin codificar los enums a mano. test ejecuta la política actual sobre texto de muestra en un sandbox: nada se persiste, nada va upstream.

Historial de versiones

Método y ruta	Rol
`GET /api/guardrail/:id/history`	Viewer+
`GET /api/guardrail/:id/history/diff`	Viewer+
`GET /api/guardrail/:id/history/:version`	Viewer+
`POST /api/guardrail/:id/revert`	Developer+

Cada creación, actualización y eliminación escribe una fila de historial en la misma transacción. revert copia una versión antigua hacia adelante como una nueva versión — el historial nunca se muta.

Eval y corpora

Método y ruta	Rol
`POST /api/guardrail/:id/eval`	Viewer+
`GET /api/guardrail/:id/eval/runs`	Viewer+
`GET /api/guardrail/eval/runs/:run_id`	Viewer+
`GET /api/guardrail/eval/corpora`	Viewer+
`POST /api/guardrail/eval/corpora`	Developer+
`GET /api/guardrail/eval/corpora/:id`	Viewer+
`DELETE /api/guardrail/eval/corpora/:id`	Developer+

Ejecuta un guardrail contra un corpus de red-team incluido o un conjunto JSONL personalizado que subas, luego lee los fallos por muestra. Útil para afinar una rúbrica de juez o probar que una política captura ataques conocidos antes de lanzar.

Feed de Matches

Método y ruta	Rol
`GET /api/guardrail/match`	cualquier miembro
`GET /api/guardrail/match/grouped`	cualquier miembro
`GET /api/guardrail/match/stats`	cualquier miembro
`GET /api/guardrail/match/export`	cualquier miembro
`GET /api/guardrail/match/cap-status`	cualquier miembro
`GET /api/guardrail/match/:id`	cualquier miembro
`POST /api/guardrail/match/:id/mark-fp`	Admin
`DELETE /api/guardrail/match/:id/mark-fp`	Admin

Una coincidencia registra el tipo de regla, la acción, la etapa y una cadena de detalle — más la subcadena coincidente solo si “Log raw content” está activado para ese guardrail (apagado por defecto). Las rutas de lectura no llevan middleware de permisos extra, así que cualquier miembro activo del espacio de trabajo puede alcanzarlas; las dos rutas mark-fp son solo de Admin (Admin u Owner) y tienen rate limit.

5. Resolución: qué guardrail aplica

Las rutas de arriba gestionan políticas; la resolución decide cuál se ejecuta en una llamada de relay dada. Es un modelo explícito-o-por-defecto sin fallback silencioso en un adjunto explícito:

guardrail_id explícito en la clave → ese guardrail aplica, si existe y está habilitado. Un adjunto deshabilitado es el interruptor de apagado — no hace fallback.
Sin adjunto → el guardrail por defecto habilitado del espacio de trabajo (is_default).
Ninguno → sin aplicación. La solicitud es idéntica byte a byte a un espacio de trabajo que nunca habilitó la función.

Este es el único comportamiento que difiere del Firewall: una política de firewall adjunta deshabilitada hace fallback al valor por defecto del espacio de trabajo, mientras que un guardrail adjunto deshabilitado resuelve a ninguno. Ve Guardrails vs Firewall.

Establece guardrail_id en una clave a través del editor de claves o la API de tokens; 0/null significa “sin adjunto explícito”.

6. Qué devuelve un block

Cuando una regla de acción block se dispara, la llamada de relay (/v1/*, sobre tu clave de relay) — no estas rutas de gestión — devuelve:

Campo	Valor
Estado HTTP	`400`
Código de error	`guardrail_blocked`
Coste de cuota	un bloqueo en etapa de entrada se dispara antes del preconsumo, así que no se cobra cuota
Reintento	marcado skip-retry

El mensaje nombra el guardrail y la regla que se disparó. Para el catálogo de códigos completo y las rutas de triaje, ve Códigos de error y ¿Por qué se bloqueó mi solicitud?.

7. Acciones, etapas y tipos de regla de un vistazo

La ruta meta los devuelve como enums; aquí están para referencia rápida.

Acciones: block (rechazar, HTTP 400), mask (redactar la coincidencia, reenviar el texto limpio), flag (solo registrar — observar sin cambiar el tráfico), annotate (no bloqueante — registrar la coincidencia e inyectar una nota legible por humanos upstream para que se le diga al modelo antes de que responda), spotlight (no bloqueante — envolver el fragmento no confiable coincidente en delimitadores y decirle al modelo que lo trate como datos, no instrucciones; una defensa contra inyección de prompts, etapa de entrada en la práctica).
Etapas: input (la solicitud), output (la respuesta del modelo), o both.
Tipos de regla: keyword, regex, pii, max_chars, external, llm_judge, grounding.

Las reglas de etapa de salida se aplican en respuestas tanto en streaming como sin streaming: un block corta el stream, y un mask reescribe los fragmentos coincidentes en banda a medida que fluyen los chunks. En un stream, los bytes ya enviados no pueden retractarse, así que una coincidencia solo se actúa una vez que suficiente de ella se ha almacenado en búfer — para la garantía más fuerte, examina en la etapa input, que sanea la solicitud antes de que el modelo la vea. Prueba tu combinación exacta de etapa/stream primero en el sandbox.

Para los overrides de PII por entidad, entidades personalizadas, el juez LLM y los campos de grounding contextual, ve la referencia profunda en Guardrails.

8. Referencias relacionadas

API de Firewall

El par del plano de acción — /api/workspace/firewall/* y las rutas del gateway.

API de Compliance

/api/compliance/* — packs, reportes firmados, residencia, preparación.

Códigos de error

Cada código *_blocked, su estado HTTP y qué hacer al respecto.

Guardrails (en profundidad)

Tipos de regla, entidades PII, presets, evals y el feed de matches al completo.

Ve también Guardrails vs Firewall, Cómo OrcaRouter inspecciona el tráfico, y el Glosario.

​1. Autenticación y alcance

​2. Una llamada concreta — lista tus guardrails

​3. El modelo de roles en una tabla

​4. Rutas por área

​5. Resolución: qué guardrail aplica

​6. Qué devuelve un block

​7. Acciones, etapas y tipos de regla de un vistazo

​8. Referencias relacionadas

API de Firewall

API de Compliance

Códigos de error

Guardrails (en profundidad)

1. Autenticación y alcance

2. Una llamada concreta — lista tus guardrails

3. El modelo de roles en una tabla

4. Rutas por área

5. Resolución: qué guardrail aplica

6. Qué devuelve un block

7. Acciones, etapas y tipos de regla de un vistazo

8. Referencias relacionadas