Refactor OpenAPI documentation for clarity and consistency

backend/openapi/components/headers/accept-ranges.yaml

@@ -1,4 +1,5 @@
-description: Indicates that the server supports range requests for content retrieval
+description: >
+    Specifies that the server allows clients to request specific ranges of content, enabling partial retrieval of resources.
 schema:
     type: string
 example: bytes

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

@@ -3,4 +3,4 @@ description: >
     This cookie is used to authenticate the user in subsequent requests.
 schema:
     type: string
-    example: 'OvMeetAccessToken=token_123456; Path=/; HttpOnly; SameSite=Strict'
+example: 'OvMeetAccessToken=token_123456; Path=/; HttpOnly; SameSite=Strict'

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

@@ -3,4 +3,4 @@ description: >
     This cookie is used to authenticate the participant in the room.
 schema:
     type: string
-    example: 'OvMeetParticipantToken=token_123456; Path=/; HttpOnly; SameSite=Strict'
+example: 'OvMeetParticipantToken=token_123456; Path=/; HttpOnly; SameSite=Strict'

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

@@ -3,4 +3,4 @@ description: >
     This cookie is used to access the recordings in a room.
 schema:
     type: string
-    example: 'OvMeetRecordingToken=token_123456; Path=/; HttpOnly; SameSite=Strict'
+example: 'OvMeetRecordingToken=token_123456; Path=/; HttpOnly; SameSite=Strict'

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

@@ -3,4 +3,4 @@ description: >
     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'
+example: 'OvMeetRefreshToken=token_123456; Path=/meet/internal-api/v1/auth; HttpOnly; SameSite=Strict'

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

@@ -5,5 +5,4 @@ description: >
     This will immediately disconnect all participants and remove the room.
 required: false
 schema:
-    type: string
+    type: boolean
-    example: 'true'

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

@@ -4,4 +4,4 @@ required: true
 description: The name of the participant.
 schema:
     type: string
-    example: 'Alice'
+example: 'Alice'

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

@@ -1,7 +1,7 @@
 name: maxItems
 in: query
 required: false
-description: The number of rooms per page (default is 10). Maximum is 100.
+description: Specifies the maximum number of items to return per page. The default value is 10, and the maximum allowed is 100.
 schema:
     type: integer
     default: 10

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

@@ -1,6 +1,6 @@
 name: nextPageToken
 in: query
 required: false
-description: The token to retrieve the next page of elements.
+description: A token used for pagination to fetch the next set of items in a multi-page response.
 schema:
     type: string

backend/openapi/components/parameters/private-access.yaml

@@ -1,8 +1,8 @@
 name: privateAcess
 in: query
 description: >
-    Indicates whether the retrieved recording URL should be configured for private access, i.e., the URL will be accessible only to authenticated users.
+    Specifies if the recording URL should be restricted to private access, 
+    meaning only authenticated users can view or download the recording.
 required: false
 schema:
-    type: string
+    type: boolean
-    example: 'true'

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

@@ -1,9 +1,9 @@
 name: fields
 in: query
 description: >
-    The fields to retrieve from the recording.
+    Specifies which fields to include in the response for the recording resource.
-    Comma-separated list of fields to include in the response.
+    Provide a comma-separated list of field names.
 required: false
 schema:
     type: string
-    example: 'recordingId,roomId'
+example: 'recordingId,roomId'

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

@@ -4,4 +4,4 @@ required: true
 description: The unique identifier of the recording.
 schema:
     type: string
-    example: 'room-123--EG_XYZ--XX445'
+example: 'room-123--EG_XYZ--XX445'

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

@@ -3,9 +3,8 @@ in: query
 required: true
 description: >
     A comma-separated list of recording IDs.
-    <br>
+    Each recording ID must follow the format: `{roomId}--{egressId}--{uid}`.
-    Each recording ID should be in the format 'roomId--egressId--uid'
 
 schema:
     type: string
-    example: 'room-123--EG_XYZ--XX445,room-123--EG_ZYX--XX446'
+example: 'room-123--EG_XYZ--XX445,room-123--EG_ZYX--XX446'

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

@@ -1,11 +1,14 @@
 name: Range
 in: header
 required: false
