backend: Refactor OpenAPI specs for consistency and clarity, and fix some minor errors

backend/openapi/components/headers/set-cookie-access-token.yaml

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

backend/openapi/components/headers/set-cookie-participant-token.yaml

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

backend/openapi/components/headers/set-cookie-refresh-token.yaml

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

backend/openapi/components/parameters/force-deletion.yaml

@@ -0,0 +1,9 @@
+name: force
+in: query
+description: >
+    Force deletion of the room even if there are active participants.
+    This will immediately disconnect all participants and remove the room.
+required: false
+schema:
+    type: string
+    example: 'true'

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

@@ -1,6 +1,7 @@
 name: participantName
 in: path
 required: true
-description: The name of the participant to delete
+description: The name of the participant.
 schema:
     type: string
+    example: 'Alice'

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

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

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

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

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

@@ -0,0 +1,7 @@
+name: recordingIds
+in: query
+required: true
+description: A comma-separated list of recording IDs to delete.
+schema:
+    type: string
+    example: 'room-123--EG_XYZ--XX445,room-123--EG_ZYX--XX446'

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

@@ -6,4 +6,4 @@ description: >
 required: false
 schema:
     type: string
-    example: 'room-123'
+    example: 'roomId,moderatorRoomUrl'

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

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

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

@@ -0,0 +1,7 @@
+name: roomIds
+in: query
+required: true
+description: A comma-separated list of room IDs to delete.
+schema:
+    type: string
+    example: 'room-123,room-456'

backend/openapi/components/parameters/x-signature.yaml

@@ -1,6 +1,5 @@
 name: X-Signature
 in: header
-description: HMAC signature for webhook verification
+description: HMAC signature for webhook verification.
-example: 1234567890abcdef
 schema:
     type: string

backend/openapi/components/parameters/x-timestamp.yaml

@@ -1,6 +1,6 @@
 name: X-Timestamp
 in: header
-description: Timestamp of the webhook event (in Unix Epoch seconds)
+description: Timestamp of the webhook event (in Unix Epoch milliseconds).
-example: 1678901234
 schema:
     type: string
+    example: '1697030400000'

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

@@ -3,13 +3,4 @@ required: true
 content:
     application/json:
         schema:
-            type: object
+            $ref: '../../schemas/internal/user-credentials.yaml'
-            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

@@ -1,4 +1,5 @@
 description: Participant details
+required: true
 content:
     application/json:
         schema:

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

@@ -2,7 +2,7 @@ description: Room update details
 content:
     application/json:
         schema:
-            $ref: '../schemas/meet-room-preferences.yaml#/MeetRoomPreferences'
+            $ref: '../../schemas/meet-room-preferences.yaml#/MeetRoomPreferences'
         examples:
             default:
                 summary: Standard preferences

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

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

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

@@ -4,5 +4,5 @@ content:
         schema:
             $ref: '../schemas/error.yaml'
         example:
-            code: 404
+            name: 'Room Error'
-            message: 'Room not found'
+            message: 'The room "room_123" does not exist'

backend/openapi/components/responses/internal/error-participant-already-exists.yaml

@@ -0,0 +1,8 @@
+description: Conflict — The participant already exists in the room
+content:
+    application/json:
+        schema:
+            $ref: '../../schemas/error.yaml'
+        example:
+            name: 'Participant Error'
+            message: '"Alice" already exists in the room "room_123"'

backend/openapi/components/responses/internal/error-participant-not-found.yaml

@@ -0,0 +1,8 @@
+description: Participant not found
+content:
+    application/json:
+        schema:
+            $ref: '../../schemas/error.yaml'
+        example:
+            name: 'Participant Error'
+            message: '"Alice" not found in room "room_123"'

backend/openapi/components/responses/internal/error-participant-token-still-valid.yaml

