...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
Base URL for these endpoints: https://ws.bsn.cloud/rest/v1/
_________________________________________________________________________
GET /diagnostics/
Runs network diagnostics on the player
Request Example
| Code Block |
|---|
GET /rest/v1/diagnostics/?destinationType=player&destinationName={{deviceSerial}} HTTP/1.1
Host: ws.bsn.cloud
Authorization: Bearer {{UserAccessToken}}
Accept: application/json, application/vnd.bsn.error+json |
Response Body
...
ethernet string:
diagnosisstring: Indicates if this type of interface is presentlogobject[ ]: This contains the diagnostic results for the ethernet interface. It has fields for name, pass, and result.namestring: The name of the diagnostic testpassbool: Indicates whether the test passed or notresultstring: The actual value for the diagnostic tests like checking type and ping.
okbool: If diagnostics were run on the interface or not.
wifi string:
...
Base URL for these endpoints: https://ws.bsn.cloud/rest/v1/
_________________________________________________________________________
GET /diagnostics/
Runs network diagnostics on the player
Request Example
| Code Block |
|---|
GET /rest/v1/diagnostics/?destinationType=player&destinationName={{deviceSerial}} HTTP/1.1
Host: ws.bsn.cloud
Authorization: Bearer {{UserAccessToken}}
Accept: application/json, application/vnd.bsn.error+json |
Response Body
For each of ethernet, wifi, modem, and internet:
diagnosisstring: Indicates if this type of interface is presentlogobject[ ]: This contains the diagnostic results for the
...
interface:
namestring: The name of the diagnostic testpassbool: Indicates whether the test passed or notresultstring: The actual value for the diagnostic tests like checking type and ping.
okbool: If diagnostics were run on the interface or not.
...
modem string:
diagnosisstring: Indicates if this type of interface is presentlogobject[ ]: This contains the diagnostic results for the modem interface. It has fields for name, pass, and result.namestring: The name of the diagnostic testpassbool: Indicates whether the test passed or notresultstring: The actual value for the diagnostic tests like checking type and ping.
okbool: If diagnostics were run on the interface or not.
...
internet string:
diagnosisstring: Indicates if this type of interface is presentlogobject[ ]: This contains the diagnostic results for the internet connectivity. It has fields for info, name, pass, and result.infostring: Returns DNS server infonamestring: Checks DNS servers and internet connectivitypassbool: Indicates whether the test passed or notresultstring: The actual value for the diagnostic tests like checking type and ping.
okbool: If diagnostics were run on the interface or not.
Response Example
...
| title | Expand to see response information: |
|---|
...
| language | json |
|---|
...
Response Example
| Expand | |||||
|---|---|---|---|---|---|
| |||||
|
...
|
...
|
...
|
...
|
...
|
...
|
...
Endpoints:
...
...
GET /diagnostics/dns-lookup/{:domain_name}/
Tests name resolution on the specified DNS address
Segment
domain_name: The DNS address (for example, google.com)
Request Example
| Code Block |
|---|
GET /rest/v1/diagnostics/dns-lookup/google.com/?destinationType=player&destinationName={{deviceSerial}} HTTP/1.1
Host: ws.bsn.cloud
Authorization: Bearer {{UserAccessToken}}
Accept: application/json, application/vnd.bsn.error+json |
Response Body
The player queries each DNS field separately, then collects returned data into the records object and returned errors into the errorList object. The following DNS fields are queried: "ipv4", "ipv6", "cname", "mx", "service", "text".
recordsobject:ipv4string[ ]: IPv4 addressesipv6string[ ]: IPv6 addressestextstring[ ]: Text recordsmxobject[ ]: Mail exchange recordsexchangestringpriorityint
server_testobjecttcpobjectmadeint: The total number of DNS requests madepassint: The total number of requests that passedfailint: The total number of requests that failed.timeoutint: The total number of requests that timed out.mismatchint: The total number of mismatched requests between the host and pointer records
udpobjectmadeint: The total number of DNS requests madepassint: The total number of requests that passedfailint: The total number of requests that failed.timeoutint: The total number of requests that timed out.mismatchint: The total number of mismatched requests between the host and pointer records
errorListobject[ ]fieldstring
...
: The field ('ipv4', 'ipv6', 'cname', 'mx', 'service', or 'text') where the error came from
errobject:errnostring: Error number (usually the same value as code)codestring: Error code number (see DNS | Node.js v14.21.3 Documentation)syscallstring: Information about the system call stackhostnamestring: The value passed in the URL
Response Example
| Code Block | ||
|---|---|---|
| ||
{
"route": "/v1/diagnostics/dns-lookup/google.com",
"method": "GET",
"data": {
"result": {
"records": {
"ipv4": [
"142.250.105.113",
"142.250.105.102",
"142.250.105.139",
"142.250.105.101",
"142.250.105.138",
"142.250.105.100"
],
"ipv6": [
"2607:f8b0:4002:c0c::8a",
"2607:f8b0:4002:c0c::8b",
"2607:f8b0:4002:c0c::71",
"2607:f8b0:4002:c0c::64"
],
"mx": [
{
"exchange": "smtp.google.com",
"priority": 10
}
]
},
"server_test": {
"tcp": {
"made": 100,
"pass": 100,
"fail": 0,
"timeout": 0,
"mismatch": 0
},
"udp": {
"made": 100,
"pass": 100,
"fail": 0,
"timeout": 0,
"mismatch": 0
}
},
"errorList": [
{
"field": "cname",
"err": {
"code": "ENODATA",
"syscall": "queryCname",
"hostname": "google.com"
}
},
{
"field": "service",
"err": {
"code": "ENODATA",
"syscall": "querySrv",
"hostname": "google.com"
}
},
{
"field": "text",
"err": {
"code": "ETIMEOUT",
"syscall": "queryTxt",
"hostname": "google.com"
}
}
]
}
}
} |
GET /diagnostics/ping/{:domain_name}/
Requests the player to ping the specified IP or DNS address on its local network. This call can take over 10 seconds to return.
Segment
domain_name: The specified IP or DNS address
Request Example
| Code Block |
|---|
GET /rest/v1/diagnostics/ping/0.0.0.0/?destinationType=player&destinationName={{deviceSerial}} HTTP/1.1
Host: ws.bsn.cloud
Authorization: Bearer {{UserAccessToken}}
Accept: application/json, application/vnd.bsn.error+json |
Response Body
successbool: A flag that indicates if the operation succeeded or notresponseobject:hostnamestring: The value that you passed in the URLresultsobject:ipv4object[ ]:addressstring: The IPv4 address that is pingedresultsobject:receivedint: The number of packets receivedstatsobject:averageint: The average time for the packet to returnquickestint: The quickest time for packet to returnslowestint: The slowest time for the packet to returnunitsint: The time units (usually microseconds)
transmittedint: The number of packets transmitted
ipv6object[ ]: This will only be returned if IPv6 is present.interfacestringsourcestringaddressstring: The IPv6 address that is pingedresultsobjectreceivedint: The number of packets receivedtransmittedint: The number of packets transmitted
The ipv6 entry will only be returned if IPv6 is present.
Response
...
Example
| Code Block | ||
|---|---|---|
| ||
{
"route": "/v1/diagnostics/ping/0.0.0.0",
"method": "GET",
"data": {
"result": {
"success": true,
"response": {
"hostname": "0.0.0.0",
"results": {
"ipv4": [
{
"address": "0.0.0.0",
"results": {
"received": 10,
"stats": {
"average": 318,
"quickest": 223,
"slowest": 336,
"units": "us"
},
"transmitted": 10
},
"up": true
}
]
},
"up": true
}
}
}
} |
GET /diagnostics/trace-route/{:domain_name}/
Requests the player to perform a standard trace-route diagnostic on the specified IP or DNS address. This call can take several minutes to return.
Segment
domain_name: The specified IP or DNS address
Query String Parameter
resolveAddress bool: Specifies whether the IP or DNS address should be resolved or not
Request Example
| Code Block |
|---|
GET /rest/v1/diagnostics/trace-route/google.com/?resolveAddress=true&destinationType=player&destinationName={{deviceSerial}} HTTP/1.1
Host: ws.bsn.cloud
Authorization: Bearer {{UserAccessToken}}
Accept: application/json, application/vnd.bsn.error+json |
Response Body
addressstring: The IP address on which you are running the trace routeresultsobject:outputstring[ ]: Returns the trace route output information in text formatprotocolstring: The IP protocol, for example, "ipv4"routeobject[ ]:hopint: How many times the data moves from one router to the nextserversobject:addressstring: The address to which the trace route request is madehostnamestring: The server hostnamestatsobject[ ]reachablestring:timestring: The time required for the trace route request to returnunitsstring: The time units (usually in milliseconds)
Response
...
Example
| Code Block | ||
|---|---|---|
| ||
{
"route": "/v1/diagnostics/trace-route/152.101.32.76",
"method": "GET",
"data": {
"result": {
"address": "123.456.7.890",
"resolveAddress": "true",
"results": {
"152.101.32.76": {
"output": [
"traceroute to 152.101.32.76 (152.101.32.76), 30 hops max, 46 byte packets",
" 1 10.0.4.1 0.744 ms 0.458 ms 1.740 ms",
" 2 192.168.0.1 1.738 ms 1.387 ms 1.387 ms",
" 3 96.120.89.217 10.553 ms 11.250 ms 11.961 ms",
" 4 96.110.176.145 11.958 ms 11.250 ms 9.845 ms",
" 5 162.151.78.253 11.957 ms 13.366 ms 10.549 ms",
" 6 96.108.99.249 13.366 ms 14.072 ms 20.414 ms",
" 7 68.86.143.93 13.368 ms 11.960 ms 10.549 ms",
" 8 96.97.98.246 32.397 ms 96.112.146.22 11.954 ms 69.241.75.42 9.841 ms",
" 9 * * *",
"10 152.101.32.76 10.452 ms 152.101.32.76 13.302 ms 152.101.32.76 12.649 ms",
"11 192.178.105.102 11.948 ms 142.251.224.181 11.073 ms 192.178.46.198 17.759 ms",
"12 142.251.32.46 11.955 ms 12.649 ms 10.543 ms"
],
"protocol": "ipv4",
"result": 0,
"route": [
{
"error": "timeout",
"hop": 9
}
]
}
}
}
}
} |
GET /diagnostics/network-configuration/{:interface}/
Retrieves information about network-interface settings on the player
Segment
interface: The network interface. Possible names includeeth0,wlan0, andmodem.
Request Example
| Code Block |
|---|
GET /rest/v1/diagnostics/network-configuration/eth0/?destinationType=player&destinationName={{deviceSerial}} HTTP/1.1
Host: ws.bsn.cloud
Authorization: Bearer {{UserAccessToken}}
Accept: application/json, application/vnd.bsn.error+json |
Response Body
Some entries (e.g. caCertificates, clientIdentifier) are identical for all interfaces.
textstring: The network configuration information in plain-text formoutputOutput: The network configuration information as a JSON object:interfacesInterface[ ]: An array of Interface objects representing network interfaces:namestring: The interface name (for example,"eth0")errorsError[ ]: An array of error messages associated with the interfaceparamsParam[ ]: An array of Param objects representing parameters associated with the network interface. Each Param interface has the following entries:namestring: The property name (e.g."MAC")valuestring: The property value (e.g."90:ac:3f:0b:d2:88")
hostInfo[ ]: An array of Info objects providing network host information. Each object can have the following entries:errorsError[ ]: An array of error messages associated with the network hostparamsParam[ ]: An array of Param objects representing parameters associated with the network host
bsnInfo[ ]: An array of Info objects providing information about BSN communication.otherInfo[ ]: An array of Info objects providing information miscellaneous network information.
caCertificatestring: The contents of a CA certificate file in text form (i.e. a "pem" file).clientCertificatebool: A flag indicating whether the player is using a client certificateclientIdentifierstring: The DHCP client identifier for the network interfacednsServerListstring[ ]: An IP address list of the DNS serversdomainstring: The domain name for the network interfaceeapTlsOptionsstring: A string containing EAP-specific optionsenabledProtocolListstring[ ]: An array of enabled IP protocols. Currently supported values are"IPv4"and "IPv6".identitystring: The RADIUS identityipAddressListstring[ ]: The IP addresses assigned to the playerinboundShaperRateint: The bandwidth limit for inbound traffic in bits per second. A value of -1 specifies the default bandwidth limit, and a value of 0 specifies no bandwidth limit (these two settings are functionally the same).metricint:
...
The routing metric for the default gateway on the interface. Routes with lower metrics are preferred over routes with higher metrics.
mtuint: The maximum transmission unit (MTU) for the network interface in bytesprivateKeystring: The private key for authenticationvlanIdListint[ ]: An array of VLAN
...
ids that are supported on the parent network interface
securityModestring: Security mode for authentication
...
Response Example
| Expand | |||||
|---|---|---|---|---|---|
| |||||
|
...
|
PUT /diagnostics/network-configuration/{:interface}/
Applies a test network configuration on the player. You should use GET to get the configuration parameters before setting it using this API. The text and output parameters are NOT needed in PUT.
Segment
interface: The network interface. Possible names includeeth0,wlan0, andmodem.
Request Body
caCertificatestring optional: The contents of a CA certificate file in text form (i.e. a "pem" file).clientCertificatebool optional: A flag indicating whether the player is using a client certificateclientIdentifierstring optional: The DHCP client identifier for the network interfacednsServerListstring[ ] optional: An IP address list of the DNS serversdomainstring optional: The domain name for the network interfaceeapTlsOptionsstring optional: A string containing EAP-specific optionsenabledProtocolListstring[ ] optional: An array of enabled IP protocols. Currently supported values are "IPv4" and "IPv6".identitystring optional: The RADIUS identityipAddressListstring[ ] optional: The IP addresses assigned to the playerinboundShaperRateint optional: The bandwidth limit for inbound traffic in bits per second. A value of -1 specifies the default bandwidth limit, and a value of 0 specifies no bandwidth limit (these two settings are functionally the same).metricint optional: The routing metric for the default gateway on the interface. Routes with lower metrics are preferred over routes with higher metrics.mtuint optional: The maximum transmission unit (MTU) for the network interface in bytesprivateKeystring optional: The private key for authenticationvlanIdListint[ ] optional: An array of VLAN ids that are supported on the parent network interfacesecurityModestring optional: Security mode for authentication
Request Example
The example request parameters and headers are set as follows:
| Code Block |
|---|
PUT /rest/v1/diagnostics/network-configuration/eth0 HTTP/1.1
Host: ws.bsn.cloud
Authorization: Bearer {{UserAccessToken}}
Accept: application/json
Content-Type: application/json
Content-Length: 75 |
This is the example request body:
| Code Block | ||
|---|---|---|
| ||
{ "data": { "caCertificates": "", |
...
|
...
"clientCertificate": false, |
...
"clientIdentifier": "BrightSign: |
...
D7E8CV332141", |
...
|
...
"dnsServerList": [],
|
...
"domain": "", |
...
"eapTlsOptions": "", |
...
|
...
"enabledProtocolList": [
|
...
"IPv4", |
...
"IPv6" |
...
],
|
...
"identity": "",
|
...
"ipAddressList": [], |
...
|
...
" |
...
privateKey": false, |
...
|
...
"securityMode": "",
|
...
"vlanIdList": [ |
...
]
|
...
} |
...
|
...
} |
...
GET /diagnostics/network-neighborhood/
Retrieves information about the player’s current network neighborhood
...
(the other players on the same network).
Request Example
| Code Block |
|---|
GET /rest/v1/diagnostics/network-neighborhood/?destinationType=player&destinationName={{deviceSerial}} HTTP/1.1
Host: ws.bsn.cloud
Authorization: Bearer {{UserAccessToken}}
Accept: application/json, application/vnd.bsn.error+json |
Response Body
successbool: A flag that indicates if the operation succeededresponseobject[ ]:
...
An array of information about players in your network neighborhood
chassis-descrstring: The model version, OS version, serial number, etc.chassis-idstring: A unique identifier for the playerchassis-namestring: The name of the playermgmt-ipstringport-descrstring: Which interface the player is usingport-idstringvlan-pvidstring
If the diagnostic could not be performed, the response body may instead be an error message.
Response Example
| Code Block | ||
|---|---|---|
| ||
{
"route": "/v1/diagnostics/network-neighborhood",
"method": "GET",
"data": {
"result": {
"success": true,
"response": [
{
"chassis-descr": "BrightSign XT1144 REVE 8.5.47 |
...
UHE115005214", "chassis-id": "90:ac:3f:28:fb:a4", "chassis-name": "BrightSign- |
...
UHE115005214", "mgmt-ip": "2601:647:4500:1e5e:92ac:3fff:fe28:fba4", "port-descr": "eth0", "port-id": "90:ac:3f:28:fb:a4", "vlan-pvid": "0" } ] } } } |
GET /diagnostics/packet-capture/
Gets the current status of packet capture operation. Packet capture operation requires the legacy DWS to be working.
Request Example
| Code Block |
|---|
GET /rest/v1/diagnostics/packet-capture/?destinationType=player&destinationName={{deviceSerial}} HTTP/1.1
Host: ws.bsn.cloud
Authorization: Bearer {{UserAccessToken}}
Accept: application/json, application/vnd.bsn.error+json |
Response Body
statusCodeint: The success or error code (200 is success)is_runningbool: Flag indicating if the packet capture operation is running
Response Example
| Code Block | ||
|---|---|---|
| ||
{
"route": "/v1/diagnostics/packet-capture",
"method": "GET",
"data": {
"result": {
"statusCode": 200,
"is_running": false
}
}
} |
POST /diagnostics/packet-capture/
Starts a packet capture operation
Request Body
...
filenamestring: The name of the packet capture file. If you don't pass this string, 'capture.pcap' is the default.interfacestring: The name of the interface for which we are performing packet capture. 'eth0' is the default.durationint: The duration for which the packet capture runs in seconds. The default is 300 seconds (5 minutes).maxpacketsint: The maximum number of packets to capture before concluding the process. 0 is the default value.snaplenint: The maximum size of each packet. Specifying 0 will instruct the function to capture the entire packet no matter the size.filterstring: A field for conditional filtering of packets. This operation uses standard pcap syntax. This string is empty by default.
Request Example
| Code Block |
|---|
POST /rest/v1/diagnostics/packet-capture/?destinationType=player&destinationName={{deviceSerial}} HTTP/1.1
Host: ws.bsn.cloud
Authorization: Bearer {{UserAccessToken}}
Accept: application/json, application/vnd.bsn.error+json
Content-Type: application/json
Content-Length: 190 |
This is the example request body:
| Code Block | ||
|---|---|---|
| ||
{
"data": {
"filename": "capture.pcap",
"interface": "eth0",
"duration": 300,
"maxpackets": 0,
"snaplen |
...
": 0,
"filter": ""
}
} |
Response Example
| Code Block | ||
|---|---|---|
| ||
{ "data": { "result": { "statusCode": 200, "is_running": true } }, " |
...
route": "/v1/diagnostics/packet-capture", |
...
"method": "POST" } |
DELETE /diagnostics/packet-capture/
Stops a packet capture operation
Request Example
| Code Block |
|---|
DELETE /rest/v1/diagnostics/packet-capture/?destinationType=player&destinationName={{deviceSerial}} HTTP/1.1
Host: ws.bsn.cloud
Authorization: Bearer {{UserAccessToken}}
Accept: application/json, application/vnd.bsn.error+json |
Response Example
| Code Block | ||
|---|---|---|
| ||
{
"route": "/v1/diagnostics/packet-capture",
"method": "DELETE",
"data": {
"result": {
"statusCode": 200,
"is_running": false
}
}
} |
GET /diagnostics/telnet/
Get information about telnet from the player, including its enabled status and port number. This is only available in BOS 9.0.110 and above.
Request Example
| Code Block |
|---|
GET /rest/v1/diagnostics/telnet?destinationType=player&destinationName={{deviceSerial}} HTTP/1.1
Host: ws.bsn.cloud
Authorization: Bearer {{UserAccessToken}} |
Response
...
Example
| Code Block | ||
|---|---|---|
| ||
{
"route": "/v1/diagnostics/telnet",
"method": "GET",
"data": {
"result": {
"enabled": true,
"portNumber": 23
}
}
} |
PUT /diagnostics/telnet/
This is only available in BOS 9.0.110 and above.
Request Body
enabledboolean: Enable or disable Telnet on the playerportNumberinteger: The port number on which to enable Telnetrebootboolean: This optional parameter reboots the player immediately after executing this operation. It istrueby default.
Request Example
The example request parameters and headers are set as follows:
| Code Block |
|---|
PUT /rest/v1/diagnostics/telnet/ HTTP/1.1
Host: ws.bsn.cloud
Authorization: Bearer {{UserAccessToken}}
Accept: application/json
Content-Type: application/json
Content-Length: 75 |
This is the example request body:
| Code Block | ||
|---|---|---|
| ||
{ "data": { "enabled": true "portNumber": "23", "password": {{password}} } } |
Response Example
| Code Block | ||
|---|---|---|
| ||
{ "data": { "result": { "success": true, "reboot": true |
...
|
...
} |
...
Response
...
| language | json |
|---|
...
|
...
}, " |
...
route": |
...
"/v1/diagnostics/ |
...
telnet", |
...
|
...
|
...
|
...
|
...
"method": "PUT" } |
GET /diagnostics/ssh/
Returns information about whether or not SSH is enabled on the player, and the port number on which it is enabled if it is. This is only available in BOS 9.0.110 and above.
Request Example
The example request parameters and headers are set as follows:
| Code Block |
|---|
GET /rest/v1/diagnostics/ssh/ HTTP/1.1
Host: ws.bsn.cloud
Authorization: Bearer {{UserAccessToken}}
Accept: application/json |
Response Example
A successful response is a 200 and this response body:
| Code Block | ||
|---|---|---|
| ||
{
"enabled": true,
"portNumber": 22,
"password": true // Indicates that a value is set
} |
PUT /diagnostics/ssh/
This is only available in BOS 9.0.110 and above.
Request Body
enabledboolean: Enable or disable SSH on the playerportNumberinteger: The port number on which to enable SSHpasswordstring: Sets the plain-text login password for the SSH connectionrebootboolean: This optional parameter reboots the player immediately after executing this operation. It istrueby default.obfuscatedPasswordstring: This optional parameter sets the login password for the SSH connection. The password should previously have been obfuscated using a shared secret. Contact support@brightsign.biz to learn more about generating a key for obfuscation and storing it on the player.
Request Example
The example request parameters and headers are set as follows:
| Code Block |
|---|
PUT /rest/v1/diagnostics/ssh/ HTTP/1.1
Host: ws.bsn.cloud
Authorization: Bearer {{UserAccessToken}}
Accept: application/json
Content-Type: application/json
Content-Length: 65 |
This is the example request body:
| Code Block | ||
|---|---|---|
| ||
{ "data": { "enabled": true, "portNumber": 22, "password": {{password}} } } |
Response Example
| Code Block | ||
|---|---|---|
| ||
{ "data": { "result": { "success": true, "reboot": true } }, "route": "/v1/diagnostics/ssh", |
...
|
...
|
...
|
...
|
...
"method": "PUT" } |