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.

Tools, guardrails and skills

What a scenario is allowed to do is set with three fields on the scenario, each the complete set of ids in the order the agent should see them:

curl -X PUT https://api.waterr.ai/v1/scenarios/{id} \
  -H "Authorization: Bearer wai_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_ids": ["fn-uuid"],
    "guardrail_ids": ["guardrail-uuid"],
    "skill_ids": ["skill-uuid"]
  }'

Field	What it attaches
`tool_ids`	Tools the agent can call
`guardrail_ids`	Guardrails, in prompt order
`skill_ids`	Meeting skills, in trigger order

Leave a field out to leave that set alone; send [] to detach everything of that kind. The scenario read returns the same three fields. Ids that are not your workspace’s answer 400 with the offending ids in errors. A whole skill package attaches with one call of its own.

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

Tools

Extend Meetings

Embed Scenario

More APIs

Guides

Integrations

Agent Skills

Scenarios

Starter scenarios (auto-seeded)

Get one scenario

Create a scenario

Generate a scenario with AI

Tools, guardrails and skills

All scenario endpoints

​Starter scenarios (auto-seeded)

​Get one scenario

​Create a scenario

​Generate a scenario with AI

​Tools, guardrails and skills

​All scenario endpoints

Starter scenarios (auto-seeded)

Get one scenario

Create a scenario

Generate a scenario with AI

Tools, guardrails and skills

All scenario endpoints