openapi: 3.1.0
info:
  title: WAVE Enterprise Streaming Platform API
  description: >
    Complete API reference for WAVE Enterprise Streaming Platform.


    ## Authentication

    All API requests require a Bearer token in the Authorization header:

    ```

    Authorization: Bearer YOUR_API_KEY

    ```


    ## Rate Limiting

    API requests are rate limited. When rate limited, you'll receive a 429
    response

    with a `Retry-After` header indicating when to retry.


    ## Pagination

    List endpoints support pagination via `page` and `perPage` query parameters.

    Responses include pagination metadata.


    ## Errors

    All errors return the normalized WAVE envelope `{ "error": { "code",
    "message" } }`,

    optionally enriched with `details`, `suggestions`, `did_you_mean`, and
    `doc_url`.
  version: 1.1.0
  contact:
    name: WAVE Developer Support
    url: https://wave.online/developers
    email: developers@wave.online
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - url: https://api.wave.online/v1
    description: Production API
security:
  - BearerAuth: []
tags:
  - name: Pricing
    description: Seller-facing pricing tier manifests (pricing-pages).
  - name: Custody
    description: Money-engine held-fund capability operations (operator-plane).
  - name: Engine
    description: The media-engine capability contract.
  - name: Gpu
    description: The WAVE-hosted GPU inference plane.
  - name: Agent Auth
    description: "The OAuth Device Authorization Grant (RFC 8628) ceremony that lets
      a self-hosted agent or CLI act on a user's wallets: the agent requests a
      device code, the user approves once in a browser, then the agent holds
      tokens and signs with ephemeral keys — no app secret ever ships to the
      agent. These two routes are the pre-credential bootstrap (no Bearer token
      required; that is the point of the grant), served as a proxy over Privy's
      device authorization endpoints."
  - name: Clips
    description: AI-powered highlight detection and clip management
  - name: Voice
    description: Text-to-speech synthesis and voice cloning
  - name: Captions
    description: Auto-captioning and multi-language translation
  - name: Chapters
    description: AI chapter detection and video segmentation
  - name: Editor
    description: Cloud video editing projects
  - name: Phone
    description: VoIP phone lines and call management
  - name: Collab
    description: Real-time collaboration rooms
  - name: Podcast
    description: Podcast show and episode management
  - name: Transcribe
    description: Speech-to-text transcription
  - name: Sentiment
    description: Sentiment and emotion analysis
  - name: Search
    description: Semantic content search
  - name: Realtime
    description: "Live control & event plane — presence, pub/sub broadcast, and the
      streaming-event bus the WAVE AI products push into. Served THROUGH the
      gateway at https://api.wave.online/v1/realtime/* (the gateway
      authenticates + meters, then forwards to the internal wave-realtime-edge
      worker); subscribe over one WebSocket, producers publish over REST.
      GA-CONTRACT-001 (2026-09-28): these four operations previously carried a
      per-operation `servers` override to the bare host `realtime.wave.online`,
      which does not resolve (NXDOMAIN) — removed below; the live route is
      /v1/realtime/*, not a separate host."
  - name: AV Mux/Demux
    description: "Synchronous container-transform for local IP video + Dante/AES67
      audio: mux separate RTP H.264 video and Dante audio into one sync-locked
      MPEG-TS or fMP4 stream, and demux the inverse. x402 metered per minute
      (`wave_av_minutes`) plus per transform-second
      (`wave_av_transform_seconds`)."
  - name: Braided Audio
    description: On-demand WAVE Braided Audio publish — mixes multiple named audio
      sources into one MoQ-native braided track (single interleaved multichannel
      stream, not N independent streams). Requires the `moq:write` entitlement.
      Publishing spins up an on-demand machine; the same namespace can be
      republished (replacing the prior machine) or explicitly stopped.
  - name: MoQ
    description: "Media over QUIC join-token mint — the only HTTP surface of the MoQ
      product. These two endpoints authorize the caller on the api host and
      return a short-lived signed join-token plus the relay URL to connect to;
      media never transits the API gateway, because the client opens the MoQ
      session DIRECTLY to the relay at moq.wave.online carrying that token. The
      media session itself is not an HTTP surface and is deliberately not
      modelled in this document: it is the IETF Media over QUIC Transport
      protocol (control + object frames over WebTransport / QUIC, with a
      WebSocket fallback for browsers that cannot open a raw QUIC session). To
      use it, point a MoQ client at `relayWsUrl` and pass the token as the
      `join` query parameter (browser WebSocket clients cannot set request
      headers) or, server-to-server, as the `x-wave-moq-join` request header —
      SDK clients mint the token; carrying it over the wire is the MoQ client's
      job. DRAFT VERSION: this surface corresponds to
      draft-ietf-moq-transport-18
      (https://datatracker.ietf.org/doc/draft-ietf-moq-transport/18/), which is
      what the WAVE relay currently speaks (preferred draft-18, negotiating
      draft-07..draft-18 over ALPN). draft-19 was published 2026-07-06 and is
      NOT yet deployed; adopting it is tracked internally. The join-token mint
      is transport-version independent — a draft bump changes the wire session,
      not this HTTP contract."
  - name: Identity
    description: Agent directory — resolve a WAVE agent id to its public channel map
      (email, credential key name, org, channels). Read-only; public-directory
      data only, never secret material.
  - name: Analytics
    description: Account-level usage and engagement analytics.
  - name: Billing
    description: Account billing status and usage-based billing detail.
  - name: Cameras
    description: Managed PTZ/robotic camera registration and control-command
      dispatch (iris, focus, zoom, white balance, gain, shutter, recording,
      presets).
  - name: Live
    description: Real-time audio transcription, with an optional fast-LLM step
      (summarize, moderate, translate, or a custom instruction) run over the
      transcript. Processes one provided audio chunk per call — it does not
      attach a persistent caption feed to a live stream.
  - name: Moderate
    description: AI-assisted content moderation for chat, comments, and other text surfaces.
  - name: Productions
    description: Multi-camera production sessions — program/preview camera switching
      and graphics-overlay control for a live production.
  - name: Streams
    description: Live stream lifecycle — create a stream, start/stop it, read its
      status and per-stream analytics, and mark highlight moments for later
      clipping.
  - name: Usage
    description: Raw per-dimension usage totals from the underlying meter ledger —
      see Billing for the billed-and-priced view.
  - name: Enhance
    description: "AI video super-resolution (paused): every call currently returns
      503 PRODUCT_PAUSED before auth or payment, and nothing is charged. v1
      ships one model, `espcn` (ESPCN, a fixed exact 3x upscale) — unrecognized
      `model` values 400. Requires the `enhance:write` entitlement; once
      unpaused, x402-payable per-output-minute (`wave_enhance_minutes`, rounded
      up to the nearest minute of rendered output duration)."
paths:
  /agent/auth/device:
    post:
      operationId: agentAuthDevice
      tags:
        - Agent Auth
      security: []
      summary: Start the OAuth Device Authorization ceremony (RFC 8628)
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      responses:
        "200":
          description: The device grant (codes, verification URI, expiry, poll interval)
          content:
            application/json:
              schema:
                type: object
                required:
                  - device_code
                  - user_code
                  - verification_uri
                  - verification_uri_complete
                  - expires_in
                  - interval
                properties:
                  device_code:
                    type: string
                  user_code:
                    type: string
                  verification_uri:
                    type: string
                    format: uri
                    description: The approve URL the human opens
                  verification_uri_complete:
                    type: string
                    format: uri
                    description: The same URL with the user code prefilled
                  expires_in:
                    type: integer
                    description: Seconds until the device code expires (600)
                  interval:
                    type: integer
                    description: Poll interval in seconds (5)
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          description: 401 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "403":
          description: Device authorization not enabled for the app (dashboard toggle)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          $ref: "#/components/responses/RateLimitError"
        "502":
          description: Upstream auth endpoint unreachable
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "503":
          description: Ceremony not configured on this deployment (no app id)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
  /agent/auth/token:
    post:
      operationId: agentAuthToken
      tags:
        - Agent Auth
      security: []
      summary: Poll for / refresh the ceremony tokens
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - title: DeviceCodeGrant
                  description: Poll for tokens while approval is pending (grant_type=device_code)
                  type: object
                  required:
                    - grant_type
                    - device_code
                  additionalProperties: false
                  properties:
                    grant_type:
                      type: string
                      enum:
                        - urn:ietf:params:oauth:grant-type:device_code
                        - device_code
                      description: The registered RFC 8628 URN (canonical, what the upstream token
                        endpoint requires) or the bare shorthand (accepted at
                        this seam and canonicalized to the URN before
                        forwarding)
                    device_code:
                      type: string
                - title: RefreshTokenGrant
                  description: Exchange a refresh token for a new access token
                    (grant_type=refresh_token)
                  type: object
                  required:
                    - grant_type
                    - refresh_token
                  additionalProperties: false
                  properties:
                    grant_type:
                      type: string
                      enum:
                        - refresh_token
                    refresh_token:
                      type: string
      responses:
        "200":
          description: "Tokens. First approval returns access_token plus the initial
            refresh_token; a refresh exchange returns access_token plus a
            REPLACEMENT refresh_token (the old one is invalidated by the same
            call). An absent refresh_token signals revocation: restart the
            ceremony."
          content:
            application/json:
              schema:
                type: object
                required:
                  - access_token
                properties:
                  access_token:
                    type: string
                  refresh_token:
                    type: string
                    description: Present on first approval and on every refresh exchange (rotation);
                      absent only when the grant is revoked or expired
        "400":
          description: Invalid grant_type, missing credential for the grant, or the
            upstream polling protocol error passed through verbatim
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: 401 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "403":
          description: 403 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          $ref: "#/components/responses/RateLimitError"
        "502":
          description: Upstream auth endpoint unreachable
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "503":
          description: Ceremony not configured on this deployment (no app id)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
  /batch:
    post:
      operationId: batchOperations
      tags:
        - Batch
      summary: Execute a batch of operations in one request
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - operations
              properties:
                operations:
                  type: array
                  minItems: 1
                  maxItems: 25
                  items:
                    type: object
                    required:
                      - method
                      - path
                    properties:
                      method:
                        type: string
                        enum:
                          - GET
                          - HEAD
                          - POST
                          - PUT
                          - PATCH
                          - DELETE
                      path:
                        type: string
                        description: An enforced /v1 route
                      body:
                        description: The operation's JSON body (mutating methods only)
      responses:
        "200":
          description: Per-operation results
          content:
            application/json:
              schema:
                type: object
                properties:
                  operations:
                    type: integer
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        ok:
                          type: boolean
                        status:
                          type: integer
                        body:
                          description: The operation's response body
        "400":
          description: Invalid batch (operations[] required, 25-op cap)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: 401 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "403":
          description: 403 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: Rate limited (RFC RateLimit headers on the response)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
  /live/pipeline:
    post:
      tags:
        - Live
      summary: Transcribe an audio clip and run a fast-LLM step over it
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      operationId: startLivePipeline
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
                - llm_model
              properties:
                file:
                  type: string
                  format: binary
                  description: Audio bytes to transcribe.
                stream_id:
                  type: string
                  maxLength: 128
                  pattern: ^[A-Za-z0-9._:-]{1,128}$
                  description: "Client-chosen correlation id (letters, digits, `. _ : -`, 1-128
                    chars), echoed back for per-stream correlation."
                language:
                  type: string
                  description: ISO 639 language hint (transcribe task only).
                task:
                  type: string
                  enum:
                    - transcribe
                    - translate
                  default: transcribe
                model:
                  type: string
                  enum:
                    - whisper-large-v3-turbo
                    - whisper-large-v3
                  description: Default whisper-large-v3-turbo; translate forces whisper-large-v3.
                mode:
                  type: string
                  enum:
                    - summarize
                    - moderate
                    - translate
                    - custom
                  default: summarize
                instruction:
                  type: string
                  maxLength: 500
                  description: Custom instruction, used when mode=custom.
                llm_model:
                  type: string
                  description: Fast LLM model id to run the pipeline step.
                max_tokens:
                  type: integer
                  minimum: 1
                  maximum: 4096
                  default: 256
      responses:
        "200":
          description: Transcript plus the LLM step's output
          content:
            application/json:
              schema:
                type: object
                properties:
                  transcript:
                    type: string
                  duration:
                    type: number
                  llm:
                    type: object
                    properties:
                      mode:
                        type: string
                      model:
                        type: string
                      output:
                        type: string
                      usage:
                        type: object
                        properties:
                          prompt_tokens:
                            type: integer
                          completion_tokens:
                            type: integer
                  stream_id:
                    type: string
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The live-pipeline feature is not armed for this account.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "503":
          description: Transcription is temporarily unavailable — retry after the given
            delay.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
  /live/caption:
    post:
      tags:
        - Live
      summary: Transcribe an audio clip
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      operationId: transcribeLiveAudio
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                stream_id:
                  type: string
                  maxLength: 128
                  pattern: ^[A-Za-z0-9._:-]{1,128}$
                  description: "Client-chosen correlation id (letters, digits, `. _ : -`, 1-128
                    chars), echoed back for per-stream correlation."
                language:
                  type: string
                task:
                  type: string
                  enum:
                    - transcribe
                    - translate
                  default: transcribe
                model:
                  type: string
                  enum:
                    - whisper-large-v3-turbo
                    - whisper-large-v3
                response_format:
                  type: string
                  enum:
                    - verbose_json
                    - json
                    - text
                  default: verbose_json
                format:
                  type: string
                  enum:
                    - json
                    - vtt
                    - srt
                    - scc
                    - text
                  default: json
                  description: Output shape. Non-json returns a serialized caption file body.
                t0:
                  type: number
                  description: Windowed-mode start offset (seconds) on the stream timeline.
                seq:
                  type: integer
                  description: Windowed-mode window index, echoed back for ordering.
      responses:
        "200":
          description: Transcription result (JSON, or a serialized caption file when
            `format` != json)
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                description: Relays the transcription engine's JSON (text, segments, language,
                  duration) verbatim, plus `stream_id`/`window` when supplied.
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The live-pipeline feature is not armed for this account.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "503":
          description: Transcription is temporarily unavailable — retry after the given
            delay.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
  /billing:
    get:
      tags:
        - Billing
      summary: Get the current billing account
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      operationId: getBilling
      responses:
        "200":
          description: Billing account
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BillingAccount"
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
  /billing/usage:
    get:
      tags:
        - Billing
      summary: Get billed usage for a date range
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      operationId: getBillingUsage
      parameters:
        - name: from
          in: query
          description: Range start (YYYY-MM-DD). Defaults to the start of the current month.
          schema:
            type: string
            format: date
        - name: to
          in: query
          description: Range end (YYYY-MM-DD). Defaults to today.
          schema:
            type: string
            format: date
      responses:
        "200":
          description: Billed usage
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BillingUsageResponse"
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "503":
          description: Billing usage is temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
  /usage:
    get:
      tags:
        - Billing
      summary: Get raw per-dimension usage
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      operationId: getUsage
      parameters:
        - name: from
          in: query
          description: Range start (YYYYMMDD). Defaults to today.
          schema:
            type: string
        - name: to
          in: query
          description: Range end (YYYYMMDD). Defaults to today.
          schema:
            type: string
      responses:
        "200":
          description: Raw usage totals
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UsageResponse"
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
  /analytics/overview:
    get:
      tags:
        - Analytics
      summary: Get an account-level analytics overview
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      operationId: getAnalyticsOverview
      parameters:
        - $ref: "#/components/parameters/AnalyticsFromParam"
        - $ref: "#/components/parameters/AnalyticsToParam"
      responses:
        "200":
          description: Analytics overview
          content:
            application/json:
              schema:
                type: object
                properties:
                  organizationId:
                    type: string
                  period:
                    $ref: "#/components/schemas/DateRange"
                  summary:
                    type: object
                    properties:
                      totalEvents:
                        type: integer
                      totalQuantity:
                        type: number
                      activeDays:
                        type: integer
                      topDimensions:
                        type: array
                        items:
                          type: object
                          properties:
                            dimension:
                              type: string
                            quantity:
                              type: number
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "503":
          description: Analytics are temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
  /analytics/top-content:
    get:
      tags:
        - Analytics
      summary: Get top content by usage
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      operationId: getAnalyticsTopContent
      parameters:
        - $ref: "#/components/parameters/AnalyticsFromParam"
        - $ref: "#/components/parameters/AnalyticsToParam"
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        "200":
          description: Top content by usage
          content:
            application/json:
              schema:
                type: object
                properties:
                  organizationId:
                    type: string
                  period:
                    $ref: "#/components/schemas/DateRange"
                  topContent:
                    type: array
                    items:
                      type: object
                      properties:
                        rank:
                          type: integer
                        dimension:
                          type: string
                        quantity:
                          type: number
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "503":
          description: Analytics are temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
  /analytics/engagement:
    get:
      tags:
        - Analytics
      summary: Get account-wide engagement analytics
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      operationId: getAnalyticsEngagement
      parameters:
        - $ref: "#/components/parameters/AnalyticsFromParam"
        - $ref: "#/components/parameters/AnalyticsToParam"
      responses:
        "200":
          description: Engagement analytics
          content:
            application/json:
              schema:
                type: object
                properties:
                  organizationId:
                    type: string
                  period:
                    $ref: "#/components/schemas/DateRange"
                  engagement:
                    type: object
                    properties:
                      totalEvents:
                        type: integer
                      totalQuantity:
                        type: number
                      averageEventsPerDay:
                        type: number
                      peakDay:
                        type:
                          - string
                          - "null"
                      peakEvents:
                        type: integer
                      activeDays:
                        type: integer
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "503":
          description: Analytics are temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
  /clips:
    get:
      tags:
        - Clips
      summary: List clips
      operationId: listClips
      parameters:
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/PerPageParam"
        - name: videoId
          in: query
          schema:
            type: string
        - name: status
          in: query
          schema:
            $ref: "#/components/schemas/JobStatus"
        - name: category
          in: query
          schema:
            type: string
      responses:
        "200":
          description: Paginated list of clips
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/PaginatedResponse"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/Clip"
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          description: 401 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "403":
          description: 403 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
    post:
      tags:
        - Clips
      summary: Create a clip
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      operationId: createClip
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ClipCreate"
      responses:
        "201":
          description: Clip created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClipCreateResponse"
        "400":
          description: Validation error (the clip route's own envelope, not the shared
            Error schema).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClipError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
  /clips/{clipId}:
    get:
      tags:
        - Clips
      summary: Get a clip
      operationId: getClip
      parameters:
        - name: clipId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Clip details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Clip"
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          description: 401 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "403":
          description: 403 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "404":
          $ref: "#/components/responses/NotFoundError"
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
    patch:
      tags:
        - Clips
      summary: Update a clip
      operationId: updateClip
      parameters:
        - name: clipId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ClipUpdate"
      responses:
        "200":
          description: Clip updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Clip"
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          description: 401 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "403":
          description: 403 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
    delete:
      tags:
        - Clips
      summary: Delete a clip
      operationId: deleteClip
      parameters:
        - name: clipId
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Clip deleted
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          description: 401 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "403":
          description: 403 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
  /clips/detect:
    post:
      tags:
        - Clips
      summary: Start AI clip detection
      operationId: detectClips
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ClipDetectRequest"
      responses:
        "202":
          description: Detection job started
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DetectionJob"
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          description: 401 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "403":
          description: 403 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
  /voice/voices:
    get:
      tags:
        - Voice
      summary: List available voices
      operationId: listVoices
      parameters:
        - name: category
          in: query
          schema:
            type: string
            enum:
              - premade
              - cloned
              - professional
        - name: language
          in: query
          schema:
            type: string
      responses:
        "200":
          description: List of voices
          content:
            application/json:
              schema:
                type: object
                properties:
                  voices:
                    type: array
                    items:
                      $ref: "#/components/schemas/Voice"
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          description: 401 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "403":
          description: 403 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
  /voice/generate:
    post:
      tags:
        - Voice
      summary: Generate speech from text
      operationId: generateSpeech
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VoiceGenerateRequest"
      responses:
        "200":
          description: >
            Speech generated. The gateway returns one of three shapes depending
            on the engine path: an inline JSON payload with base64 audio +
            character `alignment` (single round-trip, carries word timestamps),
            an async job to poll, or raw audio bytes when timestamps were not
            requested.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/VoiceSynthesisInline"
                  - $ref: "#/components/schemas/VoiceGeneration"
            audio/mpeg:
              schema:
                type: string
                format: binary
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          $ref: "#/components/responses/RateLimitError"
        "502":
          $ref: "#/components/responses/UpstreamError"
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
  /voice/clone:
    post:
      tags:
        - Voice
      summary: Clone a voice from audio samples
      operationId: cloneVoice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VoiceCloneRequest"
      responses:
        "201":
          description: Voice cloned
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Voice"
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          description: 401 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "403":
          description: 403 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
  /captions:
    get:
      tags:
        - Captions
      summary: List caption jobs
      operationId: listCaptions
      parameters:
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/PerPageParam"
        - name: videoId
          in: query
          schema:
            type: string
        - name: status
          in: query
          schema:
            $ref: "#/components/schemas/JobStatus"
      responses:
        "200":
          description: Paginated list of caption jobs
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/PaginatedResponse"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/CaptionJob"
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          description: 401 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "403":
          description: 403 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
    post:
      tags:
        - Captions
      summary: Create a caption job
      operationId: createCaptionJob
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CaptionJobCreate"
      responses:
        "201":
          description: Caption job created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CaptionJob"
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          description: 401 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "403":
          description: 403 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
  /captions/{jobId}:
    get:
      tags:
        - Captions
      summary: Get a caption job
      operationId: getCaptionJob
      parameters:
        - name: jobId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Caption job details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CaptionJob"
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          description: 401 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "403":
          description: 403 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
    delete:
      tags:
        - Captions
      summary: Delete a caption job
      operationId: deleteCaptionJob
      parameters:
        - name: jobId
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Caption job deleted
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          description: 401 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "403":
          description: 403 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
  /captions/{jobId}/download:
    get:
      tags:
        - Captions
      summary: Download captions
      operationId: downloadCaptions
      parameters:
        - name: jobId
          in: path
          required: true
          schema:
            type: string
        - name: language
          in: query
          required: true
          schema:
            type: string
        - name: format
          in: query
          schema:
            type: string
            enum:
              - srt
              - vtt
              - txt
              - json
            default: srt
      responses:
        "200":
          description: Caption download
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    format: uri
                  content:
                    type: string
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          description: 401 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "403":
          description: 403 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
  /videos/{videoId}/chapters:
    get:
      tags:
        - Chapters
      summary: List chapters for a video
      operationId: listChapters
      deprecated: true
      x-status: unrouted
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      parameters:
        - name: videoId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: List of chapters
          content:
            application/json:
              schema:
                type: object
                properties:
                  chapters:
                    type: array
                    items:
                      $ref: "#/components/schemas/Chapter"
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          description: 401 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "403":
          description: 403 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
    post:
      tags:
        - Chapters
      summary: Create a chapter
      operationId: createChapter
      deprecated: true
      x-status: unrouted
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      parameters:
        - name: videoId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ChapterCreate"
      responses:
        "201":
          description: Chapter created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Chapter"
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          description: 401 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "403":
          description: 403 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
  /videos/{videoId}/chapters/detect:
    post:
      tags:
        - Chapters
      summary: Start AI chapter detection
      operationId: detectChapters
      deprecated: true
      x-status: unrouted
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      parameters:
        - name: videoId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ChapterDetectRequest"
      responses:
        "202":
          description: Detection job started
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DetectionJob"
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          description: 401 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "403":
          description: 403 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
  /transcribe:
    get:
      tags:
        - Transcribe
      summary: List transcriptions
      operationId: listTranscriptions
      parameters:
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/PerPageParam"
        - name: status
          in: query
          schema:
            $ref: "#/components/schemas/JobStatus"
      responses:
        "200":
          description: Paginated list of transcriptions
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/PaginatedResponse"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/Transcription"
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          description: 401 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "403":
          description: 403 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
    post:
      tags:
        - Transcribe
      summary: Create a transcription
      operationId: createTranscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TranscriptionCreate"
      responses:
        "201":
          description: Transcription created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Transcription"
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          description: 401 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "403":
          description: 403 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
  /transcribe/{transcriptionId}:
    get:
      tags:
        - Transcribe
      summary: Get a transcription
      operationId: getTranscription
      parameters:
        - name: transcriptionId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Transcription details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Transcription"
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          description: 401 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "403":
          description: 403 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
    delete:
      tags:
        - Transcribe
      summary: Delete a transcription
      operationId: deleteTranscription
      parameters:
        - name: transcriptionId
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Transcription deleted
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          description: 401 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "403":
          description: 403 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
  /sentiment:
    post:
      tags:
        - Sentiment
      summary: Create a sentiment analysis
      operationId: createSentimentAnalysis
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SentimentAnalysisCreate"
      responses:
        "201":
          description: Analysis created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SentimentAnalysis"
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          description: 401 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "403":
          description: 403 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
      x-lifecycle: preview
  /sentiment/analyze:
    post:
      tags:
        - Sentiment
      summary: Analyze text directly
      operationId: analyzeText
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - text
              properties:
                text:
                  type: string
                includeEmotions:
                  type: boolean
                  default: false
                includeTopics:
                  type: boolean
                  default: false
      responses:
        "200":
          description: Analysis result
          content:
            application/json:
              schema:
                type: object
                properties:
                  sentiment:
                    type: string
                    enum:
                      - positive
                      - negative
                      - neutral
                  score:
                    type: number
                  confidence:
                    type: number
                  emotions:
                    $ref: "#/components/schemas/EmotionBreakdown"
                  topics:
                    type: array
                    items:
                      $ref: "#/components/schemas/TopicSentiment"
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          description: 401 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "403":
          description: 403 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
      x-lifecycle: preview
  /search:
    post:
      tags:
        - Search
      summary: Hybrid search (dense + sparse → RRF) over streams/clips/transcripts,
        tenant-isolated
      operationId: search
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SearchRequest"
      responses:
        "200":
          description: Ranked results + metadata (metered wave_search_queries)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchResponse"
        "400":
          description: Invalid request (bad body/query/namespace/topK)
        "401":
          description: 401 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "403":
          description: 403 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: Per-org rate limit exceeded
        "503":
          description: Search plane unconfigured
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
  /search/index:
    post:
      tags:
        - Search
      summary: Index (upsert) one doc or a batch
      operationId: searchIndex
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SearchIndexRequest"
      responses:
        "200":
          description: Indexed count + ids
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchIndexResponse"
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          description: 401 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "403":
          description: 403 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
  /search/index/{id}:
    delete:
      tags:
        - Search
      summary: Delete one indexed doc (idempotent)
      operationId: searchDelete
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: namespace
          in: query
          required: true
          schema:
            type: string
            enum:
              - streams
              - users
              - clips
              - transcripts
      responses:
        "200":
          description: Deleted flag + id
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchDeleteResponse"
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          description: 401 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "403":
          description: 403 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
  /search/analytics:
    get:
      tags:
        - Search
      summary: Own-org query insights (top / zero-result / trending)
      operationId: searchAnalytics
      responses:
        "200":
          description: Insight receipt
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchAnalyticsResponse"
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          description: 401 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "403":
          description: 403 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
  /realtime/connect:
    get:
      tags:
        - Realtime
      summary: Subscribe to a channel (WebSocket)
      operationId: realtimeConnect
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      parameters:
        - name: channel
          in: query
          required: true
          schema:
            type: string
            pattern: ^[a-z0-9][a-z0-9:_-]{0,127}$
          description: Namespaced channel id, e.g. `stream:abc`, `room:xyz`.
        - name: as
          in: query
          required: false
          schema:
            type: string
          description: Member id to present as (defaults to the caller's key prefix).
      responses:
        "101":
          description: Switching Protocols — WebSocket established.
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          description: Authentication required
        "403":
          description: 403 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "426":
          description: Upgrade required (not a WebSocket request)
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
      x-lifecycle: preview
  /realtime/channels/{channel}/publish:
    post:
      tags:
        - Realtime
      summary: Publish an event to a channel
      operationId: realtimePublish
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      parameters:
        - name: channel
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - event
              properties:
                event:
                  type: string
                  description: Event name, e.g. `caption.cue`, `sentiment.tick`, `clip.created`,
                    `stream.started`.
                data:
                  description: Arbitrary JSON payload for the event.
      responses:
        "200":
          description: Published
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  delivered:
                    type: integer
                    description: Number of subscribers the event reached
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          description: Authentication required
        "403":
          description: 403 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
      x-lifecycle: preview
  /realtime/channels/{channel}/presence:
    get:
      tags:
        - Realtime
      summary: Current presence for a channel
      operationId: realtimePresence
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      parameters:
        - name: channel
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Presence list
          content:
            application/json:
              schema:
                type: object
                properties:
                  channel:
                    type: string
                  members:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          description: 401 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "403":
          description: 403 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
      x-lifecycle: preview
  /realtime/channels/{channel}/history:
    get:
      tags:
        - Realtime
      summary: Recent event history for a channel
      operationId: realtimeHistory
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      parameters:
        - name: channel
          in: path
          required: true
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 50
            maximum: 50
      responses:
        "200":
          description: Recent events
          content:
            application/json:
              schema:
                type: object
                properties:
                  channel:
                    type: string
                  events:
                    type: array
                    items:
                      type: object
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          description: 401 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "403":
          description: 403 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
      x-lifecycle: preview
  /braid/publish:
    post:
      tags:
        - Braided Audio
      summary: Publish a braided audio track
      operationId: publishBraidAudio
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BraidPublishRequest"
      responses:
        "201":
          description: Braid machine starting
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BraidPublishResult"
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          description: 401 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: Per-org concurrency or creation-rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "501":
          description: Braid publish unavailable — the worker is not provisioned for
            on-demand publish.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
  /braid/publish/{ns}:
    delete:
      tags:
        - Braided Audio
      summary: Stop a braided audio publish
      operationId: stopBraidAudio
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      parameters:
        - name: ns
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Braid machine stopped
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BraidStopResult"
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          description: 401 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: No live braid machine for this namespace.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "501":
          description: Braid publish unavailable — the worker is not provisioned for
            on-demand publish.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
  /av/remux:
    post:
      tags:
        - AV Mux/Demux
      summary: Mux synchronized IP video + Dante audio into one container
      operationId: avRemux
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AvRemuxRequest"
      responses:
        "200":
          description: Muxed container stream — binary, or an AvTransformResult envelope
            under Accept application/json.
          content:
            video/mp2t:
              schema:
                type: string
                format: binary
            application/json:
              schema:
                $ref: "#/components/schemas/AvTransformResult"
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          description: 401 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "402":
          description: Payment required — pay the x402 challenge and retry.
          headers:
            WWW-Authenticate:
              schema:
                type: string
              description: The x402 challenge, including the quoted price.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "501":
          description: AV mux/demux unavailable — the spoke is not provisioned (AV_ORIGIN
            unset).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
  /av/demux:
    post:
      tags:
        - AV Mux/Demux
      summary: Demux one container back into separate video + Dante audio
      operationId: avDemux
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AvDemuxRequest"
      responses:
        "200":
          description: Demux result — routed IP-video + Dante sink status.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AvTransformResult"
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          description: 401 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "402":
          description: Payment required — pay the x402 challenge and retry.
          headers:
            WWW-Authenticate:
              schema:
                type: string
              description: The x402 challenge, including the quoted price.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "501":
          description: AV mux/demux unavailable — the spoke is not provisioned (AV_ORIGIN
            unset).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
  /moq/publish/{ns}/{track}:
    post:
      tags:
        - MoQ
      summary: Mint a MoQ publish join-token
      operationId: mintMoqPublishToken
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      parameters:
        - $ref: "#/components/parameters/MoqNamespaceParam"
        - $ref: "#/components/parameters/MoqTrackParam"
        - name: x-wave-declare-protocol
          in: header
          required: false
          schema:
            type: string
          description: Optional declared origin protocol for billing (e.g. `moq`). Ignored
            unless recognized and authorized for this org; never rejects the
            mint.
      responses:
        "200":
          description: "Join-token minted. Served `cache-control: no-store` — never cache
            or log `joinToken`."
          headers:
            Cache-Control:
              schema:
                type: string
              description: Always `no-store` — the response carries a short-lived bearer
                token.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MoqJoinToken"
        "400":
          description: "`MOQ_JOIN_BAD_RESOURCE` — `ns` or `track` does not match
            `^[a-z0-9-]{1,64}$`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          $ref: "#/components/responses/RateLimitError"
        "503":
          $ref: "#/components/responses/MoqJoinUnconfigured"
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
  /moq/subscribe/{ns}/{track}:
    get:
      tags:
        - MoQ
      summary: Mint a MoQ subscribe join-token
      operationId: mintMoqSubscribeToken
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      parameters:
        - $ref: "#/components/parameters/MoqNamespaceParam"
        - $ref: "#/components/parameters/MoqTrackParam"
      responses:
        "200":
          description: "Join-token minted. Served `cache-control: no-store` — never cache
            or log `joinToken`."
          headers:
            Cache-Control:
              schema:
                type: string
              description: Always `no-store` — the response carries a short-lived bearer
                token.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MoqJoinToken"
        "400":
          description: "`MOQ_JOIN_BAD_RESOURCE` — `ns` or `track` does not match
            `^[a-z0-9-]{1,64}$`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          $ref: "#/components/responses/RateLimitError"
        "503":
          $ref: "#/components/responses/MoqJoinUnconfigured"
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
  /identity/resolve:
    get:
      tags:
        - Identity
      summary: Resolve a WAVE agent id to its public channel map
      operationId: identityResolve
      description: >-
        WAVE API v1. Versioned by URL path (/v1/). Deprecations announced via
        Sunset headers and the changelog.


        **No API key required.** A request with no Authorization header is
        served the same public directory entry, rate-limited to 60
        requests/minute per caller IP on a strict sliding window (429 with
        `RateLimit-*` + `Retry-After` over the limit; fail-closed 503 if the
        limiter backend is down). A keyless request may not send `org`. Keyed
        requests behave as above (directory:read scope, org rate limit).
      parameters:
        - name: agent
          in: query
          required: true
          description: Agent id (lowercase, e.g. `opencode`, `claude`, `telephony`)
          schema:
            type: string
            pattern: ^[a-z0-9-]{1,64}$
        - name: org
          in: query
          required: false
          description: Optional tenancy self-assertion; must equal the authenticated
            principal's org
          schema:
            type: string
      responses:
        "200":
          description: The resolved directory entry
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdentityResolveResponse"
        "400":
          description: Missing/bad agent id, or org self-assertion mismatch (MISSING_AGENT
            / BAD_AGENT / ORG_MISMATCH)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdentityResolveValidationError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Well-formed but unknown agent id (UNKNOWN_AGENT)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdentityResolveNotFoundError"
        "429":
          $ref: "#/components/responses/RateLimitError"
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
      security:
        - {}
        - BearerAuth: []
  /pricing/manifests:
    get:
      tags:
        - Pricing
      summary: List the caller-org's pricing tier manifests
      operationId: pricingManifestsList
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      responses:
        "200":
          description: The org's manifests
          content:
            application/json:
              schema:
                type: object
                required:
                  - org
                  - manifests
                properties:
                  org:
                    type: string
                  manifests:
                    type: array
                    items:
                      $ref: "#/components/schemas/PricingManifest"
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
    post:
      tags:
        - Pricing
      summary: Validate + upsert the caller-org's tier manifest
      operationId: pricingManifestsCreate
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - slug
                - tiers
              properties:
                slug:
                  type: string
                tiers:
                  type: array
                  items:
                    type: object
                    additionalProperties: true
      responses:
        "200":
          description: The upserted manifest
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PricingManifest"
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
  /custody/{op}:
    post:
      tags:
        - Custody
      summary: Held-fund capability operation (grant / revoke / inspect / exercise)
      operationId: custodyOperation
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      parameters:
        - name: op
          in: path
          required: true
          description: The custody operation
          schema:
            type: string
            enum:
              - grant
              - revoke
              - inspect
              - exercise
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - grantId
              properties:
                grantId:
                  type: string
                provider:
                  type: string
                scopes:
                  type: array
                  items:
                    type: string
                ttlSeconds:
                  type: number
      responses:
        "200":
          description: The operation receipt (metadata only — never a secret field)
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "503":
          description: CUSTODY_UNCONFIGURED — bindings/flag absent
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
  /engine/capabilities:
    get:
      tags:
        - Engine
      summary: The media-engine capability contract
      operationId: engineCapabilities
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      responses:
        "200":
          description: The capability contract
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
      x-lifecycle: preview
  /gpu/infer:
    post:
      tags:
        - Gpu
      summary: Dispatch a GPU inference job on the WAVE-hosted GPU plane
      operationId: gpuInfer
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                model:
                  type: string
                input:
                  type: object
                  additionalProperties: true
      responses:
        "200":
          description: The job receipt
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
      x-lifecycle: preview
    get:
      tags:
        - Gpu
      summary: GPU plane status
      operationId: gpuStatus
      description: WAVE API v1. Versioned by URL path (/v1/). Deprecations announced
        via Sunset headers and the changelog.
      responses:
        "200":
          description: Plane status
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        "400":
          description: 400 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: 404 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        "429":
          description: 429 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code
                      message:
                        type: string
                        description: Human-readable error message
                      param:
                        type: string
                        description: The parameter that caused the error
                        nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      x-version: "1"
      x-deprecation-policy: https://wave.online/changelog
      x-lifecycle: preview
  /compose:
    post:
      tags:
        - composer
      summary: Compose a plan from a plain-language intent
      description: "Returns a PLAN: the stages, the products, the scopes needed, the
        price rows and the per-edge typing verdict. Composing never calls a
        product and never bills. Requires composer:write."
      operationId: createComposeProposal
      security:
        - bearerWithScopes:
            - composer:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ComposeProposalCreate"
      responses:
        "200":
          description: "The composed proposal. Stamps x-wave-meter: wave_compose_proposals
            (counted, never billed)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComposeProposal"
  /compose/run:
    post:
      tags:
        - composer
      summary: Run a stored proposal once
      description: "Runs every gate that must hold before a product is called: input
        check, idempotency, manifest freshness, budget and the declared-IO
        typing gate. Refuses with 501 RUN_NOT_YET_DECLARED naming the exact
        missing declaration when a stage edge is undeclared. Requires
        composer:write."
      operationId: runComposeProposal
      security:
        - bearerWithScopes:
            - composer:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ComposeRunCreate"
      responses:
        "200":
          description: A REPLAY of a prior run with the same idempotency key and the same
            input.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComposeRunReplay"
  /uploads:
    post:
      tags:
        - composer
      summary: Create a presigned upload for a Composer source
      description: "Mints a presigned R2 PUT (valid 60 minutes) for one source file of
        at most 500 MB and 60 minutes. No charge and no price row. Limited to 30
        per hour per key. Requires composer:write. Retention: a source no
        successful paid stage has used is deleted 24h after upload or fetch; a
        source a paid stage used is kept until 7 days after its last use. Each
        key may hold at most 10 GB of unused sources (paid plans scale it:
        launch 50 GB, scale 100 GB, volume/custom 250 GB); over it, this answers
        429 until sources expire or are used."
      operationId: createUpload
      security:
        - bearerWithScopes:
            - composer:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ComposeUploadCreate"
      responses:
        "201":
          description: The presigned PUT.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComposeUpload"
        "413":
          description: "UPLOAD_TOO_LARGE: sizeBytes over 500 MB."
          content:
            application/json:
              schema:
                type: object
        "415":
          description: UPLOAD_TYPE_UNSUPPORTED.
          content:
            application/json:
              schema:
                type: object
        "429":
          description: UPLOAD_RATE_LIMITED (30/h per key) or UPLOAD_STORAGE_CAP.
          content:
            application/json:
              schema:
                type: object
  /compose/ingest/resolve:
    post:
      tags:
        - composer
      summary: Resolve a run input into a probed source (stage -1)
      description: "Turns `input.uploadId` (its PUT must have finished, else 409
        UPLOAD_INCOMPLETE) or `input.url` (fetched into the same store through
        the gateway's SSRF guard on every redirect hop: https, public host, port
        443) into `{sourceId, sourceType, durationSec, hasAudio, width, height,
        mime}`. Reads mp4, mov, m4a and wav. Over 500 MB or 60 minutes is 413;
        unreadable media is 415; a failed fetch is 502. Requires composer:write.
        Retention: a source no successful paid stage has used is deleted 24h
        after upload or fetch; a source a paid stage used is kept until 7 days
        after its last use. Each key may hold at most 10 GB of unused sources
        (paid plans scale it: launch 50 GB, scale 100 GB, volume/custom 250 GB);
        over it, this answers 429 until sources expire or are used."
      operationId: resolveComposeIngest
      security:
        - bearerWithScopes:
            - composer:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ComposeIngestResolveCreate"
      responses:
        "200":
          description: The resolved source.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComposeResolvedSource"
        "400":
          description: INGEST_INPUT_INVALID or INGEST_URL_REFUSED.
          content:
            application/json:
              schema:
                type: object
        "404":
          description: UPLOAD_NOT_FOUND.
          content:
            application/json:
              schema:
                type: object
        "409":
          description: "UPLOAD_INCOMPLETE: the PUT has not finished."
          content:
            application/json:
              schema:
                type: object
        "413":
          description: SOURCE_TOO_LARGE or SOURCE_TOO_LONG.
          content:
            application/json:
              schema:
                type: object
        "415":
          description: SOURCE_UNSUPPORTED_MEDIA.
          content:
            application/json:
              schema:
                type: object
        "429":
          description: SOURCE_STORAGE_CAP.
          content:
            application/json:
              schema:
                type: object
        "502":
          description: INGEST_FETCH_FAILED.
          content:
            application/json:
              schema:
                type: object
  /compose/proposals/{proposalId}:
    get:
      tags:
        - composer
      summary: Read a stored proposal by id
      description: Org scoped. Lets the CLI, SDK and MCP renderings re-read one
        proposal instead of re-composing it. Requires composer:read.
      operationId: getComposeProposal
      security:
        - bearerWithScopes:
            - composer:read
      parameters:
        - name: proposalId
          in: path
          required: true
          schema:
            type: string
            pattern: ^prp_[A-Za-z0-9_-]+$
      responses:
        "200":
          description: The stored proposal.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComposeProposal"
  /leaderboard:
    get:
      summary: Your org's usage leaderboard (meters ranked by consumption) — API key +
        usage:read
      description: "Tenant-scoped: rows are the calling org's own metered dimensions,
        ranked by billed usage over the window (`from`/`to` as YYYYMMDD, default
        trailing 7 days). The org is taken from the API key, never from the
        query string. Unauthenticated callers receive 401
        LEADERBOARD_AUTH_REQUIRED. The PUBLIC model-eval leaderboard is a
        different surface at https://leaderboard.wave.online/leaderboard (no key
        needed)."
      tags:
        - usage
      servers:
        - url: https://api.wave.online
      security:
        - bearerWithScopes:
            - usage:read
      externalDocs:
        description: Public model-eval leaderboard (measured rows only)
        url: https://leaderboard.wave.online/leaderboard
      responses:
        "200":
          description: "{ org, window:{from,to,days}, ranking:[{rank, meter, unit, used}]
            } — private, no-store"
        "401":
          description: LEADERBOARD_AUTH_REQUIRED — no or invalid API key; body names the
            public board's URL
        "403":
          description: SCOPE_INSUFFICIENT — key lacks usage:read (body names required_scope)
  /enhance:
    post:
      tags:
        - Enhance
      summary: Super-resolve a video with an AI model (paused; x402-payable once
        unpaused)
      operationId: enhanceVideo
      x-status: paused
      description: "Paused: every call currently returns 503 PRODUCT_PAUSED before
        auth or payment; nothing is charged. Once enhance is unpaused: upscales
        a video with an on-graph AI model. v1 ships exactly one model, `espcn`
        (ESPCN super-resolution, a fixed exact 3x factor baked into the trained
        weights — not a runtime parameter). Internally every input frame is
        letterboxed to a fixed working canvas before inference, so the v1 output
        is always 672x672 regardless of input resolution; a future model may
        support other output shapes. Send either the raw video bytes as the
        request body or a `url` query parameter pointing at an `https` source
        (the source is fetched server-side; redirects are not followed and
        non-public/loopback/private hosts are rejected). Once unpaused, auth is
        either lane: a bearer API key carrying the `enhance:write` entitlement,
        or no key at all — an unauthenticated call receives the 402 x402
        challenge and is served once paid (pay-per-call). While paused there is
        no 402 and no charge. Billed against the `wave_enhance_minutes` meter:
        the OUTPUT artifact's rendered duration in minutes, rounded up to the
        next whole minute."
      security:
        - {}
        - BearerAuth: []
      parameters:
        - name: model
          in: query
          required: false
          schema:
            type: string
            enum:
              - espcn
            default: espcn
          description: AI model to apply. v1 supports only `espcn`; any other value 400s.
        - name: url
          in: query
          required: false
          schema:
            type: string
            format: uri
          description: Fetch the source video from this `https` URL instead of sending it
            as the request body. Must be publicly reachable — loopback, private,
            link-local, and `.local`/ `.internal` hosts are rejected before any
            fetch.
      requestBody:
        required: false
        description: The source video, raw bytes. Omit the body (and use `?url=`
          instead) to have the source fetched server-side. Max 200 MiB either
          way.
        content:
          video/*:
            schema:
              type: string
              format: binary
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        "200":
          description: The enhanced video, binary, streamed back with the same
            content-type as the source. Per-job receipt and billing metadata are
            carried on response headers, not a JSON body.
          headers:
            x-enhance-model:
              schema:
                type: string
              description: The model that ran, e.g. `espcn`.
            x-enhance-scale-factor:
              schema:
                type: number
              description: Upscale factor actually applied.
            x-enhance-input-dimensions:
              schema:
                type: string
              description: Input frame dimensions as `WIDTHxHEIGHT`, e.g. `1280x720`.
            x-enhance-output-dimensions:
              schema:
                type: string
              description: Output frame dimensions as `WIDTHxHEIGHT`, e.g. `672x672`.
            x-wave-meter:
              schema:
                type: string
              description: The meter this job billed against — `wave_enhance_minutes`.
            x-wave-usage-minutes:
              schema:
                type: integer
              description: Output-duration minutes billed for this job (rounded up).
          content:
            video/*:
              schema:
                type: string
                format: binary
            application/octet-stream:
              schema:
                type: string
                format: binary
        "400":
          description: Invalid request — unrecognized `model`, an unsafe or invalid `url`,
            or no video supplied (neither a request body nor `?url=`).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: 'Once enhance is unpaused (while paused every call is 503
            PRODUCT_PAUSED instead): authentication failed AND the x402
            pay-per-call lane is not armed in this environment. When the pay
            lane is armed (the production default once unpaused), a missing or
            unrecognized API key yields the 402 x402 challenge instead — never
            this 401. A client should treat 401 as "re-authenticate with a valid
            bearer key" (pay-per-call is unavailable here).'
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "402":
          $ref: "#/components/responses/PaymentRequired"
          description: "Only once enhance is unpaused: the x402 payment challenge. While
            paused this is never returned and nothing is charged; every call is
            503 PRODUCT_PAUSED."
        "403":
          $ref: "#/components/responses/Forbidden"
        "413":
          description: The source video (request body, or the resolved `?url=` source)
            exceeds the 200 MiB limit.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "422":
          description: "`INPUT_TOO_LARGE` — the source video's frame dimensions exceed the
            v1 input-size cap. Downscale the source and retry."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "501":
          description: Enhance is not yet available in this environment (the spoke is not
            provisioned).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          $ref: "#/components/responses/UpstreamError"
        "503":
          description: "`PRODUCT_PAUSED`: enhance is paused, and every call returns this
            503 before auth or payment, with nothing charged. Not retryable
            until the product is unpaused. Otherwise (once unpaused) the enhance
            backend is temporarily unavailable (e.g. cold-start / pool
            exhaustion); retryable, honor the `Retry-After` header."
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: |
        API key authentication. Get your API key from the WAVE Developer Portal.
    bearerWithScopes:
      type: http
      scheme: bearer
      description: Bearer token with scope grants. The token's scopes determine access
        (see scopes_supported).
      x-scopes:
        clips:read: Read clips and clip metadata
        clips:write: Create and modify clips
        voice:read: Read voice generation results
        voice:write: Generate voice audio
        captions:read: Read captions
        captions:write: Generate captions
        dispatch:read: Read dispatch routing info
        dispatch:write: Send dispatch requests
        usage:read: Read your own usage and meter data
        meter:read: Read your meter ledger
        insights:read: Read analytics insights
        media:read: Read media assets
        media:write: Upload and modify media
  parameters:
    RenderJobIdParam:
      name: jobId
      in: path
      required: true
      description: The render job id returned when the render was started asynchronously.
      schema:
        type: string
      example: 9f2c1a7e-4b3d-4c8a-9e21-6f0d5b8a1c34
    MoqNamespaceParam:
      name: ns
      in: path
      required: true
      description: MoQ namespace. Lowercase alphanumeric and dashes, 1–64 characters.
        The same value is bound into the minted token's claims and re-checked by
        the relay against the session it opens.
      schema:
        type: string
        pattern: ^[a-z0-9-]{1,64}$
        minLength: 1
        maxLength: 64
      example: demo-ns
    MoqTrackParam:
      name: track
      in: path
      required: true
      description: MoQ track name within the namespace. Lowercase alphanumeric and
        dashes, 1–64 characters.
      schema:
        type: string
        pattern: ^[a-z0-9-]{1,64}$
        minLength: 1
        maxLength: 64
      example: cam-1
    PageParam:
      name: page
      in: query
      schema:
        type: integer
        minimum: 1
        default: 1
    PerPageParam:
      name: perPage
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    StreamIdParam:
      name: streamId
      in: path
      required: true
      schema:
        type: string
    ProductionIdParam:
      name: productionId
      in: path
      required: true
      schema:
        type: string
    CameraIdParam:
      name: cameraId
      in: path
      required: true
      schema:
        type: string
    AnalyticsFromParam:
      name: from
      in: query
      description: Range start (ISO 8601 timestamp). Defaults to 30 days before `to`.
      schema:
        type: string
        format: date-time
    AnalyticsToParam:
      name: to
      in: query
      description: Range end (ISO 8601 timestamp). Defaults to now.
      schema:
        type: string
        format: date-time
  responses:
    ValidationError:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    NotFoundError:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    RateLimitError:
      description: Rate limit exceeded
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Unauthorized:
      description: Authentication required, or the API key / token is invalid or expired.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Forbidden:
      description: >
        The key is valid but lacks the scope or entitlement for this operation
        (e.g. SCOPE_OVERREACH, quota tier exhausted).
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    PaymentRequired:
      description: >
        Payment required — the gateway answers with an x402 challenge instead of
        serving the request. **This response does NOT use the `Error`
        envelope.** Its `error` member is a plain string (`"payment required"`);
        the normalized WAVE error object is nested under `error_detail`.
        Complete the challenge in `accepts[0]` and retry with the `x-payment`
        header. Observed on `api.wave.online` 2026-07-25: a request with no API
        key AND a request with an unrecognized API key both receive this 402
        (not a 401) on the MoQ mint routes, so a client must treat 402 as the
        ordinary "not yet authorized to pay-per-use" outcome.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/X402PaymentRequired"
    MoqJoinUnconfigured:
      description: >
        `MOQ_JOIN_UNCONFIGURED` — the mint is fail-closed and the signing secret
        is not provisioned in this environment. The gateway will never mint an
        unsigned or empty-key token. Not retryable by the caller; it clears when
        an operator provisions the secret.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    UpstreamError:
      description: >
        An upstream capability provider (e.g. the speech engine) failed. The
        gateway interprets the failure and returns this normalized WAVE error
        instead of the raw upstream response, so the caller always sees a stable
        shape it can act on.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
  schemas:
    ComposeProposalCreate:
      type: object
      description: POST /v1/compose request body. Validated by parseComposeRequest
        (compose-route.ts).
      required:
        - intent
      properties:
        intent:
          type: string
          minLength: 1
          maxLength: 280
          description: What the caller wants composed, in plain language. Sanitized and
            capped server side.
        budgetUsd:
          type: number
          minimum: 0
          description: Optional ceiling in USD. A proposal whose minimum total exceeds it
            is refused at run time.
        flowId:
          type: string
          pattern: ^flw_[A-Za-z0-9_-]{4,64}$
          description: Optional id of an existing flow this proposal belongs to.
        context:
          type: object
          description: "Optional retrieval hints. Ordering only: nothing here is rendered,
            logged or sent to a model."
          properties:
            referer:
              type: string
              maxLength: 200
    ComposeProposal:
      type: object
      description: "A composed PLAN. `executes` is always false: a proposal never
        runs, POST /v1/compose/run does."
      required:
        - id
        - intent
        - why
        - stages
        - productIds
        - tools
        - scopes
        - priceRows
        - callShape
        - candidates
        - retrieval
        - next
        - typing
        - runnable
        - notRunnableReason
        - executes
        - grounding
        - groundedAt
        - manifestHash
        - engine
        - flowId
      properties:
        id:
          type: string
          pattern: ^prp_[A-Za-z0-9_-]+$
          description: Proposal id. Re-readable via GET /v1/compose/proposals/{proposalId}.
        intent:
          type: string
          description: The sanitized intent this plan was composed from.
        why:
          type: string
          minLength: 1
          description: One governed sentence about the proposal as a whole (#1682). For a
            grounded chain it names the stages in composition order; for an
            intent WAVE could not build, it says exactly that. Always present,
            never empty.
        stages:
          type: array
          items:
            type: object
          description: The ordered stages of the plan, one per product call.
        productIds:
          type: array
          items:
            type: string
          description: The product ids the stages name, in composition order.
        tools:
          type: array
          items:
            type: string
          description: The MCP tool names the plan would call.
        scopes:
          type: array
          items:
            type: object
          description: Every scope the plan needs, each with whether the caller can be
            granted it.
        priceRows:
          type: array
          items:
            type: object
          description: One price row per stage. An unquoted row carries the literal 'quote
            at call time'.
        callShape:
          type: object
          description: "How to call the plan: the surface, the path and the body shape."
        candidates:
          type: array
          description: "The shelf (#1672): every component retrieval connected to this
            intent, best scoring entry per group."
          items:
            $ref: "#/components/schemas/ComposeCandidate"
        retrieval:
          $ref: "#/components/schemas/ComposeRetrievalInfo"
        next:
          type: array
          items:
            type: string
          description: The next actions a caller can take with this proposal.
        typing:
          type: array
          items:
            type: object
          description: One row per stage edge stating whether stage N may follow stage N-1
            AS DECLARED, and citing what was read.
        runnable:
          type: boolean
          description: "True only when every typing[] edge is declared. When false the
            chain is not offered as runnable: priceRows are per-unit list
            prices, never a run quote, and /v1/compose/run refuses."
        notRunnableReason:
          type: string
          nullable: true
          description: Null when runnable; otherwise the first undeclared edge's missing
            declaration.
        executes:
          type: boolean
          const: false
          description: Always false. A proposal is a plan, never an execution.
        grounding:
          type: string
          enum:
            - live
            - snapshot
          description: Whether the index this plan was composed against was read live.
        groundedAt:
          type: string
          format: date-time
        manifestHash:
          type: string
          description: Digest of the product manifest the plan was composed against. A run
            refuses on a stale hash.
        engine:
          type: object
          description: "Which composer engine produced the plan: `route`
            (dispatch|deterministic-fallback), `promptHash`, `model` (null until
            a sourced catalog exists). When `route` is deterministic-fallback,
            carries an additional `fallback: { reason, rungs[] }` naming WHY
            (e.g. a missing provider key, an upstream 402/4xx/5xx, a timeout, a
            schema refusal, or no products at all) and which provider rungs were
            tried, in order — never a secret or a raw upstream body. Omitted
            entirely when `route` is dispatch."
        flowId:
          type: string
          nullable: true
    ComposeCandidate:
      type: object
      description: "One retrieved shelf entry: the best scoring knowledge entry for a
        /v1 group against this intent (#1672)."
      required:
        - product
        - group
        - score
        - source
      properties:
        product:
          type: string
          nullable: true
          description: The product id when the live enforcement index carries a product
            row for this group, else null.
        group:
          type: string
          description: The /v1 group the retrieved entry belongs to. This is the diversity
            unit of the top k.
        score:
          type: number
          minimum: 0
          maximum: 1
          description: Cosine similarity to the intent, 0..1, rounded to 4 dp.
        source:
          type: object
          description: The PUBLIC document and field the winning entry for this group was
            read from.
          required:
            - url
            - field
          properties:
            url:
              type: string
              format: uri
            field:
              type: string
    ComposeRetrievalInfo:
      type: object
      description: "How the shelf was retrieved: k, which embedder produced the
        numbers, and which corpus answered (#1672)."
      required:
        - k
        - embedder
        - indexManifestHash
        - builtAt
      properties:
        k:
          type: integer
          minimum: 0
        embedder:
          type: string
          description: The embedder id. A swap changes this string on the wire, so a score
            is never comparable across embedders by accident.
        indexManifestHash:
          type: string
          description: The enforcement manifestHash the knowledge index was built from.
            Equals the proposal manifestHash when fresh.
        builtAt:
          type: string
          format: date-time
    ComposeRunInput:
      type: object
      description: The caller's own input into stage 0. EXACTLY ONE of `url` or
        `uploadId`. `url` is validated (https only, no userinfo credentials, no
        private or metadata host) and hashed. It is never dereferenced, echoed
        or logged.
      properties:
        url:
          type: string
          format: uri
          maxLength: 2048
          description: An https URL naming a public host.
        uploadId:
          type: string
          pattern: ^[A-Za-z0-9_-]{8,128}$
      oneOf:
        - required:
            - url
        - required:
            - uploadId
    ComposeUploadCreate:
      type: object
      description: POST /v1/uploads body.
      required:
        - contentType
        - sizeBytes
      properties:
        contentType:
          type: string
          enum:
            - video/mp4
            - video/quicktime
            - audio/mp4
            - audio/x-m4a
            - audio/wav
            - audio/x-wav
        sizeBytes:
          type: integer
          minimum: 1
          maximum: 524288000
    ComposeUpload:
      type: object
      description: A presigned R2 PUT. Send the bytes with exactly `upload.method`,
        `upload.url` and `upload.headers` before `expiresAt`, then resolve
        `{uploadId}`.
      required:
        - uploadId
        - upload
        - expiresAt
      properties:
        uploadId:
          type: string
          pattern: ^upl_[a-z2-7]{24}$
        upload:
          type: object
          required:
            - method
            - url
            - headers
          properties:
            method:
              type: string
              enum:
                - PUT
            url:
              type: string
              format: uri
            headers:
              type: object
              additionalProperties:
                type: string
        expiresAt:
          type: string
          format: date-time
        maxBytes:
          type: integer
        maxDurationSec:
          type: integer
        retention:
          type: string
    ComposeIngestResolveCreate:
      type: object
      description: "POST /v1/compose/ingest/resolve body: the same input a run takes."
      required:
        - input
      properties:
        input:
          $ref: "#/components/schemas/ComposeRunInput"
    ComposeResolvedSource:
      type: object
      description: "Stage -1 output: the stored, probed source every later stage
        consumes. An input, never an artifact: it has no download or export
        link."
      required:
        - sourceId
        - sourceType
        - durationSec
        - hasAudio
        - width
        - height
        - mime
        - resolvedFrom
      properties:
        sourceId:
          type: string
          pattern: ^src_[a-z2-7]{24}$
        sourceType:
          type: string
          enum:
            - video
            - audio
        durationSec:
          type: number
          minimum: 0
          maximum: 3600
        hasAudio:
          type: boolean
        width:
          type:
            - integer
            - "null"
          minimum: 0
        height:
          type:
            - integer
            - "null"
          minimum: 0
        mime:
          type: string
        resolvedFrom:
          type: string
          enum:
            - url
            - uploadId
    ComposeRunCreate:
      type: object
      description: POST /v1/compose/run request body. Validated by parseRunRequest
        (compose-run-lib.ts).
      required:
        - proposalId
        - input
      properties:
        proposalId:
          type: string
          pattern: ^prp_[A-Za-z0-9_-]+$
          description: A proposal the calling org owns.
        input:
          $ref: "#/components/schemas/ComposeRunInput"
        budgetUsd:
          type: number
          minimum: 0
          description: Ceiling in USD for this run. Exceeded means 402, not a partial run.
        idempotencyKey:
          type: string
          pattern: ^[A-Za-z0-9_.:-]{8,200}$
          description: Replay guard. The same key with a different input is a 409
            COMPOSE_RUN_CONFLICT, never a second run.
    ComposeRunReplay:
      type: object
      description: "The 200 a REPLAYED run returns: the prior run's outcome, not a new
        execution."
      required:
        - runId
        - proposalId
        - status
        - code
        - replayed
        - createdAt
      properties:
        runId:
          type: string
        proposalId:
          type: string
        status:
          type: string
          enum:
            - refused
            - running
            - completed
            - failed
        code:
          type: string
          nullable: true
        replayed:
          type: boolean
          const: true
        createdAt:
          type: string
          format: date-time
    Error:
      type: object
      description: >
        WAVE-normalized error envelope returned by the api.wave.online gateway.
        Upstream provider, auth, and quota failures are *interpreted* into this
        single shape — raw upstream errors (stack traces, vendor SDK objects)
        are never leaked to the caller. `error.code` is a stable
        machine-readable code (e.g. AUTH_REQUIRED, SCOPE_OVERREACH,
        RATE_LIMIT_EXCEEDED, UPSTREAM_ERROR); `error.message` is human-readable.
      required:
        - error
      properties:
        error:
          $ref: "#/components/schemas/ErrorBody"
    ErrorBody:
      type: object
      description: >
        The normalized WAVE error object itself — the value of the `Error`
        envelope's `error` member. Referenced directly by bodies that carry the
        error object under a different key (the 402 x402 challenge nests it
        under `error_detail` without the envelope wrapper).
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Stable machine-readable error code.
        message:
          type: string
          description: Human-readable explanation, safe to surface to end users.
        details:
          type: object
          additionalProperties: true
          description: >
            Optional structured context (e.g. failing field, retry limit,
            requested scopes) — never raw upstream payloads.
        suggestions:
          type: array
          description: >
            Actionable next steps, ordered most→least likely to resolve the
            error. Written to be acted on by a human OR an agent.
          items:
            type: string
        did_you_mean:
          type: array
          description: >
            Closest valid alternatives when the caller likely made a typo or
            wrong choice (e.g. an unknown scope, product, or route).
          items:
            type: string
        doc_url:
          type: string
          format: uri
          description: Documentation link for this error.
    Pagination:
      type: object
      properties:
        page:
          type: integer
        perPage:
          type: integer
        total:
          type: integer
        totalPages:
          type: integer
    PaginatedResponse:
      type: object
      properties:
        data:
          type: array
          items: {}
        pagination:
          $ref: "#/components/schemas/Pagination"
    JobStatus:
      type: string
      enum:
        - pending
        - processing
        - completed
        - failed
        - cancelled
    Attestation:
      type: object
      description: >
        WAVE Attestation envelope — a signed, verifiable record of exactly what
        a capability DID. This is NOT a financial receipt: customer payment
        receipts and invoices live in the billing domain (`Invoice`); an
        Attestation proves platform behaviour, not money owed. One shape, three
        instances: the Render Attestation, the Settlement Attestation (proof an
        x402 spend executed), and the Context Attestation. The bytes that are
        signed and verified are the *canonical* JSON of `attestation` (sorted
        keys, no whitespace), so any verifier reproduces exactly what the signer
        signed.
      required:
        - schema
        - attestation
        - alg
      properties:
        schema:
          type: string
          description: Attestation payload schema id + version (matches the payload's own
            `schema_version`).
          examples:
            - wave.context-attestation/v0
        attestation:
          type: object
          description: >
            The attested facts — one of the instance payload schemas (e.g.
            `#/components/schemas/ContextAttestation`).
          additionalProperties: true
        sig:
          type:
            - string
            - "null"
          description: >
            Detached signature over the canonical JSON of `attestation`, encoded
            per `alg`, or null when unsigned (`alg: none`).
        alg:
          type: string
          description: >
            Signature algorithm (e.g. `ed25519`). `none` means the attestation
            is honestly unsigned; a present signature is trusted ONLY when a
            verifier confirms it over the canonical body — a signature that
            cannot be checked is never trusted.
          examples:
            - ed25519
            - none
      allOf:
        - if:
            properties:
              alg:
                const: none
          then:
            properties:
              sig:
                type: "null"
          else:
            required:
              - sig
            properties:
              sig:
                type: string
    ContextAttestation:
      type: object
      description: >
        Proof of exactly what context a single model invocation was given — the
        Context Integrity instance of the WAVE Attestation standard. Travels as
        the `attestation` payload of an `Attestation` envelope (`schema:
        wave.context-attestation/v0`). The platform measures the window each
        model REALLY serves (not the advertised one) and either fits the prompt,
        routes up to a bigger window, or refuses — it never silently
        front-truncates.
      required:
        - model
        - served_window
        - effective_window
        - input_tokens
        - decision_kind
        - truncated
        - ts
        - schema_version
      properties:
        model:
          type: string
          description: Target model identifier.
        served_window:
          type: integer
          description: >
            The context window the model ACTUALLY served, as measured by the
            Fleet Probe — not the advertised window. Trusting the measured value
            over the advertised one is the guarantee this attestation makes.
        effective_window:
          type: integer
          description: >
            Window available for input after carving out reserved output
            headroom, chat-template overhead, and tool/MCP schema tokens.
        input_tokens:
          type: integer
          description: >
            Conservative estimate of the prompt's input tokens (chars/token
            margin biased to never under-count).
        decision_kind:
          type: string
          enum:
            - fit
            - route_up
            - refuse
          description: >
            The Truncation Guard's decision: `fit` (prompt fits), `route_up`
            (escalate to a bigger window), or `refuse` (loud — chunk or raise
            the window). Never silently truncates.
        truncated:
          type: boolean
          description: >
            True only if a downstream stage forced a truncation the guard would
            have refused. Normally false.
        ts:
          type: string
          format: date-time
          description: ISO-8601 timestamp of the decision.
        schema_version:
          type: string
          description: Payload schema version (equals the envelope `schema`).
          examples:
            - wave.context-attestation/v0
    RenderAttestation:
      type: object
      description: >
        WAVE Render Attestation v1 — the subject payload carried inside an
        `Attestation` envelope for `kind: render`. Attests that a specific
        renderer produced a specific output from a specific scene. The
        content-addressed envelope ID is derived from the canonical
        serialization of these fields (see
        `attestation/ATTESTATION-STANDARD-v1.md`).
      required:
        - v
        - kind
        - renderer
        - scene_sha256
        - output_sha256
        - format
        - bytes
      properties:
        v:
          type: string
          maxLength: 64
          description: Version string. Equals the outer envelope `v` field.
          examples:
            - wave.render-attestation/v1
        kind:
          type: string
          const: render
          description: Always `"render"` for this payload type.
        renderer:
          type: string
          description: >
            Renderer identifier in `name@version/runtime` format, e.g.
            `wave-video@0.3.0/kernel`. Used to identify which build produced the
            output.
        scene_sha256:
          type: string
          pattern: ^[0-9a-f]{64}$
          description: SHA-256 hex of the canonical scene input (the Brief or Scene IR).
        output_sha256:
          type: string
          pattern: ^[0-9a-f]{64}$
          description: SHA-256 hex of the rendered output bytes.
        format:
          type: string
          enum:
            - mp4
            - alpha
          description: Output container/codec family.
        bytes:
          type: integer
          minimum: 0
          description: Byte length of the rendered output.
    WaveAttestation:
      description: >
        Top-level wire envelope for any WAVE Attestation v1. Carried as the
        `wave.attestation` OTLP span attribute (JSON string) and stored in the
        `observability.attestation` table. The `id` is content-addressed:
        `sha256hex(canonicalJson(attestationSubject(envelope)))`. Invariant:
        `alg === "none"` ⟺ `sig === null`. See
        `attestation/ATTESTATION-STANDARD-v1.md` for the normative
        specification.
      type: object
      required:
        - id
        - kind
        - v
        - subject
        - alg
      properties:
        id:
          type: string
          pattern: ^[0-9a-f]{64}$
          description: >
            Content-addressed ID:
            `sha256hex(canonicalJson(attestationSubject(envelope)))`. Stable
            across cache replays; upserts are idempotent by this key.
        kind:
          type: string
          enum:
            - render
            - context
            - settlement
          description: Attestation kind.
        v:
          type: string
          maxLength: 64
          description: Version string, e.g. `wave.render-attestation/v1`.
        subject:
          type: object
          description: "Kind-specific payload. For `kind: render`, see `RenderAttestation`."
          additionalProperties: true
        alg:
          type: string
          maxLength: 32
          description: Signature algorithm. `"ed25519"` or `"none"`.
          examples:
            - ed25519
            - none
        sig:
          type:
            - string
            - "null"
          maxLength: 2048
          description: >
            Base64url-encoded Ed25519 signature over `canonicalJson(subject)`
            bytes. `null` when `alg` is `"none"`.
        created:
          oneOf:
            - type: integer
              description: Unix seconds.
            - type: string
              maxLength: 40
              description: ISO 8601 timestamp or unix seconds as string.
          description: When the attestation was minted.
      allOf:
        - if:
            properties:
              alg:
                const: none
          then:
            properties:
              sig:
                type: "null"
          else:
            required:
              - sig
            properties:
              sig:
                type: string
    Clip:
      type: object
      properties:
        id:
          type: string
        videoId:
          type: string
        startTime:
          type: number
        endTime:
          type: number
        duration:
          type: number
        title:
          type: string
        description:
          type: string
        score:
          type: number
        category:
          type: string
        thumbnailUrl:
          type: string
          format: uri
        previewUrl:
          type: string
          format: uri
        status:
          $ref: "#/components/schemas/JobStatus"
        organizationId:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ClipCreate:
      type: object
      description: The real live-route request contract. `videoId` is NOT accepted —
        the live route requires `source` (a recording id) instead.
      required:
        - source
        - in
      properties:
        source:
          type: string
          minLength: 1
          description: A recording id the gateway resolves to an org-scoped source URL.
        sourceType:
          type: string
          enum:
            - recording_id
          default: recording_id
          description: Only `recording_id` is accepted — a raw storage key (`r2_key`) is
            rejected outright (cross-tenant read protection).
        visibility:
          type: string
          enum:
            - public
            - private
          default: private
        in:
          type: string
          pattern: ^\d+(\.\d+)?(s|m)$
          description: Clip start offset, a time string like "5s" or "2m" (0-10m).
        out:
          type: string
          pattern: ^\d+(\.\d+)?(s|m)$
          description: Clip end offset, a time string. Provide `out` or `duration`, not
            both.
        duration:
          type: string
          pattern: ^\d+(\.\d+)?(s|m)$
          description: Output clip length, a time string (1s-60s). Provide `out` or
            `duration`, not both.
        width:
          type: integer
          minimum: 10
          maximum: 2000
        height:
          type: integer
          minimum: 10
          maximum: 2000
        fit:
          type: string
          enum:
            - contain
            - cover
            - scale-down
          default: contain
        formats:
          type: array
          default:
            - mp4
          items:
            type: string
            enum:
              - mp4
              - spritesheet
              - m4a
              - frame
          description: "`frame` produces a single JPEG still at `in` and needs neither
            `out` nor `duration`."
        quality:
          type: string
          enum:
            - 720p
            - 1080p
            - 4k
          default: 720p
        spritesheetFrames:
          type: integer
          minimum: 1
          maximum: 120
          default: 30
    ClipUpdate:
      type: object
      properties:
        title:
          type: string
        description:
          type: string
        startTime:
          type: number
        endTime:
          type: number
    ClipDetectRequest:
      type: object
      required:
        - videoId
      properties:
        videoId:
          type: string
        minDuration:
          type: number
          default: 5
        maxDuration:
          type: number
          default: 60
        categories:
          type: array
          items:
            type: string
        sensitivity:
          type: number
          minimum: 0
          maximum: 1
          default: 0.5
        maxClips:
          type: integer
    DetectionJob:
      type: object
      properties:
        id:
          type: string
        status:
          $ref: "#/components/schemas/JobStatus"
        progress:
          type: integer
        createdAt:
          type: string
          format: date-time
    ClipCreateResponse:
      type: object
      description: The real POST /clips 201 response.
      properties:
        ok:
          type: boolean
          const: true
        clipId:
          type: string
        org:
          type: string
          description: The gateway-resolved owning organization.
        visibility:
          type: string
          enum:
            - public
            - private
        source:
          type: string
        in:
          type: string
        duration:
          type: string
          description: Output clip duration, a time string like "12s".
        quality:
          type: string
          enum:
            - 720p
            - 1080p
            - 4k
        assets:
          type: array
          items:
            type: object
            properties:
              kind:
                type: string
                enum:
                  - clip
                  - spritesheet
                  - audio
                  - frame
              key:
                type: string
                description: "Org-prefixed storage key: ‹org›/{clips|public}/‹clipId›/…"
              contentType:
                type: string
              url:
                type:
                  - string
                  - "null"
                description: Delivery URL — plain for public, HMAC-signed for private. null when
                  delivery isn't configured.
    ClipError:
      type: object
      description: The clip-creation route's own error envelope for POST /clips —
        distinct from the gateway-normalized `Error` schema used elsewhere in
        this document.
      required:
        - ok
        - error
      properties:
        ok:
          type: boolean
          const: false
        error:
          type: string
        detail:
          description: Optional structured detail. Absent or null on most errors.
    Stream:
      type: object
      description: A live stream. Never carries the Cloudflare stream key or any other
        ingest secret — only the public ingest/playback URLs.
      properties:
        id:
          type: string
        title:
          type: string
        description:
          type:
            - string
            - "null"
        protocol:
          type: string
          enum:
            - webrtc
            - srt
            - rtmp
            - auto
        status:
          type: string
          enum:
            - idle
            - live
            - ended
        privacy:
          type: string
          enum:
            - public
            - private
        viewer_count:
          type: integer
        peak_viewer_count:
          type: integer
        ingest_url:
          type:
            - string
            - "null"
        playback_url:
          type:
            - string
            - "null"
        cloudflare_live_input_uid:
          type:
            - string
            - "null"
        metadata:
          type: object
          additionalProperties: true
        started_at:
          type:
            - string
            - "null"
          format: date-time
        ended_at:
          type:
            - string
            - "null"
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    CreateStreamRequest:
      type: object
      required:
        - title
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 200
        description:
          type: string
          maxLength: 5000
        protocol:
          type: string
          enum:
            - webrtc
            - srt
            - rtmp
            - auto
          default: auto
        recording:
          type: object
          properties:
            enabled:
              type: boolean
        privacy:
          type: string
          enum:
            - public
            - private
          default: public
        metadata:
          type: object
          additionalProperties: true
    Highlight:
      type: object
      properties:
        id:
          type: string
        stream_id:
          type: string
        organization_id:
          type: string
        title:
          type:
            - string
            - "null"
        settings:
          type: object
          additionalProperties: true
          description: "{label, timestamp, confidence, source}"
        created_at:
          type: string
          format: date-time
    ModerateRequest:
      type: object
      required:
        - content
        - contentType
      properties:
        content:
          type: string
          minLength: 1
          maxLength: 50000
        contentType:
          type: string
          enum:
            - text
            - title
            - description
            - comment
            - chat
            - username
            - bio
        context:
          type: object
          properties:
            streamId:
              type: string
            userId:
              type: string
            previousContent:
              type: array
              items:
                type: string
          description: streamId attributes the moderated content to a stream (e.g. a chat
            message).
        options:
          type: object
          properties:
            returnDetails:
              type: boolean
              default: true
            categories:
              type: array
              items:
                type: string
              description: Subset of harassment, hate_speech, violence, sexual_content, spam,
                misinformation, self_harm, illegal_activity,
                personal_information, copyright.
            customRules:
              type: array
              items:
                type: object
                required:
                  - name
                  - pattern
                  - action
                properties:
                  name:
                    type: string
                  pattern:
                    type: string
                    description: A regular expression evaluated against content.
                  action:
                    type: string
                    enum:
                      - flag
                      - block
    ModerateResponse:
      type: object
      properties:
        allowed:
          type: boolean
        action:
          type: string
          enum:
            - allow
            - flag
            - block
            - review
        violations:
          type: array
          items:
            type: object
            properties:
              category:
                type: string
              severity:
                type: string
                enum:
                  - low
                  - medium
                  - high
                  - critical
              confidence:
                type: number
              description:
                type: string
              matchedText:
                type: string
              rule:
                type: string
        confidence:
          type: number
        reasoning:
          type: string
        suggestedAction:
          type: string
        metadata:
          type: object
          properties:
            contentId:
              type: string
            processingTimeMs:
              type: integer
            model:
              type: string
            categoriesChecked:
              type: array
              items:
                type: string
    Production:
      type: object
      properties:
        id:
          type: string
        organization_id:
          type: string
        user_id:
          type:
            - string
            - "null"
        title:
          type: string
        description:
          type:
            - string
            - "null"
        status:
          type: string
          enum:
            - setup
            - rehearsal
            - live
            - paused
            - ended
        layout:
          type: string
          enum:
            - single
            - split
            - pip
            - grid
            - custom
        stream_ids:
          type: array
          items:
            type: string
        record:
          type: boolean
        program_camera_index:
          type:
            - integer
            - "null"
        preview_camera_index:
          type:
            - integer
            - "null"
        last_transition:
          type:
            - string
            - "null"
        overlays:
          type: object
          additionalProperties: true
        settings:
          type: object
          additionalProperties: true
        started_at:
          type:
            - string
            - "null"
          format: date-time
        ended_at:
          type:
            - string
            - "null"
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    CreateProductionRequest:
      type: object
      required:
        - title
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 255
        description:
          type: string
          maxLength: 2000
        layout:
          type: string
          enum:
            - single
            - split
            - pip
            - grid
            - custom
          default: single
        stream_ids:
          type: array
          items:
            type: string
        record:
          type: boolean
          default: false
    SwitchCameraRequest:
      type: object
      required:
        - cameraIndex
        - bus
      properties:
        cameraIndex:
          type: integer
          minimum: 0
          maximum: 15
        bus:
          type: string
          enum:
            - program
            - preview
        transition:
          type: string
          enum:
            - cut
            - dissolve
            - wipe
            - fade
          default: cut
    Camera:
      type: object
      properties:
        id:
          type: string
        organization_id:
          type: string
        name:
          type: string
        manufacturer:
          type: string
          enum:
            - blackmagic
            - sony
            - canon
            - ptzoptics
            - other
        control_protocol:
          type: string
          enum:
            - bmd_rest
            - visca_ip
            - visca_serial
            - canon_xc
            - onvif
        address:
          type:
            - string
            - "null"
          description: IPv4 address the camera was registered with.
        status:
          type: string
          enum:
            - offline
            - online
            - discovering
            - error
        presets:
          type: array
          items:
            type: object
            additionalProperties: true
        metadata:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    RegisterCameraRequest:
      type: object
      required:
        - name
        - manufacturer
        - ipAddress
        - controlProtocol
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        manufacturer:
          type: string
          enum:
            - blackmagic
            - sony
            - canon
            - ptzoptics
            - other
        model:
          type: string
        ipAddress:
          type: string
          format: ipv4
        controlProtocol:
          type: string
          enum:
            - bmd_rest
            - visca_ip
            - visca_serial
            - canon_xc
            - onvif
    ControlCameraRequest:
      description: Discriminated union on `type`. Supply only the fields the chosen
        variant needs.
      oneOf:
        - type: object
          required:
            - type
            - value
          properties:
            type:
              const: set_iris
            value:
              type: number
        - type: object
          required:
            - type
            - value
          properties:
            type:
              const: set_focus
            value:
              type: number
        - type: object
          required:
            - type
            - value
          properties:
            type:
              const: set_zoom
            value:
              type: number
        - type: object
          required:
            - type
            - temperature
            - tint
          properties:
            type:
              const: set_white_balance
            temperature:
              type: number
            tint:
              type: number
        - type: object
          required:
            - type
            - value
          properties:
            type:
              const: set_gain
            value:
              type: number
        - type: object
          required:
            - type
            - angle
          properties:
            type:
              const: set_shutter
            angle:
              type: number
        - type: object
          required:
            - type
          properties:
            type:
              const: start_recording
        - type: object
          required:
            - type
          properties:
            type:
              const: stop_recording
        - type: object
          required:
            - type
          properties:
            type:
              const: start_prerecord
        - type: object
          required:
            - type
          properties:
            type:
              const: autofocus_trigger
        - type: object
          required:
            - type
            - channel
            - level
          properties:
            type:
              const: set_audio_level
            channel:
              type: number
            level:
              type: number
        - type: object
          required:
            - type
            - presetId
          properties:
            type:
              const: recall_preset
            presetId:
              type: string
              format: uuid
        - type: object
          required:
            - type
            - name
            - slot
          properties:
            type:
              const: save_preset
            name:
              type: string
              minLength: 1
            slot:
              type: integer
              minimum: 1
              maximum: 20
      discriminator:
        propertyName: type
    DateRange:
      type: object
      properties:
        from:
          type: string
        to:
          type: string
    BillingAccount:
      type: object
      description: "The caller-org's billing status. `billingAccount: null` and `plan:
        \"free\"` mean the org has no Stripe customer yet."
      properties:
        organizationId:
          type: string
        billingAccount:
          type:
            - object
            - "null"
          properties:
            customerId:
              type: string
            email:
              type:
                - string
                - "null"
            paymentMethod:
              type:
                - object
                - "null"
              properties:
                brand:
                  type: string
                last4:
                  type: string
                expMonth:
                  type: integer
                expYear:
                  type: integer
        plan:
          type: string
          description: '"free" when the org has no billing account.'
        subscription:
          type:
            - object
            - "null"
          properties:
            id:
              type: string
            status:
              type: string
            currentPeriodEnd:
              type: integer
              description: Unix seconds.
            plan:
              type:
                - object
                - "null"
              properties:
                priceId:
                  type: string
                unitAmount:
                  type:
                    - integer
                    - "null"
                currency:
                  type: string
                interval:
                  type:
                    - string
                    - "null"
    BillingUsageResponse:
      type: object
      properties:
        organizationId:
          type: string
        period:
          $ref: "#/components/schemas/DateRange"
        usage:
          type: array
          items:
            type: object
            properties:
              dimension:
                type: string
              unit:
                type: string
              quantity:
                type: number
              billedQuantity:
                type: number
        total:
          type: number
    UsageResponse:
      type: object
      description: Raw per-dimension usage from the underlying meter ledger.
      properties:
        org:
          type: string
        range:
          type: object
          properties:
            from:
              type: string
            to:
              type: string
            days:
              type: integer
        totals:
          type: object
          additionalProperties:
            type: number
          description: Meter dimension → summed quantity (e.g. wave_braid_minutes,
            transcription_seconds, duration_ms:srt). The dimension set is
            append-only and not enumerated here.
    Voice:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        previewUrl:
          type: string
          format: uri
        category:
          type: string
        labels:
          type: object
          additionalProperties:
            type: string
    VoiceGeneration:
      type: object
      properties:
        id:
          type: string
        voiceId:
          type: string
        text:
          type: string
        status:
          $ref: "#/components/schemas/JobStatus"
        audioUrl:
          type: string
          format: uri
        alignment:
          $ref: "#/components/schemas/VoiceAlignment"
        duration:
          type: number
        characterCount:
          type: integer
        model:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    VoiceAlignment:
      type: object
      description: >
        Character-level timing for the generated audio, present only when the
        request set `timestamps: true`. A direct passthrough of the engine's
        alignment, so clients can render karaoke highlighting and derive caption
        cues. The three arrays are parallel (same length, always present
        together). Property names are snake_case because this is a verbatim
        passthrough of the speech engine's alignment, which downstream
        caption/karaoke consumers parse by these exact keys.
      required:
        - characters
        - character_start_times_seconds
        - character_end_times_seconds
      properties:
        characters:
          type: array
          items:
            type: string
        character_start_times_seconds:
          type: array
          items:
            type: number
        character_end_times_seconds:
          type: array
          items:
            type: number
    VoiceSynthesisInline:
      type: object
      description: >
        Synchronous voice synthesis result returned inline in a single
        round-trip. Used when `timestamps: true`, so the caller receives audio
        and character-level `alignment` together with no polling — the shape the
        blog karaoke/caption pipeline consumes. When timestamps are not
        requested the gateway may instead return raw audio bytes (audio/mpeg) or
        an async VoiceGeneration job.
      required:
        - audio_base64
      properties:
        audio_base64:
          type: string
          format: byte
          description: Base64-encoded audio payload (container/codec per `outputFormat`).
        alignment:
          $ref: "#/components/schemas/VoiceAlignment"
        format:
          type: string
          description: Audio container/codec of the decoded bytes (e.g. mp3_44100_128).
    VoiceGenerateRequest:
      type: object
      required:
        - voiceId
        - text
      properties:
        voiceId:
          type: string
        text:
          type: string
        stability:
          type: number
          minimum: 0
          maximum: 1
          default: 0.5
        similarityBoost:
          type: number
          minimum: 0
          maximum: 1
          default: 0.75
        style:
          type: number
          minimum: 0
          maximum: 1
          default: 0
        model:
          type: string
          default: eleven_multilingual_v2
        outputFormat:
          type: string
          default: mp3_44100_128
        timestamps:
          type: boolean
          default: false
          description: >
            When true, the resulting VoiceGeneration includes character-level
            `alignment` (start/end times) so clients can render karaoke
            highlighting and derive caption cues. Backed by the engine's
            with-timestamps mode.
    VoiceCloneRequest:
      type: object
      required:
        - name
        - audioFiles
      properties:
        name:
          type: string
        audioFiles:
          type: array
          items:
            type: string
            format: uri
          minItems: 1
          maxItems: 25
        description:
          type: string
        labels:
          type: object
          additionalProperties:
            type: string
    CaptionJob:
      type: object
      properties:
        id:
          type: string
        videoId:
          type: string
        sourceLanguage:
          type: string
        targetLanguages:
          type: array
          items:
            type: string
        status:
          $ref: "#/components/schemas/JobStatus"
        progress:
          type: integer
        outputs:
          type: object
          additionalProperties:
            type: string
        errorMessage:
          type: string
        organizationId:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    CaptionJobCreate:
      type: object
      required:
        - videoId
      properties:
        videoId:
          type: string
        sourceLanguage:
          type: string
          default: en
        targetLanguages:
          type: array
          items:
            type: string
        style:
          type: string
          default: default
        speakerLabels:
          type: boolean
          default: false
    Chapter:
      type: object
      properties:
        id:
          type: string
        videoId:
          type: string
        title:
          type: string
        description:
          type: string
        startTime:
          type: number
        endTime:
          type: number
        thumbnailUrl:
          type: string
          format: uri
    ChapterCreate:
      type: object
      required:
        - title
        - startTime
        - endTime
      properties:
        title:
          type: string
        description:
          type: string
        startTime:
          type: number
        endTime:
          type: number
    ChapterDetectRequest:
      type: object
      properties:
        minDuration:
          type: number
          default: 30
        maxChapters:
          type: integer
        includeDescriptions:
          type: boolean
          default: true
        includeThumbnails:
          type: boolean
          default: true
    EditorProject:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        status:
          type: string
        duration:
          type: number
        resolution:
          type: string
        frameRate:
          type: number
        thumbnailUrl:
          type: string
          format: uri
        exportUrl:
          type: string
          format: uri
        organizationId:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    EditorProjectCreate:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        description:
          type: string
        resolution:
          type: string
          default: 1920x1080
        frameRate:
          type: number
          default: 30
        aspectRatio:
          type: string
          default: 16:9
    EditorProjectUpdate:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
    ExportRequest:
      type: object
      properties:
        format:
          type: string
          enum:
            - mp4
            - webm
            - mov
          default: mp4
        resolution:
          type: string
        quality:
          type: string
          enum:
            - low
            - medium
            - high
            - ultra
          default: high
    ExportJob:
      type: object
      properties:
        id:
          type: string
        status:
          $ref: "#/components/schemas/JobStatus"
        progress:
          type: integer
        outputUrl:
          type: string
          format: uri
    PhoneLine:
      type: object
      properties:
        id:
          type: string
        number:
          type: string
        name:
          type: string
        status:
          type: string
        capabilities:
          type: array
          items:
            type: string
        monthlyCost:
          type: number
        organizationId:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    PhoneLineProvision:
      type: object
      properties:
        areaCode:
          type: string
        country:
          type: string
          default: US
        capabilities:
          type: array
          items:
            type: string
            enum:
              - voice
              - sms
              - mms
              - fax
        name:
          type: string
    Call:
      type: object
      properties:
        id:
          type: string
        lineId:
          type: string
        direction:
          type: string
          enum:
            - inbound
            - outbound
        fromNumber:
          type: string
        toNumber:
          type: string
        status:
          type: string
        duration:
          type: integer
        recordingUrl:
          type: string
          format: uri
        transcript:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    CallCreate:
      type: object
      required:
        - fromLineId
        - toNumber
      properties:
        fromLineId:
          type: string
        toNumber:
          type: string
        record:
          type: boolean
          default: false
        transcribe:
          type: boolean
          default: false
        webhookUrl:
          type: string
          format: uri
    CollabRoom:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
          enum:
            - video
            - audio
            - whiteboard
            - screen
        status:
          type: string
          enum:
            - waiting
            - active
            - ended
        maxParticipants:
          type: integer
        currentParticipants:
          type: integer
        scheduledStart:
          type: string
          format: date-time
        joinUrl:
          type: string
          format: uri
        organizationId:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    CollabRoomCreate:
      type: object
      required:
        - name
        - type
      properties:
        name:
          type: string
        type:
          type: string
          enum:
            - video
            - audio
            - whiteboard
            - screen
        maxParticipants:
          type: integer
          default: 10
        scheduledStart:
          type: string
          format: date-time
        settings:
          type: object
    PodcastShow:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        coverUrl:
          type: string
          format: uri
        rssUrl:
          type: string
          format: uri
        category:
          type: string
        language:
          type: string
        explicit:
          type: boolean
        episodeCount:
          type: integer
        organizationId:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    PodcastShowCreate:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        description:
          type: string
        category:
          type: string
        language:
          type: string
          default: en
        explicit:
          type: boolean
          default: false
        coverUrl:
          type: string
          format: uri
    PodcastEpisode:
      type: object
      properties:
        id:
          type: string
        showId:
          type: string
        title:
          type: string
        description:
          type: string
        audioUrl:
          type: string
          format: uri
        duration:
          type: number
        episodeNumber:
          type: integer
        seasonNumber:
          type: integer
        publishedAt:
          type: string
          format: date-time
        status:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    PodcastEpisodeCreate:
      type: object
      required:
        - title
        - audioUrl
      properties:
        title:
          type: string
        description:
          type: string
        audioUrl:
          type: string
          format: uri
        episodeNumber:
          type: integer
        seasonNumber:
          type: integer
        publishedAt:
          type: string
          format: date-time
    Transcription:
      type: object
      properties:
        id:
          type: string
        sourceId:
          type: string
        sourceType:
          type: string
          enum:
            - video
            - audio
        status:
          $ref: "#/components/schemas/JobStatus"
        language:
          type: string
        text:
          type: string
        duration:
          type: number
        wordCount:
          type: integer
        confidence:
          type: number
        organizationId:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    TranscriptionCreate:
      type: object
      required:
        - sourceId
        - sourceType
      properties:
        sourceId:
          type: string
        sourceType:
          type: string
          enum:
            - video
            - audio
        language:
          type: string
        speakerLabels:
          type: boolean
          default: false
        wordTimestamps:
          type: boolean
          default: false
        punctuation:
          type: boolean
          default: true
        model:
          type: string
          default: default
    SentimentAnalysis:
      type: object
      properties:
        id:
          type: string
        sourceId:
          type: string
        sourceType:
          type: string
          enum:
            - video
            - audio
            - text
            - chat
        status:
          $ref: "#/components/schemas/JobStatus"
        overallSentiment:
          type: string
          enum:
            - positive
            - negative
            - neutral
            - mixed
        overallScore:
          type: number
        confidence:
          type: number
        summary:
          type: string
        organizationId:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    SentimentAnalysisCreate:
      type: object
      required:
        - sourceId
        - sourceType
      properties:
        sourceId:
          type: string
        sourceType:
          type: string
          enum:
            - video
            - audio
            - text
            - chat
        text:
          type: string
        includeEmotions:
          type: boolean
          default: false
        includeTopics:
          type: boolean
          default: false
        includeSummary:
          type: boolean
          default: false
        segmentAnalysis:
          type: boolean
          default: false
    EmotionBreakdown:
      type: object
      properties:
        joy:
          type: number
        sadness:
          type: number
        anger:
          type: number
        fear:
          type: number
        surprise:
          type: number
        disgust:
          type: number
        trust:
          type: number
        anticipation:
          type: number
    TopicSentiment:
      type: object
      properties:
        topic:
          type: string
        sentiment:
          type: string
          enum:
            - positive
            - negative
            - neutral
        score:
          type: number
        mentions:
          type: integer
        keywords:
          type: array
          items:
            type: string
    SearchResult:
      type: object
      properties:
        id:
          type: string
        score:
          type: number
        fusedScore:
          type: number
        matchType:
          type: string
          enum:
            - semantic
            - keyword
            - hybrid
        denseScore:
          type: number
        sparseScore:
          type: number
        metadata:
          type: object
          properties:
            namespace:
              type: string
            title:
              type: string
            text:
              type: string
    SearchWebHit:
      type: object
      properties:
        title:
          type: string
        url:
          type: string
          format: uri
        highlights:
          type: string
    SearchResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: "#/components/schemas/SearchResult"
        metadata:
          type: object
          properties:
            query:
              type: string
            namespace:
              type: string
            totalResults:
              type: integer
            processingTimeMs:
              type: integer
            searchType:
              type: string
              enum:
                - hybrid
            cached:
              type: boolean
            web:
              type: array
              items:
                $ref: "#/components/schemas/SearchWebHit"
    SearchRequest:
      type: object
      required:
        - query
      properties:
        query:
          type: string
          maxLength: 1000
        namespace:
          type: string
          enum:
            - streams
            - users
            - clips
            - transcripts
            - all
          default: streams
        topK:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
    SearchIndexDoc:
      type: object
      required:
        - id
        - namespace
        - text
      properties:
        id:
          type: string
        namespace:
          type: string
          enum:
            - streams
            - users
            - clips
            - transcripts
        title:
          type: string
        text:
          type: string
        metadata:
          type: object
    SearchIndexRequest:
      type: object
      required:
        - id
        - namespace
        - text
      properties:
        id:
          type: string
        namespace:
          type: string
          enum:
            - streams
            - users
            - clips
            - transcripts
        title:
          type: string
        text:
          type: string
        metadata:
          type: object
        docs:
          type: array
          items:
            $ref: "#/components/schemas/SearchIndexDoc"
    SearchIndexResponse:
      type: object
      properties:
        indexed:
          type: integer
        ids:
          type: array
          items:
            type: string
    SearchDeleteResponse:
      type: object
      properties:
        deleted:
          type: boolean
        id:
          type: string
    SearchInsightRow:
      type: object
      properties:
        query:
          type: string
        term:
          type: string
        count:
          type: integer
        previous:
          type: integer
    SearchAnalyticsResponse:
      type: object
      properties:
        org:
          type: string
        generated_at:
          type: string
          format: date-time
        insights:
          type: object
          properties:
            top:
              type: array
              items:
                $ref: "#/components/schemas/SearchInsightRow"
            zeroResult:
              type: array
              items:
                $ref: "#/components/schemas/SearchInsightRow"
            trending:
              type: array
              items:
                $ref: "#/components/schemas/SearchInsightRow"
    SearchHighlight:
      type: object
      properties:
        field:
          type: string
        snippet:
          type: string
        positions:
          type: array
          items:
            type: object
            properties:
              start:
                type: integer
              end:
                type: integer
    SearchSuggestion:
      type: object
      properties:
        text:
          type: string
        type:
          type: string
          enum:
            - query
            - title
            - tag
        score:
          type: number
    SearchFacet:
      type: object
      properties:
        field:
          type: string
        values:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
              count:
                type: integer
    BraidPublishRequest:
      type: object
      required:
        - ns
        - sources
      description: "`org` is derived from the caller's authenticated principal, not
        sent in the body."
      properties:
        ns:
          type: string
          description: Namespace for the published track. Republishing the same ns
            replaces the prior machine.
        sources:
          type: array
          description: Named audio sources to braid into one interleaved multichannel
            track. Each source needs a `label`/`track` and either a `url` or a
            `path`.
          items:
            type: object
            required:
              - label
              - track
            properties:
              label:
                type: string
              track:
                type: string
              url:
                type: string
                format: uri
              path:
                type: string
        windowMs:
          type: integer
          description: Braid window size in milliseconds. Defaults to the machine-config
            default when omitted.
        sampleRate:
          type: integer
          description: Sample rate for the braided track. Defaults to the machine-config
            default when omitted.
    BraidPublishResult:
      type: object
      required:
        - ns
        - track
        - channels
        - windowMs
        - objectBytes
        - machineId
        - status
      properties:
        ns:
          type: string
        track:
          type: string
        channels:
          type: integer
        windowMs:
          type: integer
        objectBytes:
          type: integer
        machineId:
          type: string
        status:
          type: string
          enum:
            - starting
    BraidStopResult:
      type: object
      required:
        - ns
        - machineId
        - status
      properties:
        ns:
          type: string
        machineId:
          type: string
        status:
          type: string
          enum:
            - stopped
    AvRemuxRequest:
      type: object
      required:
        - videoUrl
        - audioUrl
        - container
      description: "`org` is derived from the caller's authenticated principal, not
        sent in the body."
      properties:
        videoUrl:
          type: string
          format: uri
          description: Source for local IP video (RTP H.264).
        audioUrl:
          type: string
          format: uri
          description: Source for the separate Dante/AES67 audio track.
        container:
          type: string
          description: Output container for the synchronized stream.
          enum:
            - mpegts
            - fmp4
        outputUrl:
          type: string
          format: uri
          description: Optional presigned destination to PUT the resulting container to.
            Omitted → returned inline.
    AvDemuxRequest:
      type: object
      required:
        - sourceUrl
      description: "`org` is derived from the caller's authenticated principal, not
        sent in the body."
      properties:
        sourceUrl:
          type: string
          format: uri
          description: Synchronized MPEG-TS or fMP4 container to split back into video +
            Dante audio.
        videoOutputUrl:
          type: string
          format: uri
          description: Optional presigned destination for the demuxed RTP H.264 video
            output.
        audioOutputUrl:
          type: string
          format: uri
          description: Optional presigned destination for the demuxed Dante/AES67 audio
            output.
    AvTransformResult:
      type: object
      required:
        - ok
        - container
        - durationSeconds
      properties:
        ok:
          type: boolean
        container:
          type: string
          enum:
            - mpegts
            - fmp4
        durationSeconds:
          type: number
          description: Duration of the transformed stream, in seconds — the basis for
            wave_av_transform_seconds billing.
        syncOffsetMs:
          type: number
          description: Measured audio/video sync offset after alignment, in milliseconds
            (sub-millisecond target).
    RenderTemplate:
      type: string
      description: The render template. Per-template prop shapes are published in the
        live contract (GET /render/openapi.json) so this enum can never drift
        from what the renderer accepts.
      enum:
        - slate
        - lowerThird
        - announce
        - stat
        - hero
        - quote
        - backdrop
        - field
        - badge
        - endcard
        - sting
        - ident
        - kinetic
        - ticker
        - countdown
        - receipt
        - code
        - session
        - chart
        - audiogram
        - manifesto
        - changelog
    RenderBrief:
      type: object
      description: "A render Brief — a template plus its props. Brand-parametric: an
        optional BYO `brandKit` (logo SVG, fonts as data URLs, colors) renders
        any template on a tenant's brand."
      required:
        - template
        - props
      properties:
        template:
          $ref: "#/components/schemas/RenderTemplate"
        props:
          type: object
          description: Template-specific props (see the live contract for per-template
            shapes). All string props are HTML-escaped; width/height ≤ 4096,
            durationMs ≤ 60000, fps ≤ 60.
          additionalProperties: true
    RenderResult:
      description: The delivery envelope (Accept application/json). `sha256` is the
        determinism receipt.
      oneOf:
        - $ref: "#/components/schemas/RenderResultInline"
        - $ref: "#/components/schemas/RenderResultUrl"
    RenderResultInline:
      type: object
      required:
        - delivery
        - format
        - sha256
        - bytes
        - contentType
        - dataUrl
      properties:
        delivery:
          type: string
          enum:
            - inline
        format:
          type: string
          enum:
            - mp4
        sha256:
          type: string
          description: sha256 of the output bytes (determinism receipt).
        bytes:
          type: integer
        contentType:
          type: string
          enum:
            - video/mp4
        dataUrl:
          type: string
          description: base64 data URL of the output (small MP4s only).
    RenderResultUrl:
      type: object
      required:
        - delivery
        - format
        - sha256
        - bytes
        - url
        - expiresAtSec
        - contentType
      properties:
        delivery:
          type: string
          enum:
            - url
        format:
          type: string
          enum:
            - mp4
            - alpha
        sha256:
          type: string
          description: sha256 of the output bytes (determinism receipt).
        bytes:
          type: integer
        url:
          type: string
          description: Signed, single-object, expiring URL on downloads.wave.online.
        expiresAtSec:
          type: integer
          description: Absolute Unix expiry of the signed URL.
        contentType:
          type: string
          enum:
            - video/mp4
            - video/quicktime
    RenderJobStatus:
      type: string
      description: Lifecycle of an async render. Deliberately NOT the platform-wide
        `JobStatus` enum — the render pipeline reports its own delivery-aware
        states, and collapsing the two would misreport `delivering` (output
        produced, upload in flight) as either finished or failed.
      enum:
        - queued
        - rendering
        - delivering
        - done
        - error
    RenderJobView:
      type: object
      description: A point-in-time view of an async render job. Only `jobId` and
        `status` are always present; the delivery and receipt fields appear once
        `status` is `done`, and `error` appears only when `status` is `error`.
      required:
        - jobId
        - status
      properties:
        jobId:
          type: string
        status:
          $ref: "#/components/schemas/RenderJobStatus"
        url:
          type: string
          description: "Terminal (done): the signed delivery URL."
        expiresAtSec:
          type: integer
          description: "Terminal (done): absolute Unix expiry of `url`."
        sha256:
          type: string
          description: "Terminal (done): determinism receipt — sha256 of the output bytes."
        bytes:
          type: integer
          description: "Terminal (done): output size in bytes."
        meters:
          type: array
          description: "Terminal (done): the billable usage lines this render billed."
          items:
            type: object
            properties:
              event:
                type: string
              quantity:
                type: number
        error:
          type: object
          description: "Terminal (error): a typed, client-safe error."
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
    MoqJoinToken:
      type: object
      description: A minted MoQ join-token and everything needed to open the media
        session. `joinToken` is a short-lived HMAC-signed bearer bound to
        exactly this `ns`/`track`, `role`, and the caller's organization; the
        relay derives identity and scope from the signed claims and never from a
        client-supplied header. Connect to `relayWsUrl` carrying the token as
        the `join` query parameter (browser clients) or the `x-wave-moq-join`
        header (server-to-server). Never log, cache, or persist `joinToken`;
        mint a fresh one per session.
      required:
        - ok
        - relayWsUrl
        - joinToken
        - expiresIn
        - ns
        - track
        - role
        - scope
      properties:
        ok:
          type: boolean
          description: Always `true` on a successful mint.
        relayWsUrl:
          type: string
          format: uri
          description: The DIRECT relay URL for this session, e.g.
            `wss://moq.wave.online/v1/publish/{ns}/{track}`. Media flows here,
            not through the API gateway.
        joinToken:
          type: string
          description: "The signed join-token
            (`base64url(header).base64url(payload).base64url(signature)`,
            HMAC-SHA256, `typ: MOQJ` so it can never be confused with an API
            key). Treat as a secret."
        expiresIn:
          type: integer
          description: Token lifetime in seconds from mint. Currently 120; the relay
            additionally rejects any token whose signed lifetime exceeds the
            contract ceiling, and allows a few seconds of clock skew.
        ns:
          type: string
          description: The namespace the token is bound to (echoes the path parameter).
        track:
          type: string
          description: The track the token is bound to (echoes the path parameter).
        role:
          type: string
          enum:
            - publish
            - subscribe
          description: Derived from the route, never from a client field.
        scope:
          type: string
          enum:
            - moq:write
            - moq:read
          description: "The single scope granted by this token — `moq:write` for publish,
            `moq:read` for subscribe. Least-privilege: a subscribe token cannot
            publish."
        protocol:
          type: string
          description: Present only when a publisher declared a recognized, authorized
            origin protocol at mint time (see `x-wave-declare-protocol`). Absent
            means the session bills as plain `moq`.
    X402PaymentRequired:
      type: object
      description: "The x402 payment-challenge body returned with HTTP 402. Distinct
        from the `Error` envelope: `error` here is a human-readable string and
        the normalized WAVE error object is nested under `error_detail`."
      required:
        - x402Version
        - error
        - accepts
      properties:
        x402Version:
          type: integer
          description: x402 protocol version (currently 1).
        error:
          type: string
          description: Short reason, e.g. `payment required`.
        accepts:
          type: array
          description: Payment options; sign one and retry with the `x-payment` header.
          items:
            $ref: "#/components/schemas/X402Accepts"
        error_detail:
          allOf:
            - $ref: "#/components/schemas/ErrorBody"
            - type: object
              properties:
                payment_rejected:
                  type: object
                  description: "Present ONLY when a submitted payment was REJECTED (as opposed to
                    no payment having been made at all): the sanitized deny
                    verdict, so a paying caller can tell a rejected payment
                    apart from an unpaid challenge and correct the named field.
                    `reason` is a lowercase snake_case token from the gateway's
                    closed deny vocabulary (e.g. `invalid_permit_header`,
                    `session_expired`, `duplicate`, `rate_limited`); internal
                    detail that cannot be published verbatim collapses to the
                    generic `payment_rejected`. `rail` names the payment rail
                    that denied (e.g. `base-usdc`, `tempo-pathusd`), or
                    `unknown`."
                  required:
                    - reason
                    - rail
                  properties:
                    reason:
                      type: string
                      description: Sanitized machine-readable rejection reason token.
                    rail:
                      type: string
                      description: The payment rail the rejection occurred on.
        next_action:
          type: object
          additionalProperties: true
          description: Machine-executable directive for agent callers — a `pay` directive
            carrying the same `accepts` options.
    X402Accepts:
      type: object
      description: One acceptable payment option in an x402 challenge.
      properties:
        scheme:
          type: string
          description: Payment scheme, e.g. `exact`.
        protocol:
          type: string
          description: Always `x402`.
        network:
          type: string
          description: Settlement network, e.g. `base`.
        maxAmountRequired:
          type: string
          description: Amount in the asset's smallest unit, as a decimal string.
        resource:
          type: string
          description: The request path being charged for.
        description:
          type: string
        mimeType:
          type: string
        payTo:
          type: string
          description: Destination address for the payment.
        maxTimeoutSeconds:
          type: integer
        asset:
          type: string
          description: Contract address of the settlement asset.
        extra:
          type: object
          additionalProperties: true
          description: Scheme-specific metadata (e.g. settlement mode, session id).
    PricingManifest:
      type: object
      properties:
        slug:
          type: string
        org:
          type: string
        tiers:
          type: array
          items:
            type: object
            additionalProperties: true
        createdAt:
          type: string
        updatedAt:
          type: string
      additionalProperties: true
    IdentityResolveResponse:
      description: >
        The resolved directory entry, DISCRIMINATED on the outer `agent` value:
        `agent: "telephony"` serves the TelephonyResolveResponse variant; every
        other directory key serves the AgentResolveResponse variant. Generated
        clients can narrow on `agent`.
      oneOf:
        - $ref: "#/components/schemas/AgentResolveResponse"
        - $ref: "#/components/schemas/TelephonyResolveResponse"
    AgentResolveResponse:
      type: object
      additionalProperties: false
      required:
        - agent
        - identity
      properties:
        agent:
          type: string
          pattern: ^[a-z0-9-]{1,64}$
          not:
            const: telephony
          description: The resolved agent id — any directory key EXCEPT the telephony
            service entry
        identity:
          $ref: "#/components/schemas/AgentIdentity"
    TelephonyResolveResponse:
      type: object
      additionalProperties: false
      required:
        - agent
        - identity
      properties:
        agent:
          const: telephony
        identity:
          $ref: "#/components/schemas/TelephonyIdentity"
    AgentIdentity:
      type: object
      additionalProperties: false
      description: >
        One agent's public directory entry. `key` is a credential key NAME,
        never a key value — the directory carries no secret material.
      required:
        - email
        - key
        - org
        - channels
      properties:
        email:
          type: string
          format: email
          description: The agent's inbox (e.g. `opencode@agents.wave.online`)
        key:
          type: string
          pattern: ^[A-Z0-9_]+$
          description: Credential key NAME for the agent's inbox credential (never the
            value)
        org:
          type: string
          description: Owning org (e.g. `wave`)
        channels:
          type: array
          items:
            type: string
          description: Reachable channels (e.g. `mail`, `paid-rail`, `realtime`)
    TelephonyIdentity:
      type: object
      additionalProperties: false
      description: >
        The telephony service entry — the one documented variation on the agent
        shape: plural credential key names + E.164 numbers, no email/key. `org`
        is always present so every identity object carries it.
      required:
        - org
        - channels
        - numbers
        - keys
      properties:
        org:
          type: string
          description: Owning org (e.g. `wave`)
        channels:
          type: array
          items:
            type: string
          description: Reachable channels (e.g. `voice`, `sms-blocked-a2p`)
        numbers:
          type: array
          items:
            type: string
            pattern: ^\+[1-9]\d{1,14}$
          description: E.164 numbers
        keys:
          type: array
          items:
            type: string
            pattern: ^[A-Z0-9_]+$
          description: Credential key NAMES for the telephony credentials (never values)
    IdentityResolveValidationError:
      type: object
      description: >
        400 envelope for /identity/resolve — `error.code` is one of the
        documented validation codes, so generated clients can switch on it.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - MISSING_AGENT
                - BAD_AGENT
                - ORG_MISMATCH
            message:
              type: string
    IdentityResolveNotFoundError:
      type: object
      description: >
        404 envelope for /identity/resolve — `error.code` is always
        UNKNOWN_AGENT; `agent` echoes the requested id.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - UNKNOWN_AGENT
            message:
              type: string
        agent:
          type: string
          description: Echo of the requested (unknown) agent id
x-wave-paused-products:
  note: These products are paused and not sold; their operations are omitted from
    this document. Every request that would start work answers 503
    PRODUCT_PAUSED with no payment requested.
  status_index: https://gateway.wave.online/.well-known/wave-skills.json
  products:
    - path: /v1/render
      product: render
      paused_since: 2026-09-24
    - path: /v1/renders
      product: render
      paused_since: 2026-09-24
    - path: /v1/enhance
      product: enhance
      paused_since: 2026-09-24
    - path: /v1/video-gen
      product: video-gen
      paused_since: 2026-09-24
x-wave-unserved-advertised-paths:
  note: These documented paths/operations have no spoke, no gateway-native handler
    and no server behind them — every request to them answers 404
    ROUTE_NOT_FOUND with no payment requested. Omitted here for the same reason
    the MCP tool generator and skill-card route table already refuse to build
    affordances for them (see src/unserved-advertised-paths.ts).
  prefixes:
    - /streams
    - /productions
    - /cameras
    - /editor/projects
    - /phone/lines
    - /phone/calls
    - /collab/rooms
    - /podcast/shows
    - /studio-ai
    - /moderate
  operations:
    - method: GET
      path: /sentiment
x-wave-enhance:
  route: POST /v1/enhance?model=espcn
  shape: espcn super-resolution, 672x672 only
  status: paused (503 PRODUCT_PAUSED, never charged) — see x-wave-paused-products
  retired: /v1/studio-ai/* (never served; returns 404 before any payment)
