openapi: "3.1.0"
info:
  title: ProdCom Application API
  version: 0.1.0
  description: |
    HTTP + WebSocket API for configuring, operating, and observing ProdCom.
    
    **Resource lookup:** All `:id` path parameters accept either a UUID or a
    resource name (case-insensitive, URL-encoded). UUID is attempted first; on
    failure the server falls back to name matching. If multiple resources share
    a name, the first match wins and the response includes an
    `X-Ambiguous-Name: true` header.
  contact:
    name: PRODCOM LLC
    url: https://prodcom.io
  license:
    name: MIT
    identifier: MIT

servers:
  - url: http://localhost:24480
    description: Local development (default port)

# Security is optional — when PSK is enabled in settings, Bearer token is required.
security:
  - {}
  - bearerAuth: []

tags:
  - name: System
    description: Health checks and application-level status
  - name: Items
    description: Unified ordered list of channels and groups
  - name: Channels
    description: Channel configuration and commands
  - name: Groups
    description: Group configuration
  - name: Transcript
    description: Transcript entries and real-time streams
  - name: Keywords
    description: Keyword configuration (global and channel-scoped)
  - name: Automations
    description: Automation rules (triggers, actions, policies)
  - name: Configurations
    description: Session configuration management
  - name: Audio
    description: Audio device and channel enumeration
  - name: Actions
    description: Window, font, and scroll control actions
  - name: OSC
    description: OSC server configuration, destinations, and messaging
  - name: MIDI
    description: MIDI device enumeration and messaging
  - name: Network
    description: Network sharing status
  - name: Activity
    description: Activity log
  - name: Webhooks
    description: HTTP webhook triggers for automations
  - name: WebSocket
    description: Real-time event stream via WebSocket
  - name: SSE
    description: Server-Sent Events for transcript streaming

