backend: refactor openapi doc for better maintainability

backend/nodemon.json

@@ -2,8 +2,8 @@
 	"env": {
 		"NODE_ENV": "development"
 	},
-	"watch": ["openapi/openvidu-meet-api.yaml", "openapi/openvidu-meet-internal-api.yaml", "src", "../typings/src"],
+	"watch": ["openapi/**/*.yaml", "src", "../typings/src"],
-	"ext": "js,json,ts",
+	"ext": "js,json,ts,yaml,yml",
 	"ignore": ["node_modules", "dist", "src/typings", "public"],
 	"exec": "node --experimental-specifier-resolution=node --loader ts-node/esm ./src/server.ts",
 	"events": {

backend/openapi/components/parameters/internal/participant-name.yaml

@@ -0,0 +1,6 @@
+name: participantName
+in: path
+required: true
+description: The name of the participant to delete
+schema:
+    type: string

backend/openapi/components/parameters/internal/secret.yaml

@@ -0,0 +1,6 @@
+name: secret
+in: query
+required: true
+description: The secret token from the room URL to check the participant's role
+schema:
+    type: string

backend/openapi/components/parameters/max-items.yaml

@@ -0,0 +1,8 @@
+name: maxItems
+in: query
+required: false
+description: The number of rooms per page (default is 10). Maximum is 100.
+schema:
+    type: integer
+    default: 10
+    maximum: 100

backend/openapi/components/parameters/next-page-token.yaml

@@ -0,0 +1,6 @@
+name: nextPageToken
+in: query
+required: false
+description: The token to retrieve the next page of rooms.
+schema:
+    type: string

backend/openapi/components/parameters/recording-id.yaml

@@ -0,0 +1,7 @@
+name: recordingId
+in: path
+required: true
+description: The unique identifier of the recording to delete.
+schema:
+    type: string
+    example: 'room-123--EG_XYZ--XX445'

backend/openapi/components/parameters/recording-range.yaml

@@ -0,0 +1,8 @@
+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

backend/openapi/components/parameters/room-id.yaml

@@ -0,0 +1,7 @@
+name: roomId
+in: path
+required: true
+description: The unique identifier of the room to retrieve
+schema:
+    type: string
+    example: 'room-123'

backend/openapi/components/requestBodies/create-room-request.yaml

@@ -0,0 +1,6 @@
+description: Room creation details
+required: true
+content:
+    application/json:
+        schema:
+            $ref: '../schemas/meet-room-options.yaml'

backend/openapi/components/requestBodies/internal/login-user.yaml

@@ -0,0 +1,15 @@
+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.

backend/openapi/components/requestBodies/internal/participant-token-request.yaml

@@ -0,0 +1,5 @@
+description: Participant details
+content:
+    application/json:
+        schema:
+            $ref: '../../schemas/internal/meet-token-options.yaml'

backend/openapi/components/requestBodies/start-recording-request.yaml

@@ -0,0 +1,13 @@
+description: Recording details
+content:
+    application/json:
+        schema:
+            type: object
+            required:
+                - roomId
+            properties:
+                roomId:
+                    type: string
+                    example: 'room-123'
+                    description: >
+                        The unique identifier of the room to record.

backend/openapi/components/requestBodies/update-room-request.yaml

@@ -0,0 +1,33 @@
+description: Room update details
+content:
+    application/json:
+        schema:
+            $ref: '../schemas/meet-room-preferences.yaml#/MeetRoomPreferences'
+        examples:
+            default:
+                summary: Standard preferences
+                value:
+                    chatPreferences:
+                        enabled: true
+                    recordingPreferences:
+                        enabled: true
+                    virtualBackgroundPreferences:
+                        enabled: true
+            withoutRecording:
+                summary: Room with recording disabled
+                value:
+                    chatPreferences:
+                        enabled: true
+                    recordingPreferences:
+                        enabled: false
+                    virtualBackgroundPreferences:
+                        enabled: true
+            withoutChat:
+                summary: Room with chat disabled
+                value:
+                    chatPreferences:
+                        enabled: false
+                    recordingPreferences:
+                        enabled: true
+                    virtualBackgroundPreferences:
+                        enabled: true

backend/openapi/components/responses/error-recording-already-started.yaml

@@ -0,0 +1,8 @@
+description: Conflict — The room is already being recorded
+content:
+    application/json:
+        schema:
+            $ref: '../schemas/error.yaml'
+        example:
+            name: 'Recording Error'
+            message: 'The room "room-123" is already being recorded'

backend/openapi/components/responses/error-recording-in-progress.yaml

@@ -0,0 +1,8 @@
+description: Conflict — The recording is in progress
+content:
+    application/json:
+        schema:
+            $ref: '../schemas/error.yaml'
+        example:
+            name: 'Recording Error'
+            message: 'Recording "room-123--EG_XYZ--XX445" is in progress'

backend/openapi/components/responses/error-recording-not-found.yaml

@@ -0,0 +1,8 @@
+description: Recording not found
+content:
+    application/json:
+        schema:
+            $ref: '../schemas/error.yaml'
+        example:
+            name: 'Recording Error'
+            message: 'Recording "room-123--EG_XYZ--XX445" not found'

backend/openapi/components/responses/error-room-not-found.yaml

@@ -0,0 +1,8 @@
+description: Room not found
+content:
+    application/json:
+        schema:
+            $ref: '../schemas/error.yaml'
+        example:
+            code: 404
+            message: 'Room not found'

backend/openapi/components/responses/forbidden-error.yaml

@@ -0,0 +1,7 @@
+description: Forbidden — Insufficient permissions
+content:
+    application/json:
+        schema:
+            $ref: '../schemas/error.yaml'
+        example:
+            message: 'Insufficient permissions to access this resource'

backend/openapi/components/responses/internal-server-error.yaml

@@ -0,0 +1,7 @@
+description: Internal server error
+content:
+    application/json:
+        schema:
+            $ref: '../schemas/error.yaml'
+        example:
+            message: 'Internal server error'

backend/openapi/components/responses/internal/error-invalid-credentials.yaml

@@ -0,0 +1,7 @@
+description: Invalid credentials
+content:
+    application/json:
+        schema:
+            $ref: ../../schemas/error.yaml
+        example:
+            message: 'Login failed. Invalid username or password'

backend/openapi/components/responses/internal/error-invalid-refresh-token.yaml

@@ -0,0 +1,7 @@
+description: Bad Request — The refresh token is missing or invalid
+content:
+    application/json:
+        schema:
+            $ref: ../../schemas/error.yaml
+        example:
+            message: 'No refresh token provided'

backend/openapi/components/responses/internal/success-refresh-token.yaml

@@ -0,0 +1,17 @@
+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'

backend/openapi/components/responses/internal/success-user-login.yaml

@@ -0,0 +1,24 @@
+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'

backend/openapi/components/responses/internal/success-user-logout.yaml

@@ -0,0 +1,18 @@
+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'

backend/openapi/components/responses/success-bulk-delete-recordings.yaml

@@ -0,0 +1,58 @@
+description: Bulk deletion completed. Includes lists of successfully deleted IDs and errors.
+content:
+    application/json:
+        schema:
+            type: object
+            properties:
+                deleted:
+                    type: array
+                    items:
+                        type: string
+                    description: List of successfully deleted recording IDs.
+                    example:
+                        - 'room-123--EG_XYZ--XX445'
+                        - 'room-123--EG_XYZ--XX446'
+                notDeleted:
+                    type: array
+                    description: List of recordings that could not be deleted along with the corresponding error messages.
+                    items:
+                        type: object
+                        properties:
+                            recordingId:
+                                type: string
+                                description: The unique identifier of the recording that was not deleted.
+                                example: 'room-123--EG_XYZ--XX447'
+                            error:
+                                type: string
+                                description: A message explaining why the deletion failed.
+                                example: 'Recording not found'
+        examples:
+            successful_deletion:
+                summary: All recordings were successfully deleted
+                value:
+                    deleted:
+                        - 'room-123--EG_XYZ--XX445'
+                        - 'room-123--EG_XYZ--XX446'
+                    notDeleted: []
+
+            partial_deletion_with_errors:
+                summary: Some recordings were deleted successfully, others failed
+                value:
+                    deleted:
+                        - 'room-123--EG_XYZ--XX445'
+                        - 'room-123--EG_XYZ--XX446'
+                    notDeleted:
+                        - recordingId: 'room-123--EG_XYZ--XX447'
+                          error: 'Recording not found'
+                        - recordingId: 'room-123--EG_XYZ--XX448'
+                          error: 'Access denied for deletion'
+
+            no_deletion_performed:
+                summary: No recordings were deleted
+                value:
+                    deleted: []
+                    notDeleted:
+                        - recordingId: 'room-123--EG_XYZ--XX445'
+                          error: 'Recording not found'
+                        - recordingId: 'room-123--EG_XYZ--XX446'
+                          error: 'Recording not found'

backend/openapi/components/responses/success-create-room.yaml

@@ -0,0 +1,5 @@
+description: Success room response
+content:
+    application/json:
+        schema:
+            $ref: '../schemas/meet-room.yaml'

backend/openapi/components/responses/success-get-recording.yaml

@@ -0,0 +1,27 @@
+description: Successfully retrieved the recording.
+content:
+    application/json:
+        schema:
+            $ref: '../schemas/meet-recording.yaml'
+        examples:
+            completed_recording:
+                summary: Completed recording
+                value:
+                    recordingId: 'room-123--EG_XYZ--XX445'
+                    roomId: 'room-123'
+                    status: 'COMPLETE'
+                    filename: 'room-123--XX445.mp4'
+                    startDate: 1600000000000
+                    endDate: 1600000003600
+                    duration: 3.6
+                    size: 1443846
+                    details: 'End reason: StopEgress API'
+
+            active_recording:
+                summary: Recording in progress
+                value:
+                    recordingId: 'room-456--EG_ABC--QR789'
+                    roomId: 'room-456'
+                    status: 'ACTIVE'
+                    filename: 'room-456--QR789.mp4'
+                    startDate: 1682500000000

backend/openapi/components/responses/success-get-recordings.yaml

@@ -0,0 +1,52 @@
+description: Successfully retrieved the recording list
+content:
+    application/json:
+        schema:
+            type: object
+            properties:
+                recordings:
+                    type: array
+                    items:
+                        $ref: '../schemas/meet-recording.yaml'
+                pagination:
+                    $ref: '../schemas/meet-pagination.yaml'
+        examples:
+            successful_recording_retrieval:
+                summary: Successfully retrieved a list of recordings
+                value:
+                    recordings:
+                        - recordingId: 'room-123--EG_XYZ--XX445'
+                          roomId: 'room-123'
+                          status: 'ACTIVE'
+                          filename: 'room-123--XX445.mp4'
+                          startDate: 1620000000000
+                          endDate: 1620000003600
+                          duration: 3.6
+                          size: 1024
+                          details: 'Stopped using API'
+                    pagination:
+                        isTruncated: false
+
+            paginated_recording_list:
+                summary: A paginated response indicating more recordings are available
+                value:
+                    recordings:
+                        - recordingId: 'room-456--EG_XYZ--XX678'
+                          roomId: 'room-456'
+                          status: 'COMPLETE'
+                          filename: 'room-456--XX678.mp4'
+                          startDate: 1625000000000
+                          endDate: 1625000007200
+                          duration: 7.2
+                          size: 2048
+                          details: 'Recording completed successfully'
+                    pagination:
+                        isTruncated: true
+                        nextPageToken: 'NEXT_PAGE_ABC123'
+
+            no_recordings_found:
+                summary: No recordings found for the given query
+                value:
+                    recordings: []
+                    pagination:
+                        isTruncated: false

backend/openapi/components/responses/success-get-rooms.yaml

@@ -0,0 +1,19 @@
+description: Successfully retrieved the list of OpenVidu Meet rooms
+content:
+    application/json:
+        schema:
+            type: object
+            properties:
+                rooms:
+                    type: array
+                    items:
+                        $ref: '../schemas/meet-room.yaml'
+                pagination:
+                    type: object
+                    properties:
+                        isTruncated:
+                            type: boolean
+                            description: Indicates if there are more rooms to retrieve.
+                        nextPageToken:
+                            type: string
+                            description: The token to retrieve the next page of rooms.

backend/openapi/components/responses/success-start-recording.yaml

@@ -0,0 +1,11 @@
+description: Successfully created the OpenVidu Meet recording
+content:
+    application/json:
+        schema:
+            $ref: '../schemas/meet-recording.yaml'
+        example:
+            recordingId: 'room-123--EG_XYZ--XX445'
+            roomId: 'room-123'
+            status: 'STARTING'
+            filename: 'room-123--EG_XYZ--XX445'
+            startDate: 1600000000000

backend/openapi/components/responses/success-stop-recording.yaml

@@ -0,0 +1,19 @@
+description: Accepted — The stop request has been accepted. The endpoint to retrieve the recording is provided in the Location header.
+headers:
+    Location:
+        description: The URL to retrieve the recording details
+        schema:
+            type: string
+            example: 'https://openvidu.example.com/meet/api/v1/recordings/room-123--EG_XYZ--XX445'
+content:
+    application/json:
+        schema:
+            $ref: '../schemas/meet-recording.yaml'
+        example:
+            recordingId: 'room-123--EG_XYZ--XX445'
+            roomId: 'room-123'
+            status: 'ENDING'
+            filename: 'room-123--EG_XYZ--XX445'
+            startDate: 1600000000000
+            duration: 3.6
+            details: 'End reason: StopEgress API'

backend/openapi/components/responses/unauthorized-error.yaml

@@ -0,0 +1,7 @@
+description: Unauthorized — Invalid API key or access token
+content:
+    application/json:
+        schema:
+            $ref: '../schemas/error.yaml'
+        example:
+            message: 'Unauthorized'

backend/openapi/components/responses/validation-error.yaml

@@ -0,0 +1,5 @@
+description: Unprocessable Entity — Invalid request body
+content:
+    application/json:
+        schema:
+            $ref: '../schemas/validation-error.yaml'

backend/openapi/components/schemas/error.yaml

@@ -0,0 +1,11 @@
+type: object
+required:
+    - message
+properties:
+    name:
+        type: string
+    message:
+        type: string
+    code:
+        type: integer
+description: HTTP status code associated with the error

backend/openapi/components/schemas/internal/meet-token-options.yaml

@@ -0,0 +1,21 @@
+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

backend/openapi/components/schemas/meet-pagination.yaml

@@ -0,0 +1,10 @@
+type: object
+properties:
+    isTruncated:
+        type: boolean
+        description: >
+            Indicates if there are more recordings to retrieve.
+            If true, use the `nextPageToken` to fetch the next set of recordings.
+    nextPageToken:
+        type: [string, 'null']
+        description: The token to retrieve the next page of recordings.

backend/openapi/components/schemas/meet-recording.yaml

@@ -0,0 +1,54 @@
+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
+        enum: ['STARTING', 'ACTIVE', 'ENDING', 'COMPLETE', 'FAILED', 'ABORTED', 'LIMITED_REACHED']
+        example: 'ACTIVE'
+        description: >
+            The status of the recording.
+    filename:
+        type: string
+        example: 'room-123--XX445.mp4'
+        description: >
+            The URL for the publisher to join the room. The publisher has permissions to publish audio and
+            video streams to the room.
+    startDate:
+        type: [number, 'null']
+        example: 1620000000000
+        description: The date when the recording started (milliseconds since the Unix epoch).
+    endDate:
+        type: [number, 'null']
+        example: 1620000003600
+        description: The date when the recording was stopped (milliseconds since the Unix epoch).
+    duration:
+        type: [number, 'null']
+        example: 3.6
+        description: The duration of the recording in seconds.
+    size:
+        type: [number, 'null']
+        example: 1024
+        description: The size of the recording file in bytes.
+    errorCode:
+        type: [number, 'null']
+        example: 100
+        description: The error code of the recording.
+    error:
+        type: [string, 'null']
+        description: The error message of the recording.
+    details:
+        type: [string, 'null']
+        example: 'Stopped using API'
+        description: Additional details about the recording.

backend/openapi/components/schemas/meet-room-options.yaml

@@ -0,0 +1,25 @@
+type: object
+required:
+    - expirationDate
+properties:
+    expirationDate:
+        type: number
+        example: 1620000000000
+        description: >
+            The expiration date of the room in milliseconds since the Unix epoch.
+            After this date, the room will be closed and no new participants will be allowed to join.
+    roomIdPrefix:
+        type: string
+        example: 'room'
+        description: >
+            A prefix to be used for the room ID. The room ID will be generated by concatenating this prefix with a unique identifier.
+    # maxParticipants:
+    #     type: integer
+    #     example: 10
+    #     description: >
+    #         The maximum number of participants allowed in the room. If the number of participants exceeds
+    #         this limit, new participants will not be allowed to join.
+    preferences:
+        $ref: './meet-room-preferences.yaml#/MeetRoomPreferences'
+        description: >
+            The preferences for the room. These preferences wil

backend/openapi/components/schemas/meet-room-preferences.yaml

@@ -0,0 +1,45 @@
+MeetRoomPreferences:
+    type: object
+    properties:
+        chatPreferences:
+            $ref: '#/MeetChatPreferences'
+            description: >
+                Preferences for the chat feature in the room.
+
+        recordingPreferences:
+            $ref: '#/MeetRecordingPreferences'
+            description: >
+                Preferences for recording the room.
+
+        virtualBackgroundPreferences:
+            $ref: '#/MeetVirtualBackgroundPreferences'
+            description: >
+                Preferences for virtual background in the room.
+
+MeetChatPreferences:
+    type: object
+    properties:
+        enabled:
+            type: boolean
+            default: true
+            example: true
+            description: >
+                If true, the room will be allowed to send and receive chat messages.
+MeetRecordingPreferences:
+    type: object
+    properties:
+        enabled:
+            type: boolean
+            default: true
+            example: true
+            description: >
+                If true, the room will be allowed to record the video of the participants.
+MeetVirtualBackgroundPreferences:
+    type: object
+    properties:
+        enabled:
+            type: boolean
+            default: true
+            example: true
+            description: >
+                If true, the room will be allowed to use virtual background.

backend/openapi/components/schemas/meet-room.yaml

@@ -0,0 +1,45 @@
+type: object
+properties:
+    roomId:
+        type: string
+        example: 'room-123'
+        description: >
+            The unique identifier of the room. This ID is generated when the room is created.
+    roomIdPrefix:
+        type: string
+        example: 'room'
+        description: >
+            The prefix used for the room ID. This prefix is used to generate the room ID.
+    creationDate:
+        type: number
+        example: 1620000000000
+        description: >
+            The creation date of the room in milliseconds since the Unix epoch.
+    expirationDate:
+        type: number
+        example: 1620000800000
+        description: >
+            The expiration date of the room in milliseconds since the Unix epoch.
+            After this date, the room will be closed and no new participants will be allowed to join.
+    preferences:
+        $ref: meet-room-preferences.yaml#/MeetRoomPreferences
+        description: >
+            The preferences for the room.
+    # maxParticipants:
+    #     type: integer
+    #     example: 10
+    #     description: >
+    #         The maximum number of participants allowed in the room. If the number of participants exceeds
+    #         this limit, new participants will not be allowed to join.
+    moderatorURL:
+        type: string
+        example: 'http://localhost:6080/room/room-123/?secret=tok_123456'
+        description: >
+            The URL for the moderator to join the room. The moderator has special permissions to manage the
+            room and participants.
+    publisherURL:
+        type: string
+        example: 'http://localhost:6080/room/room-123/?secret=tok_123456'
+        description: >
+            The URL for the publisher to join the room. The publisher has permissions to publish audio and
+            video streams to the room.

backend/openapi/components/schemas/meet-webhook.yaml

@@ -0,0 +1,39 @@
+MeetWebhookEvent:
+    type: object
+    properties:
+        creationDate:
+            type: number
+            description: 'The timestamp when the webhook event was created.'
+        event:
+            $ref: '#/MeetWebhookEventType'
+            description: 'The type of event.'
+        data:
+            oneOf:
+                - allOf:
+                      - title: Recording Event Data
+                      - description: 'Data for recording-related events (started, updated, ended)'
+                      - $ref: './meet-recording.yaml'
+                # - allOf:
+                #       - title: Room Event Data
+                #       - description: 'Data for room-related events (created, updated, deleted)'
+                #       - $ref: './meet-room.yaml'
+            discriminator:
+                propertyName: eventType
+                mapping:
+                    recordingStarted: './meet-recording.yaml'
+                    recordingUpdated: './meet-recording.yaml'
+                    recordingEnded: './meet-recording.yaml'
+                    # roomCreated: './meet-room.yaml'
+                    # roomUpdated: './meet-room.yaml'
+                    # roomDeleted: './meet-room.yaml'
+            description: 'The event payload data, determined by the event type.'
+
+MeetWebhookEventType:
+    type: string
+    enum:
+        - recordingStarted
+        - recordingUpdated
+        - recordingEnded
+        # - roomCreated
+        # - roomUpdated
+        # - roomDeleted

backend/openapi/components/schemas/validation-error.yaml

@@ -0,0 +1,19 @@
+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: 'expirationDate'
+                message:
+                    type: string
+                    example: 'Expected number, received string'

backend/openapi/components/security.yaml

@@ -0,0 +1,18 @@
+apiKeyInHeader:
+    type: apiKey
+    name: X-API-KEY
+    in: header
+    description: >
+        The API key to authenticate the request. This key is required to access the OpenVidu Meet API.
+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.
+participantTokenCookie:
+    type: apiKey
+    name: OvMeetParticipantToken
+    in: cookie
+    description: >
+        The JWT token to authenticate the participant when entering the room.

backend/openapi/info/info.yaml

@@ -0,0 +1,14 @@
+title: OpenVidu Meet REST API
+description: >
+    The OpenVidu Meet REST API provides a comprehensive set of endpoints for integrating real-time video
+    conferencing capabilities into your applications.
+contact:
+    name: OpenVidu
+    email: commercial@openvidu.io
+    url: https://openvidu.io/support/
+license:
+    name: Apache License 2.0
+    identifier: Apache-2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0
+version: v1
+termsOfService: https://openvidu.io/conditions/terms-of-service/

backend/openapi/openvidu-meet-internal-api.yaml

@@ -1,580 +1,31 @@
 openapi: 3.1.0
 info:
-    title: OpenVidu Meet REST API
+    $ref: './info/info.yaml'
-    description: >
-        The OpenVidu Meet REST API provides a comprehensive set of endpoints for integrating real-time video
-        conferencing capabilities into your applications.
-    contact:
-        name: OpenVidu
-        email: commercial@openvidu.io
-        url: https://openvidu.io/support/
-    license:
-        name: Apache License 2.0
-        identifier: Apache-2.0
-        url: https://www.apache.org/licenses/LICENSE-2.0
-    version: v1
-    termsOfService: https://openvidu.io/conditions/terms-of-service/
-
 servers:
     - url: /meet/internal-api/v1
       description: OpenVidu Meet Internal API
 tags:
-    - name: Internal API - Authentication
+    $ref: './tags/tags.yaml'
-      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:
+        $ref: './paths/internal/auth.yaml#/~1auth~1login'
-            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:
+        $ref: './paths/internal/auth.yaml#/~1auth~1logout'
-            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:
+        $ref: './paths/internal/auth.yaml#/~1auth~1refresh'
-            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:
+        $ref: './paths/internal/auth.yaml#/~1auth~1profile'
-            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:
+        $ref: './paths/internal/rooms.yaml#/~1rooms~1{roomId}~1participant-role'
-            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:
+        $ref: './paths/internal/recordings.yaml#/~1recordings~1{recordingId}~1stream'
-            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:
+        $ref: './paths/internal/participants.yaml#/~1participants~1token'
-            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:
+        $ref: './paths/internal/participants.yaml#/~1participants~1token~1refresh'
-            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}:
+        $ref: './paths/internal/participants.yaml#/~1participants~1{participantName}'
         delete:
             operationId: disconnectParticipant
             summary: Delete a participant from a room
