メインコンテンツへスキップ
ガードレールをコードとして管理したいとき — CI で PII ポリシーを作成する、リリース前に 2 つのバージョンを diff する、あるいはマッチフィードを 自分のダッシュボードに取り込む — /api/guardrail/* ルートと対話します。このページは ルート単位のガードレール API リファレンスです：すべてのエンドポイント、それが 必要とするワークスペースロール、そして期待される認証です。 ガードレールが何であるか、そしてルールがどう構成されるかについては、 ガードレールを読んでください。このページはワイヤレベルの コンパニオンです。

​
1. 認証とスコープ

すべての /api/guardrail/* ルートは管理プレーンです：リレーキーではなく、 コンソールセッションまたはアクセストークン（コンソールにログインするのと同じ アイデンティティ）で認証します。
あなたの 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 エンティティ、 プリセット、プリセットカテゴリ — を返すため、ツールは enum をハードコードせずに フォームを構築できます。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
マッチはルールタイプ、アクション、ステージ、詳細文字列を記録します — 加えて、 そのガードレールで “Log raw content” がオンの場合のみ、マッチした部分文字列を 記録します（デフォルトはオフ）。読み取りルートには追加の権限ミドルウェアがないため、 任意のアクティブなワークスペースメンバーが到達できます；2 つの mark-fp ルートは Admin のみ（Admin または Owner）でレート制限されています。

​
5. 解決：どのガードレールが適用されるか

上記のルートはポリシーを管理します；解決は、所与のリレー呼び出しでどれが走るかを 決定します。これは明示的またはデフォルトモデルであり、明示的なアタッチメントに サイレントなフォールバックはありません：
  1. キーの明示的 guardrail_id → そのガードレールが適用されます、ただしそれが 存在し有効である場合。無効化されたアタッチメントはオフスイッチです — それは フォールバックしません。
  2. アタッチメントなし → ワークスペースの有効なデフォルトガードレール（is_default）。
  3. どちらもなし → 強制なし。リクエストは、この機能を一度も有効化していない ワークスペースとバイト単位で同一です。
これはファイアウォールと異なる唯一の挙動です：無効化された アタッチ済みファイアウォールポリシーはワークスペースデフォルトにフォールバックしますが、 無効化されたアタッチ済みガードレールはなしに解決します。 ガードレール vs ファイアウォールを 参照してください。
キーエディタまたはトークン API を通じてキーに guardrail_id を設定します；0/null は 「明示的なアタッチメントなし」を意味します。

​
6. ブロックが返すもの

block アクションのルールが発火すると、リレー呼び出し（/v1/*、あなたのリレーキー上） — これらの管理ルートではなく — は次を返します：
フィールド値
HTTP ステータス400
エラーコードguardrail_blocked
クォータコスト入力ステージのブロックは事前消費の前に発火するため、クォータは課金されない
リトライskip-retry とマーク
メッセージは、発火したガードレールとルールを名指しします。完全なコードカタログと トリアージパスについては、エラーコードと なぜリクエストがブロックされたのか？を参照してください。

​
7. アクション、ステージ、ルールタイプ一覧

meta ルートはこれらを enum として返します；ここに簡易リファレンスとして示します。
  • アクション： block（拒否、HTTP 400）、mask（マッチをリダクトし、 クリーニングされたテキストを転送）、flag（ログのみ — トラフィックを変えずに 観察）、annotate（非ブロッキング — マッチを記録し、モデルが答える前にそれを 知らせるための人間可読なノートをアップストリームに注入）、spotlight（非ブロッキング — マッチした信頼されていないスパンをデリミタで包み、それを指示ではなくデータとして 扱うようモデルに伝える；プロンプトインジェクション防御、実際には入力ステージ）。
  • ステージ： input（リクエスト）、output（モデルのレスポンス）、または both。
  • ルールタイプ： keyword、regex、pii、max_chars、external、 llm_judge、grounding。
出力ステージのルールは、ストリーミングと非ストリーミングの両方のレスポンスで 強制されます：block はストリームを切り、mask はチャンクが流れる中でマッチした スパンを帯域内で書き換えます。ストリームでは、すでにフラッシュされたバイトは撤回 できないため、マッチは十分にバッファされたときにのみ作用されます — 最も強い保証の ためには、input ステージでスキャンしてください。これはモデルが見る前にリクエストを サニタイズします。まず正確なステージ/ストリームの組み合わせをサンドボックスで証明 してください。
エンティティごとの PII オーバーライド、カスタムエンティティ、LLM ジャッジ、文脈的 グラウンディングフィールドについては、ガードレールの 詳細リファレンスを参照してください。

​
8. 関連リファレンス

ファイアウォール API

アクションプレーンのピア — /api/workspace/firewall/* とゲートウェイルート。

コンプライアンス API

/api/compliance/* — パック、署名付きレポート、レジデンシー、レディネス。

エラーコード

すべての *_blocked コード、その HTTP ステータス、そして何をすべきか。

ガードレール（詳細）

ルールタイプ、PII エンティティ、プリセット、評価、そしてマッチフィードを完全に。
ガードレール vs ファイアウォール、 OrcaRouter がトラフィックをどう検査するか、 そして用語集も参照してください。