@@ -0,0 +1,7 @@
+description: Conflict — Current token is still valid
+content:
+    application/json:
+        schema:
+            $ref: '../../schemas/error.yaml'
+        example:
+            message: 'Participant token is still valid'

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

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

backend/openapi/components/responses/internal/error-recording-not-active.yaml

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

backend/openapi/components/responses/internal/success-delete-participant.yaml

@@ -0,0 +1,9 @@
+description: Successfully disconnect the participant
+content:
+    application/json:
+        schema:
+            type: object
+            properties:
+                message:
+                    type: string
+                    example: 'Participant deleted'

backend/openapi/components/responses/internal/success-generate-participant-token.yaml

@@ -0,0 +1,13 @@
+description: Successfully generated the participant token
+headers:
+    Set-Cookie:
+        $ref: '../../headers/set-cookie-participant-token.yaml'
+content:
+    application/json:
+        schema:
+            type: object
+            properties:
+                token:
+                    type: string
+                    description: >
+                        The token to authenticate the participant.

backend/openapi/components/responses/internal/success-get-profile.yaml

@@ -0,0 +1,5 @@
+description: Successfully retrieved user profile
+content:
+    application/json:
+        schema:
+            $ref: '../../schemas/internal/user.yaml'

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

@@ -1,12 +1,7 @@
 description: Successfully refreshed the access token
 headers:
     Set-Cookie:
-        description: >
+        $ref: '../../headers/set-cookie-access-token.yaml'
-            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:

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

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

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

@@ -8,12 +8,12 @@ headers:
 content:
     application/json:
         schema:
-            $ref: '../schemas/meet-recording.yaml'
+            $ref: '../../schemas/meet-recording.yaml'
         example:
             recordingId: 'room-123--EG_XYZ--XX445'
             roomId: 'room-123'
             status: 'ENDING'
-            filename: 'room-123--EG_XYZ--XX445'
+            filename: 'room-123--XX445.mp4'
             startDate: 1600000000000
             duration: 3.6
             details: 'End reason: StopEgress API'

backend/openapi/components/responses/internal/success-update-room.yaml

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

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

@@ -1,19 +1,9 @@
 description: Successfully logged in
 headers:
     Set-Cookie:
-        description: >
+        $ref: '../../headers/set-cookie-access-token.yaml'
-            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: >
+        $ref: '../../headers/set-cookie-refresh-token.yaml'
-            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:

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

@@ -11,7 +11,7 @@ content:
                     description: List of successfully deleted recording IDs.
                     example:
                         - 'room-123--EG_XYZ--XX445'
-                        - 'room-123--EG_XYZ--XX446'
+                        - 'room-123--EG_ZYX--XX446'
                 notDeleted:
                     type: array
                     description: List of recordings that could not be deleted along with the corresponding error messages.
@@ -32,7 +32,7 @@ content:
                 value:
                     deleted:
                         - 'room-123--EG_XYZ--XX445'
-                        - 'room-123--EG_XYZ--XX446'
+                        - 'room-123--EG_ZYX--XX446'
                     notDeleted: []
 
             partial_deletion_with_errors:
@@ -40,7 +40,7 @@ content:
                 value:
                     deleted:
                         - 'room-123--EG_XYZ--XX445'
-                        - 'room-123--EG_XYZ--XX446'
+                        - 'room-123--EG_ZYX--XX446'
                     notDeleted:
                         - recordingId: 'room-123--EG_XYZ--XX447'
                           error: 'Recording not found'
@@ -54,5 +54,5 @@ content:
                     notDeleted:
                         - recordingId: 'room-123--EG_XYZ--XX445'
                           error: 'Recording not found'
-                        - recordingId: 'room-123--EG_XYZ--XX446'
+                        - recordingId: 'room-123--EG_ZYX--XX446'
                           error: 'Recording not found'

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

@@ -14,12 +14,12 @@ content:
                         - 'room-456'
                 markedAsDeleted:
                     type: array