@@ -637,124 +88,17 @@ paths:
 
 components:
     securitySchemes:
-        accessTokenCookie:
+        $ref: './components/security.yaml'
-            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:
+        MeetRoom:
-            type: object
+            $ref: components/schemas/meet-room.yaml
-            properties:
+        MeetRoomOptions:
-                recordingId:
+            $ref: components/schemas/meet-room-options.yaml
-                    type: string
+        MeetRoomPreferences:
-                    example: 'room-123--EG_XYZ--XX445'
+            $ref: './components/schemas/meet-room-preferences.yaml#/MeetRoomPreferences'
-                    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/meet-recording.yaml
-                - $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, 'null']
-                          description: The error message of the recording.
-                      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
+            $ref: components/schemas/error.yaml
-            required:
+        MeetWebhookEvent:
-                - message
+            $ref: components/schemas/meet-webhook.yaml#/MeetWebhookEvent
-            properties:
-                name:
-                    type: string
-                message:
-                    type: string

backend/openapi/paths/internal/auth.yaml

@@ -0,0 +1,78 @@
+/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:
+            $ref: '../../components/requestBodies/internal/login-user.yaml'
+        responses:
+            '200':
+                $ref: '../../components/responses/internal/success-user-login.yaml'
+            # Should be 401
+            '404':
+                $ref: '../../components/responses/internal/error-invalid-credentials.yaml'
+            '422':
+                $ref: '../../components/responses/validation-error.yaml'
+            '500':
+                $ref: '../../components/responses/internal-server-error.yaml'
+/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':
+                $ref: '../../components/responses/internal/success-user-logout.yaml'
+
+/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':
+                $ref: '../../components/responses/internal/success-refresh-token.yaml'
+            '400':
+                $ref: '../../components/responses/internal/error-invalid-refresh-token.yaml'
+            '500':
+                $ref: '../../components/responses/internal-server-error.yaml'
+/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':
+                $ref: '../../components/responses/internal/error-invalid-refresh-token.yaml'

