Archives Moderation Sessions Signaling
 
 

Vonage Video

APIs relating to Vonage Video

Jump to:

Archives »

APIs relating to working with archives

Moderation »

APIs relating to moderating participants

Sessions »

APIs relating to creating and working with Sessions

Signaling »

APIs relating to sending and recieving Signals

List all archives in an application

List all archives in an application

GET https://video.api.vonage.com/v2/project/:application_id/archive
Host https://video.api.vonage.com
GET /v2/project/:application_id/archive

Path Parameters

application_id
string | Required

Vonage Application UUID

Query Parameter

offset
integer

Set an offset query parameters to specify the index offset of the first archive. 0 is offset of the most recently started archive (excluding deleted archive). 1 is the offset of the archive that started prior to the most recent archive. The default value is 0.

count
integer

Set a count query parameter to limit the number of archives to be returned. The default number of archives returned is 50 (or fewer, if there are fewer than 50 archives). The maximum number of archives the call will return is 1000.

session_id
string

Set a sessionId query parameter to list archives for a specific session ID. (This is useful when listing multiple archives for an automatically archived session.)

Responses

200 OK
count
integer

The total number of archives for the API key.

items
array of objects

An array of objects defining each archive retrieved. Archives are listed from the newest to the oldest in the return set.

createdAt
integer

The timestamp for when the archive started recording, expressed in milliseconds since the Unix epoch (January 1, 1970, 00:00:00 UTC).

duration
integer

The duration of the archive in seconds. For archives that have are being recorded (with the status property set to "started"), this value is set to 0.

hasAudio
boolean

Whether the archive will record audio (true, the default) or not (false). If you set both hasAudio and hasVideo to false, the call to this method results in an error.

hasVideo
boolean

Whether the archive will record video (true, the default) or not (false). If you set both hasAudio and hasVideo to false, the call to this method results in an error.

id
string

The unique archive ID.

name
string

The name of the archive (for your own identification)

applicationId
string

Your Vonage application ID

reason
string

For archives with the status "stopped", this can be set to "maximum duration exceeded", "maximum idle time exceeded", "session ended", "user initiated". For archives with the status "failed", this can be set to "failure".

resolution
string

The resolution of the archive, either "640x480" (SD landscape, the default), "1280x720" (HD landscape), "1920x1080" (FHD landscape), "480x640" (SD portrait), "720x1280" (HD portrait), or "1080x1920" (FHD portrait). You may want to use a portrait aspect ratio for archives that include video streams from mobile devices (which often use the portrait aspect ratio). This property only applies to composed archives. If you set this property and set the outputMode property to "individual", the call to the REST method results in an error.

One of: 640x480, 480x640, 1280x720, 720x1280, 1080x1920 or 1920x1080
sessionId
string

The session ID of the Vonage Video session you are working with

size
integer

The size of the archive file. For archives that have not been generated, this value is set to 0.

status
string

The status of the archive:

  • "available" — The archive is available for download from the Vonage Video cloud.
  • "expired" — The archive is no longer available for download from the Vonage Video cloud.
  • "failed" — The archive recording failed.
  • "paused" — When an archive is paused, nothing is recorded. The archive is paused if any of the following conditions occur:

    • No clients are publishing streams to the session. In this case, there is a timeout of 60 minutes, after which the archive stops and the archive status changes to "stopped".
    • All clients disconnect the session. After 60 seconds the archive stops and the archive status changes to "stopped".

    If a client resumes publishing while the archive is in the "paused" state, the archive recording resumes and the status changes back to "started".

  • "started" — The archive started and is in the process of being recorded.

  • "stopped" — The archive stopped recording.

  • "uploaded" — The archive is available for download from the S3 bucket you specified in your Video API account.

One of: available, expired, failed, paused, started, stopped or uploaded
streamMode
string

Whether streams included in the archive are selected automatically ("auto", the default) or manually ("manual"). When streams are selected automatically ("auto"), all streams in the session can be included in the archive. When streams are selected manually ("manual"), you specify streams to be included based on calls to this REST method. You can specify whether a stream's audio, video, or both are included in the archive. In composed archives, in both automatic and manual modes, the archive composer includes streams based on stream prioritization rules.

One of: auto or manual
streams
array of objects
streamId
string

The stream ID of the stream included in the archive.

hasAudio
boolean

Whether the archive will record audio (true, the default) or not (false). If you set both hasAudio and hasVideo to false, the call to this method results in an error.

hasVideo
boolean

Whether the archive will record video (true, the default) or not (false). If you set both hasAudio and hasVideo to false, the call to this method results in an error.

url
string

The download URL of the available archive file. This is only set for an archive with the status set to "available"; for other archives, (including archives with the status "uploaded") this property is set to null. The download URL is obfuscated, and the file is only available from the URL for 10 minutes.

Example Responses

200 403
{
  "count": 1,
  "items": [
    {
      "createdAt": 1384221730000,
      "duration": 5049,
      "hasAudio": true,
      "hasVideo": true,
      "id": "b40ef09b-3811-4726-b508-e41a0f96c68f",
      "name": "Foo",
      "applicationId": "78d335fa-323d-0114-9c3d-d6f0d48968cf",
      "reason": "",
      "resolution": "abc123",
      "sessionId": "flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN",
      "size": 247748791,
      "status": "available",
      "streamMode": "manual",
      "streams": [
        {
          "streamId": "abc123",
          "hasAudio": true,
          "hasVideo": true
        }
      ],
      "url": "https://tokbox.com.archive2.s3.amazonaws.com/123456/09141e29-8770-439b-b180-337d7e637545/archive.mp4"
    }
  ]
}
{
  "code": 403,
  "message": "Authentication error"
}

