/recordings:
    get:
        operationId: getRecordings
        summary: Get all recordings
        description: |
            Retrieves a paginated list of all recordings available in the system.
            You can apply filters to narrow down the results based on specific criteria.

            > **Note:** If this endpoint is called using the `recordingTokenCookie` authentication method,
            > the `roomId` filter will be ignored and only recordings associated with the room included in the token will be returned.
        tags:
            - OpenVidu Meet - Recordings
        security:
            - apiKeyInHeader: []
            - accessTokenCookie: []
            - recordingTokenCookie: []
        parameters:
            # - $ref: '../components/parameters/recording-status.yaml'
            - $ref: '../components/parameters/recording-fields.yaml'
            - $ref: '../components/parameters/room-id-query.yaml'
            - $ref: '../components/parameters/max-items.yaml'
            - $ref: '../components/parameters/next-page-token.yaml'
        responses:
            '200':
                $ref: '../components/responses/success-get-recordings.yaml'
            '401':
                $ref: '../components/responses/unauthorized-error.yaml'
            '403':
                $ref: '../components/responses/forbidden-error.yaml'
            '422':
                $ref: '../components/responses/validation-error.yaml'
            '500':
                $ref: '../components/responses/internal-server-error.yaml'

    delete:
        operationId: bulkDeleteRecordings
        summary: Bulk delete recordings
        description: |
            Deletes multiple recordings at once with the specified recording IDs.

            > **Note:** If this endpoint is called using the `recordingTokenCookie` authentication method,
            > all specified recordings must belong to the same room included in the token.
            > If a recording does not belong to that room, it will not be deleted.
        tags:
            - OpenVidu Meet - Recordings
        security:
            - apiKeyInHeader: []
            - accessTokenCookie: []
            - recordingTokenCookie: []
        parameters:
            - $ref: '../components/parameters/recording-ids.yaml'
        responses:
            '200':
                $ref: '../components/responses/success-bulk-delete-recordings.yaml'
            '204':
                description: >
                    All specified recordings were deleted successfully.
                    No content is returned.
            '401':
                $ref: '../components/responses/unauthorized-error.yaml'
            '403':
                $ref: '../components/responses/forbidden-error.yaml'
            '422':
                $ref: '../components/responses/validation-error.yaml'
            '500':
                $ref: '../components/responses/internal-server-error.yaml'

/recordings/download:
    get:
        operationId: downloadRecordings
        summary: Download recordings
        description: |
            Downloads multiple recordings as a ZIP file with the specified recording IDs.
            The ZIP file will contain all recordings in MP4 format.

            > **Note:** If this endpoint is called using the `recordingTokenCookie` authentication method,
            > all specified recordings must belong to the same room included in the token.
            > If a recording does not belong to that room, it will not be included in the ZIP file.
        tags:
            - OpenVidu Meet - Recordings
        security:
            - apiKeyInHeader: []
            - accessTokenCookie: []
            - recordingTokenCookie: []
        parameters:
            - $ref: '../components/parameters/recording-ids.yaml'
        responses:
            '200':
                description: Successfully created a ZIP file containing the requested recordings
                headers:
                    Content-Disposition:
                        description: >
                            Indicates that the response is a file download.
                            The filename will be `recordings.zip`.
                        schema:
                            type: string
                            example: attachment; filename="recordings.zip"
                content:
                    application/zip:
                        schema:
                            type: string
                            format: binary
            '400':
                $ref: '../components/responses/error-recordings-not-same-room.yaml'
            '401':
                $ref: '../components/responses/unauthorized-error.yaml'
            '403':
                $ref: '../components/responses/forbidden-error.yaml'
            '422':
                $ref: '../components/responses/validation-error.yaml'
            '500':
                $ref: '../components/responses/internal-server-error.yaml'