-                    description: List of rooms that were marked for deletion but not actually deleted. The rooms will be deleted when all participants leave the room.
                     items:
                         type: string
-                        example:
+                    description: List of rooms that were marked for deletion but not actually deleted. The rooms will be deleted when all participants leave the room.
-                            - 'room-789'
+                    example:
-                            - 'room-101'
+                        - 'room-789'
+                        - 'room-101'
         examples:
             successful_deletion:
                 summary: All rooms were successfully deleted

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

@@ -31,7 +31,7 @@ content:
                 summary: A paginated response indicating more recordings are available
                 value:
                     recordings:
-                        - recordingId: 'room-456--EG_XYZ--XX678'
+                        - recordingId: 'room-456--EG_ZYX--XX678'
                           roomId: 'room-456'
                           status: 'COMPLETE'
                           filename: 'room-456--XX678.mp4'

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

@@ -18,8 +18,8 @@ content:
                             enabled: false
                         virtualBackgroundPreferences:
                             enabled: true
-                    moderatorURL: 'http://localhost:6080/room/room-123/?secret=tok_123456'
+                    moderatorURL: 'http://localhost:6080/room/room-123/?secret=123456'
-                    publisherURL: 'http://localhost:6080/room/room-123/?secret=tok_123456'
+                    publisherURL: 'http://localhost:6080/room/room-123/?secret=654321'
 
             roomId_fields_only:
                 summary: Response with only the roomId
@@ -44,5 +44,5 @@ content:
             urls_only:
                 summary: Response containing only moderator and publisher URLs
                 value:
-                    moderatorURL: 'http://localhost:6080/room/room-123/?secret=tok_123456'
+                    moderatorURL: 'http://localhost:6080/room/room-123/?secret=123456'
-                    publisherURL: 'http://localhost:6080/room/room-123/?secret=tok_123456'
+                    publisherURL: 'http://localhost:6080/room/room-123/?secret=654321'

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

@@ -39,8 +39,8 @@ content:
                                   enabled: false
                               virtualBackgroundPreferences:
                                   enabled: true
-                          moderatorURL: 'http://localhost:6080/room/room-123/?secret=tok_123456'
+                          moderatorURL: 'http://localhost:6080/room/room-123/?secret=123456'
-                          publisherURL: 'http://localhost:6080/room/room-123/?secret=tok_123456'
+                          publisherURL: 'http://localhost:6080/room/room-123/?secret=654321'
                         - roomId: 'room-456'
                           roomIdPrefix: 'room'
                           creationDate: 1620001000000
@@ -52,8 +52,8 @@ content:
                                   enabled: true
                               virtualBackgroundPreferences:
                                   enabled: false
-                          moderatorURL: 'http://localhost:6080/room/room-456/?secret=tok_789012'
+                          moderatorURL: 'http://localhost:6080/room/room-456/?secret=789012'
-                          publisherURL: 'http://localhost:6080/room/room-456/?secret=tok_789012'
+                          publisherURL: 'http://localhost:6080/room/room-456/?secret=210987'
                     pagination:
                         isTruncated: false
                         maxItems: 10
@@ -102,10 +102,10 @@ content:
                 summary: Response containing only moderator and publisher URLs
                 value:
                     rooms:
-                        - moderatorURL: 'http://localhost:6080/room/room-123/?secret=tok_123456'
+                        - moderatorURL: 'http://localhost:6080/room/room-123/?secret=123456'
-                          publisherURL: 'http://localhost:6080/room/room-123/?secret=tok_123456'
+                          publisherURL: 'http://localhost:6080/room/room-123/?secret=654321'
-                        - moderatorURL: 'http://localhost:6080/room/room-456/?secret=tok_789012'
+                        - moderatorURL: 'http://localhost:6080/room/room-456/?secret=789012'
-                          publisherURL: 'http://localhost:6080/room/room-456/?secret=tok_789012'
+                          publisherURL: 'http://localhost:6080/room/room-456/?secret=210987'
                     pagination:
                         isTruncated: false
                         maxItems: 10

