Skip to main content
POST
For AI agents, use https://docs.tavus.io/openapi.yaml for the full HTTP API contract.
default_face_id is required on POST /v2/pals (unlike the legacy POST /v2/personas path, where default_replica_id was optional). /v2/personas and persona_id / default_replica_id remain supported as aliases.

Authorizations

​
x-api-key
string
header
required

Body

application/json
​
pal_name
string

A name for the PAL.

Example:

"Life Coach"

​
system_prompt
string

This is the system prompt that will be used by the llm. Required unless using echo mode.

Example:

"As a Life Coach, you are a dedicated professional who specializes in..."

​
greeting
string

Optional opening line the PAL speaks at the start of every conversation. When empty, the PAL stays silent unless dynamic_greeting is true.

Example:

"Hey there! What can I help you with today?"

​
dynamic_greeting
boolean
default:false

When true, conversations that omit dynamic_greeting generate an opener if this PAL has no greeting. The line is generated from the PAL (system prompt and context). A conversation can still send custom_greeting or dynamic_greeting: true — the latter generates even over this written greeting. Default is false. Generated in the first tag of the conversation's properties.languages, otherwise this PAL's languages.

Example:

false

​
pipeline_mode
enum<string>

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.

Available options:
full,
echo
​
default_face_id
string

Required. The default face associated with this PAL. Also required when layers.conferencing is set - see Google Meet / Zoom / Teams.

Example:

"rc9cff32ceba"

​
languages
string[]

The languages every conversation with this PAL is expected to run in, from the spoken languages Tavus supports. Tavus restricts speech recognition to this set, holds the PAL's replies to it, and selects a matching version of the voice per language where one exists.

The fewer languages you supply, the more accurate the conversation. Only include languages the PAL is actually expected to speak.

A conversation may override this with its own languages on properties; the sets are not merged. A language the PAL's TTS engine and model cannot speak is rejected rather than ignored. See Language support.

Maximum array length: 42
Maximum string length: 16
Example:
​
document_ids
string[]

Array of document IDs that the PAL will have access to. The document_ids are returned in the response of the Get Document and the Create Document endpoints.

Example:
​
document_tags
string[]

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 endpoint. As soon as one document has the tag, you will be able to pass the tags in this parameter..

Example:
​
objectives_id
string

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 endpoint.

Example:

"o12345"

​
guardrail_ids
string[]

Array of guardrail IDs enforced during this PAL's conversations. Up to 50 per PAL. Guardrail IDs are returned by Create Guardrails and Get Guardrails.

Maximum array length: 50
Example:
​
guardrail_tags
string[]

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.

Maximum array length: 50
Example:
​
guardrails_id
string

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.

Example:

"g12345"

​
disclosure_type
enum<string>
default:auto

Controls the AI disclosure the PAL delivers at the start of a conversation. See 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 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."
Available options:
always,
auto,
off
Example:

"auto"

​
verbal_disclosure
string

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
string

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
object

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.

Response

​
pal_id
string

A unique identifier for the PAL.

Example:

"pcb7a34da5fe"

​
pal_name
string

The name of the PAL.

Example:

"Life Coach"

​
conferencing_email
string | null

The PAL's invitable meeting email on tavusinvite.com, derived from layers.conferencing.username. Present when conferencing is configured. See Google Meet / Zoom / Teams.

Example:

"acme-anna@tavusinvite.com"

​
created_at
string

The date and time the PAL was created.