backend/openapi/paths/internal/participants.yaml

@@ -0,0 +1,125 @@
+/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:
+            $ref: '../../components/requestBodies/internal/participant-token-request.yaml'
+        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':
+                $ref: '../../components/responses/unauthorized-error.yaml'
+            '403':
+                $ref: '../../components/responses/forbidden-error.yaml'
+
+            '404':
+                $ref: '../../components/responses/error-room-not-found.yaml'
+            '409':
+                description: Conflict — The participant already exists in the room
+                content:
+                    application/json:
+                        schema:
+                            $ref: '../../components/schemas/error.yaml'
+                        example:
+                            name: 'Participant Error'
+                            message: 'Participant already exists in the room'
+            '500':
+                $ref: '../../components/responses/internal-server-error.yaml'
+
+/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:
+            $ref: '../../components/requestBodies/internal/participant-token-request.yaml'
+        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':
+                $ref: '../../components/responses/unauthorized-error.yaml'
+            '403':
+                $ref: '../../components/responses/forbidden-error.yaml'
+            '404':
+                $ref: '../../components/responses/error-room-not-found.yaml'
+            '409':
+                description: Conflict — Current token is still valid
+                content:
+                    application/json:
+                        schema:
+                            $ref: '../../components/schemas/error.yaml'
+                        example:
+                            message: 'Participant token is still valid'
+            '500':
+                $ref: '../../components/responses/internal-server-error.yaml'
+/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:
+            - $ref: '../../components/parameters/internal/participant-name.yaml'
+            - $ref: '../../components/parameters/room-id.yaml'
+        responses:
+            '204':
+                description: Successfully disconnect the participant
+            '401':
+                $ref: '../../components/responses/unauthorized-error.yaml'
+            '403':
+                $ref: '../../components/responses/forbidden-error.yaml'
+            '404':
+                $ref: '../../components/responses/error-room-not-found.yaml'
+            '500':
+                $ref: '../../components/responses/internal-server-error.yaml'