Create a new archive

Create a new archive

POST https://video.api.vonage.com/v2/project/:application_id/archive
Host https://video.api.vonage.com
POST /v2/project/:application_id/archive

Path Parameters

application_id
string | Required

Vonage Application UUID

Request body application/json

sessionId
string | Required

The session ID of the Vonage Video session you are working with

hasAudio
boolean

Whether the archive will record audio (true, the default) or not (false). If you set both hasAudio and hasVideo to false, the call to this method results in an error.

hasVideo
boolean

Whether the archive will record video (true, the default) or not (false). If you set both hasAudio and hasVideo to false, the call to this method results in an error.

layout
object
type
string

Specify this to assign the initial layout type for the archive. This applies only to composed archives. This object has three properties: type, stylesheet, and screenshareType, which are each strings. Valid values for the layout property are "bestFit" (best fit), "custom" (custom), "horizontalPresentation" (horizontal presentation), "pip" (picture-in-picture), and "verticalPresentation" (vertical presentation)). If you specify a "custom" layout type, set the stylesheet property of the layout object to the stylesheet. (For other layout types, do not set a stylesheet property.) Set the screenshareType property to the layout type to use when there is a screen-sharing stream in the session. (This property is optional.) Note if you set the screenshareType property, you must set the type property to "bestFit" and leave the stylesheet property unset. If you do not specify an initial layout type, the archive uses the best fit layout type.

Must be one of: bestFit, custom, horizontalPresentation, pip or verticalPresentation
stylesheet
string

Used for the custom layout to define the visual layout

screenshareType
string

Set the screenshareType property to the layout type to use when there is a screen-sharing stream in the session. (This property is optional.) Note if you set the screenshareType property, you must set the type property to "bestFit" and leave the stylesheet property unset.

Must be one of: bestFit, custom, horizontalPresentation, pip or verticalPresentation
name
string

The name of the archive (for your own identification)

outputMode
string

Whether all streams in the archive are recorded to a single file ("composed", the default) or to individual files ("individual").

Must be one of: composed or individual
resolution
string

The resolution of the archive, either "640x480" (SD landscape, the default), "1280x720" (HD landscape), "1920x1080" (FHD landscape), "480x640" (SD portrait), "720x1280" (HD portrait), or "1080x1920" (FHD portrait). You may want to use a portrait aspect ratio for archives that include video streams from mobile devices (which often use the portrait aspect ratio). This property only applies to composed archives. If you set this property and set the outputMode property to "individual", the call to the REST method results in an error.

Must be one of: 640x480, 480x640, 1280x720, 720x1280, 1080x1920 or 1920x1080
streamMode
string

Whether streams included in the archive are selected automatically ("auto", the default) or manually ("manual"). When streams are selected automatically ("auto"), all streams in the session can be included in the archive. When streams are selected manually ("manual"), you specify streams to be included based on calls to this REST method. You can specify whether a stream's audio, video, or both are included in the archive. In composed archives, in both automatic and manual modes, the archive composer includes streams based on stream prioritization rules.

Must be one of: auto or manual

Responses

200 Example response
createdAt
integer

The timestamp for when the archive started recording, expressed in milliseconds since the Unix epoch (January 1, 1970, 00:00:00 UTC).

duration
integer

The duration of the archive in seconds. For archives that have are being recorded (with the status property set to "started"), this value is set to 0.

hasAudio
boolean

Whether the archive will record audio (true, the default) or not (false). If you set both hasAudio and hasVideo to false, the call to this method results in an error.

hasVideo
boolean

Whether the archive will record video (true, the default) or not (false). If you set both hasAudio and hasVideo to false, the call to this method results in an error.

id
string

The unique archive ID.

name
string

The name of the archive (for your own identification)

applicationId
string

Your Vonage application ID

reason
string

For archives with the status "stopped", this can be set to "maximum duration exceeded", "maximum idle time exceeded", "session ended", "user initiated". For archives with the status "failed", this can be set to "failure".

resolution
string

The resolution of the archive, either "640x480" (SD landscape, the default), "1280x720" (HD landscape), "1920x1080" (FHD landscape), "480x640" (SD portrait), "720x1280" (HD portrait), or "1080x1920" (FHD portrait). You may want to use a portrait aspect ratio for archives that include video streams from mobile devices (which often use the portrait aspect ratio). This property only applies to composed archives. If you set this property and set the outputMode property to "individual", the call to the REST method results in an error.

One of: 640x480, 480x640, 1280x720, 720x1280, 1080x1920 or 1920x1080
sessionId
string

The session ID of the Vonage Video session you are working with

size
integer

The size of the archive file. For archives that have not been generated, this value is set to 0.

status
string

