Poly VideoOS REST API Reference Guide - Polycom Support

REFERENCE GUIDESoftware 3.0.0 December 2019 3725-86572-001APoly VideoOS REST APIPoly G7500, Studio X50, and Studio X30GETTING HELPFor more information about installing, configuring, andadministering Poly/Poly products or services, go to Poly Support.Plantronics, Inc. (Poly – formerly Plantronics and Poly)345 Encinal StreetSanta Cruz, California95060 2019 Plantronics, Inc. All rights reserved. Poly, the propellerdesign, and the Poly logo are trademarks of Plantronics, Inc. Allother trademarks are the property of their respective owners.Poly, Inc.1

ContentsBefore You Begin . 3Prerequisite Information . 3Audience and Purpose of This Guide . 3Related Poly and Partner Resources . 3REST API Commands . 5Commands and Structure . 5Diagnostics . 128Error Codes . 128Logging . 128Poly, Inc.2

Before You BeginThis guide describes the REST (Representational State Transfer) API feature, which provides aconvenient, scalable, portable, and reliable API for interacting with Poly video systems, enabling users toexecute certain functions and retrieve information.The information this guide applies to all of the following Poly video systems: Poly G7500 Poly Studio X50 Poly Studio X30Prerequisite InformationBefore you begin working with the REST API, note the following: The REST API feature is never disabled. Administrator credentials are required for access authentication before REST API commands canbe sent. Poly recommends changing the default administrator password before using the RESTAPI. All request and response bodies should be processed as JSON formatted data, unless specificallystated otherwise. The REST API cannot accept more than 10 MB of data.Audience and Purpose of This GuideThe primary audience for this manual is systems integrators who intend to enable configuration andmanagement of the system features through integrated systems. This manual is not intended for endusers.Related Poly and Partner ResourcesSee the following sites for information related to this release. The Poly Support Site is the entry point to online product, service, and solution support informationincluding Licensing & Product Registration, Self-Service, Account Management, Product-RelatedLegal Notices, and Documents & Software downloads. The Poly Document Library provides support documentation for active products, services, andsolutions. The documentation displays in responsive HTML5 format so that you can easily accessand view installation, configuration, or administration content from any online device. The Poly Community provides access to the latest developer and support information. Create anaccount to access Poly support personnel and participate in developer and support forums. Youcan find the latest information on hardware, software, and partner solutions topics, share ideas, andsolve problems with your colleagues.Poly, Inc.3

Before You Begin The Poly Partner Network are industry leaders who natively integrate the Poly standards-basedRealPresence Platform with their customers' current UC infrastructures, making it easy for you tocommunicate face-to-face with the applications and devices you use every day. The Poly Collaboration Services help your business succeed and get the most out of yourinvestment through the benefits of collaboration.Poly, Inc.4

REST API CommandsThis section describes the configuration parameters and API commands for Poly videoOS, version 3.0.Commands and StructureAudioaudioDescriptionThis API provides details about the systems audio information.Protocol, Method, andPathProtocol: HTTPSMethod: GETPath: /rest/audioInput and Output SyntaxJSONAccess LevelAdminInputNoneOutputBody:{"muteLocked": false,"muted": true,"numOfMicsConnected": 1,"volume": 62}Applicable return codes200 OK, 500 Server ErrorPoly, Inc.5

REST API CommandsaudioDescriptionThis API performs an audio action on the system related to pressed DTMFcharacters.Protocol, Method, andPathProtocol: HTTPSMethod: POSTPath: /rest/audioInput and Output SyntaxJSONAccess LevelAdminInputBody:{"action": string ,"dtmfChar": string ,"speaker": string }action – The action to complete on the system. Valid strings include “start”,“playDTMF”, “playTestTone”, “stopPlayingTestTone”, and“itpSegmentDetection”.dtmfChar – Characters provided as the DTMF keypad input.speaker – The speaker selection that plays the tone. Valid strings include“SPEAKER LEFT”, “SPEAKER RIGHT”, and “SPEAKER BOTH”.OutputNoneApplicable return codes200 OK, 400 Bad Request, 500 Server ErrorPoly, Inc.6