backend/openapi/components/responses/success-room-marked-for-deletion.yaml

@@ -0,0 +1,9 @@
+description: Room deletion accepted. The room will be deleted when all participants leave.
+content:
+    application/json:
+        schema:
+            type: object
+            properties:
+                message:
+                    type: string
+                    example: 'Room marked for deletion'

backend/openapi/components/schemas/error.yaml

@@ -8,4 +8,4 @@ properties:
         type: string
     code:
         type: integer
-description: HTTP status code associated with the error
+        description: HTTP status code associated with the error

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

@@ -6,16 +6,13 @@ required:
 properties:
     roomId:
         type: string
+        description: The unique identifier of the room where the participant will join.
         example: 'room-123'
-        description: >
-            The ID of the room where the participant will join.
     participantName:
         type: string
+        description: The name of the participant.
         example: 'Alice'
-        description: >
-            The name of the participant.
     secret:
         type: string
+        description: The secret token from the room Url
         example: 'abc123456'
-        description: >
-            The secret token from the room Url

backend/openapi/components/schemas/internal/user-credentials.yaml

@@ -0,0 +1,13 @@
+type: object
+required:
+    - username
+    - password
+properties:
+    username:
+        type: string
+        description: The username of the user.
+        example: 'admin'
+    password:
+        type: string
+        description: The password of the user.
+        example: 'password123'

backend/openapi/components/schemas/internal/user.yaml

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

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

@@ -7,7 +7,7 @@ properties:
     roomId:
         type: string
         example: 'room-123'
-        description: The ID of the room where the recording was made.
+        description: The unique identifier of the room where the recording was made.
     # outputMode:
     #   type: string
     #   example: 'COMPOSED'
@@ -15,16 +15,13 @@ properties:
     #     The output mode of the recording. Possible value: "COMPOSED".
     status:
         type: string
-        enum: ['STARTING', 'ACTIVE', 'ENDING', 'COMPLETE', 'FAILED', 'ABORTED', 'LIMITED_REACHED']
+        enum: ['STARTING', 'ACTIVE', 'ENDING', 'COMPLETE', 'FAILED', 'ABORTED', 'LIMIT_REACHED']
         example: 'ACTIVE'
-        description: >
+        description: The status of the recording.
-            The status of the recording.
     filename:
         type: string
         example: 'room-123--XX445.mp4'
-        description: >
+        description: The name of the recording file.
-            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

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

@@ -8,8 +8,8 @@ properties:
 
             After this date, the room will be automatically deleted and no new participants can join.
 
-            If this value is set, the room is marked for deletion but will only be removed after the last
+            If this value is set and the date has already passed, the room is marked for deletion but will only be removed after the last 
-              participant leaves ("graceful deletion").
+            participant leaves ("graceful deletion").
 
             If this value is not defined, the room will exist indefinitely until manually deleted.
     roomIdPrefix:

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

@@ -3,18 +3,13 @@ MeetRoomPreferences:
     properties:
         chatPreferences:
             $ref: '#/MeetChatPreferences'
-            description: >
+            description: Preferences for the chat feature in the room.
-                Preferences for the chat feature in the room.
-
         recordingPreferences:
             $ref: '#/MeetRecordingPreferences'
-            description: >
+            description: Preferences for recording the room.
-                Preferences for recording the room.
-
         virtualBackgroundPreferences:
             $ref: '#/MeetVirtualBackgroundPreferences'
-            description: >
+            description: Preferences for virtual background in the room.
-                Preferences for virtual background in the room.
 
 MeetChatPreferences:
     type: object
@@ -23,8 +18,7 @@ MeetChatPreferences:
             type: boolean
             default: true
             example: true
-            description: >
+            description: If true, the room will be allowed to send and receive chat messages.
-                If true, the room will be allowed to send and receive chat messages.
 MeetRecordingPreferences:
     type: object
     properties:
