REST API

All REST operations have in common the header referred to authorization. It is implemented via Basic Auth, and it is as simple as applying Base64 encoding to the username (always "OPENVIDUAPP") and the password (your secret shared with openvidu-server). If authorization header is wrong, every call to any REST API operation will return HTTP status 401.

For example, for secret "MY_SECRET", the final valid HTTP header would be

Authorization: Basic T1BFTlZJRFVBUFA6TVlfU0VDUkVU

List of available operations 🔗


POST /api/sessions 🔗

NEW SESSIONID PARAMETERS
Operation POST
URL https://<YOUR_OPENVIDUSERVER_IP>/api/sessions
Headers Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Content-Type: application/json
Body {"mediaMode": "MEDIA_MODE", "recordingMode": "RECORDING_MODE", "customSessionId": "CUSTOM_SESSION_ID", "defaultOutputMode": "OUTPUT_MODE", "defaultRecordingLayout": "RECORDING_LAYOUT", "defaultCustomLayout": "CUSTOM_LAYOUT"}
Sample return {"id": "zfgmthb8jl9uellk", "createdAt": 1538481996019}

Body parameters

  • mediaMode (optional string)
    • ROUTED (default) : Media streams will be routed through OpenVidu Server. This Media Mode is mandatory for session recording
    • Not available yet: RELAYED

  • recordingMode (optional string)
    • ALWAYS: Automatic recording from the first user publishing until the last participant leaves the session
    • MANUAL (default) : If you want to manage when start and stop the recording

  • customSessionId (optional string)
    • You can fix the sessionId that will be assigned to the session with this parameter. If you make another request with the exact same customSessionId while previous session already exists, no session will be created and a 409 http response will be returned. If this parameter is an empty string or not sent at all, OpenVidu Server will generate a random sessionId for you. If set, it must be an alphanumeric string: allowed numbers [0-9], letters [a-zA-Z], dashes (-) and underscores (_)

  • defaultOutputMode (optional string)
    • COMPOSED(default) : when recording the session, all streams will be composed in the same file in a grid layout
    • INDIVIDUAL: when recording the session, every stream is recorded in its own file

  • defaultRecordingLayout (optional string. Only applies if defaultOutputMode is set to COMPOSED)
    • BEST_FIT(default) : A grid layout where all the videos are evenly distributed
    • CUSTOM: Use your own custom layout. See Custom recording layouts section to learn how
    • Not available yet: PICTURE_IN_PICTURE, VERTICAL_PRESENTATION, HORIZONTAL_PRESENTATION

  • defaultCustomLayout (optional string. Only applies if defaultRecordingLayout is set to CUSTOM)
    • A relative path indicating the custom recording layout to be used if more than one is available. Default to empty string (if so custom layout expected under path set with openvidu-server configuration property OPENVIDU_RECORDING_CUSTOM_LAYOUT)

Returned JSON

  • id: session identifier. Store it for performing future operations onto this session
  • createdAt: time when the session was created in UTC milliseconds

HTTP responses

  • 200: session successfully created and sessionId ready to be used
  • 400: problem with some body parameter
  • 409: parameter customSessionId corresponds to an existing session. There has been no change at all in the state of OpenVidu Server. You can proceed to use the rejected custom sessionId as usual without a problem

POST /api/tokens 🔗

NEW TOKEN PARAMETERS
Operation POST
URL https://<YOUR_OPENVIDUSERVER_IP>/api/tokens
Headers Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Content-Type: application/json
Body {"session": "SESSION_ID", "role": "ROLE", "data": "DATA", "kurentoOptions": KURENTO_OPTIONS}
Sample return {"id":"wss://localhost:4443?sessionId=zfgmthb8jl9uellk&token=lnlrtnkwm4v8l7uc&role=PUBLISHER&turnUsername=FYYNRC&turnCredential=yfxxs3", "session": "zfgmthb8jl9uellk", "role": "PUBLISHER", "data": "User Data", "token":"wss://localhost:4443?sessionId=zfgmthb8jl9uellk&token=lnlrtnkwm4v8l7uc&role=PUBLISHER&turnUsername=FYYNRC&turnCredential=yfxxs3", "kurentoOptions": {"videoMaxSendBandwidth": 700, "allowedFilters": ["GStreamerFilter", "ZBarFilter"]}}

