openapi: 3.0.1
info:
    version: v1
    title: OpenVidu Meet Internal REST API
    description: >
        The OpenVidu Meet Internal REST API allows seamless integration of OpenVidu Meet rooms into your application.
        This REST API provides endpoints to manage rooms and recordings in OpenVidu Meet.
    termsOfService: https://openvidu.io/conditions/terms-of-service/
    contact:
        name: OpenVidu
        email: commercial@openvidu.io
        url: https://openvidu.io/support/

servers:
    - url: http://localhost:6080/meet/internal-api/v1
      description: Development server
tags:
    - name: Internal API - Authentication
      description: Authentication operations
    - name: Internal API - Rooms
      description: Operations related to managing OpenVidu Meet rooms
    - name: Internal API - Participant
      description: Operations related to managing participants in OpenVidu Meet rooms
    - name: Internal API - Recordings
      description: Operations related to managing OpenVidu Meet recordings

paths:
    /auth/login:
        post:
            operationId: loginUser
            summary: Login to OpenVidu Meet
            description: >
                Authenticates a user and returns an access and refresh token in cookies.
            tags:
                - Internal API - Authentication
            requestBody:
                description: User credentials
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                username:
                                    type: string
                                    example: 'admin'
                                    description: The username of the user.
                                password:
                                    type: string
                                    example: 'password123'
                                    description: The password of the user.
            responses:
                '200':
                    description: Successfully logged in
                    headers:
                        Set-Cookie:
                            description: >
                                The cookie containing the access token.
                                This cookie is used to authenticate the user in subsequent requests.
                            schema:
                                type: string
                                example: 'OvMeetAccessToken=token_123456; Path=/; HttpOnly; SameSite=Strict'
                        Set-Cookie-Refresh:
                            description: >
                                The cookie containing the refresh token.
                                This cookie is used to refresh the access token when it expires.
                            schema:
                                type: string
                                example: 'OvMeetRefreshToken=token_123456; Path=/meet/internal-api/v1/auth; HttpOnly; SameSite=Strict'
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    message:
                                        type: string
                                        example: 'Login succeeded'
                '404':
                    description: Invalid credentials
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                            example:
                                message: 'Login failed. Invalid username or password'
                '422':
                    description: Unprocessable Entity — The request body is invalid
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    error:
                                        type: string
                                        example: 'Unprocessable Entity'
                                    message:
                                        type: string
                                        example: 'Invalid request body'
                                    details:
                                        type: array
                                        items:
                                            type: object
                                            properties:
                                                field:
                                                    type: string
                                                    example: 'username'
                                                message:
                                                    type: string
                                                    example: 'Username must be at least 4 characters long'
                '500':
                    description: Internal server error
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                            example:
                                message: 'Internal server error'
    /auth/logout:
        post:
            operationId: logoutUser
            summary: Logout from OpenVidu Meet
            description: >
                Logs out the user and clears the access and refresh tokens from cookies.
            tags:
                - Internal API - Authentication
            responses:
                '200':
                    description: Successfully logged out
                    headers:
                        Set-Cookie:
                            schema:
                                type: string
                                example: 'OvMeetAccessToken=; Path=/; HttpOnly; SameSite=Strict'
                        Set-Cookie-Refresh:
                            schema:
                                type: string
                                example: 'OvMeetRefreshToken=; Path=/meet/internal-api/v1/auth; HttpOnly; SameSite=Strict'
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    message:
                                        type: string
                                        example: 'Logout successful'
    /auth/refresh:
        post:
            operationId: refreshAccessToken
            summary: Refresh the access token
            description: >
                Refreshes the access token using the refresh token.
                The new access token is returned in a cookie.
            tags:
                - Internal API - Authentication
            security:
                - refreshTokenCookie: []
            responses:
                '200':
                    description: Successfully refreshed the access token
                    headers:
                        Set-Cookie:
                            description: >
                                The cookie containing the new access token.
                                This cookie is used to authenticate the user in subsequent requests.
                            schema:
                                type: string
                                example: 'OvMeetAccessToken=token_123456; Path=/; HttpOnly; SameSite=Strict'
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    message:
                                        type: string
                                        example: 'Token refreshed'
                '400':
                    description: Bad Request — The refresh token is missing or invalid
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                            example:
                                message: 'No refresh token provided'
                '500':
                    description: Internal server error
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                            example:
                                message: 'Internal server error'
    /auth/profile:
        get:
            operationId: getUserProfile
            summary: Get user profile
            description: >
                Retrieves the profile information of the authenticated user.
            tags:
                - Internal API - Authentication
            security:
                - accessTokenCookie: []
            responses:
                '200':
                    description: Successfully retrieved user profile
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    username:
                                        type: string
                                        example: 'admin'
                                        description: The username of the authenticated user.
                                    role:
                                        type: string
                                        example: 'admin'
                                        description: The role assigned to the authenticated user.
                '401':
                    description: Unauthorized — The access token is missing or invalid
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                            example:
                                message: 'Unauthorized'
    /rooms/{roomId}/participant-role:
        get:
            operationId: getParticipantRole
            summary: Get participant role in a room
            description: >
                Retrieves the role that a participant will have in a specified OpenVidu Meet room when using the URL thant contains the secret token.
                This endpoint is useful for checking the participant's role before joining the room.
            tags:
                - Internal API - Rooms
            security:
                - accessTokenCookie: []
            parameters:
                - name: roomId
                  in: path
                  required: true
                  description: The name of the room to check the participant's role
                  schema:
                      type: string
                - name: secret
                  in: query
                  required: true
                  description: The secret token from the room URL to check the participant's role
                  schema:
                      type: string
            responses:
                '200':
                    description: Successfully retrieved participant role
                    content:
                        application/json:
                            schema:
                                type: string
                                example: 'moderator'
                                description: The role that the participant will have in the room.
                '404':
                    description: Room not found
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                            example:
                                name: 'Room Error'
                                message: 'The room does not exist'
                '422':
                    description: Unprocessable Entity — Invalid request query parameters
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    error:
                                        type: string
                                        example: 'Unprocessable Entity'
                                    message:
                                        type: string
                                        example: 'Invalid request query'
                                    details:
                                        type: array
                                        items:
                                            type: object
                                            properties:
                                                field:
                                                    type: string
                                                    example: 'secret'
                                                message:
                                                    type: string
                                                    example: 'secret is required'
                '500':
                    description: Internal server error
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                            example:
                                message: 'Internal server error'
    /recordings/{recordingId}/stream:
        get:
            operationId: getRecordingStream
            summary: Stream an OpenVidu Meet recording
            description: >
                Streams the OpenVidu Meet recording with the specified recording ID.
                This endpoint supports range requests, allowing partial content retrieval
                for video playback without downloading the entire file.
            tags:
                - Internal API - Recordings
            security:
                - accessTokenCookie: []
            parameters:
                - name: recordingId
                  in: path
                  required: true
                  description: The ID of the recording to stream
                  schema:
                      type: string
                - name: Range
                  in: header
                  required: false
                  description: >
                      Byte range for partial content retrieval.
                      Example: `bytes=0-1023` to request the first 1024 bytes of the file.
                  schema:
                      type: string
            responses:
                '200':
                    description: Successfully streaming the full recording
                    headers:
                        Accept-Ranges:
                            description: Indicates that byte-range requests are supported
                            schema:
                                type: string
                        Content-Length:
                            description: The total file size in bytes
                            schema:
                                type: integer
                    content:
                        video/mp4:
                            schema:
                                type: string
                                format: binary
                '206':
                    description: Partial content streaming based on byte range
                    headers:
                        Accept-Ranges:
                            description: Indicates that byte-range requests are supported
                            schema:
                                type: string
                        Content-Range:
                            description: Specifies the range of bytes being sent
                            schema:
                                type: string
                        Content-Length:
                            description: The length of the partial content in bytes
                            schema:
                                type: integer
                    content:
                        video/mp4:
                            schema:
                                type: string
                                format: binary
                '400':
                    description: Bad Request — Invalid range header format
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                            example:
                                code: 400
                                message: 'Invalid Range header'
                '401':
                    description: Unauthorized — The access token is missing or invalid
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                            example:
                                message: 'Unauthorized'
                '403':
                    description: Forbidden — The user authenticated with the access token does not have enough permissions
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                            example:
                                message: 'Insufficient permissions to access this resource'
                '404':
                    description: Recording not found
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                            example:
                                code: 404
                                message: 'Recording not found'
                '416':
                    description: Requested range not satisfiable
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                            example:
                                code: 416
                                message: 'Requested range not satisfiable'
                '500':
                    description: Internal server error
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                            example:
                                code: 500
                                message: 'Internal server error'
    /participants/token:
        post:
            operationId: generateParticipantToken
            summary: Generate a token for a participant
            description: >
                Generates a token for a participant to join an OpenVidu Meet room.
            tags:
                - Internal API - Participant
            security:
                - accessTokenCookie: []
            requestBody:
                description: Participant details
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/TokenOptions'
            responses:
                '200':
                    description: Successfully generated the participant token
                    headers:
                        Set-Cookie:
                            description: >
                                The cookie containing the participant token.
                                This cookie is used to authenticate the participant in the room.
                            schema:
                                type: string
                                example: 'OvMeetParticipantToken=token_123456; Path=/; HttpOnly; SameSite=Strict'
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    token:
                                        type: string
                                        example: 'token_123456'
                                        description: >
                                            The token to authenticate the participant.
                '401':
                    description: Unauthorized — The access token is missing or invalid when authentication is required
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                            example:
                                message: 'Unauthorized'
                '403':
                    description: Forbidden — The user authenticated with the access token does not have enough permissions when authentication is required
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                            example:
                                message: 'Insufficient permissions to access this resource'
                '404':
                    description: Room not found
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                            example:
                                name: 'Room Error'
                                message: 'The room does not exist'
                '409':
                    description: Conflict — The participant already exists in the room
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                            example:
                                name: 'Participant Error'
                                message: 'Participant already exists in the room'
                '500':
                    description: Internal server error
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                            example:
                                message: 'Internal server error'
    /participants/token/refresh:
        post:
            operationId: refreshParticipantToken
            summary: Refresh a token for a participant
            description: >
                Refresh a token for a participant in an OpenVidu Meet room.
            tags:
                - Internal API - Participant
            security:
                - accessTokenCookie: []
            requestBody:
                description: Participant details
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/TokenOptions'
            responses:
                '200':
                    description: Successfully refreshed the participant token
                    headers:
                        Set-Cookie:
                            description: >
                                The cookie containing the participant token.
                                This cookie is used to authenticate the participant in the room.
                            schema:
                                type: string
                                example: 'OvMeetParticipantToken=token_123456; Path=/; HttpOnly; SameSite=Strict'
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    token:
                                        type: string
                                        example: 'token_123456'
                                        description: >
                                            The token to authenticate the participant.
                '401':
                    description: Unauthorized — The access token is missing or invalid when authentication is required
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                            example:
                                message: 'Unauthorized'
                '403':
                    description: Forbidden — The user authenticated with the access token does not have enough permissions when authentication is required
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                            example:
                                message: 'Insufficient permissions to access this resource'
                '404':
                    description: Room or participant not found
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                            example:
                                name: 'Participant Error'
                                message: 'Participant not found in the room'
                '409':
                    description: Conflict — Current token is still valid
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                            example:
                                message: 'Participant token is still valid'
                '500':
                    description: Internal server error
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                            example:
                                message: 'Internal server error'
    /participants/{participantName}:
        delete:
            operationId: disconnectParticipant
            summary: Delete a participant from a room
            description: >
                Deletes a participant from an OpenVidu Meet room.
            tags:
                - Internal API - Participant
            security:
                - participantTokenCookie: []
            parameters:
                - name: participantName
                  in: path
                  required: true
                  description: The name of the participant to delete
                  schema:
                      type: string
                - name: roomId
                  in: query
                  required: true
                  description: The ID of the room where the participant is connected
                  schema:
                      type: string
            responses:
                '204':
                    description: Successfully disconnect the participant
                '401':
                    description: Unauthorized — The participant access token is missing or invalid
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                            example:
                                message: 'Unauthorized'
                '403':
                    description: Forbidden — The participant authenticated with the access token is not moderator of the room
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                            example:
                                message: 'Insufficient permissions to access this resource'
                '404':
                    description: Participant not found
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                            example:
                                code: 404
                                message: 'Participant not found'
                '500':
                    description: Internal server error
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                            example:
                                code: 500
                                message: 'Internal server error'