@@ -32,8 +26,7 @@ MeetRecordingPreferences:
             type: boolean
             default: true
             example: true
-            description: >
+            description: If true, the room will be allowed to record the video of the participants.
-                If true, the room will be allowed to record the video of the participants.
 MeetVirtualBackgroundPreferences:
     type: object
     properties:
@@ -41,5 +34,4 @@ MeetVirtualBackgroundPreferences:
             type: boolean
             default: true
             example: true
-            description: >
+            description: If true, the room will be allowed to use virtual background.
-                If true, the room will be allowed to use virtual background.

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

@@ -23,14 +23,13 @@ properties:
 
             After this date, the room will be automatically deleted and no new participants can join.
 
-            If this value is set, the room is marked for deletion but will only be removed after the last
+            If this value is set and the date has already passed, the room is marked for deletion but will only be removed after the last 
-              participant leaves ("graceful deletion").
+            participant leaves ("graceful deletion").
 
             If this value is not defined, the room will exist indefinitely until manually deleted.
     preferences:
         $ref: meet-room-preferences.yaml#/MeetRoomPreferences
-        description: >
+        description: The preferences for the room.
-            The preferences for the room.
     # maxParticipants:
     #     type: integer
     #     example: 10
@@ -39,13 +38,13 @@ properties:
     #         this limit, new participants will not be allowed to join.
     moderatorURL:
         type: string
-        example: 'http://localhost:6080/room/room-123/?secret=tok_123456'
+        example: 'http://localhost:6080/room/room-123/?secret=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'
+        example: 'http://localhost:6080/room/room-123/?secret=654321'
         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

@@ -3,19 +3,19 @@ MeetWebhookEvent:
     properties:
         creationDate:
             type: number
-            description: 'The timestamp when the webhook event was created.'
+            description: The timestamp when the webhook event was created.
         event:
             $ref: '#/MeetWebhookEventType'
-            description: 'The type of event.'
+            description: The type of event.
         data:
             oneOf:
                 - allOf:
                       - title: Recording Event Data
-                      - description: 'Data for recording-related events (started, updated, ended)'
+                      - 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)'
+                #       - description: Data for room-related events (created, updated, deleted)
                 #       - $ref: './meet-room.yaml'
             discriminator:
                 propertyName: eventType
@@ -26,7 +26,7 @@ MeetWebhookEvent:
                     # roomCreated: './meet-room.yaml'
                     # roomUpdated: './meet-room.yaml'
                     # roomDeleted: './meet-room.yaml'
-            description: 'The event payload data, determined by the event type.'
+            description: The event payload data, determined by the event type.
 
 MeetWebhookEventType:
     type: string

backend/openapi/components/security.yaml

@@ -10,6 +10,12 @@ accessTokenCookie:
     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 when it expires. This token is used to obtain a new access token.
 participantTokenCookie:
     type: apiKey
     name: OvMeetParticipantToken

backend/openapi/openvidu-meet-api.yaml

@@ -36,4 +36,4 @@ components:
         Error:
             $ref: components/schemas/error.yaml
         MeetWebhookEvent:
-            $ref: components/schemas/meet-webhook.yaml#/MeetWebhookEvent
+            $ref: components/schemas/meet-webhook.yaml#/MeetWebhookEvent

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

@@ -30,70 +30,13 @@ paths:
         $ref: './paths/internal/participants.yaml#/~1participants~1token~1refresh'
     /participants/{participantName}:
         $ref: './paths/internal/participants.yaml#/~1participants~1{participantName}'
