메인 콘텐츠로 건너뛰기
guardrails를 코드로 관리하고 싶을 때 — CI에서 PII 정책을 생성하거나, 릴리스 전에 두 버전을 diff하거나, matches 피드를 여러분 자신의 대시보드로 가져오기 — /api/guardrail/* 라우트와 통신합니다. 이 페이지는 라우트별 guardrail api 레퍼런스입니다: 모든 엔드포인트, 그것이 요구하는 워크스페이스 역할, 그리고 그것이 기대하는 인증. guardrail이 무엇이고 규칙이 어떻게 조합되는지는 Guardrails를 읽으세요. 이 페이지는 와이어 수준의 동반자입니다.

​
1. 인증과 범위

모든 /api/guardrail/* 라우트는 관리 평면입니다: 릴레이 키가 아니라, 콘솔 세션 또는 액세스 토큰(콘솔에 로그인하는 것과 동일한 신원)으로 인증합니다.
여러분의 sk-orca-... 릴레이 키는 /v1/* 모델 호출을 인증합니다 — /api/guardrail/*에서는 작동하지 않습니다. 구성 라우트는 활성 워크스페이스로 범위 지정된 여러분의 사용자 세션/액세스 토큰을 사용합니다.
  • 라우트는 워크스페이스 범위입니다 — 활성 워크스페이스의 guardrail만 봅니다. 아무것도 테넌트 경계를 넘지 않습니다.
  • 모든 라우트는 여러분의 워크스페이스 역할에 의해 RBAC 게이트 처리됩니다(Viewer / Developer / Admin / Owner). 읽기는 **Viewer+**에 개방; 샌드박스와 모든 쓰기는 **Developer+**를 요구; 거짓 양성 엔드포인트는 Admin(Admin 또는 Owner)을 요구합니다.
대부분의 팀은 이 라우트들을 직접 호출하지 않습니다 — 콘솔이 그것들을 모두 구동합니다. guardrail을 소스 관리, CI, 또는 여러분 자신의 도구에 연결하고 싶을 때 REST 표면을 사용하세요.

​
2. 한 가지 구체적 호출 — guardrail 목록

읽기가 시작하기 가장 간단한 곳입니다. 임의의 워크스페이스 멤버로 인증 (Viewer+): 
curl https://api.orcarouter.ai/api/guardrail/ \
  -H "Authorization: Bearer <your-access-token>" \
  -H "X-Workspace-Id: <workspace-id>"
연결된 키 카운트와 함께 워크스페이스의 guardrail을 돌려받습니다. 대신 첫 요청을 처음부터 끝까지 스크리닝하려면 — 정책 생성, 키 연결, 호출 전송 — 5단계 퀵스타트를 따르세요, 모두 콘솔에서 처리됩니다.

​
3. 한 표로 보는 역할 모델

라우트가 아니라 여러분이 취하는 액션이 등급을 선택합니다.
Action최소 역할
읽기(list/get, history, matches, eval runs), eval 실행Viewer+
샌드박스 test 실행Developer+
생성, 업데이트, 삭제, 되돌리기, corpus 업로드/삭제Developer+
match를 거짓 양성으로 표시 / 해제Admin
읽기는 guardrails:read 권한에 매핑되고(Viewer 이상이 보유); 쓰기는 guardrails:write에 매핑됩니다(Developer 이상). 거짓 양성 표시는 추가로 Admin 역할을 요구합니다. 역할과 권한이 어떻게 결합되는지는 Scope, keys & policies를 참조하세요.

​
4. 영역별 라우트

메서드 및 경로역할
GET /api/guardrail/Viewer+
GET /api/guardrail/metaViewer+
GET /api/guardrail/my-permissionsany member
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+
guardrail을 번들된 레드팀 corpus 또는 여러분이 업로드한 커스텀 JSONL 세트에 대해 실행한 뒤, 샘플별 실패를 읽으세요. judge 루브릭을 튜닝하거나 출시 전에 정책이 알려진 공격을 잡는다는 것을 증명하는 데 유용합니다.
메서드 및 경로역할
GET /api/guardrail/matchany member
GET /api/guardrail/match/groupedany member
GET /api/guardrail/match/statsany member
GET /api/guardrail/match/exportany member
GET /api/guardrail/match/cap-statusany member
GET /api/guardrail/match/:idany member
POST /api/guardrail/match/:id/mark-fpAdmin
DELETE /api/guardrail/match/:id/mark-fpAdmin
match는 규칙 유형, 액션, 단계, 그리고 detail 문자열을 기록합니다 — 그리고 그 guardrail에 “Log raw content”가 켜져 있을 경우에만 매치된 부분 문자열도(기본 꺼짐). 읽기 라우트는 추가 권한 미들웨어를 담지 않으므로, 임의의 활성 워크스페이스 멤버가 도달할 수 있습니다; 두 mark-fp 라우트는 Admin 전용(Admin 또는 Owner)이며 레이트 리밋이 적용됩니다.

​
5. 해석: 어떤 guardrail이 적용되는가

위 라우트는 정책을 관리합니다; 해석은 주어진 릴레이 호출에서 어느 것이 실행되는지를 결정합니다. 이는 명시적 연결에 대해 조용한 폴백이 없는 명시적-또는-기본값 모델입니다:
  1. 키의 명시적 guardrail_id → 그 guardrail이 적용됩니다, 그것이 존재하고 활성화된 경우. 비활성화된 연결은 오프 스위치입니다 — 폴백하지 않습니다.
  2. 연결 없음 → 워크스페이스의 활성화된 기본 guardrail(is_default).
  3. 둘 다 아님 → 강제 없음. 요청은 기능을 한 번도 활성화하지 않은 워크스페이스와 바이트 단위로 동일합니다.
이것이 Firewall과 다른 한 가지 동작입니다: 비활성화된 연결 firewall 정책은 워크스페이스 기본값으로 폴백하지만, 비활성화된 연결 guardrail은 none으로 해석됩니다. Guardrails vs Firewall 참조.
키 편집기나 토큰 API를 통해 키에 guardrail_id를 설정하세요; 0/null은 “명시적 연결 없음”을 의미합니다.

​
6. 차단이 무엇을 반환하는가

block 액션 규칙이 발동하면, 이 관리 라우트가 아니라 릴레이 호출(/v1/*, 여러분의 릴레이 키에서)이 반환합니다:
FieldValue
HTTP 상태400
오류 코드guardrail_blocked
쿼터 비용입력 단계 차단은 사전 소비 전에 발동하므로 쿼터가 청구되지 않음
재시도skip-retry로 표시됨
메시지는 발동한 guardrail과 규칙을 명시합니다. 전체 코드 카탈로그와 트리아지 경로는 오류 코드와 내 요청이 왜 차단되었나요?를 참조하세요.

​
7. 액션, 단계, 규칙 유형 한눈에 보기

meta 라우트가 이들을 enum으로 반환합니다; 빠른 참조를 위해 여기 있습니다.
  • Actions: block(거부, HTTP 400), mask(매치를 편집하고 정화된 텍스트 전달), flag(로그만 — 트래픽을 변경하지 않고 관찰), annotate(비차단 — 매치를 기록하고 사람 판독 가능한 노트를 업스트림에 주입하여 모델이 답하기 전에 알게 함), spotlight(비차단 — 매치된 신뢰할 수 없는 구간을 구분자로 감싸고 모델에게 그것을 지시가 아니라 데이터로 취급하라고 알림; 프롬프트 인젝션 방어, 실무에서 입력 단계).
  • Stages: input(요청), output(모델 응답), 또는 both.
  • Rule types: keyword, regex, pii, max_chars, external, llm_judge, grounding.
출력 단계 규칙은 스트리밍 및 비스트리밍 응답 모두에 강제됩니다: block은 스트림을 끊고, mask는 청크가 흐르는 동안 매치된 구간을 인밴드로 재작성합니다. 스트림에서는 이미 플러시된 바이트를 철회할 수 없으므로, 매치는 그것의 충분한 양이 버퍼링된 후에만 처리됩니다 — 가장 강한 보장을 위해서는 모델이 보기 전에 요청을 정화하는 input 단계에서 스캔하세요. 정확한 단계/스트림 조합을 먼저 샌드박스에서 증명하세요.
엔티티별 PII 오버라이드, 커스텀 엔티티, LLM judge, 그리고 컨텍스트 그라운딩 필드는 Guardrails의 심층 레퍼런스를 참조하세요.

​
8. 관련 레퍼런스

Firewall API

액션 평면 동료 — /api/workspace/firewall/*와 게이트웨이 라우트.

Compliance API

/api/compliance/* — 팩, 서명 리포트, 거주지, 준비도.

오류 코드

모든 *_blocked 코드, 그 HTTP 상태, 그리고 어떻게 대응할지.

Guardrails (심층)

규칙 유형, PII 엔티티, 프리셋, eval, 그리고 matches 피드 전체.
Guardrails vs Firewall, OrcaRouter가 트래픽을 검사하는 방식, 그리고 용어집도 참조하세요.