-description: >
+description: |
-    This endpoint accepts a `Range` header to specify the byte range of the recording file to be streamed.
+    This endpoint supports the `Range` header to request a specific byte range of the recording file.  
-    The format of the `Range` header should be `bytes=start-end`, where `start` is required and `end` is optional.
+    Use the format `bytes=start-end`, where `start` is the starting byte (required) and `end` is the ending byte (optional).
-    For example,
+
-      - `bytes=0-1023` to request the first 1024 bytes of the file.
+    Examples:
-      - `bytes=1000-` to request from byte 1000 to the end of the file.
+      - `bytes=0-1023`: Requests bytes 0 through 1023 (first 1024 bytes).
+      - `bytes=1000-`: Requests from byte 1000 to the end of the file.
+
+    This allows efficient partial downloads and resume capabilities for large files.
 schema:
     type: string

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

@@ -1,6 +1,7 @@
 name: secret
 in: query
 required: false
-description: The secret value used to access the recording when sharing a recording link.
+description: >
+    Optional secret value that must be provided to access the recording via a shared link, enhancing security for shared recordings.
 schema:
     type: string

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

@@ -0,0 +1,19 @@
+name: status
+in: query
+required: false
+description: |
+    Filter recordings by their status.
+
+    You can provide multiple statuses as a comma-separated list (e.g., `status=ACTIVE,FAILED`).
+
+    > ⚠️ **Note:** Using this filter may impact performance for large datasets.
+schema:
+    type: string
+    enum:
+        - STARTING
+        - ACTIVE
+        - ENDING
+        - COMPLETE
+        - FAILED
+        - ABORTED
+        - LIMIT_REACHED

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

@@ -1,9 +1,9 @@
 name: fields
 in: query
 description: >
-    The fields to retrieve from the room.
+    Specifies which fields to include in the response for the room resource.
-    Comma-separated list of fields to include in the response.
+    Provide a comma-separated list of field names.
 required: false
 schema:
     type: string
-    example: 'roomId,moderatorRoomUrl'
+example: 'roomId,moderatorRoomUrl'

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

@@ -4,4 +4,4 @@ required: true
 description: The unique identifier of the room.
 schema:
     type: string
-    example: 'room-123'
+example: 'room-123'

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

@@ -1,7 +1,9 @@
 name: roomId
 in: query
 required: false
-description: The unique identifier of the room. Specify the room ID to filter recordings by their associated room.
+description: >
+    The unique identifier for the room. 
+    Use this parameter to filter recordings and retrieve only those associated with the specified room ID.
 schema:
     type: string
-    example: 'room-123'
+example: 'room-123'

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

@@ -1,7 +1,9 @@
 name: roomIds
 in: query
 required: true
-description: A comma-separated list of room IDs to delete.
+description: >
+    Comma-separated list of room IDs to delete.
+    Each ID should correspond to an existing room.
 schema:
     type: string
-    example: 'room-123,room-456'
+example: 'room-123,room-456'

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

@@ -2,7 +2,6 @@ name: x-signature
 in: header
 description: >
     HMAC-SHA256 signature of the request body, created using your webhook secret.
-
     Use this to verify the webhook came from OpenVidu Meet and wasn't tampered with.
 required: true
 schema:

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

@@ -2,9 +2,7 @@ name: x-timestamp
 in: header
 description: >
     Unix timestamp (in seconds) when the webhook was sent.
-
     Can be used to validate webhook age and prevent replay attacks.
 required: true
 schema:
     type: string
-    example: '1697030400000'

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

@@ -1,4 +1,4 @@
-description: Room creation details
+description: Room creation options
 required: true
 content:
     application/json:

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

@@ -1,4 +1,4 @@
-description: Recording details
+description: Room to record
 required: true
 content:
     application/json:

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

@@ -1,4 +1,4 @@
-description: Room update details
+description: New room preferences
 content:
     application/json:
         schema:

backend/openapi/components/requestBodies/internal/update-security-preferences.yaml

@@ -1,4 +1,4 @@
-description: Security preferences 
+description: New security preferences
 required: true
 content:
     application/json:

