REST API

You have full control over OpenVidu Server through its REST API. All of the REST API operations exposed by OpenVidu Server...

  • Share the same base path /openvidu/api/
  • Share the same Authorization header. It is implemented via Basic Auth, and it is as simple as applying Base64 encoding to the username (always "OPENVIDUAPP") and the password (configuration propertyOPENVIDU_SECRET). All REST API operations return HTTP status 401 if the Authorization header is wrong or not provided. For example, for secret "MY_SECRET" the final HTTP header would be:

Authorization: Basic T1BFTlZJRFVBUFA6TVlfU0VDUkVU

Index 🔗



The Session object 🔗

A Session is a conference room where users can send/receive media streams to/from each other.

{
    "id": "ses_YnDaGYNcd7",
    "object": "session",
    "createdAt": 1538481996019,
    "mediaMode": "ROUTED",
    "recordingMode": "MANUAL",
    "defaultRecordingProperties": {
        "name": "MyRecording",
        "hasAudio": true,
        "hasVideo": true,
        "outputMode": "COMPOSED",
        "recordingLayout": "BEST_FIT",
        "resolution": "1280x720",
        "frameRate": 25,
        "shmSize": 536870912,
        "mediaNode": "media_i-po39jr3e10rkjsdfj"
    },
    "customSessionId": "TestSession",
    "connections": {
        "numberOfElements": 0,
        "content": []
    },
    "recording": false,
    "forcedVideoCodec": "VP8",
    "allowTranscoding": false,
    "mediaNodeId": "media_i-po39jr3e10rkjsdfj"
}
id String Identifier of the session
object String (session) String representing the object’s type. Objects of the same type share the same value
createdAt Number Time when the session was created in UTC milliseconds
mediaMode String Media mode configured for the session (ROUTED or RELAYED)
recordingMode String Recording mode configured for the session (ALWAYS or MANUAL)
defaultRecordingProperties Object The recording properties to apply by default to any recording started for this Session
customSessionId String Custom session identifier. Only defined if the session was initialized passing a customSessionId field in method POST /openvidu/api/sessions
connections Object 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 active connections. Active connections are those with status property set to active. See Connection object
recording Boolean Whether the session is being recorded or not at this moment
forcedVideoCodec String This parameter will ensure that all the browsers use the same codec, avoiding transcoding process in the media server, which result in a reduce of CPU usage. (VP8, H264 or NONE)
allowTranscoding Boolean Defines if transcoding is allowed or not when forcedVideoCodec is not a compatible codec with the browser
mediaNodeId PRO String Identifier of the Media Node hosting this session. It is the id property of a Media Node object. Only defined after the session has actually been allocated inside the Media Node, which only happens after the first user connects to the session. See Manual distribution of OpenVidu Pro sessions

POST /openvidu/api/sessions 🔗

Description 🔗

Initialize a Session in OpenVidu Server. This is the very first operation to perform in OpenVidu workflow. After that, Connection objects can be generated for this Session and their token passed to the client-side, so clients can use it to connect to the Session.

Operation 🔗
METHOD POST
URL https://YOUR_OPENVIDUSERVER_IP/openvidu/api/sessions
HEADERS Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Content-Type: application/json
Body 🔗
{
    "mediaMode": "ROUTED",
    "recordingMode": "MANUAL",
    "customSessionId": "CUSTOM_SESSION_ID",
    "forcedVideoCodec": "VP8",
    "allowTranscoding": false,
    "defaultRecordingProperties": {
        "name": "MyRecording",
        "hasAudio": true,
        "hasVideo": true,
        "outputMode": "COMPOSED",
        "recordingLayout": "BEST_FIT",
        "resolution": "1280x720",
        "frameRate": 25,
        "shmSize": 536870912,
        "mediaNode": {
            "id": "media_i-0c58bcdd26l11d0sd"
        }
    },
    "mediaNode": {
        "id": "media_i-0c58bcdd26l11d0sd"
    }
}
  • mediaMode (optional String)
    • ROUTED (default) : media streams will be routed through OpenVidu Server. This Media Mode is mandatory for session recording.
    • RELAYED: not available yet

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

  • 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 (_).

  • forcedVideoCodec (optional String) : this parameter will ensure that all the clients use the same codec, avoiding transcoding process in the media server and greatly reducing unnecessary CPU load. You can change the default value changing the global configuration property OPENVIDU_STREAMS_FORCED_VIDEO_CODEC in OpenVidu Configuration.
    • VP8 (default): recommended and default value due to its compatibility with client devices and its royalty-free public license.
    • H264: useful when any expected client won't support VP8. H264 is also widely supported, and is generally more compatible with hardware acceleration tech of mobile devices, but H264 has some patent considerations to take into account.
    • NONE: no codec will be forced. Each device will try to use its preferred video codec. If those doesn't match, then transcoding will be forcibly applied.

  • allowTranscoding (optional Boolean) : defines whether transcoding is allowed or not. Only applies when forcedVideoCodec is defined (different from NONE) and only for those client devices that don't support the codec set in forcedVideoCodec. If forcedVideoCodec is set to NONE, then this parameter has no effect and transcoding will always take place if necessary.
    • false (default): no video transcoding will be performed. The video streams of a client device won't work if it doesn't support the codecs being used in a session.
    • true: video transcoding will be performed when necessary, only for the client streams which require it.

  • defaultRecordingProperties (optional Object) : the recording properties to apply by default to any recording started for this Session. You can of course override these default values and change the recording properties of any Recording when starting them. The object structure is the same as the one defined in Start the recording of a session.

  • mediaNode (optional Object) PRO : an object with the Media Node selector to force the Media Node allocation of this session (see Manual distribution of OpenVidu Pro sessions). Right now it may only have a single property id with a Media Node identifier. That is the id property of a Media Node object. If not set, by default the recording will be allocated in the less loaded Media Node.

Returns 🔗

This operation returns a Session object.

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


GET /openvidu/api/sessions/<SESSION_ID> 🔗

Description 🔗

Retrieve a Session from OpenVidu Server.

Operation 🔗
METHOD GET
URL https://YOUR_OPENVIDUSERVER_IP/openvidu/api/sessions/SESSION_ID
HEADERS Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Returns 🔗

This operation returns a Session object.

HTTP responses 🔗
200 The Session object has been successfully retrieved
404 No Session exists for the passed SESSION_ID


GET /openvidu/api/sessions 🔗

Description 🔗

Retrieve all Sessions from OpenVidu Server.

Operation 🔗
METHOD GET
URL https://YOUR_OPENVIDUSERVER_IP/openvidu/api/sessions
HEADERS Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Returns 🔗
{
    "numberOfElements": 0,
    "content": []
}
numberOfElements Number Total number of Sessions
content Array of Objects Array of Session objects
HTTP responses 🔗
200 All of the Session objects have been successfully retrieved


DELETE /openvidu/api/sessions/<SESSION_ID> 🔗

Description 🔗

