Tavus Guardrails API
The Guardrails API from Tavus — 2 operation(s) for guardrails.
OpenAPI Specification
openapi: 3.0.3
info:
title: Tavus Developer API Collection Conversations Guardrails API
version: 1.0.0
contact: {}
servers:
- url: https://tavusapi.com
security:
- apiKey: []
tags:
- name: Guardrails
paths:
/v2/guardrails:
post:
tags:
- Guardrails
summary: Create Guardrails
description: 'This endpoint creates a new set of guardrails for a persona. Guardrails provide strict behavioral boundaries and guidelines that will be rigorously followed throughout conversations.
'
operationId: createGuardrails
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: A descriptive name for the collection of individual guardrails
data:
type: array
description: A list of individual guardrails
items:
type: object
properties:
guardrail_name:
type: string
description: A descriptive name for the guardrail. Only alphanumeric characters and underscores are allowed.
example: healthcare_compliance_guardrail
guardrail_prompt:
type: string
description: The detailed prompt that defines the behavioral boundaries and restrictions
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 will be enforced by the user's responses. If set `visual`, the guardrail can only be enforced by visual / perception cues observed by Raven
enum:
- verbal
- visual
default: verbal
example: verbal
callback_url:
type: string
description: Optional URL that will receive notifications when the guardrail is triggered
example: https://your-server.com/guardrails-webhook
required:
- guardrail_name
- guardrail_prompt
responses:
'200':
description: Guardrails created successfully
content:
application/json:
schema:
type: object
properties:
guardrails_id:
type: string
description: Unique identifier for the created guardrails
example: g12345
guardrails_name:
type: string
description: Name of the guardrails
example: Healthcare Compliance Guardrails
status:
type: string
description: Current status of the guardrails
example: active
created_at:
type: string
description: ISO 8601 timestamp of when the guardrails were created
example: '2024-01-15T10:30:00Z'
'400':
description: Bad Request - Invalid input parameters
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: Error message describing the validation failure
example: guardrail_name is required
'401':
description: UNAUTHORIZED
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message.
example: Invalid access token
security:
- apiKey: []
get:
tags:
- Guardrails
summary: Get Guardrails (All Sets)
description: 'This endpoint returns a list of all sets of guardrails.
'
operationId: getGuardrails
parameters:
- in: query
name: limit
schema:
type: integer
description: The number of guardrails to return per page. Default is 10.
- in: query
name: page
schema:
type: integer
description: The page number to return. Default is 1.
responses:
'200':
description: Successfully retrieved guardrails
content:
application/json:
schema:
type: object
properties:
data:
type: array
description: Guardrail sets for the current page; use `total_count` for the full count.
items:
type: object
properties:
guardrails_id:
type: string
description: Unique identifier for the guardrails
example: g12345
created_at:
type: string
description: ISO 8601 timestamp of when the guardrails were created
example: '2024-01-15T10:30:00Z'
updated_at:
type: string
description: ISO 8601 timestamp of when the guardrails were last updated
example: '2024-01-15T10:30:00Z'
total_count:
type: integer
description: The total number of guardrails
example: 15
'401':
description: UNAUTHORIZED
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message.
example: Invalid access token
security:
- apiKey: []
/v2/guardrails/{guardrails_id}:
parameters:
- name: guardrails_id
in: path
required: true
description: The unique identifier of the guardrails.
schema:
type: string
example: g12345
get:
tags:
- Guardrails
summary: Get Guardrails (One Set)
description: 'This endpoint returns a single set of guardrails by its unique identifier.
'
operationId: getGuardrail
responses:
'200':
description: Successfully retrieved guardrails
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
guardrail_name:
type: string
description: Name of the individual guardrail. Only alphanumeric characters and underscores are allowed.
example: healthcare_compliance_guardrail
guardrail_prompt:
type: string
description: The detailed prompt that defines the behavioral boundaries and restrictions
example: Never discuss competitor products, share sensitive medical information, or provide medical advice outside approved guidelines
modality:
type: string
description: The communication modality for an individual guardrail. If set to `verbal`, the guardrail will be enforced by the user's responses. If set `visual`, the guardrail can only be enforced by visual / perception cues observed by Raven
enum:
- verbal
- visual
default: verbal
example: verbal
callback_url:
type: string
description: URL that will receive notifications when the guardrail is triggered
example: https://your-server.com/guardrails-webhook
created_at:
type: string
description: ISO 8601 timestamp of when the guardrails were created
example: '2024-01-15T10:30:00Z'
updated_at:
type: string
description: ISO 8601 timestamp of when the guardrails were last updated
example: '2024-01-15T10:30:00Z'
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: The error message.
example: Invalid guardrails_id
'401':
description: UNAUTHORIZED
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message.
example: Invalid access token
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: The error message.
example: Guardrails not found
security:
- apiKey: []
patch:
tags:
- Guardrails
summary: Patch Guardrails
description: This endpoint allows you to update specific fields of guardrails using JSON Patch operations.
operationId: patchGuardrails
requestBody:
content:
application/json:
schema:
type: array
items:
type: object
properties:
op:
type: string
description: 'The operation to perform. Must be one of: add, remove, replace, copy, move, test'
enum:
- add
- remove
- replace
- copy
- move
- test
example: replace
path:
type: string
description: 'JSON Pointer (RFC 6901) to a location in the guardrails document. Paths must match the **current** document shape—compare the response from [Get Guardrails](/api-reference/guardrails/get-guardrails) (`GET /v2/guardrails/{guardrails_id}`) before patching.
'
example: /guardrail_name
value:
description: The value to be used within the operation. **This field is not required for the `remove` operation**.
example: Updated Compliance Guardrails
required:
- op
- path
examples:
Update Guardrails Name:
value:
- op: replace
path: /data/0/guardrail_name
value: updated_compliance_guardrails
Update Guardrails Prompt:
value:
- op: replace
path: /data/0/guardrail_prompt
value: Updated prompt with new restrictions
Remove Callback URL:
value:
- op: remove
path: /data/0/callback_url
responses:
'200':
description: Guardrails updated successfully
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: Success message
example: Guardrails updated successfully
'304':
description: No changes were made to the guardrails
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: The error message.
example: Invalid patch operation
'401':
description: UNAUTHORIZED
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message.
example: Invalid access token
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: The error message.
example: Guardrails not found
security:
- apiKey: []
delete:
tags:
- Guardrails
summary: Delete Guardrails
description: 'This endpoint deletes a single set of guardrails by its unique identifier.
'
operationId: deleteGuardrails
responses:
'204':
description: NO CONTENT - Guardrails deleted successfully
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: The error message.
example: Invalid guardrails_id
'401':
description: UNAUTHORIZED
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message.
example: Invalid access token
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: The error message.
example: Guardrails not found
security:
- apiKey: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key