> ## 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.
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)).
For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract.
Returns the **live** PAL by default. If the PAL has an active [PAL Builder](https://maker.tavus.io/dev) draft, add `?source=draft` to read the unpublished draft body without affecting live traffic. Draft views include a `publish_url` for [Publish PAL](/api-reference/pals/publish-pal). `layers.conferencing` is always the live value. See [Draft vs live PALs](/sections/conversational-video-interface/pal/draft-and-live).
## 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: >
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
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
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: []
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
````