Close a Session. This will stop all of the processes of this Session: all of its Connections, Streams and Recordings will be closed.

Operation 🔗
METHOD DELETE
URL https://YOUR_OPENVIDUSERVER_IP/openvidu/api/sessions/SESSION_ID
HEADERS Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
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 user evicted will only receive the events related to himself, last one will receive every possible event
404 No Session exists for the passed SESSION_ID


The Connection object 🔗

A Connection represents each one of the users connected to a Session. You must create a Connection for each final user connecting to the Session.

  • After creating the Connection, its status property will be set to pending. This means that the Connection is currently available to be taken by a final user.
  • Pass the token attribute of a Connection object to the client-side, and use it to call method Session.connect of OpenVidu Browser library.
  • After this, the Connection object will be associated to this final user and its status property will be set to active. Other properties will also be now populated with the data of the final user.
{
    "id": "con_Xnxg19tonh",
    "object": "connection",
    "type": "WEBRTC",
    "status": "active",
    "sessionId": "ses_YnDaGYNcd7",
    "createdAt": 1538481999022,
    "activeAt": 1538481999843,
    "location": "Madrid, Spain",
    "platform": "Chrome 85.0.4183.102 on Linux 64-bit",
    "token": "wss://localhost:4443?sessionId=TestSession&token=tok_AVe8o7iltWqtijyl&role=PUBLISHER&version=2.16.0&coturnIp=localhost&turnUsername=M2ALIY&turnCredential=7kfjy2",
    "serverData": "My Server Data",
    "clientData": "My Client Data",
    "record": true,
    "role": "PUBLISHER",
    "kurentoOptions": {
        "videoMaxRecvBandwidth": 1000,
        "videoMinRecvBandwidth": 300,
        "videoMaxSendBandwidth": 1000,
        "videoMinSendBandwidth": 300,
        "allowedFilters": [
            "GStreamerFilter",
            "ZBarFilter"
        ]
    },
    "rtspUri": null,
    "adaptativeBitrate": null,
    "onlyPlayWithSubscribers": null,
    "networkCache": null,
    "publishers": [
        {
            "createdAt": 1538481999710,
            "streamId": "str_CAM_NhxL_con_Xnxg19tonh",
            "mediaOptions": {
                "hasAudio": true,
                "audioActive": true,
                "hasVideo": true,
                "videoActive": true,
                "typeOfVideo": "CAMERA",
                "frameRate": 30,
                "videoDimensions": "{\"width\":640,\"height\":480}",
                "filter": {}
            }
        }
    ],
    "subscribers": [
        {
            "streamId": "str_MIC_JSXs_con_OV0CsFsykJ",
            "createdAt": 1538482000856
        }
    ]
}
id String Identifier of the Connection
object String (connection) String representing the object’s type. Objects of the same type share the same value
type String Type of the Connection. It can be WEBRTC for a regular user connecting from an application or IPCAM for an IP camera
status String Status of the Connection:
  • pending: the Connection is waiting for any user to use its internal token to connect to the Session, calling method Session.connect OpenVidu Browser.
  • active: the internal token of the Connection has already been used by some user to connect to the Session, and it cannot be used again.
sessionId String Identifier of the Session to which the user is connected
createdAt Number Time when the Connection was created in UTC milliseconds
activeAt Number Time when the Connection was taken by a user by calling method Session.connect with the Connection's token property, in UTC milliseconds. This is the time when the Connection status passed from pending to active
location PRO String Geographic location of the participant
platform String Complete description of the platform used by the participant to connect to the Session. Set to IPCAM if type=IPCAM
token String Token of the Connection. Pass it to the client-side to be used in method Session.connect. Set to null if type=IPCAM
serverData String Data assigned to the Connection in your application's server-side when creating the Connection (data parameter)
clientData String Data assigned to the Connection in your application's client-side when calling Session.connect (metadata parameter). Set to null if type=IPCAM or status=pending
record PRO Boolean Whether the streams published by this Connections will be recorded or not. This only affects INDIVIDUAL recording
role String Only for type=WEBRTC. Role of the Connection
kurentoOptions Object Only for type=WEBRTC. Configuration properties applied to the streams of this Connection, regarding Kurento
rtspUri String Only for type=IPCAM. RTSP URI of the IP camera
adaptativeBitrate Boolean Only for type=IPCAM. Whether to use adaptative bitrate (and therefore adaptative quality) or not
onlyPlayWithSubscribers Boolean Only for type=IPCAM. Whether to enable the IP camera stream only when some user is subscribed to it, or not
networkCache Number Only for type=IPCAM. Size of the buffer of the endpoint receiving the IP camera's stream, in milliseconds
publishers Array of Objects Collection of Publisher objects: streams the Connection is currently publishing. Each one has the following properties:
  • streamId (String) : identifier of the stream
  • createdAt (Number) : time when the stream was published in UTC milliseconds
  • mediaOptions (Object) : current properties of the published stream. See Stream object from openvidu-browser library for a description of them. Some may change dynamically. See StreamPropertyChanged event of openvidu-browser library.
    • hasVideo (Boolean)
    • hasAudio (Boolean)
    • videoActive (Boolean)
    • audioActive (Boolean)
    • frameRate (Number)
    • videoDimensions (String)
    • typeOfVideo (String)
    • filter (Object)
subscribers Array of Objects Collection of Subscriber objects: streams the user is currently subscribed to. Each one has the following properties:
  • streamId (String) : equal to the streamId property of its associated publisher, that must be present in the publishers array of some other connection of the Session
  • createdAt (Number) : time when the subscription was established in UTC milliseconds

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

Description 🔗

Create a new Connection in the Session.

Operation 🔗
METHOD POST
URL https://YOUR_OPENVIDUSERVER_IP/openvidu/api/sessions/SESSION_ID/connection
HEADERS Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Content-Type: application/json
Body 🔗

For a regular user Connection (type WEBRTC)

{
    "type": "WEBRTC",
    "data": "My Server Data",
    "record": true,
    "role": "PUBLISHER",
    "kurentoOptions": {
        "videoMaxRecvBandwidth": 1000,
        "videoMinRecvBandwidth": 300,
        "videoMaxSendBandwidth": 1000,
        "videoMinSendBandwidth": 300,
        "allowedFilters": [ "GStreamerFilter", "ZBarFilter" ]
    }
}

For an IP camera Connection (type IPCAM)

