> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waterr.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Personas

> The AI character — name, role, demeanor, voice. Reusable across scenarios.

A persona is the AI's identity: name, job title, personality, background, voice. One persona can power many scenarios.

<Tip>
  Most integrations never touch this endpoint directly. The auto-seeded **Plus One** and **Requirement Gathering** scenarios already have personas attached, and [`POST /scenarios/create-with-gpt`](/api-reference/scenarios#generate-a-scenario-with-ai) generates a persona for you. Reach for these endpoints only when you're building fully custom scenarios by hand.
</Tip>

## Create a persona

```bash theme={null}
curl -X POST https://api.waterr.ai/v1/personas \
  -H "Authorization: Bearer wai_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sarah Chen",
    "job_title": "VP of Engineering",
    "demeanor": "analytical",
    "background": "15 years building distributed systems at scale. Led engineering at two startups through Series B.",
    "gender": "female",
    "voice_id": "VOICE_UUID"
  }'
```

<ParamField body="name" type="string" required>
  Full name of the AI persona.
</ParamField>

<ParamField body="job_title" type="string" required>
  Professional title (shown to participants).
</ParamField>

<ParamField body="demeanor" type="string">
  Personality style. Options: `friendly`, `analytical`, `empathetic`, `curious`, `enthusiastic`, `critical`, `casual`, `blunt`, `assertive`, `neutral`.
</ParamField>

<ParamField body="background" type="string">
  Detailed background — the more specific, the better the AI's follow-up questions.
</ParamField>

<ParamField body="gender" type="string">
  `male` or `female` — used for default voice and avatar selection.
</ParamField>

<ParamField body="voice_id" type="string">
  Voice UUID from [Voices](/api-reference/voices). If omitted, a default voice is assigned based on `gender`.
</ParamField>

<ParamField body="avatar_id" type="string">
  Avatar UUID from the [avatar catalog](/api-reference/avatars). The avatar's image URL and gender are applied to the persona automatically. You can also set or change it later with [`PUT /personas/{id}/avatar`](/api-reference/endpoint/put-personas-id-avatar).
</ParamField>

## List personas

```bash theme={null}
curl https://api.waterr.ai/v1/personas \
  -H "Authorization: Bearer wai_<your_key>"
```

## All persona endpoints

| Method   | Endpoint                                                                     | Use                                            |
| -------- | ---------------------------------------------------------------------------- | ---------------------------------------------- |
| `POST`   | [`/personas`](/api-reference/endpoint/post-personas)                         | Create                                         |
| `GET`    | [`/personas/{id}`](/api-reference/endpoint/get-personas-id)                  | Get one                                        |
| `GET`    | [`/personas`](/api-reference/endpoint/get-personas)                          | List                                           |
| `PUT`    | [`/personas/{id}`](/api-reference/endpoint/put-personas-id)                  | Update                                         |
| `DELETE` | [`/personas/{id}`](/api-reference/endpoint/delete-personas-id)               | Delete                                         |
| `PUT`    | [`/personas/{id}/avatar`](/api-reference/endpoint/put-personas-id-avatar)    | Set avatar ([catalog](/api-reference/avatars)) |
| `DELETE` | [`/personas/{id}/avatar`](/api-reference/endpoint/delete-personas-id-avatar) | Clear avatar                                   |