openapi: 3.0.1 info: version: v1 title: OpenVidu Meet API description: > The OpenVidu Embedded API allows seamless integration of OpenVidu Meet rooms into your application. This API provides endpoints to manage rooms, generate secure access URLs, and configure room preferences. 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 # - name: OpenVidu Meet - Participant # description: Operations related to managing participants in OpenVidu Meet rooms # - name: Internal API - Room # description: Operations related to managing OpenVidu Meet rooms - name: Internal API - Participant description: Operations related to managing participants in OpenVidu Meet rooms - name: Internal API - Recordings description: Operations related to managing OpenVidu Meet recordings paths: /rooms: post: operationId: createRoom summary: Create a new OpenVidu Meet 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: [] requestBody: description: Room configuration options content: application/json: schema: $ref: '#/components/schemas/OpenViduMeetRoomOptions' examples: default: value: expirationDate: 1620000000000 roomNamePrefix: 'OpenVidu' maxParticipants: 10 preferences: chatPreferences: enabled: true recordingPreferences: enabled: true virtualBackgroundPreferences: enabled: true withNestedAttributes: summary: Room creation with nested preferences value: expirationDate: 1620000000000 roomNamePrefix: 'OpenVidu' maxParticipants: 15 preferences: chatPreferences: enabled: true recordingPreferences: enabled: false virtualBackgroundPreferences: enabled: true responses: '200': description: Successfully generated the OpenVidu Meet room content: application/json: schema: $ref: '#/components/schemas/OpenViduMeetRoom' '401': description: Unauthorized — The API key is missing or invalid content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Unauthorized' '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: 'roomNamePrefix' message: 'Expected string, received number' '415': description: 'Unsupported Media Type' content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Unsupported Media Type' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Internal server error' get: operationId: getRooms summary: Get a list of OpenVidu Meet rooms description: > Retrieves a list of OpenVidu Meet rooms that are currently active. You can specify a comma-separated list of fields (using the "fields" query parameter) to include only those properties in the response (e.g. roomName, preferences). tags: - OpenVidu Meet - Room security: - apiKeyInHeader: [] parameters: - name: fields in: query required: false description: | Comma-separated list of fields to include in the response. For example: "roomName,preferences". Only allowed fields will be returned. schema: type: string responses: '200': description: Successfully retrieved the list of OpenVidu Meet rooms content: application/json: schema: type: array items: $ref: '#/components/schemas/OpenViduMeetRoom' '401': description: Unauthorized — The API key is missing or invalid content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Unauthorized' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 500 message: 'Internal server error' /rooms/{roomName}: get: operationId: getRoom summary: Get details of an OpenVidu Meet room description: > Retrieves the details of an OpenVidu Meet room with the specified room name. Additionally, you can specify a comma-separated list of fields (using the "fields" query parameter) to include only those properties in the response (e.g. roomName, preferences). tags: - OpenVidu Meet - Room security: - apiKeyInHeader: [] parameters: - name: roomName in: path required: true description: The name of the room to retrieve schema: type: string - name: fields in: query required: false description: | Comma-separated list of fields to include in the response. For example: "roomName,preferences". Only allowed fields will be returned. schema: type: string responses: '200': description: Successfully retrieved the OpenVidu Meet room content: application/json: schema: $ref: '#/components/schemas/OpenViduMeetRoom' '401': description: Unauthorized — The API key is missing or invalid content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Unauthorized' '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 an OpenVidu Meet room description: > Updates the preferences of an OpenVidu Meet room with the specified room name. tags: - OpenVidu Meet - Room security: - apiKeyInHeader: [] parameters: - name: roomName in: path required: true description: The name of the room to update schema: type: string requestBody: description: Room preferences to update content: application/json: schema: $ref: '#/components/schemas/RoomPreferences' 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/OpenViduMeetRoom' '401': description: Unauthorized — The API key is missing or invalid content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Unauthorized' '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' delete: operationId: deleteRoom summary: Delete an OpenVidu Meet room description: > Deletes an OpenVidu Meet room with the specified room name. tags: - OpenVidu Meet - Room security: - apiKeyInHeader: [] parameters: - name: roomName in: path required: true description: The name of the room to delete schema: type: string responses: '204': description: Successfully deleted the OpenVidu Meet room '401': description: Unauthorized — The API key is missing or invalid content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Unauthorized' '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: Create a new OpenVidu Meet recording description: > Creates a new OpenVidu Meet recording for the specified room. tags: - OpenVidu Meet - Recordings security: - apiKeyInHeader: [] requestBody: description: Recording details content: application/json: schema: type: object required: - roomName properties: roomName: type: string example: 'OpenVidu-123456' description: > The name of the room to record. responses: '200': description: Successfully created the OpenVidu Meet recording content: application/json: schema: $ref: '#/components/schemas/OpenViduMeetRecording' '401': description: Unauthorized — The API key is missing or invalid content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Unauthorized' '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' get: operationId: getRecordings summary: Get a list of OpenVidu Meet recordings description: > Retrieves a list of OpenVidu Meet recordings that are currently available. tags: - OpenVidu Meet - Recordings security: - apiKeyInHeader: [] responses: '200': description: Successfully retrieved the list of OpenVidu Meet recordings content: application/json: schema: type: array items: $ref: '#/components/schemas/OpenViduMeetRecording' '401': description: Unauthorized — The API key is missing or invalid content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Unauthorized' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 500 message: 'Internal server error' delete: operationId: deleteMultipleRecordings summary: Delete multiples OpenVidu Meet recordings description: > Deletes multiples OpenVidu Meet recordings with the specified recording IDs. tags: - OpenVidu Meet - Recordings security: - apiKeyInHeader: [] requestBody: description: Recording IDs to delete required: true content: application/json: schema: type: object required: - recordingIds properties: recordingIds: type: array items: type: string example: ['recording_123456', 'recording_123457'] description: > The IDs of the recordings to delete. responses: '204': description: Successfully deleted the OpenVidu Meet recordings '401': description: Unauthorized — The API key is missing or invalid content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Unauthorized' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 500 message: 'Internal server error' /recordings/{recordingId}: put: operationId: stopRecording summary: Stop an OpenVidu Meet recording description: > Stops an OpenVidu Meet recording with the specified recording ID. tags: - OpenVidu Meet - Recordings security: - apiKeyInHeader: [] parameters: - name: recordingId in: path required: true description: The ID of the recording to stop schema: type: string responses: '204': description: Successfully stopped the OpenVidu Meet recording '401': description: Unauthorized — The API key is missing or invalid content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Unauthorized' '404': description: Recording not found content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 404 message: 'Recording not found' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 500 message: 'Internal server error' get: operationId: getRecording summary: Get details of an OpenVidu Meet recording description: > Retrieves the details of an OpenVidu Meet recording with the specified recording ID. tags: - OpenVidu Meet - Recordings security: - apiKeyInHeader: [] parameters: - name: recordingId in: path required: true description: The ID of the recording to retrieve schema: type: string responses: '200': description: Successfully retrieved the OpenVidu Meet recording content: application/json: schema: $ref: '#/components/schemas/OpenViduMeetRecording' '401': description: Unauthorized — The API key is missing or invalid content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Unauthorized' '404': description: Recording not found content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 404 message: 'Recording not found' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 500 message: 'Internal server error' delete: operationId: deleteRecording summary: Delete an OpenVidu Meet recording description: > Deletes an OpenVidu Meet recording with the specified recording ID. tags: - OpenVidu Meet - Recordings security: - apiKeyInHeader: [] parameters: - name: recordingId in: path required: true description: The ID of the recording to delete schema: type: string responses: '204': description: Successfully deleted the OpenVidu Meet recording '401': description: Unauthorized — The API key is missing or invalid content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Unauthorized' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 500 message: 'Internal server error' /recordings/{recordingId}/stream: get: operationId: getRecordingStream summary: Stream an OpenVidu Meet recording description: > Streams the OpenVidu Meet recording with the specified recording ID. This endpoint supports range requests, allowing partial content retrieval for video playback without downloading the entire file. tags: - Internal API - Recordings security: - apiKeyInHeader: [] parameters: - name: recordingId in: path required: true description: The ID of the recording to stream schema: type: string - name: Range in: header required: false description: > Byte range for partial content retrieval. Example: `bytes=0-1023` to request the first 1024 bytes of the file. schema: type: string responses: '200': description: Successfully streaming the full recording headers: Accept-Ranges: description: Indicates that byte-range requests are supported schema: type: string Content-Length: description: The total file size in bytes schema: type: integer content: video/mp4: schema: type: string format: binary '206': description: Partial content streaming based on byte range headers: Accept-Ranges: description: Indicates that byte-range requests are supported schema: type: string Content-Range: description: Specifies the range of bytes being sent schema: type: string Content-Length: description: The length of the partial content in bytes schema: type: integer content: video/mp4: schema: type: string format: binary '400': description: Bad Request — Invalid range header format content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 400 message: 'Invalid Range header' '401': description: Unauthorized — The API key is missing or invalid content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Unauthorized' '404': description: Recording not found content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 404 message: 'Recording not found' '416': description: Requested range not satisfiable content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 416 message: 'Requested range not satisfiable' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 500 message: 'Internal server error' /participants/token: post: operationId: generateParticipantToken summary: Generate a token for a participant description: > Generates a token for a participant to join an OpenVidu Meet room. tags: - Internal API - Participant requestBody: description: Participant details content: application/json: schema: type: object required: - roomName - participantName - secret properties: roomName: type: string example: 'OpenVidu-123456' description: > The name of the room to join. participantName: type: string example: 'Alice' description: > The name of the participant. secret: type: string example: 'abc123456' description: > The secret token from the room Url responses: '200': description: Successfully generated the participant token content: application/json: schema: type: object properties: token: type: string example: 'token_123456' description: > The token to authenticate the participant. '404': description: Room not found content: application/json: schema: type: object properties: name: type: string example: 'Room not found' message: type: string example: 'The room does not exist' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Internal server error' /participants/{participantName}: delete: operationId: disconnectParticipant summary: Delete a participant from a room description: > Deletes a participant from an OpenVidu Meet room. tags: - Internal API - Participant security: - apiKeyInHeader: [] parameters: - name: participantName in: path required: true description: The name of the participant to delete schema: type: string - name: roomName in: query required: true description: The name of the room from which to delete the participant schema: type: string responses: '204': description: Successfully disconnect the participant '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: 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. jwtInCookie: type: apiKey name: OvMeetAccessToken in: cookie description: > The JWT token to authenticate the request in case of consuming the API from the OpenVidu Meet admin console. schemas: OpenViduMeetRoomOptions: 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. roomNamePrefix: type: string example: 'OpenVidu' description: > A prefix to be used for the room name. The room name will be generated by appending a random alphanumeric string to this prefix. 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/RoomPreferences' description: > The preferences for the room. RoomPreferences: type: object properties: chatPreferences: $ref: '#/components/schemas/ChatPreferences' description: > Preferences for the chat feature in the room. recordingPreferences: $ref: '#/components/schemas/RecordingPreferences' description: > Preferences for recording the room. virtualBackgroundPreferences: $ref: '#/components/schemas/VirtualBackgroundPreferences' description: > Preferences for virtual background in the room. ChatPreferences: type: object properties: enabled: type: boolean default: true example: true description: > If true, the room will be allowed to send and receive chat messages. RecordingPreferences: 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. VirtualBackgroundPreferences: type: object properties: enabled: type: boolean default: true example: true description: > If true, the room will be allowed to use virtual background. OpenViduMeetRoom: type: object properties: roomName: type: string example: 'OpenVidu-123456' description: > The name of the room. This name is generated by appending a random alphanumeric string to the room name prefix specified in the request. 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. roomNamePrefix: type: string example: 'OpenVidu' description: > The prefix used for the room name. The room name is generated by appending a random alphanumeric string to this prefix. preferences: $ref: '#/components/schemas/RoomPreferences' 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/meet/OpenVidu-123456/?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/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. OpenViduMeetRecording: type: object properties: id: type: string example: 'recording_123456' description: > The unique identifier of the recording. roomName: type: string example: 'OpenVidu-123456' description: > The name of the room where the recording was made. # roomId: # type: string # example: '123456' # description: > # The unique identifier of the room where the recording was made. outputMode: type: string example: 'COMPOSED' description: > The output mode of the recording. Possible values are "COMPOSED". status: type: string example: 'READY' description: > The status of the recording. Possible values are "STARTING", "STARTED", "STOPPING", "STOPPED", "FAILED" and "RECORDING". filename: type: string example: 'recording_123456.mp4' description: > The name of the recording file. startedAt: type: number example: 1620000000000 description: > The date when the recording was started in milliseconds since the Unix epoch. endedAt: type: number example: 1620000000000 description: > The date when the recording was stopped in 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. Error: type: object required: - message properties: message: type: string