{
   "type": "IPCAM",
   "data": "Office security camera",
   "record": true,
   "rtspUri": "rtsp://your.camera.ip.sdp",
   "adaptativeBitrate": true,
   "onlyPlayWithSubscribers": true,
   "networkCache": 2000
}
  • type (optional String) : which type of Connection will be created. It can be WEBRTC for a regular user connecting from an application or IPCAM for an IP camera. Default to WEBRTC

  • data (optional String) : metadata associated to this Connection (usually participant's information). This populates property serverData of the Connection object

  • record (optional Boolean) PRO : whether to record the streams published by the Connection or not. This only affects INDIVIDUAL recording. Default to true

  • role (optional String. Check OpenViduRole section of OpenVidu Node Client for a complete description): only for type WEBRTC. Defines the role of the Connection:
    • SUBSCRIBER
    • PUBLISHER (default)
    • MODERATOR

  • kurentoOptions (optional Object) : only for type WEBRTC. You can set some configuration properties for the Connection regarding Kurento. This is a JSON object with the following optional properties:

    • videoMaxRecvBandwidth (optional Number) : maximum number of Kbps that the Connection will be able to receive from Kurento Media Server per subscriber stream. 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 Connection. 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 (optional Number) : minimum number of Kbps that the Connection will try to receive from Kurento Media Server per subscriber stream. 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 Connection.

    • videoMaxSendBandwidth (optional Number) : maximum number of Kbps that the Connection will be able to send to Kurento Media Server per publisher stream. 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 Connection. 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 (optional Number) : minimum number of Kbps that the Connection will try to send to Kurento Media Server per publisher stream. 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 Connection.

    • allowedFilters (optional array of strings) : names of the filters the Connection will be able to apply to its published streams (see Voice and video filters).

  • rtspUri (mandatory String if property type is IPCAM) : only for type IPCAM. RTSP URI of the IP camera. For example: rtsp://your.camera.ip:7777/path

  • adaptativeBitrate (optional Boolean) : only for type IPCAM. 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) : only for type IPCAM. 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

  • networkCache (optional Number) : only for type IPCAM. Size of the buffer of the endpoint receiving the IP camera's stream, in milliseconds. The smaller it is, the less delay the signal will have, but more problematic will be in unstable networks. Use short buffers only if there is a quality connection between the IP camera and OpenVidu Server. Default to 2000

Returns 🔗

Returns a Connection object.

HTTP responses 🔗
200 The Connection has been successfully created. If it is of type WEBRTC, its token can now be used to connect a final user. If it is of type IPCAM, every participant will immediately receive the proper events in OpenVidu Browser: connectionCreated identifying the new IP camera Connection 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 creating the Connection object. This can only happen if type is IPCAM. See the error message for further information


GET /openvidu/api/sessions/<SESSION_ID>/connection/<CONNECTION_ID> 🔗

Description 🔗

Get a Connection from a Session.

Operation 🔗
METHOD GET
URL https://YOUR_OPENVIDUSERVER_IP/openvidu/api/sessions/SESSION_ID/connection/CONNECTION_ID
HEADERS Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Returns 🔗

This operation returns a Connection object.

HTTP responses 🔗
200 The Connection object has been successfully retrieved
400 No Session exists for the passed SESSION_ID
404 No Connection exists for the passed CONNECTION_ID


GET /openvidu/api/sessions/<SESSION_ID>/connection 🔗

Description 🔗

List all Connections from a Session.

Operation 🔗
METHOD GET
URL https://YOUR_OPENVIDUSERVER_IP/openvidu/api/sessions/SESSION_ID/connection
HEADERS Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Returns 🔗
{
    "numberOfElements": 0,
    "content": []
}
numberOfElements Number Total number of Connections
content Array of Objects Array of Connection objects
HTTP responses 🔗
200 All of the Connection objects have been successfully retrieved
404 No Session exists for the passed SESSION_ID


PATCH /openvidu/api/sessions/<SESSION_ID>/connection/<CONNECTION_ID> 🔗

This feature is part of OpenViduPRO tier.
Description 🔗

Modify the properties of a Connection. The following properties are modifiable:

  • role: you can dynamically change the role of the Connection in the Session.
  • record: you can enable or disable INDIVIDUAL recording of the streams published by this Connection. See Selecting streams to be recorded for further information.

The affected client will trigger one ConnectionPropertyChangedEvent for each modified property.

Operation 🔗
METHOD PATCH
URL https://YOUR_OPENVIDUSERVER_IP/openvidu/api/sessions/SESSION_ID/connection/CONNECTION_ID
HEADERS Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Content-Type: application/json
Body 🔗
{
    "role": "PUBLISHER",
    "record": true
}
  • role (optional String) : new role property of the Connection
  • record (optional Boolean) : new record property of the Connection
Sample return 🔗

This operation returns the modified Connection object.

HTTP responses 🔗
200 The Connection has been successfully modified
400 Problem with some body parameter
404 No Session exists for the passed SESSION_ID, or no Connection exists for the passed CONNECTION_ID


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

Description 🔗

Force the disconnection of a user from a Session. All of the streams associated to this Connection (both publishers and subscribers) will be destroyed. If the user was publishing a stream, all other subscribers of other users receiving it will also be destroyed.

If the CONNECTION_ID belongs to a Connection in pending status, this method will simply invalidate it (its token will be no longer available for any user to connect to the Session).

Operation 🔗
METHOD DELETE
URL https://YOUR_OPENVIDUSERVER_IP/openvidu/api/sessions/SESSION_ID/connection/CONNECTION_ID
HEADERS Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
HTTP responses 🔗
204 The Connection has been successfully removed 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".
If the CONNECTION_ID belongs to a Connection in pending status, it has been successfully invalidated and its token can no longer be used.
400 No Session exists for the passed SESSION_ID
404 No Connection for the passed CONNECTION_ID


The Recording object 🔗

A Recording represents the recording process of a Session.

