> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tavus.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Guardrails

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

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

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


<Info>
  For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract.
</Info>


## OpenAPI

````yaml post /v2/guardrails
openapi: 3.0.3
info:
  title: Tavus Developer API Collection
  version: 1.0.0
  contact: {}
servers:
  - url: https://tavusapi.com
security:
  - apiKey: []
tags:
  - name: Videos
  - name: Replicas
  - name: Voices
  - name: Conversations
  - name: Personas
  - name: Pronunciation Dictionaries
  - name: Replacements
  - name: Transcriptions
  - name: Documents
paths:
  /v2/guardrails:
    post:
      tags:
        - Guardrails
      summary: Create Guardrails
      description: >
        Create a new guardrail. Guardrails provide strict behavioral boundaries
        that are enforced throughout a conversation.


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


        <Note>

        See [Legacy guardrail
        sets](/api-reference/guardrails/legacy-guardrail-sets).

        </Note>
      operationId: createGuardrails
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                guardrail_name:
                  type: string
                  maxLength: 100
                  description: >-
                    A descriptive name for the guardrail. Only alphanumeric
                    characters and underscores are allowed. Maximum 100
                    characters.
                  example: healthcare_compliance_guardrail
                guardrail_prompt:
                  type: string
                  maxLength: 1000
                  description: >-
                    The detailed prompt that defines the behavioral boundaries
                    and restrictions. Keep this short and direct for best
                    enforcement. Maximum 1,000 characters.
                  example: >-
                    Never discuss competitor products, share sensitive medical
                    information, or provide medical advice outside approved
                    guidelines.
                modality:
                  type: string
                  description: >-
                    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.
                  enum:
                    - verbal
                    - visual
                  default: verbal
                  example: verbal
                callback_url:
                  type: string
                  maxLength: 2048
                  description: >-
                    Optional URL that will receive a notification when the
                    guardrail is triggered during a conversation. Maximum 2,048
                    characters.
                  example: https://your-server.com/guardrails-webhook
                tags:
                  type: array
                  maxItems: 32
                  description: >-
                    Optional tags for organizing guardrails and for attaching
                    them to personas in bulk via `guardrail_tags` on [Create
                    Persona](/api-reference/personas/create-persona). Up to 32
                    tags per guardrail. Tag names are limited to 64 characters.
                  items:
                    type: string
                    maxLength: 64
                  example:
                    - compliance
                    - healthcare
                app_message:
                  type: boolean
                  description: >-
                    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`.
                  default: true
                  example: true
              required:
                - guardrail_name
                - guardrail_prompt
            examples:
              minimal:
                summary: Required fields only
                value:
                  guardrail_name: no_competitors
                  guardrail_prompt: >-
                    Only mention products within Our Company Inc. during
                    conversations; never discuss competitors.
              with_tags:
                summary: Guardrail with tags for tag-based attachment
                value:
                  guardrail_name: healthcare_compliance
                  guardrail_prompt: >-
                    Never share sensitive medical information or provide medical
                    advice outside approved guidelines.
                  modality: verbal
                  callback_url: https://your-server.com/guardrails-webhook
                  tags:
                    - compliance
                    - healthcare
      responses:
        '200':
          description: Guardrail created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  uuid:
                    type: string
                    description: >-
                      Unique identifier for the created guardrail. Use this
                      value in `guardrail_ids` on a persona.
                    example: g1234567890ab
                  guardrail_name:
                    type: string
                    example: healthcare_compliance_guardrail
                  guardrail_prompt:
                    type: string
                    example: >-
                      Never share sensitive medical information or provide
                      medical advice outside approved guidelines.
                  modality:
                    type: string
                    enum:
                      - verbal
                      - visual
                    example: verbal
                  callback_url:
                    type: string
                    example: https://your-server.com/guardrails-webhook
                  tags:
                    type: array
                    items:
                      type: string
                    example:
                      - compliance
                      - healthcare
                  app_message:
                    type: boolean
                    description: >-
                      Whether triggering this guardrail emits a real-time
                      app-message event on the conversation.
                    example: true
                  created_at:
                    type: string
                    example: '2024-01-15T10:30:00Z'
                  updated_at:
                    type: string
                    example: '2024-01-15T10:30:00Z'
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: guardrail_name is required
        '401':
          description: UNAUTHORIZED
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Invalid access token
      security:
        - apiKey: []
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key

````