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

# Scenarios

> Scenarios define what an AI meeting is about — a persona, a script, and goals.

A scenario bundles a [persona](/api-reference/personas), a meeting script (prompt), evaluation goals, and session settings (duration, recording, vision, etc.). You point a meeting at a `scenario_id` to start a session.

## Starter scenarios (auto-seeded)

Every new account already has **two scenarios** ready to use. List them and you'll see them in the response.

```bash theme={null}
curl https://api.waterr.ai/v1/scenarios \
  -H "Authorization: Bearer wai_<your_key>"
```

Look for the `default_kind` field:

| `default_kind`            | Scenario                                         |
| ------------------------- | ------------------------------------------------ |
| `"plus_one"`              | A personalized AI meeting (intro/coaching).      |
| `"requirement_gathering"` | An AI that scopes a project by interviewing you. |
| `null`                    | Scenarios you or your teammates created.         |

Grab the `id` and pass it to [`POST /meetings`](/api-reference/meetings) — that's the fastest way to a live AI session.

## Get one scenario

```bash theme={null}
curl https://api.waterr.ai/v1/scenarios/{id} \
  -H "Authorization: Bearer wai_<your_key>"
```

The response includes the full prompt, nested `Persona`, attached goals, meeting controls, and session options.

## Create a scenario

When you need a custom flow.

```bash theme={null}
curl -X POST https://api.waterr.ai/v1/scenarios \
  -H "Authorization: Bearer wai_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "System Design Interview",
    "description": "Practice system design for senior backend roles",
    "type": "interview",
    "persona_id": "PERSONA_UUID",
    "prompt": "You are Sarah Chen, VP of Engineering...\n\n## Flow\n1. Intro (2 min)\n2. System design problem (15 min)\n3. Their questions (3 min)\n\n## Rules\n- Push back on vague answers",
    "call_duration": 25,
    "welcome_message": "Hi! I'\''m Sarah. Let'\''s talk system design.",
    "visibility": "public",
    "goals": ["GOAL_UUID_1", "GOAL_UUID_2"]
  }'
```

<ParamField body="name" type="string" required>
  Shown in the dashboard and to participants.
</ParamField>

<ParamField body="type" type="string" required>
  `interview`, `roleplay`, `upskill`, or `brainstorm`.
</ParamField>

<ParamField body="persona_id" type="string" required>
  UUID of the persona — see [Personas](/api-reference/personas).
</ParamField>

<ParamField body="prompt" type="string">
  The meeting script — flow, rules, guardrails. Markdown supported. See the [Prompting Guide](/api-reference/prompting-guide).
</ParamField>

<ParamField body="description" type="string">
  Short description shown to participants on the join page.
</ParamField>

<ParamField body="call_duration" type="integer">
  Max session length in minutes. Default `30`.
</ParamField>

<ParamField body="welcome_message" type="string">
  The AI's opening line. If omitted, one is auto-generated from the prompt.
</ParamField>

<ParamField body="visibility" type="string">
  `public` (embeddable) or `restricted` (invite-only). Default `public`.
</ParamField>

<ParamField body="goals" type="array">
  Array of [Goal](/api-reference/goals) UUIDs for post-session scoring.
</ParamField>

## Generate a scenario with AI

Skip building manually. Describe what you want and the AI generates a persona, prompt, and goals.

```bash theme={null}
curl -X POST https://api.waterr.ai/v1/scenarios/create-with-gpt \
  -H "Authorization: Bearer wai_<your_key>" \
  -F 'userInput=Technical interview for senior backend engineer, system design focus, 25 minutes' \
  -F 'duration=25'
```

Attach a resume or JD with `-F 'file=@resume.pdf'`. The response gives you a `scenario_id` ready to use.

## All scenario endpoints

| Method   | Endpoint                                                                                                        | Use                            |
| -------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| `POST`   | [`/scenarios`](/api-reference/endpoint/post-scenarios)                                                          | Create                         |
| `GET`    | [`/scenarios`](/api-reference/endpoint/get-scenarios)                                                           | List (includes `default_kind`) |
| `PUT`    | [`/scenarios/{id}`](/api-reference/endpoint/put-scenarios-id)                                                   | Update                         |
| `DELETE` | [`/scenarios/{id}`](/api-reference/endpoint/delete-scenarios-id)                                                | Delete                         |
| `GET`    | [`/scenarios/{id}/export`](/api-reference/endpoint/get-scenarios-id-export)                                     | Export as JSON                 |
| `GET`    | [`/scenarios/membership/{id}/meetings`](/api-reference/endpoint/get-scenarios-membership-membershipid-meetings) | List meetings for a scenario   |