Saltar para o conteúdo principal
Quando você quer gerenciar guardrails como código — criar uma política de PII no CI, fazer diff de duas versões antes de um release, ou puxar o feed de matches para o seu próprio dashboard — você fala com as rotas /api/guardrail/*. Esta página é a referência da api de guardrail rota a rota: cada endpoint, o papel de workspace que ele exige e a autenticação que ele espera. Para o que um guardrail é e como as regras se compõem, leia Guardrails. Esta página é a companheira em nível de protocolo.

​
1. Autenticação e escopo

Toda rota /api/guardrail/* é plano de gerenciamento: ela autentica com a sessão ou token de acesso do seu console (a mesma identidade com a qual você faz login no console), não uma chave de relay.
Sua chave de relay sk-orca-... autentica chamadas de modelo /v1/* — ela não funciona em /api/guardrail/*. As rotas de configuração usam o token de sessão/acesso do seu usuário, com escopo para o workspace ativo.
  • As rotas têm escopo de workspace — elas só veem os guardrails do workspace ativo. Nada cruza uma fronteira de tenant.
  • Toda rota é controlada por RBAC pelo seu papel de workspace (Viewer / Developer / Admin / Owner). Leituras abertas a Viewer+; o sandbox e todas as escritas exigem Developer+; os endpoints de falso positivo exigem Admin (Admin ou Owner).
A maioria das equipes nunca chama essas rotas diretamente — o console aciona todas elas. Recorra à superfície REST quando quiser guardrails em controle de versão, em CI ou conectados às suas próprias ferramentas.

​
2. Uma chamada concreta — liste seus guardrails

Uma leitura é o lugar mais simples para começar. Autenticado como qualquer membro do workspace (Viewer+): 
curl https://api.orcarouter.ai/api/guardrail/ \
  -H "Authorization: Bearer <your-access-token>" \
  -H "X-Workspace-Id: <workspace-id>"
Você recebe de volta os guardrails do workspace com suas contagens de chaves vinculadas. Para, em vez disso, filtrar sua primeira requisição de ponta a ponta — criar uma política, vincular uma chave, enviar uma chamada — siga o quickstart de 5 passos, que faz tudo a partir do console.

​
3. O modelo de papéis em uma tabela

A ação que você toma, não a rota, escolhe o nível.
AçãoPapel mínimo
Leitura (list/get, history, matches, eval runs), rodar um evalViewer+
Rodar teste no sandboxDeveloper+
Criar, atualizar, deletar, reverter, fazer upload/delete de corpusDeveloper+
Marcar / desmarcar um match como falso positivoAdmin
Leituras mapeiam para a permissão guardrails:read (mantida por Viewer e acima); escritas mapeiam para guardrails:write (Developer e acima). Marcar um falso positivo adicionalmente exige o papel de Admin. Veja Escopo, chaves & políticas para como papéis e permissões se combinam.

​
4. Rotas por área

Método & pathPapel
GET /api/guardrail/Viewer+
GET /api/guardrail/metaViewer+
GET /api/guardrail/my-permissionsqualquer membro
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 retorna o vocabulário do motor — tipos de regra, estágios, ações, entidades de PII, presets e categorias de preset — para que uma ferramenta possa montar um formulário sem codificar os enums diretamente. test roda a política atual sobre texto de amostra em um sandbox: nada é persistido, nada vai upstream.
Método & pathPapel
GET /api/guardrail/:id/historyViewer+
GET /api/guardrail/:id/history/diffViewer+
GET /api/guardrail/:id/history/:versionViewer+
POST /api/guardrail/:id/revertDeveloper+
Todo create, update e delete escreve uma linha de histórico na mesma transação. revert copia uma versão antiga adiante como uma nova versão — o histórico nunca é mutado.
Método & pathPapel
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+
Rode um guardrail contra um corpus red-team embutido ou um conjunto JSONL personalizado que você faz upload, depois leia as falhas por amostra. Útil para ajustar um rubric de juiz ou provar que uma política pega ataques conhecidos antes de você aplicar.
Método & pathPapel
GET /api/guardrail/matchqualquer membro
GET /api/guardrail/match/groupedqualquer membro
GET /api/guardrail/match/statsqualquer membro
GET /api/guardrail/match/exportqualquer membro
GET /api/guardrail/match/cap-statusqualquer membro
GET /api/guardrail/match/:idqualquer membro
POST /api/guardrail/match/:id/mark-fpAdmin
DELETE /api/guardrail/match/:id/mark-fpAdmin
Um match registra o tipo de regra, ação, estágio e uma string de detalhe — mais a substring correspondente apenas se “Log raw content” estiver ligado para aquele guardrail (desligado por padrão). As rotas de leitura não carregam middleware extra de permissão, então qualquer membro ativo do workspace pode alcançá-las; as duas rotas mark-fp são apenas-Admin (Admin ou Owner) e com rate-limit.

​
5. Resolução: qual guardrail se aplica

As rotas acima gerenciam políticas; a resolução decide qual delas roda em uma dada chamada de relay. É um modelo explícito-ou-padrão sem fallback silencioso em um vínculo explícito:
  1. guardrail_id explícito na chave → esse guardrail se aplica, se existir e estiver habilitado. Um vínculo desabilitado é o interruptor de desligar — ele não cai de volta.
  2. Sem vínculo → o guardrail padrão habilitado do workspace (is_default).
  3. Nenhum → sem enforcement. A requisição é byte-idêntica à de um workspace que nunca habilitou o recurso.
Este é o único comportamento que difere do Firewall: uma política de firewall vinculada desabilitada cai de volta para o padrão do workspace, enquanto um guardrail vinculado desabilitado resolve para nenhum. Veja Guardrails vs Firewall.
Defina guardrail_id em uma chave através do editor de chaves ou da API de tokens; 0/null significa “sem vínculo explícito”.

​
6. O que um bloqueio retorna

Quando uma regra de ação block dispara, a chamada de relay (/v1/*, na sua chave de relay) — não estas rotas de gerenciamento — retorna:
CampoValor
Status HTTP400
Código de erroguardrail_blocked
Custo de cotaum bloqueio em estágio de entrada dispara antes do pré-consumo, então nenhuma cota é cobrada
Retrymarcado skip-retry
A mensagem nomeia o guardrail e a regra que disparou. Para o catálogo completo de códigos e caminhos de triagem, veja Códigos de erro e Por que minha requisição foi bloqueada?.

​
7. Ações, estágios e tipos de regra em resumo

A rota meta retorna estes como enums; aqui estão eles para referência rápida.
  • Ações: block (rejeita, HTTP 400), mask (redige a correspondência, encaminha o texto limpo), flag (apenas registra — observa sem alterar o tráfego), annotate (não-bloqueante — registra a correspondência e injeta uma nota legível por humanos upstream para que o modelo seja informado sobre ela antes de responder), spotlight (não-bloqueante — envolve o trecho não confiável correspondente em delimitadores e diz ao modelo para tratá-lo como dado, não instruções; uma defesa contra injeção de prompt, na prática em estágio de entrada).
  • Estágios: input (a requisição), output (a resposta do modelo) ou both.
  • Tipos de regra: keyword, regex, pii, max_chars, external, llm_judge, grounding.
Regras de estágio de saída são aplicadas em ambas as respostas, em streaming e não-streaming: um block corta o stream, e um mask reescreve os trechos correspondentes em banda à medida que os chunks fluem. Em um stream, bytes já liberados não podem ser retraídos, então uma correspondência só é tratada depois que o suficiente dela foi bufferizado — para a garantia mais forte, escaneie no estágio input, que sanitiza a requisição antes que o modelo a veja. Prove sua combinação exata de estágio/stream primeiro no sandbox.
Para overrides de PII por entidade, entidades personalizadas, o juiz LLM e campos de grounding contextual, veja a referência aprofundada em Guardrails.

​
8. Referências relacionadas

API de Firewall

O par do plano de ação — /api/workspace/firewall/* e as rotas do gateway.

API de Compliance

/api/compliance/* — packs, relatórios assinados, residência, prontidão.

Códigos de erro

Todo código *_blocked, seu status HTTP e o que fazer a respeito.

Guardrails (aprofundado)

Tipos de regra, entidades de PII, presets, evals e o feed de matches por completo.
Veja também Guardrails vs Firewall, Como o OrcaRouter inspeciona o tráfego e o Glossário.