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 face 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 face 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`. (`replica_id` is the face resource ID - the same value returned by `GET /v2/faces`.) 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 face only. To learn more about generating videos with faces, 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: >- The Face ID to render in the video (same resource as `face_id` on `/v2/faces`; this endpoint still accepts `replica_id`). 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 faces. 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 face 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/faces: get: tags: - Faces summary: List Faces description: > Returns all faces (photorealistic likenesses trained with Phoenix) created by the account associated with the API key. **Legacy:** `/v2/replicas` and `replica_id` / `replica_ids` remain supported as aliases. operationId: listFaces parameters: - in: query name: limit schema: type: integer description: The number of faces 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 face data such as the face type. - in: query name: face_type schema: type: string enum: - user - system description: >- If set to user, the response will only include user faces. If set to system, the response will only include stock faces. - in: query name: face_ids schema: type: string description: >- A comma separated list of face ids to filter the response by. Example: `face_ids=r90bbd427f71` - in: query name: model_name schema: type: string description: >- Filter the list to faces 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: >- Faces for the current page; use `total_count` for the full count under the applied filters. items: type: object properties: face_id: type: string example: r90bbd427f71 description: A unique identifier for the face. face_name: type: string example: My Face description: The name of the face. thumbnail_video_url: type: string description: >- A direct link to the video that will be used as the thumbnail for the face. 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 face_type: type: string example: user' description: >- If `verbose` query paramter is set to true. The type of face. Possible values: user, system. User faces are faces that have been created by users. System faces are stock Tavus faces that anyone may use model_name: type: string example: phoenix-3 description: >- The Phoenix model the face was trained on (e.g. `phoenix-3`, `phoenix-4`). total_count: type: integer description: The total number of faces 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: - Faces summary: Create Face description: >- Creates a new face from training video or image URL for use in conversations. See [Which training path?](/sections/faces/which-training-path) for footage requirements and [Face overview](/sections/faces/overview#platform-policies) for rights and permissions. operationId: createFace requestBody: content: application/json: schema: type: object properties: consent_video_url: deprecated: true x-mint: groups: - legacy type: string description: > **Legacy.** Optional URL to a separate consent recording used with older video-training flows. New integrations should not send this field. Ensure you have the necessary rights and permissions to use any training footage - see [Platform Policies](/sections/faces/overview#platform-policies). 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 face training. Do not send `train_image_url` in the same request. The file must meet [training video requirements](/sections/troubleshooting/training-video-size). You must have the necessary rights and permissions to use the likeness, voice, and footage you submit. See [Platform Policies](/sections/faces/overview#platform-policies). 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-face training. Requires `voice_name`. Do not send `train_video_url` in the same request. You must have the necessary rights and permissions to use the likeness and image. See [Training from an image](/sections/faces/train-with-an-image) and [Platform Policies](/sections/faces/overview#platform-policies). 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 face (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/faces/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/faces/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 face training or on error. example: https://yourwebsite.com/webhook face_name: type: string description: A name for the face. example: Rio model_name: type: string description: >- The Phoenix model version used to train the face. 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 face will have a green screen background. example: false examples: Video training: value: callback_url: https://yourwebsite.com/webhook face_name: Rio train_video_url: >- https://my-example-bucket.s3.us-east-1.amazonaws.com/your-train-video.mp4 Non-Human Face: value: callback_url: https://yourwebsite.com/webhook face_name: AI train_video_url: >- https://my-example-bucket.s3.us-east-1.amazonaws.com/your-train-video.mp4 Older Model Face: value: model_name: phoenix-3 callback_url: https://yourwebsite.com/webhook face_name: My phoenix-3 Face train_video_url: >- https://my-example-bucket.s3.us-east-1.amazonaws.com/your-train-video.mp4 Image to Face: value: callback_url: https://yourwebsite.com/webhook face_name: Image Face 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: face_id: type: string example: r90bbd427f71 description: A unique identifier for the face. status: type: string example: started description: >- The status of the face. 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/faces/{face_id}: get: tags: - Faces summary: Get Face description: | This endpoint returns a single Face by its unique identifier. operationId: getFace parameters: - in: path name: face_id required: true schema: type: string description: A unique identifier for the face. - in: query name: verbose schema: type: boolean description: >- If set to true, the response will include additional face data such as face_type. responses: '200': description: '' content: application/json: schema: type: object properties: face_id: type: string example: r90bbd427f71 description: A unique identifier for the face. face_name: type: string example: My Face description: The name of the face. thumbnail_video_url: type: string description: >- A direct link to the video that will be used as the thumbnail for the face. 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 face was created. updated_at: type: string example: '2024-01-24T07:14:03.327Z' description: The date and time of when the face was last updated. error_message: type: string nullable: true description: >- When `status` is `error`, contains details about the training failure; otherwise typically null. face_type: type: string example: user' description: >- If `verbose` query paramter is set to true. The type of face. Possible values: user, system. User faces are faces that have been created by users. System faces are stock Tavus faces that anyone may use model_name: type: string example: phoenix-3 description: >- The Phoenix model the face 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 face_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: - Faces summary: Delete Face description: >- Deletes a Face by its unique ID; deleted faces cannot be used in a conversation. operationId: deleteFace parameters: - name: face_id in: path required: true description: The unique identifier of the face. schema: type: string example: r90bbd427f71 - name: hard in: query schema: type: boolean example: false description: >- If set to true, the face and associated assets (such as training footage) will be hard deleted. CAUTION: This action is irrevocable. Note that a hard delete of a face does *not* delete the conversation created using said face. 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 face_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/faces/{face_id}/name: patch: tags: - Faces summary: Rename Face description: | This endpoint renames a single Face by its unique identifier. operationId: renameReplica requestBody: content: application/json: schema: type: object properties: face_name: type: string example: Rio required: - face_name examples: Rename Face: value: face_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 face_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: face_id in: path required: true description: The unique identifier of the face. schema: type: string example: r90bbd427f71 /v2/voices: get: tags: - Voices summary: List Voices description: > Returns available stock **`voice_name`** values and their linked **face** metadata. When you [Create Face](/api-reference/faces/create-face) with **`train_image_url`** (image-to-face), **`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 face 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 Face (image-to-face). example: anna face_id: type: string description: face 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 face 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 face, powered by a PAL that allows it to see, hear, and respond like a human. operationId: createConversation requestBody: content: application/json: schema: type: object properties: face_id: type: string description: >- The unique identifier for the face the PAL will render in the conversation. **Each request must have a valid `face_id` value that's either directly passed in or as part of a PAL**. example: r90bbd427f71 pal_id: type: string description: > The unique identifier for the PAL that will use the specified face in the conversation. - **If your PAL does not have a valid `face_id`, you must define the `face_id` field.** - **If your PAL already has a valid `face_id` and you provide one in the request, the `face_id` provided in the request will be used instead of the one defined in your PAL**. 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 PAL, 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 PAL 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 PAL 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 PAL 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 PAL 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 PAL 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 meeting_url: type: string description: > A Google Meet URL for the PAL to join instead of a Tavus-hosted Daily room (for example `https://meet.google.com/abc-defg-hij`). When set, the PAL joins that meeting shortly after the conversation is created. Requires the PAL to have a conferencing layer with `username` configured. See [Google Meet](/sections/conversational-video-interface/pal/meetings#join-a-google-meet-via-api). example: https://meet.google.com/xgq-epxn-ccp 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 PAL counts as one participant). example: 2 policy: type: string description: > Regional policy applied to this conversation. Set to `eu` when you want PAL fields left on `auto` to resolve as described in the [EU AI Act](/sections/onboarding-guide/eu-ai-act) product guide: - `emotion_recognition: auto` behaves like `limited` (Raven-1 does not attach biometric-derived emotion). - `disclosure_type: auto` delivers the spoken and on-screen AI disclosure for that conversation. - Explicit settings (`full`, `limited`, `always`, `off`) are honored as-is and are not overridden by `policy`. Leave unset when you do not want that auto resolution. Choosing the correct value per participant is your responsibility — on the create-conversation API Tavus does not geolocate the caller. enum: - eu example: eu 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 auto_start_recording: type: boolean description: >- If true, Tavus starts the recording about a second after the pal joins, so you do not need to call `startRecording()` from your client. Requires `recording_storage`. Only supported on Tavus-hosted rooms - not with `daily_room`, `meeting_url`, or LiveKit. Defaults to false. See [Start recording automatically](/sections/conversational-video-interface/quickstart/conversation-recordings#start-recording-automatically). 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 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 face or default PAL, 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: face_id: r90bbd427f71 pal_id: pcb7a34da5fe Full Customizations: value: face_id: r90bbd427f71 pal_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: face_id: r90bbd427f71 pal_id: pcb7a34da5fe audio_only: true Private Room: value: face_id: r90bbd427f71 pal_id: pcb7a34da5fe require_auth: true Google Meet (direct invite): value: face_id: r90bbd427f71 pal_id: pcb7a34da5fe meeting_url: https://meet.google.com/xgq-epxn-ccp EU AI Act compliance (policy = eu): value: face_id: r90bbd427f71 pal_id: pcb7a34da5fe policy: eu Recording Storage - Amazon S3: value: face_id: rf4e9d9790f0 pal_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: face_id: rf4e9d9790f0 pal_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: face_id: rf4e9d9790f0 pal_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. The response body contains either an `error` or `message` field depending on the error type. content: application/json: schema: type: object properties: error: type: string description: Present for request validation errors. message: type: string description: Present for limit and account errors. examples: bad_request: summary: Missing required field value: error: >- Bad Request. {'_schema': ['Either face_id or a pal_id with a default face specified must be present.']} concurrent_limit: summary: Concurrent conversation limit reached value: message: User has reached maximum concurrent conversations '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 face_id: type: string description: >- A unique identifier for the face used to create this conversation example: r90bbd427f71 pal_id: type: string description: >- A unique identifier for the PAL 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.pal_joined`: When the PAL joined the conversation (preferred for new integrations) - `system.replica_joined`: **Legacy duplicate** of `system.pal_joined` with an identical payload; still sent for backward compatibility - `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 - `application.perception_unavailable`: Emitted when perception is enabled but no visual analysis could be produced. `properties.reason` is one of `no_vision_history`, `empty_summary`, or `summary_error` (for example, the participant's camera was off, no frames were received, or the summary came back empty). - `application.post_call_action_executed`: The outcome of each [post-call action](/sections/conversational-video-interface/pal/post-call-tool) Tavus ran after the call, with `tool_name`, `status`, and the action's `request` / `response`. 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 face_id: type: string description: >- A unique identifier for the face used to create this conversation example: r90bbd427f71 pal_id: type: string description: >- A unique identifier for the PAL used to create this conversation example: pcb7a34da5fe policy: type: string nullable: true description: >- Regional policy the conversation was created with (see [EU AI Act](/sections/onboarding-guide/eu-ai-act)). Currently `eu` or unset. example: eu 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.pal_joined, system.replica_joined, application.transcription_ready, application.perception_analysis, application.perception_unavailable, application.post_call_action_executed). 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 face_id: r90bbd427f71 pal_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 face_id: replica_abc pal_id: persona_xyz created_at: '2026-04-29T03:45:49Z' updated_at: '2026-04-29T03:47:01Z' events: - event_type: system.pal_joined message_type: system timestamp: '2026-04-29T03:45:53Z' - event_type: system.replica_joined message_type: system timestamp: '2026-04-29T03:45:53Z' - event_type: application.transcription_ready message_type: application 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 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: application.perception_unavailable message_type: application timestamp: '2026-04-29T03:47:00Z' properties: reason: no_vision_history - event_type: system.shutdown message_type: system timestamp: '2026-04-29T03:47:01Z' properties: reason: participant_left_timeout - event_type: application.post_call_action_executed message_type: application timestamp: '2026-04-29T03:47:05Z' properties: tool_id: tool_abc123 tool_name: post_call_summary status: success request: url: https://your-app.example.com/hooks/call-summary method: POST body: >- {"channel":"C0SUPPORT","text":"Caller asked about order status; resolved."} response: http_status: 200 body: 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: [] delete: tags: - Conversations summary: Delete Conversation description: > This endpoint deletes a single conversation by its unique identifier. Use this for destructive data removal. For normal call cleanup when a user leaves or a session is finished, use [End Conversation](/api-reference/conversations/end-conversation) instead. 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. Use this for routine call cleanup when a user leaves or your app no longer needs the room. To destructively remove conversation data, use [Delete Conversation](/api-reference/conversations/delete-conversation). 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/conversations/{conversation_id}/canvas/interactions: parameters: - name: conversation_id in: path required: true description: The unique identifier of the conversation. schema: type: string example: c123456 post: tags: - Conversations summary: Record Canvas Interaction description: > Record a Magic Canvas interaction (submit, skip, dismiss, clear, error, or heartbeat) while a conversation is **active**. The Tavus-hosted embed and `@tavus/cvi-ui` post interactions for you. Call this endpoint directly only if you build your own renderer. **Authentication:** No API key is required while the conversation is active. Never put your Tavus API key in a browser. Once the conversation ends, every POST is rejected. **Idempotency:** Retries with the same `(conversation_id, interaction_id)` and identical `tool_call_id`, `component`, `component_version`, `type`, and `value` return `200` without firing a second webhook. `metadata` is excluded from the match. **Rate limiting:** 120 POSTs per 60-second window per `(client IP, conversation_id)`. Exceeding the limit returns `429` with `{ "error": "Too many requests" }` and a `Retry-After` header (seconds until the window resets). Custom renderers posting `heartbeat` interactions count toward this limit. See [Canvas interactions](/sections/conversational-video-interface/magic-canvas/api/interactions) for per-component `value` rules, webhook delivery, and the full error catalog. operationId: recordCanvasInteraction security: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/canvasInteractionRequest' examples: question_submit: summary: Question submit value: interaction_id: ci_call_8f2d41_submit_5e0b7c2a tool_call_id: call_8f2d41 component: canvas.question component_version: v1 type: submit value: selected_option_ids: - opt_2 skipped: false metadata: client: kiosk-web responses: '200': description: Interaction recorded (or idempotent replay) content: application/json: schema: type: object properties: success: type: boolean example: true '400': description: >- Bad Request - invalid payload, unknown conversation, or conversation not active content: application/json: schema: oneOf: - type: object description: >- Schema validation failure on the public route (field names only). properties: error: type: string example: Invalid canvas interaction payload. fields: type: array items: type: string example: - component - value - type: object description: Business-rule rejection. properties: message: type: string example: >- Canvas interactions can only be recorded for active conversations. '409': description: >- Conflict - interaction does not match the issued canvas instance, or interaction_id reused with a different payload content: application/json: schema: type: object properties: message: type: string example: >- Interaction does not match the issued canvas instance for this tool_call_id. '429': description: >- Too Many Requests - rate limit exceeded (120 POSTs per 60-second window per client IP and conversation) headers: Retry-After: description: Seconds until the current rate-limit window resets. schema: type: integer example: 60 content: application/json: schema: type: object properties: error: type: string example: Too many requests get: tags: - Conversations summary: List Canvas Interactions description: > Returns every Canvas interaction recorded for a conversation, oldest first. Uses the same field shape as the `canvas.interaction` webhook's `properties` object. Readable during and after the conversation. Call from your backend with your API key - not from the browser. See [Canvas interactions](/sections/conversational-video-interface/magic-canvas/api/interactions). operationId: listCanvasInteractions security: - apiKey: [] responses: '200': description: Interaction history returned content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/canvasInteractionRecord' '400': description: Bad Request content: application/json: schema: type: object properties: message: type: string example: Invalid conversation_id '401': description: UNAUTHORIZED content: application/json: schema: type: object properties: message: type: string example: Invalid access token /v2/deployments: post: tags: - Deployments summary: Create Deployment description: > Create a managed deployment for the widget, embed, or landing-page channel. See [Deployments overview](/sections/deployments/overview). operationId: createDeployment requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/createDeploymentRequest' responses: '200': description: Deployment created content: application/json: schema: $ref: '#/components/schemas/deployment' '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string '401': description: UNAUTHORIZED content: application/json: schema: type: object properties: message: type: string example: Invalid access token security: - apiKey: [] get: tags: - Deployments summary: List Deployments description: List deployments owned by the authenticated user. operationId: listDeployments parameters: - name: pal_id in: query required: false schema: type: string description: Filter to deployments for a single PAL. - name: search in: query required: false schema: type: string description: Case-insensitive search on deployment name. - name: status in: query required: false schema: type: string description: 'Comma-separated statuses: `draft`, `active`, `inactive`.' - name: channel in: query required: false schema: type: string description: 'Comma-separated channels: `widget`, `embed`, `landing-page`.' - name: limit in: query required: false schema: type: integer default: 20 - name: page in: query required: false schema: type: integer default: 0 - name: sort in: query required: false schema: type: string enum: - asc - desc default: desc responses: '200': description: Paginated deployment list content: application/json: schema: type: object properties: deployments: type: array items: $ref: '#/components/schemas/deployment' total: type: integer page: type: integer limit: type: integer '401': description: UNAUTHORIZED content: application/json: schema: type: object properties: message: type: string example: Invalid access token security: - apiKey: [] /v2/deployments/{deployment_id}: get: tags: - Deployments summary: Get Deployment operationId: getDeployment parameters: - name: deployment_id in: path required: true schema: type: string description: Deployment UUID. responses: '200': description: Deployment details headers: ETag: description: Weak ETag from `updated_at`. Pass as `If-Match` on PATCH. schema: type: string content: application/json: schema: $ref: '#/components/schemas/deployment' '401': description: UNAUTHORIZED content: application/json: schema: type: object properties: message: type: string example: Invalid access token '404': description: Not Found content: application/json: schema: type: object properties: message: type: string example: Deployment not found security: - apiKey: [] patch: tags: - Deployments summary: Patch Deployment description: > Apply a [JSON Patch](https://jsonpatch.com/) array to the deployment document. Send the `ETag` from GET as `If-Match` for optimistic concurrency. operationId: patchDeployment parameters: - name: deployment_id in: path required: true schema: type: string - name: If-Match in: header required: false schema: type: string description: ETag from a prior GET response. requestBody: required: true content: application/json: schema: type: array items: type: object example: - op: replace path: /name value: Support widget responses: '200': description: Updated deployment content: application/json: schema: $ref: '#/components/schemas/deployment' '401': description: UNAUTHORIZED '404': description: Not Found '422': description: Invalid JSON Patch content: application/json: schema: type: object properties: error: type: string example: Invalid JSON patch format security: - apiKey: [] delete: tags: - Deployments summary: Delete Deployment operationId: deleteDeployment parameters: - name: deployment_id in: path required: true schema: type: string responses: '204': description: Deployment deleted '401': description: UNAUTHORIZED '404': description: Not Found security: - apiKey: [] /v2/deployments/{deployment_id}/init: get: tags: - Deployments summary: Get Deployment Init Config description: > Public endpoint called when a widget or embed mounts. Returns customization, limits, captcha settings, and availability. Does **not** return a PAL identifier - the widget/embed runtime never reads it from `/init`. No API key required. Origin and browser-context checks apply for non-preview callers. operationId: getDeploymentInit parameters: - name: deployment_id in: path required: true schema: type: string responses: '200': description: Init configuration content: application/json: schema: $ref: '#/components/schemas/deploymentInitConfig' '404': description: Deployment not found or inactive content: application/json: schema: type: object properties: error: type: string security: [] /v2/deployments/{deployment_id}/start: post: tags: - Deployments summary: Start Deployment Conversation description: > Creates a conversation for a deployment. Returns the same fields as [Create Conversation](/api-reference/conversations/create-conversation). No API key required in the browser. Password, Turnstile, and call-limit checks apply for public callers. operationId: startDeploymentConversation parameters: - name: deployment_id in: path required: true schema: type: string requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/deploymentStartRequest' responses: '200': description: Conversation created content: application/json: schema: $ref: '#/components/schemas/deploymentConversationStart' '400': description: Bad Request '401': description: Authentication required (auth-gated landing pages) '404': description: Deployment not found or inactive '429': description: Rate limited or call limit reached security: [] /v2/deployments/{deployment_id}/conversations/{conversation_id}/end: post: tags: - Deployments summary: End Deployment Conversation description: >- Ends an active conversation started through a deployment. No API key required in the browser. operationId: endDeploymentConversation parameters: - name: deployment_id in: path required: true schema: type: string - name: conversation_id in: path required: true schema: type: string responses: '200': description: Conversation ended content: application/json: schema: type: object properties: conversation_id: type: string status: type: string example: ended '404': description: Not Found security: [] /v2/pals: post: tags: - PALs summary: Create PAL description: > Creates a PAL and configures how it behaves in CVI for every conversation that uses that PAL. **`default_face_id` is required** on `POST /v2/pals` (unlike the legacy `POST /v2/personas` path, where `default_replica_id` was optional). **Legacy:** `/v2/personas` and `persona_id` / `default_replica_id` remain supported as aliases. operationId: createPal requestBody: content: application/json: schema: type: object properties: pal_name: type: string description: A name for the PAL. 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 PAL. Possible values: `full`, `echo`. `full` will provide the default end-to-end experience. `echo` will turn off most steps, and allow the PAL to sync video with audio passed in through Echo events, which it will speak out. enum: - full - echo default_face_id: type: string description: >- **Required.** The default face associated with this PAL. When creating a conversation, a `pal_id` with a `default_face_id` can be used without specifying a separate `face_id`. Also **required** when `layers.conferencing` is set - see [Google Meet](/sections/conversational-video-interface/pal/meetings). example: r90bbd427f71 document_ids: type: array description: >- Array of document IDs that the PAL will have access to. These documents will be available to the PAL 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 PAL will have access to. Documents matching these tags will be available to the PAL 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 PAL. 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 guardrail_ids: type: array maxItems: 50 description: >- Array of guardrail IDs enforced during this PAL's conversations. Up to 50 per PAL. Guardrail IDs are returned by [Create Guardrails](/api-reference/guardrails/create-guardrails) and [Get Guardrails](/api-reference/guardrails/get-guardrails). items: type: string example: - g1234567890ab - g0987654321cd guardrail_tags: type: array maxItems: 50 description: >- Array of guardrail tags. Any guardrail you own with a matching tag is attached to this PAL dynamically. Up to 50 tags per PAL, and a PAL can have at most 50 guardrails total. items: type: string example: - compliance - healthcare guardrails_id: type: string description: >- **Deprecated.** The unique identifier of a guardrail set to attach to this PAL. New integrations should use `guardrail_ids` / `guardrail_tags` instead - see [Deprecated guardrail sets](/api-reference/guardrails/legacy-guardrail-sets). example: g12345 disclosure_type: type: string description: > Controls the AI disclosure the PAL delivers at the start of a conversation. See [EU AI Act](/sections/onboarding-guide/eu-ai-act) product guidance. - `always`: the PAL speaks `verbal_disclosure` before the greeting and shows `visual_disclosure` on screen for every conversation. - `auto` (default): applies the disclosure only when the conversation's [`policy`](/api-reference/conversations/create-conversation) is `eu`. - `off`: never delivers a Tavus-built-in disclosure. When `always` or `auto` fires and `verbal_disclosure` / `visual_disclosure` are empty, Tavus supplies these defaults: - `verbal_disclosure`: "Just a note, I am an AI system, not a person." - `visual_disclosure`: "You are interacting with an AI system." enum: - always - auto - 'off' default: auto example: auto verbal_disclosure: type: string description: >- Text the PAL speaks before its greeting when `disclosure_type` fires. When empty, Tavus falls back to "Just a note, I am an AI system, not a person." example: >- Just so you know, you're speaking with an AI agent from Acme. visual_disclosure: type: string description: >- Text shown as an on-screen banner while the PAL delivers `verbal_disclosure`. When empty, Tavus falls back to "You are interacting with an AI system." example: You are speaking with an AI agent. layers: type: object description: > Optional nested settings for each CVI pipeline layer (perception, STT, conversational flow, LLM, TTS, conferencing). For an overview of what each layer controls, see [PAL overview - CVI layers](/sections/conversational-video-interface/pal/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 emotion_recognition: type: string description: > Controls whether Raven-1 may infer emotion from biometric signals (what it sees and hears - facial expression, tone of voice). See [EU AI Act](/sections/onboarding-guide/eu-ai-act). - `full`: Raven-1 attaches biometric emotion analysis to user audio and video. - `limited`: Raven-1 is instructed not to attach any biometric-derived emotion data. `user_audio_analysis` and `user_visual_analysis` tags still fire for non-emotional cues (spoken content, objects, activity). - `auto` (default): follows the conversation's [`policy`](/api-reference/conversations/create-conversation) parameter. Behaves like `limited` when `policy` is `eu`, and like `full` otherwise. enum: - full - limited - auto default: auto example: auto 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 PAL 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: >- **Legacy.** Inline vision tools on the PAL (OpenAI function shape). Deprecated - create tools with `origin: vision` via [Create Tool](/api-reference/tools/create-tool) and attach to the PAL. Still supported at runtime; see [Legacy inline tool calling](/sections/troubleshooting#legacy-inline-tool-calling). 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: >- **Legacy.** Inline audio tools on the PAL (OpenAI function shape). Deprecated - create tools with `origin: audio` via [Create Tool](/api-reference/tools/create-tool) and attach to the PAL. Raven-1 only. See [Legacy inline tool calling](/sections/troubleshooting#legacy-inline-tool-calling). 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/pal/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/pal/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 PAL. When omitted or partially configured, unspecified fields use sensible defaults (`sparrow-1`, `medium` patience/interruptibility, etc.). See more details [here](/sections/conversational-video-interface/pal/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`. enum: - sparrow-1 - sparrow-0 example: sparrow-1 turn_taking_patience: type: string description: >- Controls how eagerly and quickly the PAL 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 pal_interruptibility: type: string description: >- Controls how sensitive the PAL is to user speech while the PAL is talking. Determines whether the PAL 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 replica_interruptibility: deprecated: true type: string description: >- **Legacy alias** for `pal_interruptibility`. Still accepted at runtime; existing integrations do not need to change. enum: - low - medium - high 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 PAL listens for before responding. When set, the PAL remains silent until it hears the wake phrase, similar to a voice assistant. The PAL 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 Charlie sleep_phrase: type: string description: >- A specific phrase that puts the persona back to sleep after it has been woken with the `wake_phrase`. When the persona hears the sleep phrase, it stops responding and returns to the silent state, listening again for the wake phrase before it will respond. The persona still records all user utterances in the transcript while asleep. Choose a phrase that is unique enough to avoid over-triggering. Default is `None` (disabled). example: Thanks Charlie idle_engagement: type: string description: >- Controls whether the PAL proactively re-engages the user after a stretch of silence, and how eagerly. `off` (default) = the PAL 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-gemma-4** is recommended as the default. Other Tavus-hosted options include tavus-gpt-5.6-sol, tavus-gpt-5.6-terra, and tavus-gemini-2.5-flash. See the [LLM layer documentation](/sections/conversational-video-interface/pal/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. Context limits vary by model. 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: >- **Legacy.** Inline OpenAI-style function tools on the PAL. Deprecated - create tools via [Create Tool](/api-reference/tools/create-tool) and attach with [Attach Tools to PAL](/api-reference/pal-tools/attach-tools-to-pal). Still supported at runtime; see [Legacy inline tool calling](/sections/troubleshooting#legacy-inline-tool-calling). 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. `tavus-auto` automatically selects the best TTS model for each conversation (recommended). See the [TTS layer documentation](/sections/conversational-video-interface/pal/tts) for details. default: tavus-auto enum: - tavus-auto - cartesia - elevenlabs - azure external_voice_id: type: string description: >- The voice ID used for the TTS engine when you want to customize your face'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 faces). 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 PAL. 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 conferencing: $ref: '#/components/schemas/conferencingLayer' examples: Required Parameters Only: value: pipeline_mode: full system_prompt: >- As a Life Coach, you are a dedicated professional who specializes in... default_face_id: r90bbd427f71 Full Customizations: value: pal_name: Life Coach system_prompt: >- As a Life Coach, you are a dedicated professional who specializes in... pipeline_mode: full default_face_id: r90bbd427f71 layers: llm: model: tavus-gemma-4 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 pal_interruptibility: high voice_isolation: near idle_engagement: 'off' document_ids: - d1234567890 - d2468101214 document_tags: - product_info - company_policies Google Meet conferencing: value: pal_name: Anna system_prompt: >- You are Anna, a helpful meeting assistant who takes notes and answers questions. pipeline_mode: full default_face_id: r90bbd427f71 layers: conferencing: username: acme-anna allowlist: - .*@acme\.com EU AI Act compliance: value: pal_name: Acme EU Agent system_prompt: You are a helpful support agent for Acme. pipeline_mode: full default_face_id: r90bbd427f71 disclosure_type: auto verbal_disclosure: >- Just so you know, you're speaking with an AI agent from Acme. visual_disclosure: You are speaking with an AI agent. layers: perception: perception_model: raven-1 emotion_recognition: auto responses: '200': description: '' content: application/json: schema: type: object properties: pal_id: type: string description: A unique identifier for the PAL. example: pcb7a34da5fe pal_name: type: string description: The name of the PAL. example: Life Coach conferencing_email: type: string nullable: true description: >- The PAL's invitable meeting email on `tavusinvite.com`, derived from `layers.conferencing.username`. Present when conferencing is configured. See [Google Meet](/sections/conversational-video-interface/pal/meetings). example: acme-anna@tavusinvite.com created_at: type: string description: The date and time the PAL 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: - PALs summary: List PALs description: > This endpoint returns a list of all PALs 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 PALs 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: pal_type schema: type: string description: >- Filter the PALs by type. Possible values: user, system. System PALs are PALs that have been created by Tavus. enum: - user - system - in: query name: persona_type deprecated: true schema: type: string description: >- **Legacy alias** for `pal_type`. Still accepted; use `pal_type` in new integrations. enum: - user - system responses: '200': description: '' content: application/json: schema: type: object properties: data: type: array description: >- PALs for the current page; use `total_count` for the full count under the applied filters. items: type: object properties: pal_id: type: string description: A unique identifier for the PAL. example: pcb7a34da5fe pal_name: type: string description: A name for the PAL. 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_face_id: type: string example: r90bbd427f71 description: >- The default face_id associated with this PAL if one exists. conferencing_email: type: string nullable: true description: >- The PAL's invitable meeting email on `tavusinvite.com`, derived from `layers.conferencing.username`. Present when conferencing is configured. example: acme-anna@tavusinvite.com disclosure_type: type: string description: >- AI disclosure setting for [EU AI Act](/sections/onboarding-guide/eu-ai-act) compliance. `always`, `auto` (default), or `off`. enum: - always - auto - 'off' default: auto example: auto verbal_disclosure: type: string description: >- Text the PAL speaks before its greeting when `disclosure_type` fires. example: >- Just so you know, you're speaking with an AI agent from Acme. visual_disclosure: type: string description: >- Text shown as an on-screen banner when `disclosure_type` fires. example: You are speaking with an AI agent. document_ids: type: array description: >- Array of document IDs that the PAL has access to. These documents will be available to the PAL 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 PAL has access to. Documents matching these tags will be available to the PAL 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: >- **Legacy.** Inline OpenAI-style function tools on the PAL. Deprecated - use [Create Tool](/api-reference/tools/create-tool) and [Attach Tools to PAL](/api-reference/pal-tools/attach-tools-to-pal). See [Legacy inline tool calling](/sections/troubleshooting#legacy-inline-tool-calling). 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. `tavus-auto` automatically selects the best TTS model for each conversation (recommended). default: tavus-auto enum: - tavus-auto - cartesia - elevenlabs - azure external_voice_id: type: string description: >- The voice ID used for the TTS engine when you want to customize your face'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 PAL, 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 emotion_recognition: type: string description: > Controls whether Raven-1 may infer emotion from biometric signals - used for [EU AI Act](/sections/onboarding-guide/eu-ai-act) compliance. `full`, `limited`, or `auto` (default, follows the conversation's `policy` param). enum: - full - limited - auto default: auto example: auto 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 PAL 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: >- **Legacy.** Inline vision tools on the PAL. Deprecated - use registry tools with `origin: vision`. See [Legacy inline tool calling](/sections/troubleshooting#legacy-inline-tool-calling). 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: >- **Legacy.** Inline audio tools on the PAL. Deprecated - use registry tools with `origin: audio`. Raven-1 only. See [Legacy inline tool calling](/sections/troubleshooting#legacy-inline-tool-calling). 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/pal/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 conferencing: $ref: '#/components/schemas/conferencingLayer' created_at: type: string description: The date and time the PAL was created. example: '' updated_at: type: string description: The date and time of when the PAL was last updated. total_count: type: integer description: The total number of PALs 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/pals/check-username: get: tags: - PALs summary: Check Conferencing Username Availability description: > Check whether a conferencing `username` is available on `tavusinvite.com` before creating or patching a PAL. See [Google Meet](/sections/conversational-video-interface/pal/meetings). operationId: checkConferencingUsername parameters: - name: username in: query required: true description: The username to check. Case-insensitive; stored lowercase. schema: type: string example: anna responses: '200': description: Availability result content: application/json: schema: $ref: '#/components/schemas/conferencingUsernameCheck' examples: available: summary: Available value: available: true taken: summary: Already taken value: available: false reason: Username is already taken. invalid: summary: Invalid format value: available: false reason: >- Invalid username. Must be 2+ characters, start and end with alphanumeric, and may contain '.', '_', or '-' in between. '400': description: Bad Request - missing `username` query parameter content: application/json: schema: type: object properties: error: type: string example: Bad Request. username query parameter is required '401': description: UNAUTHORIZED content: application/json: schema: type: object properties: message: type: string example: Invalid access token security: - apiKey: [] /v2/pals/{pal_id}: get: tags: - PALs summary: Get PAL description: > Returns a single PAL by its unique identifier. By default this endpoint returns the **live** PAL — the version that powers conversations, deployments, and the public API. If the PAL has an active [PAL Builder](https://maker.tavus.io/dev) draft with unpublished changes, add `?source=draft` to read the draft body without publishing it. See [Draft vs live PALs](/sections/conversational-video-interface/pal/draft-and-live) for the full model. Regardless of `source`, `layers.conferencing` is always returned from the live PAL, because conferencing is deployment config that is owned by the live row (see [PATCH PAL](/api-reference/pals/patch-pal)). operationId: getPal parameters: - name: source in: query required: false description: > Which body to return when the PAL has an active PAL Builder draft. - Omitted (default): returns the **live** PAL. The response shape is unchanged from previous behavior. - `draft`: overlays the active draft. The response `pal_id` still matches the id you queried; `is_draft_view`, `has_unpublished_changes`, `live_pal_id`, `draft_pal_id`, `publish_url`, and `routing_message` are added so you can tell you are reading unpublished content. If no draft exists, or the draft has no unpublished changes, the live body is returned unchanged. - `live`: only meaningful when you address a draft id directly — forces the live parent body. The response `pal_id` still matches the draft id you queried. `layers.conferencing` is always the live value, even on a draft view. schema: type: string enum: - draft - live example: draft responses: '200': description: '' content: application/json: schema: type: object properties: pal_id: type: string description: A unique identifier for the PAL. example: pcb7a34da5fe pal_name: type: string description: A name for the PAL. 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_face_id: type: string example: r90bbd427f71 description: >- The default face_id associated with this PAL if one exists. conferencing_email: type: string nullable: true description: >- The PAL's invitable meeting email on `tavusinvite.com`, derived from `layers.conferencing.username`. Present when conferencing is configured. example: acme-anna@tavusinvite.com disclosure_type: type: string description: >- AI disclosure setting for [EU AI Act](/sections/onboarding-guide/eu-ai-act) compliance. `always`, `auto` (default, follows the conversation's `policy` param), or `off`. enum: - always - auto - 'off' default: auto example: auto verbal_disclosure: type: string description: >- Text the PAL speaks before its greeting when `disclosure_type` fires. Empty falls back to "Just a note, I am an AI system, not a person." example: >- Just so you know, you're speaking with an AI agent from Acme. visual_disclosure: type: string description: >- Text shown as an on-screen banner when `disclosure_type` fires. Empty falls back to "You are interacting with an AI system." example: You are speaking with an AI agent. document_ids: type: array description: >- Array of document IDs that the PAL has access to. These documents will be available to the PAL 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 PAL has access to. Documents matching these tags will be available to the PAL 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: >- **Legacy.** Inline OpenAI-style function tools on the PAL. Deprecated - use [Create Tool](/api-reference/tools/create-tool) and [Attach Tools to PAL](/api-reference/pal-tools/attach-tools-to-pal). See [Legacy inline tool calling](/sections/troubleshooting#legacy-inline-tool-calling). 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. `tavus-auto` automatically selects the best TTS model for each conversation (recommended). default: tavus-auto enum: - tavus-auto - cartesia - elevenlabs - azure external_voice_id: type: string description: >- The voice ID used for the TTS engine when you want to customize your face'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 PAL, 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 emotion_recognition: type: string description: > Controls whether Raven-1 may infer emotion from biometric signals (facial expression, tone of voice) - used for [EU AI Act](/sections/onboarding-guide/eu-ai-act) compliance. `full` = always attach biometric emotion analysis. `limited` = never attach biometric emotion analysis. `auto` (default) = follows the conversation's `policy` param (`limited` when `policy` is `eu`, otherwise `full`). enum: - full - limited - auto default: auto example: auto 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 PAL 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: >- **Legacy.** Inline vision tools on the PAL. Deprecated - use registry tools with `origin: vision`. See [Legacy inline tool calling](/sections/troubleshooting#legacy-inline-tool-calling). 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: >- **Legacy.** Inline audio tools on the PAL. Deprecated - use registry tools with `origin: audio`. Raven-1 only. See [Legacy inline tool calling](/sections/troubleshooting#legacy-inline-tool-calling). 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/pal/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 conferencing: $ref: '#/components/schemas/conferencingLayer' created_at: type: string description: The date and time the PAL was created. example: '' updated_at: type: string description: The date and time of when the PAL was last updated. is_draft_view: type: boolean description: > Present and `true` only when you called this endpoint with `?source=draft` **and** the PAL has an active PAL Builder draft with unpublished changes. Absent otherwise. Signals that the response body is the draft — not the live PAL that powers running conversations. example: true has_unpublished_changes: type: boolean description: > Present with `is_draft_view=true`. `true` when the draft has edits that have not been published to the live PAL. example: true live_pal_id: type: string description: > Present with `is_draft_view=true`. The id of the live PAL that this draft belongs to. This is the same id you queried when using `?source=draft` against a live PAL id. example: pcb7a34da5fe draft_pal_id: type: string description: > Present with `is_draft_view=true`. The id of the underlying draft row. You do not normally need this — patching or publishing the live id routes to the draft automatically — but it is exposed for tooling that wants to address the draft row directly. example: p5f1e8d2a934 published_view_url: type: string description: > Present with `is_draft_view=true`. Convenience path for re-reading the live body: `/v2/pals/{live_pal_id}?source=live`. example: /v2/pals/pcb7a34da5fe?source=live publish_url: type: string description: > Present with `is_draft_view=true`. The PAL endpoint that publishes this draft to live. example: /v2/pals/pcb7a34da5fe/publish routing_message: type: string description: > Present with `is_draft_view=true`. Human-readable summary explaining that the body is the unpublished draft and that live traffic still uses the published version until you call `POST /v2/pals/{pal_id}/publish`. example: >- Showing the unpublished draft of pcb7a34da5fe. Conversations and the public live PAL use the published version until you publish — POST /v2/pals/pcb7a34da5fe/publish. Add ?source=live to read the live version. '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string description: The error message. example: Invalid pal_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: - PALs summary: Delete PAL description: | This endpoint deletes a single PAL by its unique identifier. operationId: deletePal parameters: - name: pal_id in: path required: true description: The unique identifier of the PAL. 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 pal_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: - PALs summary: Patch PAL description: > Update specific fields of a PAL using [JSON Patch](https://datatracker.ietf.org/doc/html/rfc6902) operations. ### Draft vs live routing If the PAL has an active [PAL Builder](https://maker.tavus.io/dev) draft, this endpoint **routes to the draft by default**. Live conversations, deployments, and public reads continue to use the previously-published version until you publish (`POST /v2/pals/{pal_id}/publish`) or repeat the request with `?target=live`. PALs without an active draft are unaffected — the patch applies to the live row as it always did. This default was introduced so an API patch and a PAL Maker edit stay in sync: the Builder reads the draft row, so a PATCH that skipped the draft would produce an editor that still shows the pre-patch state. To bypass the draft, pass `?target=live` — this applies the edit to the live row and resyncs the retained draft from live. Any unpublished draft edits are discarded. The response always includes `edit_target`, `edited_pal_id`, `live_pal_id`, `draft_pal_id`, and `routing_message` so you can confirm which row was written. Draft-routed responses also include `publish_url`. See [Draft vs live PALs](/sections/conversational-video-interface/pal/draft-and-live) for the full model. ### `layers.conferencing` is live-owned `layers.conferencing` (the conferencing/Google Meet integration) is deployment config that lives on the live row so meeting invitations continue to work while a draft is open. Regardless of `?target`, any patch that touches `layers.conferencing` (or removes `layers`) is applied to the live PAL and then synced into the open draft, so the draft never carries a stale conferencing config. Consequences: - `?target=draft` with a conferencing op returns `400`. - A single request cannot mix conferencing ops with edits to other fields — split the request in two. - Publishing a stale draft never wipes deployed conferencing config; live conferencing is preserved. operationId: patchPal parameters: - name: target in: query required: false description: > Which row to write to when the PAL has an active PAL Builder draft. - Omitted (default): writes to the **draft** if one exists, otherwise to live. Live traffic is unchanged until you publish. - `draft`: same as the default. Rejected with `400` if the patch touches `layers.conferencing`. - `live`: writes directly to the live PAL and resets the draft to match, so live becomes the single source of truth. Any unpublished draft edits are discarded. For `layers.conferencing`, omit `target` or pass `target=live`. Explicit `target=draft` is rejected because conferencing is live-owned. schema: type: string enum: - draft - live example: live 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 PAL document. Paths must match the **current** document shape-compare the response from [Get PAL](/api-reference/pals/get-pal) (`GET /v2/pals/{pal_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 PAL System Prompt: summary: Edit the Builder draft (default when a draft exists) value: - op: replace path: /system_prompt value: >- As a Life Coach, you are a dedicated professional who specializes in... Remove STT Hotwords: summary: Remove a value; also draft-routed when a draft exists value: - op: remove path: /layers/stt/hotwords Update conferencing (always live): summary: layers.conferencing is live-owned; sent without ?target value: - op: replace path: /layers/conferencing/username value: acme-anna Enable EU AI Act disclosure: summary: Configure disclosure text so the PAL announces it is AI value: - op: replace path: /disclosure_type value: auto - op: replace path: /verbal_disclosure value: Just so you know, you're speaking with an AI agent. - op: replace path: /visual_disclosure value: You are speaking with an AI agent. Set biometric emotion recognition to limited: summary: Pin emotion recognition to limited for every conversation value: - op: replace path: /layers/perception/emotion_recognition value: limited responses: '200': description: > The patched PAL body. In addition to the usual PAL fields, the response includes routing metadata so you can confirm which row was written. content: application/json: schema: type: object properties: pal_id: type: string description: > The PAL id you called the endpoint with — always echoed back unchanged, even when the patch was routed to the draft or to live. Safe to persist on the client. example: pcb7a34da5fe edited_pal_id: type: string description: > The id of the row that was actually written. Equals `live_pal_id` when the patch went to live and `draft_pal_id` when it went to the draft. example: p5f1e8d2a934 edit_target: type: string enum: - draft - live description: > Which row this PATCH wrote to. `draft` when the request landed on an active PAL Builder draft (the default when one exists); `live` when it landed on the live PAL — either because no draft exists, `?target=live` was passed, or the patch touched `layers.conferencing`. example: draft live_pal_id: type: string description: >- The id of the live PAL. Same as `pal_id` when you called this endpoint with the live id. example: pcb7a34da5fe draft_pal_id: type: string nullable: true description: >- The id of the active draft row, or `null` when no draft exists. example: p5f1e8d2a934 publish_url: type: string description: >- Present when the patch was routed to a draft. POST to this path to make the draft live. example: /v2/pals/pcb7a34da5fe/publish routing_message: type: string description: > Human-readable summary of where the edit went and how live/draft are related after the patch. Useful to surface in logs when auditing writes. example: >- Edited the Builder draft (p5f1e8d2a934). The live PAL (pcb7a34da5fe) is unchanged and will not reflect these edits until you publish. To edit the live PAL directly, re-send with ?target=live (this discards unpublished draft edits and resyncs the draft from live). '304': description: No changes were made to the PAL content: application/json: schema: type: object properties: message: type: string description: The error message. example: No changes were made to the PAL '400': description: > Bad Request. Common draft-routing causes: - `target` is not `draft` or `live`. - `?target=draft` was passed with a patch op that touches `layers.conferencing` (conferencing is live-owned). - A single request mixes `layers.conferencing` ops with edits to other fields — split into two requests. content: application/json: schema: type: object properties: error: type: string description: The error message. example: >- layers.conferencing is live-owned deployment config; patch it with target=live '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: pal_id in: path required: true description: The unique identifier of the PAL. schema: type: string example: pcb7a34da5fe /v2/pals/{pal_id}/publish: post: tags: - PALs summary: Publish PAL description: > Publishes the PAL Builder draft associated with this `pal_id`, making its content the live version used by new conversations, deployments, and public reads. Call this after a draft-routed [Patch PAL](/api-reference/pals/patch-pal) response. That response includes a `publish_url` you can use directly. Publishing preserves the live `layers.conferencing` configuration and keeps the draft row available for future Builder edits. If the PAL has no Builder draft, the call is idempotent: Tavus returns the current live PAL. You can pass either the stable live PAL id or its underlying draft id, although integrations should normally keep and publish the stable live `pal_id`. operationId: publishPal responses: '200': description: The published live PAL. `status` is `success`. content: application/json: schema: type: object properties: status: type: string enum: - success example: success pal_id: type: string description: >- The stable id of the live PAL that now contains the published draft content. example: pcb7a34da5fe pal_name: type: string description: The published PAL name. example: Life Coach system_prompt: type: string description: The published system prompt. example: >- As a Life Coach, you are a dedicated professional who specializes in... updated_at: type: string description: The date and time when the live PAL was updated. example: '2026-07-14T17:00:00.000000' '400': description: >- Bad Request - the PAL does not exist or is not editable by the authenticated account. content: application/json: schema: type: object properties: error: type: string description: The error message. '401': description: UNAUTHORIZED content: application/json: schema: type: object properties: message: type: string example: Invalid access token security: - apiKey: [] parameters: - name: pal_id in: path required: true description: The unique identifier of the PAL. schema: type: string example: pcb7a34da5fe /v2/tools: post: tags: - Tools summary: Create Tool description: > Create a standalone tool that can be attached to one or more PALs via [Attach Tools To PAL](/api-reference/pal-tools/attach-tools-to-pal). **In-call tools** (`trigger_type: in_call`, default) are invoked during the conversation by an LLM (`origin: llm`) or a perception model (`origin: vision` / `origin: audio`). **Post-call actions** (`trigger_type: post_call`) run once after the conversation ends; omit `origin` and set `delivery.api` (HTTPS webhook). See [Post-Call Actions](/sections/conversational-video-interface/pal/post-call-tool). Every tool dispatches via **exactly one** delivery channel: - `delivery.app_message: true` (default) - calls land on your frontend as a `conversation.tool_call` event over the Daily data channel. - `delivery.api` - Tavus makes an HTTPS request to a URL you configure. Supports five auth types and `{placeholder}` templating in the URL path, query string, and body. See [Tools Overview](/sections/conversational-video-interface/pal/tools), [LLM Tool Delivery](/sections/conversational-video-interface/pal/llm-tool-delivery), and [LLM Tool Auth](/sections/conversational-video-interface/pal/llm-tool-auth) for the conceptual model. operationId: createTool requestBody: content: application/json: schema: type: object required: - name - description properties: name: type: string description: >- Function name the LLM uses to call the tool. Must match OpenAI function-naming rules (letters, digits, underscores; must start with a letter or underscore; max 64 characters) and be unique within your account. example: get_weather description: type: string description: >- Natural-language description used by the LLM to decide when to call the tool. `description` plus the serialized `parameters` together must be at most 10000 characters. example: Get the current weather for a city parameters: type: object description: >- JSON Schema describing the tool's arguments. Follows the standard OpenAI function-calling shape. Property names starting with `tavus_` are reserved for Tavus-injected placeholders and are rejected. default: {} example: type: object properties: city: type: string description: City name required: - city delivery: $ref: '#/components/schemas/toolDelivery' trigger_type: type: string enum: - in_call - post_call default: in_call description: >- When the tool runs. `in_call` (default) offers the tool during the live conversation. `post_call` runs once after the conversation ends; omit `origin` and set `delivery.api` (HTTPS webhook). See [Post-Call Actions](/sections/conversational-video-interface/pal/post-call-tool). example: in_call origin: type: string enum: - llm - vision - audio nullable: true default: llm description: >- Live modality for in-call tools only. Required when `trigger_type` is `in_call` (defaults to `llm`). Must be omitted or null for `post_call` tools. example: llm on_call: type: string enum: - generate_filler - static_filler - silent - passthrough default: generate_filler nullable: true description: >- What the PAL does **while** the tool call is in flight. `generate_filler` (default for `llm` tools) lets the LLM speak a contextual filler line. `static_filler` plays the `static_filler` string verbatim. `silent` says nothing. `passthrough` skips filler entirely. Must be null for perception tools. example: generate_filler on_resolve: type: string enum: - generate_response - response_in_result - add_to_context - fire_and_forget default: fire_and_forget nullable: true description: >- what the PAL does **after** the tool returns. `generate_response` re-prompts the LLM with the result so it can answer naturally. `response_in_result` speaks the response text returned by your endpoint verbatim. `add_to_context` silently adds the result to conversation context. `fire_and_forget` ignores the result. Perception tools must use `fire_and_forget`. example: generate_response static_filler: type: string nullable: true description: >- Phrase the PAL speaks while the tool call is in flight. Required when `on_call` is `static_filler`; must be null for perception tools. example: Sure, let me grab that for you. responses: '200': description: Tool created content: application/json: schema: $ref: '#/components/schemas/tool' '400': description: Bad Request - validation error content: application/json: schema: type: object properties: error: type: string example: 'Bad Request. {''delivery.api.url'': ''URL must use HTTPS''}' '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string example: Invalid access token '409': description: Conflict - a tool with this name already exists content: application/json: schema: type: object properties: error: type: string example: Bad Request. A tool with this name already exists security: - apiKey: [] get: tags: - Tools summary: Get Tools description: > Returns a paginated list of tools. The `type` query parameter controls which tools are returned: - `type=user` (default) - tools you created via [Create Tool](/api-reference/tools/create-tool). - `type=system` - built-in system tools Tavus provides. These are always available to every conversation; you do not need to attach them. The only system tool today is `end_call`, which lets the PAL hang up at a natural stopping point. - `type=all` - both, with system tools listed first. System tools have `is_system_tool: true`, an `owner_id` of `null`, and use their `name` as the `tool_id` (e.g. `end_call`). They cannot be created, updated, or deleted. operationId: getTools parameters: - in: query name: limit schema: type: integer default: 10 description: Page size. Default 10. - in: query name: page schema: type: integer default: 1 description: 1-indexed page number. Default 1. - in: query name: sort schema: type: string enum: - asc - desc default: asc description: Sort order by `created_at`. Default `asc`. - in: query name: type schema: type: string enum: - user - system - all default: user description: Which tools to return. - in: query name: name_or_uuid schema: type: string description: >- Optional filter. Case-insensitive substring match against `name`, or exact match against `tool_id`. responses: '200': description: Tools returned content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/tool' total_count: type: integer description: >- Total number of tools matching the filters (across all pages). example: 12 '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string example: Invalid access token security: - apiKey: [] /v2/tools/{tool_id}: parameters: - name: tool_id in: path required: true description: >- The unique identifier of the tool. For system tools this is the tool's `name` (e.g. `end_call`). schema: type: string example: tabc123def456 get: tags: - Tools summary: Get Tool description: >- Returns a single tool by its `tool_id`. Works for both user-owned tools and built-in system tools. Secret fields (`token`, `password`, `value`, `secret`, `client_secret`) are replaced with `********` in the response. operationId: getTool responses: '200': description: Tool returned content: application/json: schema: $ref: '#/components/schemas/tool' '400': description: Tool not found content: application/json: schema: type: object properties: error: type: string example: Bad Request. Tool not found '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string example: Invalid access token security: - apiKey: [] patch: tags: - Tools summary: Update Tool description: > Update one or more fields on a tool. Only fields present in the body are changed; omitted fields keep their stored value. System tools cannot be updated. **Secrets and the `********` placeholder.** [Get Tool](/api-reference/tools/get-tool) returns secret fields scrubbed to `********`. If you do a read-modify-write and PATCH that exact value back, the request is rejected - re-encrypting the placeholder would silently corrupt the stored secret. To keep the existing secret, **omit** the field from the auth object on PATCH. Sending `delivery: null` resets delivery to the default `{ app_message: true }`. operationId: updateTool requestBody: content: application/json: schema: type: object properties: name: type: string description: >- New function name. Same naming and uniqueness rules as on create. example: get_current_weather description: type: string description: >- New description. Max 10000 characters (combined with `parameters`). parameters: type: object description: >- Replace the JSON Schema for the tool's arguments. Reserved `tavus_*` property names are rejected. delivery: allOf: - $ref: '#/components/schemas/toolDelivery' nullable: true description: >- Replace the delivery config. `null` resets to the default `{ app_message: true }`. trigger_type: type: string enum: - in_call - post_call origin: type: string enum: - llm - vision - audio nullable: true on_call: type: string enum: - generate_filler - static_filler - silent - passthrough nullable: true on_resolve: type: string enum: - generate_response - response_in_result - add_to_context - fire_and_forget nullable: true static_filler: type: string nullable: true examples: Rename: value: name: get_current_weather Switch to API delivery: value: delivery: app_message: false api: url: https://api.example.com/weather method: POST auth: type: bearer token: sk_live_... Change static filler: value: on_call: static_filler static_filler: One moment please. responses: '200': description: Tool updated content: application/json: schema: $ref: '#/components/schemas/tool' '400': description: >- Bad Request - validation error, tool not found, or attempt to modify a system tool content: application/json: schema: type: object properties: error: type: string example: Bad Request. Cannot modify system tools '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string example: Invalid access token security: - apiKey: [] delete: tags: - Tools summary: Delete Tool description: >- Soft-deletes a tool and detaches it from every PAL it was attached to. The tool name is freed for reuse on a new tool. System tools cannot be deleted. operationId: deleteTool responses: '204': description: Tool deleted '400': description: Tool not found or attempt to delete a system tool content: application/json: schema: type: object properties: error: type: string example: Bad Request. Cannot delete system tools '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string example: Invalid access token security: - apiKey: [] /v2/pals/{pal_id}/tools: parameters: - name: pal_id in: path required: true description: The unique identifier of the PAL. schema: type: string example: p12345 post: tags: - PAL Tools summary: Attach Tools To PAL description: > Attach one or more tools (by `tool_id`) to a PAL. A PAL can have at most 50 attached tools. Attaching a tool that is already attached is idempotent - it is reported in the response alongside any newly-attached tools. operationId: attachToolsToPersona requestBody: content: application/json: schema: type: object required: - tool_ids properties: tool_ids: type: array items: type: string description: >- List of `tool_id` values to attach. Must not be empty; at most 50 per request. example: - tabc123def456 - tdef456abc789 responses: '200': description: Tools attached content: application/json: schema: type: object properties: data: type: array description: >- All tools that are now attached to the PAL, including ones that were already attached before this request. items: $ref: '#/components/schemas/tool' '400': description: PAL not found, unknown `tool_id`, or PAL tool limit exceeded content: application/json: schema: type: object properties: error: type: string example: Bad Request. One or more tool_ids not found '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string example: Invalid access token security: - apiKey: [] get: tags: - PAL Tools summary: List PAL Tools description: >- List all standalone tools currently attached to a PAL. Inline tools defined under `PAL.layers.llm.tools` and built-in system tools are not returned here - only tools created via [Create Tool](/api-reference/tools/create-tool) and attached to this PAL. operationId: listPersonaTools responses: '200': description: Attached tools returned content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/tool' '400': description: PAL not found content: application/json: schema: type: object properties: error: type: string example: Bad Request. PAL not found '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string example: Invalid access token security: - apiKey: [] /v2/pals/{pal_id}/tools/{tool_id}: parameters: - name: pal_id in: path required: true description: The unique identifier of the PAL. schema: type: string example: p12345 - name: tool_id in: path required: true description: The unique identifier of the tool. schema: type: string example: tabc123def456 delete: tags: - PAL Tools summary: Detach Tool From PAL description: >- Detach a tool from a PAL. The tool itself is not deleted - it remains available to attach to other PALs. operationId: detachToolFromPersona responses: '204': description: Tool detached '400': description: PAL not found, tool not found, or tool was not attached to this PAL content: application/json: schema: type: object properties: error: type: string example: Bad Request. Tool not attached to this PAL '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string example: Invalid access token security: - apiKey: [] /v2/skills: get: tags: - Skills summary: List Skills description: > List every skill in the registry. Skills are pre-built capabilities authored by Tavus that you can attach to a PAL - see [Skills](/sections/conversational-video-interface/skills/overview). operationId: listSkills responses: '200': description: Successfully retrieved the skill registry content: application/json: schema: type: object properties: data: type: array items: type: object properties: skill_id: type: string description: >- The unique identifier of the skill. Used as the path parameter on the PAL skill endpoints. example: internet_search display_name: type: string example: Internet Search description: type: string example: >- Lets the PAL answer questions with up-to-date information from the web. '401': description: UNAUTHORIZED content: application/json: schema: type: object properties: message: type: string example: Invalid access token security: - apiKey: [] /v2/skills/{skill_id}: get: tags: - Skills summary: Get Skill description: | Retrieve the metadata for a single skill in the registry. operationId: getSkill responses: '200': description: Successfully retrieved the skill content: application/json: schema: type: object properties: skill_id: type: string example: presentation display_name: type: string example: Presentation description: type: string example: >- Let the PAL walk participants through a slide deck made from uploaded documents. '401': description: UNAUTHORIZED content: application/json: schema: type: object properties: message: type: string example: Invalid access token '404': description: Not Found content: application/json: schema: type: object properties: error: type: string example: Unknown skill 'my_skill' security: - apiKey: [] parameters: - name: skill_id in: path required: true description: The unique identifier of the skill. schema: type: string example: internet_search /v2/pals/{pal_id}/skills: get: tags: - Skills summary: List PAL Skills description: > List the skills attached to a PAL. The response is an object keyed by `skill_id`. operationId: listPersonaSkills responses: '200': description: Successfully retrieved the PAL's skill attachments content: application/json: schema: type: object properties: data: type: object description: Skill attachments keyed by `skill_id`. additionalProperties: $ref: '#/components/schemas/SkillAttachment' example: internet_search: skill_id: internet_search config: {} attached_at: '2026-06-10T14:30:45.123456+00:00' updated_at: '2026-06-10T14:30:45.123456+00:00' presentation: skill_id: presentation config: document_ids: - d1234567890 - d2468101214 slides_trigger: walk_the_deck prompt: Walk the participant through the Q4 roadmap deck. attached_at: '2026-06-10T13:15:20.654321+00:00' updated_at: '2026-06-10T14:25:10.987654+00:00' magic_canvas: skill_id: magic_canvas config: components: chart: enabled: false attached_at: '2026-06-10T12:00:00.000000+00:00' updated_at: '2026-06-10T12:00:00.000000+00:00' '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string example: PAL not found '401': description: UNAUTHORIZED content: application/json: schema: type: object properties: message: type: string example: Invalid access token security: - apiKey: [] put: tags: - Skills summary: Replace PAL Skills description: > Replace a PAL's entire skill set in one call. Skills not present in the request are detached. operationId: replacePersonaSkills requestBody: content: application/json: schema: type: object properties: skills: type: object description: >- The complete skill set for the PAL, keyed by `skill_id`. Each value holds that skill's `config` object (omit or pass `{}` for skills with no configuration). additionalProperties: type: object properties: config: type: object description: >- The configuration for this skill. Validated against the skill's config schema. example: internet_search: {} presentation: config: document_ids: - d1234567890 slides_trigger: on_demand magic_canvas: config: {} required: - skills required: true responses: '200': description: Successfully replaced the PAL's skill attachments content: application/json: schema: type: object properties: data: type: object description: The PAL's new skill attachments keyed by `skill_id`. additionalProperties: $ref: '#/components/schemas/SkillAttachment' '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string example: >- Bad Request: {'skills': {'presentation': {'config': {'document_ids': ['Missing data for required field.']}}}} '401': description: UNAUTHORIZED content: application/json: schema: type: object properties: message: type: string example: Invalid access token '404': description: Not Found content: application/json: schema: type: object properties: error: type: string example: Unknown skill 'my_skill' security: - apiKey: [] parameters: - name: pal_id in: path required: true description: The unique identifier of the PAL. schema: type: string example: pcb7a34da5fe /v2/pals/{pal_id}/skills/{skill_id}: get: tags: - Skills summary: Get PAL Skill description: | Retrieve a single skill attachment on a PAL. operationId: getPersonaSkill responses: '200': description: Successfully retrieved the skill attachment content: application/json: schema: $ref: '#/components/schemas/SkillAttachment' '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string example: PAL not found '401': description: UNAUTHORIZED content: application/json: schema: type: object properties: message: type: string example: Invalid access token '404': description: Not Found content: application/json: schema: type: object properties: error: type: string example: Skill 'presentation' is not attached to this PAL security: - apiKey: [] put: tags: - Skills summary: Attach Skill to PAL description: > Attach a skill to a PAL, or overwrite the configuration of an existing attachment. The skill is active on the PAL's next conversation. Skills with no configuration (like `internet_search`) take an empty body or `{"config": {}}`. See [Skills](/sections/conversational-video-interface/skills/overview) for each skill's configuration fields. For `magic_canvas`, see [Canvas configuration](/sections/conversational-video-interface/magic-canvas/api/configuration). operationId: attachSkillToPersona requestBody: content: application/json: schema: type: object properties: config: type: object description: > The configuration for the skill, validated against the skill's config schema. Defaults to `{}`. - `presentation`: `document_ids` (required array), optional `slides_trigger` (`on_demand` (default) or `walk_the_deck`), optional `prompt`. - `magic_canvas`: optional sparse `components` overlay, plus optional `usage_guidance` (string, max 2048 characters) appended to the Canvas system prompt to steer when the PAL shows cards. Ignored when blank or when no Canvas component is active. See [Canvas configuration](/sections/conversational-video-interface/magic-canvas/api/configuration). example: document_ids: - d1234567890 - d2468101214 slides_trigger: walk_the_deck prompt: Walk the participant through the Q4 roadmap deck. examples: no_config: summary: Skill without configuration value: config: {} presentation: summary: Presentation skill value: config: document_ids: - d1234567890 - d2468101214 slides_trigger: walk_the_deck prompt: Walk the participant through the Q4 roadmap deck. magic_canvas: summary: Magic Canvas skill value: config: usage_guidance: >- Show a chart whenever you compare numbers; ask with a question card before booking. components: scheduling_embed: provider: calendly scheduling_url: https://calendly.com/your-team/30min responses: '200': description: Successfully attached the skill content: application/json: schema: $ref: '#/components/schemas/SkillAttachment' '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string example: >- Bad Request: {'document_ids': ['Missing data for required field.']} '401': description: UNAUTHORIZED content: application/json: schema: type: object properties: message: type: string example: Invalid access token '404': description: Not Found content: application/json: schema: type: object properties: error: type: string example: Unknown skill 'my_skill' security: - apiKey: [] patch: tags: - Skills summary: Update PAL Skill description: > Merge changes into an existing skill attachment's configuration. Fields you pass replace the existing values, fields you omit are preserved, and fields set to `null` are removed. The merged configuration is validated against the skill's config schema. Unlike [Attach Skill to PAL](/api-reference/pal-skills/attach-skill-to-pal), this endpoint cannot create a new attachment - the skill must already be attached. operationId: updatePersonaSkill requestBody: content: application/json: schema: type: object properties: config: type: object description: Partial configuration to merge into the existing config. example: slides_trigger: on_demand required: - config required: true responses: '200': description: Successfully updated the skill attachment content: application/json: schema: $ref: '#/components/schemas/SkillAttachment' '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string example: >- Bad Request: {'config': ['Missing data for required field.']} '401': description: UNAUTHORIZED content: application/json: schema: type: object properties: message: type: string example: Invalid access token '404': description: Not Found content: application/json: schema: type: object properties: error: type: string example: Skill 'presentation' is not attached to this PAL security: - apiKey: [] delete: tags: - Skills summary: Detach Skill from PAL description: > Detach a skill from a PAL. The skill no longer applies to the PAL's future conversations. The skill itself stays in the registry and can be re-attached at any time. operationId: detachSkillFromPersona responses: '204': description: Successfully detached the skill '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string example: PAL not found '401': description: UNAUTHORIZED content: application/json: schema: type: object properties: message: type: string example: Invalid access token '404': description: Not Found content: application/json: schema: type: object properties: error: type: string example: Skill 'presentation' is not attached to this PAL security: - apiKey: [] parameters: - name: pal_id in: path required: true description: The unique identifier of the PAL. schema: type: string example: pcb7a34da5fe - name: skill_id in: path required: true description: The unique identifier of the skill. schema: type: string example: presentation /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 PAL. 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: > Create a new guardrail. Guardrails provide strict behavioral boundaries that are enforced throughout a conversation. Attach guardrails to a PAL directly via `guardrail_ids` or by tag via `guardrail_tags` on [Create PAL](/api-reference/pals/create-pal). See [Deprecated guardrail sets](/api-reference/guardrails/legacy-guardrail-sets). operationId: createGuardrails requestBody: content: application/json: schema: type: object properties: guardrail_name: type: string maxLength: 100 description: >- A descriptive name for the guardrail. Only alphanumeric characters and underscores are allowed. Maximum 100 characters. example: healthcare_compliance_guardrail guardrail_prompt: type: string maxLength: 1000 description: >- The detailed prompt that defines the behavioral boundaries and restrictions. Keep this short and direct for best enforcement. Maximum 1,000 characters. 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 is enforced against the participant's spoken/typed responses. If set to `visual`, the guardrail is enforced against visual/perception cues observed by Raven. enum: - verbal - visual default: verbal example: verbal callback_url: type: string maxLength: 2048 description: >- Optional URL that will receive a notification when the guardrail is triggered during a conversation. Maximum 2,048 characters. example: https://your-server.com/guardrails-webhook tags: type: array maxItems: 32 description: >- Optional tags for organizing guardrails and for attaching them to PALs in bulk via `guardrail_tags` on [Create PAL](/api-reference/pals/create-pal). Up to 32 tags per guardrail. Tag names are limited to 64 characters. items: type: string maxLength: 64 example: - compliance - healthcare app_message: type: boolean description: >- Whether triggering this guardrail emits a real-time app-message event on the conversation. Default `true`. Set to `false` to suppress the in-conversation event for guardrails you only want to observe server-side via `callback_url`. default: true example: true required: - guardrail_name - guardrail_prompt examples: minimal: summary: Required fields only value: guardrail_name: no_competitors guardrail_prompt: >- Only mention products within Our Company Inc. during conversations; never discuss competitors. with_tags: summary: Guardrail with tags for tag-based attachment value: guardrail_name: healthcare_compliance guardrail_prompt: >- Never share sensitive medical information or provide medical advice outside approved guidelines. modality: verbal callback_url: https://your-server.com/guardrails-webhook tags: - compliance - healthcare responses: '200': description: Guardrail created successfully content: application/json: schema: type: object properties: uuid: type: string description: >- Unique identifier for the created guardrail. Use this value in `guardrail_ids` on a PAL. example: g1234567890ab guardrail_name: type: string example: healthcare_compliance_guardrail guardrail_prompt: type: string example: >- Never share sensitive medical information or provide medical advice outside approved guidelines. modality: type: string enum: - verbal - visual example: verbal callback_url: type: string example: https://your-server.com/guardrails-webhook tags: type: array items: type: string example: - compliance - healthcare app_message: type: boolean description: >- Whether triggering this guardrail emits a real-time app-message event on the conversation. example: true created_at: type: string example: '2024-01-15T10:30:00Z' updated_at: type: string example: '2024-01-15T10:30:00Z' '400': description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: error: type: string example: guardrail_name is required '401': description: UNAUTHORIZED content: application/json: schema: type: object properties: message: type: string example: Invalid access token security: - apiKey: [] get: tags: - Guardrails summary: List Guardrails description: > Return a flat list of guardrails owned by the caller. Pass `legacy=false` - recommended for all new integrations. The `legacy=true` behavior returns the deprecated guardrail set list. operationId: listGuardrails parameters: - in: query name: legacy schema: type: string enum: - 'true' - 'false' description: >- **Pass `false`** to return individual guardrails (recommended). Defaults to `true` for backwards compatibility, which returns the deprecated guardrail set list. example: 'false' - in: query name: limit schema: type: integer description: Number of guardrails to return per page. Default is 10. example: 10 - in: query name: page schema: type: integer description: Page number (0-indexed when `legacy=false`). Default is 0. example: 0 - in: query name: sort schema: type: string enum: - ascending - descending description: Sort direction. Default is `ascending`. - in: query name: name_or_uuid schema: type: string description: Filter results by guardrail name or UUID. - in: query name: tags schema: type: string description: Comma-separated list of tags to filter by. Any-match (OR) semantics. example: compliance,healthcare responses: '200': description: Successfully retrieved guardrails content: application/json: schema: type: object properties: data: type: array description: >- Guardrails for the current page; use `total_count` for the full count under the applied filters. items: type: object properties: uuid: type: string example: g1234567890ab guardrail_name: type: string example: healthcare_compliance_guardrail guardrail_prompt: type: string example: >- Never share sensitive medical information or provide medical advice outside approved guidelines. modality: type: string enum: - verbal - visual example: verbal callback_url: type: string example: https://your-server.com/guardrails-webhook tags: type: array items: type: string example: - compliance - healthcare app_message: type: boolean description: >- Whether triggering this guardrail emits a real-time app-message event on the conversation. example: true created_at: type: string example: '2024-01-15T10:30:00Z' updated_at: type: string example: '2024-01-15T10:30:00Z' total_count: type: integer description: Total number of guardrails matching the filter. example: 15 page: type: integer example: 0 limit: type: integer example: 10 '401': description: UNAUTHORIZED content: application/json: schema: type: object properties: message: type: string example: Invalid access token security: - apiKey: [] /v2/guardrails/tags: get: tags: - Guardrails summary: List Guardrail Tags x-hidden: true description: > List all guardrail tags owned by the caller, with the `guardrail_ids` associated with each tag. Mirrors `GET /v2/documents/tags`. operationId: listGuardrailTags parameters: - in: query name: search schema: type: string minLength: 1 maxLength: 100 description: Optional case-insensitive substring filter on tag name. - in: query name: page schema: type: integer minimum: 1 description: 1-indexed page number. - in: query name: limit schema: type: integer description: Number of tags to return per page. responses: '200': description: Successfully retrieved tags content: application/json: schema: type: object properties: tags: type: array items: type: object properties: tag: type: string example: compliance guardrail_ids: type: array items: type: string example: - g1234567890ab - g0987654321cd total_count: type: integer example: 5 '401': description: UNAUTHORIZED security: - apiKey: [] /v2/guardrails/{guardrail_id}: get: tags: - Guardrails summary: Get Guardrails description: | Retrieve a single guardrail by its unique identifier. operationId: getGuardrails responses: '200': description: Successfully retrieved the guardrail content: application/json: schema: type: object properties: uuid: type: string example: g1234567890ab guardrail_name: type: string example: healthcare_compliance_guardrail guardrail_prompt: type: string example: >- Never share sensitive medical information or provide medical advice outside approved guidelines. modality: type: string enum: - verbal - visual example: verbal callback_url: type: string example: https://your-server.com/guardrails-webhook tags: type: array items: type: string example: - compliance - healthcare app_message: type: boolean description: >- Whether triggering this guardrail emits a real-time app-message event on the conversation. example: true created_at: type: string example: '2024-01-15T10:30:00Z' updated_at: type: string example: '2024-01-15T10:30:00Z' '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string example: Guardrail not found '401': description: UNAUTHORIZED content: application/json: schema: type: object properties: message: type: string example: Invalid access token security: - apiKey: [] patch: tags: - Guardrails summary: Patch Guardrails description: > Update specific fields of a guardrail using [JSON Patch](https://jsonpatch.com/) operations. Paths must match the **current** document shape - compare against the response from [Get Guardrails](/api-reference/guardrails/get-guardrails) before patching. operationId: patchGuardrails requestBody: content: application/json: schema: type: array items: type: object properties: op: type: string enum: - add - remove - replace - copy - move - test example: replace path: type: string description: >- JSON Pointer (RFC 6901) to a field on the guardrail (e.g. `/guardrail_prompt`, `/tags`, `/modality`). example: /guardrail_prompt value: description: >- The value used by the operation. Not required for `remove`. example: Updated prompt with stricter restrictions. required: - op - path examples: Update prompt: value: - op: replace path: /guardrail_prompt value: Never discuss competitor products under any circumstances. Add a tag: value: - op: add path: /tags/- value: compliance Replace all tags: value: - op: replace path: /tags value: - compliance - healthcare Remove callback URL: value: - op: remove path: /callback_url Suppress app message: value: - op: replace path: /app_message value: false responses: '200': description: Guardrail updated successfully content: application/json: schema: type: object properties: uuid: type: string example: g1234567890ab guardrail_name: type: string guardrail_prompt: type: string modality: type: string callback_url: type: string tags: type: array items: type: string app_message: type: boolean description: >- Whether triggering this guardrail emits a real-time app-message event on the conversation. updated_at: type: string '304': description: No changes were made to the guardrail '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string example: Invalid patch operation '401': description: UNAUTHORIZED content: application/json: schema: type: object properties: message: type: string example: Invalid access token '422': description: Invalid JSON patch format security: - apiKey: [] delete: tags: - Guardrails summary: Delete Guardrails description: > Delete a single guardrail by its unique identifier. PALs with this guardrail attached via `guardrail_ids` will have the reference removed automatically. operationId: deleteGuardrails responses: '204': description: NO CONTENT - Guardrail deleted successfully '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string example: Guardrail not found '401': description: UNAUTHORIZED content: application/json: schema: type: object properties: message: type: string example: Invalid access token security: - apiKey: [] parameters: - name: guardrail_id in: path required: true description: The unique identifier of the guardrail. schema: type: string example: g1234567890ab /v2/documents: post: tags: - Documents summary: Create Document description: >- Upload documents to your knowledge base for PALs 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 PAL](/api-reference/pals/create-pal) 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/pal/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 PAL 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 PALs 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 PALs. 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 PALs 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: Faces - name: Voices - name: Conversations - name: Deployments - name: PALs - name: Tools - name: PAL Tools - name: Pronunciation Dictionaries - name: Replacements - name: Transcriptions - name: Documents components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key schemas: tool: type: object description: >- A standalone tool definition. Returned by every tool endpoint and embedded in the `data` array of the PAL-tool endpoints. properties: tool_id: type: string description: >- Unique identifier for the tool. System tools use their `name` as the `tool_id` (e.g. `end_call`). example: tabc123def456 owner_id: type: integer nullable: true description: >- Internal user ID that owns the tool. `null` for built-in system tools. example: 3675 name: type: string description: Function name the LLM uses to call the tool. example: get_weather description: type: string description: Natural-language description of the tool. example: Get the current weather for a city parameters: type: object description: JSON Schema describing the tool's arguments. example: type: object properties: city: type: string description: City name required: - city delivery: $ref: '#/components/schemas/toolDelivery' is_system_tool: type: boolean description: >- Whether this is a built-in system tool. System tools cannot be modified or deleted. example: false trigger_type: type: string enum: - in_call - post_call description: >- When the tool runs. `post_call` tools execute server-side after the conversation ends via `delivery.api` (HTTPS webhook). example: in_call origin: type: string enum: - llm - vision - audio nullable: true description: Live modality for in-call tools. Null for post-call tools. example: llm on_call: type: string enum: - generate_filler - static_filler - silent - passthrough nullable: true description: >- What the PAL does while the tool call is in flight. Always null for perception tools. example: generate_filler on_resolve: type: string enum: - generate_response - response_in_result - add_to_context - fire_and_forget nullable: true description: What the PAL does after the tool returns. example: generate_response static_filler: type: string nullable: true description: >- Phrase the PAL speaks while the tool call is in flight. Set when `on_call` is `static_filler`. example: Sure, let me grab that for you. created_at: type: string description: ISO 8601 timestamp of when the tool was created. example: '2026-05-15T10:30:00' updated_at: type: string description: ISO 8601 timestamp of when the tool was last updated. example: '2026-05-15T10:30:00' toolDelivery: type: object description: > How the tool call is dispatched. Exactly one channel must be enabled: - `app_message: true` alone - the call is delivered to your frontend over the Daily data channel as a `conversation.tool_call` event. - `api` set with `app_message: false` - Tavus makes an HTTPS request to `api.url`. If `delivery` is omitted on create, the default is `{ "app_message": true }`. properties: app_message: type: boolean default: true description: >- Set to `true` to deliver tool calls to your frontend as `conversation.tool_call` events. Mutually exclusive with `api`. api: $ref: '#/components/schemas/toolApiDelivery' toolApiDelivery: type: object required: - url description: HTTPS request configuration for tool calls delivered via API. properties: url: type: string description: > HTTPS URL Tavus calls. Must use `https://`. Hostname must not point at private / loopback / link-local / metadata-server IP space and must not contain `{placeholder}` substitutions - placeholders are only resolved in the path, query string, and body. example: https://api.example.com/v1/weather/{city} method: type: string enum: - GET - POST - PUT - PATCH - DELETE - HEAD default: POST description: HTTP method. `GET`, `HEAD`, and `DELETE` reject `body_template`. timeout: type: number minimum: 0 exclusiveMinimum: true maximum: 60 default: 10 description: >- Request timeout in seconds. Must be greater than 0 and at most 60. Default 10. headers: type: object additionalProperties: type: string description: >- Static HTTP headers sent with every request. Keys and values must be strings. example: X-Service: weather-bot auth: $ref: '#/components/schemas/toolAuth' body_template: type: object description: >- Optional JSON object used as the request body. String values support `{placeholder}` substitutions referencing keys declared in the tool's `parameters.properties`. Rejected when `method` is `GET`, `HEAD`, or `DELETE`, and ignored when `auth.type` is `hmac` (which uses a fixed Tavus envelope). query_params: type: object additionalProperties: type: string description: >- Static query parameters appended to the URL. Keys and values must be strings; values support `{placeholder}` substitutions. Ignored when `auth.type` is `hmac`. example: units: metric content_type: type: string description: >- Override the request `Content-Type` header. Defaults to `application/json` when not set. example: application/json toolAuth: type: object required: - type description: > Outbound authentication for API delivery. The required fields depend on `type`: - `none` - no auth. - `bearer` - `token` is sent as `Authorization: Bearer `. - `basic` - `username` + `password` are encoded into `Authorization: Basic ...`. - `api_key` - `name` + `value` are sent as a header (`location: header`, default) or query parameter (`location: query`). - `hmac` - `secret` signs a fixed Tavus envelope body with HMAC-SHA256; the signature is sent in the `X-Tavus-Signature` header. HMAC mode ignores `body_template`, `query_params`, and URL placeholders. - `oauth2_client_credentials` - Tavus does a client-credentials exchange against `token_url` using `client_id` + `client_secret` (and optional `scope`) and uses the returned bearer token to call the tool URL. On response, all secret fields (`token`, `password`, `value`, `secret`, `client_secret`) are scrubbed to `********`. Echoing that back on PATCH is rejected; omit the field instead to keep the stored secret. properties: type: type: string enum: - none - bearer - basic - api_key - hmac - oauth2_client_credentials description: Auth strategy. token: type: string description: Bearer token. Required when `type=bearer`. username: type: string description: HTTP Basic username. Required when `type=basic`. password: type: string description: HTTP Basic password. Required when `type=basic`. name: type: string description: API key header / query parameter name. Required when `type=api_key`. example: X-API-Key value: type: string description: API key value. Required when `type=api_key`. location: type: string enum: - header - query default: header description: Where the API key is sent. Used only when `type=api_key`. secret: type: string description: HMAC shared secret. Required when `type=hmac`. token_url: type: string description: >- OAuth2 token endpoint. Must use HTTPS and pass the same SSRF rules as the tool URL. Required when `type=oauth2_client_credentials`. example: https://auth.example.com/oauth/token client_id: type: string description: OAuth2 client ID. Required when `type=oauth2_client_credentials`. client_secret: type: string description: >- OAuth2 client secret. Required when `type=oauth2_client_credentials`. scope: type: string description: >- Optional OAuth2 scope string. Used only when `type=oauth2_client_credentials`. SkillAttachment: type: object description: A skill attached to a PAL. properties: skill_id: type: string description: The unique identifier of the attached skill. example: presentation config: type: object description: > The skill's configuration. Empty object for skills with no configuration. Shape depends on `skill_id` - see [Skills](/sections/conversational-video-interface/skills/overview). For `magic_canvas`, `config.components` is a sparse overlay and `config.usage_guidance` is an optional string (max 2048 characters) that steers when the PAL shows cards; see [Canvas configuration](/sections/conversational-video-interface/magic-canvas/api/configuration). example: document_ids: - d1234567890 - d2468101214 slides_trigger: walk_the_deck prompt: Walk the participant through the Q4 roadmap deck. attached_at: type: string description: ISO 8601 timestamp of when the skill was first attached to the PAL. example: '2026-06-10T14:30:45.123456+00:00' updated_at: type: string description: ISO 8601 timestamp of when the attachment was last modified. example: '2026-06-10T14:30:45.123456+00:00' conferencingLayer: type: object description: > [Conferencing layer](/sections/conversational-video-interface/pal/meetings) settings. Provisions a `@tavusinvite.com` email identity so the PAL can be invited to Google Calendar events with Google Meet links and join automatically. Requires `default_face_id` on the PAL. properties: username: type: string minLength: 2 description: > Local part of the PAL's meeting email (`@tavusinvite.com`). Stored lowercase. Must start and end with an alphanumeric character; `.`, `_`, and `-` are allowed in between. Usernames matching `botN` (for example `bot1`, `bot42`) are reserved. Globally unique across `tavusinvite.com`. example: acme-anna allowlist: type: array description: > Controls who may invite this PAL via calendar. Each entry is an exact email address or a regex matched against the organizer's email. Empty or omitted allows any sender. items: type: string example: - alex@acme.com - .*@acme\.com required: - username conferencingUsernameCheck: type: object description: >- Result of [Check Conferencing Username Availability](/api-reference/pals/check-conferencing-username). properties: available: type: boolean description: '`true` when the username can be used on `tavusinvite.com`.' example: true reason: type: string description: Present when `available` is `false`. example: Username is already taken. createDeploymentRequest: type: object required: - pal_id - channel properties: pal_id: type: string description: PAL that powers the deployment. example: pcb7a34da5fe channel: type: string enum: - widget - embed - landing-page description: >- Delivery channel. See [Deployments overview](/sections/deployments/overview). name: type: string description: Display name in the Platform. password: type: string nullable: true description: Optional password visitors must enter before starting. customization: type: object description: >- Visual and conversation settings. Configure in the Platform or via JSON Patch on update. limits: type: object description: Call limits and max duration. allowed_origins: type: array items: type: string description: Origins allowed to load widget/embed deployments. deployment: type: object description: >- A managed deployment. See [Deployments overview](/sections/deployments/overview). properties: deployment_id: type: string example: d1234567890abcdef pal_id: type: string description: PAL that powers the deployment. example: pcb7a34da5fe channel: type: string enum: - widget - embed - landing-page status: type: string enum: - draft - active - inactive name: type: string has_password: type: boolean customization: type: object replica_thumbnail_video_url: type: string nullable: true deprecated: true description: >- **Removed.** Use `thumbnail_video_url` and `thumbnail_image_url` instead. thumbnail_video_url: type: string nullable: true description: URL for the face preview video thumbnail. thumbnail_image_url: type: string nullable: true description: URL for the face preview image thumbnail. limits: type: object allowed_origins: type: array items: type: string usage_total: type: integer usage_today: type: integer created_at: type: string format: date-time updated_at: type: string format: date-time deploymentInitConfig: type: object description: >- Configuration returned to widget, embed, and landing-page clients on init. properties: deployment_id: type: string channel: type: string enum: - widget - embed - landing-page customization: type: object description: >- Full customization tree including channel-specific blocks (`widget`, `landing_page`) and shared screens (`preview`, `haircheck`, `after_call`). has_password: type: boolean replica_thumbnail_video_url: type: string nullable: true deprecated: true description: >- **Removed.** Use `thumbnail_video_url` and `thumbnail_image_url` instead. thumbnail_video_url: type: string nullable: true description: URL for the face preview video thumbnail. thumbnail_image_url: type: string nullable: true description: URL for the face preview image thumbnail. show_tavus_branding: type: boolean limits: type: object properties: max_call_duration: type: integer nullable: true daily_call_limit_per_user: type: integer nullable: true captcha: type: object nullable: true description: Present when Turnstile is enabled. properties: provider: type: string site_key: type: string challenge_path: type: string action: type: string is_available: type: boolean unavailable_reason: type: string description: >- Set when `is_available` is false, e.g. `daily_limit` or `total_limit`. deploymentStartRequest: type: object properties: password: type: string nullable: true conversational_context: type: string description: Per-call context forwarded to the PAL. custom_greeting: type: string pal_id: type: string description: Preview-only PAL override for portal testing. memory_stores: type: array items: type: string captcha_token: type: string description: Cloudflare Turnstile token when captcha is enabled. deploymentConversationStart: type: object description: Same shape as Create Conversation. properties: conversation_id: type: string conversation_name: type: string conversation_url: type: string status: type: string callback_url: type: string created_at: type: string meeting_token: type: string description: Present when `require_auth` is true on the created conversation. canvasInteractionRequest: type: object description: >- Body for [Record Canvas Interaction](/api-reference/canvas-interactions/record-canvas-interaction). `value` validation depends on `component` and `type` - see [Canvas interactions](/sections/conversational-video-interface/magic-canvas/api/interactions#value-rules-per-component). required: - interaction_id - tool_call_id - component - component_version - type - value properties: interaction_id: type: string minLength: 1 maxLength: 128 description: >- Idempotency key. Unique per logical interaction; reuse verbatim on retries. Tavus clients use `ci_{tool_call_id}_{type}_{uuid}`. example: ci_call_8f2d41_submit_5e0b7c2a tool_call_id: type: string minLength: 1 maxLength: 128 description: >- The id of the Canvas invocation that showed the card. Ties the interaction to a specific card instance. example: call_8f2d41 component: type: string enum: - canvas.question - canvas.input - canvas.calendar - canvas.scheduling_embed - canvas.text - canvas.image - canvas.video - canvas.chart - canvas.alert description: Component id. example: canvas.question component_version: type: string description: Component contract version. `v1` for all current components. example: v1 type: type: string enum: - submit - skip - dismiss - clear - error - heartbeat description: >- Interaction type. Submit-capable components also allow `submit` and `skip`. example: submit value: type: object description: >- Interaction payload. At most 16 KB serialized. Shape depends on `component` and `type`. example: selected_option_ids: - opt_2 skipped: false metadata: type: object description: >- Optional client annotations, at most 4 KB serialized. Not part of idempotency matching. default: {} example: client: kiosk-web canvasInteractionRecord: type: object description: >- A recorded Canvas interaction. Returned by [List Canvas Interactions](/api-reference/canvas-interactions/list-canvas-interactions) and delivered in the `properties` object of a [`canvas.interaction`](/sections/event-schemas/canvas-interaction) webhook. properties: conversation_id: type: string example: c123456 interaction_id: type: string example: ci_call_8f2d41_submit_5e0b7c2a tool_call_id: type: string description: The Canvas invocation that showed the card. example: call_8f2d41 component: type: string example: canvas.question component_version: type: string example: v1 type: type: string example: submit value: type: object example: selected_option_ids: - opt_2 skipped: false metadata: type: object example: client: kiosk-web created_at: type: string nullable: true description: >- When the interaction was recorded. Naive ISO-8601 with microseconds and no timezone suffix (UTC). example: '2026-06-09T21:14:03.518923' canvas_interaction: description: > #### Outbound: Tavus delivers a recorded Magic Canvas interaction to your conversation `callback_url`. Configure Magic Canvas on the PAL first - see [Magic Canvas overview](/sections/conversational-video-interface/magic-canvas/overview). Full interaction rules: [Canvas interactions](/sections/conversational-video-interface/magic-canvas/api/interactions). type: object example: message_type: canvas event_type: canvas.interaction conversation_id: c123456 timestamp: '2026-06-09T21:14:03.498Z' properties: conversation_id: c123456 interaction_id: ci_call_8f2d41_submit_5e0b7c2a tool_call_id: call_8f2d41 component: canvas.question component_version: v1 type: submit value: selected_option_ids: - opt_2 skipped: false metadata: client: kiosk-web created_at: '2026-06-09T21:14:03.518923' properties: message_type: type: string description: '`canvas` for Magic Canvas webhook events.' example: canvas event_type: type: string description: '`canvas.interaction`.' example: canvas.interaction conversation_id: type: string description: The unique identifier for the conversation. example: c123456 timestamp: type: string description: ISO-8601 timestamp with a `Z` suffix (UTC). example: '2026-06-09T21:14:03.498Z' properties: $ref: '#/components/schemas/canvasInteractionRecord' 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 PAL text and interruption flags. For PAL turns, Tavus sends **duplicate** app-messages with the same payload except `properties.role`: `"pal"` (use in new integrations) and `"replica"` (legacy). User turns use `"user"` only. 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: pal 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 PAL 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 PAL uses Raven-1, optional `user_audio_analysis` / `user_visual_analysis` may appear when non-empty. properties: role: type: string description: >- `pal` or `user` for new integrations. Tavus also sends a legacy duplicate with `replica` instead of `pal` for the same PAL turn. example: pal speech: type: string description: >- Plain text after server-side sanitization. For `pal` (and legacy `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. For PAL turns, duplicate app-messages are sent with `properties.role` of `"pal"` and legacy `"replica"` (same payload otherwise). 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: pal 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 PAL's current inference turn. Can be used to correlate with other events such as `conversation.utterance` and `conversation.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: >- PAL and user streaming share this shape; `is_interrupted` appears on PAL messages when relevant. properties: role: type: string description: >- `pal` or `user`. Legacy duplicate PAL frames use `replica` instead of `pal`. example: pal 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: >- PAL 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 PAL has summarized what was visually observed, Tavus sends that full perception analysis (Raven-1 PALs). Requires Raven-style perception; see [Perception - end-of-call perception analysis](/sections/conversational-video-interface/pal/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 PALs). 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/pal/perception-tool) and [Perception](/sections/conversational-video-interface/pal/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 PAL: [LLM tool calling](/sections/conversational-video-interface/pal/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 face: description: > #### Outbound: Tavus tells you when the PAL 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 face 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 PAL 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 PAL or the user starts or stops speaking, using one event stream and a `properties.role` field instead of separate user- versus PAL-only events. `conversation.started_speaking` fires when either party begins speaking; `conversation.stopped_speaking` when either stops. For PAL turns, Tavus sends **duplicate** app-messages with the same payload except `properties.role`: `"pal"` (new integrations) and `"replica"` (legacy). 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: pal 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` (`"pal"` or `"user"`) identifying who started or stopped speaking. Legacy duplicate PAL events use `"replica"` instead of `"pal"`. 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: >- `pal` if the Tavus PAL is the speaker, `user` if the end user is the speaker. Legacy duplicates use `replica` instead of `pal`. enum: - pal - user example: pal 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 PAL 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/pal/conversational-flow) (`turn_taking_patience`, `pal_interruptibility`). properties: participant_pause_sensitivity: type: string description: How long a pause before the PAL responds. enum: - superlow - verylow - low - medium - high - auto example: medium participant_interrupt_sensitivity: type: string description: How readily the user’s speech interrupts the face. enum: - superlow - verylow - low - medium - high - auto example: medium overwrite_llm_context: description: > #### Inbound: Broadcast this to Tavus to overwrite the conversational context the PAL 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 face’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 PAL 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 PAL speaks exactly what you supply. Use this for echo-mode PALs, custom ASR flows, or other applications that provide the PAL's text or audio directly. 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 PAL so it stops talking. 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 PAL to respond to as if the user had just spoken that transcript in the conversation. Use this for chat-style text input where a user types a message and the PAL should answer. 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: []