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

# Personas

> The read-only persona view of each agent, and which of its fields are fixed values.

A persona is the identity an agent speaks with: the name callers hear, and the call settings that go with it. Sempera keeps one persona per agent, so the same persona answers on every number and channel the agent has. The personas routes are a **read-only view** of each agent, in a fixed shape; there is nothing to create, edit or delete here. Change the name, voice or call settings on the agent's draft and publish ([Agents](https://docs.sempera.org/agents.md)).

| Route | Scope | Notes |
| - | - | - |
| `GET /v1/personas` | `agents:read` | One persona per active agent the credential can read |
| `GET /v1/personas/{persona_id}` | `agents:read` | One persona. `{persona_id}` is `per_` followed by the agent id |

`GET /v1/personas` takes `page` (from 1, default 1) and `limit` (1 to 100, default 20) and answers `{"data": [...], "errors": null}` with no total and no cursor; a page past the end is an empty list, and a `page` or `limit` outside its range is `400 validation_failed`. `GET /v1/personas/{persona_id}` answers the persona itself, unwrapped. An id that does not start with `per_` is `404 not_found`, and so is an agent the credential cannot read.

## The persona

A persona reads `id` (`per_<agent id>`), `name`, `description`, `image_url`, `created_at`, `updated_at`, `deleted_at`, `current_draft_version_id`, `current_production_version_id`, `current_draft_version`, `current_production_version`, `inbound_numbers` and `workspace_id`. `name` is the agent's persona name, or its name when it has none. Both version ids are the same id, and both versions carry the same content: the draft copy differs only in `version_type` (`draft`).

A version reads `id` (`perver_<agent id>_production`), `persona_id`, `version_type`, `version_number`, `created_at`, `updated_at`, `promoted_at`, `promoted_by`, `promoted_from_version_id`, `personality_prompt`, `orchestration_prompt`, `call_config`, `default_tools`, `entity_schemas`, `kb_ids`, `memory_enabled`, `pathway_conditions`, `skills` and `auth_config`. `call_config` reads `language`, `timezone`, `voice`, `record`, `wait_for_greeting`, `noise_cancellation`, `max_duration`, `transfer_phone_number`, `keywords`, `pronunciation_guide` and `background`.

What follows the agent, read from its current specs, call settings and version history:

| Field | Value |
| - | - |
| `id`, `name`, `workspace_id` | The agent's id, persona name and workspace |
| `description` | The agent's role, as its specs name it (for example `front-desk coordinator`); `null` when its specs cannot be read |
| `created_at`, `updated_at` | When the agent's first version and its newest version were built; `null` for an agent that has never been built |
| `version_number`, and a version's `created_at` and `updated_at` | The number of the version the agent runs now, and when that version was built; `null` for an agent that has never been built |
| `personality_prompt` | The persona name again, not the agent's instructions (read those from `GET /v1/agents/{id}`) |
| `call_config.language` | The agent's language code, as its specs store it; `null` when its specs cannot be read |
| `call_config.timezone` | The business's time zone, the one the agent answers hours questions in; `null` when its specs cannot be read |
| `call_config.voice` | The id of the voice the agent's calls use; `null` when no voice has been chosen or its specs cannot be read |
| `call_config.record`, `wait_for_greeting`, `noise_cancellation`, `background` | The agent's call settings; `null` for the first three when its specs cannot be read |
| `call_config.max_duration` | The longest a call may run, in seconds; `null` when the agent sets no limit of its own |
| `call_config.keywords`, `pronunciation_guide` | The agent's speech keywords and pronunciation entries |
| `memory_enabled` | Whether the agent remembers callers ([Caller memory schema](https://docs.sempera.org/memory-schema.md)); `null` when its specs cannot be read |

What is a fixed value, whatever the agent is configured with: `image_url`, `deleted_at` and `auth_config` are `null`; `promoted_at`, `promoted_by` and `promoted_from_version_id` are `null`, because Sempera records when a version was built, not when it began reaching callers; `orchestration_prompt` is `null`, because an agent runs one conversation and has no routing prompt; `transfer_phone_number` is `""`; and `inbound_numbers`, `default_tools`, `entity_schemas`, `kb_ids`, `pathway_conditions` and `skills` are empty lists. Read the agent's tools and knowledge from its detail read (`GET /v1/agents/{id}`) and its numbers from `GET /v1/phone-numbers?agent_id=` ([Sessions and calls](https://docs.sempera.org/sessions-and-calls.md)).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.