Skip to main content
POST
/
v2
/
guardrails
curl --request POST \
  --url https://tavusapi.com/v2/guardrails \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "guardrail_name": "no_competitors",
  "guardrail_prompt": "Only mention products within Our Company Inc. during conversations; never discuss competitors."
}
'
{
  "uuid": "g1234567890ab",
  "guardrail_name": "healthcare_compliance_guardrail",
  "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"
  ],
  "app_message": true,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

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.

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

Authorizations

​
x-api-key
string
header
required

Body

application/json
​
guardrail_name
string
required

A descriptive name for the guardrail. Only alphanumeric characters and underscores are allowed. Maximum 100 characters.

Maximum string length: 100
Example:

"healthcare_compliance_guardrail"

​
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.

Maximum string length: 1000
Example:

"Never discuss competitor products, share sensitive medical information, or provide medical advice outside approved guidelines."

​
modality
enum<string>
default:verbal

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.

Available options:
verbal,
visual
Example:

"verbal"

​
callback_url
string

Optional URL that will receive a notification when the guardrail is triggered during a conversation. Maximum 2,048 characters.

Maximum string length: 2048
Example:

"https://your-server.com/guardrails-webhook"

​
tags
string[]

Optional tags for organizing guardrails and for attaching them to personas in bulk via guardrail_tags on Create Persona. Up to 32 tags per guardrail. Tag names are limited to 64 characters.

Maximum array length: 32
Maximum string length: 64
Example:
["compliance", "healthcare"]
​
app_message
boolean
default:true

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.

Example:

true

Response

Guardrail created successfully

​
uuid
string

Unique identifier for the created guardrail. Use this value in guardrail_ids on a persona.

Example:

"g1234567890ab"

​
guardrail_name
string
Example:

"healthcare_compliance_guardrail"

​
guardrail_prompt
string
Example:

"Never share sensitive medical information or provide medical advice outside approved guidelines."

​
modality
enum<string>
Available options:
verbal,
visual
Example:

"verbal"

​
callback_url
string
Example:

"https://your-server.com/guardrails-webhook"

​
tags
string[]
Example:
["compliance", "healthcare"]
​
app_message
boolean

Whether triggering this guardrail emits a real-time app-message event on the conversation.

Example:

true

​
created_at
string
Example:

"2024-01-15T10:30:00Z"

​
updated_at
string
Example:

"2024-01-15T10:30:00Z"