The status of the archive:

  • "available" — The archive is available for download from the Vonage Video cloud.
  • "expired" — The archive is no longer available for download from the Vonage Video cloud.
  • "failed" — The archive recording failed.
  • "paused" — When an archive is paused, nothing is recorded. The archive is paused if any of the following conditions occur:

    • No clients are publishing streams to the session. In this case, there is a timeout of 60 minutes, after which the archive stops and the archive status changes to "stopped".
    • All clients disconnect the session. After 60 seconds the archive stops and the archive status changes to "stopped".

    If a client resumes publishing while the archive is in the "paused" state, the archive recording resumes and the status changes back to "started".

  • "started" — The archive started and is in the process of being recorded.

  • "stopped" — The archive stopped recording.

  • "uploaded" — The archive is available for download from the S3 bucket you specified in your Video API account.

One of: available, expired, failed, paused, started, stopped or uploaded
streamMode
string

Whether streams included in the archive are selected automatically ("auto", the default) or manually ("manual"). When streams are selected automatically ("auto"), all streams in the session can be included in the archive. When streams are selected manually ("manual"), you specify streams to be included based on calls to this REST method. You can specify whether a stream's audio, video, or both are included in the archive. In composed archives, in both automatic and manual modes, the archive composer includes streams based on stream prioritization rules.

One of: auto or manual
streams
array of objects
streamId
string

The stream ID of the stream included in the archive.

hasAudio
boolean

Whether the archive will record audio (true, the default) or not (false). If you set both hasAudio and hasVideo to false, the call to this method results in an error.

hasVideo
boolean

Whether the archive will record video (true, the default) or not (false). If you set both hasAudio and hasVideo to false, the call to this method results in an error.

url
string

The download URL of the available archive file. This is only set for an archive with the status set to "available"; for other archives, (including archives with the status "uploaded") this property is set to null. The download URL is obfuscated, and the file is only available from the URL for 10 minutes.

Example Request

{
  "sessionId": "flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN"
}
{
  "sessionId": "flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN",
  "hasAudio": true,
  "hasVideo": true,
  "layout": {
    "type": "bestFit",
    "stylesheet": "stream.instructor {position: absolute; width: 100%;  height:50%;}",
    "screenshareType": "pip"
  },
  "name": "Foo",
  "streamMode": "manual"
}

Example Responses

200 400 403 404 409
{
  "createdAt": 1384221730000,
  "duration": 5049,
  "hasAudio": true,
  "hasVideo": true,
  "id": "b40ef09b-3811-4726-b508-e41a0f96c68f",
  "name": "Foo",
  "applicationId": "78d335fa-323d-0114-9c3d-d6f0d48968cf",
  "reason": "",
  "resolution": "abc123",
  "sessionId": "flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN",
  "size": 247748791,
  "status": "available",
  "streamMode": "manual",
  "streams": [
    {
      "streamId": "abc123",
      "hasAudio": true,
      "hasVideo": true
    }
  ],
  "url": "https://tokbox.com.archive2.s3.amazonaws.com/123456/09141e29-8770-439b-b180-337d7e637545/archive.mp4"
}
{
  "code": 400,
  "message": "You do not pass in a session ID or you pass in an invalid session ID."
}
{
  "code": 400,
  "message": "No clients are actively connected to the Vonage Video session."
}
{
  "code": 400,
  "message": "You specify an invalid resolution value."
}
{
  "code": 400,
  "message": "The outputMode property is set to \"individual\" and you set the resolution property and (which is not supported in individual stream archives)."
}
{
  "code": 403,
  "message": "Authentication error"
}
{
  "code": 404,
  "message": "The session does not exist, or the session exists but there are no clients connected to it."
}
{
  "code": 409,
  "message": "You attempted to start an archive for a session that does not use the Vonage Video Media Router."
}
{
  "code": 409,
  "message": "You attempt to start an archive for a session that is already being recorded without setting the multiArchiveTag option"
}
{
  "code": 409,
  "message": "You attempt to start a simultaneous archive for a session without setting a unique multiArchiveTag value."
}

Return archive information for specific archive

Return archive information for specific archive

GET https://video.api.vonage.com/v2/project/:application_id/archive/:archive_id
Host https://video.api.vonage.com
GET /v2/project/:application_id/archive/:archive_id

Path Parameters

application_id
string | Required

Vonage Application UUID

archive_id
string | Required

Archive UUID to use

Responses

200 Example response
createdAt
integer

The timestamp for when the archive started recording, expressed in milliseconds since the Unix epoch (January 1, 1970, 00:00:00 UTC).

duration
integer

The duration of the archive in seconds. For archives that have are being recorded (with the status property set to "started"), this value is set to 0.

hasAudio
boolean

Whether the archive will record audio (true, the default) or not (false). If you set both hasAudio and hasVideo to false, the call to this method results in an error.

hasVideo
boolean

Whether the archive will record video (true, the default) or not (false). If you set both hasAudio and hasVideo to false, the call to this method results in an error.

id
string

The unique archive ID.

name
string

The name of the archive (for your own identification)

applicationId
string

Your Vonage application ID

reason
string

For archives with the status "stopped", this can be set to "maximum duration exceeded", "maximum idle time exceeded", "session ended", "user initiated". For archives with the status "failed", this can be set to "failure".

resolution
string