backend/openapi/paths/internal/recordings.yaml

@@ -0,0 +1,78 @@
+/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:
+            - $ref: '../../components/parameters/recording-id.yaml'
+            - $ref: '../../components/parameters/recording-range.yaml'
+        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.yaml'
+                        example:
+                            code: 400
+                            message: 'Invalid Range header'
+            '401':
+                $ref: '../../components/responses/unauthorized-error.yaml'
+            '403':
+                $ref: '../../components/responses/forbidden-error.yaml'
+            '404':
+                $ref: '../../components/responses/error-room-not-found.yaml'
+            '416':
+                description: Requested range not satisfiable
+                content:
+                    application/json:
+                        schema:
+                            $ref: '../../components/schemas/error.yaml'
+                        example:
+                            code: 416
+                            message: 'Requested range not satisfiable'
+            '500':
+                $ref: '../../components/responses/internal-server-error.yaml'

backend/openapi/paths/internal/rooms.yaml

@@ -0,0 +1,29 @@
+/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:
+            - $ref: '../../components/parameters/room-id.yaml'
+            - $ref: '../../components/parameters/internal/secret.yaml'
+        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':
+                $ref: '../../components/responses/error-room-not-found.yaml'
+            '422':
+                $ref: '../../components/responses/validation-error.yaml'
+            '500':
+                $ref: '../../components/responses/internal-server-error.yaml'

