> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tavus.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Get PAL
> Returns a single PAL by its unique identifier.
For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract.
Pending edits from [PAL Maker](https://maker.tavus.io/dev) are not returned unless the deployments have been updated. See [PAL editing lifecycle](/sections/conversational-video-interface/pal/editing-lifecycle).
## OpenAPI
````yaml get /v2/pals/{pal_id}
openapi: 3.0.3
info:
title: Tavus Developer API Collection
version: 1.0.0
contact: {}
servers:
- url: https://tavusapi.com
security:
- apiKey: []
tags:
- name: Videos
- name: Faces
- name: Voices
- name: Conversations
- name: Deployments
- name: PALs
- name: Tools
- name: PAL Tools
- name: Connectors
- name: Pronunciation Dictionaries
- name: Replacements
- name: Transcriptions
- name: Documents
- name: Memory Stores
paths:
/v2/pals/{pal_id}:
parameters:
- name: pal_id
in: path
required: true
description: The unique identifier of the PAL.
schema:
type: string
example: pcb7a34da5fe
get:
tags:
- PALs
summary: Get PAL
description: |
Returns a single PAL by its unique identifier.
operationId: getPal
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...
greeting:
type: string
description: >-
Opening line the PAL speaks at the start of every
conversation. Empty means silent unless `dynamic_greeting`
is true.
example: Hey there! What can I help you with today?
dynamic_greeting:
type: boolean
description: >-
When true, conversations that omit `dynamic_greeting`
generate an opener from this PAL if it has no `greeting`.
A conversation can still send `custom_greeting` or
`dynamic_greeting: true`.
example: false
default_face_id:
type: string
example: rc9cff32ceba
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
voice_id:
type: string
description: >-
A Tavus Voice to speak with, e.g. `v0a1b2c3d4e5f`.
Tavus picks the provider that is the best fit for
the language(s) of the conversation. Mutually
exclusive with `external_voice_id`, and cannot be
combined with your own TTS `api_key`. See
[Voices](/sections/conversational-video-interface/voices).
example: v0a1b2c3d4e5f
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_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-soniox` is
purpose-built for Indian languages.
`tavus-whisper` provides broad multilingual
coverage. `tavus-deepgram-medical` is optimized
for clinical vocabulary (English only).
`tavus-parakeet` and `tavus-advanced` are
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'
mcp:
type: object
description: >-
Connects registered MCP servers to the PAL. See [MCP
Connectors](/sections/conversational-video-interface/pal/mcp-connectors).
properties:
connectors:
type: array
description: >-
Connector IDs the PAL can delegate background
tasks to. A deleted connector simply drops out of
this list.
items:
type: string
example:
- c8-58ea0f6420b2
connector_tools:
type: object
description: >-
The tools each attached connector is scoped down
to, keyed by connector ID. A connector with no
entry allows every tool it exposes.
additionalProperties:
type: array
items:
type: string
example:
c8-58ea0f6420b2:
- search_messages
- list_channels
spoken_updates:
type: string
enum:
- none
- outcome
- all
description: >-
Which moments of a background task the PAL speaks.
`outcome` (the default) speaks the outcome once
the task finishes. `all` also voices the updates
the background agent chooses to give while it
works - a short title and a sentence, a few per
task - one at a time and only when there is room,
so a fast task voices less than it reports over
`conversation.agent_update`. `none` volunteers
nothing; the outcome still reaches the PAL's
context for when the user asks. Booleans are
rejected.
example: outcome
visual_updates:
type: string
enum:
- none
- outcome
- all
description: >-
Which moments of a background task the PAL shows
as a Magic Canvas text card, when it has that
skill on a video call. `none` (the default) shows
nothing. `outcome` shows the outcome as a card
once the task finishes. `all` also shows each
update the background agent gives as it comes,
replacing the card. Independent of
`spoken_updates`; inert without Magic Canvas.
example: outcome
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.
'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: []
components:
schemas:
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 calendar events with Google Meet, Zoom, or Microsoft Teams 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
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.