Skip to main content
POST
/
v2
/
pals
curl --request POST \
  --url https://tavusapi.com/v2/pals \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "pipeline_mode": "full",
  "system_prompt": "As a Life Coach, you are a dedicated professional who specializes in...",
  "default_face_id": "r90bbd427f71"
}
'
{
  "pal_id": "pcb7a34da5fe",
  "pal_name": "Life Coach",
  "conferencing_email": "acme-anna@tavusinvite.com",
  "created_at": "<string>"
}
For AI agents, use https://docs.tavus.io/openapi.yaml for the full HTTP API contract.

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

Example:

"r90bbd427f71"

​
document_ids
string[]

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 and the Create Document endpoints.

Example:
["d1234567890", "d2468101214"]
​
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:
["product_info", "company_policies"]
​
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:
["g1234567890ab", "g0987654321cd"]
​
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:
["compliance", "healthcare"]
​
guardrails_id
string

Legacy. The unique identifier of a guardrail set to attach to this PAL. New integrations should use guardrail_ids / guardrail_tags instead - see Legacy guardrail sets.

Example:

"g12345"

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

Example:

"acme-anna@tavusinvite.com"

​
created_at
string

The date and time the PAL was created.