"/media/join":
    post:
        tags: [Joining]
        operationId: joinMediaShowing
        summary: Join a shared media showing
        description: |
            Joins a shared media product session — the showing-specific entry
            point that pairs the caller with whoever else is watching the same
            product at the same synchronization tick. Returns a media-server
            connection plus the assigned room.
        security:
            - cloudApiKey: []
              cloudAccessToken: []
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        required: [bigMediaId]
                        properties:
                            bigMediaId:
                                type: string
                                description: Public id of the media product to join.
                            entitlementId:
                                type: string
                                description: Entitlement the caller is using to access the product, when applicable.
                        additionalProperties: true
        responses:
            "200":
                description: Join payload.
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                room: { $ref: "../components/schemas/PublicRoom.yaml" }
                                connection:
                                    type: object
                                    additionalProperties: true
                                showing:
                                    type: object
                                    additionalProperties: true
                                    description: Active showing metadata (current playback time, sync tick, etc.).
            "401": { $ref: "../cloud-api.yaml#/components/responses/Unauthorized" }
            "403":
                description: Caller has no entitlement to this product.
                content:
                    application/json:
                        schema: { $ref: "../cloud-api.yaml#/components/schemas/Error" }
            "404":
                description: No matching product / showing.
                content:
                    application/json:
                        schema: { $ref: "../cloud-api.yaml#/components/schemas/Error" }
            "429": { $ref: "../cloud-api.yaml#/components/responses/TooManyRequests" }

"/lobby/join":
    post:
        tags: [Joining]
        operationId: joinLobby
        summary: Join the default lobby
        description: |
            Joins the default Bigscreen lobby — the room VR clients drop into
            when they boot up without an explicit destination. Returns a
            media-server connection.
        security:
            - cloudApiKey: []
              cloudAccessToken: []
        requestBody:
            required: false
            content:
                application/json:
                    schema:
                        type: object
                        properties:
                            preferredRegion:
                                type: string
                                description: AWS region preference for media-server selection.
                        additionalProperties: true
        responses:
            "200":
                description: Lobby 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" }
            "429": { $ref: "../cloud-api.yaml#/components/responses/TooManyRequests" }
