Перейти к основному содержанию
Когда вы хотите управлять guardrails как кодом — создать PII-политику в CI, сравнить две версии перед релизом или подтянуть ленту совпадений в свой собственный дашборд — вы обращаетесь к маршрутам /api/guardrail/*. Эта страница — справочник guardrail api маршрут за маршрутом: каждый эндпоинт, роль рабочего пространства, которую он требует, и аутентификация, которую он ожидает. О том, что guardrail есть и как составляются правила, читайте Guardrails. Эта страница — спутник на уровне провода.

​
1. Аутентификация и область

Каждый маршрут /api/guardrail/* — это плоскость управления: он аутентифицируется вашей консольной сессией или access-токеном (та же идентичность, с которой вы логинитесь в консоль), а не relay-ключом.
Ваш relay-ключ sk-orca-... аутентифицирует вызовы модели /v1/* — он не работает на /api/guardrail/*. Маршруты конфигурации используют ваш пользовательский session/access-токен, ограниченный активным рабочим пространством.
  • Маршруты ограничены рабочим пространством — они видят только guardrails активного рабочего пространства. Ничего не пересекает границу арендатора.
  • Каждый маршрут защищён RBAC вашей ролью рабочего пространства (Viewer / Developer / Admin / Owner). Чтения открыты Viewer+; песочница и все записи требуют Developer+; эндпоинты ложных срабатываний требуют Admin (Admin или Owner).
Большинство команд никогда не вызывают эти маршруты напрямую — консоль управляет ими всеми. Тянитесь к REST-поверхности, когда хотите guardrails в системе контроля версий, в CI или подключёнными к своему собственному инструментарию.

​
2. Один конкретный вызов — список ваших guardrails

Чтение — простейшее место для старта. Аутентифицированы как любой участник рабочего пространства (Viewer+): 
curl https://api.orcarouter.ai/api/guardrail/ \
  -H "Authorization: Bearer <your-access-token>" \
  -H "X-Workspace-Id: <workspace-id>"
Вы получаете обратно guardrails рабочего пространства со счётчиками привязанных ключей. Чтобы вместо этого проверить свой первый запрос от начала до конца — создать политику, привязать ключ, отправить вызов — следуйте быстрому старту из 5 шагов, который делает всё из консоли.

​
3. Ролевая модель в одной таблице

Действие, которое вы предпринимаете, а не маршрут, выбирает уровень.
ДействиеМинимальная роль
Чтение (список/получение, история, совпадения, прогоны эвалов), запуск эвалаViewer+
Запуск sandbox-теста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+
Прогоните guardrail по встроенному red-team корпусу или кастомному 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
Совпадение записывает тип правила, действие, стадию и строку детали — плюс совпавшую подстроку только если для этого guardrail включён “Log raw content” (по умолчанию выключено). Маршруты чтения не несут дополнительной middleware разрешений, так что любой активный участник рабочего пространства может до них достучаться; два маршрута mark-fp — только для Admin (Admin или Owner) и rate-limited.

​
5. Разрешение: какой guardrail применяется

Маршруты выше управляют политиками; разрешение решает, какая из них работает на данном relay-вызове. Это модель явный-или-default без молчаливого отката на явной привязке:
  1. Явный guardrail_id на ключе → этот guardrail применяется, если он существует и включён. Выключенная привязка — это выключатель: она не откатывается.
  2. Нет привязки → включённый default-guardrail рабочего пространства (is_default).
  3. Ни то, ни другое → нет применения. Запрос побайтно идентичен рабочему пространству, которое никогда не включало эту функцию.
Это единственное поведение, которое отличается от Firewall: выключенная привязанная политика firewall откатывается к default’у рабочего пространства, тогда как выключенный привязанный guardrail разрешается в none. См. Guardrails против Firewall.
Задайте guardrail_id на ключе через редактор ключей или token API; 0/null означает «нет явной привязки».

​
6. Что возвращает блокировка

Когда срабатывает правило с действием block, relay-вызов (/v1/*, на вашем relay-ключе) — а не эти маршруты управления — возвращает:
ПолеЗначение
HTTP-статус400
Код ошибкиguardrail_blocked
Стоимость квотыблокировка на стадии входа срабатывает до предварительного списания, так что квота не тарифицируется
Повторпомечено skip-retry
Сообщение называет guardrail и сработавшее правило. Для полного каталога кодов и путей разбора см. Коды ошибок и Почему мой запрос был заблокирован?.

​
7. Действия, стадии и типы правил с первого взгляда

Маршрут meta возвращает их как enum’ы; здесь они для быстрой справки.
  • Действия: block (отклонить, HTTP 400), mask (отредактировать совпадение, переслать очищенный текст), flag (только лог — наблюдать без изменения трафика), annotate (неблокирующее — записать совпадение и вставить человекочитаемую заметку вверх по потоку, так что модели сообщают о нём до ответа), spotlight (неблокирующее — обернуть совпавший недоверенный фрагмент в разделители и сказать модели обращаться с ним как с данными, а не инструкциями; защита от prompt-injection, на практике на стадии входа).
  • Стадии: input (запрос), output (ответ модели) или both.
  • Типы правил: keyword, regex, pii, max_chars, external, llm_judge, grounding.
Правила стадии выхода применяются на обоих — потоковых и непотоковых — ответах: block обрезает поток, а mask переписывает совпавшие фрагменты в полосе по мере того, как текут чанки. В потоке уже отправленные байты нельзя отозвать, так что совпадение обрабатывается, только когда достаточная его часть забуферизирована — для самой сильной гарантии сканируйте на стадии input, которая очищает запрос до того, как модель его увидит. Сначала докажите вашу точную комбинацию стадии/потока в песочнице.
О per-entity override’ах PII, кастомных сущностях, LLM-судье и полях контекстного grounding см. глубокий справочник в Guardrails.

​
8. Сопутствующие справочники

Firewall API

Собрат на плоскости действий — /api/workspace/firewall/* и маршруты шлюза.

Compliance API

/api/compliance/* — паки, подписанные отчёты, резидентность, готовность.

Коды ошибок

Каждый код *_blocked, его HTTP-статус и что с ним делать.

Guardrails (глубокое погружение)

Типы правил, PII-сущности, пресеты, эвалы и лента совпадений целиком.
См. также Guardrails против Firewall, Как OrcaRouter инспектирует трафик и Глоссарий.