The resolution of the archive, either "640x480" (SD landscape, the default), "1280x720" (HD landscape), "1920x1080" (FHD landscape), "480x640" (SD portrait), "720x1280" (HD portrait), or "1080x1920" (FHD portrait). You may want to use a portrait aspect ratio for archives that include video streams from mobile devices (which often use the portrait aspect ratio). This property only applies to composed archives. If you set this property and set the outputMode property to "individual", the call to the REST method results in an error.

One of: 640x480, 480x640, 1280x720, 720x1280, 1080x1920 or 1920x1080
sessionId
string

The session ID of the Vonage Video session you are working with

size
integer

The size of the archive file. For archives that have not been generated, this value is set to 0.

status
string

The status of the archive:

  • "available" — The archive is available for download from the Vonage Video cloud.
  • "expired" — The archive is no longer available for download from the Vonage Video cloud.
  • "failed" — The archive recording failed.
  • "paused" — When an archive is paused, nothing is recorded. The archive is paused if any of the following conditions occur:

    • No clients are publishing streams to the session. In this case, there is a timeout of 60 minutes, after which the archive stops and the archive status changes to "stopped".
    • All clients disconnect the session. After 60 seconds the archive stops and the archive status changes to "stopped".

    If a client resumes publishing while the archive is in the "paused" state, the archive recording resumes and the status changes back to "started".

  • "started" — The archive started and is in the process of being recorded.

  • "stopped" — The archive stopped recording.

  • "uploaded" — The archive is available for download from the S3 bucket you specified in your Video API account.

One of: available, expired, failed, paused, started, stopped or uploaded
streamMode
string

Whether streams included in the archive are selected automatically ("auto", the default) or manually ("manual"). When streams are selected automatically ("auto"), all streams in the session can be included in the archive. When streams are selected manually ("manual"), you specify streams to be included based on calls to this REST method. You can specify whether a stream's audio, video, or both are included in the archive. In composed archives, in both automatic and manual modes, the archive composer includes streams based on stream prioritization rules.

One of: auto or manual
streams
array of objects
streamId
string

The stream ID of the stream included in the archive.

hasAudio
boolean

Whether the archive will record audio (true, the default) or not (false). If you set both hasAudio and hasVideo to false, the call to this method results in an error.

hasVideo
boolean

Whether the archive will record video (true, the default) or not (false). If you set both hasAudio and hasVideo to false, the call to this method results in an error.

url
string

The download URL of the available archive file. This is only set for an archive with the status set to "available"; for other archives, (including archives with the status "uploaded") this property is set to null. The download URL is obfuscated, and the file is only available from the URL for 10 minutes.

Example Responses

200 400 403
{
  "createdAt": 1384221730000,
  "duration": 5049,
  "hasAudio": true,
  "hasVideo": true,
  "id": "b40ef09b-3811-4726-b508-e41a0f96c68f",
  "name": "Foo",
  "applicationId": "78d335fa-323d-0114-9c3d-d6f0d48968cf",
  "reason": "",
  "resolution": "abc123",
  "sessionId": "flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN",
  "size": 247748791,
  "status": "available",
  "streamMode": "manual",
  "streams": [
    {
      "streamId": "abc123",
      "hasAudio": true,
      "hasVideo": true
    }
  ],
  "url": "https://tokbox.com.archive2.s3.amazonaws.com/123456/09141e29-8770-439b-b180-337d7e637545/archive.mp4"
}
{
  "code": 400,
  "message": "You do not pass in a session ID or you pass in an invalid archive ID."
}
{
  "code": 403,
  "message": "You passed in an invalid JWT token."
}

Delete an archive

Delete an archive

DELETE https://video.api.vonage.com/v2/project/:application_id/archive/:archive_id
Host https://video.api.vonage.com
DELETE /v2/project/:application_id/archive/:archive_id

Path Parameters

application_id
string | Required

Vonage Application UUID

archive_id
string | Required

Archive UUID to use

Example Responses

204 403 409
No Content
{
  "code": 403,
  "message": "You passed in an invalid JWT token."
}
{
  "code": 409,
  "message": "Status of the archive is not \"uploaded\", \"available\", or \"deleted\""
}

Add or remove a stream from an archive

Use this method to change the streams included in a composed archive that was started with the streamMode set to "manual"

PATCH https://video.api.vonage.com/v2/project/:application_id/archive/:archive_id/streams
Host https://video.api.vonage.com
PATCH /v2/project/:application_id/archive/:archive_id/streams

Path Parameters

application_id
string | Required

Vonage Application UUID

archive_id
string | Required

Archive UUID to use

Request body application/json

removeStream
string | Required

Stream ID to remove from the archive

addStream
string | Required

The Stream ID

hasAudio
boolean

Whether the composed archive should include the stream's audio (true, the default) or not (false)

hasVideo
boolean

Whether the composed archive should include the stream's video (true, the default) or not (false).

Example Request » Remove Stream

{
  "removeStream": "12312312-3811-4726-b508-e41a0f96c68f"
}

Example Request » Add Stream

{
  "addStream": "12312312-3811-4726-b508-e41a0f96c68f"
}
{
  "addStream": "12312312-3811-4726-b508-e41a0f96c68f",
  "hasAudio": true,
  "hasVideo": true
}

Example Responses

