---
title: "Create Guardrails"
method: POST
path: "/v2/guardrails"
tags: ["Guardrails"]
---

# Create Guardrails

`POST /v2/guardrails`

Create a new guardrail. Guardrails provide strict behavioral boundaries that are enforced throughout a conversation.

Attach guardrails to a PAL directly via `guardrail_ids` or by tag via `guardrail_tags` on [Create PAL](/api-reference/pals/create-pal).

<Note>
See [Deprecated guardrail sets](/api-reference/guardrails/legacy-guardrail-sets).
</Note>

## Request body

- object
  - `guardrail_name` string, required — A descriptive name for the guardrail. Only alphanumeric characters and underscores are allowed. Maximum 100 characters.
  - `guardrail_prompt` string, required — The detailed prompt that defines the behavioral boundaries and restrictions. Keep this short and direct for best enforcement. Maximum 1,000 characters.
  - `modality` 'verbal' | 'visual' — The communication modality for the guardrail. If set to `verbal`, the guardrail is enforced against the participant's spoken/typed responses. If set to `visual`, the guardrail is enforced against visual/perception cues observed by Raven.
  - `callback_url` string — Optional URL that will receive a notification when the guardrail is triggered during a conversation. Maximum 2,048 characters.
  - `tags` string[] — Optional tags for organizing guardrails and for attaching them to PALs in bulk via `guardrail_tags` on [Create PAL](/api-reference/pals/create-pal). Up to 32 tags per guardrail. Tag names are limited to 64 characters.
  - `app_message` boolean — Whether triggering this guardrail emits a real-time app-message event on the conversation. Default `true`. Set to `false` to suppress the in-conversation event for guardrails you only want to observe server-side via `callback_url`.

## Response `200`

Guardrail created successfully

- object
  - `uuid` string — Unique identifier for the created guardrail. Use this value in `guardrail_ids` on a PAL.
  - `guardrail_name` string
  - `guardrail_prompt` string
  - `modality` 'verbal' | 'visual'
  - `callback_url` string
  - `tags` string[]
  - `app_message` boolean — Whether triggering this guardrail emits a real-time app-message event on the conversation.
  - `created_at` string
  - `updated_at` string

## Other responses

- `400` — Bad Request - Invalid input parameters
- `401` — UNAUTHORIZED

---

[API](https://skmtc.dev/tavus/apis/tavus-developer-api-collection.md) · [All operations](https://skmtc.dev/tavus/apis/tavus-developer-api-collection/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/tavus/tavus-developer-api-collection/revisions/c878e2f6508d/schema)