BOSE Work Rest API App User Guide

  BOSE Work Rest API App

Introduction

The Bose Videobar devices support representational state transfer application programming interface (REST API) for network management and monitoring. This guide provides instructions for enabling and configuring REST API on Videobar devices, and it provides a detailed description of the supported variables and operations.
Configuration items and operations are grouped in these categories:

• system
• behavior
• usb
• audio
• camera
• audioframing
• bluetooth
• network (VBl)
• wifi
• telemetry (VBl)

The API Command Reference section provides the following information for each object:

• Name/Description Name of the object and description of its use.
• Actions Actions that can be performed on the object. The action can
• be one or more of the following: get, put, delete, post.
• Range of Values Acceptable values for the object.
• Default Value Default value of the object. This is the value that is used if you revert the device to factory defaults.
  All values are specified as strings.

Trademark Notices

• Bose, Bose Work, and Videobar are trademarks of Bose Corporation.
• The Bluetooth” word mark and logos are registered trademarks owned by Bluetooth SIG, Inc. and any use of such marks by Bose Corporation is under license.
• The term HDMI is a trademark or registered trademark of HDMI Licensing Administrator, Inc.
• All other trademarks are the property of their respective owners.

Privacy  Information

Your privacy is important to Bose so we’ve developed a Privacy Policy that covers how we collect, use, disclose, transfer, and store your personal information.
PLEASE READ THIS PRIVACY POLICY CAREFULLY TO UNDERSTAND HOW WE HANDLE YOUR INFORMATION. IF YOU DO NOT AGREE TO THIS PRIVACY POLICY, PLEASE DO NOT USE THE SERVICES.

Enabling and Configuring the REST API

To enable access to the REST API on a device, use the Bose Work Configuration app, the Bose Work Management app, or the Web UI. Access the Network> API settings. Enable API access and specify an API username and password. You will need these API credentials to use any of the REST API commands. Please reference the application user guides for more information.

Testing the REST API

You can test the Videobar REST API by using the Swagger OpenAPI interface that is embedded in the device. To access this interface the Videobar must be connected to an IP network via its wired or WiFi interface, and your host PC must be on the same network or a network that can access the device via HTTPS.
Connect your PC to the Videobar via the USB interface. Start the Bose Work Configuration app and sign in to access admin controls. Choose the Network > API page and click the link:
REST API Documentation (Web UI)
If you are not connected to the device via USB and your PC is on the same network, you can access the REST API via your browser by browsing to the following address:
https:///doc-api

REST API Commands

The Videobar REST API interface uses command IDs in each of the four HTTP methods supported: get, put, delete, and post.
Below is a description of the four methods followed by a table describing the methods supported for each of the commands.

GET

The “get” method accepts a single command ID or multiple comma-delimited IDs. For example, to get the audio.micMute state, the command ID is 2. The URL is like this:
https://192.168.1.40/api?query=2  

The response body is as follows, with a value of “O” indicating the mic is not muted:
{“2”: {“status”: “success”, “value”: “0”}}

To query for multiple values, separate multiple command IDs with a comma. For example, you could query for audio.micMute (ID=2) and system.firmwareVersion (ID=l6) li ke this:
https://192.168.1.40/api?query=2,16 

Note: Do not include spaces between multiple IDs.
The result would be:
{“2”: {“status”: “success”, “value”: “0”}, “16”: {“status”: “success”, “value”: “1.2.13_fd6cc0e”}}

PUT

A “put” command uses a JSON body format with the key being “data” and the value being ID:value pairs.
For example, to set the audio.loudspeakerVolume (ID=3) to 39, the “https://192.168.1.40/ api” body is:
{“data”:”{“3″:”39″}”}

The response is:
{“3”: {“status”: “success”, “code”: “0xe000”}}

Here is an example setting multiple values:
{“data”:”{“2″:”1″,”3″:”70″}”}

The response is:
{“2”: {“status”: “success”, “code”: “0xe000”}, “3”: {“status”: “success”, “code”: “0xe000”}}

Response “code” values can be any of the following:

• 0xe000 : Success
• 0xe001 : Success – No change in value
• 0xe002 : Error – Invalid property
• 0xe003 : Error – Invalid property value
• 0xe004 : Error – Invalid property action
• 0xe005 : Error – Message malformed
• 0xe006 : Error – Access denied

POST

A “post” is similar to “put” and is used for actions, such as toggle mic mute and speaker volume up/down. You specify the command ID and use an empty string for the value.
For example, to increase the speaker volume one tick, use audio.loudspeakerVolumeUp (ID=4) with the body format like this:
{“data”:”{“4″:””}”}

