# TipPage Developer API - OpenAPI 3.1
#
# The same document that powers the reference at docs.tippage.com/api/reference.
# Import it into Postman, Insomnia, or Bruno, or feed it to a client
# generator. Guides and webhook docs: https://docs.tippage.com/api
openapi: 3.1.0

info:
  title: TipPage Developer API
  version: "1.0"
  summary: Read tips, drive the TTS and media queues, and receive signed webhooks.
  description: |
    Read your tips, drive the TTS and media queues, run the chat bot, and get
    events the moment they happen.

    | | |
    |---|---|
    | API base | `https://api.tippage.com/v1` |
    | Auth | `Authorization: Bearer tp_live_...` - see [Authentication](https://docs.tippage.com/api/authentication) |
    | Realtime stream | `wss://ws.tippage.com` - see [Realtime](https://docs.tippage.com/api/realtime) |
    | Spec | [openapi.yaml](https://docs.tippage.com/openapi.yaml) - import into Postman, Insomnia or Bruno, or generate a client |

    Guides: [OAuth 2.0](https://docs.tippage.com/api/oauth) for apps other streamers connect,
    [Webhooks](https://docs.tippage.com/api/webhooks) for signed events, [Claim and finish](https://docs.tippage.com/api/claim-and-finish)
    to play tips from your own code.

    **Rate limits:** 240 requests/min per IP and 120/min per key (or OAuth
    authorization), in `RateLimit-*` headers; over the limit is `429`.
    `POST /chat/messages` also has its own budget: 20 messages per 30 seconds
    per streamer, across all keys.

    **Errors** are JSON: `{ "error": "<human message>", "code": "<machine_code>" }`.

servers:
  - url: https://api.tippage.com/v1

security:
  - bearerAuth: []

tags:
  - name: Identity
    description: Key introspection and API discovery.
  - name: Realtime
    description: >
      The webhook event stream, live over a WebSocket at
      wss://ws.tippage.com - same events, same payloads, same event
      ids as the webhooks, delivered while you're connected. No SDK
      needed: open a plain WebSocket, send one JSON line -
      `{"data": {"apiKey": "tp_live_..."}}` for connections you control,
      or `{"data": {"token": "..."}}` with a short-lived token from
      POST /realtime/token to let clients that shouldn't hold your key
      (browsers, third parties) connect. The server streams the events
      your key's scopes allow. Full guide, wire format, channel table,
      and lifecycle: https://docs.tippage.com/api/realtime
  - name: TTS queue
    description: >
      The pending TTS queue and its played history. Reads need `tts:read`;
      controls need `tts:control`. The start/finish pair is the same
      protocol the stream overlay speaks - an external consumer can claim a
      TTS, play it its own way, and finish it into history. Full pattern:
      [claim, do your thing, finish](https://docs.tippage.com/api/claim-and-finish).
  - name: Media queue
    description: >
      The media (video request) queue, its played history, live playback
      status, and direct video queueing. Reads need `media:read`; controls
      and queueing need `media:control`.
  - name: Alerts
    description: >
      Platform alerts - subs, gift subs, resubs, cheers, raids, Kicks and
      channel point redemptions - as the overlay's alert box plays them:
      what is on screen now, what played, skip and replay. Reads need
      `tts:read`, controls `tts:control` (the same pair the dashboard's
      TTS page uses for the same panel). The live events themselves ride
      the `twitch` and `kick` [realtime groups](https://docs.tippage.com/api/realtime).
  - name: Tipping
    description: >
      Tips themselves: create manual tips (`tips:create`), the
      accept-new-tips switch (status readable by any valid key,
      opening/closing via `tipping:control`), and the supporter leaderboard
      (any valid key).
  - name: Viewers
    description: >
      Viewer management for the sub-rewards system. A viewer is someone who
      has signed in to the tip page - with Twitch or Kick - and every
      viewer object names that account as `platform` + `platform_user_id`,
      with the person's other linked account(s) in `linked_accounts`. List
      them with their first sign-in dates and credit balances
      (`viewers:read`), read one viewer's grant ledger and sub-reward usage,
      and grant or revoke credits (`viewers:manage`). Balances, grants and
      reward history are read across a person's linked accounts; a grant or
      revoke lands on the exact account you name. Everywhere a `{user}`
      appears in a path you can pass `<platform>:<id>` (`kick:123`), a bare
      numeric id, or the viewer's name (login or display name,
      case-insensitive, on either platform). Someone who has never signed
      in can't be looked up or granted credits - those requests answer
      `404 viewer_not_signed_in`.
  - name: AI voices
    description: >
      AI voice TTS (TipPage+): the curated voice catalog with per-voice
      enabled flags, this month's character usage, and toggles for the
      whole feature or individual voices. Needs `ai_voices:manage`. Every
      endpoint answers `404` unless AI voices are available to your
      account.
  - name: Channel points
    description: >
      Create channel point rewards and resolve their redemptions on Twitch.
      Needs `channel_points:manage`. Twitch only lets the app that created a
      reward resolve its redemptions, so resolving works for rewards TipPage
      created - through `POST /channel-points/rewards`, or the dashboard's
      Channel points page. Pair with the `twitch.channel_point_redemption`
      webhook, whose `is_managed` flag says whether a redemption is
      resolvable.
  - name: Webhook endpoints
    description: >
      Manage where events get delivered. Needs `webhooks:manage`. Endpoints
      can also be managed in the dashboard.
  - name: Chat timers
    description: >
      Scheduled chat-bot messages - the bot posts them on a fixed or
      randomized interval, optionally only while the streamer is live or
      after enough chat activity. Needs `timers:manage`. The same timers
      as the dashboard's Chat bot page; max 20 per streamer. Editing a
      timer's interval restarts its schedule from now.
  - name: Counters
    description: >
      Named per-streamer numbers the chat bot bumps with `{count}` /
      `{count:name}` command tokens and overlay Data labels can display
      live. Addressed by name - a lowercase slug (`a-z 0-9 _ -`, max 64
      chars) is the key on every surface. Needs `counters:manage`. Every
      change made here behaves exactly like a chat bump: overlays update
      live and the `counter.updated` webhook fires. Max 100 per streamer.
  - name: Chat bot
    description: >
      The streamer's chat bot: its status and send identity (any valid
      key), speaking in chat as the bot (`chat:write`), and the custom
      `!commands` it answers (`commands:manage`, addressed by command name
      - the trigger without the `!`). Pair with the `chat.command` webhook
      event to react when a custom command runs.
  - name: Overlays
    description: >
      The account's overlays: list them, inspect one (name, resolution,
      widget types - never overlay keys), delete one, reload a connected
      one, fire the Event celebration widget on demand (all of them or
      one specific instance), and read, update, or add to each overlay's
      tip goal. All of it needs `overlays:manage`.

paths:
  /me:
    get:
      operationId: getMe
      tags: [Identity]
      summary: Who am I
      description: >
        Returns the streamer this credential belongs to and the credential
        itself - an API key or an OAuth authorization, same shape either
        way. The first call to make when wiring up an integration.
      responses:
        "200":
          description: Credential and tenant identity.
          content:
            application/json:
              schema:
                type: object
                properties:
                  tenant:
                    type: object
                    properties:
                      id: { type: string, examples: ["t_a7f3b9c2"] }
                      name: { type: string, examples: ["CallumFromTheCorner"] }
                      avatar_url:
                        type: [string, "null"]
                        description: The connected channel's picture (Twitch first, else Kick) - the one the tip page header shows.
                      currency:
                        type: string
                        description: ISO 4217 code of the streamer's tip currency.
                        examples: ["GBP"]
                      currency_symbol:
                        type: string
                        description: >
                          Display symbol for that currency, as shown on the tip page.
                          Use it when rendering `amount` fields anywhere in this API.
                        examples: ["£"]
                      media_requests:
                        type: boolean
                        description: Media requests are switched on for the channel. Off = the media queue never fills and there is nothing to pause or show on stream; an app can leave its media controls out.
                  credential:
                    type: object
                    description: What authenticated this request.
                    properties:
                      type:
                        type: string
                        enum: [api_key, oauth]
                      id:
                        type: string
                        description: The key (`ak_...`) or, for an OAuth token, the authorization it acts under (`oa_...`).
                        examples: ["ak_1f2e3d4c5b6a"]
                      name:
                        type: string
                        description: The key's dashboard name, or the OAuth app's name.
                        examples: ["Discord bot"]
                      scopes:
                        type: array
                        items: { type: string }
                        examples: [["tts:read", "tts:control"]]
                  oauth:
                    type: [object, "null"]
                    description: The app behind an OAuth authorization; `null` for an API key.
                    properties:
                      client_id: { type: string, examples: ["oc_9f8e7d6c5b4a"] }
                      client_name: { type: string, examples: ["Loadout Sync"] }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /events:
    get:
      operationId: listEventTypes
      tags: [Identity]
      summary: Event and scope catalog
      description: Lists every webhook event type and every key scope, with descriptions.
      responses:
        "200":
          description: Catalogs keyed by name.
          content:
            application/json:
              schema:
                type: object
                properties:
                  events:
                    type: object
                    additionalProperties: { type: string }
                    description: "`event type -> description`"
                  scopes:
                    type: object
                    additionalProperties: { type: string }
                    description: "`scope -> description`"
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /realtime/token:
    post:
      operationId: mintRealtimeToken
      tags: [Realtime]
      summary: Mint a realtime handoff token
      description: >
        A short-lived credential for opening the realtime WebSocket from a
        context that shouldn't hold the API key. Send
        `{"data": {"token": "..."}}` as the first WebSocket message before
        it expires; the connection then behaves exactly like an API-key
        connection (channels come from the key's scopes at connect time,
        and the connection outlives the token). Daemons that hold the key
        can skip this endpoint and connect with
        `{"data": {"apiKey": "..."}}` directly. Requires a key with at
        least one realtime-capable scope. Guide:
        https://docs.tippage.com/api/realtime
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                expires_in:
                  type: integer
                  minimum: 60
                  maximum: 3600
                  default: 900
                  description: Token lifetime in seconds (how long it can be used to connect).
                groups:
                  type: array
                  items:
                    type: string
                    enum: [tts, media, twitch, chat, counters, overlays]
                  example: ["tts", "twitch"]
                  description: >
                    Narrow the token to a subset of the key's groups - so a
                    broad key can hand out a token that only sees some of
                    them. Every name must be a group the key's own scopes
                    already grant (otherwise 403 `group_not_granted`); it
                    can only narrow, never widen. Omit to grant everything
                    the key allows.
      responses:
        "200":
          description: Connection details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    example: "wss://ws.tippage.com"
                    description: The raw WebSocket endpoint - no client library needed.
                  token: { type: string, description: "Send as `{\"data\": {\"token\": \"...\"}}` in the first WebSocket message." }
                  expires_at: { type: string, format: date-time }
                  channels:
                    type: array
                    items: { type: string }
                    example: ["dev:t_abc123:tts", "dev:t_abc123:twitch"]
                    description: The channels this token will actually grant (the key's scopes, narrowed by `groups` if given).
        "400":
          description: "`groups` was malformed or contained an unknown group name (`bad_groups`)."
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403":
          description: The key has no realtime-capable scopes (`no_realtime_scopes`), or `groups` asked for one the key doesn't grant (`group_not_granted`).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /tts/queue:
    get:
      operationId: getTtsQueue
      tags: [TTS queue]
      summary: Pending TTS queue
      description: >
        The queued TTS entries waiting to be played, oldest first, plus the playback
        state. `tts_url` is `null` until the pre-rendered audio is ready
        (subscribe to `tip.tts_ready` or re-poll). Requires `tts:read`.
      responses:
        "200":
          description: Queue state and items.
          content:
            application/json:
              schema:
                type: object
                properties:
                  is_paused: { type: boolean }
                  playing: { type: boolean }
                  current_order_id:
                    type: [string, "null"]
                    description: order_id of the tip being played right now.
                  queue_mode:
                    type: string
                    enum: [separate, linked]
                    description: >
                      `linked` = TTS and media play as one unit and
                      pause/resume/skip on either queue act on both.
                  items:
                    type: array
                    items: { $ref: "#/components/schemas/QueueTip" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /tts/history:
    get:
      operationId: getTtsHistory
      tags: [TTS queue]
      summary: Played TTS history
      description: >
        TTS entries that finished playing, most recent first, cursor-paginated.
        Requires `tts:read`.
      parameters:
        - $ref: "#/components/parameters/HistoryLimit"
        - $ref: "#/components/parameters/HistoryBefore"
      responses:
        "200":
          description: One page of history.
          content:
            application/json:
              schema:
                type: object
                properties:
                  tips:
                    type: array
                    items: { $ref: "#/components/schemas/HistoryTip" }
                  has_more: { type: boolean }
                  next_cursor:
                    type: [string, "null"]
                    description: Pass as `?before=` to fetch the next page.
        "400":
          description: Unknown cursor.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /tts/now:
    get:
      operationId: getTtsNow
      tags: [TTS queue]
      summary: What's playing right now
      description: >
        The TTS currently claimed as playing, if any. TTS audio has no
        known duration, so there is no live position - `started_at` is
        when the claim was made, which is enough to spot a consumer that
        died mid-item. Requires `tts:read`.
      responses:
        "200":
          description: Current playback state.
          content:
            application/json:
              schema:
                type: object
                properties:
                  playing:
                    type: boolean
                    description: A TTS is claimed as playing right now.
                  is_paused: { type: boolean }
                  tip:
                    oneOf:
                      - $ref: "#/components/schemas/QueueTip"
                      - type: "null"
                  started_at:
                    type: [string, "null"]
                    format: date-time
                    description: When the current TTS was claimed.
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /tts/voices:
    get:
      operationId: listTtsVoices
      tags: [TTS queue]
      summary: Standard voices
      description: >
        The standard voices a tip can be read in - the ids
        [tip audio](/api/reference/tts-queue/getttsaudio) takes as `voice`.
        Requires `tts:read`.
      responses:
        "200":
          description: The voices.
          content:
            application/json:
              schema:
                type: object
                properties:
                  standard:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string, examples: [Emma] }
                        label: { type: string }
                        detail: { type: string, examples: ["English (UK), female"] }
                        language: { type: string, examples: [en-GB] }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /tts/{orderId}/audio:
    get:
      operationId: getTtsAudio
      tags: [TTS queue]
      summary: Audio for a tip
      description: >
        The clip for a queued tip, made on demand. A standard-voice tip's
        audio is only made when something comes to play it, so a consumer
        that plays tips itself asks here before or after claiming; an
        AI-voice tip's clip was made at payment and is handed straight back.
        The words come from the row's current name, amount and message. The
        clip you are handed is written to the queue row as `tts_url` and
        fires `tip.tts_ready` (again if it replaces an earlier clip in
        another voice, such as a dashboard preview).


        Say whose voice to read it in: `overlay` for that overlay's alert box
        voice, or `voice` for a standard voice. Passing neither is deprecated:
        it reads in Brian for now and will become `400 voice_required`. Other
        voice parameters given directly override the overlay's. A tip that has already played can
        be asked for too: you get the clip that played, whatever voice you
        name (one that played with no audio is made now). No rate limit; up to
        8 distinct voice variants per tip. The same parameters are accepted
        in a JSON body on POST. Requires `tts:read`.
      parameters:
        - $ref: "#/components/parameters/OrderId"
        - name: overlay
          in: query
          description: An overlay id (`o_...`). Read the tip the way that overlay's alert box is set to.
          schema: { type: string }
        - name: voice
          in: query
          description: A standard voice id from `/tts/voices`.
          schema: { type: string }
        - name: rate
          in: query
          schema: { type: number, minimum: 0.5, maximum: 2 }
        - name: pitch
          in: query
          schema: { type: number, minimum: 0.7, maximum: 1.5 }
        - name: readNames
          in: query
          schema: { type: boolean }
        - name: readAmounts
          in: query
          schema: { type: boolean }
        - name: readMessages
          in: query
          schema: { type: boolean }
        - name: maxLength
          in: query
          description: Cut the message at this many characters.
          schema: { type: integer, minimum: 0, maximum: 1000 }
      responses:
        "200":
          description: >
            One of: the clip (`url`, with `text` for a standard tip or `ai`
            for an AI-voice tip), `pending` (an AI voice is still being made,
            ask again after `retryMs`), or `silent` (nothing of this tip is
            read with these settings).
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    properties:
                      url: { type: string, format: uri }
                      text: { type: string, description: The words in the clip. }
                      cached: { type: boolean }
                      provider: { type: [string, "null"] }
                      ai:
                        type: object
                        description: Present for an AI-voice tip.
                        properties:
                          voiced: { type: [boolean, "null"], description: False when the AI generation failed and the clip is the standard voice. }
                          turns: { type: [array, "null"], items: { type: object } }
                  - type: object
                    properties:
                      pending: { type: boolean, enum: [true] }
                      retryMs: { type: integer }
                      message: { type: string }
                  - type: object
                    properties:
                      silent: { type: boolean, enum: [true] }
        "400":
          description: "A voice parameter is out of range or names no standard voice. Later also `voice_required` (neither `overlay` nor `voice` was given)."
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404":
          description: "`tip_not_found` (no tip of yours has that id) or `overlay_not_found` (no overlay of yours with an alert box has that id)."
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "429":
          description: "`too_many_variants`: the tip has been asked for in too many different voices."
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "503":
          description: Every synthesiser failed. `text` carries the words, for a voice of your own.
          content:
            application/json:
              schema:
                type: object
                properties:
                  fallback: { type: boolean, enum: [true] }
                  text: { type: string }
                  error: { type: string }

  /tts/pause:
    post:
      operationId: pauseTts
      tags: [TTS queue]
      summary: Pause the TTS queue
      description: >
        Stops new TTS from starting; the queue keeps accumulating. Requires
        `tts:control`.
      responses:
        "200": { $ref: "#/components/responses/Success" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /tts/resume:
    post:
      operationId: resumeTts
      tags: [TTS queue]
      summary: Resume the TTS queue
      description: Clears the paused state and playback pointer. Requires `tts:control`.
      responses:
        "200": { $ref: "#/components/responses/Success" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /tts/skip:
    post:
      operationId: skipTts
      tags: [TTS queue]
      summary: Skip the currently-playing TTS
      description: >
        Pass `order_id` to pin the request to THAT tip, so a request that
        lands after it has already finished can't skip the next one; omit
        it to skip whatever is playing. In linked mode the unit (TTS and
        media) is skipped together. Requires `tts:control`.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                order_id:
                  type: string
                  description: The tip to skip (from `/tts/now`). Omit to skip whatever is playing.
      responses:
        "200":
          description: Skipped (a no-op when nothing was playing and no `order_id` was given).
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  skipped_order_id:
                    type: [string, "null"]
                    description: The tip that was playing, if any.
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "409":
          description: >
            `not_playing` - the `order_id` named has already finished
            (`current_order_id` says what is playing now, or null).
            `skip_disabled` - skipping is locked on this channel.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      current_order_id: { type: [string, "null"] }
        "429": { $ref: "#/components/responses/RateLimited" }

  /tts/clear:
    post:
      operationId: clearTts
      tags: [TTS queue]
      summary: Clear the whole TTS queue
      description: >
        Deletes every queued TTS and resets playback state (media playback
        state included). Requires
        `tts:control`.
      responses:
        "200": { $ref: "#/components/responses/Success" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /tts/{orderId}:
    delete:
      operationId: removeTtsItem
      tags: [TTS queue]
      summary: Remove one queued TTS
      description: >
        Removes the TTS half of a tip before it plays (a paired media item
        stays queued). The removal is audit-logged for the streamer's
        moderation review. Requires `tts:control`.
      parameters:
        - $ref: "#/components/parameters/OrderId"
      responses:
        "200": { $ref: "#/components/responses/Success" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /tts/{orderId}/replay:
    post:
      operationId: replayTtsItem
      tags: [TTS queue]
      summary: Replay a TTS from history
      description: >
        Re-queues a played tip (as a new queue entry with a fresh `replay_...`
        order id; fires `tip.created` with `source: "replay"`). A short
        idempotency window returns `409` if the same tip was just replayed.
        Requires `tts:control`.
      parameters:
        - $ref: "#/components/parameters/OrderId"
      responses:
        "200": { $ref: "#/components/responses/Success" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409":
          description: Replayed too recently (idempotency window).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /tts/{orderId}/start:
    post:
      operationId: startTtsItem
      tags: [TTS queue]
      summary: Claim a TTS as now playing
      description: >
        Marks a queued TTS as currently playing - the same call the overlay
        makes. Fires `queue.tts.started`. While claimed, other consumers get
        `409 already_playing`. If your effect then fails and the tip should
        not count as played, undo the claim with
        [release](/api/reference/tts-queue/releasettsitem) instead of
        finishing. See the
        [claim, do your thing, finish](https://docs.tippage.com/api/claim-and-finish)
        guide for the full pattern. Requires `tts:control`.
      parameters:
        - $ref: "#/components/parameters/OrderId"
      responses:
        "200":
          description: Claimed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  tip: { $ref: "#/components/schemas/QueueTip" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409":
          description: >
            `queue_paused` (the queue is paused) or `already_playing` (another
            tip holds the slot; `current_order_id` names it).
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      current_order_id: { type: string }
        "429": { $ref: "#/components/responses/RateLimited" }

  /tts/{orderId}/finish:
    post:
      operationId: finishTtsItem
      tags: [TTS queue]
      summary: Finish a TTS
      description: >
        Promotes the TTS from queue to history and frees the now-playing slot
        (when it points at this one). Fires `queue.tts.finished`. Idempotent -
        finishing an already-gone TTS succeeds with `tip: null`. Finishing
        means "this played" - if it didn't (your effect failed), use
        [release](/api/reference/tts-queue/releasettsitem) to put it back
        instead. Requires `tts:control`.
      parameters:
        - $ref: "#/components/parameters/OrderId"
      responses:
        "200":
          description: Finished.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  tip:
                    oneOf:
                      - $ref: "#/components/schemas/QueueTip"
                      - type: "null"
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /tts/{orderId}/release:
    post:
      operationId: releaseTtsItem
      tags: [TTS queue]
      summary: Release a claimed TTS back to the queue
      description: >
        The undo of [start](/api/reference/tts-queue/startttsitem), for when your
        effect didn't go to plan - the audio device failed, your process is
        shutting down mid-item, the effect errored before anything played.
        Drops the now-playing claim WITHOUT finishing: the tip stays in the
        queue at its position, the slot frees, and the tip can be claimed
        again (by you after recovering, or by any other consumer). Fires
        `queue.tts.released`. Only drops a claim that actually points at
        this order id - it can never kick out a different tip's claim, and
        releasing something you don't hold is a safe no-op (`released:
        false`). If the tip DID play, use
        [finish](/api/reference/tts-queue/finishttsitem) instead so it lands in
        history. Requires `tts:control`.
      parameters:
        - $ref: "#/components/parameters/OrderId"
      responses:
        "200":
          description: "Released (`released: false` when there was no claim to drop)."
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  released:
                    type: boolean
                    description: Whether a now-playing claim was actually dropped.
                  tip:
                    oneOf:
                      - $ref: "#/components/schemas/QueueTip"
                      - type: "null"
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /media/queue:
    get:
      operationId: getMediaQueue
      tags: [Media queue]
      summary: Pending media queue
      description: >
        Video requests waiting to play, oldest first, plus playback state.
        Requires `media:read`.
      responses:
        "200":
          description: Queue state and items.
          content:
            application/json:
              schema:
                type: object
                properties:
                  is_paused: { type: boolean }
                  visible:
                    type: boolean
                    description: Whether the media player is shown on the overlay.
                  playing: { type: boolean }
                  current_order_id: { type: [string, "null"] }
                  queue_mode:
                    type: string
                    enum: [separate, linked]
                    description: Same as on the TTS queue.
                  items:
                    type: array
                    items: { $ref: "#/components/schemas/QueueMediaItem" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /media/history:
    get:
      operationId: getMediaHistory
      tags: [Media queue]
      summary: Played media history
      description: >
        Media that finished playing, most recent first, cursor-paginated the
        same way as `/tts/history`. Requires `media:read`.
      parameters:
        - $ref: "#/components/parameters/HistoryLimit"
        - $ref: "#/components/parameters/HistoryBefore"
      responses:
        "200":
          description: One page of history.
          content:
            application/json:
              schema:
                type: object
                properties:
                  media:
                    type: array
                    items: { $ref: "#/components/schemas/HistoryMediaItem" }
                  has_more: { type: boolean }
                  next_cursor: { type: [string, "null"] }
        "400":
          description: Unknown cursor.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /media/now:
    get:
      operationId: getMediaNow
      tags: [Media queue]
      summary: What's playing right now
      description: >
        The media item currently on the overlay screen, with its live
        playback position. `position_seconds` is the position within the
        video (start offset + elapsed time), capped at the video's known
        duration; it is `null` while the queue is paused (pausing clears the
        timing anchor) or when no anchor exists. Requires `media:read`.
      responses:
        "200":
          description: Current playback state.
          content:
            application/json:
              schema:
                type: object
                properties:
                  playing:
                    type: boolean
                    description: A media item is on screen right now.
                  is_paused: { type: boolean }
                  visible:
                    type: boolean
                    description: Whether the media player is shown on the overlay.
                  media:
                    oneOf:
                      - $ref: "#/components/schemas/QueueMediaItem"
                      - type: "null"
                  started_at:
                    type: [string, "null"]
                    format: date-time
                    description: When playback of the current item began.
                  position_seconds:
                    type: [integer, "null"]
                    description: Live position within the video, in seconds.
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /media:
    post:
      operationId: createMediaItem
      tags: [Media queue]
      summary: Queue a video
      description: >
        Put a video straight into the media queue, no tip attached - it
        plays on the overlay through the normal queue like any other
        request. The URL goes through the same validation as every entry
        route: platform parsing, playability checks, and the streamer's
        banned-videos list. Queued items carry `requested_via: "api"` and
        fire the `media.created` webhook. Requires `media:control`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                  description: The video URL (YouTube and other supported platforms).
                start_time:
                  type: integer
                  minimum: 0
                  default: 0
                  description: Start offset in seconds.
                name:
                  type: string
                  maxLength: 100
                  default: API
                  description: Display name shown in the queue ("requested by").
              required: [url]
      responses:
        "201":
          description: Queued.
          content:
            application/json:
              schema:
                type: object
                properties:
                  media: { $ref: "#/components/schemas/QueueMediaItem" }
        "400":
          description: >
            Invalid, unplayable, or banned video (`invalid_media`), or
            missing url (`bad_request`).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /media/pause:
    post:
      operationId: pauseMedia
      tags: [Media queue]
      summary: Pause the media queue
      description: Requires `media:control`.
      responses:
        "200": { $ref: "#/components/responses/Success" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /media/resume:
    post:
      operationId: resumeMedia
      tags: [Media queue]
      summary: Resume the media queue
      description: Requires `media:control`.
      responses:
        "200": { $ref: "#/components/responses/Success" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /media/skip:
    post:
      operationId: skipMedia
      tags: [Media queue]
      summary: Skip the currently-playing media
      description: >
        Pass `order_id` to pin the request to THAT item, so a request that
        lands after it has already finished can't skip the next one; omit
        it to skip whatever is playing. In linked mode the unit (TTS and
        media) is skipped together. Requires `media:control`.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                order_id:
                  type: string
                  description: The item to skip (from `/media/now`). Omit to skip whatever is playing.
      responses:
        "200":
          description: Skipped (a no-op when nothing was playing and no `order_id` was given).
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  skipped_order_id:
                    type: [string, "null"]
                    description: The media item that was on screen, if any.
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "409":
          description: >
            `not_playing` - the `order_id` named has already finished
            (`current_order_id` says what is playing now, or null).
            `skip_disabled` - skipping is locked on this channel.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      current_order_id: { type: [string, "null"] }
        "429": { $ref: "#/components/responses/RateLimited" }

  /media/{orderId}:
    delete:
      operationId: removeMediaItem
      tags: [Media queue]
      summary: Remove one queued media item
      description: >
        Removes the media half before it plays - a paired TTS stays queued.
        The removal is audit-logged for the streamer's moderation review,
        and `queue.media.removed` fires. Requires `media:control`.
      parameters:
        - $ref: "#/components/parameters/MediaOrderId"
      responses:
        "200": { $ref: "#/components/responses/Success" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /media/{orderId}/replay:
    post:
      operationId: replayMediaItem
      tags: [Media queue]
      summary: Replay a media item from history
      description: >
        Re-queues a played media item (as a new queue entry with a fresh
        `replay_...` order id; fires `media.created` with `is_replay`
        set). A short idempotency window returns `409` if the same item
        was just replayed. Requires `media:control`.
      parameters:
        - $ref: "#/components/parameters/MediaOrderId"
      responses:
        "200": { $ref: "#/components/responses/Success" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409":
          description: Replayed too recently (idempotency window).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /media/{orderId}/start:
    post:
      operationId: startMediaItem
      tags: [Media queue]
      summary: Claim a media item as now playing
      description: >
        Marks a queued media item as currently playing - the same call the
        overlay makes when it starts a video. Fires `queue.media.started`
        and sets the timing anchor that `/media/now` reads. Refused with
        `409 queue_paused` while the media queue is paused. Unlike the TTS
        claim there is no already-playing gate: pacing is the consumer's
        job. If your player
        then fails and the item should not count as played, undo the claim
        with [release](/api/reference/media-queue/releasemediaitem) instead of
        finishing. See
        [claim, do your thing, finish](https://docs.tippage.com/api/claim-and-finish).
        Requires `media:control`.
      parameters:
        - $ref: "#/components/parameters/MediaOrderId"
      responses:
        "200":
          description: Claimed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  media: { $ref: "#/components/schemas/QueueMediaItem" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409":
          description: "`queue_paused` - the media queue is paused."
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /media/{orderId}/finish:
    post:
      operationId: finishMediaItem
      tags: [Media queue]
      summary: Finish a media item
      description: >
        Promotes the media item from queue to history and clears the
        now-playing pointer when it points at this item. Fires
        `queue.media.finished`. Idempotent - finishing an already-gone item
        succeeds with `media: null`. Finishing means "this played" - if it
        didn't (your player failed), use
        [release](/api/reference/media-queue/releasemediaitem) to put it back
        instead. Requires `media:control`.
      parameters:
        - $ref: "#/components/parameters/MediaOrderId"
      responses:
        "200":
          description: Finished.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  media:
                    oneOf:
                      - $ref: "#/components/schemas/QueueMediaItem"
                      - type: "null"
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /media/{orderId}/release:
    post:
      operationId: releaseMediaItem
      tags: [Media queue]
      summary: Release a claimed media item back to the queue
      description: >
        The undo of [start](/api/reference/media-queue/startmediaitem), for when
        playback didn't go to plan - the player errored, the video wouldn't
        load, your process is shutting down mid-item. Drops the now-playing
        claim WITHOUT finishing: the item stays in the queue at its
        position, and it can be claimed again. Fires `queue.media.released`.
        Only drops a claim that actually points at this order id - never a
        different item's claim - and releasing something you don't hold is
        a safe no-op (`released: false`). If the item DID play, use
        [finish](/api/reference/media-queue/finishmediaitem) instead so it lands in
        history. Requires `media:control`.
      parameters:
        - $ref: "#/components/parameters/MediaOrderId"
      responses:
        "200":
          description: "Released (`released: false` when there was no claim to drop)."
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  released:
                    type: boolean
                    description: Whether a now-playing claim was actually dropped.
                  media:
                    oneOf:
                      - $ref: "#/components/schemas/QueueMediaItem"
                      - type: "null"
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /media/show:
    post:
      operationId: showMediaPlayer
      tags: [Media queue]
      summary: Show the media player
      description: >
        Make the media player visible on the overlay - the same switch as
        the dashboard's Controls tab. Fires `queue.media.shown`. Requires
        `media:control`.
      responses:
        "200":
          description: Player shown.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  visible: { type: boolean, const: true }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /media/hide:
    post:
      operationId: hideMediaPlayer
      tags: [Media queue]
      summary: Hide the media player
      description: >
        Hide the media player on the overlay. Playback state is untouched -
        hiding doesn't pause; pair with `/media/pause` if you want silence
        too. Fires `queue.media.hidden`. Requires `media:control`.
      responses:
        "200":
          description: Player hidden.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  visible: { type: boolean, const: false }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /tips:
    post:
      operationId: createManualTip
      tags: [Tipping]
      summary: Create a tip
      description: >
        Add a tip that TipPage didn't take payment for. It enters the TTS
        queue (and the media queue when `media_url` is given) and plays like
        any other tip, with TTS pre-rendered. These tips deliberately skip
        the word filter (the author is trusted). Fires `tip.created` with
        `source: "api"`.


        Two independent fields decide how the tip is counted:

        * **`source`** labels where the tip came from - a stable lower-case
          slug per platform (`kofi`, `youtube-superchat`, `ayupcc`). Reports
          list one row per distinct source. On its own it makes a **free**
          tip: shown and read out on stream, never counted as money.
        * **`paid: true`** says real money was processed on that platform
          (a Ko-fi payment, a Super Chat, a legacy tipping service you're
          bridging). The tip then counts as revenue on the streamer's
          overview and in their PDF reports under that source, climbs the
          leaderboard and moves the tip goal. Requires `source`.
          `reference` is your own transaction id for that payment, shown to
          the streamer for reconciliation.

        Neither field - a **manual tip**, exactly like the dashboard's
        manual-tip form: visible on stream, never in the money totals,
        itemised separately in reports.

        Requires `tips:create`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  maxLength: 22
                  description: The display name shown on stream.
                amount:
                  type: number
                  minimum: 0
                  maximum: 100000
                  description: Displayed amount, in the streamer's currency.
                message:
                  type: string
                  maxLength: 255
                media_url:
                  type: string
                  format: uri
                  description: Optional video to queue alongside (YouTube supported).
                media_start_time:
                  type: integer
                  minimum: 0
                  default: 0
                  description: Video start offset in seconds.
                source:
                  type: string
                  pattern: "^[a-z0-9][a-z0-9._-]{1,47}$"
                  description: >
                    Where the tip came from, as a lower-case slug (`kofi`,
                    `youtube-superchat`, `ayupcc`). A label only - pair it
                    with `paid: true` when money really moved there.
                  examples: ["kofi"]
                paid:
                  type: boolean
                  default: false
                  description: >
                    Real money was processed on `source`. Makes the tip count
                    as revenue (overview, reports, leaderboard, tip goal).
                    Requires `source`.
                reference:
                  type: string
                  maxLength: 128
                  description: >
                    Your own reference for the payment on that platform (a
                    transaction or order id). Requires `source`.
                  examples: ["kofi_txn_8f3a2c"]
              required: [name, amount]
      responses:
        "201":
          description: Tip queued.
          content:
            application/json:
              schema:
                type: object
                properties:
                  tip:
                    allOf:
                      - $ref: "#/components/schemas/QueueTip"
                    description: >
                      The tip as `GET /tts/queue` lists it. `tts_url` is
                      `null` here - the audio is pre-rendered in the
                      background (`tip.tts_ready`). `source` is `api`,
                      `external_source` / `external_ref` / `is_paid` echo
                      what you sent.
                  media_queued:
                    type: boolean
                    description: Whether a media item was queued alongside.
        "400":
          description: Validation failed (name/amount/message/media URL).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /alerts/history:
    get:
      operationId: getAlertHistory
      tags: [Alerts]
      summary: Alert history
      description: >
        Platform alerts, newest first. By default the finished ones: every
        alert the overlay played or that was skipped. With `status=all`,
        every platform event as it happened - those still waiting for an
        overlay (`waiting`), those the live alert box never showed because
        the type is off or under its minimum (`not_played`), and every
        channel-point redemption, whether or not a box alerted on it (a
        redemption that never alerted is a `channel_points` row whose `id`
        is Twitch's redemption id, status `not_played`, nothing to replay).
        A tip-filter-blocked alert is never listed. `limit` up to 200.
        Requires `tts:read`.
      parameters:
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 200, default: 50 }
        - name: status
          in: query
          schema: { type: string, enum: [finished, all], default: finished }
          description: "`all` = every platform event, not only the finished ones."
        - name: before
          in: query
          schema: { type: string, format: date-time }
          description: Cursor - a `happened_at` from a previous page (`next_cursor`). Returns rows strictly older than it.
      responses:
        "200":
          description: One page of alerts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  alerts:
                    type: array
                    items: { $ref: "#/components/schemas/Alert" }
                  has_more: { type: boolean }
                  next_cursor:
                    type: [string, "null"]
                    description: Pass as `?before=` to fetch the next page.
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /alerts/now:
    get:
      operationId: getAlertNow
      tags: [Alerts]
      summary: The alert on screen right now
      description: >
        What the overlay's alert box is showing, as the overlay reported
        it, or `null` between alerts. Requires `tts:read`.
      responses:
        "200":
          description: The current alert, or none.
          content:
            application/json:
              schema:
                type: object
                properties:
                  alert:
                    oneOf:
                      - $ref: "#/components/schemas/CurrentAlert"
                      - type: "null"
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /alerts/skip:
    post:
      operationId: skipAlert
      tags: [Alerts]
      summary: Skip the alert on screen
      description: >
        Cut the alert the overlay is showing (a gift bomb reading every
        recipient, a long raid). Pass `event_id` to pin the request to
        THAT alert, so one landing after it ended can't skip the next.
        The event is marked skipped and never replayed on a reconnect.
        Requires `tts:control`.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                event_id:
                  type: string
                  description: The alert to skip (`ev_...`, from `/alerts/now`). Omit to skip whatever is on screen.
      responses:
        "200":
          description: Skipped.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean, const: true }
                  skipped_event_id: { type: [string, "null"] }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "409":
          description: >
            `not_displaying` - no alert is on screen, or the one named has
            already finished. `skip_disabled` - skipping is locked on this
            channel.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /alerts/{id}/replay:
    post:
      operationId: replayAlert
      tags: [Alerts]
      summary: Replay an alert from the history
      description: >
        Play an alert again through the connected overlay's alert box,
        exactly like the original: a new event (`event_id`) with
        `replay_of` set, marked as a replay on screen. No webhook, no
        sub-reward credit, no chat announce, no filter run. With no overlay
        connected the replay is parked (`parked: true`) and plays on the
        next connect. Requires `tts:control`.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
          description: The alert's `id` from the history (`ev_...`).
      responses:
        "200":
          description: Replaying (or parked).
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean, const: true }
                  event_id: { type: string, description: The replay's own event id. }
                  replay_of: { type: string }
                  parked:
                    type: boolean
                    description: No overlay is connected - it plays on the next connect.
                  overlay:
                    type: [object, "null"]
                    description: The overlay whose alert box will show it.
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404":
          description: No such alert in the history.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "409":
          description: >
            `overlay_wont_show` - the connected overlay's alert box would not
            show it (`reason` = type_off | platform_off | under_minimum |
            reward_not_listed, `overlay` names it). `blocked` - the original
            was blocked by the tip filter.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /tipping:
    get:
      operationId: getTippingStatus
      tags: [Tipping]
      summary: Is tipping open
      description: >
        Whether the tip page is accepting new tips right now. Any valid
        key - this is visible on the public tip page anyway.
      responses:
        "200":
          description: Tipping status.
          content:
            application/json:
              schema:
                type: object
                properties:
                  open: { type: boolean }
                  closed_at:
                    type: [string, "null"]
                    format: date-time
                    description: When tipping was last closed (null while open).
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /tipping/open:
    post:
      operationId: openTipping
      tags: [Tipping]
      summary: Open tipping
      description: >
        Start accepting new tips again. Fires the `tipping.opened` webhook.
        Requires `tipping:control`.
      responses:
        "200":
          description: Tipping is open.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  open: { type: boolean, const: true }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /tipping/close:
    post:
      operationId: closeTipping
      tags: [Tipping]
      summary: Close tipping
      description: >
        Stop accepting new tips: the tip page shows its closed state and the
        tip endpoint rejects new checkouts server-side. A viewer already
        mid-payment when tipping closes still completes normally and their
        tip lands in the queue, and tips already queued are unaffected.
        Fires the `tipping.closed` webhook. Requires `tipping:control`.
      responses:
        "200":
          description: Tipping is closed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  open: { type: boolean, const: false }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /ai-voices:
    get:
      operationId: listAiVoices
      tags: [AI voices]
      summary: List AI voices
      description: >
        The feature's current state, every voice this account can offer
        (TipPage's own, the ones this streamer cloned, and voices other
        streamers published), and this month's usage. Being listed IS
        being offered to donors - the per-voice enable/disable calls add a
        voice to and remove it from this list. Voice `id`s are stable
        (`voi_...`). `min_amount` is the tip amount that unlocks AI
        voices on the tip page. Requires `ai_voices:manage`. Closed beta:
        answers `404` unless AI voices are enabled for your account.
      responses:
        "200":
          description: Feature state, catalog, and usage.
          content:
            application/json:
              schema:
                type: object
                properties:
                  enabled:
                    type: boolean
                    description: The master switch - whether donors are offered AI voices.
                  mode:
                    type: string
                    enum: [optional, exclusive]
                    description: >
                      `optional` keeps the standard voice as the default;
                      `exclusive` makes every tip message use an AI voice.
                  min_amount:
                    type: number
                    description: Minimum tip amount that unlocks AI voices.
                  usage:
                    type: object
                    description: >
                      This month's generation, for information only - there is
                      no monthly allowance to spend down.
                    properties:
                      month: { type: string, example: "2026-09" }
                      characters_spoken: { type: integer }
                      seconds_generated: { type: number }
                      generations: { type: integer }
                  voices:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string, example: "voi_9c1f0a2b7d4e5f60" }
                        label: { type: string, example: "Narrator" }
                        hint: { type: string, example: "Warm documentary read" }
                        gender: { type: string, enum: [m, f, x] }
                        sample_url:
                          type: string
                          description: A short sample clip of the voice.
                        reference_seconds:
                          type: integer
                          description: >
                            Seconds of reference audio behind the voice. A
                            message is spoken in one generation and every
                            voice in it shares that generation's budget, so
                            these add up.
                        source:
                          type: string
                          enum: [platform, own, shared]
                          description: >
                            `platform` is a TipPage voice, `own` one this
                            streamer cloned, `shared` one another streamer
                            published.
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /ai-voices/enable:
    post:
      operationId: enableAiVoices
      tags: [AI voices]
      summary: Enable AI voices
      description: >
        Flip the master switch on - donors see the AI voices option on the
        tip page. Same setting as the dashboard toggle. Requires
        `ai_voices:manage`. TipPage+: answers `404` unless AI voices are
        enabled for your account.
      responses:
        "200":
          description: AI voices are on.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  enabled: { type: boolean, const: true }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /ai-voices/disable:
    post:
      operationId: disableAiVoices
      tags: [AI voices]
      summary: Disable AI voices
      description: >
        Flip the master switch off - the AI voices option disappears from
        the tip page (tips already queued keep their AI audio). Requires
        `ai_voices:manage`. TipPage+: answers `404` unless AI voices are
        enabled for your account.
      responses:
        "200":
          description: AI voices are off.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  enabled: { type: boolean, const: false }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /ai-voices/{voiceId}/enable:
    post:
      operationId: enableAiVoice
      tags: [AI voices]
      summary: Enable one voice
      description: >
        Add a single voice to the set donors can pick from: a TipPage voice
        you had disabled, or another streamer's published voice (an
        unpublished one answers `404 unknown_voice`). Your own cloned
        voices are always offered and answer `400 own_voice`. Requires
        `ai_voices:manage`. TipPage+: answers `404` unless AI voices are
        enabled for your account.
      parameters:
        - name: voiceId
          in: path
          required: true
          schema: { type: string }
          description: The voice's `id` from `GET /ai-voices`.
      responses:
        "200":
          description: The voice is enabled.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  id: { type: string }
                  enabled: { type: boolean, const: true }
                  enabled_voices:
                    type: integer
                    description: How many voices the account offers after this change.
        "400":
          description: That is one of your own cloned voices - it is always offered.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
                  code: { type: string, const: own_voice }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /ai-voices/{voiceId}/disable:
    post:
      operationId: disableAiVoice
      tags: [AI voices]
      summary: Disable one voice
      description: >
        Remove a single voice from the set donors can pick from: hide a
        TipPage voice, or drop another streamer's voice you had added
        (whether or not it is still published). Your own cloned voices
        can't be disabled, only deleted from the dashboard - `400
        own_voice`. There is no last-voice rule; turn the whole feature
        off with `POST /ai-voices/disable`. Requires `ai_voices:manage`.
        TipPage+: answers `404` unless AI voices are enabled for your
        account.
      parameters:
        - name: voiceId
          in: path
          required: true
          schema: { type: string }
          description: The voice's `id` from `GET /ai-voices`.
      responses:
        "200":
          description: The voice is disabled.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  id: { type: string }
                  enabled: { type: boolean, const: false }
                  enabled_voices:
                    type: integer
                    description: How many voices the account offers after this change.
        "400":
          description: That is one of your own cloned voices - delete it from the dashboard instead.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
                  code: { type: string, const: own_voice }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /leaderboard:
    get:
      operationId: getLeaderboard
      tags: [Tipping]
      summary: Top supporters
      description: >
        The top 10 supporters by summed tip amount - the same data as the
        public leaderboard page. Any valid key.
      parameters:
        - name: days
          in: query
          schema:
            type: string
            enum: ["1", "7", "30", "all"]
          description: Time window. Omit (or pass `all`) for all-time.
      responses:
        "200":
          description: Ranked supporters, highest total first.
          content:
            application/json:
              schema:
                type: object
                properties:
                  days:
                    type: [integer, "null"]
                    description: The applied window (null = all-time).
                  leaders:
                    type: array
                    items:
                      type: object
                      properties:
                        name: { type: string }
                        total: { type: number }
        "400":
          description: Invalid days value.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /viewers:
    get:
      operationId: listViewers
      tags: [Viewers]
      summary: List signed-in viewers
      description: >
        Every account that has signed in to the tip page (Twitch or Kick),
        most recently signed-in first, each with the person's sub-reward
        credit balance (summed across their linked accounts, so a viewer
        who signed in here with both shows two rows with the same balance).
        Viewers who have never signed in don't appear - signing in is what
        creates a viewer. Requires `viewers:read`.
      parameters:
        - $ref: "#/components/parameters/HistoryLimit"
        - name: before
          in: query
          schema: { type: string }
          description: >
            Cursor - the `next_cursor` from a previous page. Opaque
            (base64url of the sign-in time + platform + id the page ended
            on); a malformed one answers `400 bad_cursor`. Returns viewers
            who signed in before that point.
      responses:
        "200":
          description: One page of viewers, newest sign-up first.
          content:
            application/json:
              schema:
                type: object
                properties:
                  viewers:
                    type: array
                    items:
                      allOf:
                        - $ref: "#/components/schemas/Viewer"
                        - type: object
                          properties:
                            credits: { $ref: "#/components/schemas/CreditBalance" }
                  has_more: { type: boolean }
                  next_cursor:
                    type: [string, "null"]
                    description: Pass as `before` to fetch the next page.
        "400":
          description: Unknown `before` cursor (`bad_cursor`).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /viewers/{user}:
    get:
      operationId: getViewer
      tags: [Viewers]
      summary: Look up any viewer
      description: >
        One person and their standing on this channel, per platform account
        - signed in to the tip page or not. `viewer` is the person (whether
        and when they signed in here); `platforms.twitch` and
        `platforms.kick` are their account on each platform with its
        standing on this channel there - follow, current sub, best known sub
        length, moderator, VIP and chat activity - or `null` where the
        person has no known account on that platform. `credits`, `grants`
        and `usage` are the sub-rewards picture (credits are earned by
        subbing, so someone who never signed in can hold them too). A
        person who linked both accounts gets both blocks, and everything is
        read across the pair. Requires `viewers:read`.


        `{user}` takes `twitch:<id or login>`, `kick:<id or login>`, a
        viewer id (`v_...`, as `viewer.id` answers), or a bare id or login
        - tried against the channel's signed-in viewers first, then as a
        Twitch account, then a Kick one.


        **Sub length.** Twitch's API has no way to ask how long someone has
        been subscribed, so `sub_months` is the most TipPage has seen: the
        subscriber badge on their latest chat line (needs the chat bot on
        for that platform) or their latest shared resub, whichever says
        more, with `sub_months_at` saying when it was seen - add the months
        since then if they are still `subscribed`. On Kick it comes from
        Kick directly. `null` = never seen.


        **Moderator and VIP** are read live: Twitch with the owner's grant
        (`null` when the channel owner has not reconnected since those
        scopes were added), Kick from kick.com's channel record.
      parameters:
        - name: user
          in: path
          required: true
          schema: { type: string }
          description: >
            `twitch:<id or login>`, `kick:<id or login>`, `v_...`, or a
            bare id or login (see above).
      responses:
        "200":
          description: The viewer.
          content:
            application/json:
              schema:
                type: object
                properties:
                  viewer:
                    $ref: "#/components/schemas/ViewerPerson"
                  platforms:
                    type: object
                    description: >
                      The person's account per platform, with its standing
                      on this channel there. `null` = no known account on
                      that platform.
                    properties:
                      twitch:
                        oneOf:
                          - $ref: "#/components/schemas/ViewerPlatform"
                          - type: "null"
                      kick:
                        oneOf:
                          - $ref: "#/components/schemas/ViewerPlatform"
                          - type: "null"
                    required: [twitch, kick]
                  credits:
                    allOf:
                      - $ref: "#/components/schemas/CreditBalance"
                      - type: object
                        properties:
                          pending:
                            type: integer
                            description: >
                              Gift-sub credits waiting for their first
                              sign-in to convert (informational - already
                              part of neither `total` nor `available`).
                  grants:
                    type: array
                    description: The award ledger, newest first (up to 100 rows).
                    items:
                      type: object
                      properties:
                        platform:
                          type: string
                          enum: [twitch, kick]
                          description: Which of the person's accounts this grant landed on.
                        platform_user_id: { type: string }
                        source:
                          type: string
                          enum: [sub_tier1, sub_tier2, sub_tier3, gift_sub, manual]
                          description: >
                            What earned the credits. `manual` covers both
                            dashboard and API grants.
                        credits: { type: integer, description: Credits in this grant. }
                        credits_used: { type: integer, description: How many of them were spent. }
                        awarded_at: { type: string, format: date-time }
                  usage:
                    type: object
                    description: Sub-reward messages; spent credits are `credits.used`.
                    properties:
                      queued: { type: integer, description: Sub-reward messages waiting in the TTS queue right now. }
                      played: { type: integer, description: Sub-reward messages that played on stream. }
                      last_used_at: { type: [string, "null"], format: date-time }
                required: [viewer, platforms, credits, grants, usage]
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404":
          description: No Twitch or Kick account matches (`user_not_found`), or the channel isn't connected to that platform.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "409": { $ref: "#/components/responses/AmbiguousViewer" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /viewers/{user}/rewards:
    get:
      operationId: listViewerRewards
      tags: [Viewers]
      summary: A viewer's sub-reward history
      description: >
        The viewer's played sub-reward messages, most recent first - the
        same shape as `/tts/history`, filtered to this viewer's sub
        rewards. Replays by the streamer are excluded; a sub reward still
        waiting to play shows up in `/tts/queue` like any other tip.
        Requires `viewers:read`.
      parameters:
        - $ref: "#/components/parameters/ViewerIdent"
        - $ref: "#/components/parameters/HistoryLimit"
        - $ref: "#/components/parameters/HistoryBefore"
      responses:
        "200":
          description: One page of played sub rewards.
          content:
            application/json:
              schema:
                type: object
                properties:
                  viewer: { $ref: "#/components/schemas/Viewer" }
                  rewards:
                    type: array
                    items: { $ref: "#/components/schemas/HistoryTip" }
                  has_more: { type: boolean }
                  next_cursor: { type: [string, "null"] }
        "400":
          description: Unknown `before` cursor (`bad_cursor`).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/ViewerNotSignedIn" }
        "409": { $ref: "#/components/responses/AmbiguousViewer" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /viewers/{user}/credits/grant:
    post:
      operationId: grantViewerCredits
      tags: [Viewers]
      summary: Grant credits
      description: >
        Grants sub-reward credits to a signed-in viewer - the same
        operation as the dashboard's grant form; the credits appear on the
        viewer's tip page immediately. Credits can only be granted to
        viewers who have signed in at least once: an unknown name or id
        answers `404 viewer_not_signed_in`, and nothing is granted.
        Requires `viewers:manage`.
      parameters:
        - $ref: "#/components/parameters/ViewerIdent"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: integer
                  minimum: 1
                  maximum: 100
                  description: Credits to grant.
              required: [amount]
      responses:
        "200":
          description: Granted; the fresh balance is returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean, const: true }
                  granted: { type: integer }
                  viewer: { $ref: "#/components/schemas/Viewer" }
                  credits: { $ref: "#/components/schemas/CreditBalance" }
        "400":
          description: "`amount` isn't an integer from 1 to 100 (`bad_request`)."
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/ViewerNotSignedIn" }
        "409": { $ref: "#/components/responses/AmbiguousViewer" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /viewers/{user}/credits/revoke:
    post:
      operationId: revokeViewerCredits
      tags: [Viewers]
      summary: Revoke credits
      description: >
        Takes unused sub-reward credits away from a viewer. Only unused
        credits are revocable - credits already spent on a message are
        gone. Asking for more than the viewer has available revokes
        nothing and answers `400 insufficient_credits` with the actual
        available count. Requires `viewers:manage`.
      parameters:
        - $ref: "#/components/parameters/ViewerIdent"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: integer
                  minimum: 1
                  description: Credits to revoke.
              required: [amount]
      responses:
        "200":
          description: Revoked; the fresh balance is returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean, const: true }
                  revoked: { type: integer }
                  viewer: { $ref: "#/components/schemas/Viewer" }
                  credits: { $ref: "#/components/schemas/CreditBalance" }
        "400":
          description: >
            Bad `amount` (`bad_request`), or more than the viewer's unused
            balance (`insufficient_credits` - the response includes
            `available`).
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Error"
                  - type: object
                    properties:
                      available:
                        type: integer
                        description: Unused credits actually available (on `insufficient_credits`).
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/ViewerNotSignedIn" }
        "409": { $ref: "#/components/responses/AmbiguousViewer" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /channel-points/rewards:
    get:
      operationId: listRewards
      tags: [Channel points]
      summary: List TipPage-created rewards
      description: >
        Every channel point reward TipPage created on the channel - the
        ones whose redemptions can be fulfilled or canceled here. Rewards
        the streamer made on Twitch or with another tool are not listed.
      responses:
        "200":
          description: The rewards.
          content:
            application/json:
              schema:
                type: object
                properties:
                  rewards:
                    type: array
                    items: { $ref: "#/components/schemas/ChannelPointReward" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }
    post:
      operationId: createReward
      tags: [Channel points]
      summary: Create a reward
      description: >
        Creates a custom channel point reward on the streamer's Twitch
        channel, owned by TipPage, so its redemptions can be resolved with
        fulfill / cancel. TipPage runs no actions on it - redemptions wait
        unfulfilled in the Twitch rewards queue and arrive on the
        `twitch.channel_point_redemption` webhook with `is_managed: true`.
        Needs a Twitch Affiliate or Partner channel.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [title, cost]
              properties:
                title: { type: string, maxLength: 45, description: Unique among the channel's rewards. }
                cost: { type: integer, minimum: 1, description: Channel points. }
                prompt: { type: string, maxLength: 200, description: Shown to viewers on Twitch. }
                is_user_input_required:
                  type: boolean
                  default: false
                  description: Twitch asks the viewer for text when they redeem it.
                background_color: { type: string, pattern: "^#[0-9A-Fa-f]{6}$", example: "#9147FF" }
      responses:
        "201":
          description: Created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reward: { $ref: "#/components/schemas/ChannelPointReward" }
        "400":
          description: >
            Invalid body (`bad_request`), a reward with that title already
            exists (`duplicate_title`), Twitch refused the settings
            (`twitch_rejected`), or the account has no Twitch channel
            (`twitch_not_linked`).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403":
          description: The key lacks the scope (`missing_scope`), or the channel is not Affiliate or Partner (`not_eligible`).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "409":
          description: The streamer has to reconnect Twitch on the dashboard (`twitch_reauth`).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "429": { $ref: "#/components/responses/RateLimited" }
        "502": { description: Twitch was unreachable or errored - retry shortly. }

  /channel-points/rewards/{rewardId}:
    delete:
      operationId: deleteReward
      tags: [Channel points]
      summary: Delete a reward
      description: >
        Deletes a TipPage-created reward from the Twitch channel. Rewards
        with TipPage actions set up on the dashboard (`has_actions`) are
        removed there instead.
      parameters:
        - name: rewardId
          in: path
          required: true
          schema: { type: string, example: cpr_0123456789abcdef }
          description: The reward's `id`.
      responses:
        "200":
          description: Deleted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean, const: true }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409":
          description: The reward has dashboard actions (`reward_has_actions`), or Twitch needs reconnecting (`twitch_reauth`).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "429": { $ref: "#/components/responses/RateLimited" }
        "502": { description: Twitch was unreachable or errored - retry shortly. }

  /channel-points/redemptions/{redemptionId}/fulfill:
    post:
      operationId: fulfillRedemption
      tags: [Channel points]
      summary: Mark a redemption fulfilled
      description: >
        Resolves the redemption as FULFILLED on Twitch - the viewer's points
        stay spent and the redemption leaves the Twitch rewards queue. Call
        this when your automation completed the redeemed action. Requires
        `channel_points:manage` and a TipPage-managed reward. Idempotent:
        repeating the call returns `already_resolved: true`.
      parameters:
        - $ref: "#/components/parameters/RedemptionId"
      responses:
        "200": { $ref: "#/components/responses/RedemptionResolved" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { description: Unknown redemption id for this channel. }
        "409":
          description: >
            Not resolvable - `code` says why: `reward_not_managed` (reward
            wasn't created by TipPage), `already_resolved` (resolved the
            other way), `song_request_active` (the song-request flow owns
            it), or `twitch_rejected` (Twitch refused the update).
        "429": { $ref: "#/components/responses/RateLimited" }
        "502": { description: Twitch was unreachable or errored - retry shortly. }

  /channel-points/redemptions/{redemptionId}/cancel:
    post:
      operationId: cancelRedemption
      tags: [Channel points]
      summary: Cancel a redemption (refund the points)
      description: >
        Resolves the redemption as CANCELED on Twitch - the viewer's channel
        points are refunded. Call this when your automation couldn't complete
        the redeemed action. Requires `channel_points:manage` and a
        TipPage-managed reward. Idempotent: repeating the call returns
        `already_resolved: true`.
      parameters:
        - $ref: "#/components/parameters/RedemptionId"
      responses:
        "200": { $ref: "#/components/responses/RedemptionResolved" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { description: Unknown redemption id for this channel. }
        "409":
          description: >
            Not resolvable - `code` says why: `reward_not_managed`,
            `already_resolved`, `song_request_active`, or `twitch_rejected`.
        "429": { $ref: "#/components/responses/RateLimited" }
        "502": { description: Twitch was unreachable or errored - retry shortly. }

  /webhook-endpoints:
    get:
      operationId: listWebhookEndpoints
      tags: [Webhook endpoints]
      summary: List endpoints
      description: Requires `webhooks:manage`. Signing secrets are never listed.
      responses:
        "200":
          description: All endpoints for this streamer.
          content:
            application/json:
              schema:
                type: object
                properties:
                  endpoints:
                    type: array
                    items: { $ref: "#/components/schemas/WebhookEndpoint" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }
    post:
      operationId: createWebhookEndpoint
      tags: [Webhook endpoints]
      summary: Add an endpoint
      description: >
        Registers a delivery URL. The response contains the signing `secret`
        **exactly once** - store it immediately. URLs must be public
        `https://`; private/internal addresses are rejected. Max 10 endpoints.
        Requires `webhooks:manage`.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/WebhookEndpointCreate" }
      responses:
        "201":
          description: Created. `secret` is shown only here (and on rotation).
          content:
            application/json:
              schema:
                type: object
                properties:
                  endpoint: { $ref: "#/components/schemas/WebhookEndpoint" }
                  secret:
                    type: string
                    examples: ["whsec_9f8e7d..."]
        "400":
          description: Invalid URL, events, or endpoint limit reached.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /webhook-endpoints/{endpointId}:
    get:
      operationId: getWebhookEndpoint
      tags: [Webhook endpoints]
      summary: Get one endpoint
      description: Requires `webhooks:manage`.
      parameters:
        - $ref: "#/components/parameters/EndpointId"
      responses:
        "200":
          description: The endpoint.
          content:
            application/json:
              schema:
                type: object
                properties:
                  endpoint: { $ref: "#/components/schemas/WebhookEndpoint" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
    patch:
      operationId: updateWebhookEndpoint
      tags: [Webhook endpoints]
      summary: Update an endpoint
      description: >
        Any subset of url / description / events / is_active. Re-enabling a
        disabled endpoint clears its failure state. Requires `webhooks:manage`.
      parameters:
        - $ref: "#/components/parameters/EndpointId"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/WebhookEndpointUpdate" }
      responses:
        "200":
          description: Updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  endpoint: { $ref: "#/components/schemas/WebhookEndpoint" }
        "400":
          description: Invalid URL or events.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
    delete:
      operationId: deleteWebhookEndpoint
      tags: [Webhook endpoints]
      summary: Delete an endpoint
      description: Deliveries stop immediately; history is removed. Requires `webhooks:manage`.
      parameters:
        - $ref: "#/components/parameters/EndpointId"
      responses:
        "200": { $ref: "#/components/responses/Success" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /webhook-endpoints/{endpointId}/rotate-secret:
    post:
      operationId: rotateWebhookSecret
      tags: [Webhook endpoints]
      summary: Rotate the signing secret
      description: >
        Mints a new `whsec_` and returns it once. The old secret stops
        validating immediately. Requires `webhooks:manage`.
      parameters:
        - $ref: "#/components/parameters/EndpointId"
      responses:
        "200":
          description: The new secret - shown only here.
          content:
            application/json:
              schema:
                type: object
                properties:
                  secret: { type: string, examples: ["whsec_1a2b3c..."] }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /webhook-endpoints/{endpointId}/ping:
    post:
      operationId: pingWebhookEndpoint
      tags: [Webhook endpoints]
      summary: Send a test event
      description: >
        Sends a signed `ping` envelope straight to the endpoint (no retries,
        not recorded in deliveries) and reports what happened. Requires
        `webhooks:manage`.
      parameters:
        - $ref: "#/components/parameters/EndpointId"
      responses:
        "200":
          description: Attempt result (a failing endpoint still returns 200 here).
          content:
            application/json:
              schema:
                type: object
                properties:
                  delivered: { type: boolean }
                  http_status:
                    type: [integer, "null"]
                    description: The endpoint's HTTP status, when it answered.
                  error: { type: [string, "null"] }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /webhook-endpoints/{endpointId}/deliveries:
    get:
      operationId: listWebhookDeliveries
      tags: [Webhook endpoints]
      summary: Recent deliveries
      description: Most recent first. Requires `webhooks:manage`.
      parameters:
        - $ref: "#/components/parameters/EndpointId"
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 100, default: 50 }
      responses:
        "200":
          description: Delivery attempts for this endpoint.
          content:
            application/json:
              schema:
                type: object
                properties:
                  deliveries:
                    type: array
                    items: { $ref: "#/components/schemas/WebhookDelivery" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /webhook-deliveries/{deliveryId}/redeliver:
    post:
      operationId: redeliverWebhookDelivery
      tags: [Webhook endpoints]
      summary: Redeliver a delivery
      description: >
        Re-queues a delivered or failed delivery for immediate retry with the
        **same event id and byte-identical payload**. Returns `409
        attempt_in_progress` while an automatic attempt for the row is
        mid-flight. Requires `webhooks:manage`.
      parameters:
        - name: deliveryId
          in: path
          required: true
          schema: { type: string }
          description: Delivery id (`wd_...`) from the deliveries list.
      responses:
        "200": { $ref: "#/components/responses/Success" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409":
          description: >
            An automatic delivery attempt for this row is mid-flight
            (`attempt_in_progress`) - check its result in a moment.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /timers:
    get:
      operationId: listChatTimers
      tags: [Chat timers]
      summary: List timers
      description: All timers, enabled or not. Requires `timers:manage`.
      responses:
        "200":
          description: All timers for this streamer.
          content:
            application/json:
              schema:
                type: object
                properties:
                  timers:
                    type: array
                    items: { $ref: "#/components/schemas/ChatTimer" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }
    post:
      operationId: createChatTimer
      tags: [Chat timers]
      summary: Create a timer
      description: >
        A new timer posts for the first time one interval from creation, not
        immediately. Messages can't start with `/` or `!`, and support the
        same template variables as custom commands minus the argument ones
        (`{channel}`, `{pick:a|b|c}`, `{random:1-100}`, `{list:name}`,
        `{uptime}`, `{ai:...}`, ... - see
        https://docs.tippage.com/chat-bot/variables). Max 20 timers.
        Requires `timers:manage`.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/ChatTimerCreate" }
      responses:
        "201":
          description: Created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  timer: { $ref: "#/components/schemas/ChatTimer" }
        "400":
          description: Invalid fields (`invalid_timer`) or timer limit reached (`limit_reached`).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /timers/{timerId}:
    get:
      operationId: getChatTimer
      tags: [Chat timers]
      summary: Get one timer
      description: Requires `timers:manage`.
      parameters:
        - $ref: "#/components/parameters/TimerId"
      responses:
        "200":
          description: The timer.
          content:
            application/json:
              schema:
                type: object
                properties:
                  timer: { $ref: "#/components/schemas/ChatTimer" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
    patch:
      operationId: updateChatTimer
      tags: [Chat timers]
      summary: Update a timer
      description: >
        Any subset of fields - `{"enabled": false}` benches a timer without
        deleting it. Changing `interval_minutes` / `interval_max_minutes`
        restarts the timer's schedule from now. Requires `timers:manage`.
      parameters:
        - $ref: "#/components/parameters/TimerId"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/ChatTimerUpdate" }
      responses:
        "200":
          description: Updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  timer: { $ref: "#/components/schemas/ChatTimer" }
        "400":
          description: Invalid fields.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
    delete:
      operationId: deleteChatTimer
      tags: [Chat timers]
      summary: Delete a timer
      description: The bot stops posting the message immediately. Requires `timers:manage`.
      parameters:
        - $ref: "#/components/parameters/TimerId"
      responses:
        "200": { $ref: "#/components/responses/Success" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /counters:
    get:
      operationId: listCounters
      tags: [Counters]
      summary: List counters
      description: All counters, name-ordered. Requires `counters:manage`.
      responses:
        "200":
          description: All counters for this streamer.
          content:
            application/json:
              schema:
                type: object
                properties:
                  counters:
                    type: array
                    items: { $ref: "#/components/schemas/Counter" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /counters/{name}:
    parameters:
      - name: name
        in: path
        required: true
        schema: { type: string, pattern: "^[a-z0-9_-]{1,64}$" }
        description: The counter's name.
    get:
      operationId: getCounter
      tags: [Counters]
      summary: Read a counter
      description: Requires `counters:manage`.
      responses:
        "200":
          description: The counter.
          content:
            application/json:
              schema:
                type: object
                properties:
                  counter: { $ref: "#/components/schemas/Counter" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
    put:
      operationId: setCounter
      tags: [Counters]
      summary: Set a counter
      description: >
        Sets an absolute value, creating the counter if it doesn't exist
        yet. Overlay labels bound to it update live and `counter.updated`
        fires. Requires `counters:manage`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [value]
              properties:
                value: { type: integer, description: "New absolute value." }
      responses:
        "200":
          description: The counter after the write.
          content:
            application/json:
              schema:
                type: object
                properties:
                  counter: { $ref: "#/components/schemas/Counter" }
        "400":
          description: Invalid name or value.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }
    delete:
      operationId: deleteCounter
      tags: [Counters]
      summary: Delete a counter
      description: >
        The value is lost; `{count}` in a command recreates it from zero
        on next use. Requires `counters:manage`.
      responses:
        "200":
          description: Deleted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /counters/{name}/increment:
    post:
      operationId: incrementCounter
      tags: [Counters]
      summary: Increment a counter
      description: >
        Adds `by` (default 1, may be negative), creating the counter at
        `by` on first use - the same semantics as `{count}` in a chat
        command. Requires `counters:manage`.
      parameters:
        - name: name
          in: path
          required: true
          schema: { type: string, pattern: "^[a-z0-9_-]{1,64}$" }
          description: The counter's name.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                by:
                  type: integer
                  default: 1
                  description: Non-zero; negative decrements.
      responses:
        "200":
          description: The counter after the increment.
          content:
            application/json:
              schema:
                type: object
                properties:
                  counter: { $ref: "#/components/schemas/Counter" }
        "400":
          description: Invalid name or value.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /bot:
    get:
      operationId: getBotStatus
      tags: [Chat bot]
      summary: Bot status
      description: >
        Whether the chat bot is switched on, and per platform (Twitch, Kick)
        the chat it's in and the identity it speaks as - on Twitch the shared
        TipPageBot or the streamer's linked custom bot, on Kick always the
        TipPage app account. A platform the streamer hasn't connected is
        `null`. Any valid key.
      responses:
        "200":
          description: Bot status.
          content:
            application/json:
              schema:
                type: object
                properties:
                  bot:
                    type: object
                    properties:
                      enabled:
                        type: boolean
                        description: The bot is switched on in at least one connected chat (see `platforms` for each).
                      platforms:
                        type: object
                        description: One entry per platform - `null` when the streamer has no channel there.
                        properties:
                          twitch:
                            oneOf:
                              - $ref: "#/components/schemas/BotPlatform"
                              - type: "null"
                          kick:
                            oneOf:
                              - $ref: "#/components/schemas/BotPlatform"
                              - type: "null"
              examples:
                twitchAndKick:
                  summary: Custom bot on Twitch, app account on Kick
                  value:
                    bot:
                      enabled: true
                      platforms:
                        twitch:
                          enabled: true
                          channel: somestreamer
                          identity: { type: custom, login: somebot, display_name: SomeBot }
                        kick:
                          enabled: false
                          channel: somestreamer
                          identity: { type: default, login: tippagebot, display_name: TipPageBot }
                twitchOnly:
                  summary: No Kick channel connected
                  value:
                    bot:
                      enabled: true
                      platforms:
                        twitch:
                          enabled: true
                          channel: somestreamer
                          identity: { type: default, login: tippagebot, display_name: TipPageBot }
                        kick: null
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /chat/messages:
    post:
      operationId: sendChatMessage
      tags: [Chat bot]
      summary: Send a chat message
      description: >
        The bot says your message in the streamer's chat - every connected
        chat by default, or just Twitch or Kick with `platform` - spoken
        by the same identity as every other bot line (TipPageBot or the
        linked custom bot on Twitch; the TipPage account on Kick). Sent
        verbatim - no template variables - and it can't start with `/` or
        `!`, so the bot never runs slash commands or triggers other bots.
        Own rate limit on top of the global ones: 20 messages per 30
        seconds per streamer, shared across all keys. Requires `chat:write`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
                  maxLength: 500
                  description: What the bot says. Can't start with `/` or `!`.
                platform:
                  type: string
                  enum: [twitch, kick, all]
                  default: all
                  description: Which chat to speak in. `all` = every chat the streamer has connected.
              required: [message]
      responses:
        "200": { $ref: "#/components/responses/Success" }
        "400":
          description: >
            Missing message (`bad_request`), over 500 characters
            (`message_too_long`), or disallowed content
            (`message_disallowed`).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "409":
          description: >
            The bot can't speak right now: switched off in the dashboard
            (`bot_disabled`), no connected channel on the requested
            platform, or not connected to the channel yet
            (`bot_unavailable` - transient when the channel exists, retry shortly).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "429": { $ref: "#/components/responses/RateLimited" }
        "502":
          description: The chat gateway is unreachable (`gateway_unavailable`) - retry shortly.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }

  /commands:
    get:
      operationId: listCustomCommands
      tags: [Chat bot]
      summary: List custom commands
      description: All custom commands, enabled or not. Requires `commands:manage`.
      responses:
        "200":
          description: The streamer's custom commands.
          content:
            application/json:
              schema:
                type: object
                properties:
                  commands:
                    type: array
                    items: { $ref: "#/components/schemas/CustomCommand" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }
    post:
      operationId: createCustomCommand
      tags: [Chat bot]
      summary: Create a command
      description: >
        `name` is the trigger without the `!` prefix; the bot's built-in
        triggers are reserved. Responses support the same template
        variables as the dashboard's Chat bot page - `{user}`, `{touser}`,
        `{args}`, `{arg:N}`, `{pick:a|b|c}`, `{random:1-100}`, `{list:name}`,
        `{if:...}`, `{repeat:N|...}`, `{uptime}`, `{ai:...}` and more, and
        variables nest (full reference:
        https://docs.tippage.com/chat-bot/variables). Response lists
        themselves are managed in the dashboard. A streamer can have at
        most 250 commands. Requires `commands:manage`.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CustomCommandCreate" }
      responses:
        "201":
          description: Created. Active in chat within a few seconds.
          content:
            application/json:
              schema:
                type: object
                properties:
                  command: { $ref: "#/components/schemas/CustomCommand" }
        "400":
          description: Invalid fields (`invalid_command`), or the streamer already has 250 commands (`limit_reached`).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "409":
          description: >
            Name already taken (`command_exists`), or an alias collides
            with another trigger (`alias_in_use`).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /commands/{commandName}:
    get:
      operationId: getCustomCommand
      tags: [Chat bot]
      summary: Get one command
      description: Requires `commands:manage`.
      parameters:
        - $ref: "#/components/parameters/CommandName"
      responses:
        "200":
          description: The command.
          content:
            application/json:
              schema:
                type: object
                properties:
                  command: { $ref: "#/components/schemas/CustomCommand" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
    patch:
      operationId: updateCustomCommand
      tags: [Chat bot]
      summary: Update a command
      description: >
        Any subset of fields - `{"enabled": false}` benches a command
        without deleting it, `name` renames it (the old name stops
        triggering immediately). Requires `commands:manage`.
      parameters:
        - $ref: "#/components/parameters/CommandName"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CustomCommandUpdate" }
      responses:
        "200":
          description: Updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  command: { $ref: "#/components/schemas/CustomCommand" }
        "400":
          description: Invalid fields (`invalid_command`).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409":
          description: >
            The new name is already taken (`command_exists`), or an alias
            collides with another trigger (`alias_in_use`).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "429": { $ref: "#/components/responses/RateLimited" }
    delete:
      operationId: deleteCustomCommand
      tags: [Chat bot]
      summary: Delete a command
      description: The bot stops answering it immediately. Requires `commands:manage`.
      parameters:
        - $ref: "#/components/parameters/CommandName"
      responses:
        "200": { $ref: "#/components/responses/Success" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /overlays/connected:
    get:
      operationId: getOverlaysConnected
      tags: [Overlays]
      summary: Is an overlay connected?
      description: >
        Whether any of the account's overlays holds a live realtime
        connection right now - without one, nothing you queue plays. Needs
        `tts:read` or `media:read` (not `overlays:manage`): it is the fact
        both queues share.
      responses:
        "200":
          description: The connected overlays.
          content:
            application/json:
              schema:
                type: object
                properties:
                  connected: { type: boolean }
                  media_screen:
                    type: boolean
                    description: A connected overlay carries a media-screen widget, so showing or hiding the video on stream has an effect.
                  overlays:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        name: { type: [string, "null"] }
                        media_screen: { type: boolean }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /overlays:
    get:
      operationId: listOverlays
      tags: [Overlays]
      summary: List overlays
      description: >
        Every overlay on the account. Overlay keys are deliberately never
        returned. Requires `overlays:manage`.
      responses:
        "200":
          description: The account's overlays.
          content:
            application/json:
              schema:
                type: object
                properties:
                  overlays:
                    type: array
                    items: { $ref: "#/components/schemas/Overlay" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /overlays/celebrate:
    post:
      operationId: celebrateAllOverlays
      tags: [Overlays]
      summary: Fire a celebration everywhere
      description: >
        Fires the Event celebration widget on every connected overlay that
        carries one - confetti and/or channel emotes, using each widget's
        own configured look. Overlays without the widget ignore it.
        Requires `overlays:manage`.
      responses:
        "200":
          description: Broadcast sent.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean, example: true }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /overlays/{overlayId}:
    get:
      operationId: getOverlay
      tags: [Overlays]
      summary: Get one overlay
      description: >
        One overlay, plus the widget types currently on its layout.
        Requires `overlays:manage`.
      parameters:
        - $ref: "#/components/parameters/OverlayId"
      responses:
        "200":
          description: The overlay.
          content:
            application/json:
              schema:
                type: object
                properties:
                  overlay:
                    allOf:
                      - $ref: "#/components/schemas/Overlay"
                      - type: object
                        properties:
                          widgets:
                            type: array
                            description: Widget types on the layout.
                            items: { type: string }
                            example: ["alert", "chat", "celebration"]
                          celebrations:
                            type: array
                            description: >
                              Placed Event celebration widget instances -
                              their ids target POST .../celebrate at one
                              specific widget.
                            items:
                              type: object
                              properties:
                                id: { type: string, example: celebration-mt9x2ab }
                                name: { type: [string, "null"], example: "Goal zone" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
    delete:
      operationId: deleteOverlay
      tags: [Overlays]
      summary: Delete an overlay
      description: >
        Permanently deletes the overlay and disconnects its browser source.
        The last remaining overlay can't be deleted (`last_overlay`, 409).
        Requires `overlays:manage`.
      parameters:
        - $ref: "#/components/parameters/OverlayId"
      responses:
        "200":
          description: Deleted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean, example: true }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409":
          description: It's the account's only overlay (`last_overlay`).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /overlays/{overlayId}/reload:
    post:
      operationId: reloadOverlay
      tags: [Overlays]
      summary: Reload an overlay
      description: >
        Asks a connected overlay's browser source to refresh itself and
        pick up its latest configuration - handy when a source looks
        stuck without touching OBS. A disconnected overlay ignores the
        request, so this is always safe to call. Requires
        `overlays:manage`.
      parameters:
        - $ref: "#/components/parameters/OverlayId"
      responses:
        "200":
          description: Broadcast sent.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean, example: true }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /overlays/{overlayId}/celebrate:
    post:
      operationId: celebrateOverlay
      tags: [Overlays]
      summary: Fire a celebration on one overlay
      description: >
        Fires the Event celebration widget on this overlay only. The
        widget's own configuration decides the look (confetti / emotes,
        style, duration); overlays without the widget ignore the trigger.
        Pass `widget_id` (from the overlay's `celebrations` list) to fire
        just ONE of several placed celebration widgets. Requires
        `overlays:manage`.
      parameters:
        - $ref: "#/components/parameters/OverlayId"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                widget_id:
                  type: string
                  description: A celebration widget instance id from GET /overlays/{overlayId}. Omit to fire every celebration widget on the overlay.
                  example: celebration-mt9x2ab
      responses:
        "200":
          description: Broadcast sent.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean, example: true }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /overlays/{overlayId}/tip-goal:
    get:
      operationId: getOverlayTipGoal
      tags: [Overlays]
      summary: Get an overlay's tip goal
      description: >
        The overlay's tip goal campaign. `current` = tips received since
        the campaign start, plus any manual adjustments made through the
        add endpoint. Requires `overlays:manage`.
      parameters:
        - $ref: "#/components/parameters/OverlayId"
      responses:
        "200":
          description: The tip goal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  tip_goal: { $ref: "#/components/schemas/TipGoal" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
    patch:
      operationId: updateOverlayTipGoal
      tags: [Overlays]
      summary: Update an overlay's tip goal
      description: >
        Any subset of campaign fields. Changing them reloads the overlay's
        browser source so the widget picks them up. Requires
        `overlays:manage`.
      parameters:
        - $ref: "#/components/parameters/OverlayId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                enabled: { type: boolean }
                title: { type: string, maxLength: 80, example: "New PC fund" }
                amount: { type: number, minimum: 0, maximum: 1000000, example: 500 }
                starts_at: { type: [string, "null"], format: date-time, description: "Count tips from this moment. Empty/null clears it." }
                ends_at: { type: [string, "null"], format: date-time, description: "Campaign end. Empty/null clears it." }
      responses:
        "200":
          description: Updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean, example: true }
        "400":
          description: Invalid amount or date.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /overlays/{overlayId}/tip-goal/add:
    post:
      operationId: addToOverlayTipGoal
      tags: [Overlays]
      summary: Add to an overlay's tip goal
      description: >
        Adjusts the goal's progress by `amount` (negative subtracts)
        WITHOUT creating a tip - it uses a separate manual-adjustment
        offset that the dashboard's reset-progress clears. The on-screen
        goal updates live, and a crossing into the target fires any
        goal-hit celebration. Requires `overlays:manage`.
      parameters:
        - $ref: "#/components/parameters/OverlayId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [amount]
              properties:
                amount:
                  type: number
                  description: Non-zero; negative to subtract. Up to 1,000,000 either way.
                  example: 25
      responses:
        "200":
          description: Adjusted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean, example: true }
                  added: { type: number, example: 25 }
        "400":
          description: amount missing, zero, or out of range (`invalid_amount`).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

# ── Webhook events ────────────────────────────────────────────────────────
# Every payload is the same envelope: { id, type, created, data }. See the
# top-of-file description for signing and retry semantics.
webhooks:
  tip.created:
    post:
      tags: [Webhook events]
      summary: "tip.created"
      description: >
        A tip entered the TTS queue, from any source - `data.source` says
        which (a webhook-testing tip says `test`, a replay says `replay`).
        `tts_url` is always `null` here; the audio renders asynchronously and
        arrives via `tip.tts_ready`.
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/EventEnvelope"
                - type: object
                  properties:
                    type: { const: "tip.created" }
                    data: { $ref: "#/components/schemas/TipCreatedData" }
      responses:
        "200": { description: Return any 2xx quickly; do real work asynchronously. }

  tip.tts_ready:
    post:
      tags: [Webhook events]
      summary: "tip.tts_ready"
      description: TTS audio became available for a queued tip - at payment for AI voices, when an alert box first plays it (or the streamer previews it) for standard voices.
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/EventEnvelope"
                - type: object
                  properties:
                    type: { const: "tip.tts_ready" }
                    data:
                      type: object
                      properties:
                        order_id: { type: string }
                        tts_url: { type: string, format: uri }
      responses:
        "200": { description: Return any 2xx quickly. }

  tip.filtered:
    post:
      tags: [Webhook events]
      summary: "tip.filtered"
      description: >
        A tip went through, but the word filter (or the AI filter) replaced
        words in its name or message before it reached the queue. Unusually
        for this API, the payload includes the **pre-filter originals** -
        seeing what was caught is the point of the event. `reasoning` is the
        AI filter's explanation, when the AI filter made the call.
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/EventEnvelope"
                - type: object
                  properties:
                    type: { const: "tip.filtered" }
                    data:
                      type: object
                      properties:
                        order_id: { type: [string, "null"] }
                        name: { type: [string, "null"], description: The filtered name (what shows on stream). }
                        original_name: { type: [string, "null"], description: The name as the donor typed it. }
                        amount: { type: [number, "null"] }
                        currency: { type: [string, "null"] }
                        message: { type: [string, "null"], description: The filtered message. }
                        original_message: { type: [string, "null"], description: The message as the donor typed it. }
                        matched_words:
                          type: array
                          items: { type: string }
                        reasoning: { type: [string, "null"] }
      responses:
        "200": { description: Return any 2xx quickly. }

  tip.blocked:
    post:
      tags: [Webhook events]
      summary: "tip.blocked"
      description: >
        The filter wants to block a tip (a blocked word, or the AI filter's
        block verdict). The tip is held for a moderator rather than dropped:
        tip.held follows, and tip.reviewed says whether it was allowed or
        rejected. The payload carries the original content. A held Stripe
        payment is only authorised; rejecting it releases the hold.
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/EventEnvelope"
                - type: object
                  properties:
                    type: { const: "tip.blocked" }
                    data:
                      type: object
                      properties:
                        order_id: { type: [string, "null"] }
                        name: { type: [string, "null"], description: The name as the donor typed it. }
                        amount: { type: [number, "null"] }
                        currency: { type: [string, "null"] }
                        message: { type: [string, "null"], description: The message as the donor typed it. }
                        blocked_words:
                          type: array
                          items: { type: string }
                        reasoning: { type: [string, "null"] }
      responses:
        "200": { description: Return any 2xx quickly. }

  tip.held:
    post:
      tags: [Webhook events]
      summary: "tip.held"
      description: >
        A tip was parked in the manual review queue instead of entering the
        TTS / media queues. `reason` says why (`manual` = the streamer
        reviews everything, `filter` = the word/AI filter matched and the
        streamer chose review over silent replace/block, `ai_unavailable`
        = the AI filter could not be reached, `media_lookalike` = the
        tip's video looks like a banned one, usually a reupload). `payment_state` says where
        the money is meanwhile: `captured` (charged), `held` (Stripe auth
        only - approval captures, rejection releases) or `none` (nothing
        was paid, e.g. a sub-reward message).
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/EventEnvelope"
                - type: object
                  properties:
                    type: { const: "tip.held" }
                    data:
                      type: object
                      properties:
                        order_id: { type: string }
                        name: { type: [string, "null"] }
                        amount: { type: [number, "null"] }
                        currency: { type: [string, "null"] }
                        message: { type: [string, "null"], description: The message as the donor typed it. }
                        has_media: { type: boolean }
                        reason: { type: string, enum: [manual, filter, ai_unavailable, media_lookalike] }
                        payment_state: { type: string, enum: [captured, held, none] }
                        source: { type: string }
      responses:
        "200": { description: Return any 2xx quickly. }

  tip.reviewed:
    post:
      tags: [Webhook events]
      summary: "tip.reviewed"
      description: >
        A moderator decided a held tip, or its Stripe payment hold expired
        before anyone did. `decision` is `approved`, `rejected` or
        `expired`; `allow_tts` / `allow_media` say which halves were let
        through. An approval is followed by the normal `tip.created` and/or
        `media.created` as the tip enters the queues. `payment_released`
        is true when a held authorisation was cancelled - the donor was
        never charged. `payment_kept` is true when a blocked tip was
        rejected but its held payment captured anyway.
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/EventEnvelope"
                - type: object
                  properties:
                    type: { const: "tip.reviewed" }
                    data:
                      type: object
                      properties:
                        order_id: { type: string }
                        decision: { type: string, enum: [approved, rejected, expired] }
                        allow_tts: { type: boolean }
                        allow_media: { type: boolean }
                        reason: { type: string, enum: [manual, filter, ai_unavailable, media_lookalike] }
                        payment_state: { type: string, enum: [captured, held, none] }
                        payment_released: { type: boolean }
                        payment_kept: { type: boolean }
                        name: { type: [string, "null"] }
                        amount: { type: [number, "null"] }
                        currency: { type: [string, "null"] }
      responses:
        "200": { description: Return any 2xx quickly. }

  tipping.opened:
    post:
      tags: [Webhook events]
      summary: "tipping.opened / tipping.closed"
      description: >
        The accept-new-tips switch flipped (from the dashboard or the API),
        with an empty `data` object. Closing stops new checkouts from
        starting; a viewer already mid-payment when tipping closes still
        completes normally and their tip lands in the queue.
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/EventEnvelope"
                - type: object
                  properties:
                    type:
                      type: string
                      enum: [tipping.opened, tipping.closed]
                    data: { type: object }
      responses:
        "200": { description: Return any 2xx quickly. }

  queue.tts.started:
    post:
      tags: [Webhook events]
      summary: "queue.tts.started"
      description: A queued TTS started playing (overlay or API consumer claimed it).
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/EventEnvelope"
                - type: object
                  properties:
                    type: { const: "queue.tts.started" }
                    data:
                      type: object
                      properties:
                        tip: { $ref: "#/components/schemas/EventTip" }
      responses:
        "200": { description: Return any 2xx quickly. }

  queue.tts.finished:
    post:
      tags: [Webhook events]
      summary: "queue.tts.finished"
      description: A tip finished playing and moved to history.
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/EventEnvelope"
                - type: object
                  properties:
                    type: { const: "queue.tts.finished" }
                    data:
                      type: object
                      properties:
                        tip: { $ref: "#/components/schemas/EventTip" }
      responses:
        "200": { description: Return any 2xx quickly. }

  queue.tts.released:
    post:
      tags: [Webhook events]
      summary: "queue.tts.released"
      description: >
        A now-playing claim was released without finishing (the consumer's
        effect failed or it shut down mid-item) - the tip stays in the
        queue and can be claimed again. `tip` is null in the rare case the
        released claim pointed at an already-removed row.
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/EventEnvelope"
                - type: object
                  properties:
                    type: { const: "queue.tts.released" }
                    data:
                      type: object
                      properties:
                        order_id: { type: string }
                        tip:
                          oneOf:
                            - $ref: "#/components/schemas/EventTip"
                            - type: "null"
      responses:
        "200": { description: Return any 2xx quickly. }

  queue.tts.skipped:
    post:
      tags: [Webhook events]
      summary: "queue.tts.skipped"
      description: The currently-playing TTS was skipped.
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/EventEnvelope"
                - type: object
                  properties:
                    type: { const: "queue.tts.skipped" }
                    data:
                      type: object
                      properties:
                        order_id:
                          type: [string, "null"]
                          description: The skipped tip, when one was playing.
      responses:
        "200": { description: Return any 2xx quickly. }

  queue.tts.removed:
    post:
      tags: [Webhook events]
      summary: "queue.tts.removed"
      description: A queued TTS was removed before playing (moderation).
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/EventEnvelope"
                - type: object
                  properties:
                    type: { const: "queue.tts.removed" }
                    data:
                      type: object
                      properties:
                        tip: { $ref: "#/components/schemas/EventTip" }
      responses:
        "200": { description: Return any 2xx quickly. }

  queue.tts.paused:
    post:
      tags: [Webhook events]
      summary: "queue.tts.paused / resumed / cleared"
      description: >
        TTS queue lifecycle events with an empty `data` object. Types:
        `queue.tts.paused`, `queue.tts.resumed`, `queue.tts.cleared`.
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/EventEnvelope"
                - type: object
                  properties:
                    type:
                      type: string
                      enum: [queue.tts.paused, queue.tts.resumed, queue.tts.cleared]
                    data: { type: object }
      responses:
        "200": { description: Return any 2xx quickly. }

  media.created:
    post:
      tags: [Webhook events]
      summary: "media.created"
      description: >
        A media item entered the media queue - via a tip, a `!sr` chat
        request, channel points, or a replay (`data.requested_via`
        discriminates). `order_id` links back to the tip when there is one.
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/EventEnvelope"
                - type: object
                  properties:
                    type: { const: "media.created" }
                    data: { $ref: "#/components/schemas/MediaCreatedData" }
      responses:
        "200": { description: Return any 2xx quickly. }

  queue.media.started:
    post:
      tags: [Webhook events]
      summary: "queue.media.started / finished / removed"
      description: >
        A media item started (`queue.media.started`) or finished
        (`queue.media.finished`) playing, or was removed from the queue
        before playing (`queue.media.removed`).
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/EventEnvelope"
                - type: object
                  properties:
                    type:
                      type: string
                      enum: [queue.media.started, queue.media.finished, queue.media.removed]
                    data:
                      type: object
                      properties:
                        media: { $ref: "#/components/schemas/EventMedia" }
      responses:
        "200": { description: Return any 2xx quickly. }

  queue.media.released:
    post:
      tags: [Webhook events]
      summary: "queue.media.released"
      description: >
        A now-playing claim on a media item was released without finishing
        (the consumer's player failed or it shut down mid-item) - the item
        stays in the queue and can be claimed again. `media` is null in the
        rare case the released claim pointed at an already-removed row.
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/EventEnvelope"
                - type: object
                  properties:
                    type: { const: "queue.media.released" }
                    data:
                      type: object
                      properties:
                        order_id: { type: string }
                        media:
                          oneOf:
                            - $ref: "#/components/schemas/EventMedia"
                            - type: "null"
      responses:
        "200": { description: Return any 2xx quickly. }

  queue.media.skipped:
    post:
      tags: [Webhook events]
      summary: "queue.media.skipped"
      description: The currently-playing media was skipped.
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/EventEnvelope"
                - type: object
                  properties:
                    type: { const: "queue.media.skipped" }
                    data:
                      type: object
                      properties:
                        order_id:
                          type: [string, "null"]
                          description: The skipped media item, when one was on screen.
      responses:
        "200": { description: Return any 2xx quickly. }

  queue.media.paused:
    post:
      tags: [Webhook events]
      summary: "queue.media.paused / resumed / shown / hidden"
      description: >
        Media queue lifecycle events with an empty `data` object. Types:
        `queue.media.paused`, `queue.media.resumed`, `queue.media.shown`,
        `queue.media.hidden` (player visibility on the overlay; hiding
        doesn't pause playback).
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/EventEnvelope"
                - type: object
                  properties:
                    type:
                      type: string
                      enum: [queue.media.paused, queue.media.resumed, queue.media.shown, queue.media.hidden]
                    data: { type: object }
      responses:
        "200": { description: Return any 2xx quickly. }

  twitch.follow:
    post:
      tags: [Webhook events]
      summary: "twitch.* (follow, sub, resub, gift_sub, cheer, raid)"
      description: >
        Twitch alerts, forwarded the moment they arrive - before the
        streamer's filter runs and whatever it decides; the filter only
        gates the overlays and the bot, so check the text yourself before
        showing it (a repeat follow inside the follow cooldown is
        dropped). Which alerts an overlay shows is configured per overlay
        and does not gate the webhook - every event fires. Types:
        `twitch.follow`, `twitch.sub`, `twitch.resub`, `twitch.gift_sub`,
        `twitch.cheer`, `twitch.raid`. Fields beyond the user identity are
        present only where they make sense (tier on subs, bits on cheers,
        viewers on raids, ...). One Twitch sub can be TWO events, and
        both fire: `twitch.sub` at payment (a non-sub became a sub - a
        first sub, a lapsed return, a Prime re-up) and `twitch.resub`
        when the viewer shares (months + message; seconds or hours
        later, sometimes first). `paired_event_id` on either names the
        other half's `event_id` once it exists (null on whichever lands
        first); `continuing: true` on a `twitch.sub` means the viewer
        has subscribed to this channel before (a re-up or a return,
        Prime or paid), whose share, if they press it, carries their
        months. `twitch.sub` fires at payment, as Twitch sent it; the
        alert box plays a Sub only once Twitch's own chat announces it
        (a first-time sub, within seconds; never a returning one, whose
        share is the alert). Show one or the other, the way the alert
        box does.
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/EventEnvelope"
                - type: object
                  properties:
                    type:
                      type: string
                      enum: [twitch.follow, twitch.sub, twitch.resub, twitch.gift_sub, twitch.cheer, twitch.raid]
                    data: { $ref: "#/components/schemas/TwitchEventData" }
      responses:
        "200": { description: Return any 2xx quickly. }

  kick.follow:
    post:
      tags: [Webhook events]
      summary: "kick.* (follow, sub, resub, gift_sub, kicks)"
      description: >
        Kick alerts - the same shape as the `twitch.*` events with
        `platform: "kick"`, forwarded before the filter like them (per-overlay
        alert settings do not gate it). Types: `kick.follow`, `kick.sub`, `kick.resub`,
        `kick.gift_sub`, `kick.kicks`. Kick subscriptions carry no tier
        (`tier` is always `"1"`). `kick.kicks` is Kick's paid gift - the
        counterpart of a cheer - with `kicks` (the amount), `gift_name` and
        the viewer's `kicks_message`.
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/EventEnvelope"
                - type: object
                  properties:
                    type:
                      type: string
                      enum: [kick.follow, kick.sub, kick.resub, kick.gift_sub, kick.kicks]
                    data: { $ref: "#/components/schemas/TwitchEventData" }
      responses:
        "200": { description: Return any 2xx quickly. }

  twitch.channel_point_redemption:
    post:
      tags: [Webhook events]
      summary: "twitch.channel_point_redemption"
      description: >
        A viewer redeemed a channel point reward. Fires for EVERY reward on
        the channel - including rewards TipPage has no actions mapped to -
        so you can build your own redemption automations. The redeemer's
        name and text input are sent as Twitch sent them, before the
        streamer's word/AI filter runs and whatever it decides - check the
        text yourself before showing it. Delivery is at-least-once:
        dedupe on `data.redemption_id` (stable across Twitch redeliveries,
        unlike the envelope id). When `is_managed` is true, close the loop
        with the fulfill/cancel endpoints once your automation has run.
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/EventEnvelope"
                - type: object
                  properties:
                    type: { const: "twitch.channel_point_redemption" }
                    data: { $ref: "#/components/schemas/ChannelPointRedemptionData" }
      responses:
        "200": { description: Return any 2xx quickly. }

  chat.command:
    post:
      tags: [Webhook events]
      summary: "chat.command"
      description: >
        A viewer executed one of the streamer's custom chat commands - the
        hook for turning commands into real-world triggers (`!explode` firing
        actual hardware). Emits only after the command's permission and
        cooldown checks pass, and only for custom commands - built-ins like
        `!queue` never fire it. `command` is the canonical command name;
        `invoked_as` is what the viewer typed (differs when an alias was
        used). Delivery is at-least-once: dedupe on `data.message_id`.
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/EventEnvelope"
                - type: object
                  properties:
                    type: { const: "chat.command" }
                    data: { $ref: "#/components/schemas/ChatCommandData" }
      responses:
        "200": { description: Return any 2xx quickly. }

  chat.moderated:
    post:
      tags: [Webhook events]
      summary: "chat.moderated"
      description: >
        Chat moderation acted on a message. One event per enforcement step
        of the response that ran (a delete, or a timeout or ban), or one
        `warn` event when the response only posted messages. `feature` names
        where the match came from (`rule`, `bannedWords`, `links`, `caps`,
        `emotes`, `symbols`, or `votekick` for a timeout the votekick bot
        module carried out), `rule` the streamer's named rule when one
        fired, `matched_term` the phrase that matched. `enforced: false`
        means the platform-side action failed - on Twitch the bot isn't
        modded in the channel or lacks the moderator scopes, on Kick the
        streamer's Kick connection lacks the moderation scopes - and the
        attempt is still reported so nothing slips by silently. Message
        text is public chat content. `platform` says which chat it
        happened in; Kick moderation is enforced through the streamer's
        own Kick connection.
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/EventEnvelope"
                - type: object
                  properties:
                    type: { const: "chat.moderated" }
                    data:
                      type: object
                      properties:
                        platform: { type: string, enum: [twitch, kick] }
                        action:
                          type: string
                          enum: [warn, delete, timeout, ban]
                        enforced: { type: boolean }
                        duration_seconds:
                          type: [integer, "null"]
                          description: Timeout length; null for other actions.
                        target_user_id: { type: [string, "null"] }
                        target_login: { type: [string, "null"] }
                        target_name: { type: [string, "null"] }
                        feature:
                          type: [string, "null"]
                          enum: [rule, bannedWords, links, caps, emotes, symbols, votekick, null]
                          description: Where the match came from - rule, bannedWords, links, caps, emotes, symbols, or votekick (a timeout carried out by the votekick bot module).
                        rule:
                          type: [object, "null"]
                          description: The named rule that fired; null for the phrase list and the protections.
                          properties:
                            id: { type: string, description: "mr_ id" }
                            name: { type: [string, "null"] }
                        matched_term: { type: [string, "null"] }
                        message: { type: [string, "null"] }
                        reason: { type: [string, "null"] }
      responses:
        "200": { description: Return any 2xx quickly. }

  character.replied:
    post:
      tags: [Webhook events]
      summary: "character.replied"
      description: >
        An AI character (closed beta) answered on stream: the reply was
        broadcast to the streamer's overlays with the character's portrait
        and captions, spoken in its voice when it has one. `source` says
        what prompted it - a chat line (`chat`), a channel-point redemption
        (`points`) or the dashboard's Try it (`test`). Replies that only
        went to chat do not fire this event.
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/EventEnvelope"
                - type: object
                  properties:
                    type: { const: "character.replied" }
                    data:
                      type: object
                      properties:
                        event_id: { type: string, example: "ev_0123456789abcdef" }
                        character:
                          type: object
                          properties:
                            id: { type: string, example: "chr_0123456789abcdef" }
                            name: { type: string }
                        source: { type: string, enum: [chat, points, test] }
                        platform: { type: [string, "null"], enum: [twitch, kick, null] }
                        user_login: { type: [string, "null"] }
                        user_name: { type: [string, "null"] }
                        question: { type: [string, "null"] }
                        reply: { type: string }
                        voiced: { type: boolean }
                        on_stream: { type: boolean }
                        image_shown: { type: boolean }
      responses:
        "200": { description: Acknowledged }
  character.held:
    post:
      tags: [Webhook events]
      summary: "character.held"
      description: >
        A viewer's picture for an AI character is waiting for a moderator on
        the Review page (the character's "hold pictures" setting). Approve
        or reject happens in the dashboard; `character.reviewed` follows.
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/EventEnvelope"
                - type: object
                  properties:
                    type: { const: "character.held" }
                    data:
                      type: object
                      properties:
                        id: { type: string, example: "ci_0123456789abcdef" }
                        character:
                          type: object
                          properties:
                            id: { type: string }
                            name: { type: string }
                        reason: { type: string, enum: [image, filter, manual] }
                        platform: { type: string, enum: [twitch, kick] }
                        user_login: { type: [string, "null"] }
                        user_name: { type: [string, "null"] }
      responses:
        "200": { description: Acknowledged }
  character.reviewed:
    post:
      tags: [Webhook events]
      summary: "character.reviewed"
      description: >
        A moderator decided a held AI-character input. `replied` is true
        when the approval produced an answer.
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/EventEnvelope"
                - type: object
                  properties:
                    type: { const: "character.reviewed" }
                    data:
                      type: object
                      properties:
                        id: { type: string }
                        character:
                          type: object
                          properties:
                            id: { type: string }
                            name: { type: string }
                        decision: { type: string, enum: [approved, rejected] }
                        platform: { type: string, enum: [twitch, kick] }
                        user_login: { type: [string, "null"] }
                        replied: { type: boolean }
      responses:
        "200": { description: Acknowledged }
  warning:
    post:
      tags: [Webhook events]
      summary: "warning"
      description: >
        An operational warning about your integration - delivered to
        **every** active endpoint regardless of its event subscriptions,
        and cannot be turned off. `code` is the stable machine-readable
        identifier (current codes: `multiple_tts_consumers`,
        `multiple_media_consumers` - an overlay and an API consumer both
        claimed items from the same queue within a short window, so items
        are likely playing twice); `message` is human-readable prose.
        At minimum log `message` somewhere a human reads, or forward it to
        a Discord channel. New codes are added over time - treat an
        unknown `code` as a log line, never an error. The same warning
        fires at most once per ~6 hours per streamer.
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/EventEnvelope"
                - type: object
                  properties:
                    type: { const: "warning" }
                    data:
                      type: object
                      required: [code, message]
                      properties:
                        code:
                          type: string
                          description: Stable identifier; branch on this, never on message text.
                        message:
                          type: string
                          description: Human-readable explanation, safe to pipe straight into a log or Discord.
                      additionalProperties:
                        description: Per-code extras (e.g. queue, consumers).
      responses:
        "200": { description: Return any 2xx quickly. }

  ping:
    post:
      tags: [Webhook events]
      summary: "ping"
      description: >
        Sent by the dashboard's "Test" button and the ping endpoint. Not
        subscribable - every endpoint can receive it.
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/EventEnvelope"
                - type: object
                  properties:
                    type: { const: "ping" }
                    data:
                      type: object
                      properties:
                        message: { type: string }
      responses:
        "200": { description: Return any 2xx quickly. }

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: "tp_live_... or tpat_..."
      description: >
        A TipPage API key (`tp_live_...`, created in Dashboard → Settings → Developer)
        or an OAuth 2.0 access token (`tpat_...`, see the OAuth guide). Both carry
        the same scopes and are accepted on every endpoint.
    oauth2:
      type: oauth2
      description: >
        For apps other streamers connect. Authorization code + PKCE (S256); refresh
        tokens rotate on use. Scopes are the same vocabulary as API keys. Guide: /api/oauth.
      flows:
        authorizationCode:
          authorizationUrl: https://auth.tippage.com/oauth/authorize
          tokenUrl: https://auth.tippage.com/oauth/token
          refreshUrl: https://auth.tippage.com/oauth/token
          scopes:
            tts:read: Read the TTS queue and history
            tips:create: Create tips
            tts:control: Control the TTS queue
            media:read: Read the media queue
            media:control: Control the media queue
            tipping:control: Open/close tipping
            viewers:read: Read viewers
            viewers:manage: Grant/revoke reward credits
            webhooks:manage: Manage webhook endpoints
            counters:manage: Manage counters
            timers:manage: Manage chat timers
            chat:read: Read chat messages (realtime stream only)
            chat:write: Send chat messages
            commands:manage: Manage chat commands
            overlays:manage: Manage overlays
            channel_points:manage: Resolve channel point redemptions
            ai_voices:manage: Manage AI voices (TipPage+)

  parameters:
    OrderId:
      name: orderId
      in: path
      required: true
      schema: { type: string }
      description: >
        The tip's order id (e.g. `tip_1755100000000_ab12cd`) - the only
        external row reference.
    MediaOrderId:
      name: orderId
      in: path
      required: true
      schema: { type: string }
      description: The media item's order id - the only external row reference.
    EndpointId:
      name: endpointId
      in: path
      required: true
      schema: { type: string }
      description: Webhook endpoint id (`we_...`).
    TimerId:
      name: timerId
      in: path
      required: true
      schema: { type: string }
      description: Chat timer id (`tmr_...`).
    CommandName:
      name: commandName
      in: path
      required: true
      schema: { type: string }
      description: The command's name - its trigger without the `!` prefix.
    OverlayId:
      name: overlayId
      in: path
      required: true
      description: The overlay's id (`o_` + 8 hex chars).
      schema: { type: string, example: o_1a2b3c4d }
    RedemptionId:
      name: redemptionId
      in: path
      required: true
      schema: { type: string, maxLength: 64 }
      description: >
        The Twitch redemption id (UUID) - `data.redemption_id` on the
        `twitch.channel_point_redemption` webhook.
    ViewerIdent:
      name: user
      in: path
      required: true
      schema: { type: string }
      description: >
        Which viewer: `<platform>:<id>` (`twitch:123456789`, `kick:123`),
        a bare numeric id, or a login / display name (case-insensitive,
        matched on both platforms; URL-encode names with special
        characters). A bare id is tried on Twitch then Kick - if an account
        with that id has signed in on both, the answer is
        `409 ambiguous_viewer`; a name shared by two different people is
        409 too, while a name that matches both of ONE person's linked
        accounts resolves to the one they signed in with most recently.
        Prefer `platform:id` in automation - it survives renames and can
        never be ambiguous.
    HistoryLimit:
      name: limit
      in: query
      schema: { type: integer, minimum: 1, maximum: 100, default: 25 }
    HistoryBefore:
      name: before
      in: query
      schema: { type: string }
      description: >
        Cursor - an `order_id` from a previous page (`next_cursor`). Returns
        rows strictly older than it.

  responses:
    Success:
      description: Done.
      content:
        application/json:
          schema:
            type: object
            properties:
              success: { type: boolean, const: true }
    RedemptionResolved:
      description: The redemption was resolved (or already was).
      content:
        application/json:
          schema:
            type: object
            properties:
              success: { type: boolean, const: true }
              status: { type: string, enum: [fulfilled, canceled] }
              already_resolved:
                type: boolean
                description: This redemption had already been resolved to this status.
    Unauthorized:
      description: >
        Missing or invalid credential (`missing_api_key` / `invalid_api_key`, or `invalid_token` for an expired/revoked OAuth access token).
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    Forbidden:
      description: The key lacks the required scope (`missing_scope`).
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/Error"
              - type: object
                properties:
                  required_scope: { type: string }
    NotFound:
      description: No such resource.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    ViewerNotSignedIn:
      description: >
        No viewer with that name or id has ever signed in to this tip page
        (`viewer_not_signed_in`). Signing in on the tip page (Twitch or
        Kick) is what creates a viewer - until then they can't be looked up
        or granted credits.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    AmbiguousViewer:
      description: >
        More than one signed-in viewer matches (`ambiguous_viewer`) - two
        people share that name, or a bare id exists on both platforms.
        Retry with `<platform>:<id>`.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    RateLimited:
      description: Rate limit exceeded - check the `RateLimit-*` headers.
      content:
        application/json:
          schema:
            type: object
            properties:
              error: { type: string }

  schemas:
    Alert:
      type: object
      description: A platform alert as the history lists it.
      properties:
        id: { type: string, description: "`ev_...` - the event id the webhooks carry." }
        type:
          type: string
          enum: [follow, subscription, gift_subscription, cheer, raid, kicks, channel_points]
        event_type:
          type: [string, "null"]
          description: The payload type (`channel.subscription.message` tells a resub from a sub).
        platform: { type: string, enum: [twitch, kick] }
        name: { type: string, description: Who it was from. }
        profile_image_url: { type: [string, "null"] }
        tier: { type: [string, "null"], description: "Twitch tier id (`1000`, `2000`, `3000`); `1` on Kick." }
        total: { type: [integer, "null"], description: Gift subs - how many. }
        bits: { type: [integer, "null"] }
        viewers: { type: [integer, "null"], description: Raids. }
        kicks: { type: [integer, "null"] }
        months: { type: [integer, "null"], description: Resubs. }
        message: { type: [string, "null"], description: The viewer's own text, when there was one. }
        reward_title: { type: [string, "null"], description: Channel point redemptions. }
        reward_cost: { type: [integer, "null"], description: Channel point redemptions - the reward's cost in points. }
        redemption_id: { type: [string, "null"], description: Channel point redemptions - Twitch's id of the redemption. }
        gift_recipients:
          type: array
          items: { type: string }
          description: Gifted subs - who received them, as Twitch's gift notices named them. Empty when none were caught (a gift whose notices never arrived, an older row).
        status:
          type: string
          enum: [played, skipped, paired, waiting, not_played]
          description: "`waiting`, `not_played` and `paired` only appear with `status=all`. `paired` = a Twitch sub's half the overlay swallowed because its other half was the alert; the two are listed as one row, so it is only seen on its own when the pair fell outside the page. A Twitch sub payment Twitch's chat has not announced is `waiting` for a few seconds and `not_played` after that - no overlay was offered it; its share, if the viewer presses it, is the alert and turns it `paired`."
        is_replay: { type: boolean }
        replay_of: { type: [string, "null"], description: The original's id when this was a replay. }
        paired_event_id: { type: [string, "null"], description: "A Twitch sub's two events (the payment, the share) are listed as ONE row carrying the share's months and message at the payment's time; this is the other half's id. `id` is the half the overlay played (what a replay plays), the share when both or neither did." }
        happened_at: { type: string, format: date-time }
        finished_at: { type: [string, "null"], format: date-time, description: When it left the screen. }
    CurrentAlert:
      type: object
      description: The alert on screen, as the overlay reported it.
      properties:
        event_id: { type: [string, "null"] }
        type: { type: [string, "null"], description: "The payload type, e.g. `channel.cheer`." }
        platform: { type: string, enum: [twitch, kick] }
        name: { type: [string, "null"] }
        tier: { type: [string, "null"] }
        total: { type: [integer, "null"] }
        bits: { type: [integer, "null"] }
        viewers: { type: [integer, "null"] }
        kicks: { type: [integer, "null"] }
        months: { type: [integer, "null"] }
        message: { type: [string, "null"] }
        profile_image_url: { type: [string, "null"] }
        is_replay: { type: boolean }
        started_at: { type: [string, "null"], format: date-time }
    Error:
      type: object
      properties:
        error:
          type: string
          description: Human-readable message.
        code:
          type: string
          description: Machine-readable code (e.g. `missing_scope`, `not_in_queue`).
      required: [error]

    QueueTip:
      type: object
      description: A tip in the pending TTS queue.
      properties:
        order_id: { type: string, examples: ["tip_1755100000000_ab12cd"] }
        name: { type: string, description: Display name (post-filter). }
        amount: { type: [number, "null"], examples: [5.00] }
        message:
          type: [string, "null"]
          description: The tip message (post-filter - what shows on stream).
        tts_url:
          type: [string, "null"]
          format: uri
          description: >-
            Audio for this tip. AI-voice tips are rendered at payment; standard
            voices are rendered when an alert box first plays the tip (in that
            box's voice) or the streamer previews it - `null` until then.
            Listen for `tip.tts_ready`.
        is_replay: { type: boolean }
        is_sub_reward: { type: boolean }
        source:
          type: string
          description: >
            Where the tip came from: `stripe`, `paypal`, `manual` (dashboard
            manual tip), `api` (POST /tips), `sub_reward`, `replay`, `test`,
            `ayupcc`, or `unknown` for tips older than source tracking.
        external_source:
          type: [string, "null"]
          description: >
            Developer-API tips only - the `source` label the caller sent
            (`kofi`, `ayupcc`); `null` for every other source. Says where
            the tip came from, not whether money moved - see `is_paid`.
        external_ref:
          type: [string, "null"]
          description: Developer-API tips only - the caller's own payment reference.
        is_paid:
          type: boolean
          description: >
            Real money changed hands (Stripe, PayPal, or a developer-API tip
            sent with `paid: true`). `false` for manual tips, free
            integration tips and sub rewards - those never count toward the
            streamer's totals.
        platform:
          type: [string, "null"]
          enum: [twitch, kick, null]
          description: >
            The platform of the account the donor was signed in with when
            they tipped; `null` for an unattributed tip.
        platform_user_id:
          type: [string, "null"]
          description: The donor's id on that platform, when signed in.
        name_was_filtered: { type: boolean }
        message_was_filtered: { type: boolean }
        queued_at: { type: string, format: date-time }

    HistoryTip:
      type: object
      description: A tip that finished playing.
      properties:
        order_id: { type: string }
        name: { type: string }
        amount: { type: [number, "null"] }
        message: { type: [string, "null"] }
        tts_url: { type: [string, "null"], format: uri }
        is_replay: { type: boolean }
        is_sub_reward: { type: boolean }
        source:
          type: string
          description: >
            Where the tip came from: `stripe`, `paypal`, `manual` (dashboard
            manual tip), `api` (POST /tips), `sub_reward`, `replay`, `test`,
            `ayupcc`, or `unknown` for tips older than source tracking.
        external_source:
          type: [string, "null"]
          description: >
            Developer-API tips only - the `source` label the caller sent
            (`kofi`, `ayupcc`); `null` for every other source. Says where
            the tip came from, not whether money moved - see `is_paid`.
        external_ref:
          type: [string, "null"]
          description: Developer-API tips only - the caller's own payment reference.
        is_paid:
          type: boolean
          description: >
            Real money changed hands (Stripe, PayPal, or a developer-API tip
            sent with `paid: true`). `false` for manual tips, free
            integration tips and sub rewards - those never count toward the
            streamer's totals.
        platform: { type: [string, "null"], enum: [twitch, kick, null], description: Platform of the signed-in donor, or `null`. }
        platform_user_id: { type: [string, "null"], description: The donor's id on that platform, when signed in. }
        name_was_filtered: { type: boolean }
        message_was_filtered: { type: boolean }
        queued_at:
          type: string
          format: date-time
          description: When the tip entered the queue.
        played_at:
          type: string
          format: date-time
          description: When it finished playing on stream.

    EventTip:
      type: object
      description: >
        Tip object carried inside queue.tts.* event payloads. Same fields as
        the REST queue shape, except the queue timestamp is named
        `created_at`.
      properties:
        order_id: { type: string }
        name: { type: string }
        amount: { type: [number, "null"] }
        message: { type: [string, "null"] }
        tts_url: { type: [string, "null"], format: uri }
        is_replay: { type: boolean }
        is_sub_reward: { type: boolean }
        source:
          type: string
          description: >
            Where the tip came from: `stripe`, `paypal`, `manual` (dashboard
            manual tip), `api` (POST /tips), `sub_reward`, `replay`, `test`,
            `ayupcc`, or `unknown` for tips older than source tracking.
        external_source:
          type: [string, "null"]
          description: >
            Developer-API tips only - the `source` label the caller sent
            (`kofi`, `ayupcc`); `null` for every other source. Says where
            the tip came from, not whether money moved - see `is_paid`.
        external_ref:
          type: [string, "null"]
          description: Developer-API tips only - the caller's own payment reference.
        is_paid:
          type: boolean
          description: >
            Real money changed hands (Stripe, PayPal, or a developer-API tip
            sent with `paid: true`). `false` for manual tips, free
            integration tips and sub rewards - those never count toward the
            streamer's totals.
        platform: { type: [string, "null"], enum: [twitch, kick, null], description: Platform of the signed-in donor, or `null`. }
        platform_user_id: { type: [string, "null"], description: The donor's id on that platform, when signed in. }
        name_was_filtered: { type: boolean }
        message_was_filtered: { type: boolean }
        created_at: { type: string, format: date-time }

    TipCreatedData:
      type: object
      properties:
        order_id: { type: string }
        name: { type: string }
        amount: { type: [number, "null"] }
        message: { type: [string, "null"] }
        source:
          type: string
          enum: [stripe, paypal, manual, api, replay, sub_reward, ayupcc, test, dev, unknown]
          description: >
            Where the tip came from. `manual` is the dashboard's manual-tip
            form; `api` is a POST /tips tip - check `external_source` /
            `is_paid` to tell a paid-elsewhere tip from a free or manual one.
        external_source:
          type: [string, "null"]
          description: >
            Developer-API tips only - the `source` label sent to POST /tips
            (where the tip came from). `null` otherwise.
        external_ref:
          type: [string, "null"]
          description: Developer-API tips only - the caller's `reference`.
        is_paid:
          type: boolean
          description: >
            Real money changed hands. `true` for Stripe, PayPal and
            developer-API tips sent with `paid: true`; `false` for manual
            tips, sub rewards and free integration tips.
        is_replay: { type: boolean }
        is_sub_reward: { type: boolean }
        platform: { type: [string, "null"], enum: [twitch, kick, null], description: Platform of the signed-in donor, or `null`. }
        platform_user_id: { type: [string, "null"], description: The donor's id on that platform, when signed in. }
        name_was_filtered: { type: boolean }
        message_was_filtered: { type: boolean }
        tts_url:
          type: "null"
          description: Always null here - listen for `tip.tts_ready` (standard voices are rendered when an alert box first plays the tip).

    QueueMediaItem:
      type: object
      description: A media item in the pending queue.
      properties:
        order_id: { type: string }
        donor_name: { type: string }
        media_url: { type: string, format: uri }
        media_start_time: { type: integer, description: Start offset in seconds. }
        video_title: { type: [string, "null"] }
        video_thumbnail: { type: [string, "null"], format: uri }
        video_duration: { type: integer, description: Duration in seconds (0 = unknown). }
        platform: { type: string, examples: [youtube] }
        requested_via:
          type: string
          description: tip | chat | admin | channel_point | ...
        is_replay: { type: boolean }
        queued_at: { type: string, format: date-time }

    HistoryMediaItem:
      type: object
      description: A media item that finished playing.
      properties:
        order_id: { type: string }
        donor_name: { type: string }
        media_url: { type: string, format: uri }
        media_start_time: { type: integer }
        video_title: { type: [string, "null"] }
        video_thumbnail: { type: [string, "null"], format: uri }
        video_duration: { type: integer }
        platform: { type: string }
        requested_via: { type: string }
        is_replay: { type: boolean }
        queued_at: { type: string, format: date-time }
        played_at: { type: string, format: date-time }

    EventMedia:
      type: object
      description: >
        Media object carried inside queue.media.* event payloads (queue
        timestamp named `created_at`).
      properties:
        order_id: { type: string }
        donor_name: { type: string }
        media_url: { type: string, format: uri }
        media_start_time: { type: integer }
        video_title: { type: [string, "null"] }
        video_thumbnail: { type: [string, "null"], format: uri }
        video_duration: { type: integer }
        platform: { type: string }
        requested_via: { type: string }
        is_replay: { type: boolean }
        created_at: { type: string, format: date-time }

    MediaCreatedData:
      type: object
      properties:
        order_id:
          type: [string, "null"]
          description: Links to the tip's order id when the media came from a tip.
        donor_name: { type: string }
        media_url: { type: string, format: uri }
        media_start_time: { type: integer }
        video_title: { type: [string, "null"] }
        video_duration: { type: integer }
        platform: { type: string }
        requested_via: { type: string }
        is_replay: { type: boolean }

    TwitchEventData:
      type: object
      description: >
        Platform alert payload (`twitch.*` and `kick.*` events). `platform`,
        `user_name` and `user_login` are always present; the rest depend on
        the event type.
      properties:
        event_id: { type: string, description: "The alert's permanent id (`ev_` + 16 hex) - the same id the activity feed uses." }
        platform: { type: string, enum: [twitch, kick], description: Which platform the viewer is on. }
        user_name: { type: [string, "null"], description: Display name. }
        user_login: { type: [string, "null"] }
        profile_image_url: { type: [string, "null"], description: "The viewer's profile picture on their platform (Twitch via Helix, Kick's own) - the one the alert box shows. Null for an anonymous gifter or when the lookup failed." }
        message:
          type: [string, "null"]
          description: Human-readable alert line ("X subscribed at Tier 2!").
        tier: { type: string, description: "Sub tier: 1 / 2 / 3 (subs, resubs, gifts)." }
        months: { type: integer, description: Cumulative months (resubs). }
        sub_message: { type: string, description: The viewer's resub message. }
        paired_event_id: { type: [string, "null"], description: "Subs and resubs: the `event_id` of the other half of the same payment (a sub's share, a share's payment) once it exists; null on whichever of the two landed first." }
        continuing: { type: boolean, description: "Subs only: the viewer has subscribed to this channel before (a re-up or a return, Prime or paid), not a first-time sub; their share, if they press it, carries the months. Twitch's own chat announces only a first-time sub at payment." }
        total: { type: integer, description: Gift count (gift subs). }
        is_anonymous: { type: boolean, description: Anonymous gifter (gift subs). }
        gift_recipients:
          type: array
          items: { type: string }
          description: Recipient names attributed to a gift bomb.
        bits: { type: integer, description: Bits cheered (cheers). }
        viewers: { type: integer, description: Raid party size (raids). }
        kicks: { type: integer, description: Kicks gifted (kick.kicks). }
        gift_name: { type: [string, "null"], description: The Kicks gift's name (kick.kicks). }
        kicks_message: { type: [string, "null"], description: The viewer's note on a Kicks gift (kick.kicks). }

    ChannelPointRedemptionData:
      type: object
      description: Channel point redemption payload.
      properties:
        user_name: { type: [string, "null"], description: Redeemer display name (as on Twitch, unfiltered). }
        user_login: { type: [string, "null"] }
        profile_image_url: { type: [string, "null"], description: The redeemer's Twitch profile picture. }
        reward_id: { type: string, description: Twitch reward id. }
        reward_title: { type: [string, "null"] }
        reward_cost: { type: [integer, "null"], description: Cost in channel points. }
        user_input:
          type: [string, "null"]
          description: The viewer's text input (as typed, unfiltered), when the reward asks for one.
        redemption_id:
          type: string
          description: Twitch redemption id - dedupe on this.
        status:
          type: string
          description: Redemption status at event time (normally `unfulfilled`).
        redeemed_at: { type: [string, "null"], format: date-time }
        is_managed:
          type: boolean
          description: >
            The reward was created by TipPage - which is what makes the
            redemption resolvable via the fulfill/cancel endpoints (Twitch
            restricts resolution to the creating app).

    ChannelPointReward:
      type: object
      properties:
        id: { type: string, example: cpr_0123456789abcdef }
        twitch_reward_id: { type: string, description: "Matches `reward_id` on the redemption webhook." }
        title: { type: string }
        cost: { type: integer }
        prompt: { type: [string, "null"] }
        background_color: { type: [string, "null"] }
        is_user_input_required: { type: boolean }
        has_actions:
          type: boolean
          description: The streamer has TipPage actions on it (dashboard Channel points page).

    ChatCommandData:
      type: object
      description: Custom chat command execution payload.
      properties:
        platform: { type: string, enum: [twitch, kick], description: Which chat the command was typed in. }
        command: { type: string, description: Canonical command name, without the `!`. }
        invoked_as:
          type: string
          description: The name the viewer actually typed (canonical name or an alias).
        args:
          type: [string, "null"]
          description: The rest of the chat line after the command, original case.
        user_id: { type: [string, "null"], description: The chatter's user id on that platform. }
        user_login: { type: [string, "null"] }
        user_name: { type: [string, "null"], description: Display name. }
        is_mod:
          type: boolean
          description: Chatter is a moderator or the broadcaster.
        message_id:
          type: [string, "null"]
          description: The chat message id on that platform - dedupe on this.

    EventEnvelope:
      type: object
      description: Every webhook body is this envelope.
      properties:
        id:
          type: string
          description: Unique event id.
          examples: ["evt_9f1e2d3c4b5a6978"]
        type: { type: string, examples: ["tip.created"] }
        created: { type: string, format: date-time }
        actor:
          description: |
            Who caused the event. `null` for system-originated events (a
            payment landing, an overlay heartbeat lapsing). Otherwise one of
            `user` (a team member in the dashboard), `chat` (a moderator's
            chat command via the bot), `api_key` (a developer API key), `oauth_app` (an OAuth-connected app),
            `overlay` (the overlay reporting start/finish) or `bot`.
          oneOf:
            - type: "null"
            - type: object
              properties:
                type: { type: string, enum: [user, chat, api_key, oauth_app, overlay, bot] }
                user_id: { type: [string, "null"], description: "TipPage user id (`u_...`). Always set for `user` actors; set for `chat` actors when the chatter's account is linked to a TipPage user." }
                platform: { type: [string, "null"], enum: [twitch, kick, null], description: "user / chat actors - the platform account behind the actor" }
                platform_id: { type: [string, "null"], description: "user / chat actors - the account's id on that platform" }
                login: { type: [string, "null"], description: "user / chat actors" }
                display_name: { type: [string, "null"], description: "user / chat actors" }
                id: { type: [string, "null"], description: "api_key (`ak_...`) / oauth_app (`oc_...`, the client id) / overlay (`o_...`, the overlay id) actors" }
                name: { type: [string, "null"], description: "api_key / oauth_app / overlay actors" }
                authorization_id: { type: [string, "null"], description: "oauth_app actors only - the authorization (`oa_...`) the app acts under" }
              required: [type]
          examples:
            - { type: chat, user_id: null, platform: twitch, platform_id: "123456789", login: modname, display_name: ModName }
            - { type: user, user_id: u_9f3c1a7e42b08d61, platform: twitch, platform_id: "44322889", login: streamer, display_name: Streamer }
        data: { type: object }
      required: [id, type, created, actor, data]

    Viewer:
      type: object
      description: >
        A viewer who has signed in to the tip page. `platform` +
        `platform_user_id` name the account they signed in with here;
        `linked_accounts` lists the person's other platform account(s), if
        they linked any (may be empty). Credits and reward history are
        read across the whole set.
      properties:
        platform: { type: string, enum: [twitch, kick], examples: [twitch] }
        platform_user_id: { type: string, examples: ["123456789"] }
        login: { type: [string, "null"], examples: ["gigachad42"] }
        display_name: { type: [string, "null"], examples: ["GigaChad42"] }
        profile_image_url: { type: [string, "null"], format: uri }
        subscriber_tier:
          type: integer
          enum: [0, 1, 2, 3]
          description: Their sub tier as last seen (0 = not subscribed).
        first_signed_in_at:
          type: string
          format: date-time
          description: When they first signed in to this tip page.
        last_active_at:
          type: string
          format: date-time
          description: Last account activity seen (profile refreshes included).
        linked_accounts:
          type: array
          description: The person's OTHER platform accounts - never the one above. Empty when nothing is linked.
          items:
            type: object
            properties:
              platform: { type: string, enum: [twitch, kick] }
              platform_user_id: { type: string }
              login: { type: [string, "null"] }
              display_name: { type: [string, "null"] }
      required: [platform, platform_user_id, linked_accounts]

    ViewerPerson:
      type: object
      description: >
        The person a viewer lookup answered for. Their name and picture are
        those of the account they signed in with here most recently (the
        account that was looked up when they never did); the dates roll up
        over every account of theirs that signed in.
      properties:
        id:
          type: [string, "null"]
          examples: ["v_9f3c1a7e42b08d61"]
          description: >
            TipPage's id for the person - stable across their linked
            accounts and every tip page, and accepted as `{user}`. `null`
            when they have never signed in to any tip page.
        signed_in:
          type: boolean
          description: Whether any account of theirs has signed in to THIS tip page.
        signed_in_with:
          type: [string, "null"]
          enum: [twitch, kick, null]
          description: The platform of their most recent sign-in here.
        display_name: { type: [string, "null"], examples: ["GigaChad42"] }
        profile_image_url: { type: [string, "null"], format: uri }
        first_signed_in_at:
          type: [string, "null"]
          format: date-time
          description: Their first sign-in to this tip page, on any account.
        last_active_at:
          type: [string, "null"]
          format: date-time
          description: Last account activity seen here (profile refreshes included).
      required: [id, signed_in, signed_in_with, display_name, profile_image_url, first_signed_in_at, last_active_at]

    ViewerPlatform:
      type: object
      description: >
        One of the person's platform accounts and its standing on this
        channel on that platform. Each standing fact is best effort -
        `null` means it could not be read (the channel isn't connected to
        that platform, the platform's API failed, a scope is missing),
        never "no". Only the chat counters are definite.
      properties:
        id: { type: string, examples: ["123456789"], description: The platform's user id. }
        login: { type: [string, "null"], examples: ["gigachad42"] }
        display_name: { type: [string, "null"], examples: ["GigaChad42"] }
        profile_image_url: { type: [string, "null"], format: uri }
        signed_in:
          type: boolean
          description: Whether THIS account has signed in to the tip page.
        following: { type: [boolean, "null"] }
        followed_at: { type: [string, "null"], format: date-time }
        subscribed:
          type: [boolean, "null"]
          description: >
            Read live; when the live read fails on an account that signed
            in here, the tier the sign-in recorded stands in.
        tier:
          type: [integer, "null"]
          enum: [1, 2, 3, null]
          description: Current sub tier (Kick has no tiers - always 1).
        gifted: { type: [boolean, "null"], description: Twitch only - the current sub is a gift. }
        gifter_login: { type: [string, "null"] }
        sub_months:
          type: [integer, "null"]
          description: Cumulative sub months as last seen (see the operation).
        sub_months_at:
          type: [string, "null"]
          format: date-time
          description: When `sub_months` was seen.
        sub_months_source:
          type: [string, "null"]
          enum: [chat, resub, kick, null]
          description: >
            `chat` = their subscriber badge in chat, `resub` = a shared
            resub, `kick` = read from Kick.
        moderator:
          type: [boolean, "null"]
          description: A moderator of this channel on that platform.
        vip:
          type: [boolean, "null"]
          description: A VIP of this channel on that platform.
        chat:
          type: object
          properties:
            messages: { type: integer, description: Chat messages counted on this channel from this account. }
            first_seen: { type: [string, "null"], format: date, description: First day they chatted. }
            last_seen_at: { type: [string, "null"], format: date-time }
      required: [id, login, display_name, profile_image_url, signed_in, following, followed_at, subscribed, tier, gifted, gifter_login, sub_months, sub_months_at, sub_months_source, moderator, vip, chat]

    CreditBalance:
      type: object
      description: A viewer's sub-reward credit balance.
      properties:
        available: { type: integer, description: Credits spendable right now. }
        total: { type: integer, description: Credits ever granted. }
        used: { type: integer, description: Credits already spent. }

    WebhookEndpoint:
      type: object
      properties:
        id: { type: string, examples: ["we_1a2b3c4d5e6f"] }
        url: { type: string, format: uri }
        description: { type: [string, "null"] }
        events:
          type: array
          items: { type: string }
          description: Subscribed event types, or `["*"]` for everything.
        is_active: { type: boolean }
        disabled_reason:
          type: [string, "null"]
          description: Set when the endpoint was auto-disabled after repeated failures.
        consecutive_failures:
          type: integer
          description: Deliveries that exhausted every retry since the last success.
        last_success_at: { type: [string, "null"], format: date-time }
        last_failure_at: { type: [string, "null"], format: date-time }
        created_at: { type: string, format: date-time }

    WebhookEndpointCreate:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: Public https:// URL.
        description: { type: string, maxLength: 200 }
        events:
          type: array
          items: { type: string }
          description: Event types to receive, or `["*"]` for everything.
      required: [url, events]

    WebhookEndpointUpdate:
      type: object
      description: Any subset of fields.
      properties:
        url: { type: string, format: uri }
        description: { type: [string, "null"], maxLength: 200 }
        events:
          type: array
          items: { type: string }
        is_active: { type: boolean }

    TipGoal:
      type: object
      properties:
        enabled: { type: boolean }
        title: { type: string, example: "New PC fund" }
        amount: { type: number, description: The target., example: 500 }
        current: { type: number, description: Tips since starts_at plus manual adjustments., example: 173.5 }
        starts_at: { type: [string, "null"], format: date-time }
        ends_at: { type: [string, "null"], format: date-time }
    Overlay:
      type: object
      properties:
        id: { type: string, example: o_1a2b3c4d }
        name: { type: string, example: "Main overlay" }
        resolution:
          type: object
          description: The overlay's fixed canvas resolution in pixels.
          properties:
            width: { type: integer, example: 1920 }
            height: { type: integer, example: 1080 }
        created_at: { type: [string, "null"], format: date-time }
        updated_at: { type: [string, "null"], format: date-time }
    Counter:
      type: object
      properties:
        name:
          type: string
          description: The counter's name - its key on every surface (chat tokens, labels, this API).
          examples: ["deaths"]
        value: { type: integer }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }

    BotPlatform:
      type: object
      description: The bot on one platform's chat.
      properties:
        enabled:
          type: boolean
          description: The streamer's on/off switch for the bot in this chat.
        channel:
          type: string
          description: The streamer's login on this platform.
          examples: [somestreamer]
        identity:
          type: object
          description: Who the bot's messages appear from. On Kick always the TipPage app account (`default`).
          properties:
            type: { type: string, enum: [default, custom] }
            login: { type: string, examples: [tippagebot] }
            display_name: { type: string, examples: [TipPageBot] }

    ChatTimer:
      type: object
      properties:
        id: { type: string, examples: ["tmr_1a2b3c4d5e6f7a8b"] }
        name:
          type: string
          description: Label shown in the dashboard - viewers never see it.
        message:
          type: string
          description: What the bot posts. Same template variables as custom commands minus the argument ones.
        interval_minutes:
          type: integer
          minimum: 1
          maximum: 1440
        interval_max_minutes:
          type: [integer, "null"]
          minimum: 1
          maximum: 1440
          description: >
            `null` = fixed cadence. Set = a fresh random interval in
            [`interval_minutes`, `interval_max_minutes`] is rolled after
            every post.
        min_chat_lines:
          type: integer
          minimum: 0
          maximum: 1000
          description: >
            The timer waits until this many chat messages have been sent
            since its last post. 0 = no requirement. A due timer that
            hasn't met the bar posts as soon as chat catches up - it never
            skips a cycle.
        live_only:
          type: boolean
          description: >
            Only post while the streamer is live, judged per platform - the
            line goes to the chats whose channel is live right now.
            `min_chat_lines` counts the lines in every chat the timer posts
            in, added together.
        platforms:
          type: array
          items: { type: string, enum: [twitch, kick] }
          description: >
            Which chat(s) the timer posts in. Default both. One schedule -
            when it fires, it posts once per connected platform in the set.
        enabled: { type: boolean }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }

    ChatTimerCreate:
      type: object
      properties:
        name: { type: string, maxLength: 64 }
        message:
          type: string
          maxLength: 2500
          description: The template. Can't start with `/` or `!`. Its fixed wording (everything outside `{variables}`) must fit in one 500-character chat message; the rendered chat line is cut to 500.
        interval_minutes: { type: integer, minimum: 1, maximum: 1440 }
        interval_max_minutes:
          type: [integer, "null"]
          minimum: 1
          maximum: 1440
          description: Omit or `null` for a fixed cadence.
        min_chat_lines: { type: integer, minimum: 0, maximum: 1000, default: 0 }
        live_only: { type: boolean, default: true }
        platforms:
          type: array
          items: { type: string, enum: [twitch, kick] }
          default: [twitch, kick]
          description: Which chat(s) the timer posts in. At least one.
        enabled: { type: boolean, default: true }
      required: [name, message, interval_minutes]

    ChatTimerUpdate:
      type: object
      description: Any subset of fields.
      properties:
        name: { type: string, maxLength: 64 }
        message: { type: string, maxLength: 2500 }
        interval_minutes: { type: integer, minimum: 1, maximum: 1440 }
        interval_max_minutes: { type: [integer, "null"], minimum: 1, maximum: 1440 }
        min_chat_lines: { type: integer, minimum: 0, maximum: 1000 }
        live_only: { type: boolean }
        platforms:
          type: array
          items: { type: string, enum: [twitch, kick] }
          description: At least one.
        enabled: { type: boolean }

    CustomCommand:
      type: object
      properties:
        name:
          type: string
          description: The trigger, without the `!` prefix.
          examples: [discord]
        response:
          type: string
          description: What the bot answers. Template variables supported.
        description:
          type: [string, "null"]
          maxLength: 200
          description: >
            Optional viewer-facing blurb shown on the tip page's command
            list instead of the response.
            `null` = the page shows a preview of the response with
            variables rendered as labels (`{urlfetch:}` addresses and
            `{ai:}` prompts are never shown).
        listed:
          type: boolean
          description: Whether the command appears on the tip page's command list. It works in chat either way.
        ai_memory:
          type: boolean
          description: >
            `{ai:}` conversation memory - when true the character remembers
            this command's last 15 exchanges (with timestamps, kept until
            the command is deleted) and reacts to repeats and returning
            viewers. Only meaningful for responses containing `{ai:}`.
            Memory is per platform unless `ai_memory_shared`.
        ai_memory_shared:
          type: boolean
          description: One memory for Twitch and Kick instead of one per platform. Only meaningful with `ai_memory`.
        platforms:
          type: array
          items: { type: string, enum: [twitch, kick] }
          description: >
            Which chat(s) it runs in. Default both. A platform the streamer
            hasn't connected is simply skipped; the set can't be empty
            (use `enabled: false` to bench it).
        permission:
          type: string
          enum: [everyone, subscriber, moderator]
          description: >
            Who can trigger it. `subscriber` includes moderators;
            `moderator` includes the streamer.
        cooldown_seconds:
          type: integer
          minimum: 0
          maximum: 3600
        cooldown_type:
          type: string
          enum: [global, per_user]
          description: >
            `global` = one shared cooldown for the whole channel;
            `per_user` = each viewer gets their own.
        aliases:
          type: array
          items: { type: string }
          description: Extra triggers for the same command, also without the `!`.
        enabled: { type: boolean }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }

    CustomCommandCreate:
      type: object
      properties:
        name:
          type: string
          maxLength: 50
          pattern: "^[a-z0-9_-]+$"
          description: >
            The trigger without the `!` prefix - lowercase letters,
            numbers, hyphens, and underscores. The bot's built-in
            triggers are reserved.
        response:
          type: string
          maxLength: 2500
          description: The template. Can't start with `/` or `!`. Its fixed wording (everything outside `{variables}`) must fit in one 500-character chat message; the rendered chat line is cut to 500.
        description:
          type: [string, "null"]
          maxLength: 200
          description: Viewer-facing blurb for the tip page's command list. Plain text.
        listed: { type: boolean, default: true }
        ai_memory: { type: boolean, default: false }
        ai_memory_shared: { type: boolean, default: false }
        platforms:
          type: array
          items: { type: string, enum: [twitch, kick] }
          default: [twitch, kick]
          description: Which chat(s) the command answers in. At least one.
        permission:
          type: string
          enum: [everyone, subscriber, moderator]
          default: everyone
        cooldown_seconds: { type: integer, minimum: 0, maximum: 3600, default: 0 }
        cooldown_type: { type: string, enum: [global, per_user], default: global }
        aliases:
          type: array
          maxItems: 10
          items: { type: string }
          description: Same lexical rules as `name`; max 10.
        enabled: { type: boolean, default: true }
      required: [name, response]

    CustomCommandUpdate:
      type: object
      description: >
        Any subset of fields. `name` renames the command - the old name
        stops triggering.
      properties:
        name: { type: string, maxLength: 50, pattern: "^[a-z0-9_-]+$" }
        response: { type: string, maxLength: 2500 }
        description: { type: [string, "null"], maxLength: 200 }
        listed: { type: boolean }
        ai_memory: { type: boolean }
        ai_memory_shared: { type: boolean }
        platforms:
          type: array
          items: { type: string, enum: [twitch, kick] }
          description: At least one.
        permission: { type: string, enum: [everyone, subscriber, moderator] }
        cooldown_seconds: { type: integer, minimum: 0, maximum: 3600 }
        cooldown_type: { type: string, enum: [global, per_user] }
        aliases:
          type: array
          maxItems: 10
          items: { type: string }
        enabled: { type: boolean }

    WebhookDelivery:
      type: object
      properties:
        id: { type: string, examples: ["wd_a1b2c3d4e5f6"] }
        event_id: { type: string, examples: ["evt_9f1e2d3c4b5a6978"] }
        event_type: { type: string, examples: ["tip.created"] }
        status:
          type: string
          enum: [delivered, failed, retrying, pending]
        attempts: { type: integer }
        next_attempt_at:
          type: [string, "null"]
          format: date-time
          description: Next retry, when still pending/retrying.
        last_status:
          type: [integer, "null"]
          description: Last HTTP status from the endpoint.
        last_error: { type: [string, "null"] }
        created_at: { type: string, format: date-time }
        delivered_at: { type: [string, "null"], format: date-time }
