Quick Start

Every new account is auto-seeded with two ready-to-use scenarios — Plus One and Requirement Gathering. So you can launch a live AI meeting in two calls: list your scenarios, then create a meeting from one.

Prerequisites

An API key — get one at waterr.ai/settings?tab=api-keys. Send it on every request:

Authorization: Bearer wai_<your_key>

Your workspace is inferred from the key — you never need to pass membership_id or org_id.

Step 1: Pick a starter scenario

GET /scenarios returns every scenario in your workspace, including the two that were auto-created for you.

curl https://api.waterr.ai/v1/scenarios \
  -H "Authorization: Bearer wai_<your_key>"

In the response, look for the default_kind field — it identifies the auto-seeded ones:

`default_kind`	What it does
`"plus_one"`	A personalized AI meeting (introduce yourself, get coached, etc.)
`"requirement_gathering"`	An AI that interviews you to scope a project
`null`	Scenarios you (or your teammates) created

Grab the id of whichever you want to try — say, the Plus One scenario.

{
  "data": [
    {
      "id": "9c4e8b21-...-...",
      "name": "Plus One",
      "default_kind": "plus_one",
      "type": "interview"
    },
    {
      "id": "a17fda30-...-...",
      "name": "Requirement Gathering",
      "default_kind": "requirement_gathering",
      "type": "interview"
    }
  ]
}

Step 2: Create a meeting

Pass the scenario_id from step 1 and a participant name. That’s it.

curl -X POST https://api.waterr.ai/v1/meetings \
  -H "Authorization: Bearer wai_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "person_name": "John Doe",
    "scenario_id": "SCENARIO_ID_FROM_STEP_1"
  }'

You get back a daily_meeting_url your participant can join right away:

{
  "success": true,
  "data": {
    "id": "meeting-uuid",
    "daily_meeting_url": "https://waterr-xx.daily.co/abc123",
    "room_token": "eyJhbGciOiJIUzI1NiIs...",
    "meeting_url": "https://waterr.ai/meeting/meeting-uuid",
    "status": "created"
  }
}

Open meeting_url in a browser — or embed the room with the Daily.co SDK.

Complete example (JavaScript)

const API = 'https://api.waterr.ai/v1';
const API_KEY = process.env.WATERR_API_KEY;  // wai_...
const headers = { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' };

// 1. Find the Plus One starter scenario
const { data: scenarios } = await fetch(`${API}/scenarios`, { headers })
  .then(r => r.json());

const plusOne = scenarios.find(s => s.default_kind === 'plus_one');

// 2. Create a meeting
const { data: meeting } = await fetch(`${API}/meetings`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    person_name: 'John Doe',
    scenario_id: plusOne.id,
  })
}).then(r => r.json());

console.log('Join here:', meeting.meeting_url);

After the meeting ends

Hit a single endpoint — GET /meetings/{id} — and you get summary, transcript, goal scores, strengths, and growth areas. See Post-Meeting Data.

Build your own scenario

When you’re ready to go past the starters, you have two options.

Option A: Generate one with AI

Describe what you want in plain language. The AI generates a persona, prompt, and goals for you.

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

The response gives you a scenario_id you can drop straight into Step 2. You can also attach a file (resume, JD, etc.) via -F '[email protected]'.

Option B: Build it by hand

Create a persona, then a scenario that references it. This is the full-control path.

# 1. Create a persona
curl -X POST https://api.waterr.ai/v1/personas \
  -H "Authorization: Bearer wai_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sarah Chen",
    "job_title": "VP of Engineering",
    "demeanor": "analytical",
    "background": "15 years in distributed systems. Known for deep technical interviews.",
    "gender": "female"
  }'

# 2. Create a scenario
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_ID",
    "prompt": "You are Sarah Chen...\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 dive into system design.",
    "visibility": "public"
  }'

See Personas and Scenarios for full field references.

Next steps

Post-Meeting Data

Fetch summary, transcript, and goal scores in one call.

Session Lifecycle

What happens between create and ended.

Prompting Guide

Write prompts that produce natural conversations.

Webhooks

Get notified when sessions complete.

Getting Started

Meetings

Personas

Scenarios

Embed Scenario

Post-Meeting Data

Goals

Avatars

Voices

Tools

Users

Guides

Integrations

Agent Skills

Prerequisites

Step 1: Pick a starter scenario

Step 2: Create a meeting

Complete example (JavaScript)

After the meeting ends

Build your own scenario

Option A: Generate one with AI

Option B: Build it by hand

Next steps

Post-Meeting Data

Session Lifecycle

Prompting Guide

Webhooks

​Prerequisites

​Step 1: Pick a starter scenario

​Step 2: Create a meeting

​Complete example (JavaScript)

​After the meeting ends

​Build your own scenario

​Option A: Generate one with AI

​Option B: Build it by hand

​Next steps

Post-Meeting Data

Session Lifecycle

Prompting Guide

Webhooks

Prerequisites

Step 1: Pick a starter scenario

Step 2: Create a meeting

Complete example (JavaScript)

After the meeting ends

Build your own scenario

Option A: Generate one with AI

Option B: Build it by hand

Next steps