backend/openapi/components/requestBodies/internal/update-webhooks-preferences.yaml

@@ -1,4 +1,4 @@
-description: Webhooks preferences 
+description: New webhooks preferences 
 required: true
 content:
     application/json:

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

@@ -1,4 +1,4 @@
-description: Conflict — The recording is in `STARTING` state or already stopped
+description: Conflict — The recording is starting or already stopped
 content:
     application/json:
         schema:

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

@@ -1,4 +1,4 @@
-description: Successfully disconnect the participant
+description: Successfully disconnected the participant
 content:
     application/json:
         schema:

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

@@ -15,4 +15,4 @@ headers:
         schema:
             type: string
             format: uri
-        example: https://your-api.com/meet/internal-api/v1/recordings/room-123--EG_XYZ--XX445
+        example: https://your-api.com/internal-api/v1/recordings/room-123--EG_XYZ--XX445

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

@@ -4,7 +4,7 @@ headers:
         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'
+            example: 'https://openvidu.example.com/api/v1/recordings/room-123--EG_XYZ--XX445'
 content:
     application/json:
         schema:

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

@@ -2,7 +2,7 @@ description: Successfully logged in
 headers:
     Set-Cookie:
         $ref: '../../headers/set-cookie-access-token.yaml'
-    Set-Cookie-Refresh:
+    Set-Cookie*:
         $ref: '../../headers/set-cookie-refresh-token.yaml'
 content:
     application/json:

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

@@ -1,13 +1,11 @@
 description: Successfully logged out
 headers:
     Set-Cookie:
+        description: >
+            Clears the access and refresh token cookie.
         schema:
             type: string
-            example: 'OvMeetAccessToken=; Path=/; HttpOnly; SameSite=Strict'
+        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:

backend/openapi/components/responses/pro-feature-error.yaml

@@ -1,4 +1,4 @@
-description: PRO Feature Error
+description: PRO feature
 content:
     application/json:
         schema:

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

@@ -36,14 +36,14 @@ content:
                         - recordingId: 'room-123--EG_XYZ--XX447'
                           error: 'Recording not found'
                         - recordingId: 'room-123--EG_XYZ--XX448'
-                          error: 'Access denied for deletion'
+                          error: 'Recording in progress'
 
             no_deletion_performed:
                 summary: No recordings were deleted
                 value:
                     deleted: []
                     notDeleted:
-                        - recordingId: 'room-123--EG_XYZ--XX445'
+                        - recordingId: 'room-123--EG_XYZ--XX447'
-                          error: 'Recording not found'
-                        - recordingId: 'room-123--EG_ZYX--XX446'
                           error: 'Recording not found'
+                        - recordingId: 'room-123--EG_ZYX--XX448'
+                          error: 'Recording in progress'

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

@@ -15,7 +15,9 @@ content:
                     type: array
                     items:
                         type: string
-                    description: List of rooms that were marked for deletion but not actually deleted. The rooms will be deleted when all participants leave the room.
+                    description: >-
+                        List of rooms that were marked for deletion but not actually deleted.
+                        These rooms will be deleted when all participants leave.
         example:
             deleted:
                 - 'room-123'

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

@@ -9,4 +9,4 @@ headers:
         schema:
             type: string
             format: uri
-        example: https://your-api.com/meet/api/v1/rooms/room-id-123
+        example: https://your-api.com/api/v1/rooms/room-123

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

@@ -1,4 +1,4 @@
-description: Successfully retrieved the recording URL.
+description: Successfully retrieved the recording URL
 content:
     application/json:
         schema:
@@ -7,5 +7,5 @@ content:
                 url:
                     type: string
                     format: uri
-                    description: URL to access the recording media.
+                    description: URL to access the recording.
-                    example: https://example.com/meet/api/v1/recordings/room-123--EG_XYZ--XX445/media?secret=abc123
+                    example: https://example.com/recording/room-123--EG_XYZ--XX445?secret=abc123

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