components:
    securitySchemes:
        accessTokenCookie:
            type: apiKey
            name: OvMeetAccessToken
            in: cookie
            description: >
                The JWT token to authenticate the request in case of consuming the API from the OpenVidu Meet frontend.
        refreshTokenCookie:
            type: apiKey
            name: OvMeetRefreshToken
            in: cookie
            description: >
                The JWT token to refresh the access token in case of consuming the API from the OpenVidu Meet frontend.
        participantTokenCookie:
            type: apiKey
            name: OvMeetParticipantToken
            in: cookie
            description: >
                The JWT token to authenticate the participant when entering the room.
    schemas:
        MeetRecordingBase:
            type: object
            properties:
                recordingId:
                    type: string
                    example: 'room-123--EG_XYZ--XX445'
                    description: The unique identifier of the recording.
                roomId:
                    type: string
                    example: 'room-123'
                    description: The ID of the room where the recording was made.
                # outputMode:
                #   type: string
                #   example: 'COMPOSED'
                #   description: >
                #     The output mode of the recording. Possible value: "COMPOSED".
                status:
                    type: string
                    example: 'ACTIVE'
                    description: >
                        The status of the recording.
                        Possible values:
                          - STARTING
                          - ACTIVE
                          - ENDING
                          - COMPLETE
                          - FAILED
                          - ABORTED
                          - LIMITED_REACHED
                filename:
                    type: string
                    example: 'room-123--XX445.mp4'
                    description: The name of the recording file.
                startDate:
                    type: number
                    example: 1620000000000
                    description: The date when the recording was started (milliseconds since the Unix epoch).

        MeetRecording:
            allOf:
                - $ref: '#/components/schemas/MeetRecordingBase'
                - type: object
                  properties:
                      endDate:
                          type: number
                          example: 1620000000000
                          description: The date when the recording was stopped (milliseconds since the Unix epoch).
                      duration:
                          type: number
                          example: 3600
                          description: The duration of the recording in seconds.
                      size:
                          type: number
                          example: 1024
                          description: The size of the recording file in bytes.
                      errorCode:
                          type: number
                          example: 100
                          description: The error code of the recording.
                      error:
                          type: string
                          description: The error message of the recording.
                          nullable: true
                      details:
                          type: string
                          example: 'Stopped using API'
                          description: Additional details about the recording.

        MeetRecordingStart:
            $ref: '#/components/schemas/MeetRecordingBase'

        TokenOptions:
            type: object
            required:
                - roomId
                - participantName
                - secret
            properties:
                roomId:
                    type: string
                    example: 'room-123'
                    description: >
                        The ID of the room where the participant will join.
                participantName:
                    type: string
                    example: 'Alice'
                    description: >
                        The name of the participant.
                secret:
                    type: string
                    example: 'abc123456'
                    description: >
                        The secret token from the room Url

        Error:
            type: object
            required:
                - message
            properties:
                name:
                    type: string
                message:
                    type: string