跳轉到主要內容
當你想把防護欄當成程式碼來管理——在 CI 中建立 PII 政策、在發布前對比兩個版本，或把匹配動態拉進 你自己的儀表板——你就和 /api/guardrail/* 路由對話。本頁是 逐路由的防護欄 API 參考：每個端點、它所需的工作區 角色，以及它預期的驗證。 關於防護欄是什麼以及規則如何組合，閱讀防護欄。 本頁是線級的伴讀。

​
1. 驗證與範圍

每個 /api/guardrail/* 路由都是管理平面：它以你的控制台 工作階段或存取權杖（與你登入控制台時相同的身份）驗證， 而非中繼金鑰。
你的 sk-orca-... 中繼金鑰驗證 /v1/* 模型呼叫——它在 /api/guardrail/* 上不起作用。設定路由使用你的使用者工作階段／存取 權杖，範圍化到活躍工作區。
  • 路由是工作區範圍化的——它們只看見活躍工作區的 防護欄。沒有任何東西跨越租戶邊界。
  • 每個路由都由你的工作區角色 RBAC 把關（Viewer / Developer / Admin / Owner）。讀取對 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 集合執行防護欄，然後讀取逐樣本失敗。對於調校評審 評分標準或在發布前證明政策能捕捉已知攻擊很有用。
方法與路徑角色
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
一次匹配記錄規則類型、動作、階段和一個詳細字串——加上 匹配到的子字串，只在該防護欄的「記錄原始內容」開啟時 （預設關閉）。讀取路由不攜帶額外的權限中介軟體，所以 任何活躍工作區成員都能存取它們；兩個 mark-fp 路由是 Admin 限定（Admin 或 Owner）且有速率限制。

​
5. 解析：哪個防護欄適用

上面的路由管理政策；解析決定哪一個在給定的 中繼呼叫上執行。它是一個明確或預設模型，明確附加時 沒有靜默回退：
  1. 金鑰上明確的 guardrail_id → 該防護欄適用，前提是它 存在且已啟用。停用的附加是關閉開關——它 不回退。
  2. 沒有附加 → 工作區已啟用的預設防護欄（is_default）。
  3. 兩者皆無 → 無強制執行。請求與從未啟用該功能的 工作區逐位元組相同。
這是與防火牆唯一不同的行為：一個 停用的附加防火牆政策回退到工作區預設值，而 停用的附加防護欄解析為無。參見 防護欄與防火牆。
透過金鑰編輯器或權杖 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 評審和情境 接地欄位，參見防護欄中的深度參考。

​
8. 相關參考

防火牆 API

動作平面的對等項——/api/workspace/firewall/* 和閘道路由。

合規性 API

/api/compliance/*——包、簽署報告、居住地、就緒度。

錯誤代碼

每個 *_blocked 代碼、它的 HTTP 狀態，以及如何處理。

防護欄（深入）

規則類型、PII 實體、預設值、評估，以及完整的匹配動態。
另見防護欄與防火牆、 OrcaRouter 如何審查流量， 以及詞彙表。