The response body is:
{“4”: {“status”: “success”, “code”: “0xe000”}}
The possible response “code” values are the same those listed for the PUT command.

DELETE

The “delete” command format is similar to “get”, and the response body is similar to “put”. Using delete will set the value back to its default.
For example, to set the audio.loudspeaker volume (ID=3) to its default value, the URL is like this:
https://192.168.1.40/api?delete=3 

The response body is:
{“3”: {“status”: “success”, “code”: “0xe000”}}

You would need to issue a “get” to retrieve the new value, which in this case is 50. For example:
Command:
https://192.168.1.40/api?query=3

Response:
{“3”: {“status”: “success”, “value”: “50”}}
The possible response “code” values are the same those listed for the PUT command

Videobar REST API Command Reference

Name/ Description| Actions| Cmd ID| Range of Values| Default Value
---|---|---|---|---
system.reboot

Reboots the system.

| post| 32| N/A| N/A
system.serialNumber

Serial number of the device.

| get| 10| string

(17 chars)

| ooooooxooooooooxx
system.firmwareVersion

Version of the firmware running on the device. This is set automatically on system firmware upgrade.

| get| 16| string

(1-16 chars)

| 0.0.0
system.model

Model of this device.

| get| D6| string

(1-22 chars)

| Not set
system.name

Name of the device so it can be uniquely identified.

| get put delete| 25| string

(1-22 chars)

| Not set
system.room

Room location of the device

| get put delete| 26| string

(0-128 chars)

| Not set
system.floor

Floor location of the device.

| get put delete| 27| string

(0-128 chars)

| Not set
system.building

Building location of the device.

| get put delete| 28| string

(0-128 chars)

| Not set
system.gpiMuteStatus (VBl)

GPI mute status (on/off).

| get| C7| 110| (Supported in VBl) 0
system.maxOccupancy

Room maximum occupancy of the device.

| get put delete| DF| string

(0-128 chars)

| Not set
behavior.ethernetEnabled (VBl)

Turns on/off the system Ethernet interface.

| get put delete| 38| 110| (Supported in VBl) 1
behavior.bluetoothEnabled

Turns on/off the system Bluetooth.

| get put delete| 3A| 110| 1
behavior.wifiEnabled

Turns on/off the system WiFi.

| get put delete| 3B| 110| 1
behavior.hdmiEnabled (VBl)

Turns on/off the HDMI.

| get put delete| C9| 110| (Supported in VBl) 0
usb.connectionStatus

USB cable connection status; 0 when disconnected.

| get| 36| 110| 0
usb.callStatus

Call status from the host connected to USB port of the system.

| get| 37| 110| 0
audio.micMute

Mutes/unmutes the system microphone.

| get put| 2| 110| 0
audio.micMuteToggle

Toggles the mute state of the system microphone.

| post| 15| N/A| N/A
Name/ Description| Actions| Cmd ID| Range of Values| Default Value
---|---|---|---|---
audio.loudspeakerMute

Mutes/unmutes the system loudspeaker.

| post| 34| N/A| N/A
audio.loudspeakerMuteToggle

Toggles the mute state of the system loudspeaker.

| post| 34| N/A| N/A
audio.loudspeakerVolume

Sets the system loudspeaker volume.

| get put delete| 3| 0-100| 50
audio.loudspeakerVolumeUp

Increases the system loudspeaker volume by one step.

| post| 4| N/A| N/A
audio.loudspeakerVolumeDown

Decreases the system loudspeaker volume by one step.

| post| 5| N/A| N/A
camera.zoom

The camera’s current zoom value.

| get put delete| 6| 1-10| 1
camera.pan

The camera’s current pan value.

| get put delete| 7| -10-10| 0
camera.tilt

The camera’s current tilt value.

| get put delete| 8| -10-10| 0
camera.zoom In

Zooms camera in by one step.

| post| 9| N/A| N/A
camera.zoomOut

Zooms camera out by one step.

| post| OA| N/A| N/A
camera.pan Left

Pans camera left by one step.

| post| OB| N/A| N/A
camera.pan Right

Pans camera right by one step.

| post| oc| N/A| N/A
camera.tiltUp

Tilts camera up by one step.

| post| OD| N/A| N/A
camera.tiltDown

Tilts camera down by one step.

| post| OE| N/A| N/A
camera.homePreset

Camera home preset in pan tilt zoom order

| get put delete| 56|