204 400 403 404
No Content
{
  "code": 400,
  "message": "Invalid request. This response may indicate that data provided in your request is an invalid JSON, or the request couldn't be fulfilled because the archive was started with streamMode set to \"auto\", which does not support stream manipulation."
}
{
  "code": 403,
  "message": "Authentication error."
}
{
  "code": 404,
  "message": "Archive or stream not found"
}

Stop an archive

To stop recording an archive, submit an HTTP POST request.

Archives stop recording after 4 hours (14,400 seconds), or 60 seconds after the last client disconnects from the session, or 60 minutes after the last client stops publishing. However, automatic archives continue recording to multiple consecutive files of up to 4 hours in length each. For more information, see Archive duration

Calling this method for automatic archives has no effect. Automatic archives continue recording to multiple consecutive files of up to 4 hours (14,400 seconds) in length each, until 60 seconds after the last client disconnects from the session, or 60 minutes after the last client stops publishing a stream to the session.

POST https://video.api.vonage.com/v2/project/:application_id/archive/:archive_id/stop
Host https://video.api.vonage.com
POST /v2/project/:application_id/archive/:archive_id/stop

Path Parameters

application_id
string | Required

Vonage Application UUID

archive_id
string | Required

Archive UUID to use

Responses

200 Example response
createdAt
integer

The timestamp for when the archive started recording, expressed in milliseconds since the Unix epoch (January 1, 1970, 00:00:00 UTC).

duration
integer

The duration of the archive in seconds. For archives that have are being recorded (with the status property set to "started"), this value is set to 0.

hasAudio
boolean

Whether the archive will record audio (true, the default) or not (false). If you set both hasAudio and hasVideo to false, the call to this method results in an error.

hasVideo
boolean

Whether the archive will record video (true, the default) or not (false). If you set both hasAudio and hasVideo to false, the call to this method results in an error.

id
string

The unique archive ID.

name
string

The name of the archive (for your own identification)

applicationId
string

Your Vonage application ID

reason
string

For archives with the status "stopped", this can be set to "maximum duration exceeded", "maximum idle time exceeded", "session ended", "user initiated". For archives with the status "failed", this can be set to "failure".

resolution
string

The resolution of the archive, either "640x480" (SD landscape, the default), "1280x720" (HD landscape), "1920x1080" (FHD landscape), "480x640" (SD portrait), "720x1280" (HD portrait), or "1080x1920" (FHD portrait). You may want to use a portrait aspect ratio for archives that include video streams from mobile devices (which often use the portrait aspect ratio). This property only applies to composed archives. If you set this property and set the outputMode property to "individual", the call to the REST method results in an error.

One of: 640x480, 480x640, 1280x720, 720x1280, 1080x1920 or 1920x1080
sessionId
string

The session ID of the Vonage Video session you are working with

size
integer

The size of the archive file. For archives that have not been generated, this value is set to 0.

status
string

The status of the archive:

  • "available" — The archive is available for download from the Vonage Video cloud.
  • "expired" — The archive is no longer available for download from the Vonage Video cloud.
  • "failed" — The archive recording failed.
  • "paused" — When an archive is paused, nothing is recorded. The archive is paused if any of the following conditions occur:

    • No clients are publishing streams to the session. In this case, there is a timeout of 60 minutes, after which the archive stops and the archive status changes to "stopped".
    • All clients disconnect the session. After 60 seconds the archive stops and the archive status changes to "stopped".

    If a client resumes publishing while the archive is in the "paused" state, the archive recording resumes and the status changes back to "started".

  • "started" — The archive started and is in the process of being recorded.

  • "stopped" — The archive stopped recording.

  • "uploaded" — The archive is available for download from the S3 bucket you specified in your Video API account.

One of: available, expired, failed, paused, started, stopped or uploaded
streamMode
string

Whether streams included in the archive are selected automatically ("auto", the default) or manually ("manual"). When streams are selected automatically ("auto"), all streams in the session can be included in the archive. When streams are selected manually ("manual"), you specify streams to be included based on calls to this REST method. You can specify whether a stream's audio, video, or both are included in the archive. In composed archives, in both automatic and manual modes, the archive composer includes streams based on stream prioritization rules.

One of: auto or manual
streams
array of objects
streamId
string

The stream ID of the stream included in the archive.

hasAudio
boolean

Whether the archive will record audio (true, the default) or not (false). If you set both hasAudio and hasVideo to false, the call to this method results in an error.

hasVideo
boolean

Whether the archive will record video (true, the default) or not (false). If you set both hasAudio and hasVideo to false, the call to this method results in an error.

url
string

The download URL of the available archive file. This is only set for an archive with the status set to "available"; for other archives, (including archives with the status "uploaded") this property is set to null. The download URL is obfuscated, and the file is only available from the URL for 10 minutes.

Example Responses