# ---------------------------------------------------------------------------
# Paths
# ---------------------------------------------------------------------------
paths:

  # ── System ───────────────────────────────────────────────────────────────

  /api/v1/ping:
    get:
      operationId: ping
      tags: [System]
      summary: Health check
      responses:
        "200":
          description: Server is running
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    type: object
                    required: [pong]
                    properties:
                      pong:
                        type: boolean
                        const: true
                  meta:
                    $ref: "#/components/schemas/Meta"

  /api/v1/status:
    get:
      operationId: getStatus
      tags: [System]
      summary: Application status
      description: |
        Returns the current state of the application including version, uptime,
        platform, active configuration name, channel count, and server port info.
      responses:
        "200":
          description: Application status
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    $ref: "#/components/schemas/AppStatus"
                  meta:
                    $ref: "#/components/schemas/Meta"

  # ── Communication Items ──────────────────────────────────────────────────

  /api/v1/items:
    get:
      operationId: listItems
      tags: [Items]
      summary: List communication items in display order
      description: |
        Returns the unified ordered list of channels and groups as displayed in
        the UI. Each item indicates its type (`channel` or `group`), ID, name,
        and a summary of properties.
      responses:
        "200":
          description: Ordered list of communication items
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/CommunicationItem"
                  meta:
                    $ref: "#/components/schemas/Meta"

  /api/v1/items/{id}:
    get:
      operationId: getItem
      tags: [Items]
      summary: Get a single communication item
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: Communication item details
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    $ref: "#/components/schemas/CommunicationItem"
                  meta:
                    $ref: "#/components/schemas/Meta"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/items/selected:
    get:
      operationId: getSelectedItem
      tags: [Items]
      summary: Get the currently selected communication item
      responses:
        "200":
          description: The selected communication item
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    $ref: "#/components/schemas/CommunicationItem"
                  meta:
                    $ref: "#/components/schemas/Meta"
        "404":
          description: No item is currently selected
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/items/reorder:
    put:
      operationId: reorderItems
      tags: [Items]
      summary: Reorder communication items
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReorderItemsRequest"
      responses:
        "200":
          description: Items reordered
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    type: object
                    properties:
                      reordered:
                        type: boolean
                        const: true
                  meta:
                    $ref: "#/components/schemas/Meta"
        "400":
          $ref: "#/components/responses/BadRequest"

  # ── Channels ─────────────────────────────────────────────────────────────

  /api/v1/channels:
    get:
      operationId: listChannels
      tags: [Channels]
      summary: List all channels
      responses:
        "200":
          description: All channels
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Channel"
                  meta:
                    $ref: "#/components/schemas/Meta"
    post:
      operationId: createChannel
      tags: [Channels]
      summary: Create a new channel
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateChannelRequest"
      responses:
        "201":
          description: Channel created
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    $ref: "#/components/schemas/Channel"
                  meta:
                    $ref: "#/components/schemas/Meta"
        "400":
          $ref: "#/components/responses/BadRequest"

  /api/v1/channels/{id}:
    get:
      operationId: getChannel
      tags: [Channels]
      summary: Get channel details
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: Channel details
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    $ref: "#/components/schemas/Channel"
                  meta:
                    $ref: "#/components/schemas/Meta"
        "404":
          $ref: "#/components/responses/NotFound"
    put:
      operationId: updateChannel
      tags: [Channels]
      summary: Update a channel
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateChannelRequest"
      responses:
        "200":
          description: Channel updated
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    $ref: "#/components/schemas/Channel"
                  meta:
                    $ref: "#/components/schemas/Meta"
        "404":
          $ref: "#/components/responses/NotFound"
    delete:
      operationId: deleteChannel
      tags: [Channels]
      summary: Delete a channel
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: Channel deleted
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    type: object
                    properties:
                      deleted:
                        type: boolean
                        const: true
                  meta:
                    $ref: "#/components/schemas/Meta"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/channels/selected:
    get:
      operationId: getSelectedChannel
      tags: [Channels]
      summary: Get currently selected channel
      responses:
        "200":
          description: The selected channel
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    $ref: "#/components/schemas/Channel"
                  meta:
                    $ref: "#/components/schemas/Meta"
        "404":
          description: No channel is selected
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/channels/select/next:
    post:
      operationId: selectNextChannel
      tags: [Channels]
      summary: Select the next communication item
      responses:
        "200":
          description: Next item selected
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    $ref: "#/components/schemas/CommunicationItem"
                  meta:
                    $ref: "#/components/schemas/Meta"
        "404":
          description: No next item available
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/channels/select/previous:
    post:
      operationId: selectPreviousChannel
      tags: [Channels]
      summary: Select the previous communication item
      responses:
        "200":
          description: Previous item selected
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    $ref: "#/components/schemas/CommunicationItem"
                  meta:
                    $ref: "#/components/schemas/Meta"
        "404":
          description: No previous item available
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/channels/{id}/select:
    post:
      operationId: selectChannel
      tags: [Channels]
      summary: Select a channel as active
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: Channel selected
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    type: object
                    properties:
                      selected:
                        type: string
                  meta:
                    $ref: "#/components/schemas/Meta"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/channels/{id}/send:
    post:
      operationId: sendTextToChannel
      tags: [Channels]
      summary: Send typed text to a channel
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SendTextRequest"
      responses:
        "200":
          description: Text sent
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    type: object
                    properties:
                      sent:
                        type: boolean
                        const: true
                  meta:
                    $ref: "#/components/schemas/Meta"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/channels/{id}/clear:
    post:
      operationId: clearChannelTranscript
      tags: [Channels]
      summary: Clear transcript for a channel
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: Transcript cleared
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    type: object
                    properties:
                      cleared:
                        type: boolean
                        const: true
                  meta:
                    $ref: "#/components/schemas/Meta"

  /api/v1/channels/{id}/mark-read:
    post:
      operationId: markChannelRead
      tags: [Channels]
      summary: Mark all transcript entries as read for a channel
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: Transcript marked as read
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    type: object
                    properties:
                      marked:
                        type: boolean
                        const: true
                  meta:
                    $ref: "#/components/schemas/Meta"

  /api/v1/channels/{id}/keywords:
    get:
      operationId: listChannelKeywords
      tags: [Keywords]
      summary: List keywords scoped to a channel
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: Channel-scoped keywords
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Keyword"
                  meta:
                    $ref: "#/components/schemas/Meta"
        "404":
          $ref: "#/components/responses/NotFound"
    post:
      operationId: createChannelKeyword
      tags: [Keywords]
      summary: Add a keyword to a channel
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateKeywordRequest"
      responses:
        "201":
          description: Keyword added
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    $ref: "#/components/schemas/Keyword"
                  meta:
                    $ref: "#/components/schemas/Meta"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/channels/{id}/keywords/{keywordId}:
    delete:
      operationId: deleteChannelKeyword
      tags: [Keywords]
      summary: Remove a keyword from a channel
      parameters:
        - $ref: "#/components/parameters/ResourceId"
        - name: keywordId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Keyword removed
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    type: object
                    properties:
                      deleted:
                        type: boolean
                        const: true
                  meta:
                    $ref: "#/components/schemas/Meta"
        "404":
          $ref: "#/components/responses/NotFound"

  # ── Groups ───────────────────────────────────────────────────────────────

  /api/v1/groups:
    get:
      operationId: listGroups
      tags: [Groups]
      summary: List all groups
      responses:
        "200":
          description: All groups
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Group"
                  meta:
                    $ref: "#/components/schemas/Meta"
    post:
      operationId: createGroup
      tags: [Groups]
      summary: Create a new group
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateGroupRequest"
      responses:
        "201":
          description: Group created
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    $ref: "#/components/schemas/Group"
                  meta:
                    $ref: "#/components/schemas/Meta"
        "400":
          $ref: "#/components/responses/BadRequest"

  /api/v1/groups/{id}:
    get:
      operationId: getGroup
      tags: [Groups]
      summary: Get group details
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: Group details
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    $ref: "#/components/schemas/Group"
                  meta:
                    $ref: "#/components/schemas/Meta"
        "404":
          $ref: "#/components/responses/NotFound"
    put:
      operationId: updateGroup
      tags: [Groups]
      summary: Update a group
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateGroupRequest"
      responses:
        "200":
          description: Group updated
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    $ref: "#/components/schemas/Group"
                  meta:
                    $ref: "#/components/schemas/Meta"
        "404":
          $ref: "#/components/responses/NotFound"
    delete:
      operationId: deleteGroup
      tags: [Groups]
      summary: Delete a group
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: Group deleted
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    type: object
                    properties:
                      deleted:
                        type: boolean
                        const: true
                  meta:
                    $ref: "#/components/schemas/Meta"
        "404":
          $ref: "#/components/responses/NotFound"

  # ── Transcript ───────────────────────────────────────────────────────────

  /api/v1/transcript:
    get:
      operationId: listTranscriptEntries
      tags: [Transcript]
      summary: List transcript entries
      description: |
        Paginated listing of transcript entries. Pagination is **required** —
        the endpoint does not support unbounded listing.
      parameters:
        - name: channelId
          in: query
          description: Filter entries by channel UUID or name
          schema:
            type: string
        - name: since
          in: query
          description: Return entries created after this timestamp (ISO 8601)
          schema:
            type: string
            format: date-time
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: Paginated transcript entries
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/TranscriptEntry"
                  meta:
                    $ref: "#/components/schemas/PaginatedMeta"

  /api/v1/transcript/{id}:
    get:
      operationId: getTranscriptEntry
      tags: [Transcript]
      summary: Get a single transcript entry
      parameters:
        - name: id
          in: path
          required: true
          description: Transcript entry UUID
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Transcript entry
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    $ref: "#/components/schemas/TranscriptEntry"
                  meta:
                    $ref: "#/components/schemas/Meta"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/transcript/clear:
    post:
      operationId: clearTranscript
      tags: [Transcript]
      summary: Clear transcript entries
      description: |
        Clears all transcript entries, or entries for a specific channel if
        `channelId` is provided in the request body.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                channelId:
                  type: string
                  description: Optional channel ID to clear entries for
      responses:
        "200":
          description: Transcript cleared
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    type: object
                    properties:
                      cleared:
                        type: boolean
                        const: true
                  meta:
                    $ref: "#/components/schemas/Meta"

  /api/v1/transcript/mark-read:
    post:
      operationId: markTranscriptAsRead
      tags: [Transcript]
      summary: Mark transcript entries as read
      description: |
        Marks all transcript entries as read, or entries for a specific channel
        if `channelId` is provided in the request body.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                channelId:
                  type: string
                  description: Optional channel ID to mark as read
      responses:
        "200":
          description: Transcript marked as read
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    type: object
                    properties:
                      marked:
                        type: boolean
                        const: true
                  meta:
                    $ref: "#/components/schemas/Meta"

  # ── Keywords (global) ───────────────────────────────────────────────────

  /api/v1/keywords:
    get:
      operationId: listKeywords
      tags: [Keywords]
      summary: List global keywords
      responses:
        "200":
          description: Global keywords
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Keyword"
                  meta:
                    $ref: "#/components/schemas/Meta"
    post:
      operationId: createKeyword
      tags: [Keywords]
      summary: Create a global keyword
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateKeywordRequest"
      responses:
        "201":
          description: Keyword created
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    $ref: "#/components/schemas/Keyword"
                  meta:
                    $ref: "#/components/schemas/Meta"
        "400":
          $ref: "#/components/responses/BadRequest"

  /api/v1/keywords/{id}:
    get:
      operationId: getKeyword
      tags: [Keywords]
      summary: Get keyword details
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: Keyword details
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    $ref: "#/components/schemas/Keyword"
                  meta:
                    $ref: "#/components/schemas/Meta"
        "404":
          $ref: "#/components/responses/NotFound"
    put:
      operationId: updateKeyword
      tags: [Keywords]
      summary: Update a keyword
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateKeywordRequest"
      responses:
        "200":
          description: Keyword updated
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    $ref: "#/components/schemas/Keyword"
                  meta:
                    $ref: "#/components/schemas/Meta"
        "404":
          $ref: "#/components/responses/NotFound"
    delete:
      operationId: deleteKeyword
      tags: [Keywords]
      summary: Delete a keyword
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: Keyword deleted
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    type: object
                    properties:
                      deleted:
                        type: boolean
                        const: true
                  meta:
                    $ref: "#/components/schemas/Meta"
        "404":
          $ref: "#/components/responses/NotFound"

  # ── Automations ──────────────────────────────────────────────────────────

  /api/v1/automations:
    get:
      operationId: listAutomations
      tags: [Automations]
      summary: List all automations
      responses:
        "200":
          description: All automations
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Automation"
                  meta:
                    $ref: "#/components/schemas/Meta"
    post:
      operationId: createAutomation
      tags: [Automations]
      summary: Create a new automation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateAutomationRequest"
      responses:
        "201":
          description: Automation created
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    $ref: "#/components/schemas/Automation"
                  meta:
                    $ref: "#/components/schemas/Meta"
        "400":
          $ref: "#/components/responses/BadRequest"

  /api/v1/automations/{id}:
    get:
      operationId: getAutomation
      tags: [Automations]
      summary: Get automation details
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: Automation details
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    $ref: "#/components/schemas/Automation"
                  meta:
                    $ref: "#/components/schemas/Meta"
        "404":
          $ref: "#/components/responses/NotFound"
    put:
      operationId: updateAutomation
      tags: [Automations]
      summary: Update an automation
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateAutomationRequest"
      responses:
        "200":
          description: Automation updated
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    $ref: "#/components/schemas/Automation"
                  meta:
                    $ref: "#/components/schemas/Meta"
        "404":
          $ref: "#/components/responses/NotFound"
    delete:
      operationId: deleteAutomation
      tags: [Automations]
      summary: Delete an automation
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: Automation deleted
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    type: object
                    properties:
                      deleted:
                        type: boolean
                        const: true
                  meta:
                    $ref: "#/components/schemas/Meta"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/automations/{id}/trigger:
    post:
      operationId: triggerAutomation
      tags: [Automations]
      summary: Manually trigger an automation
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: Automation triggered
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    type: object
                    properties:
                      triggered:
                        type: boolean
                        const: true
                  meta:
                    $ref: "#/components/schemas/Meta"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/automations/{id}/enable:
    put:
      operationId: enableAutomation
      tags: [Automations]
      summary: Enable an automation
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: Automation enabled
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    $ref: "#/components/schemas/Automation"
                  meta:
                    $ref: "#/components/schemas/Meta"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/automations/{id}/disable:
    put:
      operationId: disableAutomation
      tags: [Automations]
      summary: Disable an automation
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: Automation disabled
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    $ref: "#/components/schemas/Automation"
                  meta:
                    $ref: "#/components/schemas/Meta"
        "404":
          $ref: "#/components/responses/NotFound"

  # ── Configurations ───────────────────────────────────────────────────────

  /api/v1/configurations:
    get:
      operationId: listConfigurations
      tags: [Configurations]
      summary: List saved session configurations
      responses:
        "200":
          description: All saved configurations
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/SessionConfiguration"
                  meta:
                    $ref: "#/components/schemas/Meta"
    post:
      operationId: createConfiguration
      tags: [Configurations]
      summary: Create a new session configuration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateConfigurationRequest"
      responses:
        "201":
          description: Configuration created
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    $ref: "#/components/schemas/SessionConfiguration"
                  meta:
                    $ref: "#/components/schemas/Meta"
        "400":
          $ref: "#/components/responses/BadRequest"

  /api/v1/configurations/active:
    get:
      operationId: getActiveConfiguration
      tags: [Configurations]
      summary: Get the active session configuration
      responses:
        "200":
          description: Active configuration
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    $ref: "#/components/schemas/SessionConfiguration"
                  meta:
                    $ref: "#/components/schemas/Meta"

  /api/v1/configurations/{id}:
    put:
      operationId: updateConfiguration
      tags: [Configurations]
      summary: Update a session configuration
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateConfigurationRequest"
      responses:
        "200":
          description: Configuration updated
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    $ref: "#/components/schemas/SessionConfiguration"
                  meta:
                    $ref: "#/components/schemas/Meta"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
    delete:
      operationId: deleteConfiguration
      tags: [Configurations]
      summary: Delete a session configuration
      description: Cannot delete the active configuration (returns 409).
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: Configuration deleted
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    type: object
                    properties:
                      deleted:
                        type: boolean
                        const: true
                  meta:
                    $ref: "#/components/schemas/Meta"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: Cannot delete the active configuration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/configurations/{id}/activate:
    post:
      operationId: activateConfiguration
      tags: [Configurations]
      summary: Activate a session configuration
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: Configuration activated
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    $ref: "#/components/schemas/SessionConfiguration"
                  meta:
                    $ref: "#/components/schemas/Meta"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/configurations/{id}/export:
    get:
      operationId: exportConfiguration
      tags: [Configurations]
      summary: Export a session configuration as base64 data
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: Exported configuration
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    $ref: "#/components/schemas/ExportedConfiguration"
                  meta:
                    $ref: "#/components/schemas/Meta"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/configurations/import:
    post:
      operationId: importConfiguration
      tags: [Configurations]
      summary: Import a session configuration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ImportConfigurationRequest"
      responses:
        "201":
          description: Configuration imported
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    $ref: "#/components/schemas/SessionConfiguration"
                  meta:
                    $ref: "#/components/schemas/Meta"
        "400":
          $ref: "#/components/responses/BadRequest"

  # ── Audio Devices ────────────────────────────────────────────────────────

  /api/v1/audio/devices:
    get:
      operationId: listAudioDevices
      tags: [Audio]
      summary: List available audio input devices
      responses:
        "200":
          description: Audio input devices
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/AudioDevice"
                  meta:
                    $ref: "#/components/schemas/Meta"

  /api/v1/audio/devices/{id}/channels:
    get:
      operationId: listAudioDeviceChannels
      tags: [Audio]
      summary: List audio channels for a device
      parameters:
        - name: id
          in: path
          required: true
          description: Audio device identifier
          schema:
            type: string
      responses:
        "200":
          description: Audio channels for the device
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/AudioChannel"
                  meta:
                    $ref: "#/components/schemas/Meta"
        "404":
          $ref: "#/components/responses/NotFound"

  # ── Actions (Window, Font, Scroll) ──────────────────────────────────────

  /api/v1/window/show:
    post:
      operationId: showWindow
      tags: [Actions]
      summary: Show the main application window
      responses:
        "200":
          description: Window shown
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OkResponse"

  /api/v1/window/hide:
    post:
      operationId: hideWindow
      tags: [Actions]
      summary: Hide the main application window
      responses:
        "200":
          description: Window hidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OkResponse"

  /api/v1/window/flash:
    post:
      operationId: flashWindow
      tags: [Actions]
      summary: Flash the main application window
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FlashWindowRequest"
      responses:
        "200":
          description: Window flashed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OkResponse"

  /api/v1/font/increase:
    post:
      operationId: increaseFontSize
      tags: [Actions]
      summary: Increase transcript font size
      responses:
        "200":
          description: Font size increased
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OkResponse"

  /api/v1/font/decrease:
    post:
      operationId: decreaseFontSize
      tags: [Actions]
      summary: Decrease transcript font size
      responses:
        "200":
          description: Font size decreased
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OkResponse"

  /api/v1/scroll/up:
    post:
      operationId: scrollUp
      tags: [Actions]
      summary: Scroll transcript up
      responses:
        "200":
          description: Scrolled up
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OkResponse"

  /api/v1/scroll/down:
    post:
      operationId: scrollDown
      tags: [Actions]
      summary: Scroll transcript down
      responses:
        "200":
          description: Scrolled down
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OkResponse"

  /api/v1/scroll/current:
    post:
      operationId: scrollToCurrent
      tags: [Actions]
      summary: Scroll transcript to the current position
      responses:
        "200":
          description: Scrolled to current
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OkResponse"

  # ── OSC ──────────────────────────────────────────────────────────────────

  /api/v1/osc/server:
    get:
      operationId: getOSCServerConfig
      tags: [OSC]
      summary: Get OSC server configuration
      responses:
        "200":
          description: OSC server config
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    $ref: "#/components/schemas/OSCServerConfig"
                  meta:
                    $ref: "#/components/schemas/Meta"
    put:
      operationId: updateOSCServerConfig
      tags: [OSC]
      summary: Update OSC server configuration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateOSCServerRequest"
      responses:
        "200":
          description: OSC server config updated
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    $ref: "#/components/schemas/OSCServerConfig"
                  meta:
                    $ref: "#/components/schemas/Meta"

  /api/v1/osc/destinations:
    get:
      operationId: listOSCDestinations
      tags: [OSC]
      summary: List OSC destinations
      responses:
        "200":
          description: OSC destinations
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/OSCDestination"
                  meta:
                    $ref: "#/components/schemas/Meta"
    post:
      operationId: createOSCDestination
      tags: [OSC]
      summary: Create an OSC destination
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateOSCDestinationRequest"
      responses:
        "201":
          description: OSC destination created
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    $ref: "#/components/schemas/OSCDestination"
                  meta:
                    $ref: "#/components/schemas/Meta"
        "400":
          $ref: "#/components/responses/BadRequest"

  /api/v1/osc/destinations/{id}:
    parameters:
      - $ref: "#/components/parameters/ResourceId"
    get:
      operationId: getOSCDestination
      tags: [OSC]
      summary: Get OSC destination details
      responses:
        "200":
          description: OSC destination details
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    $ref: "#/components/schemas/OSCDestination"
                  meta:
                    $ref: "#/components/schemas/Meta"
        "404":
          $ref: "#/components/responses/NotFound"
    put:
      operationId: updateOSCDestination
      tags: [OSC]
      summary: Update an OSC destination
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateOSCDestinationRequest"
      responses:
        "200":
          description: OSC destination updated
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    $ref: "#/components/schemas/OSCDestination"
                  meta:
                    $ref: "#/components/schemas/Meta"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
    delete:
      operationId: deleteOSCDestination
      tags: [OSC]
      summary: Delete an OSC destination
      responses:
        "200":
          description: OSC destination deleted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeletedResponse"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/osc/send:
    post:
      operationId: sendOSC
      tags: [OSC]
      summary: Send an OSC message
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SendOSCRequest"
      responses:
        "200":
          description: OSC message sent
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SentResponse"
        "400":
          $ref: "#/components/responses/BadRequest"

  # ── MIDI ─────────────────────────────────────────────────────────────────

  /api/v1/midi:
    get:
      operationId: listMIDIDevicesAlias
      tags: [MIDI]
      summary: List available MIDI devices (alias for /midi/devices)
      responses:
        "200":
          description: MIDI devices
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/MIDIDevice"
                  meta:
                    $ref: "#/components/schemas/Meta"

  /api/v1/midi/devices:
    get:
      operationId: listMIDIDevices
      tags: [MIDI]
      summary: List available MIDI devices
      responses:
        "200":
          description: MIDI devices
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/MIDIDevice"
                  meta:
                    $ref: "#/components/schemas/Meta"

  /api/v1/midi/send:
    post:
      operationId: sendMIDI
      tags: [MIDI]
      summary: Send a MIDI message
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SendMIDIRequest"
      responses:
        "200":
          description: MIDI message sent
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SentResponse"
        "400":
          $ref: "#/components/responses/BadRequest"

  # ── Network ──────────────────────────────────────────────────────────────

  /api/v1/network:
    get:
      operationId: getNetworkStatus
      tags: [Network]
      summary: Get network sharing status
      responses:
        "200":
          description: Network status
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    $ref: "#/components/schemas/NetworkStatus"
                  meta:
                    $ref: "#/components/schemas/Meta"

  # ── Activity ─────────────────────────────────────────────────────────────

  /api/v1/activity:
    get:
      operationId: listActivityEntries
      tags: [Activity]
      summary: List activity log entries
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: Paginated activity entries
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ActivityEntry"
                  meta:
                    $ref: "#/components/schemas/PaginatedMeta"

  # ── Webhooks ─────────────────────────────────────────────────────────────

  /api/v1/webhooks/{path}:
    post:
      operationId: triggerWebhook
      tags: [Webhooks]
      summary: Fire a webhook automation
      description: |
        Triggers any automation whose trigger type is `httpWebhook` and whose
        `path` matches. Path segments after `/webhooks/` are joined with `/`
        (e.g. `/webhooks/nested/path` matches path `nested/path`).
      parameters:
        - name: path
          in: path
          required: true
          description: Webhook path registered in the automation trigger
          schema:
            type: string
      responses:
        "200":
          description: Webhook triggered successfully
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data:
                    type: object
                    required: [triggered]
                    properties:
                      triggered:
                        type: boolean
                        const: true
                  meta:
                    $ref: "#/components/schemas/Meta"
        "404":
          $ref: "#/components/responses/NotFound"
        "405":
          description: Only POST is allowed

  # ── WebSocket ────────────────────────────────────────────────────────────

  /api/v1/ws:
    get:
      operationId: connectWebSocket
      tags: [WebSocket]
      summary: Open a WebSocket connection for real-time events
      description: |
        Upgrade to a WebSocket connection. Once connected the server sends
        JSON-framed events for transcript updates, channel changes, and
        automation triggers.

        **Authentication:** When PSK is enabled, provide the key via
        `Authorization: Bearer <key>` header or `?key=<key>` query parameter.

        **Subscribe:** Send `{"type":"subscribe","events":["transcript"]}` to
        filter events. Supported event categories: `transcript`, `channel`,
        `automation`, `status`.

        **Welcome message:** The server sends a `{"type":"welcome"}` frame
        immediately after upgrade.

        **Heartbeat:** The server sends periodic `{"type":"heartbeat"}`
        frames; respond with the same to keep the connection alive.
      parameters:
        - name: key
          in: query
          required: false
          description: API key for WebSocket auth (alternative to Bearer header)
          schema:
            type: string
      responses:
        "101":
          description: WebSocket upgrade successful
        "401":
          $ref: "#/components/responses/Unauthorized"

  # ── SSE ──────────────────────────────────────────────────────────────────

  /api/v1/transcript/stream:
    get:
      operationId: streamTranscript
      tags: [SSE]
      summary: Server-Sent Events stream for transcript updates
      description: |
        Opens a persistent HTTP connection that streams transcript events
        as `text/event-stream`. Each event is a JSON object representing a
        new, updated, or completed transcript entry.

        Use the optional `channelId` query parameter to limit events to a
        single channel.

        Events include opaque SSE IDs. Reconnect with `Last-Event-ID` and the
        same channel filter to replay events after that cursor. Replay is
        memory-only and bounded to 512 events and 2 MiB across the server.
        An unknown, evicted, cleared, or previous-server cursor yields
        `transcript.reset` with `reason: cursor_unavailable`. Clients must
        reload transcript state on reset; this is not durable history.
        Clearing transcripts or stopping the API discards the replay buffer.
        `transcript.cursor` events carry the latest ID with empty object data.
        Initial connections remain live-only unless `snapshot=true` is passed
        without Last-Event-ID. Snapshot mode first sends `transcript.snapshot`
        containing an array of entries, followed by events collected since its
        starting cursor, then live events. Merge by entry ID and revision;
        ignore older/equal content revisions already included in the snapshot.
        Snapshots are bounded to 3000 entries and 2 MiB. An incomplete snapshot
        or lost replay history yields `transcript.reset` with reason
        `snapshot_unavailable`, never a silently truncated snapshot.
        Pending output is bounded to 4 MiB per connection; slow connections
        close and must reconnect/reload if their cursor is no longer retained.
      parameters:
        - name: snapshot
          in: query
          required: false
          description: Request a bounded initial snapshot plus buffered updates; ignored when Last-Event-ID is supplied
          schema:
            type: boolean
            default: false
        - name: Last-Event-ID
          in: header
          required: false
          description: Opaque SSE cursor from the previous connection using the same channel filter
          schema:
            type: string
        - name: channelId
          in: query
          required: false
          description: Filter events to a specific channel
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: SSE stream opened
          content:
            text/event-stream:
              schema:
                type: string
                description: Newline-delimited SSE events

  # ── OpenAPI Spec ─────────────────────────────────────────────────────────

  /api/v1/openapi.yaml:
    get:
      operationId: getOpenAPISpec
      tags: [System]
      summary: Retrieve the OpenAPI specification
      description: Returns the raw OpenAPI 3.1 YAML specification.
      security: []
      responses:
        "200":
          description: OpenAPI specification
          content:
            text/yaml:
              schema:
                type: string