@@ -1,4 +1,4 @@
-description: Successfully retrieved the recording.
+description: Successfully retrieved the recording
 content:
     application/json:
         schema:

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=123456'
+                    moderatorURL: 'http://localhost:6080/room/room-123?secret=123456'
-                    publisherURL: 'http://localhost:6080/room/room-123/?secret=654321'
+                    publisherURL: 'http://localhost:6080/room/room-123?secret=654321'
 
             fields=roomId:
                 summary: Response with only the roomId
@@ -44,5 +44,5 @@ content:
             fields=moderatorURL,publisherURL:
                 summary: Response containing only moderator and publisher URLs
                 value:
-                    moderatorURL: 'http://localhost:6080/room/room-123/?secret=123456'
+                    moderatorURL: 'http://localhost:6080/room/room-123?secret=123456'
-                    publisherURL: 'http://localhost:6080/room/room-123/?secret=654321'
+                    publisherURL: 'http://localhost:6080/room/room-123?secret=654321'

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

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

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

@@ -1,5 +1,5 @@
 description: >
-    All specified rooms were marked error for deletion (due to active participants)
+    All specified rooms were marked for deletion (due to active participants)
     and will be removed once all participants leave.
 content:
     application/json:

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

@@ -1,4 +1,4 @@
-description: Unprocessable Entity — Invalid request body
+description: Unprocessable Entity — Invalid request
 content:
     application/json:
         schema:

backend/openapi/components/responses/webhook-success.yaml

@@ -1,7 +1,7 @@
-description: >
+description: |
-  Webhook received and processed successfully.
+    Webhook received and processed successfully.
 
-  Important: Webhook endpoints must return HTTP 200 OK promptly to acknowledge receipt.
+    > **Important:** Webhook endpoints must return HTTP 200 OK promptly to acknowledge receipt.
-  Any processing should be done asynchronously after responding.
+    > Any processing should be done asynchronously after responding.
-
+    >
-  Non-200 responses or timeouts will trigger retries according to the webhook delivery policy.
+    > Non-200 responses or timeouts will trigger retries according to the webhook delivery policy.

backend/openapi/components/schemas/internal/meet-room-role-permissions.yaml

@@ -23,8 +23,7 @@ properties:
                     room:
                         type: string
                         description: >
-                            The ID of the room associated with the participant.
+                            Unique identifier of the room to which the participant is assigned.
-                        example: roomId
                     canPublish:
                         type: boolean
                         description: >
@@ -61,5 +60,5 @@ properties:
                     canChangeVirtualBackground:
                         type: boolean
                         description: >
-                            Indicates whether the participant can change virtual background in the room.
+                            Indicates whether the participant can change their own virtual background.
                         example: true

backend/openapi/components/schemas/internal/security-preferences.yaml

@@ -16,7 +16,9 @@ AuthenticationPreferences:
                         - single-user
                     default: single-user
                     example: single-user
-                    description: The authentication method to use.
+                    description: |
+                        Specifies the authentication method used to access the application.
+                        - `single-user`: Only one user account exists, which has administrative privileges and is used for all access.
         authModeToAccessRoom:
             type: string
             enum:
@@ -25,4 +27,8 @@ AuthenticationPreferences:
                 - all_users
             default: none
             example: none
-            description: The authentication mode to access a room.
+            description: |
+                Specifies who is required to authenticate before accessing a room:
+                - `none`: No authentication required.
+                - `moderators_only`: Only moderators need to authenticate.
+                - `all_users`: All users must authenticate.

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

@@ -8,5 +8,6 @@ properties:
         type: array
         items:
             type: string
+            enum: ['admin', 'user']
         example: ['admin', 'user']
         description: A list of roles assigned to the authenticated user.

backend/openapi/components/schemas/internal/webhooks-preferences.yaml

@@ -6,5 +6,6 @@ properties:
         description: Indicates whether webhooks are enabled or disabled.
     url:
         type: string
+        format: uri
         example: 'https://example.com/webhook'
         description: The URL to which webhooks will be sent. This is only mandatory if webhooks are enabled.

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

@@ -3,13 +3,13 @@ properties:
     isTruncated:
         type: boolean
         description: >
-            Indicates if there are more elements to retrieve.
+            Indicates if there are more items to retrieve.
-            If true, use the `nextPageToken` to fetch the next set of elements.
+            If true, use the `nextPageToken` to fetch the next set of items.
     nextPageToken:
         type: [string, 'null']