200 400 403 404 409
{
  "createdAt": 1384221730000,
  "duration": 5049,
  "hasAudio": true,
  "hasVideo": true,
  "id": "b40ef09b-3811-4726-b508-e41a0f96c68f",
  "name": "Foo",
  "applicationId": "78d335fa-323d-0114-9c3d-d6f0d48968cf",
  "reason": "",
  "resolution": "abc123",
  "sessionId": "flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN",
  "size": 247748791,
  "status": "available",
  "streamMode": "manual",
  "streams": [
    {
      "streamId": "abc123",
      "hasAudio": true,
      "hasVideo": true
    }
  ],
  "url": "https://tokbox.com.archive2.s3.amazonaws.com/123456/09141e29-8770-439b-b180-337d7e637545/archive.mp4"
}
{
  "code": 400,
  "message": "You did not pass a Session ID or you passed an invalid Session ID"
}
{
  "code": 403,
  "message": "You passed an invalid JWT token"
}
{
  "code": 404,
  "message": "You passed an invalid archive ID"
}
{
  "code": 409,
  "message": "You attempted to stop an archive that was not being recorded"
}

Change the layout of an archive

You can dynamically change the layout type of a composed archive while it is being recorded.

PUT https://video.api.vonage.com/v2/project/:application_id/archive/:archive_id/layout
Host https://video.api.vonage.com
PUT /v2/project/:application_id/archive/:archive_id/layout

Path Parameters

application_id
string | Required

Vonage Application UUID

archive_id
string | Required

Archive UUID to use

Request body application/json

type
string

Specify this to assign the initial layout type for the archive. This applies only to composed archives. This object has three properties: type, stylesheet, and screenshareType, which are each strings. Valid values for the layout property are "bestFit" (best fit), "custom" (custom), "horizontalPresentation" (horizontal presentation), "pip" (picture-in-picture), and "verticalPresentation" (vertical presentation)). If you specify a "custom" layout type, set the stylesheet property of the layout object to the stylesheet. (For other layout types, do not set a stylesheet property.) Set the screenshareType property to the layout type to use when there is a screen-sharing stream in the session. (This property is optional.) Note if you set the screenshareType property, you must set the type property to "bestFit" and leave the stylesheet property unset. If you do not specify an initial layout type, the archive uses the best fit layout type.

Must be one of: bestFit, custom, horizontalPresentation, pip or verticalPresentation
stylesheet
string

Used for the custom layout to define the visual layout

screenshareType
string

Set the screenshareType property to the layout type to use when there is a screen-sharing stream in the session. (This property is optional.) Note if you set the screenshareType property, you must set the type property to "bestFit" and leave the stylesheet property unset.

Must be one of: bestFit, custom, horizontalPresentation, pip or verticalPresentation

Example Request

{
  "type": "bestFit",
  "stylesheet": "stream.instructor {position: absolute; width: 100%;  height:50%;}",
  "screenshareType": "pip"
}

Example Responses

200 400 403

This endpoint does not support application/json

{
  "code": 400,
  "message": "Invalid request. This response may indicate that data in your request data is invalid JSON. It may also indicate that you passed in invalid layout options."
}
{
  "code": 403,
  "message": "Authentication error."
}

Moderation

APIs relating to moderating participants

Available Operations:

Force a connection to disconnect

Force a client to disconnect from a session

DELETE https://video.api.vonage.com/v2/project/:application_id/session/:session_id/connection/:connection_id
Host https://video.api.vonage.com
DELETE /v2/project/:application_id/session/:session_id/connection/:connection_id

Path Parameters

application_id
string | Required

Vonage Application UUID

session_id
string | Required

Video session ID

connection_id
string | Required

Specific publisher connection ID

Example Responses

200 400 403 404

This endpoint does not support application/json

{
  "code": 400,
  "message": "One of the arguments — sessionId or connectionId — is invalid."
}
{
  "code": 403,
  "message": "You are not authorized to forceDisconnect, check your authentication credentials."
}
{
  "code": 403,
  "message": "The client specified by the connectionId property is not connected to the session."
}

Mute a specific stream

Force mute a specific publisher stream

POST https://video.api.vonage.com/v2/project/:application_id/session/:session_id/stream/:stream_id/mute
Host https://video.api.vonage.com
POST /v2/project/:application_id/session/:session_id/stream/:stream_id/mute

Path Parameters

application_id
string | Required

Vonage Application UUID

session_id
string | Required

Video session ID

stream_id
string | Required

Stream ID

Responses

200 Project Details
applicationId
string

The Vonage application ID

status
string

Whether the project is active ("ACTIVE") or suspended ("SUSPENDED")

name
string

The name, if you specified one when creating the project; or an empty string if you did not specify a name

environment
string

This is set to "standard" or "enterprise", and it refers to the environment a project is running on. Enterprise package partners have access to the enterprise environment.

createdAt
integer

The time at which the project was created (a UNIX timestamp, in milliseconds)

Example Responses

200 400 403 404
{
  "applicationId": "78d335fa-323d-0114-9c3d-d6f0d48968cf",
  "status": "ACTIVE",
  "name": "Joe Montana",
  "environment": "standard",
  "createdAt": 1414642898000
}
{
  "code": 400,
  "message": "Invalid request"
}
{
  "code": 403,
  "message": "Authentication error"
}
{
  "code": 404,
  "message": "Not found. The session or stream is not found"
}

Mute multiple participants in a session

You can use the Vonage Video REST API to force all streams (except for an optional list of streams) in a session to mute published audio. You can also use this method to disable the force mute state of a session (see below).

POST https://video.api.vonage.com/v2/project/:application_id/session/:session_id/mute
Host https://video.api.vonage.com
POST /v2/project/:application_id/session/:session_id/mute

Path Parameters