-        delete:
-            operationId: disconnectParticipant
-            summary: Delete a participant from a room
-            description: >
-                Deletes a participant from an OpenVidu Meet room.
-            tags:
-                - Internal API - Participant
-            security:
-                - participantTokenCookie: []
-            parameters:
-                - name: participantName
-                  in: path
-                  required: true
-                  description: The name of the participant to delete
-                  schema:
-                      type: string
-                - name: roomId
-                  in: query
-                  required: true
-                  description: The ID of the room where the participant is connected
-                  schema:
-                      type: string
-            responses:
-                '204':
-                    description: Successfully disconnect the participant
-                '401':
-                    description: Unauthorized — The participant access token is missing or invalid
-                    content:
-                        application/json:
-                            schema:
-                                $ref: '#/components/schemas/Error'
-                            example:
-                                message: 'Unauthorized'
-                '403':
-                    description: Forbidden — The participant authenticated with the access token is not moderator of the room
-                    content:
-                        application/json:
-                            schema:
-                                $ref: '#/components/schemas/Error'
-                            example:
-                                message: 'Insufficient permissions to access this resource'
-                '404':
-                    description: Participant not found
-                    content:
-                        application/json:
-                            schema:
-                                $ref: '#/components/schemas/Error'
-                            example:
-                                code: 404
-                                message: 'Participant not found'
-                '500':
-                    description: Internal server error
-                    content:
-                        application/json:
-                            schema:
-                                $ref: '#/components/schemas/Error'
-                            example:
-                                code: 500
-                                message: 'Internal server error'
 
 components:
     securitySchemes:
         $ref: './components/security.yaml'
     schemas:
+        User:
+            $ref: components/schemas/internal/user.yaml
         MeetRoom:
             $ref: components/schemas/meet-room.yaml
         MeetRoomOptions:
@@ -104,5 +47,3 @@ components:
             $ref: components/schemas/meet-recording.yaml
         Error:
             $ref: components/schemas/error.yaml
-        MeetWebhookEvent:
-            $ref: components/schemas/meet-webhook.yaml#/MeetWebhookEvent

backend/openapi/paths/internal/auth.yaml

@@ -11,7 +11,6 @@
         responses:
             '200':
                 $ref: '../../components/responses/internal/success-user-login.yaml'
-            # Should be 401
             '404':
                 $ref: '../../components/responses/internal/error-invalid-credentials.yaml'
             '422':
@@ -28,8 +27,24 @@
             - Internal API - Authentication
         responses:
             '200':
-                $ref: '../../components/responses/internal/success-user-logout.yaml'
+                description: Successfully logged out
-
+                headers:
+                    Set-Cookie:
+                        schema:
+                            type: string
+                            example: 'OvMeetAccessToken=; Path=/; HttpOnly; SameSite=Strict'
+                    Set-Cookie-Refresh:
+                        schema:
+                            type: string
+                            example: 'OvMeetRefreshToken=; Path=/meet/internal-api/v1/auth; HttpOnly; SameSite=Strict'
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            properties:
+                                message:
+                                    type: string
+                                    example: 'Logout successful'
 /auth/refresh:
     post:
         operationId: refreshAccessToken
@@ -60,19 +75,6 @@
             - accessTokenCookie: []
         responses:
             '200':
-                description: Successfully retrieved user profile
+                $ref: '../../components/responses/internal/success-get-profile.yaml'
-                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'
+                $ref: '../../components/responses/unauthorized-error.yaml'

backend/openapi/paths/internal/participants.yaml

@@ -12,41 +12,15 @@
             $ref: '../../components/requestBodies/internal/participant-token-request.yaml'
         responses:
             '200':
-                description: Successfully generated the participant token
+                $ref: '../../components/responses/internal/success-generate-participant-token.yaml'
-                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
+                $ref: '../../components/responses/internal/error-participant-already-exists.yaml'
-                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'
 
@@ -64,25 +38,7 @@
             $ref: '../../components/requestBodies/internal/participant-token-request.yaml'
         responses:
             '200':
-                description: Successfully refreshed the participant token
+                $ref: '../../components/responses/internal/success-generate-participant-token.yaml'
-                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':
@@ -90,13 +46,7 @@
             '404':
                 $ref: '../../components/responses/error-room-not-found.yaml'
             '409':
