Skip to main content
POST
/
v2
/
personas
curl --request POST \
  --url https://tavusapi.com/v2/personas \
  --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..."
}
'
{
  "persona_id": "pcb7a34da5fe",
  "persona_name": "Life Coach",
  "created_at": "<string>"
}

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.

Authorizations

​
x-api-key
string
header
required

Body

application/json
​
persona_name
string

A name for the persona.

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 persona. Possible values: full, echo. full will provide the default end-to-end experience. echo will turn off most steps, and allow the replica to sync video with audio passed in through Echo events, which it will speak out.

Available options:
full,
echo
​
default_replica_id
string

The default replica_id associated with this persona if one exists. When creating a conversation, a persona_id with a default_replica_id associated can we used to create a conversation without specifying a replica_id.

Example:

"r90bbd427f71"

​
document_ids
string[]

Array of document IDs that the persona will have access to. These documents will be available to the persona 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 persona will have access to. Documents matching these tags will be available to the persona 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 persona. Objectives provide goal-oriented instructions that help guide conversations toward specific outcomes. Create objectives using the Create Objectives endpoint.

Example:

"o12345"

​
guardrails_id
string

The unique identifier of the guardrails to attach to this persona. Guardrails provide strict behavioral boundaries and guidelines that will be rigorously followed throughout conversations. Create guardrails using the Create Guardrails endpoint.

Example:

"g12345"

​
layers
object

Optional nested settings for each CVI pipeline layer (perception, STT, conversational flow, LLM, TTS). For an overview of what each layer controls, see Persona overview — CVI layers.

Response

​
persona_id
string

A unique identifier for the persona.

Example:

"pcb7a34da5fe"

​
persona_name
string

The name of the persona.

Example:

"Life Coach"

​
created_at
string

The date and time the persona was created.