REST API Commandsaudio/acousticfenceDescriptionThis API performs acoustic fence actions and broadcasts audio fence indicators.Protocol, Method, andPathProtocol: HTTPSMethod: POSTPath: /rest/audio/acousticfenceInput and Output SyntaxJSONAccess LevelAdminInputBody:{"action": string ,"dtmfChar": string ,"speaker": string }action – The action to complete on the system. Valid strings include “start”,“playDTMF”, “playTestTone”, “stopPlayingTestTone”, and“itpSegmentDetection”.dtmfChar – Characters provided as the DTMF keypad input.speaker – The speaker selection to play the tone. Valid strings include“SPEAKER LEFT”, “SPEAKER RIGHT”, and “SPEAKER BOTH”.OutputNoneApplicable return codes200 OK, 400 Bad Request, 500 Server ErrorPoly, Inc.7

REST API Commandsaudio/audiometersDescriptionThis API provides system audio meter information.Protocol, Method, andPathProtocol: HTTPSMethod: GETPath: /rest/audio/audiometersInput and Output SyntaxJSONAccess LevelAdminInputNoneOutputPoly, Inc.Body:{"isValid": false,"levelBack": -20,"levelCenter": -20,"levelLeft": -20,"levelRight": -20,"meterIndex": -1,"nameInstance": -1,"portDirection": "IN","portInstance": 0,"portName": "FAR IN","validChanMode": "left and right"},{"isValid": false,"levelBack": -20,"levelCenter": -20,"levelLeft": -20,"levelRight": -20,"meterIndex": -1,"nameInstance": -1,"portDirection": "IN","portInstance": 1,"portName": "CAMERA MIC","validChanMode": "left and right"},{"isValid": false,"levelBack": -20,"levelCenter": -20,"levelLeft": -20,"levelRight": -20,"meterIndex": 1,"nameInstance": 1,"portDirection": "IN","portInstance": 2,"portName": "IP TABLE MIC",8

REST API Commands"validChanMode": "left and right and center"},{"isValid": false,"levelBack": -20,"levelCenter": -20,"levelLeft": -20,"levelRight": -20,"meterIndex": 2,"nameInstance": 2,"portDirection": "IN","portInstance": 3,"portName": "POLYCOM MIC","validChanMode": "left and right and center"},{"isValid": false,"levelBack": -20,"levelCenter": -20,"levelLeft": -20,"levelRight": -20,"meterIndex": 3,"nameInstance": 3,"portDirection": "IN","portInstance": 4,"portName": "POLYCOM MIC","validChanMode": "left and right and center"},{"isValid": false,"levelBack": -20,"levelCenter": -20,"levelLeft": -20,"levelRight": -20,"meterIndex": 4,"nameInstance": 4,"portDirection": "IN","portInstance": 5,"portName": "POLYCOM MIC","validChanMode": "left and right and center"},{"isValid": false,"levelBack": -20,"levelCenter": -20,"levelLeft": -20,"levelRight": -20,"meterIndex": -1,"nameInstance": -1,"portDirection": "IN","portInstance": 6,"portName": "MIC IP ADAPTER","validChanMode": "left and right"},Poly, Inc.9