backend/openapi/paths/recordings.yaml

@@ -0,0 +1,180 @@
+/recordings:
+    post:
+        operationId: createRecording
+        summary: Start a recording
+        description: >
+            Start a new recording for an OpenVidu Meet room with the specified room ID.
+        tags:
+            - OpenVidu Meet - Recordings
+        security:
+            - participantTokenCookie: []
+        requestBody:
+            $ref: '../components/requestBodies/start-recording-request.yaml'
+        responses:
+            '200':
+                $ref: '../components/responses/success-start-recording.yaml'
+            '401':
+                $ref: '../components/responses/unauthorized-error.yaml'
+            '403':
+                $ref: '../components/responses/forbidden-error.yaml'
+            '404':
+                $ref: '../components/responses/error-room-not-found.yaml'
+            '409':
+                $ref: '../components/responses/error-recording-already-started.yaml'
+            '422':
+                $ref: '../components/responses/validation-error.yaml'
+            '500':
+                $ref: '../components/responses/internal-server-error.yaml'
+    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.
+        tags:
+            - OpenVidu Meet - Recordings
+        security:
+            - apiKeyInHeader: []
+            - accessTokenCookie: []
+        parameters:
+            # - name: status
+            #   in: query
+            #   required: false
+            #   description: |
+            #       Filter recordings by their status.
+
+            #       Possible values:
+            #       - `STARTING`
+            #       - `ACTIVE`
+            #       - `ENDING`
+            #       - `COMPLETE`
+            #       - `FAILED`
+            #       - `ABORTED`
+            #       - `LIMITED_REACHED`
+
+            #       You can provide multiple statuses as a comma-separated list (e.g., `status=ACTIVE,FAILED`).
+            #       If not specified, recordings with any status will be returned.
+
+            #       > ⚠️ **Note:** Using this filter may impact performance for large datasets.
+            #   schema:
+            #       type: string
+            - $ref: '../components/parameters/room-id.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'
+            '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.
+        tags:
+            - OpenVidu Meet - Recordings
+        security:
+            - apiKeyInHeader: []
+            - accessTokenCookie: []
+        parameters:
+            - name: recordingIds
+              in: query
+              required: true
+              description: |
+                  The unique IDs of the recordings to delete.
+                  You can provide multiple recording IDs as a comma-separated list (e.g., `recordingIds=room-123--EG_XYZ--XX445,room-123--EG_XYZ--XX446`).
+              schema:
+                  type: string
+        responses:
+            '200':
+                $ref: '../components/responses/success-bulk-delete-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'
+
+/recordings/{recordingId}:
+    put:
+        operationId: stopRecording
+        summary: Stop a recording
+        description: >
+            Stops a recording with the specified recording ID.
+            The recording must be in an `ACTIVE` state; otherwise, a 409 error is returned.
+        tags:
+            - OpenVidu Meet - Recordings
+        security:
+            - participantTokenCookie: []
+        parameters:
+            - $ref: '../components/parameters/recording-id.yaml'
+        responses:
+            '200':
+                $ref: '../components/responses/success-stop-recording.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'
+            '500':
+                $ref: '../components/responses/internal-server-error.yaml'
+
+    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: []
+        parameters:
+            - $ref: '../components/parameters/recording-id.yaml'
+        responses:
+            '200':
+                $ref: '../components/responses/success-get-recording.yaml'
+            '401':
+                $ref: '../components/responses/unauthorized-error.yaml'
+            '403':
+                $ref: '../components/responses/forbidden-error.yaml'
+            '404':
+                $ref: '../components/responses/error-recording-not-found.yaml'
+            '500':
+                $ref: '../components/responses/internal-server-error.yaml'
+    delete:
+        operationId: deleteRecording
+        summary: Delete a recording
+        description: >
+            Deletes a recording with the specified recording.
+            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: []
+        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'
+            '500':
+                $ref: '../components/responses/internal-server-error.yaml'

