761 lines
33 KiB
YAML
761 lines
33 KiB
YAML
openapi: 3.1.0
|
|
info:
|
|
title: OpenVidu Meet REST API
|
|
description: >
|
|
The OpenVidu Meet REST API provides a comprehensive set of endpoints for integrating real-time video
|
|
conferencing capabilities into your applications.
|
|
contact:
|
|
name: OpenVidu
|
|
email: commercial@openvidu.io
|
|
url: https://openvidu.io/support/
|
|
license:
|
|
name: Apache License 2.0
|
|
identifier: Apache-2.0
|
|
url: https://www.apache.org/licenses/LICENSE-2.0
|
|
version: v1
|
|
termsOfService: https://openvidu.io/conditions/terms-of-service/
|
|
|
|
servers:
|
|
- url: /meet/internal-api/v1
|
|
description: OpenVidu Meet Internal API
|
|
tags:
|
|
- name: Internal API - Authentication
|
|
description: Authentication operations
|
|
- name: Internal API - Rooms
|
|
description: Operations related to managing OpenVidu Meet rooms
|
|
- name: Internal API - Participant
|
|
description: Operations related to managing participants in OpenVidu Meet rooms
|
|
- name: Internal API - Recordings
|
|
description: Operations related to managing OpenVidu Meet recordings
|
|
|
|
paths:
|
|
/auth/login:
|
|
post:
|
|
operationId: loginUser
|
|
summary: Login to OpenVidu Meet
|
|
description: >
|
|
Authenticates a user and returns an access and refresh token in cookies.
|
|
tags:
|
|
- Internal API - Authentication
|
|
requestBody:
|
|
description: User credentials
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
username:
|
|
type: string
|
|
example: 'admin'
|
|
description: The username of the user.
|
|
password:
|
|
type: string
|
|
example: 'password123'
|
|
description: The password of the user.
|
|
responses:
|
|
'200':
|
|
description: Successfully logged in
|
|
headers:
|
|
Set-Cookie:
|
|
description: >
|
|
The cookie containing the access token.
|
|
This cookie is used to authenticate the user in subsequent requests.
|
|
schema:
|
|
type: string
|
|
example: 'OvMeetAccessToken=token_123456; Path=/; HttpOnly; SameSite=Strict'
|
|
Set-Cookie-Refresh:
|
|
description: >
|
|
The cookie containing the refresh token.
|
|
This cookie is used to refresh the access token when it expires.
|
|
schema:
|
|
type: string
|
|
example: 'OvMeetRefreshToken=token_123456; Path=/meet/internal-api/v1/auth; HttpOnly; SameSite=Strict'
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
example: 'Login succeeded'
|
|
'404':
|
|
description: Invalid credentials
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
message: 'Login failed. Invalid username or password'
|
|
'422':
|
|
description: Unprocessable Entity — The request body is invalid
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: 'Unprocessable Entity'
|
|
message:
|
|
type: string
|
|
example: 'Invalid request body'
|
|
details:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
field:
|
|
type: string
|
|
example: 'username'
|
|
message:
|
|
type: string
|
|
example: 'Username must be at least 4 characters long'
|
|
'500':
|
|
description: Internal server error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
message: 'Internal server error'
|
|
/auth/logout:
|
|
post:
|
|
operationId: logoutUser
|
|
summary: Logout from OpenVidu Meet
|
|
description: >
|
|
Logs out the user and clears the access and refresh tokens from cookies.
|
|
tags:
|
|
- Internal API - Authentication
|
|
responses:
|
|
'200':
|
|
description: Successfully logged out
|
|
headers:
|
|
Set-Cookie:
|
|
schema:
|
|
type: string
|
|
example: 'OvMeetAccessToken=; Path=/; HttpOnly; SameSite=Strict'
|
|
Set-Cookie-Refresh:
|
|
schema:
|
|
type: string
|
|
example: 'OvMeetRefreshToken=; Path=/meet/internal-api/v1/auth; HttpOnly; SameSite=Strict'
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
example: 'Logout successful'
|
|
/auth/refresh:
|
|
post:
|
|
operationId: refreshAccessToken
|
|
summary: Refresh the access token
|
|
description: >
|
|
Refreshes the access token using the refresh token.
|
|
The new access token is returned in a cookie.
|
|
tags:
|
|
- Internal API - Authentication
|
|
security:
|
|
- refreshTokenCookie: []
|
|
responses:
|
|
'200':
|
|
description: Successfully refreshed the access token
|
|
headers:
|
|
Set-Cookie:
|
|
description: >
|
|
The cookie containing the new access token.
|
|
This cookie is used to authenticate the user in subsequent requests.
|
|
schema:
|
|
type: string
|
|
example: 'OvMeetAccessToken=token_123456; Path=/; HttpOnly; SameSite=Strict'
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
example: 'Token refreshed'
|
|
'400':
|
|
description: Bad Request — The refresh token is missing or invalid
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
message: 'No refresh token provided'
|
|
'500':
|
|
description: Internal server error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
message: 'Internal server error'
|
|
/auth/profile:
|
|
get:
|
|
operationId: getUserProfile
|
|
summary: Get user profile
|
|
description: >
|
|
Retrieves the profile information of the authenticated user.
|
|
tags:
|
|
- Internal API - Authentication
|
|
security:
|
|
- accessTokenCookie: []
|
|
responses:
|
|
'200':
|
|
description: Successfully retrieved user profile
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
username:
|
|
type: string
|
|
example: 'admin'
|
|
description: The username of the authenticated user.
|
|
role:
|
|
type: string
|
|
example: 'admin'
|
|
description: The role assigned to the authenticated user.
|
|
'401':
|
|
description: Unauthorized — The access token is missing or invalid
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
message: 'Unauthorized'
|
|
/rooms/{roomId}/participant-role:
|
|
get:
|
|
operationId: getParticipantRole
|
|
summary: Get participant role in a room
|
|
description: >
|
|
Retrieves the role that a participant will have in a specified OpenVidu Meet room when using the URL thant contains the secret token.
|
|
This endpoint is useful for checking the participant's role before joining the room.
|
|
tags:
|
|
- Internal API - Rooms
|
|
security:
|
|
- accessTokenCookie: []
|
|
parameters:
|
|
- name: roomId
|
|
in: path
|
|
required: true
|
|
description: The name of the room to check the participant's role
|
|
schema:
|
|
type: string
|
|
- name: secret
|
|
in: query
|
|
required: true
|
|
description: The secret token from the room URL to check the participant's role
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: Successfully retrieved participant role
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: string
|
|
example: 'moderator'
|
|
description: The role that the participant will have in the room.
|
|
'404':
|
|
description: Room not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
name: 'Room Error'
|
|
message: 'The room does not exist'
|
|
'422':
|
|
description: Unprocessable Entity — Invalid request query parameters
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: 'Unprocessable Entity'
|
|
message:
|
|
type: string
|
|
example: 'Invalid request query'
|
|
details:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
field:
|
|
type: string
|
|
example: 'secret'
|
|
message:
|
|
type: string
|
|
example: 'secret is required'
|
|
'500':
|
|
description: Internal server error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
message: 'Internal server error'
|
|
/recordings/{recordingId}/stream:
|
|
get:
|
|
operationId: getRecordingStream
|
|
summary: Stream an OpenVidu Meet recording
|
|
description: >
|
|
Streams the OpenVidu Meet recording with the specified recording ID.
|
|
This endpoint supports range requests, allowing partial content retrieval
|
|
for video playback without downloading the entire file.
|
|
tags:
|
|
- Internal API - Recordings
|
|
security:
|
|
- accessTokenCookie: []
|
|
parameters:
|
|
- name: recordingId
|
|
in: path
|
|
required: true
|
|
description: The ID of the recording to stream
|
|
schema:
|
|
type: string
|
|
- name: Range
|
|
in: header
|
|
required: false
|
|
description: >
|
|
Byte range for partial content retrieval.
|
|
Example: `bytes=0-1023` to request the first 1024 bytes of the file.
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: Successfully streaming the full recording
|
|
headers:
|
|
Accept-Ranges:
|
|
description: Indicates that byte-range requests are supported
|
|
schema:
|
|
type: string
|
|
Content-Length:
|
|
description: The total file size in bytes
|
|
schema:
|
|
type: integer
|
|
content:
|
|
video/mp4:
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
'206':
|
|
description: Partial content streaming based on byte range
|
|
headers:
|
|
Accept-Ranges:
|
|
description: Indicates that byte-range requests are supported
|
|
schema:
|
|
type: string
|
|
Content-Range:
|
|
description: Specifies the range of bytes being sent
|
|
schema:
|
|
type: string
|
|
Content-Length:
|
|
description: The length of the partial content in bytes
|
|
schema:
|
|
type: integer
|
|
content:
|
|
video/mp4:
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
'400':
|
|
description: Bad Request — Invalid range header format
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
code: 400
|
|
message: 'Invalid Range header'
|
|
'401':
|
|
description: Unauthorized — The access token is missing or invalid
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
message: 'Unauthorized'
|
|
'403':
|
|
description: Forbidden — The user authenticated with the access token does not have enough permissions
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
message: 'Insufficient permissions to access this resource'
|
|
'404':
|
|
description: Recording not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
code: 404
|
|
message: 'Recording not found'
|
|
'416':
|
|
description: Requested range not satisfiable
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
code: 416
|
|
message: 'Requested range not satisfiable'
|
|
'500':
|
|
description: Internal server error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
code: 500
|
|
message: 'Internal server error'
|
|
/participants/token:
|
|
post:
|
|
operationId: generateParticipantToken
|
|
summary: Generate a token for a participant
|
|
description: >
|
|
Generates a token for a participant to join an OpenVidu Meet room.
|
|
tags:
|
|
- Internal API - Participant
|
|
security:
|
|
- accessTokenCookie: []
|
|
requestBody:
|
|
description: Participant details
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/TokenOptions'
|
|
responses:
|
|
'200':
|
|
description: Successfully generated the participant token
|
|
headers:
|
|
Set-Cookie:
|
|
description: >
|
|
The cookie containing the participant token.
|
|
This cookie is used to authenticate the participant in the room.
|
|
schema:
|
|
type: string
|
|
example: 'OvMeetParticipantToken=token_123456; Path=/; HttpOnly; SameSite=Strict'
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
token:
|
|
type: string
|
|
example: 'token_123456'
|
|
description: >
|
|
The token to authenticate the participant.
|
|
'401':
|
|
description: Unauthorized — The access token is missing or invalid when authentication is required
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
message: 'Unauthorized'
|
|
'403':
|
|
description: Forbidden — The user authenticated with the access token does not have enough permissions when authentication is required
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
message: 'Insufficient permissions to access this resource'
|
|
'404':
|
|
description: Room not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
name: 'Room Error'
|
|
message: 'The room does not exist'
|
|
'409':
|
|
description: Conflict — The participant already exists in the room
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
name: 'Participant Error'
|
|
message: 'Participant already exists in the room'
|
|
'500':
|
|
description: Internal server error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
message: 'Internal server error'
|
|
/participants/token/refresh:
|
|
post:
|
|
operationId: refreshParticipantToken
|
|
summary: Refresh a token for a participant
|
|
description: >
|
|
Refresh a token for a participant in an OpenVidu Meet room.
|
|
tags:
|
|
- Internal API - Participant
|
|
security:
|
|
- accessTokenCookie: []
|
|
requestBody:
|
|
description: Participant details
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/TokenOptions'
|
|
responses:
|
|
'200':
|
|
description: Successfully refreshed the participant token
|
|
headers:
|
|
Set-Cookie:
|
|
description: >
|
|
The cookie containing the participant token.
|
|
This cookie is used to authenticate the participant in the room.
|
|
schema:
|
|
type: string
|
|
example: 'OvMeetParticipantToken=token_123456; Path=/; HttpOnly; SameSite=Strict'
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
token:
|
|
type: string
|
|
example: 'token_123456'
|
|
description: >
|
|
The token to authenticate the participant.
|
|
'401':
|
|
description: Unauthorized — The access token is missing or invalid when authentication is required
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
message: 'Unauthorized'
|
|
'403':
|
|
description: Forbidden — The user authenticated with the access token does not have enough permissions when authentication is required
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
message: 'Insufficient permissions to access this resource'
|
|
'404':
|
|
description: Room or participant not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
name: 'Participant Error'
|
|
message: 'Participant not found in the room'
|
|
'409':
|
|
description: Conflict — Current token is still valid
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
message: 'Participant token is still valid'
|
|
'500':
|
|
description: Internal server error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
message: 'Internal server error'
|
|
/participants/{participantName}:
|
|
delete:
|
|
operationId: disconnectParticipant
|
|
summary: Delete a participant from a room
|
|
description: >
|
|
Deletes a participant from an OpenVidu Meet room.
|
|
tags:
|
|
- Internal API - Participant
|
|
security:
|
|
- participantTokenCookie: []
|
|
parameters:
|
|
- name: participantName
|
|
in: path
|
|
required: true
|
|
description: The name of the participant to delete
|
|
schema:
|
|
type: string
|
|
- name: roomId
|
|
in: query
|
|
required: true
|
|
description: The ID of the room where the participant is connected
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'204':
|
|
description: Successfully disconnect the participant
|
|
'401':
|
|
description: Unauthorized — The participant access token is missing or invalid
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
message: 'Unauthorized'
|
|
'403':
|
|
description: Forbidden — The participant authenticated with the access token is not moderator of the room
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
message: 'Insufficient permissions to access this resource'
|
|
'404':
|
|
description: Participant not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
code: 404
|
|
message: 'Participant not found'
|
|
'500':
|
|
description: Internal server error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
code: 500
|
|
message: 'Internal server error'
|
|
|
|
components:
|
|
securitySchemes:
|
|
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.
|
|
refreshTokenCookie:
|
|
type: apiKey
|
|
name: OvMeetRefreshToken
|
|
in: cookie
|
|
description: >
|
|
The JWT token to refresh the access token in case of consuming the API from the OpenVidu Meet frontend.
|
|
participantTokenCookie:
|
|
type: apiKey
|
|
name: OvMeetParticipantToken
|
|
in: cookie
|
|
description: >
|
|
The JWT token to authenticate the participant when entering the room.
|
|
schemas:
|
|
MeetRecordingBase:
|
|
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: 'room-123--XX445.mp4'
|
|
description: The name of the recording file.
|
|
startDate:
|
|
type: number
|
|
example: 1620000000000
|
|
description: The date when the recording was started (milliseconds since the Unix epoch).
|
|
|
|
MeetRecording:
|
|
allOf:
|
|
- $ref: '#/components/schemas/MeetRecordingBase'
|
|
- type: object
|
|
properties:
|
|
endDate:
|
|
type: number
|
|
example: 1620000000000
|
|
description: The date when the recording was stopped (milliseconds since the Unix epoch).
|
|
duration:
|
|
type: number
|
|
example: 3600
|
|
description: The duration of the recording in seconds.
|
|
size:
|
|
type: number
|
|
example: 1024
|
|
description: The size of the recording file in bytes.
|
|
errorCode:
|
|
type: number
|
|
example: 100
|
|
description: The error code of the recording.
|
|
error:
|
|
type: [string, 'null']
|
|
description: The error message of the recording.
|
|
details:
|
|
type: string
|
|
example: 'Stopped using API'
|
|
description: Additional details about the recording.
|
|
|
|
MeetRecordingStart:
|
|
$ref: '#/components/schemas/MeetRecordingBase'
|
|
|
|
TokenOptions:
|
|
type: object
|
|
required:
|
|
- roomId
|
|
- participantName
|
|
- secret
|
|
properties:
|
|
roomId:
|
|
type: string
|
|
example: 'room-123'
|
|
description: >
|
|
The ID of the room where the participant will join.
|
|
participantName:
|
|
type: string
|
|
example: 'Alice'
|
|
description: >
|
|
The name of the participant.
|
|
secret:
|
|
type: string
|
|
example: 'abc123456'
|
|
description: >
|
|
The secret token from the room Url
|
|
|
|
Error:
|
|
type: object
|
|
required:
|
|
- message
|
|
properties:
|
|
name:
|
|
type: string
|
|
message:
|
|
type: string
|