{
    "id": "ses_YnDaGYNcd7",
    "object": "recording",
    "name": "MyRecording",
    "outputMode": "COMPOSED",
    "hasAudio": true,
    "hasVideo": true,
    "resolution": "1280x720",
    "frameRate": 25,
    "recordingLayout": "CUSTOM",
    "customLayout": "",
    "sessionId": "ses_YnDaGYNcd7",
    "createdAt": 1600564785109,
    "size": 303072692,
    "duration": 108000.234,
    "url": "https://my.openvidu.ip/openvidu/recordings/ses_YnDaGYNcd7/MyRecording.mp4",
    "status": "ready"
}
id String Identifier of the Recording. It will be based on the identifier of the session. Store it to perform other operations such as stop, get or delete the Recording
object String (recording) String representing the object’s type. Objects of the same type share the same value
name String Name of the Recording. If no name parameter is provided, will be equal to id field
outputMode String Output mode of the Recording
hasAudio Boolean True if the Recording includes an audio track, false otherwise
hasVideo Boolean True if the Recording includes a video track, false otherwise
resolution String Resolution of the video file. Only defined if outputMode is set to COMPOSED or COMPOSED_QUICK_START and hasVideo to true
frameRate Number Frame rate of the video file. Only defined if outputMode is set to COMPOSED or COMPOSED_QUICK_START and hasVideo to true
recordingLayout String The recording layout that is being used. Only defined if outputMode is set to COMPOSED or COMPOSED_QUICK_START and hasVideo to true
customLayout String The custom layout that is being used. Only defined if recordingLayout is set to CUSTOM
sessionId String Session associated to the Recording
createdAt Number Time when the Recording started in UTC milliseconds
size Number Size in bytes of the video file. Only guaranteed to be greater than 0 if status is ready
duration Number Duration of the video file in seconds. Only guaranteed to be greater than 0 if status is ready
url String URL where the Recording file is available. Only guaranteed to different than null if status is ready
The final URL value follows this format:
https://YOUR_OPENVIDUSERVER_IP/openvidu/recordings/<RECORDING_ID>/<RECORDING_NAME>.<EXTENSION>
This path will be protected with OpenVidu credentials depending on whether openvidu-server configuration property OPENVIDU_RECORDING_PUBLIC_ACCESS is false or true. This format is equals to the AWS S3 URL object property of the uploaded object for OpenVidu Pro deployments configured to upload recordings to S3
status String Status of the Recording:
  • starting: the Recording is being started. This is in a way a special status, because it can only appear if a concurrent REST API call to list recordings is done at the narrow time frame in which the Recording starts. The moment the start operation returns, the Recording status will be started. A Recording in this status cannot be stopped. It does not get triggered in CDR/Webhook recordingStatusChanged.
  • started: the session is being recorded. This means the associated video(s) already exists and its size is greater than 0. NOTE: when using COMPOSED recording with video, this event does not mean there are publisher's streams being actually recorded in the video file. It only ensures the video file exists and its size is greater than 0.
  • stopped: the recording process has stopped and files are being processed. Depending on the type of OpenVidu deployment and configuration, properties duration and size can be set to 0 and url can be null. If this is the case, wait for status ready to get the final value of these properties.
  • ready: the recorded file has been successfully processed and is available for download. Properties duration, size and url will always be properly defined at this moment. For OpenVidu Pro deployments configured to upload recordings to S3 this status means that the Recording has been successfully stored in the S3 bucket.
  • failed: the recording process has failed. The final state of the recorded file cannot be guaranteed to be stable.
The recording status will be started after calling the start operation and while the Recording is active. After calling stop operation, the status may be stopped or ready depending on the type of deployment of OpenVidu. OpenVidu CE will always return ready status. OpenVidu Pro will always return stopped status and properties size, duration and url will not have their final value defined yet. Listen to recordingStatusChanged CDR/Webhook event to know when the Recording has reached ready status in this case

POST /openvidu/api/recordings/start 🔗

Description 🔗

Start the recording of a Session. See Recording documentation.

Operation 🔗
METHOD POST
URL https://YOUR_OPENVIDUSERVER_IP/openvidu/api/recordings/start
HEADERS Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Content-Type: application/json
Body 🔗
{
    "session":"ses_YnDaGYNcd7",
    "name": "MyRecording",
    "hasAudio": true,
    "hasVideo": true,
    "outputMode": "COMPOSED",
    "recordingLayout": "CUSTOM",
    "customLayout": "mySimpleLayout",
    "resolution": "1280x720",
    "frameRate": 25,
    "shmSize": 536870912,
    "ignoreFailedStreams": false,
    "mediaNode": {
        "id": "media_i-0c58bcdd26l11d0sd"
    }
}
  • 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.
    • 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.
    • COMPOSED_QUICK_START : same as COMPOSED, but the recording will start much quicker in exchange for a higher CPU usage during the lifespan of the session. See Composed quick start recording for further information. This output mode only applies when defined in the defaultRecordingProperties object when initializing a Session.

  • 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 or COMPOSED_QUICK_START and hasVideo to true) : the layout to be used in this 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 configuration property OPENVIDU_RECORDING_CUSTOM_LAYOUT).

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

  • frameRate (optional Number. Only applies if outputMode is set to COMPOSED or COMPOSED_QUICK_START and hasVideo to true) : the frame rate of the recorded video file. Minimum 1 and maximum 120. Default to 25.

  • shmSize (optional Number. Only applies if outputMode is set to COMPOSED or COMPOSED_QUICK_START and hasVideo to true) : the amount of memory dedicated to the recording module in charge of this specific recording, in bytes. The default value is usually fine, but you can adjust it to your needs. Default to 536870912 (512 MB).

  • ignoreFailedStreams (optional Boolean. Only applies if outputMode is set to INDIVIDUAL) : whether to ignore failed streams or not when starting the recording. For INDIVIDUAL recordings, by default all the streams available at the moment the recording process starts must be healthy and properly sending media. If some stream that should be sending media is broken, then the recording process fails after a 10s timeout. In this way your application is notified that some stream is not being recorded, so it can retry the process again. But you can disable this rollback behavior and simply ignore any failed stream, which will be susceptible to be recorded in the future if media starts flowing as expected at any point. The downside of this behavior is that you will have no guarantee that all streams present at the beginning of a recording are actually being recorded. Default to false.

  • mediaNode (optional Object) PRO
    • An object with the Media Node selector to force the Media Node allocation of this recording. Only for composed recordings with video (see Scalable composed recording). Right now it may only have a single property id with a Media Node identifier. That is the id property of a Media Node object. If not set, by default the recording will be allocated in the same Media Node as the one hosting the recorded session, which is the best option in terms of network traffic.

Returns 🔗

This operation returns a Recording object.

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), frameRate parameter exceed acceptable values (min 0 and max 120), or trying to start a recording with both hasAudio and hasVideo to false
404 No session exists for the passed session body 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 configuration property is set to false


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

Description 🔗

Stop the recording of a Session. See Recording documentation.

Operation 🔗
METHOD POST
URL https://YOUR_OPENVIDUSERVER_IP/openvidu/api/recordings/stop/RECORDING_ID
HEADERS Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Returns 🔗

This operation returns a Recording object.

HTTP responses 🔗
200 The session has successfully stopped from being recorded
404 No recording exists for the passed RECORDING_ID
406 Recording has starting status. Wait until started status before stopping the recording
501 OpenVidu Server recording module is disabled: OPENVIDU_RECORDING configuration property is set to false


GET /openvidu/api/recordings/<RECORDING_ID> 🔗

Description 🔗

Retrieve a Recording from OpenVidu Server.

Operation 🔗
METHOD GET
URL https://YOUR_OPENVIDUSERVER_IP/openvidu/api/recordings/RECORDING_ID
HEADERS Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Returns 🔗

This operation returns a Recording object.

HTTP responses 🔗
200 The recording information has been successfully retrieved
404 No recording exists for the passed RECORDING_ID
501 OpenVidu Server recording module is disabled: OPENVIDU_RECORDING configuration property is set to false


GET /openvidu/api/recordings 🔗

Description 🔗

Retrieve all Recordings from OpenVidu Server.

Operation 🔗
METHOD GET
URL https://YOUR_OPENVIDUSERVER_IP/openvidu/api/recordings
HEADERS Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Returns 🔗
{
    "count": 0,
    "items": []
}
count Number Total number of recordings
items Array of Objects Array of Recording objects
HTTP responses 🔗
200 All the recording information has been successfully retrieved
501 OpenVidu Server recording module is disabled: OPENVIDU_RECORDING configuration property is set to false


