"/screen":
    post:
        tags: [Screens]
        operationId: createScreen
        summary: Create a screen
        description: Creates a new screen owned by the calling account.
        security:
            - cloudApiKey: []
              cloudAccessToken: []
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        properties:
                            name: { type: string }
                            type: { type: string }
                            settings:
                                type: object
                                additionalProperties: true
                        additionalProperties: true
        responses:
            "200":
                description: Created screen.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/Screen.yaml" }
            "401": { $ref: "../cloud-api.yaml#/components/responses/Unauthorized" }

"/screen/{screenId}":
    parameters:
        - in: path
          name: screenId
          required: true
          schema: { type: string }
    get:
        tags: [Screens]
        operationId: getScreen
        summary: Fetch a screen
        description: Returns a screen owned by the calling account.
        security:
            - cloudApiKey: []
              cloudAccessToken: []
        responses:
            "200":
                description: Screen record.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/Screen.yaml" }
            "401": { $ref: "../cloud-api.yaml#/components/responses/Unauthorized" }
            "403":
                description: Caller does not own this screen.
                content:
                    application/json:
                        schema: { $ref: "../cloud-api.yaml#/components/schemas/Error" }
            "404":
                description: No screen with this id.
                content:
                    application/json:
                        schema: { $ref: "../cloud-api.yaml#/components/schemas/Error" }
    put:
        tags: [Screens]
        operationId: updateScreen
        summary: Update a screen
        description: Mutates the screen's settings (owner only).
        security:
            - cloudApiKey: []
              cloudAccessToken: []
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        properties:
                            name: { type: string }
                            settings:
                                type: object
                                additionalProperties: true
                        additionalProperties: true
        responses:
            "200":
                description: Updated screen.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/Screen.yaml" }
            "401": { $ref: "../cloud-api.yaml#/components/responses/Unauthorized" }
            "403":
                description: Caller does not own this screen.
                content:
                    application/json:
                        schema: { $ref: "../cloud-api.yaml#/components/schemas/Error" }
            "404":
                description: No screen with this id.
                content:
                    application/json:
                        schema: { $ref: "../cloud-api.yaml#/components/schemas/Error" }
    delete:
        tags: [Screens]
        operationId: deleteScreen
        summary: Delete a screen
        security:
            - cloudApiKey: []
              cloudAccessToken: []
        responses:
            "200":
                description: Screen deleted.
            "401": { $ref: "../cloud-api.yaml#/components/responses/Unauthorized" }
            "403":
                description: Caller does not own this screen.
                content:
                    application/json:
                        schema: { $ref: "../cloud-api.yaml#/components/schemas/Error" }
            "404":
                description: No screen with this id.
                content:
                    application/json:
                        schema: { $ref: "../cloud-api.yaml#/components/schemas/Error" }

"/screens":
    get:
        tags: [Screens]
        operationId: getScreens
        summary: List the caller's screens
        security:
            - cloudApiKey: []
              cloudAccessToken: []
        responses:
            "200":
                description: Screens.
                content:
                    application/json:
                        schema:
                            type: array
                            items: { $ref: "../components/schemas/Screen.yaml" }
            "401": { $ref: "../cloud-api.yaml#/components/responses/Unauthorized" }

"/screen/{screenId}/session":
    parameters:
        - in: path
          name: screenId
          required: true
          schema: { type: string }
    get:
        tags: [Screens]
        operationId: getScreenMediaInfo
        summary: Active media session on a screen
        security:
            - cloudApiKey: []
              cloudAccessToken: []
        responses:
            "200":
                description: Media session info, or empty if nothing is playing.
                content:
                    application/json:
                        schema:
                            type: object
                            additionalProperties: true
                            description: '`Screen.mediaSession` payload — see `Screen` schema.'
            "401": { $ref: "../cloud-api.yaml#/components/responses/Unauthorized" }
            "404":
                description: No screen with this id.
                content:
                    application/json:
                        schema: { $ref: "../cloud-api.yaml#/components/schemas/Error" }
    put:
        tags: [Screens]
        operationId: updateScreenMediaSession
        summary: Update / start the screen's media session
        description: Starts a new session on the screen, or mutates an active one (play / pause / seek).
        security:
            - cloudApiKey: []
              cloudAccessToken: []
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        properties:
                            mediaProductId: { type: string }
                            bigMediaId: { type: string }
                            playbackState:
                                type: string
                                enum: [playing, paused, ended]
                            currentTimeMs: { type: integer }
                        additionalProperties: true
        responses:
            "200":
                description: Updated screen.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/Screen.yaml" }
            "401": { $ref: "../cloud-api.yaml#/components/responses/Unauthorized" }
            "403":
                description: Caller does not own the screen.
                content:
                    application/json:
                        schema: { $ref: "../cloud-api.yaml#/components/schemas/Error" }
            "404":
                description: No screen with this id.
                content:
                    application/json:
                        schema: { $ref: "../cloud-api.yaml#/components/schemas/Error" }
    delete:
        tags: [Screens]
        operationId: closeScreenMediaShowing
        summary: End the screen's media session
        description: Ends the active media session on a screen.
        security:
            - cloudApiKey: []
              cloudAccessToken: []
        responses:
            "200":
                description: Session closed.
            "401": { $ref: "../cloud-api.yaml#/components/responses/Unauthorized" }
            "403":
                description: Caller does not own the screen.
                content:
                    application/json:
                        schema: { $ref: "../cloud-api.yaml#/components/schemas/Error" }
            "404":
                description: No screen with this id.
                content:
                    application/json:
                        schema: { $ref: "../cloud-api.yaml#/components/schemas/Error" }

"/room/{roomId}/screen/{screenId}":
    parameters:
        - in: path
          name: roomId
          required: true
          schema: { type: string }
        - in: path
          name: screenId
          required: true
          schema: { type: string }
    put:
        tags: [Screens]
        operationId: updateRoomScreen
        summary: Attach / update a screen on a room
        description: Attaches the screen to the room (or mutates the binding's settings).
        security:
            - cloudApiKey: []
              cloudAccessToken: []
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        properties:
                            settings:
                                type: object
                                additionalProperties: true
                        additionalProperties: true
        responses:
            "200":
                description: Updated screen.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/Screen.yaml" }
            "401": { $ref: "../cloud-api.yaml#/components/responses/Unauthorized" }
            "403":
                description: Caller is not the room owner / screen owner.
                content:
                    application/json:
                        schema: { $ref: "../cloud-api.yaml#/components/schemas/Error" }
            "404":
                description: Room or screen not found.
                content:
                    application/json:
                        schema: { $ref: "../cloud-api.yaml#/components/schemas/Error" }
    delete:
        tags: [Screens]
        operationId: removeRoomScreen
        summary: Detach a screen from a room
        security:
            - cloudApiKey: []
              cloudAccessToken: []
        responses:
            "200":
                description: Detached.
            "401": { $ref: "../cloud-api.yaml#/components/responses/Unauthorized" }
            "403":
                description: Caller is not the room owner.
                content:
                    application/json:
                        schema: { $ref: "../cloud-api.yaml#/components/schemas/Error" }
            "404":
                description: Room or screen not found.
                content:
                    application/json:
                        schema: { $ref: "../cloud-api.yaml#/components/schemas/Error" }
