"/api/media-server/register":
    post:
        tags: [Media Server]
        operationId: registerExternalMediaServer
        summary: Register a media server
        description: |
            Called by a `media_server_next` instance on startup to register itself
            with cloud_api. The server reports its IP, port range, region, instance
            metadata, etc.; cloud_api adds it to the active rotation.
        security:
            - mediaServerApiKey: []
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        required: [id, ipAddress]
                        properties:
                            id: { type: string, description: Server-reported id. }
                            version: { type: string }
                            ipAddress: { type: string }
                            minPort: { type: integer }
                            maxPort: { type: integer }
                            isAccelerated: { type: boolean }
                            region: { type: string }
                            instanceId: { type: string }
                            instanceType: { type: string }
                        additionalProperties: true
        responses:
            "200":
                description: Registered media server.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/MediaServer.yaml" }
            "401": { $ref: "../cloud-api.yaml#/components/responses/Unauthorized" }
            "422":
                description: Registration payload invalid.
                content:
                    application/json:
                        schema: { $ref: "../cloud-api.yaml#/components/schemas/Error" }

"/api/media-server":
    get:
        tags: [Media Server]
        operationId: getMediaServerInfo
        summary: Self-introspect (the server's own record)
        description: |
            Returns the cloud_api-side record for the calling media server —
            used by the server to confirm its registration is intact and to read
            cluster-managed fields (activation status, etc.). Identifies the
            caller via headers checked by `MediaServerApi.checkMediaServerHeaders`.
        security:
            - mediaServerApiKey: []
        responses:
            "200":
                description: The caller's media-server record.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/MediaServer.yaml" }
            "401": { $ref: "../cloud-api.yaml#/components/responses/Unauthorized" }
            "404":
                description: Caller is not registered. Re-call `/register`.
                content:
                    application/json:
                        schema: { $ref: "../cloud-api.yaml#/components/schemas/Error" }

"/api/media-server/manifest":
    get:
        tags: [Media Server]
        operationId: getMediaServerManifest
        summary: Current manifest of rooms the server should host
        description: |
            Returns the manifest of rooms cloud_api expects this server to be
            hosting. The server reconciles its local state against the manifest;
            divergences trigger heartbeat-driven follow-up via SQS.
        security:
            - mediaServerApiKey: []
        responses:
            "200":
                description: Manifest payload.
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                mediaServerId: { type: string }
                                generatedAt: { type: string, format: date-time }
                                rooms:
                                    type: array
                                    items:
                                        type: object
                                        properties:
                                            roomId: { type: string }
                                            roomInstanceId: { type: string }
                                            expectedOccupants: { type: integer }
                                        additionalProperties: true
                                count: { type: integer }
            "401": { $ref: "../cloud-api.yaml#/components/responses/Unauthorized" }

"/api/media-server/messages":
    get:
        tags: [Media Server]
        operationId: getMediaServerMessages
        summary: Long-poll for outbound messages
        description: |
            Long-polls for outbound commands from cloud_api to this media server
            (kicks, mutes, room-state updates). Servers that can reach SQS would
            normally consume the same messages there; this endpoint is a fallback
            for servers that can't.
        security:
            - mediaServerApiKey: []
        parameters:
            - in: query
              name: maxMessages
              schema: { type: integer, default: 10 }
            - in: query
              name: waitSeconds
              schema: { type: integer, default: 20 }
        responses:
            "200":
                description: Pending messages (possibly empty).
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                messages:
                                    type: array
                                    items:
                                        type: object
                                        properties:
                                            messageId: { type: string }
                                            type: { type: string }
                                            payload:
                                                type: object
                                                additionalProperties: true
                                            sentAt: { type: string, format: date-time }
                                count: { type: integer }
            "401": { $ref: "../cloud-api.yaml#/components/responses/Unauthorized" }

"/api/media-server/message":
    post:
        tags: [Media Server]
        operationId: postMediaServerMessage
        summary: Inbound message from a media server
        description: |
            HTTP-side of the media-server → cloud-api message bus. Servers that
            can't post to SQS directly use this endpoint; cloud_api forwards the
            message into the BigscreenCloud queue for the in-process worker to
            consume. Heartbeats, peer state changes, and error reports flow this way.
        security:
            - mediaServerApiKey: []
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        required: [type]
                        properties:
                            type:
                                type: string
                                description: Message class — `Heartbeat`, `PeerState`, `RoomEvent`, `Error`, etc.
                            payload:
                                type: object
                                description: Type-specific payload.
                                additionalProperties: true
        responses:
            "200":
                description: Message accepted.
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                accepted: { type: boolean }
                                queuedTo: { type: string, description: SQS queue the message was forwarded to. }
            "401": { $ref: "../cloud-api.yaml#/components/responses/Unauthorized" }
            "422":
                description: Message could not be parsed or routed.
                content:
                    application/json:
                        schema: { $ref: "../cloud-api.yaml#/components/schemas/Error" }