DELETE /openvidu/api/recordings/<RECORDING_ID> 🔗

Description 🔗

Delete a Recording. This will delete all of the recording files from disk.

Operation 🔗
METHOD DELETE
URL https://YOUR_OPENVIDUSERVER_IP/openvidu/api/recordings/RECORDING_ID
HEADERS Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
HTTP responses 🔗
204 All of the recording files have been successfully deleted from disk
404 No recording exists for the passed RECORDING_ID
409 The recording has started status. Stop it before deletion
501 OpenVidu Server recording module is disabled: OPENVIDU_RECORDING configuration property is set to false


The Media Node object 🔗

Media Nodes represent each one of the worker instances of your OpenVidu Pro cluster. See OpenVidu Pro architecture.

The Media Node API is part of OpenViduPRO tier. 
{
    "id": "media_i-0c58bcdd26l11d0sd",
    "object": "mediaNode",
    "environmentId": "i-0c58bcdd26l11d0sd",
    "ip": "172.17.0.2",
    "uri": "ws://172.17.0.2:8888/kurento",
    "launchingTime": 1600678236916,
    "connected": true,
    "connectionTime": 1600678251771,
    "load": 12.45,
    "status": "running",
    "sessions": [],
    "recordingIds": [],
    "kurentoInfo": {}
}
id String Media Node unique identifier. Use it to perform REST operations on this Media Node
object String (mediaNode) String representing the object’s type. Objects of the same type share the same value
environmentId String Media Node unique identifier dependent on the deployment environment. For example, an AWS EC2 machine identifier if the cluster is deployed in AWS
ip String Media Node IP
uri String Media Node URI endpoint. This is the URI where OpenVidu Server will establish a connection with the Media Node
launchingTime Number When the Media Node was launched, in UTC milliseconds
connected Boolean Whether OpenVidu Server Pro is connected to this Media Node or not. This property may be false if there is an unexpected disconnection of the Media Node
connectionTime Number When OpenVidu Server established the connection with the Media Node, in UTC milliseconds
disconnectionTime Number When OpenVidu Server lost its connection to the Media Node, in UTC milliseconds. Only available if connected is false
load Number CPU load of the Media Node. Decimal number between 0.00 and 100.00
status String Status of the Media Node. See Media Node statuses
sessions Array of Objects Collection of sessions initialized in this Media Node. See Session object
Property only retrievable when providing query param sessions=true in methods:
recordingIds Array of Strings Collection of recordings initialized in this Media Node. Each string is the id of a Recording object. See Scalable composed recording
Property only retrievable when providing query param recordings=true in methods:
kurentoInfo Object Object with extra advanced information about the Kurento Media Server internal process of this Media Node (version, modules, memory usage...). This is a property aimed at advanced users, subject to change.
Property only retrievable when providing query param extra-info=true in methods:

GET /openvidu/api/media-nodes/<MEDIA_NODE_ID> 🔗

The Media Node API is part of OpenViduPRO tier.
Description 🔗

Retrieve the information of a Media Node.

Operation 🔗
METHOD GET
URL https://YOUR_OPENVIDUSERVER_IP/openvidu/api/media-nodes/MEDIA_NODE_ID
HEADERS Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Content-Type: application/x-www-form-urlencoded
QUERY PARAMS sessions,recordings,extra-info
Query params 🔗
Parameter Type Default Description
sessions Boolean false Whether to return session information along Media Node information or not. Only sessions hosted in this Media Node will be retrieved. See Session object
extra‑info Boolean false Whether to return extra information about the Media Node or not. Only for advanced users

https://YOUR_OPENVIDUSERVER_IP/openvidu/api/media-nodes/MEDIA_NODE_ID?sessions=false&recordings=true&extra-info=false

Sample return 🔗

This operation returns a Media Node object.

HTTP responses 🔗
200 The Media Node information has been successfully retrieved
404 No Media Node exists for the passed MEDIA_NODE_ID


GET /openvidu/api/media-nodes 🔗

The Media Node API is part of OpenViduPRO tier.
Description 🔗

Retrieve the information of all Media Nodes.

Operation 🔗
METHOD GET
URL https://YOUR_OPENVIDUSERVER_IP/openvidu/api/media-nodes
HEADERS Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Content-Type: application/x-www-form-urlencoded
QUERY PARAMS sessions,recordings,extra-info
Query params 🔗
Parameter Type Default Description
sessions Boolean false Whether to return session information along Media Node information or not. Only sessions hosted in this Media Node will be retrieved. See Session object
extra‑info Boolean false Whether to return extra information about the Media Node or not. Only for advanced users

https://YOUR_OPENVIDUSERVER_IP/openvidu/api/media-nodes?sessions=false&recordings=true&extra-info=false

Sample return 🔗
{
    "numberOfElements": 0,
    "content": []
}
numberOfElements Number Total number of Media Nodes
content Array of Objects Array of Media Node objects
HTTP responses 🔗
200 All the Media Nodes information has been successfully retrieved


POST /openvidu/api/media-nodes 🔗

The Media Node API is part of OpenViduPRO tier.
Description 🔗

Add a new Media Node to the cluster.

Operation 🔗
METHOD POST
URL https://YOUR_OPENVIDUSERVER_IP/openvidu/api/media-nodes
HEADERS Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Content-Type: application/json
QUERY PARAMS wait
Query params 🔗
Parameter Type Default Description
wait Boolean false Whether to wait until the new Media Node reaches running status or not. Setting this property to true basically makes this method synchronized. You will not receive a response until the Media Node is properly running or an error is thrown

https://YOUR_OPENVIDUSERVER_IP/openvidu/api/media-nodes?wait=false

Body 🔗

Example for On Premises deployments:

{
    "uri": "ws://172.17.0.5:8888/kurento",
    "environmentId": "myCustomInstance"
}
  • uri (mandatory String only for On Premises deployments) : the websocket endpoint of a running Media Node. Should be something similar to ws://media.server.ip:8888/kurento. This property is only necessary and is only taken into account On Premises deployments. For other deployment environments a new Media Node will be automatically launched completely ignoring parameter uri.
  • environmentId (optional String only for On Premises deployments) : a custom environment id. This can help further identify your on premises Media Node.

Example for AWS deployments:

{
    "instanceType": "c5.2xlarge",
    "volumeSize": 200
}
  • instanceType (optional String only for AWS deployments) : a valid EC2 instance type. If specified, a Media Node will be created using the specified EC2 instance type. If not especified, value AWS_INSTANCE_TYPE in /opt/openvidu/.env will be used. This property is only taken into account in AWS deployments.
  • volumeSize (optional Number only for AWS deployments) : Volume size for the new Media Node in GB. If specified, the Media Node will be created with such disk volume size. If not especified, value AWS_VOLUME_SIZE in /opt/openvidu/.env will be used. This property is only taken into account in AWS deployments.
Sample return 🔗