application_id
string | Required

Vonage Application UUID

session_id
string | Required

Video session ID

Request body application/json

active
boolean | Required

Whether to mute streams in the session (true) and enable the mute state of the session, or to disable the mute state of the session (false). With the mute state enabled (true), all current and future streams published to the session (with the exception of streams in the excludedStreamIds array) are muted. When you call this method with the active property set to false, future streams published to the session are not muted (but any existing muted streams remain muted).

excludedStreamIds
array of strings | Required

The stream IDs for streams that should not be muted. This is an optional property. If you omit this property, all streams in the session will be muted. This property only applies when the active property is set to true. When the active property is set to false, it is ignored.

The elements in the excludedStreamIds array are stream IDs (strings) for the streams you wish to exclude from being muted.

If you do not wish to include an array of excluded streams, do not include any body content.

Responses

200 Project Details
applicationId
string

The Vonage application ID

status
string

Whether the project is active ("ACTIVE") or suspended ("SUSPENDED")

name
string

The name, if you specified one when creating the project; or an empty string if you did not specify a name

environment
string

This is set to "standard" or "enterprise", and it refers to the environment a project is running on. Enterprise package partners have access to the enterprise environment.

createdAt
integer

The time at which the project was created (a UNIX timestamp, in milliseconds)

Example Request

{
  "active": true,
  "excludedStreamIds": [
    "excludedStream1",
    "excludedStream2"
  ]
}

Example Responses

200 400 403 404
{
  "applicationId": "78d335fa-323d-0114-9c3d-d6f0d48968cf",
  "status": "ACTIVE",
  "name": "Joe Montana",
  "environment": "standard",
  "createdAt": 1414642898000
}
{
  "code": 400,
  "message": "Invalid request. This response may indicate that data in your request data is invalid JSON."
}
{
  "code": 403,
  "message": "Authentication error"
}
{
  "code": 404,
  "message": "Not found. The session or stream is not found"
}

Sessions

APIs relating to creating and working with Sessions

Available Operations:

Create New Session

Generate a new session.

POST https://video.api.vonage.com/session/create
Host https://video.api.vonage.com
POST /session/create

Request body application/x-www-form-urlencoded

archiveMode
string

Set to always to have the session archived automatically. With the archiveModeset to manual (the default), you can archive the session by calling the REST /archive POST method. If you set the archiveMode to always, you must also set the p2p.preference parameter to disabled (the default).

location
string

The IP address that the Vonage Video APi will use to situate the session in its global network. If no location hint is passed in (which is recommended), the session uses a media server based on the location of the first client connecting to the session. Pass a location hint in only if you know the general geographic region (and a representative IP address) and you think the first client connecting may not be in that region. Specify an IP address that is representative of the geographical location for the session.

p2p.preference
string

Set to enabled if you prefer clients to attempt to send audio-video streams directly to other clients; set to disabled for sessions that use the Vonage Video Media Router. (Optional; the default setting is disabled -- the session uses the Vonage Video Media Router.)

Responses

200 Sample Response when creating a new session
session_id
string
application_id
string
create_dt
string
media_server_url
string

Example Request

POST /session/create HTTP/1.1
Host: video.api.vonage.com 
Content-Type: application/x-www-form-urlencoded
Content-Length: 0

Example Responses

200
[
  {
    "session_id": "abc123",
    "application_id": "abc123",
    "create_dt": "abc123",
    "media_server_url": "abc123"
  }
]

Get layout information about a stream

Use this method to get information on an Vonage Video stream

For example, you can call this method to get information about layout classes used by an Vonage Video stream. The layout classes define how the stream is displayed in the layout of a broadcast stream.

GET https://video.api.vonage.com/v2/project/:application_id/session/:session_id/stream/:stream_id
Host https://video.api.vonage.com
GET /v2/project/:application_id/session/:session_id/stream/:stream_id

Path Parameters

application_id
string | Required

Vonage Application UUID

session_id
string | Required

Video session ID

stream_id
string | Required

Stream ID

Responses

200 Information about a stream's layout
id
string

The Stream ID

videoType
string

Set to "camera", "screen", or "custom". A "screen" video uses screen sharing on the publisher as the video source; a "custom" video is published by a web client using an HTML VideoTrack element as the video source.

name
string

The stream name (if one was set when the client published the stream).

layoutClassList
array of strings

An array of the layout classes for the stream.

Example Responses

200 400 403 404 408
{
  "id": "8b732909-0a06-46a2-8ea8-074e64d43422",
  "videoType": "camera",
  "name": "",
  "layoutClassList": [
    "full"
  ]
}
{
  "code": 400,
  "message": "Invalid request. This response may indicate that data in your request data is invalid JSON. Or it may indicate that you do not pass in a session ID or you passed in an invalid stream ID."
}
{
  "code": 403,
  "message": "You passed in an invalid Vonage JWT token."
}
{
  "code": 404,
  "message": "The session exists but has not had any streams added to it yet."
}
{
  "code": 408,
  "message": "You passed in an invalid stream ID."
}

Get information about all connected stream layouts

Use this method to get information on all Vonage Video streams in a session

For example, you can call this method to get information about layout classes used by an Vonage Video stream. The layout classes define how the stream is displayed in the layout of a broadcast stream.