REST API Commands{"isValid": false,"levelBack": -20,"levelCenter": -20,"levelLeft": -20,"levelRight": -20,"meterIndex": -1,"nameInstance": -1,"portDirection": "IN","portInstance": 7,"portName": "CAMERA MIC","validChanMode": "left and right"},{"isValid": true,"levelBack": -20,"levelCenter": -20,"levelLeft": -20,"levelRight": -20,"meterIndex": -1,"nameInstance": -1,"portDirection": "IN","portInstance": 9,"portName": "THREE POINT FIVE","validChanMode": "left and right"},{"isValid": true,"levelBack": -20,"levelCenter": -20,"levelLeft": -20,"levelRight": -20,"meterIndex": 1,"nameInstance": 1,"portDirection": "IN","portInstance": 10,"portName": "HDMI","validChanMode": "left and right"},{"isValid": true,"levelBack": -20,"levelCenter": -20,"levelLeft": -20,"levelRight": -20,"meterIndex": -1,"nameInstance": -1,"portDirection": "OUT","portInstance": 0,"portName": "LINE OUT","validChanMode": "left and right"},{"isValid": false,Poly, Inc.10

REST API Commands"levelBack": -20,"levelCenter": -20,"levelLeft": -20,"levelRight": -20,"meterIndex": -1,"nameInstance": -1,"portDirection": "IN","portInstance": 11,"portName": "HEADSET IN","validChanMode": "left and right"},{"isValid": false,"levelBack": -20,"levelCenter": -20,"levelLeft": -20,"levelRight": -20,"meterIndex": -1,"nameInstance": -1,"portDirection": "OUT","portInstance": 1,"portName": "HEADSET OUT","validChanMode": "left and right"}Applicable return codesPoly, Inc.200 OK, 500 Server Error11

REST API Commandsaudio/microphonesDescriptionThis API provides the list of microphones with relevant information for each one.Protocol, Method, andPathProtocol: HTTPSMethod: GETPath: /rest/audio/microphonesInput and Output SyntaxJSONAccess LevelAdminInputNoneOutputBody:{"number": 0,"mute": "boolean","type": 0,"typeInString": "Polycom IP Table Microphone","hwVersion": "string","swVersion": "string","parentID": 0,"state": "MIC STATE GREEN"}Applicable return codes200 OK, 500 Server ErrorPoly, Inc.12

REST API Commandsaudio/mutedDescriptionThis API provides the microphone mute status.Protocol, Method, andPathProtocol: HTTPSMethod: GETPath: /rest/audio/mutedInput and Output SyntaxJSONAccess LevelAdminInputNoneOutputBody: boolean Applicable return codes200 OK, 500 Server ErrorPoly, Inc.13

REST API Commandsaudio/mutedDescriptionThis API performs an audio action on the system to mute or unmute microphones.Protocol, Method, andPathProtocol: HTTPSMethod: POSTPath: /rest/audio/mutedInput and Output SyntaxJSONAccess LevelAdminInputBody: boolean boolean – True mutes the microphones. False unmutes the microphones.OutputNoneApplicable return codes200 OK, 400 Bad Request, 500 Server ErrorPoly, Inc.14

REST API Commandsaudio/volumeDescriptionThis API provides information on the microphone volume level.Protocol, Method, andPathProtocol: HTTPSMethod: GETPath: /rest/audio/volumeInput and Output SyntaxJSONAccess LevelAdminInputNoneOutputBody: integer Applicable return codes200 OK, 500 Server ErrorPoly, Inc.15

REST API Commandsaudio/volumeDescriptionThis API performs an audio action on the system to set volume level.Protocol, Method, andPathProtocol: HTTPSMethod: POSTPath: /rest/audio/volumeInput and Output SyntaxJSONAccess LevelAdminInputBody: integer integer – An integer representing the volume level.OutputNoneApplicable return codes200 OK, 400 Bad Request, 500 Server ErrorPoly, Inc.16

REST API CommandsCalendarcalendarDescriptionThis API provides the status of the meetings calendar server.Protocol, Method, andPathProtocol: HTTPSMethod: GETPath: /rest/calendarInput and Output SyntaxJSONAccess LevelAdminInputNoneOutputBody:{Status: "ONLINE"}Valid status strings include DISABLED, OFFLINE, ONLINE, CONNECTING,ERR AUTHENTICATION, and ERR UNKNOWN.Applicable return codesPoly, Inc.200 OK, 500 Server Error17