Body parameters

  • session (mandatory string) : the sessionId for which the token should be associated

  • role (optional string. Check OpenViduRole section of OpenVidu Node Client for a complete description)
    • SUBSCRIBER
    • PUBLISHER (default)
    • MODERATOR

  • data (optional string) : metadata associated to this token (usually participant's information)

  • kurentoOptions (optional JSON object) : you can set some configuration properties for the participant owning this token regarding Kurento. This is a JSON object with the following optional properties:

    • videoMaxRecvBandwidth: maximum number of Kbps that the client owning the token will be able to receive from Kurento Media Server. 0 means unconstrained. Giving a value to this property will override the global configuration set in OpenVidu configuration (parameter OPENVIDU_STREAMS_VIDEO_MAX_RECV_BANDWIDTH) for every incoming stream of the user owning the token. WARNING: the lower value set to this property limits every other bandwidth of the WebRTC pipeline this server-to-client stream belongs to. This includes the user publishing the stream and every other user subscribed to the same stream.
    • videoMinRecvBandwidth: minimum number of Kbps that the client owning the token will try to receive from Kurento Media Server. 0 means unconstrained. Giving a value to this property will override the global configuration set in OpenVidu configuration (parameter OPENVIDU_STREAMS_VIDEO_MIN_RECV_BANDWIDTH) for every incoming stream of the user owning the token.
    • videoMaxSendBandwidth: maximum number of Kbps that the client owning the token will be able to send to Kurento Media Server. 0 means unconstrained. Giving a value to this property will override the global configuration set in OpenVidu configuration (parameter OPENVIDU_STREAMS_VIDEO_MAX_SEND_BANDWIDTH) for every outgoing stream of the user owning the token. WARNING: this value limits every other bandwidth of the WebRTC pipeline this client-to-server stream belongs to. This includes every other user subscribed to the stream.
    • videoMinSendBandwidth: minimum number of Kbps that the client owning the token will try to send to Kurento Media Server. 0 means unconstrained. Giving a value to this property will override the global configuration set in OpenVidu configuration (parameter OPENVIDU_STREAMS_VIDEO_MIN_SEND_BANDWIDTH) for every outgoing stream of the user owning the token.
    • allowedFilters: array of strings containing the names of the filters the user owning the token will be able to apply (see Voice and video filters)

Returned JSON

  • token: token value. Send it to one client to pass it as a parameter in openvidu-browser method Session.connect
  • session: same as in the body request
  • role: same as in the body request
  • data: same as in the body request
  • id: same value as token
  • kurentoOptions: object with Kurento configuration if provided, same as in the body request

HTTP responses

  • 200: token successfully created and ready to be used by one client to connect to the associated session
  • 400: problem with some body parameter
  • 404: provided value for session parameter was not found in OpenVidu Server. You must first call POST /api/sessions to get a session id

GET /api/sessions/<SESSION_ID> 🔗

GET SESSION INFO PARAMETERS
Operation GET
URL https://<YOUR_OPENVIDUSERVER_IP>/api/sessions/<SESSION_ID>
Headers Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Content-Type: application/x-www-form-urlencoded
Sample return {"sessionId":"TestSession","createdAt":1538482606338,"mediaMode":"ROUTED","recordingMode":"MANUAL","defaultOutputMode":"COMPOSED","defaultRecordingLayout":"BEST_FIT","customSessionId":"TestSession","connections":{"numberOfElements":2,"content":[{"connectionId":"vhdxz7abbfirh2lh","createdAt":1538482606412,"location":"","platform":"Chrome 69.0.3497.100 on Linux 64-bit","token":"wss://localhost:4443?sessionId=TestSession&token=2ezkertrimk6nttk&role=PUBLISHER&turnUsername=H0EQLL&turnCredential=kjh48u","role":"PUBLISHER","serverData":"","clientData":"TestClient1","publishers":[{"createdAt":1538482606976,"streamId":"vhdxz7abbfirh2lh_CAMERA_CLVAU","mediaOptions":{"hasAudio":true,"audioActive":true,"hasVideo":true,"videoActive":true,"typeOfVideo":"CAMERA","frameRate":30,"videoDimensions":"{\"width\":640,\"height\":480}","filter":{}}}],"subscribers":[]},{"connectionId":"maxawd3ysuj1rxvq","createdAt":1538482607659,"location":"","platform":"Chrome 69.0.3497.100 on Linux 64-bit","token":"wss://localhost:4443?sessionId=TestSession&token=ovj1b4ysuqmcirti&role=PUBLISHER&turnUsername=INOAHN&turnCredential=oujrqd","role":"PUBLISHER","serverData":"","clientData":"TestClient2","publishers":[],"subscribers":[{"createdAt":1538482607799,"streamId":"vhdxz7abbfirh2lh_CAMERA_CLVAU","publisher":"vhdxz7abbfirh2lh"}]}]},"recording":false}

Returned JSON

  • sessionId: identifier of the session (identical to SESSION_ID url parameter)
  • createdAt: time when the session was created in UTC milliseconds
  • mediaMode: media mode configured for the session (ROUTED or RELAYED)
  • recording: whether the session is being recorded or not at this moment
  • recordingMode: recording mode configured for the session (ALWAYS or MANUAL)
  • defaultOutputMode: the default output mode for the recordings of the session (COMPOSED or INDIVIDUAL)
  • defaultRecordingLayout: the default recording layout configured for the recordings of the session. Only defined if field defaultOutputMode is set to COMPOSED
  • defaultCustomLayout: the default custom layout configured for the recordings of the session. Its format is a relative path. Only defined if field defaultRecordingLayout is set to CUSTOM
  • customSessionId: custom session identifier. Only defined if the session was initialized passing a customSessionId field (see POST /api/sessions)
  • connections: collection of active connections in the session. This object is defined by a numberOfElements property counting the total number of active connections and a content array with the actual connections. Each object of this array has this structure:
    • connectionId: identifier of the user's connection
    • createdAt: time when the connection was established in UTC milliseconds
    • location: geo location of the participant
      PRO
    • platform: complete description of the platform used by the participant to connect to the session
    • role: role of the connection
    • clientData: data defined in OpenVidu Browser when calling Session.connect (metadata parameter)
    • serverData: data assigned to the user's token when generating the token in OpenVidu Server
    • token: user's token
    • publishers: array of Publisher objects (streams the user is publishing). Each one is defined by the unique streamId property, has a createdAt property indicating the time it was created in UTC milliseconds and has a mediaOptions object with the current properties of the published stream ("hasVideo","hasAudio","videoActive","audioActive","frameRate","videoDimensions","typeOfVideo", "filter")
    • subscribers: array of Subscriber objects (streams the user is subscribed to). Each on is defined by their streamId (equal to the "streamId" property of its associated publisher, that must be present in some other connection of the session) and a createdAt property indicating the time it was created in UTC milliseconds

HTTP responses

  • 200: the session information has been successfully retrieved
  • 404: no session exists for the passed SESSION_ID

GET /api/sessions 🔗

GET ALL SESSION INFO PARAMETERS
Operation GET
URL https://<YOUR_OPENVIDUSERVER_IP>/api/sessions
Headers Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Sample return {"numberOfElements":1,"content":[{"sessionId":"TestSession","createdAt":1538482606338,"mediaMode":"ROUTED","recordingMode":"MANUAL","defaultOutputMode":"COMPOSED","defaultRecordingLayout":"BEST_FIT","customSessionId":"TestSession","connections":{"numberOfElements":2,"content":[{"connectionId":"vhdxz7abbfirh2lh","createdAt":1538482606412,"location":"","platform":"Chrome 69.0.3497.100 on Linux 64-bit","token":"wss://localhost:4443?sessionId=TestSession&token=2ezkertrimk6nttk&role=PUBLISHER&turnUsername=H0EQLL&turnCredential=kjh48u","role":"PUBLISHER","serverData":"","clientData":"TestClient1","publishers":[{"createdAt":1538482606976,"streamId":"vhdxz7abbfirh2lh_CAMERA_CLVAU","mediaOptions":{"hasAudio":true,"audioActive":true,"hasVideo":true,"videoActive":true,"typeOfVideo":"CAMERA","frameRate":30,"videoDimensions":"{\"width\":640,\"height\":480}","filter":{}}}],"subscribers":[]},{"connectionId":"maxawd3ysuj1rxvq","createdAt":1538482607659,"location":"","platform":"Chrome 69.0.3497.100 on Linux 64-bit","token":"wss://localhost:4443?sessionId=TestSession&token=ovj1b4ysuqmcirti&role=PUBLISHER&turnUsername=INOAHN&turnCredential=oujrqd","role":"PUBLISHER","serverData":"","clientData":"TestClient2","publishers":[],"subscribers":[{"createdAt":1538482607799,"streamId":"vhdxz7abbfirh2lh_CAMERA_CLVAU","publisher":"vhdxz7abbfirh2lh"}]}]},"recording":false}]}

Returned JSON

  • numberOfElements: total number of active sessions
  • content: array of sessions. Each object has the same structure as defined in the returned JSON of GET /api/sessions/<SESSION_ID>

HTTP responses

  • 200: all the session information has been successfully retrieved

POST /api/signal 🔗

SEND A SIGNAL PARAMETERS
Operation POST
URL https://<YOUR_OPENVIDUSERVER_IP>/api/signal
Headers Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Content-Type: application/json
Body {"session": "SESSION_ID", "to": ["connectionId1", "connectionId2"], "type": "MY_TYPE", "data": "This is my signal data"}
Sample return Returns nothing

Body parameters

  • session (mandatory string) : the sessionId of the session you want to send the signal to

  • to (optional array of strings) : list of connection identifiers to which you want to send the signal. If this property is not included or is an empty array, the signal will be sent to all participants of the session

  • type (optional string) : type of the signal. In the body example of the table above, only users subscribed to Session.on('signal:MY_TYPE') will trigger that signal. Users subscribed to Session.on('signal') will trigger signals of any type

  • data (optional string) : actual data of the signal

HTTP responses

  • 200: signal successfully sent. This doesn't necessary mean that all the intended recipients will have received it correctly. If any user has lost its connection to OpenVidu Server during this process, it may not receive the signal
  • 400: there is a problem with some body parameter
  • 404: no session exists for the passed SESSION_ID
  • 406: no connection exists for the passed to array. This error may be triggered if the session has no connected participants or if you provide some string value that does not correspond to a valid connectionId of the session (even though others may be correct)

DELETE /api/sessions/<SESSION_ID> 🔗

CLOSE SESSION PARAMETERS
Operation DELETE
URL https://<YOUR_OPENVIDUSERVER_IP>/api/sessions/<SESSION_ID>
Headers Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Content-Type: application/x-www-form-urlencoded
Sample return Returns nothing

HTTP responses

  • 204: the session has been successfully closed. Every participant will have received the proper events in OpenVidu Browser: streamDestroyed, connectionDestroyed and sessionDisconnected, all of them with "reason" property set to "sessionClosedByServer". Depending on the order of eviction of the users, some of them will receive more events than the others (the first one will only receive the events related to himself, last one will receive every possible event)
  • 404: no session exists for the passed SESSION_ID

DELETE /api/sessions/<SESSION_ID>/connection/<CONNECTION_ID> 🔗

FORCE DISCONNECTION PARAMETERS
Operation DELETE
URL https://<YOUR_OPENVIDUSERVER_IP>/api/sessions/<SESSION_ID>/connection/<CONNECTION_ID>
Headers Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Content-Type: application/x-www-form-urlencoded
Sample return Returns nothing

HTTP responses

  • 204: the user has been successfully evicted from the session. Every participant will have received the proper events in OpenVidu Browser: streamDestroyed if the user was publishing, connectionDestroyed for the remaining users and sessionDisconnected for the evicted user. All of them with "reason" property set to "forceDisconnectByServer"
  • 400: no session exists for the passed SESSION_ID
  • 404: no connection exists for the passed CONNECTION_ID

DELETE /api/sessions/<SESSION_ID>/stream/<STREAM_ID> 🔗

FORCE UNPUBLISHING PARAMETERS
Operation DELETE
URL https://<YOUR_OPENVIDUSERVER_IP>/api/sessions/<SESSION_ID>/stream/<STREAM_ID>
Headers Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Content-Type: application/x-www-form-urlencoded
Sample return Returns nothing

HTTP responses

POST /api/sessions/<SESSION_ID>/connection 🔗

Available from OpenVidu >= 2.12.0

PUBLISH IP CAMERA PARAMETERS
Operation POST
URL https://<YOUR_OPENVIDUSERVER_IP>/api/sessions/<SESSION_ID>/connection
Headers Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Content-Type: application/json
Body {"type": "IPCAM", "rtspUri": "rtsp://b1.dnsdojo.com:1935/live/sys3.stream", "adaptativeBitrate": true, "onlyPlayWithSubscribers": true, "data": "Office security camera"}
Sample return {"connectionId": "ipc_IPCAM_rtsp_A8MJ_91_191_213_49_554_live_mpeg4_sdp", "createdAt": 1582121476379, "location": "unknown", "platform": "IPCAM", "role": "PUBLISHER", "serverData": "MY_IP_CAMERA", "publishers": [{"createdAt": 1582121476439, "streamId": "str_IPC_XC1W_ipc_IPCAM_rtsp_A8MJ_91_191_213_49_554_live_mpeg4_sdp", "rtspUri": "rtsp://91.191.213.49:554/live_mpeg4.sdp", "mediaOptions": {"hasAudio": true, "audioActive": true, "hasVideo": true, "videoActive": true, "typeOfVideo": "IPCAM", "frameRate": null, "videoDimensions": null, "filter": {}, "adaptativeBitrate": true, "onlyPlayWithSubscribers": true}} ], "subscribers": []}

Body parameters

  • type (optional string) : which type of stream will be published. For now can only be IPCAM. Default to IPCAM

  • rtspUri (mandatory string) : RTSP URI of the IP camera. For example: rtsp://your.camera.ip:7777/path

  • adaptativeBitrate (optional boolean) : whether to use adaptative bitrate (and therefore adaptative quality) or not. For local network connections that do not require media transcoding this can be disabled to save CPU power. If you are not sure if transcoding might be necessary, setting this property to false may result in media connections not being established. Default to true

  • onlyPlayWithSubscribers (optional boolean) : enable the IP camera stream only when some user is subscribed to it. This allows you to reduce power consumption and network bandwidth in your server while nobody is asking to receive the camera's video. On the counterpart, first user subscribing to the IP camera stream will take a little longer to receive its video. Default to true

  • data (optional string) : metadata you want to associate to the camera's participant. This will be included as Connection.data property received by your clients on connectionCreated event, and will also be available in backend events (CDR and Webhook)

Returned JSON

Returns the new Connection object. This object is the same as each JSON object in the connections.content array returned by method GET /api/sessions/<SESSION_ID>

  • connectionId: identifier of the camera's connection. Store it to perform other operations such as unpublish the IP camera from the session
  • createdAt: time when the connection was established in UTC milliseconds
  • location: geo location of the IP camera
    PRO
  • platform: "IPCAM"
  • role: "PUBLISHER"
  • clientData: "" (IP camera connections cannot be initialized from the client-side)
  • serverData: data associated to the IP camera connection with query parameter data
  • token: undefined (IP camera connections do not have a token associated)
  • publishers: array of Publisher objects (streams the camera is publishing. There will only be one object). Each one is defined by the unique streamId property, has a createdAt property indicating the time it was created in UTC milliseconds and has a mediaOptions object with the current properties of the published stream ("hasVideo", "hasAudio", "videoActive", "audioActive", "frameRate", "videoDimensions", "typeOfVideo", "filter")
  • subscribers: [] (camera is always a send-only connection, so it won't have any subscriber object)

HTTP responses

  • 200: the IP camera has been successfully published to the session. Every participant will have received the proper events in OpenVidu Browser: connectionCreated identifying the new camera participant and streamCreated so they can subscribe to the IP camera stream.
  • 400: problem with some body parameter
  • 404: no session exists for the passed SESSION_ID
  • 500: unexpected error when publishing the IP camera stream into the session. See the error message for further information

POST /api/recordings/start 🔗

START SESSION RECORDING PARAMETERS
Operation POST
URL https://<YOUR_OPENVIDUSERVER_IP>/api/recordings/start
Headers Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Content-Type: application/json
Body {"session": "SESSION_ID", "name": "NAME", "outputMode": "OUTPUT_MODE", "hasAudio": "HAS_AUDIO", "hasVideo": "HAS_VIDEO", "resolution": "RESOLUTION", "recordingLayout": "RECORDING_LAYOUT", "customLayout": "CUSTOM_LAYOUT"}
Sample return {"id": "fds4e07mdug1ga3h", "sessionId": "fds4e07mdug1ga3h", "name": "MyRecording", "outputMode": "COMPOSED", "hasAudio":true, "hasVideo":false,"createdAt":1538483606521, "size":3205004, "duration":12.92, "url":null, "status": "started"}

Body parameters

  • session (mandatory string) : the sessionId belonging to the session you want to start recording

  • name (optional string) : the name you want to give to the video file. You can access this same property in openvidu-browser on recordingEvents. If no name is provided, the video file will be named after id property of the recording

  • outputMode (optional string) : record all streams in a single file in a grid layout or record each stream in its own separate file. This property will override the defaultOutputMode property set on POST /api/sessions for this particular recording
    • COMPOSED(default) : when recording the session, all streams will be composed in the same file in a grid layout
    • INDIVIDUAL: when recording the session, every stream is recorded in its own file

  • hasAudio (optional boolean) : whether to record audio or not. Default to true

  • hasVideo (optional boolean) : whether to record video or not. Default to true

  • recordingLayout (optional string. Only applies if outputMode is set to COMPOSED and hasVideo to true) : the layout to be used in this recording. This property will override the defaultRecordingLayout property set on POST /api/sessions for this particular recording.
    • BEST_FIT(default) : A grid layout where all the videos are evenly distributed
    • CUSTOM: Use your own custom layout. See Custom recording layouts section to learn how
    • Not available yet: PICTURE_IN_PICTURE, VERTICAL_PRESENTATION, HORIZONTAL_PRESENTATION

  • customLayout (optional string. Only applies if recordingLayout is set to CUSTOM) : a relative path indicating the custom recording layout to be used if more than one is available. Default to empty string (if so custom layout expected under path set with openvidu-server system property OPENVIDU_RECORDING_CUSTOM_LAYOUT) . This property will override the defaultCustomLayout property set on POST /api/sessions for this particular recording

  • resolution (optional string. Only applies if outputMode is set to COMPOSED and hasVideo to true) : the resolution of the recorded video file. It is a string indicating the width and height in pixels like this: "1920x1080". Values for both width and height must be between 100 and 1999

Returned JSON

  • id: recording identifier. Store it to perform other operations such as stop, get or delete the recording
  • sessionId: session associated to the recording (same value as session in the body request)
  • name: name of the recording. If no name parameter is passed in the POST operation, will be equal to id field
  • outputMode: output mode of the recording
  • hasAudio: true if the recording has an audio track, false otherwise
  • hasVideo: true if the recording has a video track, false otherwise
  • recordingLayout: the recording layout that is being used. Only defined if outputMode is set to COMPOSED and hasVideo to true
  • customLayout: the custom layout that is being used. Only defined if recordingLayout is set to CUSTOM
  • resolution: resolution of the video file. Only defined if outputMode is set to COMPOSED and hasVideo to true
  • createdAt: time when the recording started in UTC milliseconds
  • size: size in bytes of the video file (0 until stop operation is called)
  • duration: duration of the video file in seconds (0 until stop operation is called)
  • url: set to null
  • status: set to "started"

HTTP responses

  • 200: the session has started to be recorded. The moment this response is retrieved, it means that the video file is already created and contains proper data, and that the recording can be stopped with guarantees
  • 400: problem with some body parameter
  • 422: resolution parameter exceeds acceptable values (for both width and height, min 100px and max 1999px) or trying to start a recording with both hasAudio and hasVideo to false
  • 404: no session exists for the passed sessionId parameter
  • 406: the session has no connected participants
  • 409: the session is not configured for using MediaMode ROUTED or it is already being recorded
  • 501: OpenVidu Server recording module is disabled (OPENVIDU_RECORDING property set to false)

POST /api/recordings/stop/<RECORDING_ID> 🔗

STOP SESSION RECORDING PARAMETERS
Operation POST
URL https://<YOUR_OPENVIDUSERVER_IP>/api/recordings/stop/<RECORDING_ID>
Headers Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Content-Type: application/x-www-form-urlencoded
Sample return {"id": "fds4e07mdug1ga3h", "sessionId": "fds4e07mdug1ga3h", "name": "MyRecording", "outputMode": "COMPOSED", "hasAudio": true, "hasVideo": false, "createdAt": 1538483606521, "size": 3205004, "duration": 12.92, "url": null, "status": "stopped"}

Returned JSON

  • id: recording identifier
  • sessionId: session associated to the recording
  • name: name of the recording. If no name parameter is passed when starting the recording, will be equal to id field
  • outputMode: output mode of the recording
  • hasAudio: true if the recording has an audio track, false otherwise
  • hasVideo: true if the recording has a video track, false otherwise
  • recordingLayout: the recording layout used in the recording. Only defined if outputMode is set to COMPOSED and hasVideo to true
  • customLayout: the custom layout used in the recording. Only defined if recordingLayout is set to CUSTOM
  • resolution: resolution of the video file. Only defined if outputMode is set to COMPOSED and hasVideo to true
  • createdAt: time when the recording started in UTC milliseconds
  • size: size in bytes of the video file
  • duration: duration of the video file in seconds
  • url: set to "https://YOUR_OPENVIDUSERVER_IP/recordings/<RECORDING_ID>/<RECORDING_NAME>.<EXTENSION>". This path will be protected with OpenVidu credentials depending on whether openvidu-server system property OPENVIDU_RECORDING_PUBLIC_ACCESS is false or true
  • status: set to "stopped" or "available" depending on whether openvidu-server system property OPENVIDU_RECORDING_PUBLIC_ACCESS is false or true

HTTP responses

  • 200: the session has successfully stopped from being recorded. The video file is ready to be reproduced
  • 404: no recording exists for the passed RECORDING_ID
  • 406: recording has starting status. Wait until started status before stopping the recording

GET /api/recordings/<RECORDING_ID> 🔗

GET RECORDING INFO PARAMETERS
Operation GET
URL https://<YOUR_OPENVIDUSERVER_IP>/api/recordings/<RECORDING_ID>
Headers Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Content-Type: application/x-www-form-urlencoded
Sample return {"id": "fds4e07mdug1ga3h", "sessionId": "fds4e07mdug1ga3h", "name": "MyRecording", "outputMode": "COMPOSED", "hasAudio": true, "hasVideo": false, "createdAt": 1538483606521, "size": 3205004, "duration": 12.92, "url": null, "status": "stopped"}

Returned JSON

  • id: recording identifier
  • sessionId: session associated to the recording
  • name: name of the recording. If no name parameter is passed when starting the recording, will be equal to id field
  • outputMode: output mode of the recording
  • hasAudio: true if the recording has an audio track, false otherwise
  • hasVideo: true if the recording has a video track, false otherwise
  • recordingLayout: the recording layout used in the recording. Only defined if outputMode is set to COMPOSED and hasVideo to true
  • customLayout: the custom layout used in the recording. Only defined if recordingLayout is set to CUSTOM
  • resolution: resolution of the video file. Only defined if outputMode is set to COMPOSED and hasVideo to true
  • createdAt: time when the recording started in UTC milliseconds
  • size: size in bytes of the video file (0 until stop operation is called)
  • duration: duration of the video file in seconds (0 until stop operation is called)
  • url: set to null until stop operation is called. Then it will be "https://YOUR_OPENVIDUSERVER_IP/recordings/<RECORDING_ID>/<RECORDING_NAME>.<EXTENSION>", path that may be protected with OpenVidu credentials depending on whether openvidu-server system property OPENVIDU_RECORDING_PUBLIC_ACCESS is false or true.
  • status: status of the recording ("starting", "started", "stopped", "ready", "failed")

HTTP responses

  • 200: the recording information has been successfully retrieved
  • 404: no recording exists for the passed RECORDING_ID

GET /api/recordings 🔗

LIST RECORDINGS INFO PARAMETERS
Operation GET
URL https://<YOUR_OPENVIDUSERVER_IP>/api/recordings
Headers Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Sample return {"count": 2, "items": [{"id": "n0kcws1evvn3esmo", "sessionId": "n0kcws1evvn3esmo", "name": "n0kcws1evvn3esmo", "outputMode": "COMPOSED", "hasAudio": true, "hasVideo": true, "recordingLayout": "BEST_FIT", "resolution": "1920x1080", "createdAt": 1521202349460, "size": 22887561, "duration": 132.08, "url": "https://localhost:4443/recordings/n0kcws1evvn3esmo/n0kcws1evvn3esmo.mp4", "status": "available"}, {"id": "fds4e07mdug1ga3h", "sessionId": "fds4e07mdug1ga3h", "name": "MyRecording", "outputMode": "COMPOSED", "hasAudio": true, "hasVideo": false, "createdAt": 1538483606521, "size": 3205004, "duration": 12.92, "url": "https://localhost:4443/recordings/fds4e07mdug1ga3h/MyRecording.webm", "status": "available"}]}

Returned JSON

  • count: number of total recordings
  • items: array of recording information in JSON format. Each item has the same properties as stated in the return value of method GET /api/recordings/<RECORDING_ID>

HTTP responses

  • 200: all of the available recording information has been successfully retrieved

DELETE /api/recordings/<RECORDING_ID> 🔗

DELETE RECORDING PARAMETERS
Operation DELETE
URL https://<YOUR_OPENVIDUSERVER_IP>/api/recordings/<RECORDING_ID>
Headers Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Content-Type: application/x-www-form-urlencoded
Sample return Returns nothing

HTTP responses

  • 204: the video file and all of its metadata has been successfully deleted from the host
  • 404: no recording exists for the passed RECORDING_ID
  • 409: the recording has "started" status. Stop it before deletion

GET /config 🔗

GET OPENVIDU CONFIGURATION PARAMETERS
Operation GET
URL https://<YOUR_OPENVIDUSERVER_IP>/config
Headers Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Sample return {"VERSION": "2.13.0", "DOMAIN_OR_PUBLIC_IP": "test.openvidu.io", "HTTPS_PORT": 443, "OPENVIDU_PUBLICURL": "https://test.openvidu.io/", "OPENVIDU_CDR": false, "OPENVIDU_STREAMS_VIDEO_MAX_RECV_BANDWIDTH": 1000, "OPENVIDU_STREAMS_VIDEO_MIN_RECV_BANDWIDTH": 300, "OPENVIDU_STREAMS_VIDEO_MAX_SEND_BANDWIDTH": 1000, "OPENVIDU_STREAMS_VIDEO_MIN_SEND_BANDWIDTH": 300, "OPENVIDU_SESSIONS_GARBAGE_INTERVAL": 900, "OPENVIDU_SESSIONS_GARBAGE_THRESHOLD": 3600, "OPENVIDU_RECORDING": true, "OPENVIDU_RECORDING_VERSION": "2.9.0", "OPENVIDU_RECORDING_PATH": "/opt/openvidu/recordings/", "OPENVIDU_RECORDING_PUBLIC_ACCESS": false, "OPENVIDU_RECORDING_NOTIFICATION": "publisher_moderator", "OPENVIDU_RECORDING_CUSTOM_LAYOUT": "/opt/openvidu/custom-layout/", "OPENVIDU_RECORDING_AUTOSTOP_TIMEOUT": 120, "OPENVIDU_WEBHOOK": true, "OPENVIDU_WEBHOOK_ENDPOINT": "https://webhook.openvidu.com/webhook", "OPENVIDU_WEBHOOK_HEADERS": [], "OPENVIDU_WEBHOOK_EVENTS": ["recordingStatusChanged", "mediaNodeStatusChanged"]}

Returned JSON

  • VERSION: version of OpenVidu Server
  • Rest of properties: current active values for the configuration properties of OpenVidu Server