Personas
Create and version simulated user profiles with background, role, and language for testing.
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.
Create a Persona
Create a new simulation persona with an initial version. In the initial_version body, background, user_models, nonsensitive_user_variables, and sensitive_user_variables are required, while preferred_language and timezone are optional.
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.",
"user_models": ["First-time user who needs step-by-step guidance"],
"nonsensitive_user_variables": {"region": "US-West"},
"sensitive_user_variables": {},
"preferred_language": "eng"
}
}'Response (201):
Create a simulation persona.
Permissions
Simulation:CreateSimulationPersonafor the persona to create.Simulation:ModifySimulationPersonafor the persona to create.
The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.
The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.
[]The name of the simulation persona.
The role of the simulation persona.
Succeeded.
The ID of the simulation persona that was created.
Invalid authorization credentials.
Missing required permissions.
The specified organization was not found.
A simulation persona with this name already exists.
Invalid request path parameter or request body failed validation.
The user has exceeded the rate limit of 100 requests per minute for this endpoint.
The service is going through temporary maintenance.
POST /v1/{organization}/simulation/persona/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 316
{
"name": "text",
"role": "text",
"tags": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"initial_version": {
"background": "text",
"preferred_language": "aaa",
"timezone": "Africa/Abidjan",
"user_models": [
"text"
],
"nonsensitive_user_variables": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"sensitive_user_variables": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
}{
"simulation_persona_id": "text"
}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 IDsis_deleted=true|false: filter by deletion statusrole=<role>(repeatable): filter by persona rolecreator=<org_id,user_id>(repeatable): filter by creatortag=key:value(repeatable;valuemay be*for any value, or empty for null)sort_by=+updated_at|-updated_at(repeatable; onlyupdated_atis a supported sort field - prefix+for ascending,-for descending; other fields fail validation with 422)limit(0-50, default 50),continuation_token(int, default 0)
Retrieve simulation personas that match the given filters.
Permissions
This endpoint may be impacted by the following permissions:
- Only simulation personas that the authenticated user has
Simulation:GetSimulationPersonapermission for will be retrieved.
The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.
The IDs of the simulation personas to retrieve.
[]The maximum number of simulation personas to return.
50The continuation token from the previous request used to retrieve the next page of simulation personas.
0Whether the simulation persona is deleted.
The roles of the simulation personas.
[]The creators of the simulation personas to retrieve. Each value must be of the format org_id,user_id.
[]The tags of the simulation personas to retrieve. Each value must be of the format key:value. If value is *, it means the value does not matter. If value is empty, it matches against when the value is None.
[]The fields to sort the sets by. Supported fields are updated_at. Specify a + before the field name to indicate ascending sorting and - for descending sorting. Multiple fields can be specified to break ties.
[]The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.
[]Succeeded.
Whether there are more simulation personas to fetch.
The continuation token to use to retrieve the next page of simulation personas.
Invalid authorization credentials.
Missing required permissions.
Specified organization is not found.
Invalid request path parameter or request query parameter failed validation.
The user has exceeded the rate limit of 50 requests per minute for this endpoint.
The service is going through temporary maintenance.
GET /v1/{organization}/simulation/persona/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*
{
"simulation_personas": [
{
"id": "text",
"name": "text",
"role": "text",
"tags": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"is_deleted": true,
"created_at": "2026-01-01T00:00:00.000Z",
"creator": {
"org_id": "text",
"user_id": "text"
},
"updated_at": "2026-01-01T00:00:00.000Z",
"updated_by": {
"org_id": "text",
"user_id": "text"
}
}
],
"has_more": true,
"continuation_token": null,
"filter_values": {
"creators": [
{
"org_id": "text",
"user_id": "text"
}
],
"tags": [
"text"
],
"roles": [
"text"
]
}
}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 textrole=<role>(repeatable): filter by rolecreator=<org_id,user_id>(repeatable): filter by creatortag=key:value(repeatable)
Search for simulation personas that match the given filters and contain the given query in its name and the background of its latest version. Only the top 50 results will be returned. The results will be sorted by the relevance of the search query.
Permissions
This endpoint may be impacted by the following permissions:
- Only simulation personas that the authenticated user has
Simulation:GetSimulationPersonapermission for will be retrieved.
The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.
The query to search for. Any simulation personas containing the terms in its name and the background of its latest version would be returned.
The roles of the simulation personas.
[]The creators of the simulation personas. Each value must be of the format org_id,user_id.
[]The tags of the simulation personas. Must be specified using the syntax key:value, which means to match all sets with the given key and value pair among its tags. If value is *, it means the value does not matter. If value is empty, it matches against when the value is None.
[]The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.
[]Succeeded.
Invalid authorization credentials.
Missing required permissions.
Specified organization is not found.
Invalid request path parameter or request query parameter failed validation.
The user has exceeded the rate limit of 50 requests per minute for this endpoint.
The service is going through temporary maintenance.
GET /v1/{organization}/simulation/persona/search?query=text HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*
{
"simulation_personas": [
{
"id": "text",
"name": "text",
"role": "text",
"tags": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"is_deleted": true,
"created_at": "2026-01-01T00:00:00.000Z",
"creator": {
"org_id": "text",
"user_id": "text"
},
"updated_at": "2026-01-01T00:00:00.000Z",
"updated_by": {
"org_id": "text",
"user_id": "text"
}
}
]
}Update a Persona
Update a simulation persona's metadata (tags). To change the persona's background or language, create a new version instead.
Update a simulation persona.
Permissions
This endpoint requires the following permissions:
Simulation:ModifySimulationPersonafor the persona to update.
The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.
The ID of the simulation persona to update
^[a-f0-9]{24}$The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.
[]Succeeded.
No content
Invalid authorization credentials.
Missing required permissions.
The specified organization or simulation persona does not exist.
Invalid request path parameter or request body failed validation.
The user has exceeded the rate limit of 100 requests per minute for this endpoint.
The service is going through temporary maintenance.
POST /v1/{organization}/simulation/persona/{simulation_persona_id}/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 43
{
"tags": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}No content
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.
Delete a simulation persona. This endpoint only soft-deletes the simulation persona so any existing references to it would still be valid. However, they cannot be used in any new simulations.
This endpoint will error if the simulation persona is used in any simulation unit tests.
Permissions
This endpoint requires the following permissions:
Simulation:DeleteSimulationPersonaon the simulation persona to delete.
The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.
The ID of the simulation persona to delete.
^[a-f0-9]{24}$The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.
[]Succeeded.
No content
The specified simulation persona is used in a simulation unit test.
Invalid authorization credentials.
Missing required permissions.
The specified organization or simulation persona does not exist.
Invalid request path parameter failed validation.
The user has exceeded the rate limit of 100 requests per minute for this endpoint.
The service is going through temporary maintenance.
DELETE /v1/{organization}/simulation/persona/{simulation_persona_id}/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*
No content
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.
Create a new simulation persona version
Create a new version of the simulation persona.
Permissions
This endpoint requires the following permissions:
Simulation:ModifySimulationPersonafor the simulation persona.
The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.
The ID of the simulation persona to create a version for.
^[a-f0-9]{24}$The version number of the new version. If specified, this endpoint throws an error if the next version in the database doesn't equal to the value of this parameter.
The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.
[]The background of the simulation persona.
The preferred language of the simulation persona in the ISO 639-3 format. If unspecified, the preferred language of the organization is used. If that is unspecified too, the language of the agent is used.
{}A specific type to indicate that a field is not set in the request.
The timezone of the simulation persona in the IANA tz database format. If unspecified, the organization's default timezone is used. If the organization's default timezone is not specified, UTC is used.
{}A specific type to indicate that a field is not set in the request.
A list of strings representing the user models associated with the simulation persona.
Succeeded.
The version number of the created simulation persona version.
The specified version number is not the expected next version to be created.
Invalid authorization credentials.
Missing required permissions.
The specified organization or simulation persona does not exist.
Invalid request path parameter, request query parameter, or request body failed validation.
The user has exceeded the rate limit of 100 requests per minute for this endpoint.
The service is going through temporary maintenance.
POST /v1/{organization}/simulation/persona/{simulation_persona_id}/version/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 226
{
"background": "text",
"preferred_language": "aaa",
"timezone": "Africa/Abidjan",
"user_models": [
"text"
],
"nonsensitive_user_variables": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"sensitive_user_variables": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}{
"version": 1
}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).
Get simulation persona versions
Retrieve versions of a simulation persona.
Permissions
This endpoint requires the following permissions:
Simulation:GetSimulationPersonafor the simulation persona.
The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.
The ID of the simulation persona to get versions for.
^[a-f0-9]{24}$The versions of the simulation persona to retrieve. One can specify an exact version to retrieve, which is either the version number or latest, which retrieves the latest version. Alternatively, one can specify a range of inclusive lower and upper bound for the version number separated by -, and every version within the range would be retrieved.
1The maximum number of simulation persona versions to return.
10The continuation token from the previous request used to retrieve the next page of simulation persona versions.
0The fields to sort the versions by. Supported fields are version. Specify a + before the field name to indicate ascending sorting and - for descending sorting. Multiple fields can be specified to break ties.
[]The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.
[]Succeeded.
Whether there are more simulation persona versions to fetch.
A token to supply to the next request to retreive the next page of simulation persona versions.
Invalid authorization credentials.
Missing required permissions.
The specified organization or simulation persona does not exist.
Invalid request path parameter or request query parameter failed validation.
The user has exceeded the rate limit of 50 requests per minute for this endpoint.
The service is going through temporary maintenance.
GET /v1/{organization}/simulation/persona/{simulation_persona_id}/version/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*
{
"simulation_persona_versions": [
{
"_id": "text",
"org_id": "text",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"simulation_persona_id": "text",
"version": 1,
"background": "text",
"preferred_language": "text",
"timezone": "text",
"user_models": [
"text"
],
"nonsensitive_user_variables": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"sensitive_user_variables": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"creator": {
"org_id": "text",
"user_id": "text"
}
}
],
"has_more": true,
"continuation_token": null
}Related
Last updated
Was this helpful?