GET https://video.api.vonage.com/v2/project/:application_id/session/:session_id/stream
Host https://video.api.vonage.com
GET /v2/project/:application_id/session/:session_id/stream

Path Parameters

application_id
string | Required

Vonage Application UUID

session_id
string | Required

Video session ID

Responses

200 Information about multiple streams layout config
count
integer

Number of items in the response

items
array of objects

Stream layouts for requested session IDs

id
string

The Stream ID

videoType
string

Set to "camera", "screen", or "custom". A "screen" video uses screen sharing on the publisher as the video source; a "custom" video is published by a web client using an HTML VideoTrack element as the video source.

name
string

The stream name (if one was set when the client published the stream).

layoutClassList
array of strings

An array of the layout classes for the stream.

Example Responses

200 400 403 404 408
{
  "count": 1,
  "items": [
    {
      "id": "8b732909-0a06-46a2-8ea8-074e64d43422",
      "videoType": "camera",
      "name": "",
      "layoutClassList": [
        "full"
      ]
    }
  ]
}
{
  "code": 400,
  "message": "Invalid request. This response may indicate that data in your request data is invalid JSON. Or it may indicate that you do not pass in a session ID or you passed in an invalid stream ID."
}
{
  "code": 403,
  "message": "You passed in an invalid Vonage JWT token."
}
{
  "code": 404,
  "message": "The session exists but has not had any streams added to it yet."
}
{
  "code": 408,
  "message": "You passed in an invalid stream ID."
}

Change the layout of a stream

Use this method to change layout classes for an Vonage Video stream. The layout classes define how the stream is displayed in the layout of a composed Vonage Video archive.

PUT https://video.api.vonage.com/v2/project/:application_id/session/:session_id/stream
Host https://video.api.vonage.com
PUT /v2/project/:application_id/session/:session_id/stream

Path Parameters

application_id
string | Required

Vonage Application UUID

session_id
string | Required

Video session ID

Request body application/json

items
array of objects | Required

Array of stream IDs and their new class lists

id
string

Array of stream IDs and their new class lists

layoutClassList
array of strings

Array of class names as strings

Example Request

{
}
{
  "items": [
    {
      "id": "8b732909-0a06-46a2-8ea8-074e64d43422",
      "layoutClassList": [
        "full"
      ]
    }
  ]
}

Example Responses

200 400 403

This endpoint does not support application/json

{
  "code": 400,
  "message": "Invalid request. This response may indicate that data in your request data is invalid JSON. It may also indicate that you passed in invalid layout options."
}
{
  "code": 403,
  "message": "Authentication error"
}

Signaling

APIs relating to sending and recieving Signals

Available Operations:

Send a signal to all participants

Use the Signal REST API to send signals to all participants in an active Vonage Video session or to a specific client connected to that session. Signals sent from the server have an empty from parameter in the signal received handlers on clients connected to the session. For a signal sent from a participant in the session, the from property is set the connection ID of the client that sent the signal, but in this case there is no associated connection.

POST https://video.api.vonage.com/v2/project/:application_id/session/:session_id/signal
Host https://video.api.vonage.com
POST /v2/project/:application_id/session/:session_id/signal

Path Parameters

application_id
string | Required

Vonage Application UUID

session_id
string | Required

Video session ID

Request body application/json

type
string | Required

Type of data that is being sent to the client. This cannot exceed 128 bytes.

data
string | Required

Payload that is being sent to the client. This cannot exceed 8kb.

Example Request

{
  "type": "chat",
  "data": "Text of the chat message"
}

Example Responses

200 400 403 404 413

This endpoint does not support application/json

{
  "code": 400,
  "message": "One of the signal properties — data, type, sessionId or connectionId — is invalid."
}
{
  "code": 403,
  "message": "You are not authorized to send the signal. Check your authentication credentials."
}
{
  "code": 404,
  "message": "The client specified by the connectionId property is not connected to the session."
}
{
  "code": 413,
  "message": "The type string exceeds the maximum length (128 bytes), or the data string exceeds the maximum size (8 kB)."
}

Send signal to a specific participant

Send signals to a specific participant in an active Vonage Video session

POST https://video.api.vonage.com/v2/project/:application_id/session/:session_id/connection/:connection_id/signal
Host https://video.api.vonage.com
POST /v2/project/:application_id/session/:session_id/connection/:connection_id/signal

Path Parameters

application_id
string | Required

Vonage Application UUID

session_id
string | Required

Video session ID

connection_id
string | Required

Specific publisher connection ID

Request body application/json

type
string | Required

Type of data that is being sent to the client. This cannot exceed 128 bytes.

data
string | Required

Payload that is being sent to the client. This cannot exceed 8kb.

Example Request

{
  "type": "chat",
  "data": "Text of the chat message"
}

Example Responses

200 400 403 404 413

This endpoint does not support application/json

{
  "code": 400,
  "message": "One of the signal properties — data, type, sessionId or connectionId — is invalid."
}
{
  "code": 403,
  "message": "You are not authorized to send the signal. Check your authentication credentials."
}
{
  "code": 404,
  "message": "The client specified by the connectionId property is not connected to the session."
}
{
  "code": 413,
  "message": "The type string exceeds the maximum length (128 bytes), or the data string exceeds the maximum size (8 kB)."
}