openapi: 3.0.1 info: version: v1 title: OpenVidu Meet REST API description: > The OpenVidu Meet REST API allows seamless integration of OpenVidu Meet rooms into your application. This REST API provides endpoints to manage rooms and recordings in OpenVidu Meet. termsOfService: https://openvidu.io/conditions/terms-of-service/ contact: name: OpenVidu email: commercial@openvidu.io url: https://openvidu.io/support/ servers: - url: http://localhost:6080/meet/api/v1 description: Development server tags: - name: OpenVidu Meet - Room description: Operations related to managing OpenVidu Meet rooms - name: OpenVidu Meet - Recordings description: Operations related to managing OpenVidu Meet recordings paths: /rooms: post: operationId: createRoom summary: Create a room description: > Creates a new OpenVidu Meet room with the specified expiration date. The room will be available for participants to join using the generated URLs. tags: - OpenVidu Meet - Room security: - apiKeyInHeader: [] - accessTokenCookie: [] requestBody: description: Room creation details content: application/json: schema: $ref: '#/components/schemas/MeetRoomOptions' examples: default: value: expirationDate: 1620000000000 roomIdPrefix: 'room' # maxParticipants: 10 preferences: chatPreferences: enabled: true recordingPreferences: enabled: true virtualBackgroundPreferences: enabled: true responses: '200': description: Successfully created the OpenVidu Meet room content: application/json: schema: $ref: '#/components/schemas/MeetRoom' '401': description: Unauthorized — The API key is missing or invalid, or the access token is missing or invalid when using cookie-based authentication content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Unauthorized' '403': description: Forbidden — The user authenticated with the access token does not have enough permissions content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Insufficient permissions to access this resource' '422': description: Unprocessable Entity — The request body is invalid content: application/json: schema: type: object properties: error: type: string example: 'Unprocessable Entity' message: type: string example: 'Invalid request body' details: type: array items: type: object properties: field: type: string example: 'expirationDate' message: type: string example: 'Expected number, received string' example: error: 'Unprocessable Entity' message: 'Invalid request body' details: - field: 'expirationDate' message: 'Expected number, received string' - field: 'roomIdPrefix' message: 'Expected string, received number' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Internal server error' get: operationId: getRooms summary: Get all rooms description: > Retrieves a paginated list of all rooms available in the system. tags: - OpenVidu Meet - Room security: - apiKeyInHeader: [] - accessTokenCookie: [] parameters: - name: maxItems in: query required: false description: The number of rooms per page (default is 10). Maximum is 100. schema: type: integer default: 10 - name: nextPageToken in: query required: false description: The token to retrieve the next page of rooms. schema: type: string responses: '200': description: Successfully retrieved the list of OpenVidu Meet rooms content: application/json: schema: type: object properties: rooms: type: array items: $ref: '#/components/schemas/MeetRoom' pagination: type: object properties: isTruncated: type: boolean description: Indicates if there are more rooms to retrieve. nextPageToken: type: string description: The token to retrieve the next page of rooms. '401': description: Unauthorized — The API key is missing or invalid, or the access token is missing or invalid when using cookie-based authentication content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Unauthorized' '403': description: Forbidden — The user authenticated with the access token does not have enough permissions content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Insufficient permissions to access this resource' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 500 message: 'Internal server error' /rooms/{roomId}: get: operationId: getRoom summary: Get a room description: > Retrieves the details of an OpenVidu Meet room with the specified room ID. tags: - OpenVidu Meet - Room security: - apiKeyInHeader: [] - accessTokenCookie: [] - participantTokenCookie: [] parameters: - name: roomId in: path required: true description: The unique identifier of the room to retrieve schema: type: string example: 'room-123' responses: '200': description: Successfully retrieved the room content: application/json: schema: $ref: '#/components/schemas/MeetRoom' '401': description: Unauthorized — The API key is missing or invalid, or the access/participant token is missing or invalid when using cookie-based authentication 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: Room not found content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 404 message: 'Room not found' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 500 message: 'Internal server error' put: operationId: updateRoom summary: Update a room description: > Updates the preferences of an OpenVidu Meet room with the specified room ID. tags: - OpenVidu Meet - Room security: - apiKeyInHeader: [] - accessTokenCookie: [] parameters: - name: roomId in: path required: true description: The unique identifier of the room to update schema: type: string example: 'room-123' requestBody: description: Room update details content: application/json: schema: $ref: '#/components/schemas/MeetRoomPreferences' examples: default: value: preferences: chatPreferences: enabled: true recordingPreferences: enabled: true virtualBackgroundPreferences: enabled: true responses: '200': description: Successfully updated the OpenVidu Meet room content: application/json: schema: $ref: '#/components/schemas/MeetRoom' '401': description: Unauthorized — The API key is missing or invalid, or the access token is missing or invalid when using cookie-based authentication content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Unauthorized' '403': description: Forbidden — The user authenticated with the access token does not have enough permissions content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Insufficient permissions to access this resource' '404': description: Room not found content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 404 message: 'Room not found' '422': description: Unprocessable Entity — The request body is invalid content: application/json: schema: type: object properties: error: type: string example: 'Unprocessable Entity' message: type: string example: 'Invalid request body' details: type: array items: type: object properties: field: type: string example: 'recordingPreferences' message: type: string example: 'Expected boolean, received string' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 500 message: 'Internal server error' delete: operationId: deleteRoom summary: Delete a room description: > Deletes an OpenVidu Meet room with the specified room ID. The room with participants will be closed and all participants will be disconnected. The room will be deleted from the system and will no longer be available. tags: - OpenVidu Meet - Room security: - apiKeyInHeader: [] - accessTokenCookie: [] parameters: - name: roomId in: path required: true description: The unique identifier of the room to delete schema: type: string example: 'room-123' responses: '204': description: Successfully deleted the OpenVidu Meet room '401': description: Unauthorized — The API key is missing or invalid, or the access token is missing or invalid when using cookie-based authentication content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Unauthorized' '403': description: Forbidden — The user authenticated with the access token does not have enough permissions content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Insufficient permissions to access this resource' '404': description: Room not found content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 404 message: 'Room not found' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 500 message: 'Internal server error' /recordings: post: operationId: createRecording summary: Start a recording description: > Start a new recording for an OpenVidu Meet room with the specified room ID. tags: - OpenVidu Meet - Recordings security: - participantTokenCookie: [] requestBody: description: Recording details content: application/json: schema: type: object required: - roomId properties: roomId: type: string example: 'room-123' description: > The unique identifier of the room to record. responses: '200': description: Successfully created the OpenVidu Meet recording content: application/json: schema: $ref: '#/components/schemas/MeetRecordingStart' '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 — Recording is not enabled for the room or the participant authenticated with the access token has not enough permissions content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Insufficient permissions to access this resource' '404': description: Room not found content: application/json: schema: $ref: '#/components/schemas/Error' example: name: 'Room Error' message: 'The room "room-123" does not exist' '409': description: Conflict — The room is already being recorded content: application/json: schema: $ref: '#/components/schemas/Error' example: name: 'Recording Error' message: 'The room "room-123" is already being recorded' '422': description: Unprocessable Entity — The request body is invalid content: application/json: schema: type: object properties: error: type: string example: 'Unprocessable Entity' message: type: string example: 'Invalid request body' details: type: array items: type: object properties: field: type: string example: 'roomId' message: type: string example: 'roomId not found' example: error: 'Unprocessable Entity' message: 'Invalid request body' details: - field: 'roomId' example: 'roomId not found' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' example: name: 'Unexpected Error' message: 'Something went wrong' get: operationId: getRecordings summary: Get all recordings description: > Retrieves a paginated list of all recordings available in the system. You can apply filters to narrow down the results based on specific criteria. tags: - OpenVidu Meet - Recordings security: - apiKeyInHeader: [] - accessTokenCookie: [] parameters: # - name: status # in: query # required: false # description: | # Filter recordings by their status. # Possible values: # - `STARTING` # - `ACTIVE` # - `ENDING` # - `COMPLETE` # - `FAILED` # - `ABORTED` # - `LIMITED_REACHED` # You can provide multiple statuses as a comma-separated list (e.g., `status=ACTIVE,FAILED`). # If not specified, recordings with any status will be returned. # > ⚠️ **Note:** Using this filter may impact performance for large datasets. # schema: # type: string - name: roomId in: query required: false description: | The unique identifier of the room for which you want to retrieve recordings. If not provided, recordings from all rooms will be returned. schema: type: string - name: maxItems in: query required: false description: The number of recordings per page (default is 10). Maximum is 100. schema: type: integer default: 10 - name: nextPageToken in: query required: false description: The token to retrieve the next page of recordings. schema: type: string responses: '200': description: Successfully retrieved the recording list content: application/json: schema: type: object properties: recordings: type: array items: $ref: '#/components/schemas/MeetRecording' pagination: type: object properties: isTruncated: type: boolean description: Indicates if there are more recordings to retrieve. nextPageToken: type: string description: The token to retrieve the next page of recordings. '401': description: Unauthorized — The API key is missing or invalid, or the access token is missing or invalid when using cookie-based authentication content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Unauthorized' '403': description: Forbidden — The user authenticated with the access token does not have enough permissions content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Insufficient permissions to access this resource' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 500 message: 'Internal server error' delete: operationId: bulkDeleteRecordings summary: Bulk delete recordings description: > Deletes multiple recordings at once with the specified recording IDs. tags: - OpenVidu Meet - Recordings security: - apiKeyInHeader: [] - accessTokenCookie: [] parameters: - name: recordingIds in: query required: true description: | The unique IDs of the recordings to delete. You can provide multiple recording IDs as a comma-separated list (e.g., `recordingIds=room-123--EG_XYZ--XX445,room-123--EG_XYZ--XX446`). schema: type: string responses: '200': description: Bulk deletion completed. Includes lists of successfully deleted IDs and errors. content: application/json: schema: type: object properties: deleted: type: array items: type: string description: List of successfully deleted recording IDs. example: - 'room-123--EG_XYZ--XX445' - 'room-123--EG_XYZ--XX446' notDeleted: type: array description: List of recordings that could not be deleted along with the corresponding error messages. items: type: object properties: recordingId: type: string description: The unique identifier of the recording that was not deleted. example: 'room-123--EG_XYZ--XX447' error: type: string description: A message explaining why the deletion failed. example: 'Recording not found' '401': description: Unauthorized — The API key is missing or invalid, or the access token is missing or invalid when using cookie-based authentication content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Unauthorized' '403': description: Forbidden — The user authenticated with the access token does not have enough permissions content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Insufficient permissions to access this resource' '422': description: Unprocessable Entity — The request body is invalid content: application/json: schema: type: object properties: error: type: string example: 'Unprocessable Entity' message: type: string example: 'Invalid request body' details: type: array items: type: object properties: field: type: string example: 'recordingIds' message: type: string example: 'recordingIds not found' example: error: 'Unprocessable Entity' message: 'Invalid request body' details: - field: 'recordingIds' example: 'recordingIds not found' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' example: name: 'Unexpected Error' message: 'Something went wrong' /recordings/{recordingId}: put: operationId: stopRecording summary: Stop a recording description: > Stops a recording with the specified recording ID. The recording must be in an `ACTIVE` state; otherwise, a 409 error is returned. tags: - OpenVidu Meet - Recordings security: - participantTokenCookie: [] parameters: - name: recordingId in: path required: true description: The unique identifier of the recording to stop. schema: type: string example: 'room-123--EG_XYZ--XX445' responses: '200': description: Accepted — The stop request has been accepted. The endpoint to retrieve the recording is provided in the Location header. headers: Location: description: The URL to retrieve the recording details schema: type: string example: 'https://openvidu.example.com/meet/api/v1/recordings/room-123--EG_XYZ--XX445' content: application/json: schema: $ref: '#/components/schemas/MeetRecording' '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 — Recording is not enabled for the room or the participant authenticated with the access token has not enough permissions content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Insufficient permissions to access this resource' '404': description: Recording not found content: application/json: schema: $ref: '#/components/schemas/Error' example: name: 'Recording Error' message: 'Recording "room-123--EG_XYZ--XX445" not found' '409': description: Conflict — The recording is already stopped. content: application/json: schema: $ref: '#/components/schemas/Error' example: name: 'Recording Error' message: 'Recording "room-123--EG_XYZ--XX445" is already stopped' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' example: name: 'Unexpected Error' message: 'Something went wrong' get: operationId: getRecording summary: Get a recording description: > Retrieves the details of a recording with the specified recording ID. tags: - OpenVidu Meet - Recordings security: - apiKeyInHeader: [] - accessTokenCookie: [] parameters: - name: recordingId in: path required: true description: The unique identifier of the recording to retrieve schema: type: string example: 'room-123--EG_XYZ--XX445' responses: '200': description: Successfully retrieved the recording. content: application/json: schema: $ref: '#/components/schemas/MeetRecording' '401': description: Unauthorized — The API key is missing or invalid, or the access token is missing or invalid when using cookie-based authentication content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Unauthorized' '403': description: Forbidden — The user authenticated with the access token does not have enough permissions content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Insufficient permissions to access this resource' '404': description: Recording not found — The recording with the specified ID was not found content: application/json: schema: $ref: '#/components/schemas/Error' example: name: 'Recording Error' message: 'Recording "room-123--EG_XYZ--XX445" not found' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' example: name: 'Unexpected Error' message: 'Something went wrong' delete: operationId: deleteRecording summary: Delete a recording description: > Deletes a recording with the specified recording. The recording will only be deleted if it exists and is not in progress (i.e., not in a state such as `ACTIVE`, `STARTING`, or `ENDING`). tags: - OpenVidu Meet - Recordings security: - apiKeyInHeader: [] - accessTokenCookie: [] parameters: - name: recordingId in: path required: true description: The unique identifier of the recording to delete. schema: type: string example: 'room-123--EG_XYZ--XX445' responses: '204': description: Recording successfully deleted. No content is returned. '401': description: Unauthorized — The API key is missing or invalid, or the access token is missing or invalid when using cookie-based authentication content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Unauthorized' '403': description: Forbidden — The user authenticated with the access token does not have enough permissions content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Insufficient permissions to access this resource' '404': description: Recording not found content: application/json: schema: $ref: '#/components/schemas/Error' example: name: 'Recording Error' message: 'Recording "room-123--EG_XYZ--XX445" not found' '409': description: Conflict — The recording is in progress content: application/json: schema: $ref: '#/components/schemas/Error' example: name: 'Recording Error' message: 'Recording "room-123--EG_XYZ--XX445" is in progress' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' example: name: 'Unexpected Error' message: 'Something went wrong' components: securitySchemes: apiKeyInHeader: type: apiKey name: X-API-KEY in: header description: > The API key to authenticate the request. This key is required to access the OpenVidu Meet API. accessTokenCookie: type: apiKey name: OvMeetAccessToken in: cookie description: > The JWT token to authenticate the request in case of consuming the API from the OpenVidu Meet frontend. participantTokenCookie: type: apiKey name: OvMeetParticipantToken in: cookie description: > The JWT token to authenticate the participant when entering the room. schemas: MeetRoom: type: object properties: roomId: type: string example: 'room-123' description: > The unique identifier of the room. This ID is generated when the room is created. roomIdPrefix: type: string example: 'room' description: > The prefix used for the room ID. This prefix is used to generate the room ID. creationDate: type: number example: 1620000000000 description: > The creation date of the room in milliseconds since the Unix epoch. expirationDate: type: number example: 1620000000000 description: > The expiration date of the room in milliseconds since the Unix epoch. After this date, the room will be closed and no new participants will be allowed to join. preferences: $ref: '#/components/schemas/MeetRoomPreferences' description: > The preferences for the room. # maxParticipants: # type: integer # example: 10 # description: > # The maximum number of participants allowed in the room. If the number of participants exceeds # this limit, new participants will not be allowed to join. moderatorURL: type: string example: 'http://localhost:6080/room/room-123/?secret=tok_123456' description: > The URL for the moderator to join the room. The moderator has special permissions to manage the room and participants. publisherURL: type: string example: 'http://localhost:6080/room/room-123/?secret=tok_123456' description: > The URL for the publisher to join the room. The publisher has permissions to publish audio and video streams to the room. MeetRoomOptions: type: object required: - expirationDate properties: expirationDate: type: number example: 1620000000000 description: > The expiration date of the room in milliseconds since the Unix epoch. After this date, the room will be closed and no new participants will be allowed to join. roomIdPrefix: type: string example: 'room' description: > A prefix to be used for the room ID. The room ID will be generated by concatenating this prefix with a unique identifier. # maxParticipants: # type: integer # example: 10 # description: > # The maximum number of participants allowed in the room. If the number of participants exceeds # this limit, new participants will not be allowed to join. preferences: $ref: '#/components/schemas/MeetRoomPreferences' description: > The preferences for the room. These preferences will be applied to the room when it is created. MeetRoomPreferences: type: object properties: chatPreferences: $ref: '#/components/schemas/MeetChatPreferences' description: > Preferences for the chat feature in the room. recordingPreferences: $ref: '#/components/schemas/MeetRecordingPreferences' description: > Preferences for recording the room. virtualBackgroundPreferences: $ref: '#/components/schemas/MeetVirtualBackgroundPreferences' description: > Preferences for virtual background in the room. MeetChatPreferences: type: object properties: enabled: type: boolean default: true example: true description: > If true, the room will be allowed to send and receive chat messages. MeetRecordingPreferences: type: object properties: enabled: type: boolean default: true example: true description: > If true, the room will be allowed to record the video of the participants. MeetVirtualBackgroundPreferences: type: object properties: enabled: type: boolean default: true example: true description: > If true, the room will be allowed to use virtual background. MeetRecordingBase: type: object properties: recordingId: type: string example: 'room-123--EG_XYZ--XX445' description: The unique identifier of the recording. roomId: type: string example: 'room-123' description: The ID of the room where the recording was made. # outputMode: # type: string # example: 'COMPOSED' # description: > # The output mode of the recording. Possible value: "COMPOSED". status: type: string example: 'ACTIVE' description: > The status of the recording. Possible values: - STARTING - ACTIVE - ENDING - COMPLETE - FAILED - ABORTED - LIMITED_REACHED filename: type: string example: 'http://localhost:6080/meet/OpenVidu-123456/?secret=tok_123456' description: > The URL for the publisher to join the room. The publisher has permissions to publish audio and video streams to the room. viewerURL: type: string example: 'http://localhost:6080/meet/OpenVidu-123456/?secret=tok_123456' description: > The URL for the viewer to join the room. The viewer has read-only permissions to watch the room and participants. MeetRecording: allOf: - $ref: '#/components/schemas/MeetRecordingBase' - type: object properties: endDate: type: number example: 1620000000000 description: The date when the recording was stopped (milliseconds since the Unix epoch). duration: type: number example: 3600 description: The duration of the recording in seconds. size: type: number example: 1024 description: The size of the recording file in bytes. errorCode: type: number example: 100 description: The error code of the recording. error: type: string description: The error message of the recording. nullable: true details: type: string example: 'Stopped using API' description: Additional details about the recording. MeetRecordingStart: $ref: '#/components/schemas/MeetRecordingBase' Error: type: object required: - message properties: name: type: string message: type: string