This operation returns the created Media Node object. Most of its properties won't be defined until the Media Node reaches running status. You can user query param wait=true to wait until the Media Node is running before receiving the response, or you can listen to mediaNodeStatusChanged webhook event.

HTTP responses 🔗
200 The Media Node has been successfully added to the cluster
400 Problem with some body parameter
404 The Media Node is not within reach of OpenVidu Server. This simply means that OpenVidu cannot establish a connection with it. This may be caused by multiple reasons: wrong IP, port or path, a network problem, too strict a proxy configuration...
409 The Media Node was already registered in OpenVidu Server as part of the cluster
501 The cluster is deployed On Premises and no uri parameter was passed in the body request
502 The process of launching a new Media Node instance failed. This won't ever happen for On Premises deployments, where instances require to be previously launched


DELETE /openvidu/api/media-nodes/<MEDIA_NODE_ID> 🔗

The Media Node API is part of OpenViduPRO tier.
Description 🔗

Remove a Media Node from the cluster. If there are ongoing Sessions currently hosted by the Media Node and the deletion process is forced, all of the Sessions will be closed.

Operation 🔗
METHOD DELETE
URL https://YOUR_OPENVIDUSERVER_IP/openvidu/api/media-nodes/MEDIA_NODE_ID
HEADERS Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Content-Type: application/x-www-form-urlencoded
QUERY PARAMS wait,deletion-strategy
Query params 🔗
Parameter Type Default Description
wait Boolean false Whether to wait until the new Media Node reaches terminated status or not. Setting this property to true basically makes this method synchronized. You will not receive a response until the Media Node is fully terminated or an error is thrown
deletion‑strategy String "if‑no‑sessions" How should OpenVidu Pro proceed with the Media Node deletion. Can be:
  • now : OpenVidu Pro will remove the Media Node immediately. All OpenVidu sessions hosted by this Media Node will be closed with reason mediaServerDisconnect (all streams, participants and recordings of all these sessions will be stopped with this same reason)
  • if-no-sessions : if there's any OpenVidu session initialized inside of this Media Node, then this operation will fail with HTTP status 409. If the Media Node has no ongoing sessions, then OpenVidu Pro will remove it immediately, returning status 204.
  • when-no-sessions : if there's any OpenVidu session initialized inside this Media Node, then it will not be immediately deleted, but instead will be set to waiting-idle-to-terminate status. This status means the Media Node is under quarantine and no more sessions will be initialized inside of it. Whenever the last session of this Media Node is destroyed (no matter the reason), then it will be automatically deleted. The response status will be 202 if this operation changed the Media Node to waiting-idle-to-terminate status and 204 if there were no ongoing sessions inside the Media Node and therefore OpenVidu Pro has deleted it.

https://YOUR_OPENVIDUSERVER_IP/openvidu/api/media-nodes/MEDIA_NODE_ID?wait=false&deletion-strategy=if-no-sessions

HTTP responses 🔗
202 If query parameter deletion-strategy is set to when-no-sessions, then it means that the Media Node to be deleted has ongoing sessions inside of it. Media Node status has been set to waiting-idle-to-terminate
204 The Media Node was successfully removed
404 No Media Node exists for the passed MEDIA_NODE_ID
409 If query parameter deletion-strategy is set to if-no-sessions, then it means that the Media Node to be deleted has ongoing sessions inside of it. No Media Node deletion will take place at all
502 Error while terminating the Media Node instance. This won't ever happen for On Premises deployments, where instances require manual shut down


PATCH /openvidu/api/media-nodes/<MEDIA_NODE_ID> 🔗

The Media Node API is part of OpenViduPRO tier.
Description 🔗

Modify the status of a Media Node. This method allows you to manually transition a Media Node through its statuses.

Operation 🔗
METHOD PATCH
URL https://YOUR_OPENVIDUSERVER_IP/openvidu/api/media-nodes/MEDIA_NODE_ID
HEADERS Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Content-Type: application/json
Body 🔗
{
    "status": "terminating"
}
  • status (mandatory String) : new desired status of the Media Node. Valid values are canceled (from launching status), launching (from canceled status), waiting-idle-to-terminate (from running status), running (from waiting-idle-to-terminate) and terminating (from both running and waiting-idle-to-terminate). Visit Media Node statuses to understand the Media Node lifecycle
Sample return 🔗

This operation returns the modified Media Node object.

HTTP responses 🔗
200 The Media Node has been successfully modified
204 The Media Node has not been modified because its status was the same as the provided through body parameters
400 Problem with some body parameter. This means the Media Node cannot transition from its current status to the indicated one in the status request body parameter
404 No Media Node exists for the passed MEDIA_NODE_ID


PUT /openvidu/api/media-nodes 🔗

The Media Node API is part of OpenViduPRO tier.
Description 🔗

Autodiscover Media Nodes. This method makes OpenVidu Server search for reachable, running Media Nodes that are not part of the cluster yet. This can be useful in case a Media Node was launched by any other means than OpenVidu itself: this method is the only way to automatically add these Media Nodes to the running cluster.

Operation 🔗
METHOD PUT
URL https://YOUR_OPENVIDUSERVER_IP/openvidu/api/media-nodes
HEADERS Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Sample return 🔗
{
    "numberOfElements": 0,
    "content": []
}
numberOfElements Number Total number of newly autodiscovered Media Nodes
content Array of Objects Array of newly autodiscovered Media Node objects
HTTP responses 🔗
200 Autodiscovery process has completed


Others 🔗

POST /openvidu/api/tokens 🔗

The Token API is deprecated. Use the Connection API: instead of generating a Token with POST /openvidu/api/tokens, create a Connection with POST /openvidu/api/sessions/<SESSION_ID>/connection
Description 🔗

Generate a token for a Session. This token must be sent to the client side to be used in openvidu-browser library to connect to the Session.

Operation 🔗
METHOD POST
URL https://YOUR_OPENVIDUSERVER_IP/openvidu/api/tokens
HEADERS Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Content-Type: application/json
Body 🔗
{
  "session": "SESSION_ID",
  "role": "PUBLISHER",
  "data": "DATA",
  "kurentoOptions": {
      "videoMaxRecvBandwidth": 1000,
      "videoMinRecvBandwidth": 300,
      "videoMaxSendBandwidth": 1000,
      "videoMinSendBandwidth": 300,
      "allowedFilters": [ "GStreamerFilter", "ZBarFilter" ]
  }
}
  • 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 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 (optional Number) : 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 (optional Number) : 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 (optional Number) : 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 (optional Number) : 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 (optional array of strings) : names of the filters the user owning the token will be able to apply (see Voice and video filters).
Returns 🔗

This operation returns a Token object:

