# Scenarios

Manage simulation scenarios that define what a simulated user is trying to accomplish during a test conversation. Scenarios include an objective, detailed instructions for the simulated user, and the initial message type that determines how the conversation starts.

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

Scenarios are versioned independently. When you create a scenario, an initial version is created automatically. Create additional versions to iterate on objectives, instructions, and conversation start behavior. Unit tests always use the latest version of a referenced scenario.
{% endhint %}

## Create a Scenario

Create a new simulation scenario with an initial version.

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

```bash
curl --request POST \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/simulation/scenario/' \
     --header 'Authorization: Bearer <AUTH-TOKEN>' \
     --header 'Content-Type: application/json' \
     --data '{
       "name": "Account Setup Assistance",
       "tags": {"category": "onboarding", "priority": "high"},
       "initial_version": {
         "objective": "The user needs help setting up their account and configuring preferences.",
         "instructions": "Act confused about the setup process. Ask questions about each step. Express satisfaction when the agent explains things clearly.",
         "initial_message_type": "user-message",
         "conversation_starts_at": null
       }
     }'
```

{% endtab %}
{% endtabs %}

**Response (201):**

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

### Initial Message Types

The `initial_message_type` field controls how the simulated conversation begins:

| Value              | Behavior                                         |
| ------------------ | ------------------------------------------------ |
| `"user-message"`   | The simulated persona sends the first message    |
| `"external-event"` | An external event triggers the conversation      |
| `"skip"`           | The agent speaks first (no initial user message) |

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

## List Scenarios

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

Common filters:

* `id=<id>` (repeatable): filter by specific scenario IDs
* `is_deleted=true|false`: filter by deletion status
* `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-200, 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/scenario/?limit=10&tag=category:onboarding' \
     --header 'Authorization: Bearer <AUTH-TOKEN>' \
     --header 'Accept: application/json'
```

{% endtab %}
{% endtabs %}

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

## Search Scenarios

Search for simulation scenarios by text query. Matches against the scenario name. Returns the top 50 results sorted by relevance.

* `query` (required): the search text
* `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/scenario/search?query=account%20setup' \
     --header 'Authorization: Bearer <AUTH-TOKEN>' \
     --header 'Accept: application/json'
```

{% endtab %}
{% endtabs %}

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

## Update a Scenario

Update a simulation scenario's metadata (tags). To change the scenario's objective, instructions, or initial message type, create a new version instead.

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

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

{% endtab %}
{% endtabs %}

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

## Delete a Scenario

Soft-delete a simulation scenario. Existing references remain valid but the scenario cannot be used in new unit tests. This endpoint returns an error if the scenario 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/scenario/<SCENARIO-ID>/' \
     --header 'Authorization: Bearer <AUTH-TOKEN>'
```

{% endtab %}
{% endtabs %}

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

## Create a Scenario Version

Create a new version of a simulation scenario. Use this to update the scenario's objective, instructions, initial message type, or conversation start time.

The optional `version` query parameter lets you specify the expected version number for optimistic concurrency control.

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

```bash
curl --request POST \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/simulation/scenario/<SCENARIO-ID>/version/' \
     --header 'Authorization: Bearer <AUTH-TOKEN>' \
     --header 'Content-Type: application/json' \
     --data '{
       "objective": "The user needs help setting up their account, configuring preferences, and enabling notifications.",
       "instructions": "Act confused about the setup process. Ask questions about each step. If the agent skips a step, ask about it. Express satisfaction when the agent explains things clearly.",
       "initial_message_type": "user-message",
       "conversation_starts_at": null
     }'
```

{% endtab %}
{% endtabs %}

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

## Get Scenario Versions

Retrieve versions of a simulation scenario. 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/scenario/<SCENARIO-ID>/version/?version=latest' \
     --header 'Authorization: Bearer <AUTH-TOKEN>' \
     --header 'Accept: application/json'

# Get all versions from 1 to latest
curl --request GET \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/simulation/scenario/<SCENARIO-ID>/version/?version=1-latest' \
     --header 'Authorization: Bearer <AUTH-TOKEN>' \
     --header 'Accept: application/json'
```

{% endtab %}
{% endtabs %}

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/simulation/scenario/{simulation\_scenario\_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 Personas](https://docs.amigo.ai/developer-guide/classic-api/core-api/simulations/simulation-personas)
* [Simulation Unit Tests](https://docs.amigo.ai/developer-guide/classic-api/core-api/simulations/simulation-unit-tests)