/recordings/{recordingId}:
    get:
        operationId: getRecording
        summary: Get a recording
        description: >
            Retrieves the details of a recording with the specified recording ID.
        tags:
            - OpenVidu Meet - Recordings
        security:
            - apiKeyInHeader: []
            - accessTokenCookie: []
            - recordingTokenCookie: []
        parameters:
            - $ref: '../components/parameters/recording-id.yaml'
            - $ref: '../components/parameters/recording-secret.yaml'
        responses:
            '200':
                $ref: '../components/responses/success-get-recording.yaml'
            '400':
                $ref: '../components/responses/error-invalid-recording-secret.yaml'
            '401':
                $ref: '../components/responses/unauthorized-error.yaml'
            '403':
                $ref: '../components/responses/forbidden-error.yaml'
            '404':
                $ref: '../components/responses/error-recording-not-found.yaml'
            '422':
                $ref: '../components/responses/validation-error.yaml'
            '500':
                $ref: '../components/responses/internal-server-error.yaml'
    delete:
        operationId: deleteRecording
        summary: Delete a recording
        description: |
            Deletes a recording with the specified recording ID.

            > ⚠️ **Note:** The recording will only be deleted if it exists and is not in progress
            > (i.e., not in a state such as `ACTIVE`, `STARTING`, or `ENDING`).
        tags:
            - OpenVidu Meet - Recordings
        security:
            - apiKeyInHeader: []
            - accessTokenCookie: []
            - recordingTokenCookie: []
        parameters:
            - $ref: '../components/parameters/recording-id.yaml'
        responses:
            '204':
                description: Recording successfully deleted. No content is returned.
            '401':
                $ref: '../components/responses/unauthorized-error.yaml'
            '403':
                $ref: '../components/responses/forbidden-error.yaml'
            '404':
                $ref: '../components/responses/error-recording-not-found.yaml'
            '409':
                $ref: '../components/responses/error-recording-in-progress.yaml'
            '422':
                $ref: '../components/responses/validation-error.yaml'
            '500':
                $ref: '../components/responses/internal-server-error.yaml'
/recordings/{recordingId}/media:
    get:
        operationId: getRecordingMedia
        summary: Get recording media
        description: |
            Retrieves the media of a recording with the specified recording ID.
            The media is returned in a binary format suitable for video playback.

            This endpoint supports range requests, allowing partial content retrieval
            for video playback without downloading the entire file.
        tags:
            - OpenVidu Meet - Recordings
        security:
            - apiKeyInHeader: []
            - accessTokenCookie: []
            - recordingTokenCookie: []
        parameters:
            - $ref: '../components/parameters/recording-id.yaml'
            - $ref: '../components/parameters/recording-secret.yaml'
            - $ref: '../components/parameters/recording-range.yaml'
        responses:
            '200':
                description: Successfully retrieved the full recording media
                headers:
                    Accept-Ranges:
                        $ref: '../components/headers/accept-ranges.yaml'
                    Content-Length:
                        $ref: '../components/headers/content-length.yaml'
                    Cache-Control:
                        $ref: '../components/headers/cache-control.yaml'
                content:
                    video/mp4:
                        schema:
                            type: string
                            format: binary
            '206':
                description: Successfully retrieved a partial range of the recording media
                headers:
                    Accept-Ranges:
                        $ref: '../components/headers/accept-ranges.yaml'
                    Content-Length:
                        $ref: '../components/headers/content-length.yaml'
                    Cache-Control:
                        $ref: '../components/headers/cache-control.yaml'
                    Content-Range:
                        $ref: '../components/headers/content-range.yaml'
                content:
                    video/mp4:
                        schema:
                            type: string
                            format: binary
            '400':
                $ref: '../components/responses/error-invalid-recording-secret.yaml'
            '401':
                $ref: '../components/responses/unauthorized-error.yaml'
            '403':
                $ref: '../components/responses/forbidden-error.yaml'
            '404':
                $ref: '../components/responses/error-recording-not-found.yaml'
            '409':
                $ref: '../components/responses/error-recording-in-progress.yaml'
            '416':
                description: Requested range not satisfiable
                content:
                    application/json:
                        schema:
                            $ref: '../components/schemas/error.yaml'
                        example:
                            error: Recording Error
                            message: 'Recording "room-123--EG_XYZ--XX445" range not satisfiable. File size: 123456789'
            '422':
                $ref: '../components/responses/validation-error.yaml'
            '500':
                $ref: '../components/responses/internal-server-error.yaml'
/recordings/{recordingId}/url:
    get:
        operationId: getRecordingUrl
        summary: Get recording URL
        description: |
            Retrieves the URL of a recording with the specified recording ID.
            This URL is intended to be shared with people who do not have direct access to the recording.

        # It can be configured to be accessible by anyone (public access) or restricted to authenticated users only, 
        # depending on the `privateAccess` query parameter.
        tags:
            - OpenVidu Meet - Recordings
        security:
            - apiKeyInHeader: []
            - accessTokenCookie: []
            - recordingTokenCookie: []
        parameters:
            - $ref: '../components/parameters/recording-id.yaml'
            # - $ref: '../components/parameters/private-access.yaml'
        responses:
            '200':
                $ref: '../components/responses/success-get-recording-url.yaml'
            '401':
                $ref: '../components/responses/unauthorized-error.yaml'
            '403':
                $ref: '../components/responses/forbidden-error.yaml'
            '404':
                $ref: '../components/responses/error-recording-not-found.yaml'
            '422':
                $ref: '../components/responses/validation-error.yaml'
            '500':
                $ref: '../components/responses/internal-server-error.yaml'