-        description: The token to retrieve the next page of elements.
+        description: The token to retrieve the next page of items.
     maxItems:
         type: integer
         description: >
-            Maximum number of elements returned in a single response page.
+            Maximum number of items returned in a single response page.
             Corresponds to the `maxItems` query parameter in the request.

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

@@ -3,15 +3,14 @@ properties:
     autoDeletionDate:
         type: [number, 'null']
         example: 1900000000000
-        description: >
+        description: |
-            The date and time when the room will be deleted (must be one hour in the future or more) represented in milliseconds since the Unix epoch.
+            The timestamp (in milliseconds since the Unix epoch) specifying when the room will be automatically deleted.
+            This must be at least one hour in the future.
 
-            After this date, the room will be automatically deleted and no new participants can join.
+            After this time, the room is closed to new participants and scheduled for deletion. 
+            It will be removed after the last participant leaves (graceful deletion).
 
-            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
+            If not set, the room remains active until manually deleted.
-            participant leaves ("graceful deletion").
-
-            If this value is not defined, the room will exist indefinitely until manually deleted.
     roomIdPrefix:
         type: string
         example: 'room'

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

@@ -18,15 +18,14 @@ properties:
     autoDeletionDate:
         type: [number, 'null']
         example: 1900000000000
-        description: >
+        description: |
-            The date and time when the room will be deleted (must be one hour in the future or more) represented in milliseconds since the Unix epoch.
+            The timestamp (in milliseconds since the Unix epoch) specifying when the room will be automatically deleted.
+            This must be at least one hour in the future.
 
-            After this date, the room will be automatically deleted and no new participants can join.
+            After this time, the room is closed to new participants and scheduled for deletion. 
+            It will be removed after the last participant leaves (graceful deletion).
 
-            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 
+            If not set, the room remains active until manually deleted.
-            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: The preferences for the room.
@@ -38,13 +37,13 @@ properties:
     #         this limit, new participants will not be allowed to join.
     moderatorURL:
         type: string
-        example: 'http://localhost:6080/room/room-123/?secret=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
+            The URL for the moderator participants to join the room. The moderator role has special permissions to manage the
             room and participants.
     publisherURL:
         type: string
-        example: 'http://localhost:6080/room/room-123/?secret=654321'
+        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
+            The URL for the publisher participants to join the room. The publisher role has permissions to publish audio and
             video streams to the room.

backend/openapi/components/schemas/webhook-base-event.yaml

@@ -1,17 +1,17 @@
 type: object
 required:
-  - creationDate
+    - creationDate
-  - event
+    - event
-  - data
+    - data
 properties:
-  creationDate:
+    creationDate:
-    type: number
+        type: number
-    description: The date when the event was created (milliseconds since the Unix epoch).
+        description: The date when the event was created (milliseconds since the Unix epoch).
-    example: 1620000000000
+        example: 1620000000000
-  event:
+    event:
-    type: string
+        type: string
-    description: Event type identifier.
+        description: Event type identifier.
-    example: webhookEvent
+        example: webhookEvent
-  data:
+    data:
-    type: object
+        type: object
-    description: The data associated with the event.
+        description: The data associated with the event.

backend/openapi/components/security.yaml

@@ -15,7 +15,7 @@ refreshTokenCookie:
     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.
+        The JWT token to refresh the access token when it expires..
 participantTokenCookie:
     type: apiKey
     name: OvMeetParticipantToken

backend/openapi/openvidu-meet-api.yaml

@@ -26,8 +26,6 @@ paths:
 components:
     securitySchemes:
         $ref: './components/security.yaml'
-    # responses:
-    #     $ref: './components/responses.yaml'
     schemas:
         MeetRoom:
             $ref: components/schemas/meet-room.yaml

backend/openapi/paths/internal/auth.yaml

@@ -27,28 +27,11 @@
             - Internal API - Authentication
         responses:
             '200':