backend/openapi/paths/rooms.yaml

@@ -0,0 +1,132 @@
+/rooms:
+    post:
+        operationId: createRoom
+        summary: Create a room
+        description: >
+            Creates a new OpenVidu Meet room with the specified expiration date.
+            The room will be available for participants to join using the generated URLs.
+        tags:
+            - OpenVidu Meet - Room
+        security:
+            - apiKeyInHeader: []
+            - accessTokenCookie: []
+        requestBody:
+            $ref: '../components/requestBodies/create-room-request.yaml'
+        responses:
+            '200':
+                $ref: '../components/responses/success-create-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'
+
+    get:
+        operationId: getRooms
+        summary: Get all rooms
+        description: >
+            Retrieves a paginated list of all rooms available in the system.
+        tags:
+            - OpenVidu Meet - Room
+        security:
+            - apiKeyInHeader: []
+            - accessTokenCookie: []
+        parameters:
+            - $ref: '../components/parameters/max-items.yaml'
+            - $ref: '../components/parameters/next-page-token.yaml'
+        responses:
+            '200':
+                $ref: '../components/responses/success-get-rooms.yaml'
+            '401':
+                $ref: '../components/responses/unauthorized-error.yaml'
+            '403':
+                $ref: '../components/responses/forbidden-error.yaml'
+            '500':
+                $ref: '../components/responses/internal-server-error.yaml'
+/rooms/{roomId}:
+    get:
+        operationId: getRoom
+        summary: Get a room
+        description: >
+            Retrieves the details of an OpenVidu Meet room with the specified room ID.
+        tags:
+            - OpenVidu Meet - Room
+        security:
+            - apiKeyInHeader: []
+            - accessTokenCookie: []
+            - participantTokenCookie: []
+        parameters:
+            - $ref: '../components/parameters/room-id.yaml'
+        responses:
+            '200':
+                $ref: '../components/responses/success-create-room.yaml'
+            '401':
+                $ref: '../components/responses/unauthorized-error.yaml'
+            '403':
+                $ref: '../components/responses/forbidden-error.yaml'
+            '404':
+                $ref: '../components/responses/error-room-not-found.yaml'
+            '500':
+                $ref: '../components/responses/internal-server-error.yaml'
+    put:
+        operationId: updateRoom
+        summary: Update a room
+        description: >
+            Updates the preferences of an OpenVidu Meet room with the specified room ID.
+        tags:
+            - OpenVidu Meet - Room
+        security:
+            - apiKeyInHeader: []
+            - accessTokenCookie: []
+        parameters:
+            - name: roomId
+              in: path
+              required: true
+              description: The unique identifier of the room to update
+              schema:
+                  type: string
+                  example: 'room-123'
+        requestBody:
+            $ref: '../components/requestBodies/update-room-request.yaml'
+        responses:
+            '200':
+                $ref: '../components/responses/success-create-room.yaml'
+            '401':
+                $ref: '../components/responses/unauthorized-error.yaml'
+            '403':
+                $ref: '../components/responses/forbidden-error.yaml'
+            '404':
+                $ref: '../components/responses/error-room-not-found.yaml'
+            '422':
+                $ref: '../components/responses/validation-error.yaml'
+            '500':
+                $ref: '../components/responses/internal-server-error.yaml'
+
+    delete:
+        operationId: deleteRoom
+        summary: Delete a room
+        description: >
+            Deletes an OpenVidu Meet room with the specified room ID.
+            The room with participants will be closed and all participants will be disconnected.
+            The room will be deleted from the system and will no longer be available.
+        tags:
+            - OpenVidu Meet - Room
+        security:
+            - apiKeyInHeader: []
+            - accessTokenCookie: []
+        parameters:
+            - $ref: '../components/parameters/room-id.yaml'
+        responses:
+            '204':
+                description: Successfully deleted the OpenVidu Meet room
+            '401':
+                $ref: '../components/responses/unauthorized-error.yaml'
+            '403':
+                $ref: '../components/responses/forbidden-error.yaml'
+            '404':
+                $ref: '../components/responses/error-room-not-found.yaml'
+            '500':
+                $ref: '../components/responses/internal-server-error.yaml'

