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

# Personas

> Use and author project personas through the authenticated platform API.

Use [platform authentication](/api/authentication) for these endpoints. Browser
requests name `projectId`. A project API key already fixes the acting project.
Custom definitions are available only in their owning project. Predefined
definitions are shared; their model settings belong to the acting project.

| Method and path                         | Purpose                                                                             |
| --------------------------------------- | ----------------------------------------------------------------------------------- |
| `GET /v1/personas`                      | List available active definitions. Supports `projectId`, `search`, and `pageToken`. |
| `GET /v1/persona-form`                  | Read supported model pairs, recommended choices, and speed limits.                  |
| `GET /v1/personas/{personaId}`          | Read the current core and saved project settings.                                   |
| `POST /v1/personas/{personaId}/use`     | Save complete first-use settings, or return the existing association.               |
| `POST /v1/personas`                     | Create a custom definition, first core, and project settings together.              |
| `PATCH /v1/personas/{personaId}`        | Edit project settings or the current custom core.                                   |
| `POST /v1/personas/{personaId}/fork`    | Clone the current core and effective project settings.                              |
| `GET /v1/personas/{personaId}/versions` | Read core history, newest first.                                                    |
| `GET /v1/persona-versions/{versionId}`  | Read one immutable core.                                                            |
| `GET /v1/personas/{personaId}/usage`    | Read active tests that select the definition.                                       |
| `DELETE /v1/personas/{personaId}`       | Delete a custom persona from authoring; keep saved evidence.                        |

## Use and save model settings

`POST /v1/personas/{personaId}/use` accepts `projectId` and an optional complete
`models` object. Omit `models` to save the current core's declared defaults.
Repeated Use returns the existing settings. To change them, send `PATCH` with
`models`:

```json theme={null}
{
  "models": {
    "llm": { "provider": "openai", "model": "gpt-4o-mini" },
    "stt": { "provider": "openai", "model": "gpt-live-transcribe" },
    "tts": {
      "provider": "openai",
      "model": "gpt-4o-mini-tts",
      "voiceId": "alloy",
      "speed": 1
    }
  }
}
```

Every supplied `models` object must be complete. Unknown fields, unsupported
provider/model pairs, empty voice IDs, invalid types, and out-of-range speeds
receive `422`. Custom nonempty voice IDs are accepted without a provider lookup.
Model settings contain no credentials.

A current response includes `parameterContract` for the core and a separate
`settings` object with `id`, `models`, `createdAt`, and `updatedAt`. `settings`
is `null` before first use. A read does not create an association. Test selection
creates it with defaults when needed. Settings changes create no core version.

## Create and edit behavior

Creation requires `name`, `identityName`, `personality`, and `language`.
`description` and a complete `models` selection are optional. Omitted models
use the release's complete recommended selection. All three records commit
together.

For a core edit, first read the current `versionId`, then send it as
`expectedVersionId` with the changed behavior:

```json theme={null}
{
  "expectedVersionId": "prsv_01M0E4J0BBE1FVDVTZ1BSS5C97",
  "personality": "Asks one question and waits for a complete answer."
}
```

Use the ID returned by your current read. A stale base receives `409 version_conflict`; a behavior edit without a base receives `422`. The server
locks the current definition so concurrent edits cannot overwrite a newer
core. An unchanged core creates no version. Name and description remain live
metadata and need no core base.

Predefined cores cannot be edited by customers. The `/fork` endpoint takes an
optional `projectId` body and returns a new project-owned definition at version

1. It copies the current core and effective settings, without changing any test
   selection.

History responses carry identity name, personality, language, parameter
contract, version identity, and creation time. They never contain today's
project model values. History is read-only; there is no restoration operation.

Compatible shared core updates become current automatically. Current reads
then return that core with the same saved project settings. Incompatible
parameter changes are refused before publication. Clones receive no source
updates, and historical reads remain separate from today's settings.

Runs freeze the persona version and settings at creation. Queued simulations
and retries keep that selection after later settings or core updates. See
[Runs](/api/runs) and [persona concepts](/concepts/personas).