-                description: Successfully logged out
+                $ref: '../../components/responses/internal/success-user-logout.yaml'
-                headers:
-                    Set-Cookie:
-                        schema:
-                            type: string
-                            example: 'OvMeetAccessToken=; Path=/; HttpOnly; SameSite=Strict'
-                    Set-Cookie-Refresh:
-                        schema:
-                            type: string
-                            example: 'OvMeetRefreshToken=; Path=/meet/internal-api/v1/auth; HttpOnly; SameSite=Strict'
-                content:
-                    application/json:
-                        schema:
-                            type: object
-                            properties:
-                                message:
-                                    type: string
-                                    example: 'Logout successful'
 /auth/refresh:
     post:
         operationId: refreshAccessToken
-        summary: Refresh the access token
+        summary: Refresh access token
         description: >
             Refreshes the access token using the refresh token.
             The new access token is returned in a cookie.
@@ -68,10 +51,11 @@
     post:
         operationId: createApiKey
         summary: Create a new API key
-        description: >
+        description: |
-            Creates a new API key. Only one API key can be created in the system.
+            Creates a new API key, returning it in the response.
-            If an API key already exists, it will be replaced with the new one.
+
-            The API key is returned in the response.
+            > **Note:** Only one API key can be created in the system.
+            > If an API key already exists, it will be replaced with the new one.
         tags:
             - Internal API - Authentication
         security:
@@ -84,8 +68,11 @@
     get:
         operationId: getApiKeys
         summary: Get API keys
-        description: >
+        description: |
             Retrieves the existing API keys.
+
+            > **Note:** Only one API key can exist in the system.
+            > If no API key exists, an empty array will be returned.
         tags:
             - Internal API - Authentication
         security:
@@ -106,9 +93,6 @@
             - accessTokenCookie: []
         responses:
             '204':
-                description: Successfully deleted the API key
+                description: Successfully deleted the API key. No content is returned.
             '500':
                 $ref: '../../components/responses/internal-server-error.yaml'
-
-
-

backend/openapi/paths/internal/global-preferences.yaml

@@ -45,7 +45,7 @@
         operationId: testWebhookUrl
         summary: Test webhook URL
         description: >
-            Tests the provided webhook URL to ensure it is reachable and valid.
+            Tests the provided webhook URL to ensure it is valid and reachable.
         tags:
             - Internal API - Global Preferences
         requestBody:

backend/openapi/paths/internal/meetings.yaml

@@ -2,8 +2,8 @@
     delete:
         operationId: endMeeting
         summary: End a meeting
-        description: >
+        description: |
-            Ends a meeting in an OpenVidu Meet room. This will stop all recordings and disconnect all participants.
+            Ends the current meeting in an OpenVidu Meet room. This will stop all recordings and disconnect all participants.
 
             This endpoint is idempotent. If the meeting is already ended, it will return a success response without any action.
         tags:
@@ -29,9 +29,9 @@
 /meetings/{roomId}/participants/{participantName}:
     delete:
         operationId: disconnectParticipant
-        summary: Delete a participant from a meeting
+        summary: Kick a participant from a meeting
         description: >
-            Deletes a participant from an OpenVidu Meet room. This will disconnect the participant from the meeting.
+            Kicks a participant from the current meeting in an OpenVidu Meet room.
         tags:
             - Internal API - Meetings
         security:

backend/openapi/paths/internal/participants.yaml

@@ -1,7 +1,7 @@
 /participants/token:
     post:
         operationId: generateParticipantToken
-        summary: Generate a token for a participant
+        summary: Generate token for participant
         description: >
             Generates a token for a participant to join an OpenVidu Meet room.
         tags:
@@ -30,7 +30,7 @@
 /participants/token/refresh:
     post:
         operationId: refreshParticipantToken
-        summary: Refresh a token for a participant
+        summary: Refresh token for participant
         description: >
             Refresh a token for a participant in an OpenVidu Meet room.
         tags:

backend/openapi/paths/internal/recordings.yaml

@@ -35,9 +35,10 @@
     post:
         operationId: stopRecording
         summary: Stop a recording
-        description: >
+        description: |
             Stops a recording with the specified recording ID.
-            The recording must be in an `ACTIVE` state; otherwise, a 409 error is returned.
+
+            > **Note:** The recording must be in an `ACTIVE` state; otherwise, a 409 error is returned.
         tags:
             - Internal API - Recordings
         security:

