> ## 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
> This endpoint returns a single PAL by its unique identifier.
For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract.
## 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: Pronunciation Dictionaries
- name: Replacements
- name: Transcriptions
- name: Documents
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: |
This endpoint returns a single PAL by its unique identifier.
operationId: getPal
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
data:
type: array
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
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.
enum:
- cartesia
- elevenlabs
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
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.
'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 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
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
````