backend/openapi/tags/tags.yaml

@@ -0,0 +1,12 @@
+- name: OpenVidu Meet - Room
+  description: Operations related to managing OpenVidu Meet rooms
+- name: OpenVidu Meet - Recordings
+  description: Operations related to managing OpenVidu Meet recordings
+- 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

backend/openapi/webhooks/webhooks.yaml

@@ -0,0 +1,161 @@
+recordingStarted:
+    post:
+        summary: Recording started
+        description: >
+            This webhook is triggered when a recording starts.
+            The API provider will send a POST request to this endpoint with the recording details.
+            The JSON payload includes information such as the recording identifier, room, and its status.
+        operationId: recordingStartedWebhook
+        parameters:
+            - name: X-Timestamp
+              in: header
+              description: Timestamp of the webhook event (in Unix Epoch seconds)
+              example: 1678901234
+              schema:
+                  type: string
+            - name: X-Signature
+              in: header
+              description: HMAC signature for webhook verification
+              example: 1234567890abcdef
+              schema:
+                  type: string
+        requestBody:
+            required: true
+            content:
+                application/json:
+                    schema:
+                        # $ref: '#/components/schemas/RecordingStartedWebhook'
+                        properties:
+                            creationDate:
+                                type: number
+                                description: The date when the event was created (milliseconds since the Unix epoch).
+                                example: 1620000000000
+                            event:
+                                type: string
+                                description: Event type identifier.
+                                example: recordingStarted
+                            data:
+                                type: object
+                                properties:
+                                    recordingId:
+                                        type: string
+                                        description: The unique identifier of the recording that started.
+                                        example: room-123--EG_XYZ--XX445
+                                    roomId:
+                                        type: string
+                                        description: The unique identifier of the room for which the recording started.
+                                        example: room-123
+                                    status:
+                                        type: string
+                                        description: The status of the recording.
+                                        example: STARTING
+        responses:
+            '200':
+                description: Webhook received successfully
+#     recordingUpdated:
+#         post:
+#             summary: Recording updated
+#             description: >
+#                 This webhook is triggered when a recording update occurs.
+#                 The API provider sends a POST request with the updated details of the recording.
+#             operationId: recordingUpdatedWebhook
+#             parameters:
+#                 - name: X-Timestamp
+#                   in: header
+#                   description: Timestamp of the webhook event (in Unix Epoch seconds)
+#                   example: 1678901234
+#                   schema:
+#                       type: string
+#                 - name: X-Signature
+#                   in: header
+#                   description: HMAC signature for webhook verification
+#                   example: 1234567890abcdef
+#                   schema:
+#                       type: string
+#             requestBody:
+#                 required: true
+#                 content:
+#                     application/json:
+#                         schema:
+#                             type: object
+#                             properties:
+#                                 creationDate:
+#                                     type: number
+#                                     description: The date when the event was created (milliseconds since the Unix epoch).
+#                                     example: 1620000000000
+#                                 event:
+#                                     type: string
+#                                     description: Event type identifier.
+#                                     example: recordingUpdated
+#                                 data:
+#                                     type: object
+#                                     properties:
+#                                         recordingId:
+#                                             type: string
+#                                             description: The unique identifier of the recording being updated.
+#                                             example: room-123--EG_XYZ--XX445
+#                                         roomId:
+#                                             type: string
+#                                             description: The unique identifier of the room for which the recording is updated.
+#                                             example: room-123
+#                                         status:
+#                                             type: string
+#                                             description: The updated status of the recording.
+#                                             example: ACTIVE
+#             responses:
+#                 '200':
+#                     description: Webhook received successfully
+
+#     recordingEnded:
+#         post:
+#             summary: Recording ended
+#             description: >
+#                 This webhook is triggered when a recording ends.
+#                 The API provider will send a POST request containing the final details of the recording.
+#             operationId: recordingEndedWebhook
+#             parameters:
+#                 - name: X-Timestamp
+#                   in: header
+#                   description: Timestamp of the webhook event (in Unix Epoch seconds)
+#                   example: 1678901234
+#                   schema:
+#                       type: string
+#                 - name: X-Signature
+#                   in: header
+#                   description: HMAC signature for webhook verification
+#                   example: 1234567890abcdef
+#                   schema:
+#                       type: string
+#             requestBody:
+#                 required: true
+#                 content:
+#                     application/json:
+#                         schema:
+#                             type: object
+#                             properties:
+#                                 creationDate:
+#                                     type: number
+#                                     description: The date when the event was created (milliseconds since the Unix epoch).
+#                                     example: 1620000000000
+#                                 event:
+#                                     type: string
+#                                     description: Event type identifier.
+#                                     example: recordingEnded
+#                                 data:
+#                                     type: object
+#                                     properties:
+#                                         recordingId:
+#                                             type: string
+#                                             description: The unique identifier of the recording that ended.
+#                                             example: room-123--EG_XYZ--XX445
+#                                         roomId:
+#                                             type: string
+#                                             description: The unique identifier of the room for which the recording ended.
+#                                             example: room-123
+#                                         status:
+#                                             type: string
+#                                             description: The final status of the recording.
+#                                             example: COMPLETE
+#             responses:
+#                 '200':
+#                     description: Webhook received successfully

