Saltar para o conteúdo principal
Você publicou uma política pii-shield mais apertada na segunda, um colega ampliou um regex na quarta, e agora o tráfego real está gerando falsos positivos. Você precisa ver o que mudou, quem mudou e reverter — sem adivinhar o JSON anterior ou fazer redeploy de nada. É isso que o versionamento de guardrail te dá: uma linha de histórico por mudança, um diff entre quaisquer duas, e revert em um clique. Esta página é o destino focado na superfície de versionamento. Para o motor de guardrail em si — tipos de regra, estágios, ações — comece na Visão geral dos guardrails ou na referência completa de Guardrails.

​
1. O que o versionamento de guardrail registra

Toda mutação em um guardrail — create, update, delete e revert — escreve uma linha de histórico append-only na mesma transação que a mudança. A linha captura um snapshot da config visível ao usuário naquele momento:
  • o name do guardrail,
  • se ele estava enabled,
  • se era o default do workspace,
  • o corpo completo de rules.
Cada linha carrega um número de version monotônico (começando em 1), a operation que a produziu, o author e um timestamp. Como a linha é escrita transacionalmente com a edição, o histórico nunca pode ficar fora de sincronia com a política ao vivo — se a edição commita, sua linha de histórico também.
O histórico é append-only. Um revert não rebobina ou reescreve linhas passadas; ele anexa uma nova versão (veja §4). Você sempre vê a sequência completa de quem fez o quê, em ordem.

​
2. Um exemplo concreto — encontre a edição ruim e reverta

Digamos que o guardrail 42 desviou. Você escreve tudo isto a partir do console na sua própria sessão — a chave de relay sk-orca-... serve apenas para chamadas /v1/*, nunca para ler ou mudar política.
1

Liste o histórico

Abra History na linha do guardrail em /console/guardrails. O feed é do mais novo primeiro. Você vê v5 update (quarta, por um colega), v4 update (segunda, por você), v3 update, e assim por diante até v1 create. Ler o histórico está aberto a qualquer Member do workspace.
2

Faça o diff da mudança suspeita

Escolha as duas versões que cercam a regressão — v4 e v5 — e veja o diff. O corpo de rules é mostrado lado a lado, então o regex ampliado salta como a linha que mudou.
3

Reverta

Restaure v4. O name, a flag enabled, a flag default e as rules do guardrail ao vivo são definidos de volta para aquele snapshot, e uma nova linha v6 revert é anexada. A mudança fica ao vivo na próxima requisição — sem redeploy, sem mudança de SDK. Reverter exige o papel Developer+.
O mesmo fluxo pela API REST, tudo no seu session / access token (nunca a chave de relay), com escopo de workspace 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}'
A resposta do revert retorna o guardrail ao vivo pós-revert para que sua UI possa atualizar sem um round-trip extra. A próxima chamada /v1/* filtrada por este guardrail vê a política restaurada.

​
3. Histórico, diff e o feed de versões

GET /api/guardrail/:id/history retorna o rastro de versões, do mais novo primeiro. Cada entrada é um snapshot com seu número de versão, operação (create / update / delete / revert), autor e timestamp. O feed tem escopo de workspace — um chamador em outro workspace recebe o mesmo envelope de não-encontrado que um guardrail ausente, então a existência nunca vaza.
GET /api/guardrail/:id/history/:version busca um snapshot pelo seu número de versão — útil para inspecionar o corpo exato de rules que estava ao vivo em um ponto no tempo antes de você decidir se reverte para ele.
GET /api/guardrail/:id/history/diff?from=N&to=M retorna ambos os snapshots — from e to — para que o console possa renderizar uma comparação lado a lado do name, das flags e das rules. Ambas as versões devem pertencer ao seu workspace, ou a chamada retorna o envelope uniforme de não-encontrado.
Leituras — lista de histórico, versão única e diff — estão abertas a qualquer Member do workspace. São pura inspeção: nada sobre o tráfego muda, e nenhuma chamada a modelo ou fornecedor é feita.

​
4. O revert restaura como uma nova versão

Um revert não é uma rebobinagem. POST /api/guardrail/:id/revert com um corpo to_version:
  1. Carrega o snapshot da versão alvo.
  2. Restaura o name, a flag enabled, a flag default e as rules do guardrail ao vivo para aquele snapshot — atomicamente, em uma transação.
  3. Anexa uma nova linha de histórico revert capturando o estado agora ao vivo.
Então reverter v5 de volta para v4 produz um novo v6 cujo conteúdo é igual a v4. Seu histórico lê v1 → v2 → … → v5 → v6(revert) — cada passo preservado, nada mutado. Reverta aquele snapshot mais antigo de novo depois e você obtém um v7, e assim por diante.
Um estado desabilitado ou não-padrão restaurado faz o round-trip intacto. Se a versão para a qual você reverte tinha enabled: false ou não era o padrão do workspace, reverter define o guardrail ao vivo de volta para exatamente isso — ele não mantém silenciosamente a política ligada. Faça o diff primeiro para saber se um revert também virará essas flags.
Como o vínculo vive no gateway, um revert desloca cada chave de API vinculada a este guardrail de uma vez — e o padrão do workspace, se for este — na próxima chamada. Veja vincular a uma chave e o padrão do workspace para como o vínculo resolve.

​
5. Papéis e retenção

AçãoRotaPapel
Listar / ler versões, diffGET …/history, …/history/diff, …/history/:versionMember
Reverter para uma versãoPOST …/revertDeveloper+
Todas as rotas de histórico são /api/guardrail/* e autenticam com seu session / access token sob X-Workspace-Id — nunca uma chave de relay sk-orca-.... Reverter carrega o mesmo gate Developer+ que criar ou atualizar um guardrail, já que muda o tráfego ao vivo.
O histórico é retido nas 50 versões mais recentes por guardrail. Linhas mais antigas são podadas automaticamente conforme você continua editando, então um fluxo de loop-de-edição falador nunca faz o rastro crescer ilimitadamente. O endpoint de lista retorna até as 50 mais novas, do mais novo primeiro.
Combine o versionamento com ajuste flag-first: publique uma nova regra como flag, observe o feed de matches, e se ela se comportar mal, faça o diff e reverta em segundos em vez de reconstruir a política antiga à mão.

​
6. Para onde ir a seguir

Teste e eval antes de publicar

Prove uma política no sandbox e contra um corpus antes que ela se torne uma versão que você teria que reverter.

Ajustar falsos positivos

O loop de flag-depois-promover que o versionamento torna seguro.

Ações: block, mask, flag

O que cada regra faz uma vez que uma versão está ao vivo.

Referência de Guardrails

O motor completo — tipos de regra, estágios, presets e a API completa.
O versionamento aqui cobre a política de conteúdo de guardrail. O firewall tem sua própria superfície de mudança para política de ferramenta; para como as duas camadas de enforcement diferem, veja guardrails vs. firewall.