Skip to main content

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.

New integrations should use the Guardrails API. The endpoints documented below remain available for accounts that still rely on the legacy set shape.
The legacy API groups multiple guardrails together into a named set that is attached to a persona via guardrails_id. The endpoints on this page use the same paths as the new individual API — the server discriminates between the two surfaces based on the request body shape (for POST) or the UUID type (for GET, PATCH, DELETE).

​
Create guardrail set

POST /v2/guardrails Send a payload with name and data (an array of guardrail items) to create a legacy set. If you send guardrail_name at the top level instead, the request is routed to Create Guardrails and creates an individual guardrail. 
curl --request POST \
  --url https://tavusapi.com/v2/guardrails \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "name": "Healthcare Compliance Guardrails",
    "data": [
      {
        "guardrail_name": "no_medical_advice",
        "guardrail_prompt": "Never provide medical advice outside approved guidelines.",
        "modality": "verbal",
        "callback_url": "https://your-server.com/guardrails-webhook"
      },
      {
        "guardrail_name": "check_if_alone",
        "guardrail_prompt": "Confirm throughout the call that the participant is alone.",
        "modality": "visual"
      }
    ]
  }'
Response 
{
  "guardrails_id": "g12345",
  "guardrails_name": "Healthcare Compliance Guardrails",
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z"
}
Attach the returned guardrails_id to a persona via guardrails_id on Create Persona.

​
List guardrail sets

GET /v2/guardrails?legacy=true legacy=true is the default, so omitting the parameter returns the legacy set list. Pass legacy=false to get a flat list of individual guardrails instead. 
curl --request GET \
  --url 'https://tavusapi.com/v2/guardrails?legacy=true' \
  --header 'x-api-key: <api-key>'

​
Get guardrail set

GET /v2/guardrails/{guardrails_id} When the supplied UUID is a legacy set UUID, the response returns the set shape: 
{
  "uuid": "g12345",
  "name": "Healthcare Compliance Guardrails",
  "data": [
    {
      "guardrail_name": "no_medical_advice",
      "guardrail_prompt": "Never provide medical advice outside approved guidelines.",
      "modality": "verbal",
      "callback_url": "https://your-server.com/guardrails-webhook"
    }
  ]
}

​
Patch guardrail set

PATCH /v2/guardrails/{guardrails_id} Send a JSON Patch array against the set document. Mirror UUIDs are preserved across field-level edits, moves, and removes; a whole-object replace /data/<i> rotates the underlying individual UUID. 
curl --request PATCH \
  --url https://tavusapi.com/v2/guardrails/g12345 \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '[
    { "op": "replace", "path": "/data/0/guardrail_prompt", "value": "Updated prompt." }
  ]'

​
Delete guardrail set

DELETE /v2/guardrails/{guardrails_id} Deletes the set and all of its mirrored individual items. Personas referencing the set via guardrails_id are scrubbed automatically. 
curl --request DELETE \
  --url https://tavusapi.com/v2/guardrails/g12345 \
  --header 'x-api-key: <api-key>'

​
Migrating to individual guardrails

The two surfaces interoperate — every guardrail item inside a legacy set is also addressable as an individual guardrail by its own uuid. To move off the legacy set shape:
  1. Stop creating new sets. Use Create Guardrails per guardrail.
  2. Attach guardrails to personas via guardrail_ids (explicit list) or guardrail_tags (tag-based, dynamic) on Create Persona instead of guardrails_id.
  3. Existing sets continue to work — personas can mix guardrails_id, guardrail_ids, and guardrail_tags during the transition.