Chuyển đến nội dung chính
Khi bạn muốn quản lý guardrails như code — tạo một chính sách PII trong CI, diff hai phiên bản trước một release, hoặc kéo feed match vào dashboard của riêng bạn — bạn nói chuyện với các route /api/guardrail/*. Trang này là tham chiếu guardrail api theo từng route: mọi endpoint, vai trò workspace nó yêu cầu, và auth nó mong đợi. Về việc một guardrail là gì và các quy tắc kết hợp ra sao, đọc Guardrails. Trang này là người đồng hành ở tầng wire.

​
1. Auth và scope

Mọi route /api/guardrail/* đều thuộc mặt phẳng quản lý: nó xác thực bằng session hoặc access token console của bạn (cùng danh tính bạn đăng nhập vào console), không phải một relay key.
Relay key sk-orca-... của bạn xác thực các cuộc gọi model /v1/* — nó không hoạt động trên /api/guardrail/*. Các route cấu hình dùng session/access token người dùng của bạn, được scope theo workspace đang hoạt động.
  • Các route được scope theo workspace — chúng chỉ bao giờ thấy guardrail của workspace đang hoạt động. Không gì vượt qua ranh giới tenant.
  • Mỗi route được gate bằng RBAC theo vai trò workspace (Viewer / Developer / Admin / Owner) của bạn. Đọc mở cho Viewer+; sandbox và mọi thao tác ghi yêu cầu Developer+; các endpoint false-positive yêu cầu Admin (Admin hoặc Owner).
Hầu hết các team không bao giờ gọi trực tiếp các route này — console điều khiển tất cả chúng. Hãy dùng tới bề mặt REST khi bạn muốn guardrail nằm trong source control, trong CI, hoặc nối vào công cụ của riêng bạn.

​
2. Một cuộc gọi cụ thể — liệt kê guardrail của bạn

Một thao tác đọc là nơi đơn giản nhất để bắt đầu. Đã xác thực với tư cách bất kỳ thành viên workspace nào (Viewer+): 
curl https://api.orcarouter.ai/api/guardrail/ \
  -H "Authorization: Bearer <your-access-token>" \
  -H "X-Workspace-Id: <workspace-id>"
Bạn nhận lại các guardrail của workspace với số lượng key đính kèm của chúng. Để thay vào đó sàng lọc request đầu tiên của bạn từ đầu đến cuối — tạo một chính sách, đính một key, gửi một cuộc gọi — hãy theo quickstart 5 bước, làm tất cả từ console.

​
3. Mô hình vai trò trong một bảng

Hành động bạn thực hiện, không phải route, mới quyết định tầng.
Hành độngVai trò tối thiểu
Đọc (list/get, lịch sử, match, lần chạy eval), chạy một evalViewer+
Chạy sandbox testDeveloper+
Tạo, cập nhật, xóa, revert, upload/xóa corpusDeveloper+
Đánh dấu / bỏ đánh dấu một match là false positiveAdmin
Đọc ánh xạ tới quyền guardrails:read (do Viewer trở lên nắm giữ); ghi ánh xạ tới guardrails:write (Developer trở lên). Đánh dấu một false positive bổ sung yêu cầu vai trò Admin. Xem Scope, key & chính sách để biết cách vai trò và quyền kết hợp.

​
4. Các route theo khu vực

Method & pathVai trò
GET /api/guardrail/Viewer+
GET /api/guardrail/metaViewer+
GET /api/guardrail/my-permissionsmọi thành viên
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 trả về từ vựng của engine — kiểu quy tắc, giai đoạn, hành động, thực thể PII, preset, và danh mục preset — để một công cụ có thể dựng một form mà không cần hard-code các enum. test chạy chính sách hiện tại trên văn bản mẫu trong một sandbox: không gì được lưu, không gì đi upstream.
Method & pathVai trò
GET /api/guardrail/:id/historyViewer+
GET /api/guardrail/:id/history/diffViewer+
GET /api/guardrail/:id/history/:versionViewer+
POST /api/guardrail/:id/revertDeveloper+
Mọi lần tạo, cập nhật, và xóa đều ghi một hàng lịch sử trong cùng transaction. revert sao chép một phiên bản cũ tiến lên thành một phiên bản mới — lịch sử không bao giờ bị thay đổi.
Method & pathVai trò
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+
Chạy một guardrail đối với một corpus red-team đóng gói sẵn hoặc một bộ JSONL tùy chỉnh bạn upload, rồi đọc các lần thất bại theo từng mẫu. Hữu ích để tinh chỉnh một rubric judge hoặc chứng minh một chính sách bắt được các tấn công đã biết trước khi bạn phát hành.
Method & pathVai trò
GET /api/guardrail/matchmọi thành viên
GET /api/guardrail/match/groupedmọi thành viên
GET /api/guardrail/match/statsmọi thành viên
GET /api/guardrail/match/exportmọi thành viên
GET /api/guardrail/match/cap-statusmọi thành viên
GET /api/guardrail/match/:idmọi thành viên
POST /api/guardrail/match/:id/mark-fpAdmin
DELETE /api/guardrail/match/:id/mark-fpAdmin
Một match ghi lại kiểu quy tắc, hành động, giai đoạn, và một chuỗi chi tiết — cộng với chuỗi con đã khớp chỉ khi “Log raw content” đang bật cho guardrail đó (mặc định tắt). Các route đọc không mang middleware quyền bổ sung, nên bất kỳ thành viên workspace đang hoạt động nào cũng có thể tiếp cận chúng; hai route mark-fp chỉ dành cho Admin (Admin hoặc Owner) và bị giới hạn tần suất.

​
5. Phân giải: guardrail nào áp dụng

Các route ở trên quản lý chính sách; phân giải quyết định cái nào chạy trên một cuộc gọi relay nhất định. Đó là một mô hình tường minh-hoặc-mặc định không có fallback im lặng trên một lần đính tường minh:
  1. guardrail_id tường minh trên key → guardrail đó áp dụng, nếu nó tồn tại và được bật. Một lần đính bị vô hiệu là công tắc tắt — nó không fallback.
  2. Không đính → guardrail mặc định đã bật của workspace (is_default).
  3. Cả hai đều không → không thực thi. Request giống hệt từng byte với một workspace chưa bao giờ bật tính năng này.
Đây là hành vi duy nhất khác với Firewall: một chính sách firewall đính bị vô hiệu sẽ fallback về mặc định của workspace, trong khi một guardrail đính bị vô hiệu phân giải thành không có gì. Xem Guardrails vs Firewall.
Đặt guardrail_id trên một key qua trình soạn key hoặc token API; 0/null nghĩa là “không đính tường minh.”

​
6. Một lần block trả về gì

Khi một quy tắc hành động block kích hoạt, cuộc gọi relay (/v1/*, trên relay key của bạn) — không phải các route quản lý này — trả về:
TrườngGiá trị
Trạng thái HTTP400
Mã lỗiguardrail_blocked
Chi phí quotamột lần chặn ở giai đoạn input kích hoạt trước pre-consume, nên không tốn quota
Retryđánh dấu skip-retry
Message nêu tên guardrail và quy tắc đã kích hoạt. Về danh mục mã đầy đủ và các đường phân loại, xem Mã lỗi và Tại sao request của tôi bị chặn?.

​
7. Hành động, giai đoạn, và kiểu quy tắc trong nháy mắt

Route meta trả về những thứ này dưới dạng enum; đây là chúng để tham chiếu nhanh.
  • Hành động: block (từ chối, HTTP 400), mask (redact match, chuyển tiếp văn bản đã làm sạch), flag (chỉ ghi log — quan sát mà không đổi traffic), annotate (không chặn — ghi lại match và chèn một ghi chú con người đọc được lên upstream để model được báo về nó trước khi nó trả lời), spotlight (không chặn — bọc đoạn không đáng tin đã khớp trong các dấu phân cách và bảo model coi nó là dữ liệu, không phải hướng dẫn; một phòng vệ prompt-injection, thực tế ở giai đoạn input).
  • Giai đoạn: input (request), output (phản hồi của model), hoặc both.
  • Kiểu quy tắc: keyword, regex, pii, max_chars, external, llm_judge, grounding.
Các quy tắc giai đoạn output được thực thi trên cả phản hồi streaming và không streaming: một block cắt stream, và một mask viết lại các đoạn đã khớp ngay trong dòng khi các chunk chảy qua. Trên một stream, các byte đã flush không thể thu hồi, nên một match chỉ được hành động khi đã buffer đủ — để đảm bảo mạnh nhất, hãy quét ở giai đoạn input, nơi sanitize request trước khi model từng thấy nó. Hãy chứng minh tổ hợp giai đoạn/stream chính xác của bạn trong sandbox trước.
Về các override PII theo từng thực thể, thực thể tùy chỉnh, LLM judge, và các trường grounding theo ngữ cảnh, xem tham chiếu sâu trong Guardrails.

​
8. Tham chiếu liên quan

Firewall API

Đối tác ở mặt phẳng hành động — /api/workspace/firewall/* và các route gateway.

Compliance API

/api/compliance/* — pack, báo cáo có chữ ký, residency, readiness.

Mã lỗi

Mọi mã *_blocked, trạng thái HTTP của nó, và phải làm gì với nó.

Guardrails (đào sâu)

Kiểu quy tắc, thực thể PII, preset, eval, và feed match đầy đủ.
Xem thêm Guardrails vs Firewall, Cách OrcaRouter kiểm tra traffic, và Bảng thuật ngữ.