backend/openapi/paths/internal/rooms.yaml

@@ -106,9 +106,10 @@
     get:
         operationId: getRoomRoleAndPermissions
         summary: Get room role and permissions
-        description: >
+        description: |
             Retrieves the role and associated permissions that a participant will have in a specified OpenVidu Meet room
             when using the URL thant contains the given secret value.
+
             This endpoint is useful for checking the participant's role and permissions before joining the room.
         tags:
             - Internal API - Rooms

backend/openapi/paths/recordings.yaml

@@ -2,12 +2,12 @@
     get:
         operationId: getRecordings
         summary: Get all recordings
-        description: >
+        description: |
             Retrieves a paginated list of all recordings available in the system.
             You can apply filters to narrow down the results based on specific criteria.
 
             > **Note:** If this endpoint is called using the `recordingTokenCookie` authentication method,
-            the `roomId` filter will be ignored and only recordings associated with the room included in the token will be returned.
+            > the `roomId` filter will be ignored and only recordings associated with the room included in the token will be returned.
         tags:
             - OpenVidu Meet - Recordings
         security:
@@ -15,27 +15,7 @@
             - accessTokenCookie: []
             - recordingTokenCookie: []
         parameters:
-            # - name: status
+            # - $ref: '../components/parameters/recording-status.yaml'
-            #   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/recording-fields.yaml'
             - $ref: '../components/parameters/room-id-query.yaml'
             - $ref: '../components/parameters/max-items.yaml'
@@ -55,12 +35,12 @@
     delete:
         operationId: bulkDeleteRecordings
         summary: Bulk delete recordings
-        description: >
+        description: |
             Deletes multiple recordings at once with the specified recording IDs.
 
             > **Note:** If this endpoint is called using the `recordingTokenCookie` authentication method,
-            all specified recordings must belong to the same room included in the token.
+            > all specified recordings must belong to the same room included in the token.
-            If a recording does not belong to that room, it will not be deleted.
+            > If a recording does not belong to that room, it will not be deleted.
         tags:
             - OpenVidu Meet - Recordings
         security:
@@ -89,13 +69,13 @@
     get:
         operationId: downloadRecordings
         summary: Download recordings
-        description: >
+        description: |
             Downloads multiple recordings as a ZIP file with the specified recording IDs.
             The ZIP file will contain all recordings in MP4 format.
 
             > **Note:** If this endpoint is called using the `recordingTokenCookie` authentication method,
-            all specified recordings must belong to the same room included in the token.
+            > all specified recordings must belong to the same room included in the token.
-            If a recording does not belong to that room, it will not be included in the ZIP file.
+            > If a recording does not belong to that room, it will not be included in the ZIP file.
         tags:
             - OpenVidu Meet - Recordings
         security:
@@ -145,6 +125,7 @@
             - recordingTokenCookie: []
         parameters:
             - $ref: '../components/parameters/recording-id.yaml'
+            - $ref: '../components/parameters/recording-secret.yaml'
         responses:
             '200':
                 $ref: '../components/responses/success-get-recording.yaml'
@@ -163,9 +144,11 @@
     delete:
         operationId: deleteRecording
         summary: Delete a recording
