openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com paths: /v2/lipsync: post: tags: - Lipsync summary: Create Lipsync deprecated: true description: | This endpoint is no longer supported by Tavus. Create a new lipsync video by providing a video URL and an audio URL. The service will synchronize the speaker's mouth movements with the provided audio. operationId: createLipsync requestBody: content: application/json: schema: type: object properties: original_video_url: type: string description: "A direct link to the video that will be modified. This should be a publicly accessible / presigned S3 URL." example: "https://example.com/video.mp4" source_audio_url: type: string description: "A direct link to the audio file that will be synchronized with the video. This should be a publicly accessible / presigned S3 URL." example: "https://example.com/audio.mp3" lipsync_name: type: string description: "An optional name for the lipsync video." example: "My Lipsync Video" callback_url: type: string description: "A url that will receive a callback on completion of the lipsync or on error." example: "https://your-callback-url.com" required: - original_video_url - source_audio_url responses: "200": description: "" content: application/json: schema: type: object properties: lipsync_id: type: string description: "A unique identifier for the lipsync request." example: "wf85407a7ba9d" lipsync_name: type: string nullable: true description: "The name of the lipsync request." example: "My Lipsync Video" status: type: string description: "The status of the lipsync request." example: "started" callback_url: type: string description: "The callback URL that will receive notifications about the lipsync request." example: "https://your-callback-url.com" request_id: type: string description: "Legacy field - will be removed soon. Use lipsync_id instead." example: "wf85407a7ba9d" request_name: type: string description: "Legacy field - will be removed soon. Use lipsync_name instead." example: "My Lipsync Video" "400": description: "Bad Request" content: application/json: schema: type: object properties: error: type: string description: "The error message." example: "Invalid original_video_url" "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: - Lipsync summary: List Lipsyncs deprecated: true description: | This endpoint is no longer supported by Tavus. This endpoint returns a list of all Lipsyncs created by the account associated with the API Key in use. operationId: listLipsyncs parameters: - in: query name: limit schema: type: integer description: "The number of lipsyncs 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: "" content: application/json: schema: type: object properties: data: type: array items: type: object properties: lipsync_id: type: string description: "A unique identifier for the lipsync request." example: "w0108f2d24k2a" lipsync_name: type: string description: "The name of the lipsync video." example: "My Lipsync Video" status: type: string description: "The status of the lipsync request. Can be either `started`, `completed`, or `error`." created_at: type: string description: "The date and time the lipsync request was created." video_url: type: string description: "The URL to download the completed lipsync video." example: "https://lipsync-prod.s3.amazonaws.com/l0108f2d24k2a.mp4" request_id: type: string description: "Legacy field - will be removed soon. Use lipsync_id instead." example: "w0108f2d24k2a" request_name: type: string description: "Legacy field - will be removed soon. Use lipsync_name instead." example: "My Lipsync Video" total_count: type: integer description: "The total number of lipsync videos that fit the query." "401": description: "UNAUTHORIZED" content: application/json: schema: type: object properties: message: type: string description: "The error message." example: "Invalid access token" security: - apiKey: [] /v2/lipsync/{lipsync_id}: get: tags: - Lipsync summary: Get Lipsync deprecated: true description: | This endpoint is no longer supported by Tavus. This endpoint returns a single lipsync by its unique identifier. operationId: getLipsync parameters: - in: path name: lipsync_id required: true schema: type: string description: "A unique identifier for the lipsync request." responses: "200": description: "" content: application/json: schema: type: object properties: lipsync_id: type: string description: "A unique identifier for the lipsync request." example: "w0108f2d24k2a" lipsync_name: type: string description: "The name of the lipsync video." example: "My Lipsync Video" status: type: string description: "The status of the lipsync request." created_at: type: string description: "The date and time the lipsync request was created." video_url: type: string description: "The URL to download the completed lipsync video." example: "https://lipsync-prod.s3.amazonaws.com/l0108f2d24k2a.mp4" request_id: type: string description: "Legacy field - will be removed soon. Use lipsync_id instead." example: "w0108f2d24k2a" request_name: type: string description: "Legacy field - will be removed soon. Use lipsync_name instead." example: "My Lipsync Video" "400": description: "Bad Request" content: application/json: schema: type: object properties: error: type: string description: "The error message." example: "Invalid lipsync_id" "401": description: "UNAUTHORIZED" content: application/json: schema: type: object properties: message: type: string description: "The error message." example: "Invalid access token" security: - apiKey: [] delete: tags: - Lipsync summary: Delete Lipsync deprecated: true description: | This endpoint is no longer supported by Tavus. This endpoint deletes a single lipsync by its unique identifier. operationId: deleteLipsync parameters: - in: path name: lipsync_id required: true schema: type: string example: "w4ed23359d415" description: "A unique identifier for the lipsync request." responses: "204": description: "OK" "400": description: "Bad Request" content: application/json: schema: type: object properties: error: type: string description: "The error message." example: "Invalid lipsync_id" "401": description: "UNAUTHORIZED" content: application/json: schema: type: object properties: message: type: string description: "The error message." example: "Invalid access token" security: - apiKey: [] /v2/replacements: post: tags: - Replacements summary: Create Replacement deprecated: true description: | This endpoint is no longer supported by Tavus. This endpoint creates a test word replacement request that will modify specific words or phrases in an existing video. operationId: createReplacement requestBody: content: application/json: schema: type: object properties: original_video_url: type: string description: "A direct link to the video that will be modified. This should be a publicly accessible / presigned S3 URL." example: "https://example.com/video.mp4" transcription_id: type: string example: "t0108f2d24k2a" description: "A unique identifier for the transcription." new_transcript: type: string example: "Hello John, I'm excited to show you our new product!" description: "The new text that will replace the old text in the video. This should be an edited version of the text returned from the transcription service (referenced by transcription_id). Both the original transcription and this new text are used to identify which words to replace." callback_url: type: string description: "A url that will receive a callback on completion of the replacement or on error." example: "https://your-callback-url.com" replacement_name: type: string description: "An optional name for the replacement." example: "My First Replacement" required: - original_video_url - new_transcript responses: "200": description: "" content: application/json: schema: type: object properties: replacement_id: type: string example: "w0108f2d24k2a" description: "A unique identifier for the replacement." status: type: string description: "The status of the replacement." created_at: type: string description: "The date and time the replacement was created." security: - apiKey: [] get: tags: - Replacements summary: List Replacements deprecated: true description: | This endpoint is no longer supported by Tavus. This endpoint returns a list of all Replacements created by the account associated with the API Key in use. operationId: listReplacements parameters: - in: query name: limit schema: type: integer description: "The number of replacements 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: "" content: application/json: schema: type: object properties: data: type: array items: type: object properties: replacement_id: type: string description: "A unique identifier for the replacement." example: "w0108f2d24k2a" replacement_name: type: string description: "The name of the replacement." example: "My First Replacement" status: type: string description: "The status of the replacement. Can be either `started`, `completed`, or `error`." created_at: type: string description: "The date and time the replacement was created." total_count: type: integer description: "The total number of replacements that fit the query." security: - apiKey: [] /v2/replacements/{replacement_id}: get: tags: - Replacements summary: Get Replacement deprecated: true description: | This endpoint is no longer supported by Tavus. This endpoint returns a single replacement by its unique identifier. operationId: getReplacement parameters: - in: path name: replacement_id required: true schema: type: string description: "A unique identifier for the replacement." responses: "200": description: "" content: application/json: schema: type: object properties: replacement_id: type: string example: "w0108f2d24k2a" description: "A unique identifier for the replacement." replacement_name: type: string description: "The name of the replacement." status: type: string description: "The status of the replacement." created_at: type: string description: "The date and time the replacement was created." security: - apiKey: [] delete: tags: - Replacements summary: Delete Replacement deprecated: true description: | This endpoint is no longer supported by Tavus. This endpoint deletes a single replacement by its unique identifier. operationId: deleteReplacement parameters: - in: path name: replacement_id required: true schema: type: string description: "A unique identifier for the replacement." responses: "204": description: "" security: - apiKey: [] /v2/videos: get: tags: - Videos summary: List Videos description: | This endpoint returns a list of all Videos created by the account associated with the API Key in use. operationId: listVideos parameters: - in: query name: limit schema: type: integer description: "The number of videos to return per page. Default is 10." - in: query name: page schema: type: integer description: "The page number to return (0-indexed). Default is 0 (first page)." responses: "200": description: "" content: application/json: schema: type: object properties: data: type: array description: "Videos for the current page; use `total_count` for the full count under the applied filters." items: type: object properties: video_id: type: string description: "A unique identifier for the video." example: "783537ef5" video_name: type: string description: "A name for the video." example: "My First Video" status: type: string description: "The status of the video. Possible values: queued, generating, ready, deleted, error." example: "generating" data: type: object properties: script: type: string description: "The script that was initially used to generate the video." example: "Hello from Tavus! Enjoy your new replica" download_url: type: string description: "A link to download the video." example: "" hosted_url: type: string description: "A link to view the video." stream_url: type: string description: "A link to stream the video." example: "" status_details: type: string description: "A detailed status of the video." example: "" background_url: type: string description: "A link to a website. This will be used as the background for the video. The website must be publicly accessible and properly formed." example: "" background_source_url: type: string description: "A direct link to a video that is publicly accessible via a storage location such as an S3 bucket. This will be used as the background for the video. The video must be publicly accessible." example: "" still_image_thumbnail_url: type: string description: "A link to a still image that is a thumbnail of the video." example: "" gif_thumbnail_url: type: string description: "A link to a gif that is a thumbnail of the video." example: "" error_details: type: string description: "If the video has an error, this will contain the error message." example: "" total_count: type: integer description: "The total number of videos given the filters provided." "401": description: "UNAUTHORIZED" content: application/json: schema: type: object properties: message: type: string description: "The error message." example: "Invalid access token" security: - apiKey: [] post: tags: - Videos summary: Generate Video description: | This endpoint generates a new video using a Replica and either a script or an audio file. operationId: generateVideo requestBody: description: | The only required body parameters are `replica_id` and either `script` or `audio_url`. If a `background_url` is provided, Tavus records the website and uses it as the background. If a `background_source_url` is provided (for example a presigned S3 URL to a video), that video is used as the background. If neither is provided, the video is full-screen replica only. To learn more about generating videos with Replicas, see [here](/sections/video/quickstart). To learn more about writing an effective script for your video, see [Scripting prompting](/sections/troubleshooting#script-length). content: application/json: schema: type: object properties: replica_id: type: string description: "A unique identifier for the replica that will be used to generate the video." example: "r90bbd427f71" video_name: type: string description: "A name for the video." example: "My First Video" background_url: type: string description: "A link to a website. This will be used as the background for the video. The website must be publicly accessible and properly formed." example: "https://yourwebsite.com/" background_source_url: type: string description: "A direct link to a video that is publicly accessible via a storage location such as an S3 bucket. This will be used as the background for the video. The video must be publicly accessible." example: "https://my-example-bucket.s3.us-east-1.amazonaws.com/your-background-video.mp4" callback_url: type: string description: "A url that will receive a callback on completion of video generation or on error." example: "https://yourwebsite.com/webhook" fast: type: boolean description: "If set to true, the video will be generated using a barebones fast rendering process. This will result in a faster generation of the video but some features will be disabled. Features such as background generation, thumbnail images, and streaming urls are not supported when using this fast rendering process." example: false transparent_background: type: boolean description: | If set to true, the generated video will be a `.webm` video with a transparent background. Please note that this feature only works if the `fast` parameter is set to `true`. example: false watermark_image_url: type: string description: "A direct link to a image that is publicly accessible via a storage location such as an S3 bucket. This will be used as the watermark on the video. Currently, it support `png` & `jpeg` formats only. Ensure the image is publicly accessible." example: https://s3.amazonaws.com/watermark.png properties: type: object properties: background_scroll: type: boolean description: | If `background_url` is provided, this option may be configured. If set to `true`, the background video will scroll down through the website. If set to `false`, the background video will display the top of the website. The default is `true`. example: true background_scroll_type: type: string description: | If `background_url` is provided and `background_scroll` is set to `true`, this option may be configured. This parameter defines the scroll pattern if `background_scroll` is set to `true`. There are two options: `human`, `smooth`. The `human` scroll type is the default type and mimics a human scrolling through the webpage, briefly stopping at certain intervals to give a natural appearance. The `smooth` scroll type scroll in a uniform manner all the way down the website without stopping. The default is `human`. background_scroll_depth: type: string description: | If `background_url` is provided and `background_scroll` is set to `true`, this option may be configured. This parameter defines how far down the webpage the background video will scroll. There are two options: `middle`, `bottom`. The `middle` depth option will stop scrolling once the middle of the webpage has been hit. The `bottom` will scroll the webpage all the way to the bottom of the page. The default is `middle`. background_scroll_return: type: string description: | If `background_url` is provided and `background_scroll` is set to `true`, this option may be configured. This parameter defines the scrolling behavior once the webpage has been scrolled to the depth specified by the `background_scroll_depth` parameter. There are two options: `return`, `halt`. The `return` option will scroll back up once the webpage has reached `background_scroll_depth`. The `halt` option will pause the background video at the location specified in `background_scroll_depth`. The default is `return`. start_with_wave: type: boolean description: | If set to true, the video will start with a wave animation. This is only supported for select stock replicas. The default is `true`. example: true required: - replica_id oneOf: - title: Generate from Text type: object properties: script: type: string description: "A text script that will be used to generate the audio in the video." example: "Hello from Tavus! Enjoy your new replica" required: - script - title: Generate from Audio File type: object properties: audio_url: type: string description: "A download link to a .wav or .mp3 file that is publicly accessible via a storage location such as an S3 bucket. This audio file will be used as the audio for the generated video." required: - audio_url examples: Generate Video: value: background_url: "https://yourwebsite.com/" replica_id: "r90bbd427f71" script: "Hi, this is my first video." video_name: "My First Video" responses: "200": description: "" content: application/json: schema: type: object properties: video_id: type: string example: "abcd123" description: "A unique identifier for the video." video_name: type: string example: "Sample Video" description: "The name of the video." status: type: string example: "queued" description: "The status of the video. Possible values: queued, generating, ready, deleted, error." hosted_url: type: string example: "https://tavus.video/abcd123" description: "A direct link to view your video once generation has completed, hosted by Tavus." created_at: type: string example: "Mon, 14 Jul 2025 09:14:24 GMT" description: "The date and time the video was created." "400": description: "Bad Request" content: application/json: schema: type: object properties: error: type: string description: "The error message." example: "Invalid replica_id" "401": description: "UNAUTHORIZED" content: application/json: schema: type: object properties: message: type: string description: "The error message." example: "Invalid access token" security: - apiKey: [] /v2/videos/{video_id}: get: tags: - Videos summary: Get Video description: | This endpoint returns a single video by its unique identifier. operationId: getVideo parameters: - in: path name: video_id required: true schema: type: string description: "A unique identifier for the video." - in: query name: verbose schema: type: boolean description: "If set to true, the response will include additional video data such as the thumbnail image and gif links." responses: "200": description: "OK" content: application/json: schema: type: object properties: video_id: type: string example: "" description: "A unique identifier for the video." video_name: type: string description: "The name of the video." status: type: string example: "ready" description: "Lifecycle status; possible values: `queued`, `generating`, `ready`, `deleted`, `error`. When `ready`, `download_url`, `stream_url`, and `hosted_url` are populated for download, stream, and viewing respectively." data: type: object properties: script: type: string description: "The script that was initially used to generate the video." download_url: type: string description: "A direct link to download your generated video (populated when `status` is `ready`)." stream_url: type: string description: "A direct link to stream your generated video (populated when `status` is `ready`)." hosted_url: type: string description: "A direct link to view your generated video, hosted by Tavus (populated when `status` is `ready`)." status_details: type: string description: "A detailed status of the video." created_at: type: string description: "The date and time the video was created." updated_at: type: string description: "The date and time of when the video was last updated." still_image_thumbnail_url: type: string description: "Included if the `verbose` query parameter is set to true. A link to an image thumbnail of the video." gif_thumbnail_url: type: string description: "Included if the `verbose` query parameter is set to true. A link to a gif thumbnail of the video." "400": description: "Bad Request" content: application/json: schema: type: object properties: error: type: string description: "The error message." example: "Invalid video_id" "401": description: "UNAUTHORIZED" content: application/json: schema: type: object properties: message: type: string description: "The error message." example: "Invalid access token" security: - apiKey: [] delete: tags: - Videos summary: Delete Video description: | This endpoint deletes a single video by its unique identifier. operationId: deleteVideo parameters: - name: video_id in: path required: true description: The unique identifier of the video generation. schema: type: string example: "8a4f94e736" - name: hard in: query schema: type: boolean example: false description: "If set to true, the video and associated assets (such as thumbnail images) will be hard deleted. CAUTION: This action is irrevocable." responses: "200": description: "" "400": description: "Bad Request" content: application/json: schema: type: object properties: error: type: string description: "The error message." example: "Invalid video_id" "401": description: "UNAUTHORIZED" content: application/json: schema: type: object properties: message: type: string description: "The error message." example: "Invalid access token" security: - apiKey: [] /v2/videos/{video_id}/name: patch: tags: - Videos summary: Rename Video description: | This endpoint renames a single video by its unique identifier. operationId: renameVideo requestBody: content: application/json: schema: type: object properties: video_name: type: string example: "Sales" required: - video_name examples: Rename Video: value: video_name: "Sales" responses: "200": description: "OK" "400": description: "Bad Request" content: application/json: schema: type: object properties: error: type: string description: "The error message." example: "Invalid video_id" "401": description: "UNAUTHORIZED" content: application/json: schema: type: object properties: message: type: string description: "The error message." example: "Invalid access token" security: - apiKey: [] parameters: - name: video_id in: path required: true description: The unique identifier of the video generation. schema: type: string example: "8a4f94e736" /v2/replicas: get: tags: - Replicas summary: List Replicas description: | This endpoint returns a list of all Replicas created by the account associated with the API Key in use. operationId: listReplicas parameters: - in: query name: limit schema: type: integer description: "The number of replicas to return per page." - in: query name: page schema: type: integer description: "The page number to return" - in: query name: verbose schema: type: boolean description: "If set to true, the response will include additional replica data such as the replica type." - in: query name: replica_type schema: type: string enum: - user - system description: "If set to user, the response will only include user replicas. If set to system, the response will only include stock replicas." - in: query name: replica_ids schema: type: string description: "A comma separated list of replica ids to filter the response by. Example: `replica_ids=r90bbd427f71`" - in: query name: model_name schema: type: string description: "Filter the list to replicas trained on a specific Phoenix model (e.g. `phoenix-3`, `phoenix-4`)." responses: "200": description: "" content: application/json: schema: type: object properties: data: type: array description: "Replicas for the current page; use `total_count` for the full count under the applied filters." items: type: object properties: replica_id: type: string example: "r90bbd427f71" description: "A unique identifier for the replica." replica_name: type: string example: "My Replica" description: "The name of the replica." thumbnail_video_url: type: string description: "A direct link to the video that will be used as the thumbnail for the replica." training_progress: type: string example: "100/100" description: "Training progress as a string (for example `100/100`)." status: type: string example: "completed" description: "Training lifecycle: `started`, `completed`, or `error`." created_at: type: string replica_type: type: string example: user' description: "If `verbose` query paramter is set to true. The type of replica. Possible values: user, system. User replicas are replicas that have been created by users. System replicas are stock Tavus replicas that anyone may use" model_name: type: string example: "phoenix-3" description: "The Phoenix model the replica was trained on (e.g. `phoenix-3`, `phoenix-4`)." total_count: type: integer description: "The total number of replicas given the filters provided." example: 42 "401": description: "UNAUTHORIZED" content: application/json: schema: type: object properties: message: type: string description: "The error message." example: "Invalid access token" security: - apiKey: [] post: tags: - Replicas summary: Create Replica description: Creates a new replica from a training video or image URL for use in conversations—see [Which training path?](/sections/replica/which-training-path) for preparation, consent, and media requirements. operationId: createReplica requestBody: content: application/json: schema: type: object properties: consent_video_url: type: string description: | Optional direct link to a **separate** video that contains only the consent statement when it is not spoken at the start of `train_video_url`. **Required** when your flow uses a standalone consent recording alongside `train_video_url` for likeness-based training from video. See [Training from a video](/sections/replica/train-with-a-video) and [consent statement requirements](/sections/troubleshooting/consent-statement) for exact wording and troubleshooting. If omitted, the opening of `train_video_url` must include the consent statement instead (see `train_video_url`). example: "https://my-example-bucket.s3.us-east-1.amazonaws.com/your-consent-video.mp4" train_video_url: type: string description: | A direct download link such as a **presigned S3 URL** or other publicly reachable file used for video-based replica training. Do not send `train_image_url` in the same request. The file must meet [training video requirements](/sections/troubleshooting/training-video-size). When you **do not** send `consent_video_url`, this training clip **must** open with the following statement (verbatim), or training will fail: > I, [FULL NAME], am currently speaking and consent Tavus to create an AI clone of me by using the audio and video samples I provide. I understand that this AI clone can be used to create videos that look and sound like me. See [consent statement requirements](/sections/troubleshooting/consent-statement) for formatting tips and troubleshooting. example: "https://my-example-bucket.s3.us-east-1.amazonaws.com/your-train-video.mp4" train_image_url: type: string description: "A direct link to a publicly accessible image used for image-to-replica training. Requires `voice_name`. Do not send `train_video_url` in the same request. See [Training from an image](/sections/replica/train-with-an-image) for image training, voice selection, and consent." example: "https://my-example-bucket.s3.us-east-1.amazonaws.com/your-train-image.png" voice_name: type: string description: "Required when `train_image_url` is set. Slug that selects the voice from an existing Tavus stock replica (case-insensitive, e.g. `anna`). If supplied with `train_video_url`, the name is still validated when present. Use [List Voices](/api-reference/voices/list-voices) to discover valid slugs; see also [example `voice_name` values](/sections/replica/train-with-an-image#example-voice-name-table)." example: "anna" auto_fix_training_image: type: boolean description: "When set to `true`, Tavus's AI Image Fixer instantly fixes any uploaded image to fit our [image requirements](/sections/replica/train-with-an-image#image-requirements), eliminating the need for editing or recapturing photos. Only applies to image-based training (`train_image_url`)." example: true callback_url: type: string description: "A url that will receive a callback on completion of replica training or on error." example: "https://yourwebsite.com/webhook" replica_name: type: string description: "A name for the replica." example: "Rio" model_name: type: string description: "The Phoenix model version used to train the replica. Defaults to `phoenix-4`; set to `phoenix-3` for the older model." example: "phoenix-4" properties: type: object properties: background_green_screen: type: boolean description: "If set to true, the replica will have a green screen background." example: false examples: Video with consent videos: value: callback_url: "https://yourwebsite.com/webhook" replica_name: "Rio" train_video_url: "https://my-example-bucket.s3.us-east-1.amazonaws.com/your-train-video.mp4" consent_video_url: "https://my-example-bucket.s3.us-east-1.amazonaws.com/your-consent-video.mp4" Non-Human Replica: value: callback_url: "https://yourwebsite.com/webhook" replica_name: "AI" train_video_url: "https://my-example-bucket.s3.us-east-1.amazonaws.com/your-train-video.mp4" Older Model Replica: value: model_name: "phoenix-3" callback_url: "https://yourwebsite.com/webhook" replica_name: "My phoenix-3 Replica" train_video_url: "https://my-example-bucket.s3.us-east-1.amazonaws.com/your-train-video.mp4" consent_video_url: "https://my-example-bucket.s3.us-east-1.amazonaws.com/your-consent-video.mp4" Image to Replica: value: callback_url: "https://yourwebsite.com/webhook" replica_name: "Image Replica" train_image_url: "https://my-example-bucket.s3.us-east-1.amazonaws.com/your-train-image.png" voice_name: "anna" auto_fix_training_image: true responses: "200": description: "" content: application/json: schema: type: object properties: replica_id: type: string example: "r90bbd427f71" description: "A unique identifier for the replica." status: type: string example: "started" description: "The status of the replica. Possible values: `started`, `completed`, `error`." "400": description: "Bad Request" content: application/json: schema: type: object properties: error: type: string description: "The error message." example: "Either train_video_url or train_image_url must be provided." "401": description: "UNAUTHORIZED" content: application/json: schema: type: object properties: message: type: string description: "The error message." example: "Invalid access token" security: - apiKey: [] /v2/replicas/{replica_id}: get: tags: - Replicas summary: Get Replica description: | This endpoint returns a single Replica by its unique identifier. operationId: getReplica parameters: - in: path name: replica_id required: true schema: type: string description: "A unique identifier for the replica." - in: query name: verbose schema: type: boolean description: "If set to true, the response will include additional replica data such as replica_type." responses: "200": description: "" content: application/json: schema: type: object properties: replica_id: type: string example: "r90bbd427f71" description: "A unique identifier for the replica." replica_name: type: string example: "My Replica" description: "The name of the replica." thumbnail_video_url: type: string description: "A direct link to the video that will be used as the thumbnail for the replica." training_progress: type: string example: "100/100" description: "Training progress as a string (for example `100/100`)." status: type: string example: "completed" description: "Training lifecycle: `started`, `completed`, or `error`. On failure, this is `error` and `error_message` is populated." created_at: type: string example: "2024-01-24T07:14:03.327Z" description: "The date and time the replica was created." updated_at: type: string example: "2024-01-24T07:14:03.327Z" description: "The date and time of when the replica was last updated." error_message: type: string nullable: true description: "When `status` is `error`, contains details about the training failure; otherwise typically null." replica_type: type: string example: user' description: "If `verbose` query paramter is set to true. The type of replica. Possible values: user, system. User replicas are replicas that have been created by users. System replicas are stock Tavus replicas that anyone may use" model_name: type: string example: "phoenix-3" description: "The Phoenix model the replica was trained on (e.g. `phoenix-3`, `phoenix-4`)." "400": description: "Bad Request" content: application/json: schema: type: object properties: error: type: string description: "The error message." example: "Invalid replica_id" "401": description: "UNAUTHORIZED" content: application/json: schema: type: object properties: message: type: string description: "The error message." example: "Invalid access token" security: - apiKey: [] delete: tags: - Replicas summary: Delete Replica description: Deletes a Replica by its unique ID; deleted replicas cannot be used in a conversation. operationId: deleteReplica parameters: - name: replica_id in: path required: true description: The unique identifier of the replica. schema: type: string example: r90bbd427f71 - name: hard in: query schema: type: boolean example: false description: "If set to true, the replica and associated assets (such as training footage) will be hard deleted. CAUTION: This action is irrevocable. Note that a hard delete of a replica does *not* delete the conversation created using said replica. See [Delete Video](https://docs.tavus.io/api-reference/video-request/delete-video) for more info." responses: "200": description: "OK" "400": description: "Bad Request" content: application/json: schema: type: object properties: error: type: string description: "The error message." example: "Invalid replica_id" "401": description: "UNAUTHORIZED" content: application/json: schema: type: object properties: message: type: string description: "The error message." example: "Invalid access token" security: - apiKey: [] /v2/replicas/{replica_id}/name: patch: tags: - Replicas summary: Rename Replica description: | This endpoint renames a single Replica by its unique identifier. operationId: renameReplica requestBody: content: application/json: schema: type: object properties: replica_name: type: string example: "Rio" required: - replica_name examples: Rename Replica: value: replica_name: "Rio" responses: "200": description: "OK" "400": description: "Bad Request" content: application/json: schema: type: object properties: error: type: string description: "The error message." example: "Invalid replica_id" "401": description: "UNAUTHORIZED" content: application/json: schema: type: object properties: message: type: string description: "The error message." example: "Invalid access token" security: - apiKey: [] parameters: - name: replica_id in: path required: true description: The unique identifier of the replica. schema: type: string example: r90bbd427f71 /v2/voices: get: tags: - Voices summary: List Voices description: | Returns available stock **`voice_name`** values and their linked **replica** metadata. When you [Create Replica](/api-reference/phoenix-replica-model/create-replica) with **`train_image_url`** (image-to-replica), **`voice_name`** is required—use this list to pick a valid slug and to preview options. operationId: getVoices parameters: - name: limit in: query description: "Page size (1–100)." schema: type: integer minimum: 1 maximum: 100 default: 10 - name: page in: query description: "Page number (1-based)." schema: type: integer minimum: 1 default: 1 - name: search in: query description: "Case-insensitive substring match on `voice_name`." schema: type: string - name: sort in: query description: "Sort `voice_name` ascending or descending." schema: type: string enum: [asc, desc] default: asc - name: tag in: query description: "If set, only voices whose replica tags include this tag name (case-insensitive)." schema: type: string responses: "200": description: "" content: application/json: schema: type: object properties: data: type: array description: "Voices for the current page; use `total_count`, `page`, and `limit` with the query parameters for pagination." items: type: object properties: voice_name: type: string description: "Slug to pass as **`voice_name`** on Create Replica (image-to-replica)." example: "anna" replica_id: type: string description: "Replica identifier associated with this voice." example: "r90bbd427f71" audio_url: type: string nullable: true description: "Optional preview URL (e.g. sample clip) when available." tags: type: array description: "Tags from the replica record (e.g. for filtering)." items: type: object properties: tag_name: type: string total_count: type: integer description: "Total rows matching filters (before pagination)." page: type: integer limit: type: integer "401": description: "UNAUTHORIZED" content: application/json: schema: type: object properties: message: type: string description: "The error message." example: "Invalid access token" security: - apiKey: [] /v2/conversations: post: tags: - Conversations description: | This endpoint starts a real-time video conversation with your AI replica, powered by a persona that allows it to see, hear, and respond like a human. operationId: createConversation requestBody: content: application/json: schema: type: object properties: replica_id: type: string description: "The unique identifier for the replica that will join the conversation. **Each request must have a valid `replica_id` value that's either directly passed in or as part of a persona**." example: "r90bbd427f71" persona_id: type: string description: | The unique identifier for the persona that the replica will use in the conversation. - **If your Persona does not have a valid `replica_id`, you must define the `replica_id` field.** - **If your Persona already has a valid `replica_id` and you provide one in the request, the `replica_id` provided in the request will be used instead of the one defined in your persona**. example: "pcb7a34da5fe" audio_only: type: boolean description: "Specifies whether the interaction should be voice-only. **This field is required if you want to create an audio-only conversation**." example: "false" callback_url: type: string description: "A url that will receive webhooks with updates regarding the conversation state." example: "https://yourwebsite.com/webhook" conversation_name: type: string description: "A name for the conversation." example: "Improve Sales Technique" conversational_context: type: string description: "Optional context that will be appended to any context provided in the persona, if one is provided." example: "I want to improve my sales techniques. Help me practice handling common objections from clients and closing deals more effectively." custom_greeting: type: string description: "An optional custom greeting that the replica will give once a participant joines the conversation." example: "Hey there!" memory_stores: type: array items: type: string description: "The memory stores to use for the conversation. The persona will have access to the existing memories in the store and will add newly made memories to the store as well. In most use cases, you will only need to pass in a single memory store." example: ["anna"] document_ids: type: array items: type: string description: "The ids of the documents that the persona will be able to access during the conversation. The `document_ids` are returned during the document creation process in the response of the [Get Document](/api-reference/documents/get-document) and the [Create Document](/api-reference/documents/create-document) endpoints." example: ["doc_1234567890"] document_retrieval_strategy: type: string description: "The strategy to use for document retrieval. Possible values: `speed`, `quality`, `balanced`. Default is `balanced`." example: "balanced" document_tags: type: array items: type: string description: "The tags of the documents that the replica will be able to access during the conversation. The tags are passed in the `document_tags` parameter of the [Create Document](/api-reference/documents/create-document) endpoint. The document tags do not have to be created explicitly, it is enough to pass in the tags during the document creation process." example: ["sales", "marketing"] test_mode: type: boolean description: "If true, the conversation will be created but the replica will not join the call. This can be used for testing the conversation creation process without incurring any costs. Additionally, the conversation will be created with a status `ended` so it does not affect concurrency limits." example: false require_auth: type: boolean description: "If true, creates a private room requiring authentication. A `meeting_token` will be returned in the response that must be used to join the conversation. Without a valid token, users will see 'You are not allowed to join this meeting.'" example: false max_participants: type: integer minimum: 2 description: "Maximum number of participants allowed in the conversation room. Must be at least 2 (the replica counts as one participant)." example: 2 properties: type: object description: "Optional properties that can be used to customize the conversation." properties: max_call_duration: type: integer description: "The maximum duration of the call in seconds. The default max_call_duration is 3600 seconds (1 hour). Once the time limit specified by this parameter has been reached, the conversation will automatically shut down." example: 3600 participant_left_timeout: type: integer description: "The duration in seconds after which the call will be automatically shut down once the last participant leaves." example: 60 participant_absent_timeout: type: integer description: "Starting from conversation creation, the duration in seconds after which the call will be automatically shut down if no participant joins the call. Default is 300 seconds (5 minutes)." example: 300 enable_recording: type: boolean description: "If true, the user will be able to record the conversation. You can find more instructions on recording [here](/sections/conversational-video-interface/quickstart/conversation-recordings#conversation-recordings)." example: true enable_closed_captions: type: boolean description: "If true, the user will be able to display closed captions (subtitles) during the conversation. You can find more instructions on displaying closed captions if you are using your custom DailyJS components [here](https://docs.daily.co/reference/daily-js/events/transcription-events#transcription-message). You need to have an [event listener](https://docs.daily.co/reference/daily-js/events) on Daily that listens for app-messages." example: true apply_greenscreen: type: boolean description: "If true, the background will be replaced with a greenscreen (RGB values: [0, 255, 155]). You can use WebGL on the frontend to make the greenscreen transparent or change its color." example: true require_auth: type: boolean description: "If true, participants must authenticate before joining the conversation. More info on private rooms [here](/sections/conversational-video-interface/conversation/customizations/private-rooms)." example: false language: type: string description: "The language of the conversation. Please provide the FULL language name, not the two letter code, or specify `multilingual` for automatic language detection. When set to `multilingual`, CVI will use STT language detection to identify the user's spoken language and respond accordingly. If you are using your own TTS voice, please ensure it supports the language you provide. If you are using a stock replica or default persona, please note that only Elevenlabs and Cartesia supported languages are available. You can find a full list of supported languages for Cartesia [here](https://docs.cartesia.ai/2024-11-13/build-with-cartesia/models#language-support), and for ElevenLabs [here](https://elevenlabs.io/languages)." example: "multilingual" recording_s3_bucket_name: type: string deprecated: true description: | **Deprecated.** Use `recording_storage` (also on `properties`) instead. The name of the S3 bucket where the recording will be stored. Existing integrations using this flat field continue to work unchanged. example: "conversation-recordings" recording_s3_bucket_region: type: string deprecated: true description: | **Deprecated.** Use `recording_storage` (also on `properties`) instead. The region of the S3 bucket where the recording will be stored. Existing integrations using this flat field continue to work unchanged. example: "us-east-1" aws_assume_role_arn: type: string deprecated: true description: | **Deprecated.** Use `recording_storage` (also on `properties`) instead. The ARN of the role that will be assumed to access the S3 bucket. Existing integrations using this flat field continue to work unchanged. example: "" recording_storage: $ref: "#/components/schemas/recording_storage_config" examples: Required Parameters Only: value: replica_id: "r90bbd427f71" persona_id: "pcb7a34da5fe" Full Customizations: value: replica_id: "r90bbd427f71" persona_id: "pcb7a34da5fe" callback_url: "https://yourwebsite.com/webhook" conversation_name: "Improve Sales Technique" conversational_context: "I want to improve my sales techniques. Help me practice handling common objections from clients and closing deals more effectively." properties: max_call_duration: 1800 participant_left_timeout: 60 participant_absent_timeout: 120 language: "multilingual" enable_closed_captions: true apply_greenscreen: true Audio Only: value: replica_id: "r90bbd427f71" persona_id: "pcb7a34da5fe" audio_only: true Private Room: value: replica_id: "r90bbd427f71" persona_id: "pcb7a34da5fe" require_auth: true Recording Storage - Amazon S3: value: replica_id: "rf4e9d9790f0" persona_id: "pcb7a34da5fe" properties: enable_recording: true recording_storage: provider: "s3" bucket_name: "conversation-recordings" bucket_region: "us-east-1" assume_role_arn: "arn:aws:iam::123456789012:role/TavusRecordingWriter" external_id: "tavus-acct-abc123" Recording Storage - Google Cloud Storage: value: replica_id: "rf4e9d9790f0" persona_id: "pcb7a34da5fe" properties: enable_recording: true recording_storage: provider: "gcs" bucket_name: "conversation-recordings" project_id: "my-gcp-project" workload_identity_provider: "projects/123456/locations/global/workloadIdentityPools/tavus-recording-pool/providers/tavus-worker" service_account_email: "tavus-recording-writer@my-gcp-project.iam.gserviceaccount.com" Recording Storage - Azure Blob Storage: value: replica_id: "rf4e9d9790f0" persona_id: "pcb7a34da5fe" properties: enable_recording: true recording_storage: provider: "azure_blob" storage_account: "myrecordingsaccount" container: "conversation-recordings" tenant_id: "11111111-2222-3333-4444-555555555555" client_id: "66666666-7777-8888-9999-000000000000" responses: "200": description: "" content: application/json: schema: type: object properties: conversation_id: type: string description: "A unique identifier for the conversation." example: "c123456" conversation_name: type: string description: "The name of the conversation." example: "A Meeting with Hassaan" conversation_url: type: string description: "A direct link to join the conversation. This link can be used to join the conversation directly or can be embedded in a website." example: "https://tavus.daily.co/c123456" status: type: string description: "The status of the conversation. Possible values: `active`, `ended`." example: "active" callback_url: type: string description: "The url that will receive webhooks with updates of the conversation state." example: "sample.com/callback" created_at: type: string description: "The date and time the conversation was created." example: "" meeting_token: type: string description: "A short-lived JWT token required to join the conversation. Only returned when `require_auth` is true. Append as `?t=TOKEN` to the conversation URL or pass to Daily SDK's join() method." example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." "400": description: "Bad Request" content: application/json: schema: type: object properties: error: type: string description: "The error message." example: "There was an error creating the conversation, please reach out to support at support@tavus.io!" "401": description: "UNAUTHORIZED" content: application/json: schema: type: object properties: message: type: string description: "The error message." example: "Invalid access token" get: tags: - Conversations summary: List Conversations description: | This endpoint returns a list of all Conversations created by the account associated with the API Key in use. operationId: listConversations parameters: - in: query name: limit schema: type: integer description: "The number of conversations to return per page. Default is 10." - in: query name: page schema: type: integer description: "The page number to return. Default is 1." - in: query name: status schema: type: string description: "Filter the conversations by status. Possible values: active, ended." responses: "200": description: "" content: application/json: schema: type: object properties: data: type: array description: "Conversations for the current page; use `total_count` for the full count under the applied filters." items: type: object properties: conversation_id: type: string description: "A unique identifier for the conversation." example: "c123456" conversation_name: type: string description: "A name for the conversation." example: "A Meeting with Hassaan" status: type: string description: "The status of the video." example: "active" conversation_url: type: string description: "A direct link to join the conversation." example: "https://tavus.daily.co/c123456" callback_url: type: string description: "The url that will receive webhooks with updates of the conversation state." example: "https://yourwebsite.com/webhook" replica_id: type: string description: "A unique identifier for the replica used to create this conversation" example: "r90bbd427f71" persona_id: type: string description: "A unique identifier for the persona used to create this conversation" example: "pcb7a34da5fe" created_at: type: string description: "The date and time the conversation was created." example: "" updated_at: type: string description: "The date and time of when the conversation was last updated." total_count: type: integer description: "The total number of conversations given the filters provided." "401": description: "UNAUTHORIZED" content: application/json: schema: type: object properties: message: type: string description: "The error message." example: "Invalid access token" security: - apiKey: [] /v2/conversations/{conversation_id}: get: tags: - Conversations summary: Get Conversation description: | This endpoint returns a single conversation by its unique identifier. operationId: getConversation parameters: - name: verbose in: query required: false schema: type: boolean default: false description: | Append `verbose=true` to the URL to receive additional event data in the response, including: - `shutdown_reason`: The reason why the conversation ended (e.g., "participant_left_timeout") - `system.replica_joined`: When the replica joined the conversation - `system.shutdown`: When and why the conversation ended - `application.transcription_ready`: The end-of-call transcript. Each entry in `properties.transcript` has `role` (`user` / `assistant` / `system` / `tool`), `content`, `timestamp` (Unix epoch float, seconds), `seconds_from_start`, `duration` (seconds, float) and `inference_id` where available. - `application.perception_analysis`: The final visual analysis of the user that includes their appearance, behavior, emotional states, and screen activities This is particularly useful as an alternative to using the `callback_url` parameter on the [create conversation](/api-reference/conversations/create-conversation) endpoint for retrieving detailed conversation data. responses: "200": description: "" content: application/json: schema: type: object properties: conversation_id: type: string example: "c123456" description: "A unique identifier for the conversation." conversation_name: type: string example: "A Meeting with Hassaan" description: "The name of the conversation." conversation_url: type: string example: "https://tavus.daily.co/c123456" description: "A direct link to join the conversation." callback_url: type: string description: "The url that will receive webhooks with updates of the conversation state." example: "https://yourwebsite.com/webhook" status: type: string description: "The status of the conversation." example: "active" replica_id: type: string description: "A unique identifier for the replica used to create this conversation" example: "r90bbd427f71" persona_id: type: string description: "A unique identifier for the persona used to create this conversation" example: "pcb7a34da5fe" created_at: type: string example: "" description: "The date and time the conversation was created." updated_at: type: string example: "" description: "The date and time of when the conversation was last updated." events: type: array nullable: true description: "When `verbose=true`, additional conversation events (e.g. shutdown, perception analysis payloads, end-of-call transcript)." items: type: object properties: event_type: type: string description: "Event name (e.g. system.replica_joined, application.transcription_ready, application.perception_analysis)." timestamp: type: string description: "ISO 8601 time of the event." properties: type: object additionalProperties: true description: "Event-specific payload when present. For `application.transcription_ready`, includes a `transcript` array of per-turn entries." examples: default: summary: Default response (verbose omitted or false) value: conversation_id: "c123456" conversation_name: "A Meeting with Hassaan" conversation_url: "https://tavus.daily.co/c123456" callback_url: "https://yourwebsite.com/webhook" status: "active" replica_id: "r90bbd427f71" persona_id: "pcb7a34da5fe" created_at: "2026-04-29T12:00:00Z" updated_at: "2026-04-29T12:05:00Z" verbose: summary: Example when verbose=true value: conversation_id: "conv_123" status: "ended" replica_id: "replica_abc" persona_id: "persona_xyz" created_at: "2026-04-29T03:45:49Z" updated_at: "2026-04-29T03:47:01Z" events: - event_type: "system.replica_joined" timestamp: "2026-04-29T03:45:53Z" - event_type: "application.transcription_ready" timestamp: "2026-04-29T03:47:00Z" properties: transcript: - role: "assistant" content: "Hi, welcome. What brought you here today?" timestamp: 1779475657.84 seconds_from_start: 0.0 duration: 2.15 inference_id: "inf_abc123" - role: "user" content: "Just testing." timestamp: 1779475684.88 seconds_from_start: 27.04 duration: 1.84 - event_type: "system.shutdown" timestamp: "2026-04-29T03:47:01Z" properties: reason: "participant_left_timeout" "400": description: "Bad Request" content: application/json: schema: type: object properties: error: type: string description: "The error message." example: "Invalid conversation_id" "401": description: "UNAUTHORIZED" content: application/json: schema: type: object properties: message: type: string description: "The error message." example: "Invalid access token" security: - apiKey: [] delete: tags: - Conversations summary: Delete Conversation description: | This endpoint deletes a single conversation by its unique identifier. operationId: deleteConversation parameters: - name: hard in: query schema: type: boolean example: true description: "If set to true, the conversation and associated assets will be hard deleted. CAUTION: This action is irrevocable." responses: "204": description: "NO CONTENT" "400": description: "Bad Request" content: application/json: schema: type: object properties: error: type: string description: "The error message." example: "Invalid conversation_id" "401": description: "UNAUTHORIZED" content: application/json: schema: type: object properties: message: type: string description: "The error message." example: "Invalid access token" security: - apiKey: [] parameters: - name: conversation_id in: path required: true description: The unique identifier of the conversation. schema: type: string example: c123456 /v2/conversations/{conversation_id}/end: post: tags: - Conversations summary: End Conversation description: | This endpoint ends a single conversation by its unique identifier. operationId: endConversation responses: "200": description: "OK" "400": description: "Bad Request" content: application/json: schema: type: object properties: error: type: string description: "The error message." example: "Invalid conversation_id" "401": description: "UNAUTHORIZED" content: application/json: schema: type: object properties: message: type: string description: "The error message." example: "Invalid access token" security: - apiKey: [] parameters: - name: conversation_id in: path required: true description: The unique identifier of the conversation. schema: type: string example: c123456 /v2/personas: post: tags: - Personas summary: Create Persona description: Creates a persona that configures how a replica behaves and sounds in CVI for every conversation that uses that persona. operationId: createPersona requestBody: content: application/json: schema: type: object properties: persona_name: type: string description: "A name for the persona." example: "Life Coach" system_prompt: type: string description: "This is the system prompt that will be used by the llm. **Each request must have a `system_prompt` value unless you're using echo mode**." example: "As a Life Coach, you are a dedicated professional who specializes in..." pipeline_mode: type: string description: "The pipeline mode to use for the persona. Possible values: `full`, `echo`. `full` will provide the default end-to-end experience. `echo` will turn off most steps, and allow the replica to sync video with audio passed in through Echo events, which it will speak out." enum: - "full" - "echo" default_replica_id: type: string description: "The default replica_id associated with this persona if one exists. When creating a conversation, a persona_id with a default_replica_id associated can we used to create a conversation without specifying a replica_id." example: "r90bbd427f71" document_ids: type: array description: "Array of document IDs that the persona will have access to. These documents will be available to the persona in all their conversations. The `document_ids` are returned in the response of the [Get Document](/api-reference/documents/get-document) and the [Create Document](/api-reference/documents/create-document) endpoints." items: type: string example: ["d1234567890", "d2468101214"] document_tags: type: array description: "Array of document tags that the persona will have access to. Documents matching these tags will be available to the persona in all their conversations. The tags are passed in the `document_tags` parameter of the [Create Document](/api-reference/documents/create-document) endpoint. As soon as one document has the tag, you will be able to pass the tags in this parameter.." items: type: string example: ["product_info", "company_policies"] objectives_id: type: string description: "The unique identifier of the objectives to attach to this persona. Objectives provide goal-oriented instructions that help guide conversations toward specific outcomes. Create objectives using the [Create Objectives](/api-reference/objectives/create-objectives) endpoint." example: "o12345" guardrails_id: type: string description: "The unique identifier of the guardrails to attach to this persona. Guardrails provide strict behavioral boundaries and guidelines that will be rigorously followed throughout conversations. Create guardrails using the [Create Guardrails](/api-reference/guardrails/create-guardrails) endpoint." example: "g12345" layers: type: object description: | Optional nested settings for each CVI pipeline layer (perception, STT, conversational flow, LLM, TTS). For an overview of what each layer controls, see [Persona overview — CVI layers](/sections/conversational-video-interface/persona/overview#cvi-layer). properties: perception: type: object properties: perception_model: type: string description: "The perception model to use. `raven-1` (default and recommended) provides real-time emotional understanding from user audio, more natural and human-like interactions, plus all visual capabilities from raven-0. `raven-0` (legacy settings [here](/sections/troubleshooting#migration-from-legacy-perception-to-raven-1)) offers advanced visual perception only. `off` disables all perception." enum: - "raven-1" - "raven-0" - "off" default: "raven-1" example: "raven-1" visual_awareness_queries: type: array description: "Custom queries that Raven continuously monitors in the visual stream. These provide ambient visual context without requiring explicit prompting." items: type: string example: [ "Is the user showing an ID card?", "Does the user appear distressed or uncomfortable?", ] visual_tool_prompt: type: string description: "A prompt that details how and when to use visual tools based on what Raven sees. This helps the replica understand the context of the visual tools." example: "You have a tool to notify the system when an ID card is detected, named `notify_if_id_shown`. You MUST use this tool when a form of ID is detected." visual_tools: type: array description: "Tools that can be triggered based on visual context, enabling automated actions in response to visual cues." items: type: object properties: name: type: string description: "The name of the tool to be called." description: type: string description: "A description of what the tool does and when it should be called." example: [ { type: "function", function: { name: "notify_if_id_shown", description: "Use this function when a drivers license or passport is detected in the image with high confidence. After collecting the ID, internally use final_ask()", parameters: { type: "object", properties: { id_type: { type: "string", description: "best guess on what type of ID it is", }, }, required: ["id_type"], }, }, }, ] audio_awareness_queries: type: array description: "Custom queries that Raven-1 continuously monitors in the audio stream. These provide ambient audio context such as user tone and emotional state. Only available with `raven-1`." items: type: string example: [ "Does the user sound frustrated or confused?", "Is the user speaking quickly as if in a hurry?", ] audio_tool_prompt: type: string description: "A prompt that details how and when to use audio tools based on what Raven-1 hears. Only available with `raven-1`." example: "You have a tool to escalate to a human agent when the user sounds very frustrated, named `escalate_to_human`. Use this tool when detecting sustained frustration." audio_tools: type: array description: "Tools that can be triggered based on audio analysis, enabling automated actions in response to user tone and emotion. Only available with `raven-1`." items: type: object properties: name: type: string description: "The name of the tool to be called." description: type: string description: "A description of what the tool does and when it should be called." example: [ { type: "function", function: { name: "escalate_to_human", description: "Escalate the conversation to a human agent when user frustration is detected", parameters: { type: "object", properties: { reason: { type: "string", description: "The reason for escalation", }, }, required: ["reason"], }, }, }, ] stt: type: object description: | **Note**: Turn-taking is now configured on the [Conversational Flow layer](/sections/conversational-video-interface/persona/conversational-flow). properties: stt_engine: type: string description: "The STT engine used for transcription. `tavus-auto` (default, recommended) automatically selects the best model for the conversation's language. `tavus-parakeet` offers highest throughput and lowest latency for English and European languages. `tavus-soniox` is purpose-built for Indian languages with broad multilingual coverage. `tavus-whisper` provides broad multilingual coverage across all supported languages. `tavus-deepgram-medical` is domain-specific English STT optimized for clinical and healthcare vocabulary. `tavus-advanced` is deprecated and not recommended for new integrations. See the [STT layer documentation](/sections/conversational-video-interface/persona/stt) for details." enum: - "tavus-auto" - "tavus-parakeet" - "tavus-soniox" - "tavus-whisper" - "tavus-deepgram-medical" - "tavus-advanced" default: "tavus-auto" example: "tavus-auto" hotwords: type: string description: | The hotwords parameter lets you provide example phrases that guide the STT model to prioritize certain words or phrases—especially names, technical terms, or uncommon language. For instance, including "Roey is the name of the person you're speaking with" helps the model transcribe "Roey" correctly instead of "Rowie." example: "Roey is the name of the person you're speaking with." conversational_flow: type: object description: "Controls conversational flow dynamics for the replica. When not explicitly provided, all fields default to None (turned off). If any parameter is provided, sensible defaults are applied to all other parameters. See more details [here](/sections/conversational-video-interface/persona/conversational-flow)." properties: turn_detection_model: type: string description: "The model used for turn detection. Options include `sparrow-1` (recommended) for advanced turn detection that is faster, more accurate, and more natural, and `sparrow-0` (legacy) for standard turn detection. Default is `sparrow-1` when any conversational flow parameter is provided." enum: - "sparrow-1" - "sparrow-0" example: "sparrow-1" turn_taking_patience: type: string description: "Controls how eagerly and quickly the replica claims conversational turns. Affects both response latency and likelihood of interrupting during natural pauses. `low` = eager and quick to respond, may interrupt pauses; `medium` (default) = balanced; `high` = patient, waits for clear turn completion." enum: - "low" - "medium" - "high" example: "medium" replica_interruptibility: type: string description: "Controls how sensitive the replica is to user speech while the replica is talking. Determines whether the replica stops to listen or keeps speaking. `low` = keeps talking, less interruptible; `medium` (default) = balanced; `high` = stops easily, more interruptible." enum: - "low" - "medium" - "high" example: "medium" voice_isolation: type: string description: "Controls the voice isolation model used on participant audio. Voice isolation separates speech from background noise in the participant's microphone audio. `near` (default) = separates speech from background noise for scenarios where the user is less than 1 meter away from the microphone; `off` = no voice isolation, raw audio is sent down the conversational pipeline. Default is `near`." enum: - "off" - "near" default: "near" example: "near" wake_phrase: type: string description: "A specific phrase the persona listens for before responding. When set, the persona remains silent until it hears the wake phrase, similar to a voice assistant. The persona still records all user utterances in the transcript so it has full conversation context when it does respond. Choose a phrase that is unique enough to avoid over-triggering (avoid generic greetings like `Hey`). Default is `None` (disabled)." example: "Hey Siri" idle_engagement: type: string description: "Controls whether the replica proactively re-engages the user after a stretch of silence, and how eagerly. `off` (default) = the replica never breaks silence; `patient` = re-engages after longer silences, suited to tutors or contemplative use cases; `eager` = re-engages after shorter silences, suited to SDR or sales-style use cases." enum: - "off" - "patient" - "eager" default: "off" example: "off" llm: type: object properties: model: type: string description: | The model name that will be used by the LLM. **tavus-gpt-oss** is recommended as a good starting point. Other Tavus-hosted options include tavus-gemini-2.5-flash, tavus-claude-haiku-4.5, tavus-gpt-5.2, and tavus-gemini-3-flash. See the [LLM layer documentation](/sections/conversational-video-interface/persona/llm) for a full comparison. For your own OpenAI-compatible LLM, provide a `model`, `base_url`, and `api_key`. **Context window:** Performance and intelligence are best when prompts are limited to 5,000 tokens. Degradations in speed and instruction following may occur in the 15,000–20,000 token range. Tavus-hosted models support up to 32,000 tokens. Tip: 1 token ≈ 4 characters. base_url: type: string description: "The base url for your OpenAI compatible endpoint." example: "your-base-url" api_key: type: string description: "The API key for the OpenAI compatible endpoint." example: "your-api-key" speculative_inference: type: boolean description: "When set to `true`, the LLM begins processing speech transcriptions before user input ends, improving responsiveness. Default is `true`." example: true default: true tools: type: array description: "Optional tools to provide to your custom LLM - click [here](/sections/conversational-video-interface/persona/llm-tool) for more details." example: [ { "type": "function", "function": { "name": "get_current_weather", "description": "Get the current weather in a given location", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA", }, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"], }, }, "required": ["location"], }, }, }, ] headers: type: object description: "Optional headers to provide to your custom LLM" example: { "Authorization": "Bearer your-api-key", } extra_body: type: object description: | Optional parameters to customize the LLM request. For Tavus-hosted models, you can pass `temperature` and `top_p`: - `temperature`: Controls randomness in the model's output. Range typically 0.0 to 2.0. Lower values make output more deterministic and focused, higher values make it more creative and varied. - `top_p`: Controls diversity via nucleus sampling. Range 0.0 to 1.0. Lower values make output more focused on high-probability tokens, higher values allow more diverse token selection. For custom LLMs, you can pass any parameters that your LLM provider supports (e.g., `temperature`, `top_p`, `frequency_penalty`, etc.). example: { "temperature": 0.7, "top_p": 0.9 } tts: type: object properties: api_key: type: string description: | The API key for the chosen TTS provider. Only required when using private voices. **ElevenLabs:** When using pronunciation dictionaries with your own ElevenLabs key, the key must have the `pronunciation_dictionaries_write` scope (or full account access). See [ElevenLabs API key scopes](https://elevenlabs.io/docs/api-reference/service-accounts/api-keys/create). **Cartesia:** No additional scope required — any valid Cartesia API key works. example: "your-api-key" tts_engine: type: string description: "The TTS engine that will be used." enum: - "cartesia" - "elevenlabs" external_voice_id: type: string description: "The voice ID used for the TTS engine when you want to customize your replica's voice. Choose from Cartesia's stock voices by referring to their [Voice Catalog](https://docs.cartesia.ai/api-reference/voices/list), or if you want more options you can consider [ElevenLabs](https://elevenlabs.io/docs/api-reference/voices/get-all)." example: "external-voice-id" voice_settings: type: object description: | Optional voice settings to customize TTS behavior. For Cartesia we support inline Cartesia SSML settings (https://docs.cartesia.ai/build-with-cartesia/sonic-3/ssml-tags). For ElevenLabs we support: `speed` (0.7–1.2), `stability` (0.0–1.0), `similarity_boost` (0.0–1.0), `style` (0.0–1.0), `use_speaker_boost` (boolean). See [ElevenLabs Voice Settings](https://elevenlabs.io/docs/api-reference/voices/settings/get). example: { "speed": 0.5, "emotion": ["positivity:high", "curiosity"] } tts_emotion_control: type: boolean description: "When true, Tavus automatically handles LLM prompting for emotion tags, enabling expressive vocal delivery and natural emotional facial movements (only available with Phoenix-4 replicas). Defaults to true." example: true default: true tts_model_name: type: string description: "The model name that will be used by the TTS engine. Please double check this with the TTS provider you are using to ensure valid model names." example: "sonic-3" pronunciation_dictionary_id: type: string description: | The unique identifier of a Tavus pronunciation dictionary to attach to this persona. Tavus will apply the dictionary's rules at conversation time. Provider-specific dictionary IDs are managed internally by Tavus and are not exposed in GET responses — only this field is visible. example: "pd_abc123def456" examples: Required Parameters Only: value: pipeline_mode: "full" system_prompt: "As a Life Coach, you are a dedicated professional who specializes in..." Full Customizations: value: persona_name: "Life Coach" system_prompt: "As a Life Coach, you are a dedicated professional who specializes in..." pipeline_mode: "full" default_replica_id: "r90bbd427f71" layers: llm: model: "tavus-gpt-oss" speculative_inference: true tools: - type: function function: name: "life_coach_insight" description: "Offer personalized life coaching advice or guidance based on a user's challenge or goal." parameters: type: object properties: topic: type: string description: "The area of life or goal the user wants to improve (e.g. career, relationships, confidence)" urgency_level: type: string enum: ["low", "medium", "high"] required: ["topic"] tts: tts_engine: "cartesia" voice_settings: speed: "normal" emotion: ["positivity:high", "curiosity"] tts_emotion_control: true tts_model_name: "sonic-3" perception: perception_model: "raven-1" visual_awareness_queries: - "Is the user showing an ID card?" - "Does the user appear distressed or uncomfortable?" visual_tool_prompt: "You have a tool to notify the system when an ID card is detected, named `notify_if_id_shown`. You MUST use this tool when a form of ID is detected." visual_tools: - type: function function: name: "notify_if_id_shown" description: "Use this function when a drivers license or passport is detected in the image with high confidence. After collecting the ID, internally use final_ask()" parameters: type: object properties: id_type: type: string description: "best guess on what type of ID it is" required: ["id_type"] audio_awareness_queries: - "Does the user sound frustrated or confused?" stt: stt_engine: "tavus-auto" conversational_flow: turn_detection_model: "sparrow-1" turn_taking_patience: "medium" turn_commitment: "medium" replica_interruptibility: "high" voice_isolation: "near" idle_engagement: "off" document_ids: ["d1234567890", "d2468101214"] document_tags: ["product_info", "company_policies"] responses: "200": description: "" content: application/json: schema: type: object properties: persona_id: type: string description: "A unique identifier for the persona." example: "pcb7a34da5fe" persona_name: type: string description: "The name of the persona." example: "Life Coach" created_at: type: string description: "The date and time the persona was created." "400": description: "Bad Request" content: application/json: schema: type: object properties: error: type: string description: "The error message." example: "Invalid replica_uuid" "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: - Personas summary: List Personas description: | This endpoint returns a list of all Personas created by the account associated with the API Key in use. operationId: listPersonas parameters: - in: query name: limit schema: type: integer description: "The number of personas to return per page. Default is 10." - in: query name: page schema: type: integer description: "The page number to return. Default is 1." - in: query name: persona_type schema: type: string description: "Filter the personas by type. Possible values: user, system. System personas are personas that have been created by Tavus." enum: - user - system responses: "200": description: "" content: application/json: schema: type: object properties: data: type: array description: "Personas for the current page; use `total_count` for the full count under the applied filters." items: type: object properties: persona_id: type: string description: "A unique identifier for the persona." example: "pcb7a34da5fe" persona_name: type: string description: "A name for the persona." example: "Life Coach" system_prompt: type: string description: "The system prompt that will be used by the llm." example: "As a Life Coach, you are a dedicated professional who specializes in..." default_replica_id: type: string example: "r90bbd427f71" description: "The default replica_id associated with this persona if one exists." document_ids: type: array description: "Array of document IDs that the persona has access to. These documents will be available to the persona in all their conversations. The document_ids are returned in the response of the [Get Document](/api-reference/documents/get-document) and the [Create Document](/api-reference/documents/create-document) endpoints." items: type: string example: ["d1234567890", "d2468101214"] document_tags: type: array description: "Array of document tags that the persona has access to. Documents matching these tags will be available to the persona in all their conversations." items: type: string example: ["product_info", "company_policies"] layers: type: object properties: llm: type: object properties: model: type: string description: "The model name that will be used by the llm." base_url: type: string description: "The base URL for the OpenAI compatible endpoint if you are using your own llm." example: "your-base-url" api_key: type: string description: "The API key for the OpenAI compatible endpoint if you are using your own llm." example: "your-api-key" tools: type: array description: "Optional tools to provide to your custom LLM" example: [ { "type": "function", "function": { "name": "get_current_weather", "description": "Get the current weather in a given location", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA", }, "unit": { "type": "string", "enum": [ "celsius", "fahrenheit", ], }, }, "required": ["location"], }, }, }, ] tts: type: object properties: api_key: type: string description: | The API key for the chosen TTS provider. Only required when using private voices. **ElevenLabs:** When using pronunciation dictionaries with your own ElevenLabs key, the key must have the `pronunciation_dictionaries_write` scope (or full account access). See [ElevenLabs API key scopes](https://elevenlabs.io/docs/api-reference/service-accounts/api-keys/create). example: "your-api-key" tts_engine: type: string description: "The TTS engine that will be used." enum: - "cartesia" - "elevenlabs" external_voice_id: type: string description: "The voice ID used for the TTS engine when you want to customize your replica's voice. Choose from Cartesia's stock voices by referring to their [Voice Catalog](https://docs.cartesia.ai/api-reference/voices/list), or if you want more options you can consider [ElevenLabs](https://elevenlabs.io/docs/api-reference/voices/get-all)." example: "external-voice-id" voice_settings: type: object description: | Optional voice settings to customize TTS behavior. For Cartesia we support inline Cartesia SSML settings (https://docs.cartesia.ai/build-with-cartesia/sonic-3/ssml-tags). For ElevenLabs we support: speed (0.7–1.2), stability (0.0–1.0), similarity_boost (0.0–1.0), style (0.0–1.0), use_speaker_boost (boolean). See https://elevenlabs.io/docs/api-reference/voices/settings/get. example: { "speed": 0.5, "emotion": ["positivity:high", "curiosity"] } tts_emotion_control: type: boolean description: "If true, the TTS engine will be able to control the emotion of the voice. Defaults to true." example: true default: true tts_model_name: type: string description: "The model name that will be used by the TTS engine. Please double check this with the TTS provider you are using to ensure valid model names." example: "sonic-3" pronunciation_dictionary_id: type: string description: "The unique identifier of the Tavus pronunciation dictionary attached to this persona, if any. Provider-specific dictionary IDs are managed internally and are not exposed." example: "pd_abc123def456" perception: type: object properties: perception_model: type: string description: "The perception model to use. `raven-1` (default and recommended) provides real-time emotional understanding from user audio, more natural and human-like interactions, plus all visual capabilities from raven-0. `raven-0` (legacy settings [here](/sections/troubleshooting#migration-from-legacy-perception-to-raven-1)) offers advanced visual perception only. `off` disables all perception." enum: - "raven-1" - "raven-0" - "off" default: "raven-1" example: "raven-1" visual_awareness_queries: type: array description: "Custom queries that Raven continuously monitors in the visual stream. These provide ambient visual context without requiring explicit prompting." items: type: string example: [ "Is the user showing an ID card?", "Does the user appear distressed or uncomfortable?", ] visual_tool_prompt: type: string description: "A prompt that details how and when to use visual tools based on what Raven sees. This helps the replica understand the context of the visual tools." example: "You have a tool to notify the system when an ID card is detected, named `notify_if_id_shown`. You MUST use this tool when a form of ID is detected." visual_tools: type: array description: "Tools that can be triggered based on visual context, enabling automated actions in response to visual cues." items: type: object properties: name: type: string description: "The name of the tool to be called." description: type: string description: "A description of what the tool does and when it should be called." example: [ { type: "function", function: { name: "notify_if_id_shown", description: "Use this function when a drivers license or passport is detected in the image with high confidence. After collecting the ID, internally use final_ask()", parameters: { type: "object", properties: { id_type: { type: "string", description: "best guess on what type of ID it is", }, }, required: ["id_type"], }, }, }, ] audio_awareness_queries: type: array description: "Custom queries that Raven-1 continuously monitors in the audio stream. These provide ambient audio context such as user tone and emotional state. Only available with `raven-1`." items: type: string example: [ "Does the user sound frustrated or confused?", "Is the user speaking quickly as if in a hurry?", ] audio_tool_prompt: type: string description: "A prompt that details how and when to use audio tools based on what Raven-1 hears. Only available with `raven-1`." example: "You have a tool to escalate to a human agent when the user sounds very frustrated, named `escalate_to_human`. Use this tool when detecting sustained frustration." audio_tools: type: array description: "Tools that can be triggered based on audio analysis, enabling automated actions in response to user tone and emotion. Only available with `raven-1`." items: type: object properties: name: type: string description: "The name of the tool to be called." description: type: string description: "A description of what the tool does and when it should be called." example: [ { type: "function", function: { name: "escalate_to_human", description: "Escalate the conversation to a human agent when user frustration is detected", parameters: { type: "object", properties: { reason: { type: "string", description: "The reason for escalation", }, }, required: ["reason"], }, }, }, ] stt: type: object description: | **Note**: Turn-taking is now configured on the [Conversational Flow layer](/sections/conversational-video-interface/persona/conversational-flow). properties: stt_engine: type: string description: "The STT engine used for transcription. `tavus-auto` (default, recommended) automatically selects the best model. `tavus-parakeet` offers highest throughput for English and European languages. `tavus-soniox` is purpose-built for Indian languages. `tavus-whisper` provides broad multilingual coverage. `tavus-deepgram-medical` is optimized for clinical vocabulary (English only). `tavus-advanced` is deprecated." enum: - "tavus-auto" - "tavus-parakeet" - "tavus-soniox" - "tavus-whisper" - "tavus-deepgram-medical" - "tavus-advanced" default: "tavus-auto" example: "tavus-auto" hotwords: type: string description: "The hotwords that will be used for the STT engine." example: "This is a hotword example" created_at: type: string description: "The date and time the persona was created." example: "" updated_at: type: string description: "The date and time of when the persona was last updated." total_count: type: integer description: "The total number of personas given the filters provided." "401": description: "UNAUTHORIZED" content: application/json: schema: type: object properties: message: type: string description: "The error message." example: "Invalid access token" security: - apiKey: [] /v2/personas/{persona_id}: get: tags: - Personas summary: Get Persona description: | This endpoint returns a single persona by its unique identifier. operationId: getPersona responses: "200": description: "" content: application/json: schema: type: object properties: data: type: array items: type: object properties: persona_id: type: string description: "A unique identifier for the persona." example: "pcb7a34da5fe" persona_name: type: string description: "A name for the persona." example: "Life Coach" system_prompt: type: string description: "The system prompt that will be used by the llm." example: "As a Life Coach, you are a dedicated professional who specializes in..." default_replica_id: type: string example: "r90bbd427f71" description: "The default replica_id associated with this persona if one exists." document_ids: type: array description: "Array of document IDs that the persona has access to. These documents will be available to the persona in all their conversations. The document_ids are returned in the response of the [Get Document](/api-reference/documents/get-document) and the [Create Document](/api-reference/documents/create-document) endpoints." items: type: string example: ["d1234567890", "d2468101214"] document_tags: type: array description: "Array of document tags that the persona has access to. Documents matching these tags will be available to the persona in all their conversations." items: type: string example: ["product_info", "company_policies"] layers: type: object properties: llm: type: object properties: model: type: string description: "The model name that will be used by the llm." base_url: type: string description: "The base URL for the OpenAI compatible endpoint if you are using your own llm." example: "your-base-url" api_key: type: string description: "The API key for the OpenAI compatible endpoint if you are using your own llm." example: "your-api-key" tools: type: array description: "Optional tools to provide to your custom LLM" example: [ { "type": "function", "function": { "name": "get_current_weather", "description": "Get the current weather in a given location", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA", }, "unit": { "type": "string", "enum": [ "celsius", "fahrenheit", ], }, }, "required": ["location"], }, }, }, ] headers: type: object description: "Optional headers to provide to your custom LLM" example: { "Authorization": "Bearer your-api-key", } extra_body: type: object description: | Optional parameters to customize the LLM request. For Tavus-hosted models, you can pass `temperature` and `top_p`: - `temperature`: Controls randomness in the model's output. Range typically 0.0 to 2.0. Lower values make output more deterministic and focused, higher values make it more creative and varied. - `top_p`: Controls diversity via nucleus sampling. Range 0.0 to 1.0. Lower values make output more focused on high-probability tokens, higher values allow more diverse token selection. For custom LLMs, you can pass any parameters that your LLM provider supports (e.g., `temperature`, `top_p`, `frequency_penalty`, etc.). example: { "temperature": 0.7, "top_p": 0.9 } tts: type: object properties: api_key: type: string description: | The API key for the chosen TTS provider. Only required when using private voices. **ElevenLabs:** When using pronunciation dictionaries with your own ElevenLabs key, the key must have the `pronunciation_dictionaries_write` scope (or full account access). See [ElevenLabs API key scopes](https://elevenlabs.io/docs/api-reference/service-accounts/api-keys/create). example: "your-api-key" tts_engine: type: string description: "The TTS engine that will be used." enum: - "cartesia" - "elevenlabs" external_voice_id: type: string description: "The voice ID used for the TTS engine when you want to customize your replica's voice. Choose from Cartesia's stock voices by referring to their [Voice Catalog](https://docs.cartesia.ai/api-reference/voices/list), or if you want more options you can consider [ElevenLabs](https://elevenlabs.io/docs/api-reference/voices/get-all)." example: "external-voice-id" voice_settings: type: object description: | Optional voice settings to customize TTS behavior. For Cartesia we support inline Cartesia SSML settings (https://docs.cartesia.ai/build-with-cartesia/sonic-3/ssml-tags). For ElevenLabs we support: speed (0.7–1.2), stability (0.0–1.0), similarity_boost (0.0–1.0), style (0.0–1.0), use_speaker_boost (boolean). See https://elevenlabs.io/docs/api-reference/voices/settings/get. example: { "speed": 0.5, "emotion": ["positivity:high", "curiosity"] } tts_emotion_control: type: boolean description: "If true, the TTS engine will be able to control the emotion of the voice. Defaults to true." example: true default: true tts_model_name: type: string description: "The model name that will be used by the TTS engine. Please double check this with the TTS provider you are using to ensure valid model names." example: "sonic-3" pronunciation_dictionary_id: type: string description: "The unique identifier of the Tavus pronunciation dictionary attached to this persona, if any. Provider-specific dictionary IDs are managed internally and are not exposed." example: "pd_abc123def456" perception: type: object properties: perception_model: type: string description: "The perception model to use. `raven-1` (default and recommended) provides real-time emotional understanding from user audio, more natural and human-like interactions, plus all visual capabilities from raven-0. `raven-0` (legacy settings [here](/sections/troubleshooting#migration-from-legacy-perception-to-raven-1)) offers advanced visual perception only. `off` disables all perception." enum: - "raven-1" - "raven-0" - "off" default: "raven-1" example: "raven-1" visual_awareness_queries: type: array description: "Custom queries that Raven continuously monitors in the visual stream. These provide ambient visual context without requiring explicit prompting." items: type: string example: [ "Is the user showing an ID card?", "Does the user appear distressed or uncomfortable?", ] visual_tool_prompt: type: string description: "A prompt that details how and when to use visual tools based on what Raven sees. This helps the replica understand the context of the visual tools." example: "You have a tool to notify the system when an ID card is detected, named `notify_if_id_shown`. You MUST use this tool when a form of ID is detected." visual_tools: type: array description: "Tools that can be triggered based on visual context, enabling automated actions in response to visual cues." items: type: object properties: name: type: string description: "The name of the tool to be called." description: type: string description: "A description of what the tool does and when it should be called." example: [ { type: "function", function: { name: "notify_if_id_shown", description: "Use this function when a drivers license or passport is detected in the image with high confidence. After collecting the ID, internally use final_ask()", parameters: { type: "object", properties: { id_type: { type: "string", description: "best guess on what type of ID it is", }, }, required: ["id_type"], }, }, }, ] audio_awareness_queries: type: array description: "Custom queries that Raven-1 continuously monitors in the audio stream. These provide ambient audio context such as user tone and emotional state. Only available with `raven-1`." items: type: string example: [ "Does the user sound frustrated or confused?", "Is the user speaking quickly as if in a hurry?", ] audio_tool_prompt: type: string description: "A prompt that details how and when to use audio tools based on what Raven-1 hears. Only available with `raven-1`." example: "You have a tool to escalate to a human agent when the user sounds very frustrated, named `escalate_to_human`. Use this tool when detecting sustained frustration." audio_tools: type: array description: "Tools that can be triggered based on audio analysis, enabling automated actions in response to user tone and emotion. Only available with `raven-1`." items: type: object properties: name: type: string description: "The name of the tool to be called." description: type: string description: "A description of what the tool does and when it should be called." example: [ { type: "function", function: { name: "escalate_to_human", description: "Escalate the conversation to a human agent when user frustration is detected", parameters: { type: "object", properties: { reason: { type: "string", description: "The reason for escalation", }, }, required: ["reason"], }, }, }, ] stt: type: object description: | **Note**: Turn-taking is now configured on the [Conversational Flow layer](/sections/conversational-video-interface/persona/conversational-flow). properties: stt_engine: type: string description: "The STT engine used for transcription. `tavus-auto` (default, recommended) automatically selects the best model. `tavus-parakeet` offers highest throughput for English and European languages. `tavus-soniox` is purpose-built for Indian languages. `tavus-whisper` provides broad multilingual coverage. `tavus-deepgram-medical` is optimized for clinical vocabulary (English only). `tavus-advanced` is deprecated." enum: - "tavus-auto" - "tavus-parakeet" - "tavus-soniox" - "tavus-whisper" - "tavus-deepgram-medical" - "tavus-advanced" default: "tavus-auto" example: "tavus-auto" hotwords: type: string description: "The hotwords that will be used for the STT engine." example: "This is a hotword example" created_at: type: string description: "The date and time the persona was created." example: "" updated_at: type: string description: "The date and time of when the persona was last updated." "400": description: "Bad Request" content: application/json: schema: type: object properties: error: type: string description: "The error message." example: "Invalid persona_id" "401": description: "UNAUTHORIZED" content: application/json: schema: type: object properties: message: type: string description: "The error message." example: "Invalid access token" security: - apiKey: [] delete: tags: - Personas summary: Delete Persona description: | This endpoint deletes a single persona by its unique identifier. operationId: deletePersona parameters: - name: persona_id in: path required: true description: The unique identifier of the persona. schema: type: string example: pcb7a34da5fe responses: "204": description: "NO CONTENT" "400": description: "Bad Request" content: application/json: schema: type: object properties: error: type: string description: "The error message." example: "Invalid persona_id" "401": description: "UNAUTHORIZED" content: application/json: schema: type: object properties: message: type: string description: "The error message." example: "Invalid access token" security: - apiKey: [] patch: tags: - Personas summary: Patch Persona description: This endpoint allows you to update specific fields of a persona using JSON Patch operations. operationId: patchPersona 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: "add" path: type: string description: | JSON Pointer (RFC 6901) to a location in the persona document. Paths must match the **current** document shape—compare the response from [Get Persona](/api-reference/personas/get-persona) (`GET /v2/personas/{persona_id}`) before patching. example: "/layers/llm/model" value: type: string description: "The value to be used within the operation. **This field is not required for the `remove` operation**." example: "tavus-llama-4" required: - op - path - value examples: Replace Persona System Prompt: value: - op: "replace" path: "/system_prompt" value: "As a Life Coach, you are a dedicated professional who specializes in..." Remove STT Hotwords: value: - op: "remove" path: "/layers/stt/hotwords" responses: "200": description: "OK" "304": description: "No changes were made to the persona" content: application/json: schema: type: object properties: message: type: string description: "The error message." example: "No changes were made to the persona" "400": description: "Bad Request" content: application/json: schema: type: object properties: error: type: string description: "The error message." example: "Invalid persona_id" "422": description: "Invalid JSON patch format" content: application/json: schema: type: object properties: message: type: string description: "The error message." example: "Invalid JSON patch format" security: - apiKey: [] parameters: - name: persona_id in: path required: true description: The unique identifier of the persona. schema: type: string example: pcb7a34da5fe /v2/transcriptions: post: tags: - Transcriptions summary: Create Transcription description: | This endpoint creates a transcription request that will convert speech to text in your video content. operationId: createTranscription requestBody: content: application/json: schema: type: object properties: file_url: type: string description: "A direct link to the video that will be transcribed. This should be a publicly accessible / presigned S3 URL." example: "https://example.com/video.mp4" callback_url: type: string description: "A url that will receive a callback on completion of the transcription or on error." example: "https://your-callback-url.com" required: - file_url - callback_url responses: "200": description: "" content: application/json: schema: type: object properties: transcription_id: type: string example: "t0108f2d24k2a" description: "A unique identifier for the transcription." status: type: string description: "The status of the transcription." callback_url: type: string description: "The callback URL provided in the request." example: "https://your-callback-url.com" security: - apiKey: [] get: tags: - Transcriptions summary: List Transcriptions description: | This endpoint returns a list of all Transcriptions created by the account associated with the API Key in use. operationId: listTranscriptions parameters: - in: query name: limit schema: type: integer description: "The number of transcriptions 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: "" content: application/json: schema: type: object properties: data: type: array items: type: object properties: transcription_id: type: string description: "A unique identifier for the transcription." example: "t0108f2d24k2a" file_url: type: string description: "The URL of the file that was transcribed." example: "https://example.com/video.mp4" text: type: string description: "The transcribed text from the video." status: type: string description: "The status of the transcription. Can be either `started`, `completed`, or `error`." created_at: type: string description: "The date and time the transcription was created." total_count: type: integer description: "The total number of transcriptions that fit the query." security: - apiKey: [] /v2/objectives: post: tags: - Objectives summary: Create Objectives description: | This endpoint creates objectives for a persona. operationId: createObjectives requestBody: content: application/json: schema: type: object properties: data: type: array description: "Array of objectives to create. Objectives provide goal-oriented instructions that help guide conversations toward specific achievements and desired outcomes." items: type: object properties: objective_name: type: string description: "A descriptive name for the objective. This must be a string value without spaces." example: "ask_if_new_patient" objective_prompt: type: string description: "The detailed prompt that defines what the objective should accomplish." example: "Ask the patient if they are new or have been here before" confirmation_mode: type: string description: "How the objective completion should be confirmed. If set to `manual`, the user will be prompted to confirm the objective completion. If set to `auto`, the LLM will determine whether the objective was completed or not." enum: - "auto" - "manual" default: "auto" example: "auto" output_variables: type: array description: "Optional list of variables that should be extracted or collected during the objective." items: type: string example: ["patient_status"] modality: type: string description: "The communication modality for the objective. If set to `verbal`, the objective will be completed by the user's responses. If set to `visual`, the objective can only be completed by visual / perception cues observed by Raven." enum: - "verbal" - "visual" default: "verbal" example: "verbal" next_conditional_objectives: type: object description: "A mapping of objective names to conditions that must be satisfied for that objective to be activated once this objective is completed. Use this to write multiple conditional objectives." additionalProperties: type: string example: new_patient_intake_process: "If the patient has never been to the practice before" existing_patient_intake_process: "If the patient has been to the practice before" next_required_objective: type: string description: "The name of the next required objective that will be activated once the current objective is completed. Use this to write a single next required objective without conditions." example: "get_patient_name" callback_url: type: string description: "Optional URL that will receive notifications when the objective is completed." example: "https://your-server.com/webhook" required: - objective_name - objective_prompt required: - data responses: "200": description: "Objective created successfully" content: application/json: schema: type: object properties: objectives_id: type: string description: "Unique identifier for the created objective" example: "o12345" objective_name: type: string description: "Name of the objective" example: "New Objectives" status: type: string description: "Current status of the objective" example: "active" created_at: type: string description: "ISO 8601 timestamp of when the objective was 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: "objective_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: - Objectives summary: Get Objectives description: | This endpoint returns a list of all objectives. operationId: getObjectives parameters: - in: query name: limit schema: type: integer description: "The number of objectives 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 objectives" content: application/json: schema: type: object properties: data: type: array description: "Objectives for the current page; use `total_count` for the full count." items: type: object properties: objectives_id: type: string description: "Unique identifier for the objective" example: "o12345" objective_name: type: string description: "Name of the objective" example: "ask_if_new_patient" objective_prompt: type: string description: "The detailed prompt that defines what the objective should accomplish" example: "Ask the patient if they are new or have been here before" confirmation_mode: type: string description: "How the objective completion should be confirmed" example: "auto" output_variables: type: array description: "List of variables that should be extracted or collected during the objective" items: type: string example: ["patient_status"] modality: type: string description: "The communication modality for the objective" example: "verbal" next_conditional_objectives: type: object description: "Mapping of objective names to conditions that must be satisfied for that objective to be activated. Use this to write multiple conditional objectives" additionalProperties: type: string example: new_patient_intake_process: "If the patient has never been to the practice before" existing_patient_intake_process: "If the patient has been to the practice before" next_required_objective: type: string description: "The name of the next required objective that will be activated once the current objective is completed. Use this to write a single next required objective without conditions" example: "get_patient_name" callback_url: type: string description: "URL that will receive notifications when the objective is completed" example: "https://your-server.com/webhook" created_at: type: string description: "ISO 8601 timestamp of when the objective was created" example: "2024-01-15T10:30:00Z" updated_at: type: string description: "ISO 8601 timestamp of when the objective was last updated" example: "2024-01-15T10:30:00Z" total_count: type: integer description: "The total number of objectives" example: 25 "401": description: "UNAUTHORIZED" content: application/json: schema: type: object properties: message: type: string description: "The error message." example: "Invalid access token" security: - apiKey: [] /v2/objectives/{objectives_id}: get: tags: - Objectives summary: Get Objective description: | This endpoint returns a single objective by its unique identifier. operationId: getObjective parameters: - name: objectives_id in: path required: true description: "The unique identifier of the objective." schema: type: string example: "o12345" responses: "200": description: "Successfully retrieved objective" content: application/json: schema: type: object properties: data: type: object properties: objective_name: type: string description: "Name of the objective" example: "ask_if_new_patient" objective_prompt: type: string description: "The detailed prompt that defines what the objective should accomplish" example: "Ask the patient if they are new or have been here before" confirmation_mode: type: string description: "How the objective completion should be confirmed" example: "auto" output_variables: type: array description: "List of variables that should be extracted or collected during the objective" items: type: string example: ["patient_status"] modality: type: string description: "The communication modality for the objective" example: "verbal" next_conditional_objectives: type: object description: "Mapping of objective names to conditions that must be satisfied for that objective to be activated" additionalProperties: type: string example: new_patient_intake_process: "If the patient has never been to the practice before" existing_patient_intake_process: "If the patient has been to the practice before" next_required_objective: type: string description: "The name of the next required objective that will be activated once the current objective is completed. Use this to write a single next required objective without conditions" example: "get_patient_name" callback_url: type: string description: "URL that will receive notifications when the objective is completed" example: "https://your-server.com/webhook" created_at: type: string description: "ISO 8601 timestamp of when the objective was created" example: "2024-01-15T10:30:00Z" updated_at: type: string description: "ISO 8601 timestamp of when the objective was 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 objectives_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: "Objective not found" security: - apiKey: [] patch: tags: - Objectives summary: Patch Objective description: | This endpoint allows you to update specific fields of an objective using JSON Patch operations. operationId: patchObjective requestBody: description: | **Note:** The `path` field is a JSON Pointer string that references a location within the target document where the operation is performed. For example: ```json [ { "op": "replace", "path": "/data/0/objective_name", "value": "updated_objective_name" }, { "op": "replace", "path": "/data/0/objective_prompt", "value": "Updated prompt for the objective" }, { "op": "replace", "path": "/data/0/confirmation_mode", "value": "manual" }, { "op": "add", "path": "/data/0/output_variables", "value": ["new_variable"] }, { "op": "replace", "path": "/data/0/modality", "value": "visual" }, { "op": "remove", "path": "/data/0/callback_url" } ] ``` 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: "A JSON Pointer string that references a location within the target document where the operation is performed" example: "/objective_name" value: description: "The value to be used within the operation. **This field is not required for the `remove` operation**." example: "updated_objective_name" required: - op - path examples: Update Objective Name: value: - op: "replace" path: "/objective_name" value: "updated_objective_name" Update Objective Prompt: value: - op: "replace" path: "/objective_prompt" value: "Updated prompt for the objective" Add Output Variables: value: - op: "add" path: "/output_variables" value: ["new_variable", "another_variable"] Remove Callback URL: value: - op: "remove" path: "/callback_url" responses: "200": description: "Objective updated successfully" content: application/json: schema: type: object properties: message: type: string description: "Success message" example: "Objective updated successfully" "304": description: "No changes were made to the objective" "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: "Objective not found" security: - apiKey: [] delete: tags: - Objectives summary: Delete Objective description: | This endpoint deletes a single objective by its unique identifier. operationId: deleteObjective responses: "204": description: "NO CONTENT - Objective deleted successfully" "400": description: "Bad Request" content: application/json: schema: type: object properties: error: type: string description: "The error message." example: "Invalid objectives_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: "Objective not found" security: - apiKey: [] parameters: - name: objectives_id in: path required: true description: "The unique identifier of the objective." schema: type: string example: "o12345" /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}: 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: [] parameters: - name: guardrails_id in: path required: true description: "The unique identifier of the guardrails." schema: type: string example: "g12345" /v2/documents: post: tags: - Documents summary: Create Document description: Upload documents to your knowledge base for personas to reference during conversations. operationId: createDocument requestBody: content: application/json: schema: type: object properties: document_url: type: string description: | Direct URL to a file or a website for your [Knowledge Base](/sections/conversational-video-interface/knowledge-base). Submitting this URL starts processing **asynchronously**; the document can be used in conversations once processing completes, which may take **a few minutes** depending on file size. For now, our Knowledge Base only supports documents written in English and works best for conversations in English. We will be expanding our Knowledge Base language support soon. Maximum file size **50MB**. Supported file formats: `.pdf`, `.txt`, `.docx`, `.doc`, `.png`, `.jpg`, `.pptx`, `.csv`, and `.xlsx`. Website URLs are supported: a snapshot of the page is processed into document content; use the `crawl` object for multi-page crawling from a starting URL. example: "https://docs.example.com/" document_name: type: string description: "Optional name for the document. If not provided, a default name will be generated." example: "Example Docs" callback_url: type: string description: "Optional URL that receives status updates while the document processes asynchronously (e.g. started, processing, ready, error)." example: "https://your-server.com/webhook" tags: type: array description: | Optional tags to categorize the document for management and for use with document-based access in conversations. After the document is ready, attach it via `document_ids` on [Create Persona](/api-reference/personas/create-persona) or [Create Conversation](/api-reference/conversations/create-conversation). items: type: string example: ["docs", "website"] crawl: type: object description: | Optional configuration for website crawling. When provided with a website URL, the system follows links from the starting URL and processes multiple pages into a single document. Without this parameter, only the single page at the URL is scraped. **Rate limits:** at most **100** crawl documents per user, at most **5** concurrent crawls at any time, and a **1-hour cooldown** between recrawls of the same document. To fetch fresh content after a crawled document exists, use [Recrawl Document](/api-reference/documents/recrawl-document). properties: depth: type: integer description: "How many levels deep to follow links from the starting URL (1-10). A depth of 1 means only pages directly linked from the starting URL." minimum: 1 maximum: 10 example: 2 max_pages: type: integer description: "Maximum number of pages to crawl (1-100). Processing stops once this limit is reached." minimum: 1 maximum: 100 example: 10 required: - document_url examples: minimal: summary: Required fields only value: document_url: "https://docs.example.com/" with_crawl: summary: Website with multi-page crawl value: document_name: "Company Knowledge Base" document_url: "https://docs.example.com/" crawl: depth: 2 max_pages: 20 callback_url: "https://your-server.com/webhook" responses: "200": description: "Document created successfully" content: application/json: schema: type: object properties: document_id: type: string description: "Unique identifier for the created document" example: "d8-5c71baca86fc" document_name: type: string description: "Name of the document" example: "Example Docs" document_url: type: string description: "URL of the document or website" example: "https://docs.example.com/" status: type: string description: "Current status of the document processing. Possible values: `started`, `processing`, `ready`, `error`, `recrawling`." enum: - started - processing - ready - error - recrawling example: "started" progress: type: integer nullable: true description: "Processing progress as a percentage (0-100). Null when processing has not started or is complete." example: null error_message: type: string nullable: true description: "Error code indicating why processing failed. Only present when status is `error`. Possible values include: `file_download_failed`, `file_format_unsupported`, `file_size_too_large`, `file_empty`, `invalid_file_url`, `document_processing_failed`, `website_processing_failed`, `chunking_failed`, `embedding_failed`, `vector_store_failed`, `contact_support`." created_at: type: string description: "ISO 8601 timestamp of when the document was created" example: "2024-01-01T12:00:00Z" updated_at: type: string description: "ISO 8601 timestamp of when the document was last updated" example: "2024-01-01T12:00:00Z" callback_url: type: string description: "URL that will receive status updates" example: "https://your-server.com/webhook" tags: type: array description: "Array of document tags" items: type: string example: ["docs", "website"] crawl_config: type: object nullable: true description: "The crawl configuration used for this document (only present for crawled websites)" properties: depth: type: integer description: "Crawl depth setting" example: 2 max_pages: type: integer description: "Maximum pages setting" example: 10 crawled_urls: type: array nullable: true description: "List of URLs that were crawled (only present for crawled websites after processing completes)" items: type: string example: ["https://docs.example.com/", "https://docs.example.com/getting-started", "https://docs.example.com/api"] last_crawled_at: type: string nullable: true description: "ISO 8601 timestamp of when the document was last crawled" example: "2024-01-01T12:00:00Z" crawl_count: type: integer nullable: true description: "Number of times the document has been crawled" example: 1 "400": description: "Bad Request" content: application/json: schema: type: object properties: error: type: string description: "The error message" example: "Invalid request: document_url is required" "401": description: "Unauthorized" content: application/json: schema: type: object properties: message: type: string description: "The error message" example: "Invalid access token" "429": description: "Too Many Requests - Crawl rate limit exceeded" content: application/json: schema: type: object properties: error: type: string description: "The error message" example: "Crawl document limit reached (100). Contact support@tavus.io to increase your limit." security: - apiKey: [] get: tags: - Documents summary: List Documents description: | Retrieve a list of documents. operationId: listDocuments parameters: - in: query name: limit schema: type: integer description: "Number of documents to return per page (default: 10)" example: 10 - in: query name: page schema: type: integer description: "Page number for pagination (0-based, default: 0)" example: 0 - in: query name: sort schema: type: string enum: ["ascending", "descending"] description: "Sort direction for the results (default: ascending)" example: "ascending" - in: query name: status schema: type: string description: "Filter documents by status" - in: query name: name_or_uuid schema: type: string description: "Search for documents by name or UUID" - in: query name: tags schema: type: string description: "Comma-separated list of tags to filter by" example: "important,meeting" responses: "200": description: "List of documents" content: application/json: schema: type: object properties: data: type: array description: "Documents for the current page; use `total_count` for the full count under the applied filters." items: type: object properties: document_id: type: string description: "Unique identifier for the document" example: "d8-5c71baca86fc" document_name: type: string description: "Name of the document" example: "Example Docs" document_url: type: string description: "URL of the document" example: "https://docs.example.com/" status: type: string description: "Current status of the document processing. Possible values: `started`, `processing`, `ready`, `error`, `recrawling`." enum: - started - processing - ready - error - recrawling example: "ready" progress: type: integer nullable: true description: "Processing progress as a percentage (0-100). Null when processing has not started or is complete." example: null error_message: type: string nullable: true description: "Error code indicating why processing failed. Only present when status is `error`. Possible values include: `file_download_failed`, `file_format_unsupported`, `file_size_too_large`, `file_empty`, `invalid_file_url`, `document_processing_failed`, `website_processing_failed`, `chunking_failed`, `embedding_failed`, `vector_store_failed`, `contact_support`." created_at: type: string description: "ISO 8601 timestamp of when the document was created" example: "2024-01-01T12:00:00Z" updated_at: type: string description: "ISO 8601 timestamp of when the document was last updated" example: "2024-01-01T12:05:00Z" callback_url: type: string description: "URL that receives status updates" example: "https://your-server.com/webhook" tags: type: array description: "Array of document tags" items: type: string example: ["docs", "website"] crawl_config: type: object nullable: true description: "The crawl configuration used for this document (only present for crawled websites)" properties: depth: type: integer description: "Crawl depth setting" example: 2 max_pages: type: integer description: "Maximum pages setting" example: 10 crawled_urls: type: array nullable: true description: "List of URLs that were crawled (only present for crawled websites after processing completes)" items: type: string example: ["https://docs.example.com/", "https://docs.example.com/getting-started"] last_crawled_at: type: string nullable: true description: "ISO 8601 timestamp of when the document was last crawled" example: "2024-01-01T12:00:00Z" crawl_count: type: integer nullable: true description: "Number of times the document has been crawled" example: 1 total_count: type: integer description: "Total number of documents matching the filter criteria" example: 42 page: type: integer description: "Current page number" example: 0 limit: type: integer description: "Number of documents per page" example: 10 "400": description: "Bad Request" content: application/json: schema: type: object properties: error: type: string description: "The error message" example: "Invalid request: limit must be a positive integer" "401": description: "Unauthorized" content: application/json: schema: type: object properties: message: type: string description: "The error message" example: "Invalid access token" security: - apiKey: [] /v2/documents/{document_id}: get: tags: - Documents summary: Get Document description: | Retrieve detailed information about a specific document using its unique identifier. operationId: getDocument parameters: - in: path name: document_id required: true schema: type: string description: "The unique identifier of the document to retrieve" example: "d8-5c71baca86fc" x-codeSamples: - lang: curl source: | curl https://tavusapi.com/v2/documents/{document_id} \ -H "x-api-key: YOUR_API_KEY" - lang: Python source: | import requests headers = { "x-api-key": "YOUR_API_KEY" } response = requests.get( "https://tavusapi.com/v2/documents/{document_id}", headers=headers ) - lang: JavaScript source: | const response = await fetch( "https://tavusapi.com/v2/documents/{document_id}", { headers: { "x-api-key": "YOUR_API_KEY" } } ); responses: "200": description: "Document details" content: application/json: schema: type: object properties: document_id: type: string description: "Unique identifier for the document" example: "d8-5c71baca86fc" document_name: type: string description: "Name of the document" example: "Example Docs" document_url: type: string description: "URL of the document" example: "https://docs.example.com/" status: type: string description: "Current status of the document processing. Possible values: `started`, `processing`, `ready`, `error`, `recrawling`." enum: - started - processing - ready - error - recrawling example: "ready" progress: type: integer nullable: true description: "Processing progress as a percentage (0-100). Null when processing has not started or is complete." example: null error_message: type: string nullable: true description: "Error code indicating why processing failed. Only present when status is `error`. Possible values include: `file_download_failed`, `file_format_unsupported`, `file_size_too_large`, `file_empty`, `invalid_file_url`, `document_processing_failed`, `website_processing_failed`, `chunking_failed`, `embedding_failed`, `vector_store_failed`, `contact_support`." created_at: type: string description: "ISO 8601 timestamp of when the document was created" example: "2024-01-01T12:00:00Z" updated_at: type: string description: "ISO 8601 timestamp of when the document was last updated" example: "2024-01-01T12:05:00Z" callback_url: type: string description: "URL that receives status updates" example: "https://your-server.com/webhook" tags: type: array description: "Array of document tags" items: type: string example: ["docs", "website"] crawl_config: type: object nullable: true description: "The crawl configuration used for this document (only present for crawled websites)" properties: depth: type: integer description: "Crawl depth setting" example: 2 max_pages: type: integer description: "Maximum pages setting" example: 10 crawled_urls: type: array nullable: true description: "List of URLs that were crawled (only present for crawled websites after processing completes)" items: type: string example: ["https://docs.example.com/", "https://docs.example.com/getting-started", "https://docs.example.com/api"] last_crawled_at: type: string nullable: true description: "ISO 8601 timestamp of when the document was last crawled" example: "2024-01-01T12:00:00Z" crawl_count: type: integer nullable: true description: "Number of times the document has been crawled" example: 1 "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: message: type: string description: "The error message" example: "Document not found" security: - apiKey: [] delete: tags: - Documents summary: Delete Document description: | Delete a document and its associated data using its unique identifier. operationId: deleteDocument parameters: - in: path name: document_id required: true schema: type: string description: "The unique identifier of the document to delete" responses: "204": description: "NO CONTENT - Document deleted successfully" "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: message: type: string description: "The error message" example: "Document not found" security: - apiKey: [] patch: tags: - Documents summary: Update Document description: Update a document's `document_name` and `tags`. operationId: patchDocument parameters: - in: path name: document_id required: true schema: type: string description: "The unique identifier of the document to update" requestBody: content: application/json: schema: type: object properties: document_name: type: string description: "New name for the document" example: "Updated Document Name" tags: type: array description: "New array of tags for the document. This will overwrite the existing tags for the document." items: type: string example: ["docs", "website", "updated"] responses: "200": description: "Document updated successfully" content: application/json: schema: type: object properties: document_id: type: string description: "Unique identifier for the document" example: "d8-5c71baca86fc" document_name: type: string description: "Updated name of the document" example: "Updated Document Name" document_url: type: string description: "URL of the document" example: "https://docs.example.com/" status: type: string description: "Current status of the document processing. Possible values: `started`, `processing`, `ready`, `error`, `recrawling`." enum: - started - processing - ready - error - recrawling example: "ready" progress: type: integer nullable: true description: "Processing progress as a percentage (0-100). Null when processing has not started or is complete." example: null error_message: type: string nullable: true description: "Error code indicating why processing failed. Only present when status is `error`. Possible values include: `file_download_failed`, `file_format_unsupported`, `file_size_too_large`, `file_empty`, `invalid_file_url`, `document_processing_failed`, `website_processing_failed`, `chunking_failed`, `embedding_failed`, `vector_store_failed`, `contact_support`." created_at: type: string description: "ISO 8601 timestamp of when the document was created" example: "2024-01-01T12:00:00Z" updated_at: type: string description: "ISO 8601 timestamp of when the document was last updated" example: "2024-01-01T13:00:00Z" callback_url: type: string description: "URL that receives status updates" example: "https://your-server.com/webhook" tags: type: array description: "Updated array of document tags" items: type: string example: ["docs", "website", "updated"] crawl_config: type: object nullable: true description: "The crawl configuration used for this document (only present for crawled websites)" properties: depth: type: integer description: "Crawl depth setting" example: 2 max_pages: type: integer description: "Maximum pages setting" example: 10 crawled_urls: type: array nullable: true description: "List of URLs that were crawled (only present for crawled websites after processing completes)" items: type: string example: ["https://docs.example.com/", "https://docs.example.com/getting-started", "https://docs.example.com/api"] last_crawled_at: type: string nullable: true description: "ISO 8601 timestamp of when the document was last crawled" example: "2024-01-01T12:00:00Z" crawl_count: type: integer nullable: true description: "Number of times the document has been crawled" example: 1 "400": description: "Bad Request" content: application/json: schema: type: object properties: error: type: string description: "The error message" example: "Invalid request: document_name must be a string" "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: message: type: string description: "The error message" example: "Document not found" security: - apiKey: [] /v2/documents/{document_id}/recrawl: post: tags: - Documents summary: Recrawl Document description: Trigger a recrawl of a website document to fetch fresh content. operationId: recrawlDocument parameters: - in: path name: document_id required: true schema: type: string description: | Unique id of the crawl-backed **website** document to refresh. Use when the source site changed, you want to refresh content on a schedule, or retry after crawl or processing errors. The document must be in **`ready`** or **`error`** (otherwise `409`). It must have been created with a `crawl` configuration unless you supply `crawl` in the request body for this call. The same document cannot be recrawled more than once within each **1-hour** cooldown (`429` if invoked too soon). example: "d8-5c71baca86fc" requestBody: required: false description: | Optional body. Omit entirely to reuse the crawl `depth` / `max_pages` stored from document creation, or include `crawl` to override those values for this run only. After **`202`**, status is typically **`recrawling`** until processing finishes. If you set `callback_url` when [creating the document](/api-reference/documents/create-document), webhooks report progress until the document returns to **`ready`** or **`error`**. Poll [Get Document](/api-reference/documents/get-document) for current status, `crawl_count`, and `last_crawled_at`. **Account limits:** at most **5** concurrent crawls per user and at most **100** crawl-backed documents per user. content: application/json: schema: type: object properties: crawl: type: object description: | Optional `depth` and `max_pages` for **this recrawl only**; overrides stored crawl settings from document creation when provided. If omitted, the original crawl configuration is used. **What runs:** the same starting URL as the original crawl, links followed within these limits, fresh page content processed, existing vectors replaced when processing completes, and `crawl_count` / `last_crawled_at` updated (see the `202` payload and Get Document while status is `recrawling`). properties: depth: type: integer description: "How many levels deep to follow links from the starting URL (1-10). A depth of 1 means only pages directly linked from the starting URL." minimum: 1 maximum: 10 example: 2 max_pages: type: integer description: "Maximum number of pages to crawl (1-100). Processing stops once this limit is reached." minimum: 1 maximum: 100 example: 10 examples: override_crawl: summary: Override crawl settings for this recrawl value: crawl: depth: 3 max_pages: 50 responses: "202": description: "Recrawl initiated successfully" content: application/json: schema: type: object properties: document_id: type: string description: "Unique identifier for the document" example: "d8-5c71baca86fc" document_name: type: string description: "Name of the document" example: "Company Website" document_url: type: string description: "URL of the document" example: "https://example.com/" status: type: string description: "After a successful recrawl request, typically **`recrawling`** until processing completes, then **`ready`** or **`error`**. Other values: `started`, `processing`." enum: - started - processing - ready - error - recrawling example: "recrawling" progress: type: integer nullable: true description: "Processing progress as a percentage (0-100). Null when processing has not started or is complete." example: null error_message: type: string nullable: true description: "Error code indicating why processing failed. Only present when status is `error`. Possible values include: `file_download_failed`, `file_format_unsupported`, `file_size_too_large`, `file_empty`, `invalid_file_url`, `document_processing_failed`, `website_processing_failed`, `chunking_failed`, `embedding_failed`, `vector_store_failed`, `contact_support`." created_at: type: string description: "ISO 8601 timestamp of when the document was created" example: "2024-01-01T12:00:00Z" updated_at: type: string description: "ISO 8601 timestamp of when the document was last updated" example: "2024-01-15T10:30:00Z" callback_url: type: string description: "If set on [Create Document](/api-reference/documents/create-document), Tavus POSTs status updates here while this recrawl runs through completion." example: "https://your-server.com/webhook" tags: type: array description: "Array of document tags" items: type: string example: ["website", "company"] crawl_config: type: object description: "The crawl configuration being used for the recrawl" properties: depth: type: integer example: 2 max_pages: type: integer example: 10 crawled_urls: type: array nullable: true description: "List of URLs from the previous crawl (will be updated when recrawl completes)" items: type: string example: ["https://docs.example.com/", "https://docs.example.com/getting-started"] last_crawled_at: type: string nullable: true description: "ISO 8601 timestamp of the previous crawl" example: "2024-01-01T12:05:00Z" crawl_count: type: integer description: "Number of times the document has been crawled (will increment when recrawl completes)" example: 1 "400": description: "Bad Request - Validation error" content: application/json: schema: type: object properties: error: type: string description: "The error message" example: "Document was not created with crawl configuration" "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: message: type: string description: "The error message" example: "Document not found" "409": description: "Conflict - Document state prevents recrawl" content: application/json: schema: type: object properties: error: type: string description: "The error message" example: "Document must be in 'ready' or 'error' state to recrawl, current status: processing" "429": description: "Too Many Requests - Rate limit exceeded or cooldown period" content: application/json: schema: type: object properties: error: type: string description: "The error message" example: "Recrawl cooldown: please wait 45 minutes before recrawling this document." security: - apiKey: [] /v2/pronunciation-dictionaries: post: tags: - Pronunciation Dictionaries summary: Create Pronunciation Dictionary description: | Create a [pronunciation dictionary](/sections/conversational-video-interface/persona/pronunciation-dictionaries) with custom rules for controlling how words are spoken. Rules are automatically synced to both Cartesia and ElevenLabs so they work regardless of which TTS engine your persona uses. operationId: createPronunciationDictionary requestBody: content: application/json: schema: type: object properties: name: type: string description: "Name of the pronunciation dictionary. Max 255 characters." example: "Brand Terms" rules: type: array description: "List of pronunciation rules. Duplicate `text` values are not allowed. You can omit rules at creation and add them later via [Update Pronunciation Dictionary](/api-reference/pronunciation-dictionaries/update-pronunciation-dictionary)." items: type: object properties: text: type: string description: "The word or phrase to match. Max 200 characters." example: "Tavus" pronunciation: type: string description: "How the text should be pronounced. For `alias` type, this is the replacement text. For `ipa` type, this is an IPA string (raw or pipe-delimited). Max 500 characters." example: "TAH-vus" type: type: string description: "Rule type. One of `alias` or `ipa`." enum: ["alias", "ipa"] example: "alias" case_sensitive: type: boolean description: "Whether matching is case-sensitive." default: false example: false word_boundaries: type: boolean description: "Whether to match only whole words." default: true example: true required: - text - pronunciation - type example: - text: "Tavus" pronunciation: "TAH-vus" type: "alias" required: - name responses: "201": description: "Pronunciation dictionary created successfully" content: application/json: schema: type: object properties: pronunciation_dictionary_id: type: string description: "Unique identifier for the pronunciation dictionary." example: "pd_abc123def456gh" name: type: string description: "Name of the pronunciation dictionary." example: "Brand Terms" rules: type: array description: "List of pronunciation rules." items: type: object properties: text: type: string example: "Tavus" pronunciation: type: string example: "TAH-vus" type: type: string enum: ["alias", "ipa"] example: "alias" case_sensitive: type: boolean example: false word_boundaries: type: boolean example: true rules_count: type: integer description: "Number of rules in the dictionary." example: 1 created_at: type: string description: "ISO 8601 timestamp of when the dictionary was created." example: "2025-01-15T10:30:00Z" updated_at: type: string description: "ISO 8601 timestamp of when the dictionary was last updated." example: "2025-01-15T10:30:00Z" "400": description: "Bad Request" content: application/json: schema: type: object properties: error: type: string description: "The error message" example: "Invalid request: 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: - Pronunciation Dictionaries summary: List Pronunciation Dictionaries description: | List all pronunciation dictionaries for the authenticated user with pagination. operationId: listPronunciationDictionaries parameters: - in: query name: limit schema: type: integer minimum: 1 maximum: 100 default: 10 description: "Number of results per page. Range: 1-100." example: 10 - in: query name: page schema: type: integer default: 0 description: "Zero-based page number." example: 0 - in: query name: sort schema: type: string enum: ["asc", "desc"] default: "desc" description: "Sort order by creation date." example: "desc" responses: "200": description: "List of pronunciation dictionaries" content: application/json: schema: type: object properties: data: type: array description: "Dictionaries for the current page; use `total_count`, `page`, and `limit` with the query parameters for pagination." items: type: object properties: pronunciation_dictionary_id: type: string description: "Unique identifier for the pronunciation dictionary." example: "pd_abc123def456gh" name: type: string description: "Name of the pronunciation dictionary." example: "Brand Terms" rules_count: type: integer description: "Number of rules in the dictionary. List responses omit the full `rules` array; use [Get Pronunciation Dictionary](/api-reference/pronunciation-dictionaries/get-pronunciation-dictionary) to retrieve rules." example: 3 created_at: type: string description: "ISO 8601 timestamp of when the dictionary was created." example: "2025-01-15T10:30:00Z" updated_at: type: string description: "ISO 8601 timestamp of when the dictionary was last updated." example: "2025-01-15T10:30:00Z" total_count: type: integer description: "Total number of pronunciation dictionaries for the user" example: 2 page: type: integer description: "Current page number" example: 0 limit: type: integer description: "Number of dictionaries per page" example: 10 "401": description: "Unauthorized" content: application/json: schema: type: object properties: message: type: string description: "The error message" example: "Invalid access token" security: - apiKey: [] /v2/pronunciation-dictionaries/{dictionary_id}: get: tags: - Pronunciation Dictionaries summary: Get Pronunciation Dictionary description: | Retrieve a pronunciation dictionary by its ID, including all rules. operationId: getPronunciationDictionary parameters: - in: path name: dictionary_id required: true schema: type: string description: "The unique identifier of the pronunciation dictionary." example: "pd_abc123def456gh" responses: "200": description: "Pronunciation dictionary details" content: application/json: schema: type: object properties: pronunciation_dictionary_id: type: string description: "Unique identifier for the pronunciation dictionary." example: "pd_abc123def456gh" name: type: string description: "Name of the pronunciation dictionary." example: "Brand Terms" rules: type: array description: "List of pronunciation rules." items: type: object properties: text: type: string example: "Tavus" pronunciation: type: string example: "TAH-vus" type: type: string enum: ["alias", "ipa"] example: "alias" case_sensitive: type: boolean example: false word_boundaries: type: boolean example: true rules_count: type: integer description: "Number of rules in the dictionary." example: 1 created_at: type: string description: "ISO 8601 timestamp of when the dictionary was created." example: "2025-01-15T10:30:00Z" updated_at: type: string description: "ISO 8601 timestamp of when the dictionary was last updated." example: "2025-01-15T10:30:00Z" "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: message: type: string description: "The error message" example: "Pronunciation dictionary not found" security: - apiKey: [] patch: tags: - Pronunciation Dictionaries summary: Update Pronunciation Dictionary description: | Update a pronunciation dictionary's name or rules using [JSON Patch](https://jsonpatch.com/) format (RFC 6902). Supported mutable fields are `name` and `rules`. operationId: patchPronunciationDictionary parameters: - in: path name: dictionary_id required: true schema: type: string description: "The unique identifier of the pronunciation dictionary." example: "pd_abc123def456gh" requestBody: description: | Read-only fields like `pronunciation_dictionary_id`, `created_at`, and `updated_at` are silently ignored. If all operations target read-only fields or result in no changes, the endpoint returns `304`. When rules are updated, all personas referencing this dictionary are automatically updated with the new provider-specific pronunciation data. **Note:** Updating rules replaces the entire rules array. There is no way to add or remove individual rules — provide the complete updated list. For example: ```json [ { "op": "replace", "path": "/name", "value": "Updated Brand Terms" }, { "op": "replace", "path": "/rules", "value": [ { "text": "Tavus", "pronunciation": "TAH-vus", "type": "alias" } ]} ] ``` 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: "A JSON Pointer string that references a location within the target document where the operation is performed. Supported paths: `/name`, `/rules`." example: "/name" value: description: "The value to be used within the operation. Required unless using `remove`." required: - op - path examples: Update name: value: - op: "replace" path: "/name" value: "Updated Brand Terms" Update rules: value: - op: "replace" path: "/rules" value: - text: "Tavus" pronunciation: "TAH-vus" type: "alias" - text: "CVI" pronunciation: "conversational video interface" type: "alias" Update both: value: - op: "replace" path: "/name" value: "Updated Brand Terms" - op: "replace" path: "/rules" value: - text: "Tavus" pronunciation: "TAH-vus" type: "alias" responses: "200": description: "Pronunciation dictionary updated successfully" content: application/json: schema: type: object properties: pronunciation_dictionary_id: type: string description: "Unique identifier for the pronunciation dictionary." example: "pd_abc123def456gh" name: type: string description: "Name of the pronunciation dictionary." example: "Updated Brand Terms" rules: type: array description: "List of pronunciation rules." items: type: object properties: text: type: string example: "Tavus" pronunciation: type: string example: "TAH-vus" type: type: string enum: ["alias", "ipa"] example: "alias" case_sensitive: type: boolean example: false word_boundaries: type: boolean example: true rules_count: type: integer description: "Number of rules in the dictionary." example: 1 created_at: type: string description: "ISO 8601 timestamp of when the dictionary was created." example: "2025-01-15T10:30:00Z" updated_at: type: string description: "ISO 8601 timestamp of when the dictionary was last updated." example: "2025-01-15T12:00:00Z" "304": description: "No changes were made to the pronunciation dictionary" "400": description: "Bad Request" content: application/json: schema: type: object properties: error: type: string description: "The error message" example: "Invalid request: duplicate text values in rules" "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: message: type: string description: "The error message" example: "Pronunciation dictionary not found" "422": description: "Invalid JSON patch format" content: application/json: schema: type: object properties: message: type: string description: "The error message" example: "Invalid JSON patch format" security: - apiKey: [] delete: tags: - Pronunciation Dictionaries summary: Delete Pronunciation Dictionary description: | Permanently delete a pronunciation dictionary and remove it from all linked personas. operationId: deletePronunciationDictionary parameters: - in: path name: dictionary_id required: true schema: type: string description: | The unique identifier of the pronunciation dictionary to delete. **Warning:** This action is permanent. The dictionary is deleted from both Cartesia and ElevenLabs, and all personas referencing it will have their `pronunciation_dictionary_id` set to `null` and provider-specific pronunciation settings removed from `voice_settings`. example: "pd_abc123def456gh" responses: "204": description: "NO CONTENT - Pronunciation dictionary deleted successfully" "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: message: type: string description: "The error message" example: "Pronunciation dictionary not found" security: - apiKey: [] /v2/transcriptions/{transcription_id}: get: tags: - Transcriptions summary: Get Transcription description: | This endpoint returns a single transcription by its unique identifier. operationId: getTranscription parameters: - in: path name: transcription_id required: true schema: type: string description: "A unique identifier for the transcription." responses: "200": description: "" content: application/json: schema: type: object properties: transcription_id: type: string example: "t0108f2d24k2a" description: "A unique identifier for the transcription." file_url: type: string description: "The URL of the file that was transcribed." example: "https://example.com/video.mp4" text: type: string description: "The transcribed text from the video." status: type: string description: "The status of the transcription." created_at: type: string description: "The date and time the transcription was created." security: - apiKey: [] delete: tags: - Transcriptions summary: Delete Transcription description: | This endpoint deletes a single transcription by its unique identifier. operationId: deleteTranscription parameters: - in: path name: transcription_id required: true schema: type: string description: "A unique identifier for the transcription." responses: "204": description: "" security: - apiKey: [] tags: - name: Videos - name: Replicas - name: Voices - name: Conversations - name: Personas - name: Pronunciation Dictionaries - name: Replacements - name: Transcriptions - name: Documents components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key schemas: utterance: description: | #### Outbound: Tavus tells you who spoke and the full utterance text for that turn (from when they started until they finished, which may be more than one sentence). Compare with [`conversation.utterance.streaming`](/sections/event-schemas/conversation-utterance-streaming) for progressive replica text and interruption flags. type: object example: message_type: "conversation" event_type: "conversation.utterance" seq: 600 conversation_id: "your-conversation-id" inference_id: "550e8400-e29b-41d4-a716-446655440000" turn_idx: 8 properties: role: "replica" speech: "Full assistant reply for this inference." user_audio_analysis: "optional short summary" user_visual_analysis: "optional short summary" interrupted: true properties: message_type: type: string description: "`conversation` for conversation-layer app messages." example: "conversation" event_type: type: string description: "`conversation.utterance`." example: "conversation.utterance" timestamp: type: number description: "Unix timestamp (seconds since epoch) indicating when this event was created. Use this to build timestamped transcripts or reconstruct the timeline of a conversation." example: 1746000000.123 seq: type: integer description: "Monotonic per event; a higher `seq` was emitted later. Use with `turn_idx` as in [Event ordering and turn tracking](/sections/conversational-video-interface/interactions-protocols/overview#event-ordering-and-turn-tracking)." example: 42 conversation_id: type: string description: "The unique identifier for the conversation." example: "c123456" inference_id: type: string description: "This is a unique identifier for a given utterance. In this case, it will be the utterance the replica is speaking." example: "83294d9f-8306-491b-a284-791f56c8383f" turn_idx: type: integer description: "Turn index; increments when `conversation.respond` is processed. Groups utterances, tool calls, and speaking-state events for the same turn. See [Event ordering and turn tracking](/sections/conversational-video-interface/interactions-protocols/overview#event-ordering-and-turn-tracking)." example: 3 properties: type: object description: "Omitted when empty. When the speaker is the user and the persona uses Raven-1, optional `user_audio_analysis` / `user_visual_analysis` may appear when non-empty." properties: role: type: string description: "Typically `replica` or `user`." example: "replica" speech: type: string description: "Plain text after server-side sanitization. For `replica`, this is the full LLM response text for the inference (which may differ from words actually spoken if the user barged in); internal LLM chat history is truncated to what was actually spoken on interruption." example: "Full assistant reply for this inference." user_audio_analysis: type: string description: "Optional; omitted when empty. Short summary of tone/delivery when available (e.g. Raven-1)." example: "optional short summary" user_visual_analysis: type: string description: "Optional; omitted when empty. Short visual/demeanor summary when available (e.g. Raven-1)." example: "optional short summary" interrupted: type: boolean description: "Only included when `true` (barge-in / interrupted completion)." example: true required: - role - speech conversation_utterance_streaming: description: | #### Outbound: Tavus sends each streaming chunk so you can show what is being said in real time as the accumulated text grows during the turn. Contrast with [`conversation.utterance`](/sections/event-schemas/conversation-utterance), which delivers the full turn text at once rather than streaming chunks. type: object example: message_type: "conversation" event_type: "conversation.utterance.streaming" seq: 500 conversation_id: "your-conversation-id" inference_id: "550e8400-e29b-41d4-a716-446655440000" turn_idx: 7 properties: role: "replica" speech: "Here is everything said so far in this turn." content_index: 3 final: false is_interrupted: false properties: message_type: type: string description: "`conversation` for conversation-layer app messages." example: "conversation" event_type: type: string description: "`conversation.utterance.streaming`." example: "conversation.utterance.streaming" timestamp: type: number description: "Unix timestamp (seconds since epoch) indicating when this event was created. Use this to build timestamped transcripts or reconstruct the timeline of a conversation." example: 1746000000.123 seq: type: integer description: "Monotonic per event; a higher `seq` was emitted later. Use with `turn_idx` as in [Event ordering and turn tracking](/sections/conversational-video-interface/interactions-protocols/overview#event-ordering-and-turn-tracking)." example: 42 conversation_id: type: string description: "The unique identifier for the conversation." example: "c123456" inference_id: type: string description: "A unique identifier for the replica's current inference turn. Can be used to correlate with other events such as `conversation.utterance` and `conversation.replica.started_speaking`." example: "83294d9f-8306-491b-a284-791f56c8383f" turn_idx: type: integer description: "Turn index; increments when `conversation.respond` is processed. Groups utterances, tool calls, and speaking-state events for the same turn. See [Event ordering and turn tracking](/sections/conversational-video-interface/interactions-protocols/overview#event-ordering-and-turn-tracking)." example: 3 properties: type: object description: "Replica and user streaming share this shape; `is_interrupted` appears on replica messages when relevant." properties: role: type: string description: "`replica` or `user` (fixed per frame class in the transport layer)." example: "replica" speech: type: string description: "Full accumulated transcript for this turn so far (partial until `final` is true)." example: "Here is everything said so far in this turn." content_index: type: integer description: "Monotonic index per streaming sequence for ordering." example: 3 final: type: boolean description: "`true` when no further chunks for this turn." example: false is_interrupted: type: boolean description: "Replica only: barge-in / interrupted completion. Omitted on user streaming (implicit non-interrupted behavior)." example: false required: - role - speech - content_index - final perception_analysis: description: | #### Outbound: After the conversation ends and the replica has summarized what was visually observed, Tavus sends that full perception analysis (Raven-1 personas). Requires Raven-style perception; see [Perception — end-of-call perception analysis](/sections/conversational-video-interface/persona/perception#end-of-call-perception-analysis). type: object example: message_type: "conversation" event_type: "conversation.perception_analysis" seq: 128 conversation_id: "your-conversation-id" inference_id: "550e8400-e29b-41d4-a716-446655440000" turn_idx: 3 properties: analysis: "Bulleted summary of recent visual / ambient observations." properties: message_type: type: string description: "`conversation` for conversation-layer app messages." example: "conversation" event_type: type: string description: "`conversation.perception_analysis`." example: "conversation.perception_analysis" timestamp: type: number description: "Unix timestamp (seconds since epoch) indicating when this event was created. Use this to build timestamped transcripts or reconstruct the timeline of a conversation." example: 1746000000.123 seq: type: integer description: "Monotonic per event; a higher `seq` was emitted later. Use with `turn_idx` as in [Event ordering and turn tracking](/sections/conversational-video-interface/interactions-protocols/overview#event-ordering-and-turn-tracking)." example: 42 conversation_id: type: string description: "The unique identifier for the conversation." example: "c123456" inference_id: type: string description: "Present when the frame carries a UUID `id`." example: "550e8400-e29b-41d4-a716-446655440000" turn_idx: type: integer description: "Turn index; increments when `conversation.respond` is processed. Groups utterances, tool calls, and speaking-state events for the same turn. See [Event ordering and turn tracking](/sections/conversational-video-interface/interactions-protocols/overview#event-ordering-and-turn-tracking)." example: 3 properties: type: object description: "Omitted when empty." properties: analysis: type: string description: "Full text summary from perception (Raven / perception-enabled personas)." example: "Bulleted summary of recent visual / ambient observations." required: - analysis perception_tool_call: description: | #### Outbound: Tavus broadcasts when Raven triggers a perception tool from visual or audio input. Configure perception tools: [Perception tool calling](/sections/conversational-video-interface/persona/perception-tool) and [Perception](/sections/conversational-video-interface/persona/perception). type: object example: message_type: "conversation" event_type: "conversation.perception_tool_call" seq: 129 conversation_id: "your-conversation-id" turn_idx: 3 properties: name: "describe_scene" arguments: '{"detail":"high"}' modality: "audio" frames: - { "uri": "https://example.invalid/frame" } properties: message_type: type: string description: "`conversation` for conversation-layer app messages." example: "conversation" event_type: type: string description: "`conversation.perception_tool_call`." example: "conversation.perception_tool_call" timestamp: type: number description: "Unix timestamp (seconds since epoch) indicating when this event was created. Use this to build timestamped transcripts or reconstruct the timeline of a conversation." example: 1746000000.123 seq: type: integer description: "Monotonic per event; a higher `seq` was emitted later. Use with `turn_idx` as in [Event ordering and turn tracking](/sections/conversational-video-interface/interactions-protocols/overview#event-ordering-and-turn-tracking)." example: 42 conversation_id: type: string description: "The unique identifier for the conversation." example: "c123456" turn_idx: type: integer description: "Turn index; increments when `conversation.respond` is processed. Groups utterances, tool calls, and speaking-state events for the same turn. See [Event ordering and turn tracking](/sections/conversational-video-interface/interactions-protocols/overview#event-ordering-and-turn-tracking)." example: 3 properties: type: object description: "Tool name, modality from the perception step, arguments as returned by the model, optional non-empty `frames` for multimodal metadata." properties: modality: type: string description: "Perception modality for this call (e.g. `audio` or `vision`)." enum: - "vision" - "audio" example: "audio" name: type: string description: "Tool function name." example: "describe_scene" arguments: description: "As returned by the perception model: JSON string or structured object." oneOf: - type: string example: '{"detail":"high"}' - type: object additionalProperties: true example: { "hat_type": "baseball cap" } frames: type: array description: "Included only when non-empty; frame metadata (e.g. `uri`, base64 `data` + `mime_type`, or other keys)." items: type: object additionalProperties: true example: uri: "https://example.invalid/frame" required: - name - arguments - modality tool_call: description: | #### Outbound: Tavus signals an LLM tool call your client should run. Configure tools on the persona: [LLM tool calling](/sections/conversational-video-interface/persona/llm-tool). type: object example: message_type: "conversation" event_type: "conversation.tool_call" seq: 310 conversation_id: "your-conversation-id" inference_id: "550e8400-e29b-41d4-a716-446655440000" turn_idx: 5 properties: name: "get_weather" arguments: '{"location":"NYC"}' tool_call_id: "call_abc123" properties: message_type: type: string description: "`conversation` for conversation-layer app messages." example: "conversation" event_type: type: string description: "`conversation.tool_call`." example: "conversation.tool_call" timestamp: type: number description: "Unix timestamp (seconds since epoch) indicating when this event was created. Use this to build timestamped transcripts or reconstruct the timeline of a conversation." example: 1746000000.123 seq: type: integer description: "Monotonic per event; a higher `seq` was emitted later. Use with `turn_idx` as in [Event ordering and turn tracking](/sections/conversational-video-interface/interactions-protocols/overview#event-ordering-and-turn-tracking)." example: 42 conversation_id: type: string description: "The unique identifier for the conversation." example: "c123456" inference_id: type: string description: "This is a unique identifier for a given utterance. In this case, it will be the user utterance that triggered the tool call." example: "83294d9f-8306-491b-a284-791f56c8383f" turn_idx: type: integer description: "Turn index; increments when `conversation.respond` is processed. Groups utterances, tool calls, and speaking-state events for the same turn. See [Event ordering and turn tracking](/sections/conversational-video-interface/interactions-protocols/overview#event-ordering-and-turn-tracking)." example: 3 properties: type: object description: "Function name and serialized arguments from the LLM. Tavus does not execute tools server-side—your app performs the call per your integration." properties: name: type: string description: "Function / tool name." example: "get_weather" arguments: type: string description: "Serialized tool arguments (typically a JSON string from the LLM)." example: '{"location":"NYC"}' tool_call_id: type: string description: "Correlation id for the tool call; omitted when empty." example: "call_abc123" required: - name - arguments user: description: | #### Outbound: Tavus tells you when the user has just started or stopped speaking so you can drive UI or backend actions at those moments. type: object example: message_type: "conversation" event_type: "conversation.user.started_speaking" seq: 400 conversation_id: "your-conversation-id" inference_id: "550e8400-e29b-41d4-a716-446655440000" turn_idx: 6 properties: message_type: type: string description: "`conversation` for conversation-layer app messages." example: "conversation" event_type: type: string description: "`conversation.user.started_speaking` or `conversation.user.stopped_speaking`." example: "conversation.user.started_speaking" enum: - "conversation.user.started_speaking" - "conversation.user.stopped_speaking" timestamp: type: number description: "Unix timestamp (seconds since epoch) indicating when this event was created. Use this to build timestamped transcripts or reconstruct the timeline of a conversation." example: 1746000000.123 seq: type: integer description: "Monotonic per event; a higher `seq` was emitted later. Use with `turn_idx` as in [Event ordering and turn tracking](/sections/conversational-video-interface/interactions-protocols/overview#event-ordering-and-turn-tracking)." example: 42 conversation_id: type: string description: "Omitted when empty." example: "your-conversation-id" inference_id: type: string description: "UUID for this utterance when present; with speculative inference the id may change while the user is still speaking, so `user.started_speaking` inference_id often will not match later `conversation.utterance` / tool_call ids." example: "550e8400-e29b-41d4-a716-446655440000" turn_idx: type: integer description: "Turn index; increments when `conversation.respond` is processed. Groups utterances, tool calls, and speaking-state events for the same turn. See [Event ordering and turn tracking](/sections/conversational-video-interface/interactions-protocols/overview#event-ordering-and-turn-tracking)." example: 6 replica: description: | #### Outbound: Tavus tells you when the replica has just started or stopped speaking—use stopped events for how long it spoke and whether the user interrupted. type: object example: message_type: "conversation" event_type: "conversation.replica.stopped_speaking" seq: 201 conversation_id: "your-conversation-id" inference_id: "550e8400-e29b-41d4-a716-446655440000" turn_idx: 4 properties: duration: 4.512 interrupted: false properties: message_type: type: string description: "`conversation` for conversation-layer app messages." example: "conversation" event_type: type: string description: "`conversation.replica.started_speaking` or `conversation.replica.stopped_speaking`." example: "conversation.replica.stopped_speaking" enum: - "conversation.replica.started_speaking" - "conversation.replica.stopped_speaking" timestamp: type: number description: "Unix timestamp (seconds since epoch) indicating when this event was created. Use this to build timestamped transcripts or reconstruct the timeline of a conversation." example: 1746000000.123 seq: type: integer description: "Monotonic per event; a higher `seq` was emitted later. Use with `turn_idx` as in [Event ordering and turn tracking](/sections/conversational-video-interface/interactions-protocols/overview#event-ordering-and-turn-tracking)." example: 201 conversation_id: type: string description: "Omitted when empty." example: "your-conversation-id" inference_id: type: string description: "UUID for the replica utterance when present at envelope level (matches transport `id`). Correlate with [`conversation.utterance`](/sections/event-schemas/conversation-utterance) and [`conversation.tool_call`](/sections/event-schemas/conversation-toolcall)." example: "550e8400-e29b-41d4-a716-446655440000" turn_idx: type: integer description: "Turn index; increments when `conversation.respond` is processed. Groups utterances, tool calls, and speaking-state events for the same turn. See [Event ordering and turn tracking](/sections/conversational-video-interface/interactions-protocols/overview#event-ordering-and-turn-tracking)." example: 4 properties: type: object description: "Omitted for `started_speaking`. On `stopped_speaking`, includes how long the replica spoke and whether stop was due to interruption." properties: duration: type: number nullable: true description: "Seconds (rounded), or `null` if timing unavailable." example: 4.512 interrupted: type: boolean description: "`true` if stop was due to interruption / mismatch vs natural end." example: false required: - duration - interrupted speaking: description: | #### Outbound: Tavus notifies you when the replica or the user starts or stops speaking, using one event stream and a `properties.role` field instead of separate user- versus replica-only events. `conversation.started_speaking` fires when either party begins speaking; `conversation.stopped_speaking` when either stops. type: object example: message_type: "conversation" event_type: "conversation.stopped_speaking" seq: 601 inference_id: "83294d9f-8306-491b-a284-791f56c8383f" turn_idx: 3 properties: role: "replica" interrupted: false duration: 2.341 properties: message_type: type: string description: "`conversation` for conversation-layer app messages." example: "conversation" event_type: type: string description: "`conversation.started_speaking` or `conversation.stopped_speaking`." example: "conversation.started_speaking" enum: - "conversation.started_speaking" - "conversation.stopped_speaking" timestamp: type: number description: "Unix timestamp (seconds since epoch) indicating when this event was created. Use this to build timestamped transcripts or reconstruct the timeline of a conversation." example: 1746000000.123 seq: type: integer description: "Monotonic per event; a higher `seq` was emitted later. Use with `turn_idx` as in [Event ordering and turn tracking](/sections/conversational-video-interface/interactions-protocols/overview#event-ordering-and-turn-tracking)." example: 42 inference_id: type: string description: "Identifier for correlating this speaking span with [`conversation.utterance`](/sections/event-schemas/conversation-utterance), [`conversation.tool_call`](/sections/event-schemas/conversation-toolcall), and other events from the same turn." example: "83294d9f-8306-491b-a284-791f56c8383f" turn_idx: type: integer description: "Turn index; increments when `conversation.respond` is processed. Groups utterances, tool calls, and speaking-state events for the same turn. See [Event ordering and turn tracking](/sections/conversational-video-interface/interactions-protocols/overview#event-ordering-and-turn-tracking)." example: 3 properties: type: object description: | Always includes `role` (`"replica"` or `"user"`) identifying who started or stopped speaking. On `conversation.stopped_speaking` only, also includes `interrupted` (whether the speaker was cut off mid-speech before finishing naturally) and `duration` (how long they spoke, in seconds; may be `null` if the start time could not be determined). properties: role: type: string description: "`replica` if the Tavus replica is the speaker, `user` if the end user is the speaker." enum: - "replica" - "user" example: "replica" interrupted: type: boolean description: "Whether the speaker was interrupted before finishing naturally. Only present on `conversation.stopped_speaking`. `true` means they were cut off mid-speech." example: false duration: type: number nullable: true description: "How long the speaker was speaking, in seconds. Only present on `conversation.stopped_speaking`. May be `null` in rare cases where the start time could not be determined." example: 2.341 required: - role sensitivity: description: | #### Inbound: Broadcast this to Tavus to update VAD sensitivity using `participant_pause_sensitivity` or `participant_interrupt_sensitivity`—how long you can pause before the replica replies versus how easily you can interrupt it. type: object example: message_type: "conversation" event_type: "conversation.sensitivity" conversation_id: "your-conversation-id" properties: participant_interrupt_sensitivity: "medium" properties: message_type: type: string description: "`conversation` for conversation-layer app messages." example: "conversation" event_type: type: string description: "`conversation.sensitivity`." example: "conversation.sensitivity" conversation_id: type: string description: "The unique identifier for the conversation." example: "your-conversation-id" properties: type: object description: "Send exactly one of the two keys per message (not both). Enum values are listed on each field. UX mapping overlaps [Conversational Flow](/sections/conversational-video-interface/persona/conversational-flow) (`turn_taking_patience`, `replica_interruptibility`)." properties: participant_pause_sensitivity: type: string description: "How long a pause before the replica responds." enum: - "superlow" - "verylow" - "low" - "medium" - "high" - "auto" example: "medium" participant_interrupt_sensitivity: type: string description: "How readily the user’s speech interrupts the replica." enum: - "superlow" - "verylow" - "low" - "medium" - "high" - "auto" example: "medium" overwrite_llm_context: description: | #### Inbound: Broadcast this to Tavus to overwrite the conversational context the replica uses, or set that context if none was provided when the conversation was created. type: object example: message_type: "conversation" event_type: "conversation.overwrite_llm_context" conversation_id: "your-conversation-id" properties: context: "[]" properties: message_type: type: string description: "`conversation` for conversation-layer app messages." example: "conversation" event_type: type: string description: "`conversation.overwrite_llm_context`." example: "conversation.overwrite_llm_context" conversation_id: type: string description: "The unique identifier for the conversation." example: "your-conversation-id" properties: type: object properties: context: type: string description: "New context string that replaces the replica’s current conversational context (if none was set at conversation creation, this becomes the initial context). See [Create Conversation](/api-reference/conversations/create-conversation) for `conversational_context` at session start." example: "[]" required: - context append_llm_context: description: | #### Inbound: Broadcast this to Tavus to append conversational context the replica should use, or establish it if none was set at conversation creation, and optionally mark a job completed. type: object example: message_type: "conversation" event_type: "conversation.append_llm_context" conversation_id: "your-conversation-id" properties: context: "Additional system context for this turn." job_status: "completed" properties: message_type: type: string description: "`conversation` for conversation-layer app messages." example: "conversation" event_type: type: string description: "`conversation.append_llm_context`." example: "conversation.append_llm_context" conversation_id: type: string description: "The unique identifier for the conversation." example: "your-conversation-id" properties: type: object properties: context: type: string description: "Appended as LLM context; if no `conversational_context` existed from conversation creation, this string seeds it. See [Create Conversation](/api-reference/conversations/create-conversation) for `conversational_context` at session start." example: "Additional system context for this turn." job_status: type: string description: "When set to `completed`, a job-completed event is queued internally." example: "completed" required: - context echo: description: | #### Inbound: Broadcast this to Tavus so the replica speaks exactly what you supply—`text` and base64 `audio` are set under `properties` (`modality`). type: object example: message_type: "conversation" event_type: "conversation.echo" conversation_id: "your-conversation-id" properties: modality: "text" text: "Hello from an external echo." done: true properties: message_type: type: string description: "`conversation` for conversation-layer app messages." example: "conversation" event_type: type: string description: "`conversation.echo`." example: "conversation.echo" conversation_id: type: string description: "The unique identifier for the conversation." example: "your-conversation-id" properties: type: object properties: modality: type: string description: "`text` (default) or `audio`." enum: - "text" - "audio" example: "text" text: type: string description: "Chunk of assistant text when `modality` is `text` (default)." example: "Hello from an external echo." audio: type: string description: "Base64 audio when `modality` is `audio` (PCM or pipeline-specific encoding)." example: "" sample_rate: type: integer description: "Sample rate for audio; defaults to `16000` when `modality` is `audio`." default: 16000 example: 16000 inference_id: type: string description: "If omitted, server generates a UUID; if provided, normalized to a stable MD5-derived UUID for streaming chunks across multiple echo frames." example: "my-stable-client-id" done: type: boolean description: "Default `true` for text and `false` for audio in server defaults; set explicitly when streaming—keep `false` until the final audio chunk, then `true` or audio may be cut off." example: true realtime_api: description: | #### This is no longer supported by Tavus. Previously: forward OpenAI realtime event bodies through this channel so Tavus could relay realtime session updates to OpenAI. deprecated: true type: object properties: message_type: type: string description: "`conversation` for conversation-layer app messages." example: "conversation" event_type: type: string description: "`conversation.realtime_api`." example: "conversation.realtime_api" conversation_id: type: string description: "The unique identifier for the conversation." example: "c123456" properties: type: object description: "The properties act as a way to forward realtime events from Tavus to OpenAI. Pass your OpenAI realtime event body in here." example: { "type": "session.update", "session": { "instructions": "You are a helpful assistant. Only respond in French from now on.", }, } interrupt: description: | #### Inbound: Broadcast this to Tavus to externally interrupt the replica so it stops talking—commonly used with [Echo](/sections/event-schemas/conversation-echo). type: object example: message_type: "conversation" event_type: "conversation.interrupt" conversation_id: "your-conversation-id" properties: message_type: type: string description: "`conversation` for conversation-layer app messages." example: "conversation" event_type: type: string description: "`conversation.interrupt`." example: "conversation.interrupt" conversation_id: type: string description: "Omitted when empty." example: "your-conversation-id" respond: description: | #### Inbound: Broadcast text to Tavus for the replica to respond to as if the user had just spoken that transcript in the conversation. type: object example: message_type: "conversation" event_type: "conversation.respond" conversation_id: "your-conversation-id" properties: text: "User message as if they had just finished speaking." properties: message_type: type: string description: "`conversation` for conversation-layer app messages." example: "conversation" event_type: type: string description: "`conversation.respond`." example: "conversation.respond" conversation_id: type: string description: "The unique identifier for the conversation." example: "your-conversation-id" properties: type: object properties: text: type: string description: "Treated as a completed user transcript: creates a new inference id, clears talking state, queues user-done and a user utterance frame with this text." example: "User message as if they had just finished speaking." required: - text recording_storage_config: type: object description: | Provider-agnostic recording storage configuration. Supports Amazon S3 (any region), Google Cloud Storage via Workload Identity Federation, and Azure Blob Storage via Entra ID Federated Credentials. All fields are non-secret identifiers — every provider uses federated identity, so you configure a trust relationship on your side and pass identifiers to us, never credentials. Use this in place of the legacy `recording_s3_bucket_name` / `recording_s3_bucket_region` / `aws_assume_role_arn` fields. Existing customers using the flat fields continue to work unchanged. required: - provider properties: provider: type: string enum: [s3, gcs, azure_blob] description: "Storage provider discriminator." example: "s3" bucket_name: type: string description: "Bucket name. Used when `provider` is `s3` or `gcs`." example: "conversation-recordings" bucket_region: type: string description: | AWS region (e.g. `us-east-1`, `eu-north-1`). Used when `provider` is `s3`. Any AWS region is supported — Daily-supported regions get a direct write; others are routed through a Tavus-managed Cloudflare Worker that copies the recording into your bucket via `sts:AssumeRole`. example: "us-east-1" assume_role_arn: type: string description: "IAM role ARN that Tavus assumes to write to your bucket. Used when `provider` is `s3`." example: "arn:aws:iam::123456789012:role/TavusRecordingWriter" external_id: type: string description: "Optional `ExternalId` value to include in the AssumeRole call. Used when `provider` is `s3`." example: "tavus-acct-abc123" project_id: type: string description: "GCP project ID containing the bucket. Used when `provider` is `gcs`." example: "my-gcp-project" workload_identity_provider: type: string description: | Resource name of your Workload Identity Pool Provider — without the `//iam.googleapis.com/` prefix (Tavus prepends it). Used when `provider` is `gcs`. example: "projects/123456/locations/global/workloadIdentityPools/tavus-pool/providers/tavus-cf-worker" service_account_email: type: string description: "Email of the service account that has `storage.objects.create` on the bucket. Used when `provider` is `gcs`." example: "tavus-recording-writer@my-gcp-project.iam.gserviceaccount.com" storage_account: type: string description: "Azure storage account name. Used when `provider` is `azure_blob`." example: "myrecordingsaccount" container: type: string description: "Container within the storage account. Used when `provider` is `azure_blob`." example: "conversation-recordings" tenant_id: type: string description: "Azure AD tenant UUID. Used when `provider` is `azure_blob`." example: "11111111-2222-3333-4444-555555555555" client_id: type: string description: "App Registration client UUID. Used when `provider` is `azure_blob`." example: "66666666-7777-8888-9999-000000000000" security: - apiKey: []