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