Scenarios

A scenario bundles a persona, 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.

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 — that’s the fastest way to a live AI session.

Get one scenario

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.

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"]
  }'

string

required

Shown in the dashboard and to participants.

string

required

interview, roleplay, upskill, or brainstorm.

string

required

UUID of the persona — see Personas.

string

The meeting script — flow, rules, guardrails. Markdown supported. See the Prompting Guide.

string

Short description shown to participants on the join page.

integer

Max session length in minutes. Default 30.

string

The AI’s opening line. If omitted, one is auto-generated from the prompt.

string

public (embeddable) or restricted (invite-only). Default public.

array

Array of Goal UUIDs for post-session scoring.

Generate a scenario with AI

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

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 '[email protected]'. The response gives you a scenario_id ready to use.

All scenario endpoints

Method	Endpoint	Use
`POST`	`/scenarios`	Create
`GET`	`/scenarios`	List (includes `default_kind`)
`PUT`	`/scenarios/{id}`	Update
`DELETE`	`/scenarios/{id}`	Delete
`GET`	`/scenarios/{id}/export`	Export as JSON
`GET`	`/scenarios/membership/{id}/meetings`	List meetings for a scenario

Getting Started

Meetings

Personas

Embed Scenario

Post-Meeting Data

Goals

Avatars

Voices

Tools

Users

Guides

Integrations

Agent Skills

Scenarios

Starter scenarios (auto-seeded)

Get one scenario

Create a scenario

Generate a scenario with AI

All scenario endpoints

​Starter scenarios (auto-seeded)

​Get one scenario

​Create a scenario

​Generate a scenario with AI

​All scenario endpoints

Starter scenarios (auto-seeded)

Get one scenario

Create a scenario

Generate a scenario with AI

All scenario endpoints