# Personas

Manage simulated user profiles used in simulation testing. Personas define the characteristics of a simulated user (their background, role, and preferred language), so you can test how your agent interacts with different user archetypes.

{% hint style="info" %}
**Versioning**

Personas are versioned. When you create a persona, an initial version is created automatically. You can then create additional versions to iterate on the persona's background and language without changing its identity (name, role, tags). Unit tests always use the latest version of a referenced persona.
{% endhint %}

## Create a Persona

Create a new simulation persona with an initial version.

{% tabs %}
{% tab title="cURL" %}

```bash
curl --request POST \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/simulation/persona/' \
     --header 'Authorization: Bearer <AUTH-TOKEN>' \
     --header 'Content-Type: application/json' \
     --data '{
       "name": "Confused New User",
       "role": "patient",
       "tags": {"category": "onboarding", "difficulty": "low"},
       "initial_version": {
         "background": "A 35-year-old first-time user who is unfamiliar with the platform and tends to ask basic questions.",
         "preferred_language": "eng"
       }
     }'
```

{% endtab %}
{% endtabs %}

**Response (201):**

```json
{
  "simulation_persona_id": "6618791275130b73714e8d1c"
}
```

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/simulation/persona/" method="post" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

## List Personas

Retrieve simulation personas that match the given filters. Only personas the authenticated user has `Simulation:GetSimulationPersona` permission for are returned.

Common filters:

* `id=<id>` (repeatable): filter by specific persona IDs
* `is_deleted=true|false`: filter by deletion status
* `role=<role>` (repeatable): filter by persona role
* `creator=<org_id,user_id>` (repeatable): filter by creator
* `tag=key:value` (repeatable; `value` may be `*` for any value, or empty for null)
* `sort_by=+created_at|-created_at|+name|-name` (repeatable)
* `limit` (0-50, default 50), `continuation_token` (int, default 0)

{% tabs %}
{% tab title="cURL" %}

```bash
curl --request GET \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/simulation/persona/?limit=10&role=patient' \
     --header 'Authorization: Bearer <AUTH-TOKEN>' \
     --header 'Accept: application/json'
```

{% endtab %}
{% endtabs %}

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/simulation/persona/" method="get" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

## Search Personas

Search for simulation personas by text query. Matches against the persona name and the background of its latest version. Returns the top 50 results sorted by relevance.

* `query` (required): the search text
* `role=<role>` (repeatable): filter by role
* `creator=<org_id,user_id>` (repeatable): filter by creator
* `tag=key:value` (repeatable)

{% tabs %}
{% tab title="cURL" %}

```bash
curl --request GET \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/simulation/persona/search?query=confused%20user' \
     --header 'Authorization: Bearer <AUTH-TOKEN>' \
     --header 'Accept: application/json'
```

{% endtab %}
{% endtabs %}

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/simulation/persona/search" method="get" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

## Update a Persona

Update a simulation persona's metadata (tags). To change the persona's background or language, create a new version instead.

{% tabs %}
{% tab title="cURL" %}

```bash
curl --request POST \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/simulation/persona/<PERSONA-ID>/' \
     --header 'Authorization: Bearer <AUTH-TOKEN>' \
     --header 'Content-Type: application/json' \
     --data '{
       "tags": {"category": "onboarding", "difficulty": "medium"}
     }'
```

{% endtab %}
{% endtabs %}

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/simulation/persona/{simulation\_persona\_id}/" method="post" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

## Delete a Persona

Soft-delete a simulation persona. Existing references remain valid but the persona cannot be used in new unit tests. This endpoint returns an error if the persona is currently used in any simulation unit test.

{% tabs %}
{% tab title="cURL" %}

```bash
curl --request DELETE \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/simulation/persona/<PERSONA-ID>/' \
     --header 'Authorization: Bearer <AUTH-TOKEN>'
```

{% endtab %}
{% endtabs %}

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/simulation/persona/{simulation\_persona\_id}/" method="delete" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

## Create a Persona Version

Create a new version of a simulation persona. Use this to update the persona's background or preferred language while preserving version history.

The optional `version` query parameter lets you specify the expected version number. If the next version in the database does not match this value, the request fails. This is useful for optimistic concurrency control.

{% tabs %}
{% tab title="cURL" %}

```bash
curl --request POST \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/simulation/persona/<PERSONA-ID>/version/' \
     --header 'Authorization: Bearer <AUTH-TOKEN>' \
     --header 'Content-Type: application/json' \
     --data '{
       "background": "A 35-year-old first-time user who is unfamiliar with technology in general and needs extra hand-holding through each step.",
       "preferred_language": "eng"
     }'
```

{% endtab %}
{% endtabs %}

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/simulation/persona/{simulation\_persona\_id}/version/" method="post" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

## Get Persona Versions

Retrieve versions of a simulation persona. You can request a specific version number, `latest`, or a range (for example, `2-5` or `1-latest`).

{% tabs %}
{% tab title="cURL" %}

```bash
# Get the latest version
curl --request GET \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/simulation/persona/<PERSONA-ID>/version/?version=latest' \
     --header 'Authorization: Bearer <AUTH-TOKEN>' \
     --header 'Accept: application/json'

# Get versions 1 through 5
curl --request GET \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/simulation/persona/<PERSONA-ID>/version/?version=1-5' \
     --header 'Authorization: Bearer <AUTH-TOKEN>' \
     --header 'Accept: application/json'
```

{% endtab %}
{% endtabs %}

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/simulation/persona/{simulation\_persona\_id}/version/" method="get" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

## Related

* [Simulation Overview](https://docs.amigo.ai/developer-guide/classic-api/core-api/simulations)
* [Simulation Scenarios](https://docs.amigo.ai/developer-guide/classic-api/core-api/simulations/simulation-scenarios)
* [Simulation Unit Tests](https://docs.amigo.ai/developer-guide/classic-api/core-api/simulations/simulation-unit-tests)