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>"
}
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
​
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"

​
guardrail_ids
string[]

Array of guardrail IDs enforced during this persona's conversations. Up to 50 per persona. 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 persona dynamically. Up to 50 tags per persona, and a persona 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 persona. 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). 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.