{
    "id": "wss://localhost:4443?sessionId=ses_YnDaGYNcd7&token=tok_HCGhiWHWX6hC9el4&role=PUBLISHER&version=2.16.0&coturnIp=localhost&turnUsername=C4LVAW&turnCredential=3hbpdz&webrtcStatsInterval=0",
    "token": "wss://localhost:4443?sessionId=ses_YnDaGYNcd7&token=tok_HCGhiWHWX6hC9el4&role=PUBLISHER&version=2.16.0&coturnIp=localhost&turnUsername=C4LVAW&turnCredential=3hbpdz&webrtcStatsInterval=0",
    "connectionId": "con_Xnxg19tonh",
    "createdAt": 1538481996024,
    "session": "ses_YnDaGYNcd7",
    "role": "PUBLISHER",
    "data": "MY_SERVER_DATA",
    "record": true,
    "kurentoOptions": {
        "videoMaxRecvBandwidth": 1000,
        "videoMinRecvBandwidth": 300,
        "videoMaxSendBandwidth": 1000,
        "videoMinSendBandwidth": 300,
        "allowedFilters": [
            "GStreamerFilter",
            "ZBarFilter"
        ]
    }
}
id String Token value. Send it to one client to pass it as parameter in openvidu-browser method Session.connect
token String Same value as id
connectionId String Connection identifier that will be assigned to the user consuming this token
createdAt Number Time when the token was created in UTC milliseconds
session String Identifier of the session for which this token is valid
role String Role of the token. Check OpenViduRole section of OpenVidu Node Client for a complete description
data String Metadata associated to this token. Usually participant's information
record Boolean Whether the streams published by the participant owning this token will be recorded or not. This only affects INDIVIDUAL recording PRO
kurentoOptions Object Configuration properties for the participant owning this token regarding Kurento. See a complete description of them in the body of POST /openvidu/api/tokens
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 /openvidu/api/sessions to get a session id


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

Description 🔗

Force the unpublishing of a media stream from a Session. The stream belongs to a specific Connection obejct. All of the subscribers receiving this stream will also be destroyed.

Operation 🔗
METHOD DELETE
URL https://YOUR_OPENVIDUSERVER_IP/openvidu/api/sessions/SESSION_ID/stream/STREAM_ID
HEADERS Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
HTTP responses 🔗
204 The stream has been successfully unpublished. Every participant will have received the proper streamDestroyed event in OpenVidu Browser with "reason" property set to "forceUnpublishByServer"
400 No session exists for the passed SESSION_ID
404 No stream exists for the passed STREAM_ID
405 You cannot directly delete the stream of an IPCAM participant (any participant created with method POST /openvidu/api/sessions/<SESSION_ID>/connection). Instead you must delete the connection object with DELETE /openvidu/api/sessions/<SESSION_ID>/connection/<CONNECTION_ID>


POST /openvidu/api/signal 🔗

Description 🔗

Send a signal to a Session, to specific Connections or as a broadcast message to all Connections. This is the server-side implementation of the client operation Session.signal.

Operation 🔗
METHOD POST
URL https://YOUR_OPENVIDUSERVER_IP/openvidu/api/signal
HEADERS Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Content-Type: application/json
Body 🔗
{
    "session":"ses_YnDaGYNcd7",
    "to": ["con_Xnxg19tonh", "con_TNVdbuQCJF"],
    "type":"MY_TYPE",
    "data":"This is my signal data"
}
  • session (mandatory String) : the sessionId of the session you want to send the signal to.

  • to (optional Array of String) : 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 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 body parameter
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)


GET /openvidu/api/config 🔗

Description 🔗

Retrieve current OpenVidu configuration.

Operation 🔗
METHOD GET
URL https://YOUR_OPENVIDUSERVER_IP/openvidu/api/config
HEADERS Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Returns 🔗

Returns an object with the current OpenVidu configuration. This is an example of the object returned by OpenVidu CE:

{
    "VERSION": "2.16.0",
    "DOMAIN_OR_PUBLIC_IP": "my.openvidu.ip",
    "HTTPS_PORT": 443,
    "OPENVIDU_PUBLICURL": "https://my.openvidu.ip",
    "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.16.0",
    "OPENVIDU_RECORDING_PATH": "/opt/openvidu/recordings/",
    "OPENVIDU_RECORDING_PUBLIC_ACCESS": false,
    "OPENVIDU_RECORDING_NOTIFICATION": "moderator",
    "OPENVIDU_RECORDING_CUSTOM_LAYOUT": "/opt/openvidu/custom-layout/",
    "OPENVIDU_RECORDING_AUTOSTOP_TIMEOUT": 60,
    "OPENVIDU_WEBHOOK": true,
    "OPENVIDU_WEBHOOK_ENDPOINT": "http://my.webhook.endpoint:7777/webhook",
    "OPENVIDU_WEBHOOK_HEADERS": [],
    "OPENVIDU_WEBHOOK_EVENTS": [
        "sessionCreated",
        "sessionDestroyed",
        "recordingStatusChanged"
    ]
}

This is an example of an object returned by OpenVidu Pro. It includes all properties of OpenVidu CE configuration and others unique to OpenVidu Pro configuration:

{
    "VERSION": "2.15.1",
    "OPENVIDU_SERVER_DEPENDENCY_VERSION": "2.16.0",
    "DOMAIN_OR_PUBLIC_IP": "my.openvidu.ip",
    "HTTPS_PORT": 443,
    "OPENVIDU_PUBLICURL": "https://my.openvidu.ip",
    "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.16.0",
    "OPENVIDU_RECORDING_PATH": "/opt/openvidu/recordings/",
    "OPENVIDU_RECORDING_PUBLIC_ACCESS": false,
    "OPENVIDU_RECORDING_NOTIFICATION": "moderator",
    "OPENVIDU_RECORDING_CUSTOM_LAYOUT": "/opt/openvidu/custom-layout/",
    "OPENVIDU_RECORDING_AUTOSTOP_TIMEOUT": 60,
    "OPENVIDU_WEBHOOK": true,
    "OPENVIDU_WEBHOOK_ENDPOINT": "http://my.webhook.endpoint:7777/webhook",
    "OPENVIDU_WEBHOOK_HEADERS": [],
    "OPENVIDU_WEBHOOK_EVENTS": [
        "sessionCreated",
        "sessionDestroyed",
        "recordingStatusChanged"
    ],
    "KMS_URIS": [
        "ws://10.1.1.26:8888/kurento",
        "ws://10.1.1.16:8888/kurento"
    ],
    "OPENVIDU_PRO_STATS_MONITORING_INTERVAL": 10,
    "OPENVIDU_PRO_STATS_WEBRTC_INTERVAL": 30,
    "OPENVIDU_PRO_CLUSTER_ID": "MY_CLUSTER",
    "OPENVIDU_PRO_CLUSTER_ENVIRONMENT": "docker",
    "OPENVIDU_PRO_CLUSTER_MEDIA_NODES": 1,
    "OPENVIDU_PRO_CLUSTER_PATH": "/opt/openvidu/cluster/",
    "OPENVIDU_PRO_CLUSTER_AUTOSCALING": true,
    "OPENVIDU_PRO_CLUSTER_AUTOSCALING_MAX_NODES": 3,
    "OPENVIDU_PRO_CLUSTER_AUTOSCALING_MIN_NODES": 2,
    "OPENVIDU_PRO_CLUSTER_AUTOSCALING_MAX_LOAD": 70,
    "OPENVIDU_PRO_CLUSTER_AUTOSCALING_MIN_LOAD": 30,
    "OPENVIDU_PRO_NETWORK_QUALITY": true,
    "OPENVIDU_PRO_NETWORK_QUALITY_INTERVAL": 10,
    "OPENVIDU_PRO_ELASTICSEARCH": true,
    "OPENVIDU_PRO_ELASTICSEARCH_HOST": "http://127.0.0.1:9200",
    "OPENVIDU_PRO_ELASTICSEARCH_VERSION": "7.8.0",
    "OPENVIDU_PRO_KIBANA": true,
    "OPENVIDU_PRO_KIBANA_HOST": "http://127.0.0.1/kibana",
    "OPENVIDU_PRO_KIBANA_VERSION": "7.8.0",
    "OPENVIDU_PRO_RECORDING_STORAGE": "local"
}
HTTP responses 🔗
200 OpenVidu configuration has been successfully retrieved


