WaterrAI API API

openapi: 3.0.0
info:
  title: WaterrAI API
  version: 1.0.0
  description: >-
    REST API for the WaterrAI meeting platform — create scenarios, spin up AI-driven meetings, fetch transcripts and
    analyses.
  contact:
    name: Support
    email: harshit@waterr.ai
servers:
  - url: https://api.waterr.ai/v1
    description: Production
components:
  securitySchemes:
    apiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: wai_...
      description: 'API key from waterr.ai/settings?tab=api-keys. Send as `Authorization: Bearer wai_<your_key>`.'
  schemas:
    GoalResult:
      type: object
      properties:
        id:
          type: string
        analysis_id:
          type: string
        goal_id:
          type: string
        score:
          type: number
        feedback:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Analysis:
      type: object
      properties:
        id:
          type: string
        meeting_id:
          type: string
        average_score:
          type: number
        total_score:
          type: number
        summary:
          type: string
        strengths:
          type: string
        growth_areas:
          type: string
        repetitions:
          type: string
        filler_words:
          type: string
        weak_words:
          type: string
        sentence_starters:
          type: string
        goal_results:
          type: array
          items:
            $ref: '#/components/schemas/GoalResult'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    User:
      type: object
      properties:
        id:
          type: string
        google_user_id:
          type: string
        email:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        role:
          type: string
          enum:
            - user
            - admin
            - manager
    AuthResponse:
      type: object
      properties:
        status:
          type: string
        message:
          type: string
        data:
          type: object
          properties:
            token:
              type: string
            user:
              $ref: '#/components/schemas/User'
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
        message:
          type: string
        details:
          type: string
    MeetingControls:
      type: object
      properties:
        id:
          type: string
        scenario_id:
          type: string
        allow_recording:
          type: boolean
        allow_transcription:
          type: boolean
        allow_chat:
          type: boolean
        allow_screen_share:
          type: boolean
        allow_participant_video:
          type: boolean
        allow_participant_audio:
          type: boolean
        allow_live_vision:
          type: boolean
        allow_web_search:
          type: boolean
        use_gpt_vision:
          type: boolean
        max_participants:
          type: integer
        waiting_room_enabled:
          type: boolean
        auto_admit:
          type: boolean
        end_call_enabled:
          type: boolean
        controls:
          type: object
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Scenario:
      type: object
      properties:
        tool_ids:
          type: array
          items: { type: string, format: uuid }
          description: Ids of the tools attached to this scenario, in order (single read).
        guardrail_ids:
          type: array
          items: { type: string, format: uuid }
        skill_ids:
          type: array
          items: { type: string, format: uuid }
        id:
          type: string
        name:
          type: string
        description:
          type: string
        prompt:
          type: string
        user_prompt:
          type: string
        type:
          type: string
          enum:
            - interview
            - roleplay
            - upskill
            - brainstorm
        persona_id:
          type: string
        org_id:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Voice:
      type: object
      properties:
        id:
          type: string
        partner_voice_id:
          type: string
        name:
          type: string
        provider:
          type: string
        user_basic_info_id:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Avatar:
      type: object
      description: >-
        A catalog avatar — the visual identity a persona presents in prejoin
        cards and meetings. Global curated avatars have `owner_membership_id: null`;
        avatars you generate or upload are owned by your account and visible
        only to you.
      properties:
        id:
          type: string
          format: uuid
        url:
          type: string
          description: Public image URL. Assigning the avatar copies this into the persona's `avatar` field.
          example: 'https://waterr-ai-avatars.s3.us-east-1.amazonaws.com/F-1.jpg'
        category:
          type: string
          description: 'Business-role category, e.g. `recruiter`, `sales`, `coach`, `executive`, `casual`, `illustrated`, `professional`.'
          example: professional
        gender:
          type: string
          enum:
            - male
            - female
            - neutral
          nullable: true
          description: 'Drives voice pairing. `neutral` for illustrated/abstract avatars.'
        default_voice_id:
          type: string
          format: uuid
          nullable: true
          description: 'Suggested voice for this avatar. Applied when you set `sync_voice: true`.'
        source:
          type: string
          enum:
            - curated
            - generated
            - uploaded
          description: '`curated` — global catalog. `generated`/`uploaded` — account-owned (generation API coming soon).'
        orientation:
          type: string
          enum:
            - portrait
            - landscape
          description: >-
            The avatar's shape, which also decides the meeting layout.
            `portrait` (3:4) renders a tile beside the participant's camera.
            `landscape` (16:9, framed like a video call) fills the meeting
            stage with the participant's camera floating in a corner. Measured
            from the image at ingest — never taken from the request body.
          example: landscape
        environment:
          type: string
          nullable: true
          description: >-
            Room the still was shot in, e.g. `hospital-clinic`,
            `conference-room`, `office-cityview`, `executive-office`,
            `startup-office`, `broadcast-studio`, `home-study`. `null` for
            the legacy studio portraits.
          example: hospital-ward
        identity_key:
          type: string
          nullable: true
          description: >-
            Groups every shape and room of the same face, e.g. `F-3`. Filter on
            it to offer the same person in another setting. `null` for avatars
            that are their own identity.
          example: F-3
        video_url:
          type: string
          nullable: true
          description: >-
            Seamless idle loop matching this exact still. When present the
            meeting plays it under the agent until a live renderer takes over,
            falling back to the still if it cannot load.
        owner_membership_id:
          type: string
          format: uuid
          nullable: true
          description: '`null` for the global curated catalog; your membership ID for avatars you own.'
        tags:
          type: object
        width:
          type: integer
          nullable: true
        height:
          type: integer
          nullable: true
        Voice:
          $ref: '#/components/schemas/Voice'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    CustomFunction:
      type: object
      description: A tool the LLM can call mid-meeting. Defined once on your account, attached to one or more scenarios.
      required:
        - id
        - name
        - description
        - parameters_schema
        - execution_mode
        - has_webhook_secret
        - timeout_ms
        - tool_spec
      properties:
        id:
          type: string
          format: uuid
          description: Tool UUID. Generated by the server.
          example: 4f8a6c50-9d3b-4c1f-9c0a-7a3b6e2d1f10
        membership_id:
          type: string
          format: uuid
          description: Account that owns the tool.
          example: a1b2c3d4-e5f6-7890-abcd-ef0123456789
        name:
          type: string
          maxLength: 64
          pattern: '^[a-zA-Z0-9_-]{1,64}$'
          description: 'Function name the LLM calls. Letters, digits, `_`, `-`. Max 64. Unique per account.'
          example: lookup_account
        description:
          type: string
          description: One-sentence prompt that tells the LLM when to call this tool. Shown verbatim to the model.
          example: 'Fetch the participant''s CRM record so you can reference their plan, MRR, and last contact date.'
        parameters_schema:
          type: object
          description: 'JSON Schema for the arguments. Top-level type must be `"object"`.'
          default: { type: 'object', properties: {}, required: [] }
          example:
            type: object
            properties:
              account_id:
                type: string
                description: The participant's account ID (e.g. cus_XXXX).
            required:
              - account_id
        execution_mode:
          type: string
          enum:
            - webhook
            - client
          default: webhook
          description: '`webhook` — we POST the call to `webhook_url` and use the response. `client` — your frontend handles the call.'
          example: webhook
        webhook_url:
          type: string
          format: uri
          nullable: true
          description: 'Where we POST the tool call. Required when `execution_mode = "webhook"`.'
          example: 'https://your-app.com/waterr/tools/lookup_account'
        has_webhook_secret:
          type: boolean
          description: 'True if a signing secret is set. The secret itself is returned once — on create (when we mint it) and on rotate — and never again.'
          example: true
        webhook_secret_rotated_at:
          type: string
          format: date-time
          nullable: true
          description: 'When the signing secret was last rotated. `null` if never.'
          example: null
        timeout_ms:
          type: integer
          minimum: 1000
          maximum: 30000
          default: 10000
          description: 'Max wait for your webhook to respond, in ms. Range 1000–30000.'
          example: 8000
        on_call:
          type: string
          enum:
            - generate_filler
            - static_filler
            - silent
            - passthrough
          default: silent
          description: 'What the persona does WHILE the tool runs. `silent` (default) — go quiet. `static_filler` — speak the exact `static_filler` phrase. `generate_filler` — pick from a generic pool ("let me check on that"). `passthrough` — silent + skip LLM follow-up on the result.'
          example: static_filler
        static_filler:
          type: string
          nullable: true
          description: 'Phrase the persona speaks while the tool runs. Required when `on_call = "static_filler"`. Must be null otherwise.'
          example: 'Sure, let me grab that for you.'
        on_resolve:
          type: string
          enum:
            - generate_response
            - response_in_result
            - add_to_context
            - fire_and_forget
          default: generate_response
          description: 'What to do with the tool result AFTER it returns. `generate_response` (default) — feed to LLM, persona speaks about it. `add_to_context` — stash silently, no follow-up turn. `response_in_result` — speak the result verbatim (Gemini Live: degrades to add_to_context). `fire_and_forget` — don''t wait for the result at all.'
          example: generate_response
        tool_spec:
          type: object
          description: 'Read-only. The OpenAI-shaped spec the LLM sees: `{ type, function: { name, description, parameters } }`.'
          example:
            type: function
            function:
              name: lookup_account
              description: 'Fetch the participant''s CRM record so you can reference their plan, MRR, and last contact date.'
              parameters:
                type: object
                properties:
                  account_id:
                    type: string
                required:
                  - account_id
        created_at:
          type: string
          format: date-time
          example: '2026-06-18T12:34:56.000Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-06-18T12:34:56.000Z'
    ScenarioCustomFunctionAttachment:
      type: object
      description: Links a tool to a scenario. The tool is advertised to the LLM only when `active = true`.
      required:
        - id
        - scenario_id
        - custom_function_id
        - active
      properties:
        id:
          type: string
          format: uuid
          example: f0d2e1b8-cc1d-4ef7-a3ba-1f4b0d2c5a4b
        scenario_id:
          type: string
          format: uuid
          example: 7e3b9c2a-1d4f-4a1b-bdc6-9c8b2d3f4e5a
        custom_function_id:
          type: string
          format: uuid
          example: 4f8a6c50-9d3b-4c1f-9c0a-7a3b6e2d1f10
        active:
          type: boolean
          default: true
          description: 'Set `false` to hide the tool from the LLM without detaching.'
          example: true
        position:
          type: integer
          minimum: 0
          default: 0
          description: 'Display order in the UI. Runtime ignores this.'
          example: 0
        custom_function:
          $ref: '#/components/schemas/CustomFunction'
          description: Embedded tool definition. Returned on list/attach/update responses.
        created_at:
          type: string
          format: date-time
          example: '2026-06-18T12:35:00.000Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-06-18T12:35:00.000Z'
    Guardrail:
      type: object
      description: >-
        A named prompt fragment. Every guardrail attached to a scenario is appended to that scenario's
        system prompt as a bullet under a `## Guardrails` heading, so the persona treats it as a
        non-negotiable rule for the whole conversation.
      required:
        - id
        - guardrail_name
        - guardrail_prompt
        - active
      properties:
        id:
          type: string
          format: uuid
          example: 9b1f3d70-2a4e-4c8b-8f1a-6d5c4b3a2e10
        membership_id:
          type: string
          format: uuid
          example: a1b2c3d4-e5f6-7890-abcd-ef0123456789
        guardrail_name:
          type: string
          maxLength: 64
          pattern: '^[a-zA-Z0-9_-]{1,64}$'
          description: >-
            Handle for the rule. Unique per account. Used in the API and in your logs — it is never
            shown to the persona or the participant.
          example: no_competitors
        guardrail_prompt:
          type: string
          maxLength: 10000
          description: >-
            The rule itself, appended verbatim to the system prompt. Write it as a direct instruction.
            Encrypted at rest.
          example: 'Only mention products within Our Company Inc. during conversations; never discuss competitors.'
        active:
          type: boolean
          default: true
          description: 'Account-level kill-switch. `false` removes the rule from every scenario at once.'
          example: true
        scenarios:
          type: array
          description: 'Scenarios this guardrail is attached to. Returned only on the single-guardrail read.'
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              name:
                type: string
              active:
                type: boolean
              position:
                type: integer
        created_at:
          type: string
          format: date-time
          example: '2026-09-09T12:34:56.000Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-09-09T12:34:56.000Z'
    ScenarioGuardrailAttachment:
      type: object
      description: 'Links a guardrail to a scenario. The rule enters the system prompt only when `active = true`.'
      required:
        - id
        - scenario_id
        - guardrail_id
        - active
      properties:
        id:
          type: string
          format: uuid
          example: c7e4a2b1-8f3d-4e6a-9b0c-1d2e3f4a5b6c
        scenario_id:
          type: string
          format: uuid
          example: 7e3b9c2a-1d4f-4a1b-bdc6-9c8b2d3f4e5a
        guardrail_id:
          type: string
          format: uuid
          example: 9b1f3d70-2a4e-4c8b-8f1a-6d5c4b3a2e10
        active:
          type: boolean
          default: true
          description: 'Set `false` to keep the attachment but drop the rule from the prompt.'
          example: true
        position:
          type: integer
          minimum: 0
          default: 0
          description: 'Order this rule appears in within the `## Guardrails` block. Lower first.'
          example: 0
        guardrail:
          $ref: '#/components/schemas/Guardrail'
          description: Embedded guardrail definition. Returned on list/attach/update responses.
        created_at:
          type: string
          format: date-time
          example: '2026-09-09T12:35:00.000Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-09-09T12:35:00.000Z'
    Skill:
      type: object
      description: >-
        An invokable instruction pack. Only the one-line `trigger` sits in the agent's prompt each turn;
        the full `instructions` load when the agent invokes the skill mid-meeting and are dropped when
        the flow completes.
      required:
        - id
        - name
        - trigger
        - instructions
        - active
      properties:
        id:
          type: string
          format: uuid
          example: 9f0e1d2c-3b4a-5968-8776-655443322110
        membership_id:
          type: string
          format: uuid
          example: a1b2c3d4-e5f6-7890-abcd-ef0123456789
        name:
          type: string
          maxLength: 64
          pattern: '^[a-zA-Z0-9_-]{1,64}$'
          description: 'Identifier the agent passes to `invoke_skill`. Unique per account.'
          example: book_demo
        trigger:
          type: string
          maxLength: 500
          description: >-
            One line describing WHEN to invoke this skill. Lives in the base prompt on every turn —
            keep it short and specific.
          example: 'book_demo: when the participant asks to see the product live.'
        instructions:
          type: string
          maxLength: 8000
          description: 'The instruction pack, delivered to the agent only after it invokes the skill.'
          example: 'Confirm intent first. Then collect their preferred time and timezone, one question per turn, and call schedule_demo once.'
        gated_tool_names:
          type: array
          maxItems: 20
          default: []
          items:
            type: string
            pattern: '^[a-zA-Z0-9_-]{1,64}$'
          description: >-
            Custom-function names that refuse to execute until this skill is invoked. `[]` means the
            skill is purely behavioural.
          example:
            - schedule_demo
        active:
          type: boolean
          default: true
          description: 'Account-level kill-switch for the definition.'
          example: true
        scenarios:
          type: array
          description: 'Scenarios this skill is attached to. Returned only on the single-skill read.'
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              name:
                type: string
              active:
                type: boolean
              position:
                type: integer
        created_at:
          type: string
          format: date-time
          example: '2026-09-10T09:00:00.000Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-09-10T09:00:00.000Z'
    ScenarioSkillAttachment:
      type: object
      description: 'Links a skill to a scenario. The trigger reaches the agent only when `active = true`.'
      required:
        - id
        - scenario_id
        - skill_id
        - active
      properties:
        id:
          type: string
          format: uuid
          example: 3a2b1c0d-4e5f-6789-abcd-ef0123456789
        scenario_id:
          type: string
          format: uuid
          example: 7e3b9c2a-1d4f-4a1b-bdc6-9c8b2d3f4e5a
        skill_id:
          type: string
          format: uuid
          example: 9f0e1d2c-3b4a-5968-8776-655443322110
        active:
          type: boolean
          default: true
          description: 'Set `false` to keep the attachment but hide the skill from the agent.'
          example: true
        position:
          type: integer
          minimum: 0
          default: 0
          description: 'Order the triggers are listed in. Lower first.'
          example: 0
        skill:
          $ref: '#/components/schemas/Skill'
          description: Embedded skill definition. Returned on list/attach/update responses.
        created_at:
          type: string
          format: date-time
          example: '2026-09-10T09:05:00.000Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-09-10T09:05:00.000Z'
    Memory:
      type: object
      description: >-
        One remembered fact, held in the container named by its user_memory_tag. Every agent with
        memory on that runs a call under that tag is told it at the start of the call.
      properties:
        id:
          type: string
          format: uuid
          example: 452f76ca-c6cd-4ab9-9beb-ded26e54d903
        user_memory_tag:
          type: string
          example: crm_48213
        content:
          type: string
          description: One fact, one line.
          example: Prefers calls after 6pm IST
        token_estimate:
          type: integer
          example: 7
        source:
          type: string
          enum: [meeting, import, api]
          description: '`meeting` = learned on a call, `import` = added via POST /memories.'
        source_scenario_id:
          type: string
          format: uuid
          nullable: true
          description: The agent that learned it, or that an import was attributed to.
        source_meeting_id:
          type: string
          format: uuid
          nullable: true
        external_id:
          type: string
          nullable: true
          description: The fact's id in the system it was imported from.
          example: note_91
        created_at:
          type: string
          format: date-time
          example: '2026-05-01T00:00:00.000Z'
    MemoryContainer:
      type: object
      description: Every memory under one user_memory_tag in your workspace.
      properties:
        user_memory_tag:
          type: string
          example: crm_48213
        subject:
          type: object
          nullable: true
          description: >-
            Who a default container (`membership:<id>` / `participant:<id>`) is about. Null for
            your own tags.
          properties:
            kind:
              type: string
              enum: [membership, participant]
            id:
              type: string
              format: uuid
            name:
              type: string
              nullable: true
            email:
              type: string
              nullable: true
        memory_count:
          type: integer
          example: 7
        token_total:
          type: integer
          example: 52
        first_memory_at:
          type: string
          format: date-time
        last_memory_at:
          type: string
          format: date-time
        agents:
          type: array
          description: The agents that have written into this container.
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              name:
                type: string
                nullable: true
              memory_enabled:
                type: boolean
security:
  - apiKeyAuth: []
tags:
  - name: Users
  - name: Personas
  - name: Voices
  - name: Scenarios
  - name: Goals
  - name: Meetings
  - name: Analyses
  - name: Recordings
  - name: Transcripts
  - name: Tools
    description: Account-scoped custom function (tool) definitions the LLM can call mid-meeting.
  - name: Guardrails
    description: Account-scoped named prompt fragments appended to a scenario's system prompt.
  - name: Meeting Skills
    description: Account-scoped invokable instruction packs the agent loads mid-meeting.
  - name: Stage Tokens
    description: Verify the signed token a screen app (presented page) received for the meeting it was opened in.
  - name: Skill Packages
    description: Register a `waterr-skill.json` manifest version and install it — skill, tools, renderers and events endpoint in one call.


# --- truncated at 32 KB (123 KB total) ---
# Full source: https://artifacts.apis.io/waterr-ai/openapi/_original/waterr-ai-api-openapi.yml