跳转到主要内容
当你想把 防护栏 作为代码来管理时——在 CI 里 创建一条 PII 策略、在发布前对两个版本做 diff，或把匹配信息流拉进你自己的 仪表板——你就要和 /api/guardrail/* 路由打交道。本页是逐路由的 防护栏 api 参考：每一个端点、它所需的工作区角色，以及它期待的认证。 关于一个防护栏是什么以及规则如何组合，请阅读 防护栏。本页是它的线缆级别（wire-level）搭档。

​
1. 认证与范围

每一个 /api/guardrail/* 路由都是管理平面（management plane）：它用 你的控制台会话或访问令牌（你用来登录控制台的同一身份）来认证，而非 一个中继密钥。
你的 sk-orca-... 中继密钥认证 /v1/* 模型调用——它在 /api/guardrail/* 上不起作用。配置路由使用你的用户会话/访问令牌，限定到活跃工作区。
  • 路由是工作区限定的——它们永远只看到活跃工作区的防护栏。没有任何 东西跨越租户边界。
  • 每个路由都按你的 工作区角色 （Viewer / Developer / Admin / Owner）做 RBAC 门控。读取对 Viewer+ 开放；沙箱和所有写入需要 Developer+；误报端点需要 Admin（Admin 或 Owner）。
大多数团队从不直接调用这些路由——控制台驱动了它们全部。当你想把防护栏 放进源代码控制、放进 CI，或接进你自己的工具链时，才动用 REST 表面。

​
2. 一个具体调用——列出你的防护栏

读取是最简单的起点。以任意工作区成员（Viewer+）身份认证： 
curl https://api.orcarouter.ai/api/guardrail/ \
  -H "Authorization: Bearer <your-access-token>" \
  -H "X-Workspace-Id: <workspace-id>"
你会拿回工作区的防护栏以及它们各自附加的密钥数量。如果你想端到端地筛查 你的第一个请求——创建一条策略、附加一个密钥、发出一次调用——可遵循 5 步快速开始， 它从控制台完成全部操作。

​
3. 一张表里的角色模型

挑选层级的是你所采取的动作，而非路由。
动作最低角色
读取（列表/获取、历史、匹配、评测运行）、运行一次评测Viewer+
运行沙箱测试Developer+
创建、更新、删除、还原、上传/删除语料Developer+
标记 / 取消标记一条匹配为误报Admin
读取映射到 guardrails:read 权限（Viewer 及以上持有）；写入映射到 guardrails:write（Developer 及以上）。标记一条误报还额外需要 Admin 角色。 关于角色和权限如何组合，参见 范围、密钥与策略。

​
4. 按区域划分的路由

方法与路径角色
GET /api/guardrail/Viewer+
GET /api/guardrail/metaViewer+
GET /api/guardrail/my-permissions任意成员
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 返回引擎词汇——规则类型、阶段、动作、PII 实体、预设以及预设 类别——这样一个工具就能在不硬编码枚举的情况下构建表单。test 在一个 沙箱里对样本文本运行当前策略：不持久化任何内容，不发往上游。
方法与路径角色
GET /api/guardrail/:id/historyViewer+
GET /api/guardrail/:id/history/diffViewer+
GET /api/guardrail/:id/history/:versionViewer+
POST /api/guardrail/:id/revertDeveloper+
每一次创建、更新和删除都在同一个事务里写入一条历史行。revert 把一个 旧版本向前复制为一个新版本——历史永不被改动。
方法与路径角色
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+
针对一个内置的红队语料或一个你上传的自定义 JSONL 集合运行一个 防护栏，然后读取每个样本的失败。对于调优一个 judge 评分标准，或在你 发布前证明一条策略能捕获已知攻击，都很有用。
方法与路径角色
GET /api/guardrail/match任意成员
GET /api/guardrail/match/grouped任意成员
GET /api/guardrail/match/stats任意成员
GET /api/guardrail/match/export任意成员
GET /api/guardrail/match/cap-status任意成员
GET /api/guardrail/match/:id任意成员
POST /api/guardrail/match/:id/mark-fpAdmin
DELETE /api/guardrail/match/:id/mark-fpAdmin
一条匹配记录规则类型、动作、阶段和一个详情字符串——外加匹配的子串 仅当该防护栏开启了 “Log raw content” 时（默认关闭）。读取路由不 携带额外的权限中间件，因此任何活跃工作区成员都能访问它们；两个 mark-fp 路由是 Admin 专属（Admin 或 Owner）且有速率限制。

​
5. 解析：哪个防护栏生效

上面的路由管理策略；解析则决定在某次给定的中继调用上哪一个运行。这是一个 **显式或默认（explicit-or-default）**模型，对显式附加没有静默回退：
  1. 密钥上的显式 guardrail_id → 该防护栏生效，前提是它存在且已启用。 一个被禁用的附加就是那个关闭开关——它不会回退。
  2. 没有附加 → 工作区已启用的默认防护栏（is_default）。
  3. 两者皆无 → 不执行。该请求与一个从未启用该功能的工作区字节相同。
这是唯一一处与 防火墙 不同的行为：一条被禁用的 已附加防火墙策略会回退到工作区默认值，而一条被禁用的已附加防护栏解析为 无（none）。参见 防护栏 vs 防火墙。
通过密钥编辑器或 token API 在一个密钥上设置 guardrail_id；0/null 表示 “没有显式附加”。

​
6. 一次拦截返回什么

当一条 block 动作规则触发时，中继调用（/v1/*，在你的中继密钥上）—— 而非这些管理路由——返回：
字段值
HTTP 状态400
错误码guardrail_blocked
配额代价一次输入阶段拦截在预扣之前触发，因此不收取任何配额
重试标记为 skip-retry
消息点名触发的防护栏和规则。完整的错误码目录和分诊路径，参见 错误码 和 我的请求为什么被拦下了？。

​
7. 动作、阶段与规则类型一览

meta 路由把它们作为枚举返回；这里列出以供快速参考。
  • 动作： block（拒绝，HTTP 400）、mask（脱敏匹配项，转发清理后的 文本）、flag（仅记录——在不改变流量的情况下观察）、annotate （非阻塞——记录匹配并向上游注入一条人类可读的备注，让模型在回答之前 被告知）、spotlight（非阻塞——把匹配到的不可信片段用分隔符包裹起来， 并告诉模型把它当作数据而非指令处理；一种提示注入防御，实践中作用于 输入阶段）。
  • 阶段： input（请求）、output（模型的响应）或 both。
  • 规则类型： keyword、regex、pii、max_chars、external、 llm_judge、grounding。
输出阶段规则在流式和非流式响应上都执行：一个 block 切断流，而一个 mask 会在分块流动时就地改写匹配的片段。在一个流上，已经刷出的字节无法 撤回，因此一条匹配只有在它缓冲到足够多时才会被处置——为了获得最强保证， 在输入阶段扫描，它会在模型看到请求之前对其消毒。先在沙箱里证明你 确切的阶段/流式组合。
关于逐实体的 PII 覆盖、自定义实体、LLM judge 和上下文 grounding 字段， 参见 防护栏 中的深入参考。

​
8. 相关参考

防火墙 API

动作平面的对等物——/api/workspace/firewall/* 和网关路由。

合规 API

/api/compliance/* —— 合规包、签名报告、数据居住、就绪度。

错误码

每一个 *_blocked 错误码、它的 HTTP 状态，以及该怎么处理。

防护栏（深入）

规则类型、PII 实体、预设、评测，以及完整的匹配信息流。
另见 防护栏 vs 防火墙、 OrcaRouter 如何检查流量 以及 词汇表。