Deprecated guardrail sets

New integrations should use the Guardrails API. The endpoints documented below remain available for accounts that still rely on the deprecated set shape.

The deprecated API groups multiple guardrails together into a named set that is attached to a PAL 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 deprecated 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 PAL via guardrails_id on Create PAL.

List guardrail sets

GET /v2/guardrails?legacy=true legacy=true is the default, so omitting the parameter returns the deprecated 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 deprecated 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. PALs 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 deprecated set is also addressable as an individual guardrail by its own uuid. To move off the deprecated set shape:

Stop creating new sets. Use Create Guardrails per guardrail.
Attach guardrails to PALs via guardrail_ids (explicit list) or guardrail_tags (tag-based, dynamic) on Create PAL instead of guardrails_id.
Existing sets continue to work - PALs can mix guardrails_id, guardrail_ids, and guardrail_tags during the transition.

⌘I

Introduction

Conversation

PAL

Face

Tools

Skills

Magic Canvas

Objectives

Guardrails

Knowledge Base

Pronunciation Dictionaries

Voices

Deployments

Deprecated guardrail sets

Create guardrail set

List guardrail sets

Get guardrail set

Patch guardrail set

Delete guardrail set

Migrating to individual guardrails

​Create guardrail set

​List guardrail sets

​Get guardrail set

​Patch guardrail set

​Delete guardrail set

​Migrating to individual guardrails

Create guardrail set

List guardrail sets

Get guardrail set

Patch guardrail set

Delete guardrail set

Migrating to individual guardrails