---
title: "Record Guardrail Definition"
method: POST
path: "/api/v1/hooks/guardrails"
tags: ["hooks"]
---

# Record Guardrail Definition

`POST /api/v1/hooks/guardrails`

## Request

- The document declares no server URL.
- Auth: one of:
  - API key in header `Otari-Key`
  - API key in header `x-api-key`

Keep one version of an agent guardrail, so the gate spans that name it can say what each gate is for.

`otari hook` sends this once per version, the first time it reports a check
against it. The fingerprint is recomputed from the gates, and one that does
not match the one sent is refused, so a version cannot be stored under
another's name. Sending a version again changes nothing. It is stored in the
API key's workspace, beside that key's traces, and takes the same key a trace
export does: a budget-exempt API key, never the master key.

## Request body

- GuardrailDefinitionRequest
  - `digest` string, required
  - `gates` GateDefinitionRequest[], required
    - `enforcement` 'required' | 'advisory', required
    - `gate_id` string, required
    - `gate_type` 'command' | 'command_if_changed' | 'judge' | 'path' | 'verifier', required
    - `message` string, required
    - `origin` 'repo' | 'user', required
    - `runs` string[], required

## Response `200`

Successful Response

- GuardrailDefinitionResponse
  - `digest` string, required

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-22** `cb6a979aecf1`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/mozilla-ai/apis/otari/changes/api/v1/hooks/guardrails/post.md)

---

[API](https://skmtc.dev/mozilla-ai/apis/otari.md) - [All operations](https://skmtc.dev/mozilla-ai/apis/otari/llms.txt) - [OpenAPI document](https://skmtc.dev/mozilla-ai/apis/otari/revisions/42276d3c251d?raw)