-                description: Conflict — Current token is still valid
+                $ref: '../../components/responses/internal/error-participant-token-still-valid.yaml'
-                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}:
@@ -110,16 +60,16 @@
         security:
             - participantTokenCookie: []
         parameters:
-            - $ref: '../../components/parameters/internal/participant-name.yaml'
             - $ref: '../../components/parameters/room-id.yaml'
+            - $ref: '../../components/parameters/internal/participant-name.yaml'
         responses:
-            '204':
+            '200':
-                description: Successfully disconnect the participant
+                $ref: '../../components/responses/internal/success-delete-participant.yaml'
             '401':
                 $ref: '../../components/responses/unauthorized-error.yaml'
             '403':
                 $ref: '../../components/responses/forbidden-error.yaml'
             '404':
-                $ref: '../../components/responses/error-room-not-found.yaml'
+                $ref: '../../components/responses/internal/error-participant-not-found.yaml'
             '500':
                 $ref: '../../components/responses/internal-server-error.yaml'

backend/openapi/paths/internal/recordings.yaml

@@ -12,7 +12,7 @@
             $ref: '../../components/requestBodies/start-recording-request.yaml'
         responses:
             '200':
-                $ref: '../../components/responses/success-start-recording.yaml'
+                $ref: '../../components/responses/internal/success-start-recording.yaml'
             '401':
                 $ref: '../../components/responses/unauthorized-error.yaml'
             '403':
@@ -20,12 +20,11 @@
             '404':
                 $ref: '../../components/responses/error-room-not-found.yaml'
             '409':
-                $ref: '../../components/responses/error-recording-already-started.yaml'
+                $ref: '../../components/responses/internal/error-recording-already-started.yaml'
             '422':
                 $ref: '../../components/responses/validation-error.yaml'
             '500':
                 $ref: '../../components/responses/internal-server-error.yaml'
-
 /recordings/{recordingId}/stop:
     post:
         operationId: stopRecording
@@ -41,7 +40,7 @@
             - $ref: '../../components/parameters/recording-id.yaml'
         responses:
             '202':
-                $ref: '../../components/responses/success-stop-recording.yaml'
+                $ref: '../../components/responses/internal/success-stop-recording.yaml'
             '401':
                 $ref: '../../components/responses/unauthorized-error.yaml'
             '403':
@@ -49,7 +48,7 @@
             '404':
                 $ref: '../../components/responses/error-recording-not-found.yaml'
             '409':
-                $ref: '../../components/responses/error-recording-in-progress.yaml'
+                $ref: '../../components/responses/internal/error-recording-not-active.yaml'
             '500':
                 $ref: '../../components/responses/internal-server-error.yaml'
 

backend/openapi/paths/internal/rooms.yaml

@@ -7,21 +7,14 @@
         tags:
             - Internal API - Rooms
         security:
-            - apiKeyInHeader: []
             - accessTokenCookie: []
         parameters:
-            - name: roomId
+            - $ref: '../../components/parameters/room-id.yaml'
-              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'
+            $ref: '../../components/requestBodies/internal/update-room-request.yaml'
         responses:
             '200':
-                $ref: '../../components/responses/success-create-room.yaml'
+                $ref: '../../components/responses/internal/success-update-room.yaml'
             '401':
                 $ref: '../../components/responses/unauthorized-error.yaml'
             '403':
@@ -32,7 +25,6 @@
                 $ref: '../../components/responses/validation-error.yaml'
             '500':
                 $ref: '../../components/responses/internal-server-error.yaml'
-
 /rooms/{roomId}/participant-role:
     get:
         operationId: getParticipantRole

backend/openapi/paths/recordings.yaml

@@ -56,14 +56,7 @@
             - apiKeyInHeader: []
             - accessTokenCookie: []
         parameters:
