/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'