"/channels/{version}/{name}":
    parameters:
        - in: path
          name: version
          required: true
          schema: { type: string }
          description: Channel-group schema version (`v1`, `v2`, …).
        - in: path
          name: name
          required: true
          schema: { type: string }
          description: Channel-group name.
    get:
        tags: [Channels]
        operationId: getChannelGroup
        summary: Fetch a channel group
        description: Returns a Bigscreen-curated channel group — its channels, atlas textures, and metadata.
        security:
            - cloudApiKey: []
              cloudAccessToken: []
        responses:
            "200":
                description: Channel group payload.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/ChannelGroup.yaml" }
            "401": { $ref: "../cloud-api.yaml#/components/responses/Unauthorized" }
            "404":
                description: No channel group with this name / version.
                content:
                    application/json:
                        schema: { $ref: "../cloud-api.yaml#/components/schemas/Error" }

"/channel/info/{channel_id}":
    parameters:
        - in: path
          name: channel_id
          required: true
          schema: { type: string }
    get:
        tags: [Channels]
        operationId: getChannelInfo
        summary: Fetch a single channel
        description: Returns a single channel by id.
        security:
            - cloudApiKey: []
              cloudAccessToken: []
        responses:
            "200":
                description: Channel record.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/Channel.yaml" }
            "401": { $ref: "../cloud-api.yaml#/components/responses/Unauthorized" }
            "404":
                description: No channel with this id.
                content:
                    application/json:
                        schema: { $ref: "../cloud-api.yaml#/components/schemas/Error" }

"/channel/join":
    post:
        tags: [Channels]
        operationId: joinChannel
        summary: Join a channel's live stream
        description: |
            Joins the live streaming room for a channel — used when the user
            taps a channel tile in the VR client. Returns a media-server connection.
        security:
            - cloudApiKey: []
              cloudAccessToken: []
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        required: [channelId]
                        properties:
                            channelId: { type: string }
                            streamIndex: { type: integer }
        responses:
            "200":
                description: Join payload.
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                room: { $ref: "../components/schemas/PublicRoom.yaml" }
                                connection:
                                    type: object
                                    additionalProperties: true
            "401": { $ref: "../cloud-api.yaml#/components/responses/Unauthorized" }
            "403":
                description: Caller is not allowed in this channel (geo-restricted, etc.).
                content:
                    application/json:
                        schema: { $ref: "../cloud-api.yaml#/components/schemas/Error" }
            "404":
                description: No channel with this id.
                content:
                    application/json:
                        schema: { $ref: "../cloud-api.yaml#/components/schemas/Error" }