-        description: >
+        description: |
-            Deletes a recording with the specified recording.
+            Deletes a recording with the specified recording ID.
-            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`).
+
+            > ⚠️ **Note:** The recording will only be deleted if it exists and is not in progress
+            > (i.e., not in a state such as `ACTIVE`, `STARTING`, or `ENDING`).
         tags:
             - OpenVidu Meet - Recordings
         security:
@@ -193,9 +176,10 @@
     get:
         operationId: getRecordingMedia
         summary: Get recording media
-        description: >
+        description: |
             Retrieves the media of a recording with the specified recording ID.
             The media is returned in a binary format suitable for video playback.
+
             This endpoint supports range requests, allowing partial content retrieval
             for video playback without downloading the entire file.
         tags:
@@ -210,7 +194,7 @@
             - $ref: '../components/parameters/recording-range.yaml'
         responses:
             '200':
-                description: Successfully streaming the full recording
+                description: Successfully retrieved the full recording media
                 headers:
                     Accept-Ranges:
                         $ref: '../components/headers/accept-ranges.yaml'
@@ -224,7 +208,7 @@
                             type: string
                             format: binary
             '206':
-                description: Partial content streaming based on byte range
+                description: Successfully retrieved a partial range of the recording media
                 headers:
                     Accept-Ranges:
                         $ref: '../components/headers/accept-ranges.yaml'
@@ -256,8 +240,8 @@
                         schema:
                             $ref: '../components/schemas/error.yaml'
                         example:
-                            code: 416
+                            error: Recording Error
-                            message: 'Requested range not satisfiable'
+                            message: 'Recording "room-123--EG_XYZ--XX445" range not satisfiable. File size: 123456789'
             '422':
                 $ref: '../components/responses/validation-error.yaml'
             '500':
@@ -266,9 +250,10 @@
     get:
         operationId: getRecordingUrl
         summary: Get recording URL
-        description: >
+        description: |
             Retrieves the URL of a recording with the specified recording ID.
             This URL is intended to be shared with people who do not have direct access to the recording.
+
             It can be configured to be accessible by anyone (public access) or restricted to authenticated users only, 
             depending on the `privateAccess` query parameter.
         tags:

backend/openapi/paths/rooms.yaml

@@ -3,7 +3,7 @@
         operationId: createRoom
         summary: Create a room
         description: >
-            Creates a new OpenVidu Meet room with the specified expiration date.
+            Creates a new OpenVidu Meet room.
             The room will be available for participants to join using the generated URLs.
         tags:
             - OpenVidu Meet - Room
@@ -29,6 +29,7 @@
         summary: Get all rooms
         description: >
             Retrieves a paginated list of all rooms available in the system.
+            You can apply filters to narrow down the results based on specific criteria.
         tags:
             - OpenVidu Meet - Room
         security:
@@ -53,7 +54,7 @@
     delete:
         operationId: bulkDeleteRooms
         summary: Bulk delete rooms
-        description: >
+        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
@@ -120,7 +121,7 @@
     delete:
         operationId: deleteRoom
         summary: Delete a room
-        description: >
+        description: |
             Deletes an OpenVidu Meet room with the specified room ID.
 
             If the room has active participants, it will be marked for deletion

backend/openapi/webhooks/webhooks.yaml

@@ -1,7 +1,7 @@
 recordingStarted:
     post:
         summary: Recording started
-        description: >
+        description: |
             This webhook is triggered when a recording starts.
 
             > The recording can be in the `STARTING` status for a few seconds before it becomes `ACTIVE`.
@@ -31,7 +31,7 @@ recordingStarted:
                                           - properties:
                                                 status:
                                                     type: string
-                                                    enum: [STARTING]
+                                                    enum: [STARTING, ACTIVE]
                                                     description: The status of the recording.
                                                     example: STARTING
         responses:
@@ -41,7 +41,7 @@ recordingStarted:
 recordingUpdated:
     post:
         summary: Recording updated
-        description: >
+        description: |
             This webhook is triggered when a recording update occurs.
 
             > This update can be due to a change in the recording status (e.g., from `STARTING` to `ACTIVE`).
@@ -81,10 +81,11 @@ recordingUpdated:
 recordingEnded:
     post:
         summary: Recording ended
-        description: >
+        description: |
             This webhook is triggered when a recording ends.
 
-            > The recording can end due to various reasons, such as the user stopping the recording or the recording reaching its maximum duration.
+            > The recording can end due to various reasons, such as the user stopping the recording
+            > or the recording reaching its maximum duration.
         operationId: recordingEndedWebhook
         parameters:
             - $ref: ../components/parameters/x-timestamp.yaml
@@ -112,7 +113,7 @@ recordingEnded:
                                           - properties:
                                                 status:
                                                     type: string
-                                                    enum: [COMPLETE, FAILED, ABORTED, LIMITED_REACHED]
+                                                    enum: [COMPLETE, FAILED, ABORTED, LIMIT_REACHED]
                                                     description: The status of the recording.
                                                     example: COMPLETE
                                                 endDate: