 | Poly is a leading provider of communication and collaboration technology, offering a wide range of products and services to enhance the way people connect and work together. One of the key features of Poly's technology is the REST (Representational State Transfer) API, which provides a convenient, scalable, portable, and reliable way to interact with Poly video systems. The REST API allows users to execute certain functions and retrieve information from Poly video systems, enabling greater control and customization of their communication and collaboration experience. This feature is available on a range of Poly MTR Android systems, including the Poly G7500, Poly Studio X70, X50 and X30. In this blogpost, we explore the REST API commands that are available. |
Before using the REST API, it is important to note that administrator credentials are required for access authentication. Poly recommends changing the default administrator password before using the REST API. Additionally, all request and response bodies should be processed as JSON formatted data, and the REST API cannot accept more than 10 MB of data. The REST API feature is always on and cannot be disabled.
The primary audience for the REST API feature is systems integrators who intend to enable configuration and management of system features through integrated systems. However, the REST API can also be useful for advanced users who want to have greater control over their Poly video systems.
The REST API offers a wide range of commands and functions, covering various aspects of the Poly video system. These include audio, calendar, cameras, collaboration, conferences, directory, session, system, SysTracker, video, and diagnostics. Each of these categories includes a range of specific commands and functions, allowing users to fully customize and control their Poly video system.
The System category allows admins to perform maintenance tasks for multiple devices. For example, below is a simple Powershell script to reboot multiple PolyOS devices:
# This is very basic script to reboot Poly OS devices using REST API (PowerShell 6+ required)
$DeviceIPs = @("192.168.0.136";"192.168.0.214";"192.168.0.133")
$DeviceUserName = "admin"
$DevicePassword = "XXXXXXX"
$SessionRequestBody = ConvertTo-Json @{user=$DeviceUserName ; password=$DevicePassword }
$RebootRequestBody = ConvertTo-Json @{action="reboot" }
foreach ($DeviceIP in $DeviceIPs)
{ Invoke-WebRequest -Method 'POST' -Uri ("https://" + $DeviceIP + "/rest/session") -Body $SessionRequestBody -ContentType 'application/json' -SkipCertificateCheck -SessionVariable session
Start-Sleep -Seconds 2
Invoke-WebRequest -Method 'POST' -Uri ("https://" + $DeviceIP + "/rest/system/reboot") -Body $RebootRequestBody -ContentType 'application/json' -SkipCertificateCheck -WebSession $session
Start-Sleep -Seconds 2
}
Running the above script will immediately reboot the devices and output the following:
The primary audience for the REST API feature is systems integrators who intend to enable configuration and management of system features through integrated systems. However, the REST API can also be useful for advanced users who want to have greater control over their Poly video systems.
The REST API offers a wide range of commands and functions, covering various aspects of the Poly video system. These include audio, calendar, cameras, collaboration, conferences, directory, session, system, SysTracker, video, and diagnostics. Each of these categories includes a range of specific commands and functions, allowing users to fully customize and control their Poly video system.
The System category allows admins to perform maintenance tasks for multiple devices. For example, below is a simple Powershell script to reboot multiple PolyOS devices:
# This is very basic script to reboot Poly OS devices using REST API (PowerShell 6+ required)
$DeviceIPs = @("192.168.0.136";"192.168.0.214";"192.168.0.133")
$DeviceUserName = "admin"
$DevicePassword = "XXXXXXX"
$SessionRequestBody = ConvertTo-Json @{user=$DeviceUserName ; password=$DevicePassword }
$RebootRequestBody = ConvertTo-Json @{action="reboot" }
foreach ($DeviceIP in $DeviceIPs)
{ Invoke-WebRequest -Method 'POST' -Uri ("https://" + $DeviceIP + "/rest/session") -Body $SessionRequestBody -ContentType 'application/json' -SkipCertificateCheck -SessionVariable session
Start-Sleep -Seconds 2
Invoke-WebRequest -Method 'POST' -Uri ("https://" + $DeviceIP + "/rest/system/reboot") -Body $RebootRequestBody -ContentType 'application/json' -SkipCertificateCheck -WebSession $session
Start-Sleep -Seconds 2
}
Running the above script will immediately reboot the devices and output the following:
For example, the audio category includes commands for retrieving audio information, performing audio actions, and controlling microphone mute and volume. Below is a sample Powershell script that leverages the audio GET method:
# This is very basic script to get audio info from Poly OS devices using REST API (PowerShell 6+ required)
$DeviceIPs = @("192.168.0.136";"192.168.0.214";"192.168.0.133")
$DeviceUserName = "admin"
$DevicePassword = "XXXXXXX"
$SessionRequestBody = ConvertTo-Json @{user=$DeviceUserName ; password=$DevicePassword }
foreach ($DeviceIP in $DeviceIPs)
{ Invoke-WebRequest -Method "POST" -Uri ("https://" + $DeviceIP + "/rest/session") -Body $SessionRequestBody -ContentType "application/json" -SkipCertificateCheck -SessionVariable SV
Start-Sleep -Seconds 2
Invoke-WebRequest -Method "GET" -Uri ("https://" + $DeviceIP + "/rest/audio") -SkipCertificateCheck -WebSession $SV
Start-Sleep -Seconds 2
}
Running the above script will obtain audio status information:
Content: {"volume":48,"muted":false,"muteLocked":false,"numOfMicsConnected":2}
The output is as shown below:
# This is very basic script to get audio info from Poly OS devices using REST API (PowerShell 6+ required)
$DeviceIPs = @("192.168.0.136";"192.168.0.214";"192.168.0.133")
$DeviceUserName = "admin"
$DevicePassword = "XXXXXXX"
$SessionRequestBody = ConvertTo-Json @{user=$DeviceUserName ; password=$DevicePassword }
foreach ($DeviceIP in $DeviceIPs)
{ Invoke-WebRequest -Method "POST" -Uri ("https://" + $DeviceIP + "/rest/session") -Body $SessionRequestBody -ContentType "application/json" -SkipCertificateCheck -SessionVariable SV
Start-Sleep -Seconds 2
Invoke-WebRequest -Method "GET" -Uri ("https://" + $DeviceIP + "/rest/audio") -SkipCertificateCheck -WebSession $SV
Start-Sleep -Seconds 2
}
Running the above script will obtain audio status information:
Content: {"volume":48,"muted":false,"muteLocked":false,"numOfMicsConnected":2}
The output is as shown below:
The cameras category includes commands for controlling near and far cameras, managing camera presets, and retrieving camera information. Below is a sample script that performs a hide action on the local video:
#This is very basic script to hide local video using REST API (PowerShell 6+ required)
$DeviceIPs = @("192.168.0.136";"192.168.0.214";"192.168.0.133")
$DeviceUserName = "admin"
$DevicePassword = "admin"
$SessionRequestBody = ConvertTo-Json @{user=$DeviceUserName ; password=$DevicePassword }
$VideoRequestBody = ConvertTo-Json @{"mute"=$true }
foreach ($DeviceIP in $DeviceIPs)
{ Invoke-WebRequest -Method 'POST' -Uri ("https://" + $DeviceIP + "/rest/session") -Body $SessionRequestBody -ContentType 'application/json' -SkipCertificateCheck -SessionVariable session
Start-Sleep -Seconds 2
Invoke-WebRequest -Method 'POST' -Uri ("https://" + $DeviceIP + "/rest/video/local/mute") -Body $VideoRequestBody -ContentType 'application/json' -SkipCertificateCheck -WebSession $session
Start-Sleep -Seconds 2
}
The output will provide the result in Content: {"success":true} as per screenshot below:
#This is very basic script to hide local video using REST API (PowerShell 6+ required)
$DeviceIPs = @("192.168.0.136";"192.168.0.214";"192.168.0.133")
$DeviceUserName = "admin"
$DevicePassword = "admin"
$SessionRequestBody = ConvertTo-Json @{user=$DeviceUserName ; password=$DevicePassword }
$VideoRequestBody = ConvertTo-Json @{"mute"=$true }
foreach ($DeviceIP in $DeviceIPs)
{ Invoke-WebRequest -Method 'POST' -Uri ("https://" + $DeviceIP + "/rest/session") -Body $SessionRequestBody -ContentType 'application/json' -SkipCertificateCheck -SessionVariable session
Start-Sleep -Seconds 2
Invoke-WebRequest -Method 'POST' -Uri ("https://" + $DeviceIP + "/rest/video/local/mute") -Body $VideoRequestBody -ContentType 'application/json' -SkipCertificateCheck -WebSession $session
Start-Sleep -Seconds 2
}
The output will provide the result in Content: {"success":true} as per screenshot below:
There are many more REST methods available for different categories and it would not be feasible to provide examples for all. A full list of REST API methods are referenced in the attached document for this blogpost.
In addition to the REST API methods, Poly also offers a range of resources and support for users. The Poly Online Support Center is the entry point for online product, service, and solution support, offering video tutorials, documents and software, a knowledge base, community discussions, Poly University, and additional services. The Poly Document Library provides support documentation for active products, services, and solutions, while the Poly Community offers access to the latest developer and support information.
In addition to the REST API methods, Poly also offers a range of resources and support for users. The Poly Online Support Center is the entry point for online product, service, and solution support, offering video tutorials, documents and software, a knowledge base, community discussions, Poly University, and additional services. The Poly Document Library provides support documentation for active products, services, and solutions, while the Poly Community offers access to the latest developer and support information.
Overall, the REST API feature of Poly products and services offers a powerful and flexible way for users to control and customize their communication and collaboration experience. With a wide range of commands and functions, and extensive support and resources available, the REST API is a valuable tool for systems integrators and advanced users alike.
| video-os-rest-api-4-0-0.pdf |
RSS Feed