-            - name: recordingIds
+            - $ref: '../components/parameters/recording-ids.yaml'
-              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'
@@ -138,7 +131,6 @@
         tags:
             - OpenVidu Meet - Recordings
         security:
-            - apiKeyInHeader: []
             - accessTokenCookie: []
         parameters:
             - $ref: '../components/parameters/recording-id.yaml'
@@ -194,7 +186,7 @@
             '403':
                 $ref: '../components/responses/forbidden-error.yaml'
             '404':
-                $ref: '../components/responses/error-room-not-found.yaml'
+                $ref: '../components/responses/error-recording-not-found.yaml'
             '416':
                 description: Requested range not satisfiable
                 content:

backend/openapi/paths/rooms.yaml

@@ -53,22 +53,27 @@
         summary: Bulk delete rooms
         description: >
             Delete multiple OpenVidu Meet rooms at once with the specified room IDs.
+
+            If a room has active participants, it will be marked for deletion
+            and will be removed once all participants leave.
+
+            If the "force" parameter is set to true, all rooms will be deleted immediately
+            regardless of active participants.
         tags:
             - OpenVidu Meet - Room
         security:
             - apiKeyInHeader: []
             - accessTokenCookie: []
         parameters:
-            - name: roomIds
+            - $ref: '../components/parameters/room-ids.yaml'
-              in: query
+            - $ref: '../components/parameters/force-deletion.yaml'
-              required: true
-              description: A comma-separated list of room IDs to delete.
-              schema:
-                  type: string
-                  example: 'room-123,room-456'
         responses:
             '200':
                 $ref: '../components/responses/success-bulk-delete-rooms.yaml'
+            '202':
+                $ref: '../components/responses/success-room-marked-for-deletion.yaml'
+            '204':
+                description: Successfully deleted the OpenVidu Meet room
             '401':
                 $ref: '../components/responses/unauthorized-error.yaml'
             '403':
@@ -107,18 +112,13 @@
         operationId: deleteRoom
         summary: Delete a room
         description: >
-            Permanently removes an OpenVidu Meet room with the specified room ID.
+            Deletes an OpenVidu Meet room with the specified room ID.
-            When a room is deleted:
 
-            - All active participants are immediately disconnected
+            If the room has active participants, it will be marked for deletion
+            and will be removed once all participants leave.
 
-            - All associated resources and session data are removed
+            If the "force" parameter is set to true, the room will be deleted immediately
-
+            regardless of active participants.
-            - The room ID becomes available for reuse
-
-            This operation is idempotent - deleting a non-existent room or
-            attempting to delete an already removed room will return a successful
-            response.
         tags:
             - OpenVidu Meet - Room
         security:
@@ -128,7 +128,7 @@
             - $ref: '../components/parameters/room-id.yaml'
         responses:
             '202':
-                description: Room deletion accepted. The room will be deleted when all participants leave.
+                $ref: '../components/responses/success-room-marked-for-deletion.yaml'
             '204':
                 description: Successfully deleted the OpenVidu Meet room
             '401':

backend/openapi/webhooks/webhooks.yaml

@@ -10,6 +10,7 @@ recordingStarted:
         parameters:
             - $ref: ../components/parameters/x-timestamp.yaml
             - $ref: ../components/parameters/x-signature.yaml
+        # TODO: Use defined schema for request body
         requestBody:
             required: true
             content:
@@ -60,6 +61,7 @@ recordingUpdated:
         parameters:
             - $ref: ../components/parameters/x-timestamp.yaml
             - $ref: ../components/parameters/x-signature.yaml
+        # TODO: Use defined schema for request body
         requestBody:
             required: true
             content:
@@ -112,6 +114,7 @@ recordingEnded:
         parameters:
             - $ref: ../components/parameters/x-timestamp.yaml
             - $ref: ../components/parameters/x-signature.yaml
+        # TODO: Use defined schema for request body
         requestBody:
             required: true
             content: