Skip to main content

​
Overview

Scenarios define conversation contexts that combine a persona with specific goals, prompts, and settings. Scenarios can be public (for embedding), restricted, or private.

​
Get All Scenarios

Retrieve all scenarios for the authenticated user.
​
none
curl -X GET https://api.waterrai.com/scenarios \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "status": "success",
  "data": [
    {
      "id": 456,
      "name": "Product Manager Interview Practice",
      "description": "Practice interview scenarios",
      "type": "interview",
      "persona_id": 123,
      "visibility": "public",
      "scenario_link": "pm-interview-practice",
      "created_at": "2024-01-15T10:35:00Z"
    }
  ]
}

​
Get Scenario by ID

Retrieve a specific scenario by its ID. Returns full scenario data including persona, goals, and meeting controls.
​
id
integer
required
The scenario ID
curl -X GET https://api.waterrai.com/scenarios/456 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "status": "success",
  "data": {
    "id": 456,
    "name": "Product Manager Interview Practice",
    "description": "Practice interview scenarios for product management roles",
    "type": "interview",
    "persona_id": 123,
    "prompt": "You are conducting a mock interview...",
    "visibility": "public",
    "scenario_link": "pm-interview-practice",
    "Persona": {
      "id": 123,
      "name": "Sarah Chen",
      "job_title": "Senior Product Manager"
    },
    "DirectGoals": [],
    "MeetingControls": {
      "allow_recording": true,
      "allow_transcription": true,
      "allow_chat": true
    },
    "created_at": "2024-01-15T10:35:00Z"
  }
}

​
Get Scenario for Embed

Retrieve a public scenario optimized for embedding. This endpoint returns embed data and does not require authentication for public scenarios.
​
id
integer
required
The scenario ID (must be a public scenario)
curl -X GET https://api.waterrai.com/scenarios/embed/456

{
  "id": 456,
  "name": "Product Manager Interview Practice",
  "description": "Practice interview scenarios",
  "type": "interview",
  "persona_id": 123,
  "Persona": {
    "id": 123,
    "name": "Sarah Chen",
    "job_title": "Senior Product Manager",
    "avatar": "https://example.com/avatar.jpg",
    "voice_id": 1,
    "Voice": {
      "id": 1,
      "name": "Sarah Voice",
      "provider": "elevenlabs",
      "partner_voice_id": "voice123"
    }
  },
  "Goals": []
}
This endpoint only works for scenarios with visibility: "public". For private or restricted scenarios, use the regular GET endpoint with authentication.

​
Create Scenario

Create a new scenario with a persona and optional goals.
Organization ID: The org_id is automatically determined from your authenticated account (via API secret or JWT token), so you don’t need to provide it in the request. If you do provide it, it will be used; otherwise, your account’s organization will be used automatically.
​
name
string
required
Name of the scenario
​
type
string
required
Scenario type. Options: interview, roleplay, upskill, brainstorm
​
persona_id
integer
required
ID of the associated persona
​
description
string
Description of the scenario
​
prompt
string
Prompt for the scenario (markdown supported)
​
user_prompt
string
Original user prompt entered on Create page
​
data_model_id
integer
ID of the associated data model (optional)
​
visibility
string
Visibility setting. Options: public, restricted, private (default: private)
​
goals
array
Array of goal IDs to associate with the scenario
curl -X POST https://api.waterrai.com/scenarios \
  -H "Authorization: Bearer YOUR_API_SECRET_OR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Manager Interview Practice",
    "description": "Practice interview scenarios for product management roles",
    "type": "interview",
    "persona_id": 123,
    "prompt": "You are conducting a mock interview for a product manager position. Ask about product strategy, user research, and prioritization frameworks.",
    "visibility": "public"
  }'

{
  "status": "success",
  "data": {
    "id": 456,
    "name": "Product Manager Interview Practice",
    "description": "Practice interview scenarios",
    "type": "interview",
    "persona_id": 123,
    "scenario_link": "pm-interview-practice",
    "visibility": "public",
    "created_at": "2024-01-15T10:35:00Z"
  }
}

​
Update Scenario

Update an existing scenario.
​
name
string
Name of the scenario
​
description
string
Description of the scenario
​
prompt
string
Prompt for the scenario
​
type
string
Scenario type
​
persona_id
integer
ID of the associated persona
​
visibility
string
Visibility setting
​
goals
array
Array of goal IDs
​
id
integer
required
The scenario ID to update
curl -X PUT https://api.waterrai.com/scenarios/456 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Advanced Product Manager Interview",
    "description": "Advanced interview scenarios",
    "visibility": "public"
  }'

{
  "status": "success",
  "data": {
    "id": 456,
    "name": "Advanced Product Manager Interview",
    "description": "Advanced interview scenarios",
    "updated_at": "2024-01-15T11:00:00Z"
  }
}

​
Delete Scenario

Delete a scenario by ID.
​
id
integer
required
The scenario ID to delete
curl -X DELETE https://api.waterrai.com/scenarios/456 \
  -H "Authorization: Bearer YOUR_API_TOKEN"
Embedding Scenarios: To embed a scenario in your application, first ensure it has visibility: "public", then use the /scenarios/embed/:id endpoint to get the embed data. This endpoint returns optimized data for embedding without requiring authentication.