# ---------------------------------------------------------------------------
# Components
# ---------------------------------------------------------------------------
components:

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        Pre-shared key (PSK) authentication. When enabled in ProdCom settings,
        include the API key in the Authorization header: `Bearer <key>`.

  parameters:
    ResourceId:
      name: id
      in: path
      required: true
      description: Resource UUID or name (case-insensitive). UUID is tried first.
      schema:
        type: string

    Limit:
      name: limit
      in: query
      description: "Maximum number of results to return (default: 50, max: 200)"
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 50

    Offset:
      name: offset
      in: query
      description: Number of results to skip for pagination
      schema:
        type: integer
        minimum: 0
        default: 0

  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"

    BadRequest:
      description: Invalid request parameters or body
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"

    Unauthorized:
      description: Authentication required or invalid API key
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"

  schemas:

    # ── Envelope ──────────────────────────────────────────────────────────

    Meta:
      type: object
      required: [timestamp]
      properties:
        timestamp:
          type: string
          format: date-time
          description: Server timestamp of the response
        requestId:
          type: string
          description: Unique identifier for this request
      example:
        timestamp: "2026-04-13T14:30:00Z"

    PaginatedMeta:
      allOf:
        - $ref: "#/components/schemas/Meta"
        - type: object
          required: [totalCount, hasMore]
          properties:
            totalCount:
              type: integer
              description: Total number of matching results
            hasMore:
              type: boolean
              description: Whether more results exist beyond this page
      example:
        timestamp: "2026-04-13T14:30:00Z"
        totalCount: 47
        hasMore: true

    ErrorResponse:
      type: object
      required: [error, meta]
      properties:
        error:
          type: object
          required: [code, message]
          properties:
            code:
              type: string
              enum:
                - BAD_REQUEST
                - UNAUTHORIZED
                - NOT_FOUND
                - CONFLICT
                - VALIDATION_ERROR
                - METHOD_NOT_ALLOWED
                - NOT_IMPLEMENTED
                - RATE_LIMITED
                - INTERNAL_ERROR
            message:
              type: string
              description: Human-readable error description
        meta:
          $ref: "#/components/schemas/Meta"
      example:
        error:
          code: NOT_FOUND
          message: Channel not found
        meta:
          timestamp: "2026-04-13T14:30:00Z"

    # ── System ────────────────────────────────────────────────────────────

    AppStatus:
      type: object
      required:
        - version
        - platform
        - uptime
        - activeConfigurationName
        - channelCount
        - apiPort
      properties:
        version:
          type: string
          description: Application version (e.g. "2.3.0")
        platform:
          type: string
          enum: [macOS, iOS]
        uptime:
          type: number
          format: double
          description: Seconds since the API server started
        activeConfigurationName:
          type: string
          description: Name of the active session configuration
        channelCount:
          type: integer
          description: Total number of channels in the active configuration
        apiPort:
          type: integer
          description: Port the API server is listening on
        oscPort:
          type: [integer, "null"]
          description: Port the OSC server is listening on (null if disabled)
        networkBroadcastPort:
          type: [integer, "null"]
          description: Port the network broadcast server is using (null if disabled)
      example:
        version: "2.3.0"
        platform: macOS
        uptime: 3621.5
        activeConfigurationName: Festival 2026 - Mons
        channelCount: 4
        apiPort: 24480
        oscPort: 9000
        networkBroadcastPort: null

    # ── Communication Items ───────────────────────────────────────────────

    CommunicationItem:
      type: object
      required: [type, id, name]
      properties:
        type:
          type: string
          enum: [channel, group]
        id:
          type: string
          format: uuid
        name:
          type: string
        channel:
          $ref: "#/components/schemas/Channel"
          description: Present when type is "channel"
        group:
          $ref: "#/components/schemas/Group"
          description: Present when type is "group"
      example:
        type: channel
        id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        name: Stage Left TB
        channel:
          id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
          name: Stage Left TB
          color: "#FF6B35"
          sourceType: localAudio
          speechLocale: en-US
          typingEnabled: false
          isSelected: true
          unreadCount: 3

    # ── Channels ──────────────────────────────────────────────────────────

    Channel:
      type: object
      required:
        - id
        - name
        - sourceType
        - typingEnabled
        - isSelected
        - unreadCount
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        color:
          type: [string, "null"]
          description: Hex color string (e.g. "#FF6B35")
        sourceType:
          type: string
          enum: [localAudio, network]
        speechLocale:
          type: [string, "null"]
          description: BCP 47 locale code (e.g. "en-US")
        typingEnabled:
          type: boolean
          description: Whether this channel accepts typed input
        isSelected:
          type: boolean
          description: Whether this is the currently active channel
        unreadCount:
          type: integer
          description: Number of unseen transcript entries
        keywords:
          type: array
          items:
            $ref: "#/components/schemas/Keyword"
          description: Keywords scoped to this channel
      example:
        id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        name: Stage Left TB
        color: "#FF6B35"
        sourceType: localAudio
        speechLocale: en-US
        typingEnabled: false
        isSelected: true
        unreadCount: 3
        keywords:
          - id: "kw-001"
            text: cue
            shouldHighlight: true
            highlightColor: "#00FF00"
            isSensitive: false

    # ── Groups ────────────────────────────────────────────────────────────

    Group:
      type: object
      required:
        - id
        - name
        - channelIds
        - shareOnNetwork
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        channelIds:
          type: array
          items:
            type: string
            format: uuid
          description: IDs of channels in this group
        shareOnNetwork:
          type: boolean
        groupPassword:
          type: [string, "null"]
          description: Omitted in responses for security; included in write requests
        keywords:
          type: array
          items:
            $ref: "#/components/schemas/Keyword"
          description: Keywords scoped to this group
      example:
        id: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
        name: All Cameras
        channelIds:
          - "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
          - "c3d4e5f6-a7b8-9012-cdef-123456789012"
        shareOnNetwork: true

    # ── Transcript ────────────────────────────────────────────────────────

    TranscriptEntry:
      type: object
      required:
        - id
        - channelId
        - text
        - source
        - inProgress
        - hasBeenSeen
        - date
      properties:
        id:
          type: string
          format: uuid
        channelId:
          type: string
          format: uuid
        channelName:
          type: string
          description: Denormalized channel name for convenience
        text:
          type: string
        source:
          type: string
          enum: [audio, typed, automation]
        inProgress:
          type: boolean
          description: True while speech recognition is still processing
        hasBeenSeen:
          type: boolean
        date:
          type: string
          format: date-time
        completeDate:
          type: [string, "null"]
          format: date-time
        seenDate:
          type: [string, "null"]
          format: date-time
        translatedText:
          type: [string, "null"]
        triggeredAutomations:
          type: array
          items:
            type: string
          description: Names of automations triggered by this entry
        revision:
          type: integer
          minimum: 1
          description: Monotonic content revision for this stable entry ID; absent from older servers
      example:
        id: "e1e2e3e4-f5f6-7890-abcd-ef1234567890"
        channelId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        channelName: Stage Left TB
        text: "Standby for cue 12, go on my mark"
        source: audio
        inProgress: false
        hasBeenSeen: true
        date: "2026-04-13T14:28:15Z"
        completeDate: "2026-04-13T14:28:18Z"
        seenDate: "2026-04-13T14:28:20Z"
        translatedText: null
        triggeredAutomations:
          - Flash on cue

    # ── Keywords ──────────────────────────────────────────────────────────

    Keyword:
      type: object
      required:
        - id
        - text
        - shouldHighlight
        - isSensitive
      properties:
        id:
          type: string
          format: uuid
        text:
          type: string
          description: Substring to match (case-insensitive)
        shouldHighlight:
          type: boolean
        highlightColor:
          type: [string, "null"]
          description: Hex color string
        replacementText:
          type: [string, "null"]
          description: Display text override
        isSensitive:
          type: boolean
          description: When true, matched text is replaced with asterisks in the UI
      example:
        id: "kw-001"
        text: standby
        shouldHighlight: true
        highlightColor: "#FFFF00"
        replacementText: null
        isSensitive: false

    # ── Automations ───────────────────────────────────────────────────────

    Automation:
      type: object
      required:
        - id
        - name
        - enabled
        - executionPolicy
        - trigger
        - actions
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        enabled:
          type: boolean
        executionPolicy:
          type: string
          enum: [cancelAndRestart, ignoreIfRunning]
        trigger:
          $ref: "#/components/schemas/AutomationTrigger"
        actions:
          type: array
          items:
            $ref: "#/components/schemas/AutomationAction"
      example:
        id: "auto-001"
        name: Flash on cue
        enabled: true
        executionPolicy: cancelAndRestart
        trigger:
          type: message
          keywords:
            - cue
          triggerEarly: false
        actions:
          - type: flashWindow
            duration: 2.0
            text: "CUE DETECTED"
            repeats: 3

    AutomationTrigger:
      type: object
      required: [type]
      properties:
        type:
          type: string
          enum: [message, midi, osc, httpWebhook]
        channelId:
          type: [string, "null"]
          format: uuid
          description: "Filter trigger to a specific channel (message triggers)"
        keywords:
          type: array
          items:
            type: string
          description: "Keyword filter (message triggers)"
        triggerEarly:
          type: boolean
          description: "Trigger before speech finalization (message triggers)"
        midiCommand:
          type: object
          description: "MIDI command details (midi triggers)"
        oscTrigger:
          type: object
          description: "OSC pattern + argument filters (osc triggers)"
        path:
          type: [string, "null"]
          description: "Webhook URL path to match (httpWebhook triggers)"
      example:
        type: message
        keywords:
          - cue
        triggerEarly: false

    AutomationAction:
      type: object
      required: [type]
      properties:
        type:
          type: string
          enum:
            - flashWindow
            - showWindow
            - hideWindow
            - selectChannel
            - selectPreviousChannel
            - selectNextChannel
            - scrollTranscriptUp
            - scrollTranscriptDown
            - scrollTranscriptToCurrent
            - clearTranscript
            - markTranscriptAsRead
            - increaseTranscriptFontSize
            - decreaseTranscriptFontSize
            - midi
            - osc
            - sendTextToChannel
            - httpRequest
        delay:
          type: number
          format: double
          description: Delay in seconds before executing this action
        text:
          type: [string, "null"]
          description: "Text parameter (flashWindow text, sendTextToChannel template)"
        duration:
          type: [number, "null"]
          format: double
          description: "Duration in seconds (flashWindow)"
        repeats:
          type: [integer, "null"]
          description: "Repeat count (flashWindow)"
        targetChannelId:
          type: [string, "null"]
          format: uuid
          description: "Target channel (selectChannel, clearTranscript, etc.)"
        target:
          type: [string, "null"]
          enum: [all, selected, channel, dynamic]
          description: "Target resolution for channel-scoped actions"
        method:
          type: [string, "null"]
          enum: [get, post, put, patch, delete]
          description: "HTTP method (httpRequest actions)"
        url:
          type: [string, "null"]
          format: uri
          description: "Request URL (httpRequest actions)"
        headers:
          type: [object, "null"]
          additionalProperties:
            type: string
          description: "HTTP headers (httpRequest actions)"
        body:
          type: [string, "null"]
          description: "Request body template — supports {value} placeholders (httpRequest actions)"
        timeout:
          type: [number, "null"]
          format: double
          description: "Request timeout in seconds (httpRequest actions)"
      example:
        type: flashWindow
        duration: 2.0
        text: "CUE DETECTED"
        repeats: 3

    # ── Configurations ────────────────────────────────────────────────────

    SessionConfiguration:
      type: object
      required:
        - id
        - name
        - channelCount
        - automationCount
        - keywordCount
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        channelCount:
          type: integer
          description: Number of channels in this configuration
        automationCount:
          type: integer
          description: Number of automations
        keywordCount:
          type: integer
          description: Number of global keywords
      example:
        id: "cfg-001"
        name: Festival 2026 - Mons
        channelCount: 4
        automationCount: 3
        keywordCount: 5

    # ── Audio ─────────────────────────────────────────────────────────────

    AudioDevice:
      type: object
      required:
        - id
        - name
        - channelCount
      properties:
        id:
          type: string
          description: System audio device identifier
        name:
          type: string
        manufacturer:
          type: [string, "null"]
        channelCount:
          type: integer
          description: Number of audio input channels
      example:
        id: "dev-ubmadi"
        name: UB Madi
        manufacturer: DiGiCo
        channelCount: 16

    AudioChannel:
      type: object
      required:
        - index
      properties:
        index:
          type: integer
          description: Zero-based audio channel index
        label:
          type: [string, "null"]
          description: Audio channel label (if provided by the device)
      example:
        index: 0
        label: Channel 1

    # ── Shared Response Envelopes ─────────────────────────────────────────

    OkResponse:
      type: object
      required: [data, meta]
      properties:
        data:
          type: object
          required: [ok]
          properties:
            ok:
              type: boolean
              const: true
        meta:
          $ref: "#/components/schemas/Meta"
      example:
        data:
          ok: true
        meta:
          timestamp: "2026-04-13T14:30:00Z"

    DeletedResponse:
      type: object
      required: [data, meta]
      properties:
        data:
          type: object
          required: [deleted]
          properties:
            deleted:
              type: boolean
              const: true
        meta:
          $ref: "#/components/schemas/Meta"
      example:
        data:
          deleted: true
        meta:
          timestamp: "2026-04-13T14:30:00Z"

    SentResponse:
      type: object
      required: [data, meta]
      properties:
        data:
          type: object
          required: [sent]
          properties:
            sent:
              type: boolean
              const: true
        meta:
          $ref: "#/components/schemas/Meta"
      example:
        data:
          sent: true
        meta:
          timestamp: "2026-04-13T14:30:00Z"

    # ── Request Bodies ────────────────────────────────────────────────────

    ReorderItemsRequest:
      type: object
      required: [ids]
      properties:
        ids:
          type: array
          items:
            type: string
            format: uuid
          description: Ordered list of item IDs
      example:
        ids:
          - "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
          - "b2c3d4e5-f6a7-8901-bcde-f12345678901"
          - "c3d4e5f6-a7b8-9012-cdef-123456789012"

    CreateChannelRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
        color:
          type: [string, "null"]
          description: Hex color string (e.g. "#FF6B35")
        speechLocale:
          type: [string, "null"]
          description: BCP 47 locale code (e.g. "en-US")
        typingEnabled:
          type: boolean
      example:
        name: Stage Right TB
        color: "#4A90D9"
        speechLocale: en-US
        typingEnabled: false

    UpdateChannelRequest:
      type: object
      properties:
        name:
          type: string
        color:
          type: [string, "null"]
          description: Hex color string
        speechLocale:
          type: [string, "null"]
          description: BCP 47 locale code
        typingEnabled:
          type: boolean
      example:
        name: Stage Right TB (Updated)
        color: "#FF6B35"

    SendTextRequest:
      type: object
      required: [text]
      properties:
        text:
          type: string
      example:
        text: "Standby lighting cue 12"

    CreateGroupRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
        channelIds:
          type: array
          items:
            type: string
            format: uuid
        shareOnNetwork:
          type: boolean
      example:
        name: All Cameras
        channelIds:
          - "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
          - "c3d4e5f6-a7b8-9012-cdef-123456789012"
        shareOnNetwork: true

    UpdateGroupRequest:
      type: object
      properties:
        name:
          type: string
        channelIds:
          type: array
          items:
            type: string
            format: uuid
        shareOnNetwork:
          type: boolean
      example:
        name: All Cameras (Updated)
        shareOnNetwork: false

    CreateKeywordRequest:
      type: object
      required: [text]
      properties:
        text:
          type: string
        shouldHighlight:
          type: boolean
        highlightColor:
          type: [string, "null"]
        replacementText:
          type: [string, "null"]
        isSensitive:
          type: boolean
      example:
        text: standby
        shouldHighlight: true
        highlightColor: "#FFFF00"
        isSensitive: false

    UpdateKeywordRequest:
      type: object
      properties:
        text:
          type: string
        shouldHighlight:
          type: boolean
        highlightColor:
          type: [string, "null"]
        replacementText:
          type: [string, "null"]
        isSensitive:
          type: boolean
      example:
        highlightColor: "#FF0000"
        shouldHighlight: true

    CreateAutomationRequest:
      type: object
      required: [name, trigger, actions]
      properties:
        name:
          type: string
        enabled:
          type: boolean
        executionPolicy:
          type: string
          enum: [cancelAndRestart, ignoreIfRunning]
        trigger:
          $ref: "#/components/schemas/AutomationTrigger"
        actions:
          type: array
          items:
            $ref: "#/components/schemas/AutomationAction"
      example:
        name: Flash on cue
        enabled: true
        executionPolicy: cancelAndRestart
        trigger:
          type: message
          keywords:
            - cue
        actions:
          - type: flashWindow
            duration: 2.0
            text: "CUE DETECTED"
            repeats: 3

    UpdateAutomationRequest:
      type: object
      properties:
        name:
          type: string
        enabled:
          type: boolean
        executionPolicy:
          type: string
          enum: [cancelAndRestart, ignoreIfRunning]
        trigger:
          $ref: "#/components/schemas/AutomationTrigger"
        actions:
          type: array
          items:
            $ref: "#/components/schemas/AutomationAction"
      example:
        enabled: false

    CreateConfigurationRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
      example:
        name: Festival 2026 - Mons

    UpdateConfigurationRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
      example:
        name: Festival 2026 - Mons (Updated)

    ImportConfigurationRequest:
      type: object
      required: [data]
      properties:
        data:
          type: string
          description: Base64-encoded configuration data
        name:
          type: string
          description: Optional override name for the imported configuration
      example:
        data: "dGhpcyBpcyBiYXNlNjQgZW5jb2RlZCBjb25maWd1cmF0aW9uIGRhdGE="
        name: Imported Show Config

    ExportedConfiguration:
      type: object
      required: [name, data]
      properties:
        name:
          type: string
        data:
          type: string
          description: Base64-encoded configuration data
      example:
        name: Festival 2026 - Mons
        data: "dGhpcyBpcyBiYXNlNjQgZW5jb2RlZCBjb25maWd1cmF0aW9uIGRhdGE="

    FlashWindowRequest:
      type: object
      properties:
        duration:
          type: number
          format: double
          description: Flash duration in seconds
        text:
          type: string
          description: Text to display during flash
        repeats:
          type: integer
          description: Number of flash repeats
      example:
        duration: 2.0
        text: "ATTENTION"
        repeats: 3

    # ── OSC Models ────────────────────────────────────────────────────────

    OSCServerConfig:
      type: object
      required: [isEnabled, receivePort]
      properties:
        isEnabled:
          type: boolean
        receivePort:
          type: integer
      example:
        isEnabled: true
        receivePort: 9000

    UpdateOSCServerRequest:
      type: object
      properties:
        isEnabled:
          type: boolean
        receivePort:
          type: integer
      example:
        isEnabled: true
        receivePort: 9000

    OSCDestination:
      type: object
      required: [id, name, host, port, isEnabled]
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        host:
          type: string
        port:
          type: integer
        isEnabled:
          type: boolean
      example:
        id: "osc-001"
        name: Lighting Console
        host: 192.168.1.100
        port: 7000
        isEnabled: true

    CreateOSCDestinationRequest:
      type: object
      required: [name, host, port]
      properties:
        name:
          type: string
          minLength: 1
        host:
          type: string
          minLength: 1
        port:
          type: integer
          minimum: 1
          maximum: 65535
        isEnabled:
          type: boolean
      example:
        name: Lighting Console
        host: 192.168.1.100
        port: 7000
        isEnabled: true

    UpdateOSCDestinationRequest:
      type: object
      properties:
        name:
          type: string
        host:
          type: string
        port:
          type: integer
          minimum: 1
          maximum: 65535
        isEnabled:
          type: boolean
      example:
        port: 8000
        isEnabled: false

    SendOSCRequest:
      type: object
      required: [addressPattern]
      properties:
        destinationId:
          type: string
          description: Target destination ID (optional)
        addressPattern:
          type: string
          minLength: 1
          description: OSC address pattern
        arguments:
          type: array
          items:
            $ref: "#/components/schemas/OSCArgument"
      example:
        destinationId: "osc-001"
        addressPattern: /cue/fire
        arguments:
          - type: int
            value: "12"
          - type: float
            value: "0.75"

    OSCArgument:
      type: object
      required: [type, value]
      properties:
        type:
          type: string
          enum: [int, float, string, bool]
        value:
          type: string
          description: String representation of the argument value
      example:
        type: float
        value: "0.75"

    # ── MIDI Models ───────────────────────────────────────────────────────

    MIDIDevice:
      type: object
      required: [id, name, isInput, isOutput]
      properties:
        id:
          type: string
        name:
          type: string
        manufacturer:
          type: [string, "null"]
        isInput:
          type: boolean
        isOutput:
          type: boolean
      example:
        id: "midi-001"
        name: X-Touch Mini
        manufacturer: Behringer
        isInput: true
        isOutput: true

    SendMIDIRequest:
      type: object
      required: [type, channel]
      properties:
        deviceId:
          type: string
          description: Target MIDI device ID (optional)
        type:
          type: string
          enum: [noteOn, noteOff, controlChange, programChange]
        channel:
          type: integer
          minimum: 0
          maximum: 15
        note:
          type: integer
          description: Note number (noteOn/noteOff)
        velocity:
          type: integer
          description: Velocity (noteOn/noteOff)
        controller:
          type: integer
          description: Controller number (controlChange)
        value:
          type: integer
          description: Controller value (controlChange)
        program:
          type: integer
          description: Program number (programChange)
      example:
        type: noteOn
        channel: 0
        note: 60
        velocity: 127

    # ── Network ───────────────────────────────────────────────────────────

    NetworkStatus:
      type: object
      required: [isEnabled, port, connectedPeers]
      properties:
        isEnabled:
          type: boolean
        port:
          type: integer
        connectedPeers:
          type: integer
      example:
        isEnabled: true
        port: 24424
        connectedPeers: 2

    # ── Activity ──────────────────────────────────────────────────────────

    ActivityEntry:
      type: object
      required: [id, timestamp, category, direction, summary]
      properties:
        id:
          type: string
        timestamp:
          type: string
          format: date-time
        category:
          type: string
        direction:
          type: string
        summary:
          type: string
      example:
        id: "act-001"
        timestamp: "2026-04-13T14:30:00Z"
        category: api
        direction: inbound
        summary: "GET /api/v1/channels — 200 OK"