GET /openvidu/api/health 🔗

Health API is part of OpenViduPRO tier.
Description 🔗

Check the health status of the OpenVidu Pro cluster. An OpenVidu Pro cluster is healthy if OpenVidu Server Pro Node is up and there is at least one Media Node running and connected to the cluster (see OpenVidu Pro architecture).

Operation 🔗
METHOD GET
URL https://YOUR_OPENVIDUSERVER_IP/openvidu/api/health
HEADERS Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Sample return 🔗
{
    "status": "UP"
}
status String Health status of the OpenVidu Pro cluster. Can be UP or DOWN
HTTP responses 🔗
200 Health status is UP
503 Health status is DOWN


POST /openvidu/api/restart 🔗

Restart API is part of OpenViduPRO tier.
Description 🔗

Restart OpenVidu Server Pro programmatically. This helps easily modifying configuration properties and cleaning up any possible stranded process or file.

Operation 🔗
METHOD POST
URL https://YOUR_OPENVIDUSERVER_IP/openvidu/api/restart
HEADERS Authorization: Basic EncodeBase64(OPENVIDUAPP:<YOUR_SECRET>)
Content-Type: application/json
Body 🔗
{
    "OPENVIDU_SECRET":"MY_SECRET",
    "OPENVIDU_CDR":true,
    "OPENVIDU_RECORDING":true,
    "OPENVIDU_RECORDING_PUBLIC_ACCESS":true,
    "OPENVIDU_RECORDING_NOTIFICATION":"publisher_moderator",
    "OPENVIDU_RECORDING_PATH":"/opt/openvidu/recordings",
    "OPENVIDU_RECORDING_CUSTOM_LAYOUT":"/opt/openvidu/custom-layout",
    "OPENVIDU_RECORDING_AUTOSTOP_TIMEOUT":120,
    "OPENVIDU_WEBHOOK":true,
    "OPENVIDU_WEBHOOK_ENDPOINT":"http://localhost:7777/webhook/",
    "OPENVIDU_WEBHOOK_HEADERS":[
        "Authorization: Basic T1BFTlZJRFVBUFA6TVlfU0VDUkVU"
   ],
    "OPENVIDU_WEBHOOK_EVENTS":[
        "recordingStatusChanged"
    ],
    "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_PRO_NETWORK_QUALITY": true,
    "OPENVIDU_PRO_NETWORK_QUALITY_INTERVAL": 5,
    "OPENVIDU_PRO_STATS_WEBRTC_INTERVAL":20
}

The body of the POST request is a JSON object with the new configuration properties to be applied on the restart process. These include OpenVidu CE configuration properties and OpenVidu Pro configuration properties. All of them are optional. Not all properties can be modified this way. Others require a manual update. The complete list of available properties to be modified with this method is listed below. Visit the configuration docs for a detailed description of each one of them.

  • OPENVIDU_CDR (optional Boolean)
  • OPENVIDU_RECORDING (optional Boolean)
  • OPENVIDU_RECORDING_PATH (optional String)
  • OPENVIDU_RECORDING_PUBLIC_ACCESS (optional Boolean)
  • OPENVIDU_RECORDING_NOTIFICATION (optional String)
  • OPENVIDU_RECORDING_CUSTOM_LAYOUT (optional String)
  • OPENVIDU_RECORDING_AUTOSTOP_TIMEOUT (optional Number)
  • OPENVIDU_WEBHOOK (optional Boolean)
  • OPENVIDU_WEBHOOK_ENDPOINT (optional String)
  • OPENVIDU_WEBHOOK_HEADERS: (optional Array of Strings)
  • OPENVIDU_WEBHOOK_EVENTS (optional Array of Strings)
  • OPENVIDU_STREAMS_VIDEO_MAX_RECV_BANDWIDTH (optional Number)
  • OPENVIDU_STREAMS_VIDEO_MIN_RECV_BANDWIDTH (optional Number)
  • OPENVIDU_STREAMS_VIDEO_MAX_SEND_BANDWIDTH (optional Number)
  • OPENVIDU_STREAMS_VIDEO_MIN_SEND_BANDWIDTH (optional Number)
  • OPENVIDU_SESSIONS_GARBAGE_INTERVAL (optional Number)
  • OPENVIDU_SESSIONS_GARBAGE_THRESHOLD (optional Number)
  • OPENVIDU_PRO_CLUSTER_ID (optional String)
  • OPENVIDU_PRO_CLUSTER_MEDIA_NODES (optional Number)
  • OPENVIDU_PRO_CLUSTER_PATH (optional String)
  • OPENVIDU_PRO_CLUSTER_AUTOSCALING (optional Boolean)
  • OPENVIDU_PRO_CLUSTER_AUTOSCALING_MAX_NODES (optional Number)
  • OPENVIDU_PRO_CLUSTER_AUTOSCALING_MIN_NODES (optional Number)
  • OPENVIDU_PRO_CLUSTER_AUTOSCALING_MAX_LOAD (optional Number)
  • OPENVIDU_PRO_CLUSTER_AUTOSCALING_MIN_LOAD (optional Number)
  • OPENVIDU_PRO_NETWORK_QUALITY (optional Boolean)
  • OPENVIDU_PRO_NETWORK_QUALITY_INTERVAL (optional Number)
  • OPENVIDU_PRO_STATS_MONITORING_INTERVAL (optional Number)
  • OPENVIDU_PRO_STATS_WEBRTC_INTERVAL (optional Number)
HTTP responses 🔗
200 The restarting process has been initialized. All properties are valid and OpenVidu Server should restart properly
400 There is some problem with a body parameter. The error message will provide further details

NOTES

This method will restart OpenVidu Server Pro with the new provided configuration parameters. For those parameters for which no value has been provided, the previous existing will be used. The new applied values will be stored in disk in your configuration file, so you will be able to restart the host without losing your new configuration.