backend/package.json

@@ -29,8 +29,8 @@
 	"scripts": {
 		"build:prod": "tsc",
 		"postbuild:prod": "npm run doc:api && npm run doc:internal-api",
-		"doc:api": "mkdir -p public/openapi && npx openapi-generate-html -i openapi/openvidu-meet-api.yaml --ui=stoplight --theme=light --title 'OpenVidu Meet REST API' --description 'OpenVidu Meet REST API' -o public/openapi/public.html",
+		"doc:api": "mkdir -p public/openapi && cd openapi && npx openapi-generate-html -i openvidu-meet-api.yaml --ui=stoplight --theme=light --title 'OpenVidu Meet REST API' --description 'OpenVidu Meet REST API' -o ../public/openapi/public.html",
-		"doc:internal-api": "mkdir -p public/openapi && npx openapi-generate-html -i openapi/openvidu-meet-internal-api.yaml --ui=stoplight --theme=dark --title 'OpenVidu Meet Internal REST API' --description 'OpenVidu Meet Internal REST API' -o public/openapi/internal.html",
+		"doc:internal-api": "mkdir -p public/openapi && cd openapi && npx openapi-generate-html -i openvidu-meet-internal-api.yaml --ui=stoplight --theme=dark --title 'OpenVidu Meet Internal REST API' --description 'OpenVidu Meet Internal REST API' -o ../public/openapi/internal.html",
 		"start:prod": "node dist/src/server.js",
 		"start:dev": "nodemon",
 		"package:build": "npm run build:prod && npm pack",