B-Deploy Device Endpoints (v2)
These endpoints allow users to automatically provision BrightSign players over the internet. This endpoint handles everything regarding individual players if you add your serial number to BrightSign’s cloud storage with an associated player name, provisioning package name, and the URL where the provisioning package is hosted. The URL is optional - it can be left blank if using a setup package.
Base URL for these endpoints: https://provision.bsn.cloud/rest-device/v2/device/
GET
Retrieves a collection of provision records which belong to your network in B-Deploy
URL Parameters
- query[NetworkName] string required: The BSN.Cloud/BSN.com network name
- sort[serial] byte optional: A flag which defines whether the returned list should be sorted by player serial
- page[pageNum] number optional: An index of a page in the paged list to retrieve
- page[pageSize] number optional: The maximum number of provision records on a page in the paged list
___________________________________________________
Request Example
- query[NetworkName] is set to JaneDoeNetwork
- sort[serial] is set to 1
- page[pageNum] is set to 1
- page[pageSize] is set to 20
GET /rest-device/v2/device/?query%5BNetworkName%5D=JaneDoeNetwork&sort%5Bserial%5D=1&page%5BpageNum%5D=1&page%5BpageSize%5D=20 HTTP/1.1
Host: provision.bsn.cloud
Connection: Keep-Alive
Authorization: {{Bearer Token}}
Accept: application/json
Accept-Encoding: gzip,deflate___________________________________________________
Success Response Body
200: Returns a paged list of Provision Record Entity (v2)
Response Example
{
"error": null,
"result": {
"total": 1,
"matched": 1,
"players": [
{
"_id": "1a2b3c4d5e6f7a8b9c0d1e2f",
"client": "baconnected",
"NetworkName": "JaneDoeNetwork",
"username": "[email protected]",
"serial": "123456789012",
"name": "My Player",
"model": "XC4055",
"desc": "Brand New Player",
"setupName": "My Setup Package",
"createdAt": "2024-08-25T13:38:00.042Z",
"updatedAt": "2024-08-25T13:38:00.042Z",
"__v": 0
}
],
"priv": "user"
}
}Failure Response
400: The request is malformed and therefore invalid
401: The access token is invalid or not specified
403: The supplied access token, though valid, doesn't provide access to this method.
5XX: Any 500 code is an internal server error
GET /?_id={string}
Retrieves a provision record from B-Deploy which has the specified ID.
Query String Parameter
- _id string required: The unique identifier of the provision record to retrieve. If this parameter is not included in the URL, the GET request will return all provision records associated with the account
___________________________________________________
Request Example
- _id is set to 1a2b3c4d5e6f7a8b9c0d1e2f
GET /rest-device/v2/device/?_id=1a2b3c4d5e6f7a8b9c0d1e2f HTTP/1.1
Host: provision.bsn.cloud
Connection: Keep-Alive
Authorization: {{Bearer Token}}
Accept: application/json
Accept-Encoding: gzip,deflate___________________________________________________
Success Response Body
200: Returns the specified Provision Record Entity (v2)
Response Example
{
"error": null,
"result": {
"_id": "1a2b3c4d5e6f7a8b9c0d1e2f",
"client": "baconnected",
"NetworkName": "JaneDoeNetwork",
"username": "[email protected]",
"serial": "ABCD00000001",
"name": "ProvisionTest",
"model": "XC4055",
"desc": "Brand New Player",
"setupName": "My Setup Package",
"createdAt": "2024-08-25T13:38:00.042Z",
"updatedAt": "2024-08-25T13:38:00.042Z",
"__v": 0
}
}Failure Response
400: The request is malformed and therefore invalid
401: The access token is invalid or not specified
403: The supplied access token, though valid, doesn't provide access to this method.
404: The server cannot find the requested resource (the path does not exist)
5XX: Any 500 code is an internal server error
GET /?serial={string}
Retrieves a provision record from B-Deploy created for a player having the specified serial.
Query String Parameter
- serial string required: The serial of a player which is specified by a provision record. If this parameter is not included in the URL, the GET request will return all provision records associated with the account
___________________________________________________
Request Example
- serial is set to ABCD00000001
GET /rest-device/v2/device/?serial=ABCD00000001 HTTP/1.1
Host: provision.bsn.cloud
Connection: Keep-Alive
Authorization: {{Bearer Token}}
Accept: application/json
Accept-Encoding: gzip,deflate___________________________________________________
Success Response Body
200: Returns the specified Provision Record Entity (v2)
Response Example
{
"error": null,
"result": {
"total": 1,
"matched": 1,
"players": [
{
"_id": "1a2b3c4d5e6f7a8b9c0d1e2f",
"client": "baconnected",
"NetworkName": "JaneDoeNetwork",
"username": "[email protected]",
"serial": "ABCD00000001",
"name": "ProvisionTest",
"model": "XC4055",
"desc": "Brand New Player",
"setupName": "My Setup Package",
"createdAt": "2024-08-25T13:38:00.042Z",
"updatedAt": "2024-08-25T13:38:00.042Z",
"__v": 0
}
],
"priv": "user"
}
}Failure Response
400: The request is malformed and therefore invalid
401: The access token is invalid or not specified
403: The supplied access token, though valid, doesn't provide access to this method.
5XX: Any 500 code is an internal server error
POST
Creates a provision record for a specific player and refers to either a setup package stored in B-Deploy or provided by an external service.
Request Body
- username string required: The login of the person who owns the record. Note that the person may or may not be registered in BSN.Cloud.
- serial string required: The serial number of the player represented by the provision record
- name string optional: The name that the target player will get as a result of provisioning. When specified, it overrides the values specified in the referenced setup package.
- NetworkName string required: The name of the network to which the specified player should be provisioned
- model string optional: The model of the player which has the specified serial
- desc string optional: The description that the target player will get in result of provisioning. When specified, it overrides the values specified in the referenced setup package.
- setupId string optional: The unique identifier of the setup package stored in B-Deploy and managed using the PSS API documented in B-Deploy Setup Endpoints (v2)
- setupName string optional: The descriptive name of a setup package stored in B-Deploy and managed using the PSS API documented in B-Deploy Setup Endpoints (v2)
- url string optional: The URL from which the player will download its presentation as part of the final provisioning step
- userdata string optional: Allows you to allows you to provide additional attributes to a custom setup package
Request Example
POST /rest-device/v2/device HTTP/1.1
Host: provision.bsn.cloud
Content-Type: application/json
Authorization: {{Bearer Token}}
Accept: application/json
Accept-Encoding: gzip,deflate
Content-Type: application/json
Content-Length: 252This is an example request body with a setupId and setupName:
{
"username": "[email protected]",
"serial": "ABCD00000001",
"name": "ProvisionTest",
"NetworkName": "Test",
"model": "XC4055",
"desc": "Jane's player",
"setupId": "f2e1d0c9b8a7f6e5d4c3b2a1",
"setupName": "My Setup Package",
"userdata": ""
}This is an example request body with a url:
{
"username": "[email protected]",
"serial": "ABCD00000001",
"name": null,
"NetworkName": "Test",
"model": "XC4055",
"desc": "Jane's player",
"userdata": "key=value",
"url": "https://provisiondemo.brightsignnetwork.com/autorun.zip"
}___________________________________________________
Success Response
201: Returns the unique identifier of a provision record created in B-Deploy and added to your network
Failure Response
400: The request is malformed and therefore invalid
401: The access token is invalid or not specified
403: The supplied access token, though valid, doesn't provide access to this method
415: The server cannot accept the data representation that you sent (as specified in the header)
5XX: Any 500 code is an internal server error
PUT /?_id={string}
Modifies a provision record of a specified player in B-Deploy
Request Body
- _id string required: The unique identifier (a 24 digits-long hexadecimal number) of the device object
- username string required: The login of the person who owns the record. Note that the person may or may not be registered in BSN.Cloud.
- serial string required: The serial number of the player represented by the provision record
- name string optional: The name that the target player will get as a result of provisioning. When specified, it overrides the values specified in the referenced setup package.
- NetworkName string required: The name of the network to which the specified player should be provisioned
- model string optional: The model of the player which has the specified serial
- desc string optional: The description that the target player will get as a result of provisioning. When specified, it overrides the values specified in the referenced setup package.
- setupId string optional: The unique identifier of the setup package stored in B-Deploy and managed using the PSS API documented on this page.
- setupName string optional: The descriptive name of a setup package stored in B-Deploy and managed using the PSS API documented on this page.
- url string optional: Refers to the setup package or handler provided by external services, like partner applications.
- userdata string optional: An optional property which allows you to provide additional attributes to a custom setup package
___________________________________________________
Request Example
This method requires an url property value with an absolute URL value format or a pair of setupId and setupName property values.
PUT /rest-device/v2/device/ HTTP/1.1
Host: provision.bsn.cloud
Content-Type: application/json
Authorization: {{Bearer Token}}
Accept: application/json
Accept-Encoding: gzip,deflate
Content-Type: application/json
Content-Length: 283This is the url example request body:
{
"_id": "1a2b3c4d5e6f7a8b9c0d1e2f",
"username": "[email protected]",
"serial": "ABCD00000001",
"name": "ProvisionTest",
"NetworkName": "Test",
"model": "XC4055",
"desc": "Jane's player",
"url": "https://www.janeplayers.com/setups/autorun.zip",
"userdata": "key=value"
}This is the setupId and setupName example request body:
{
"_id": "1a2b3c4d5e6f7a8b9c0d1e2f",
"username": "[email protected]",
"serial": "ABCD00000001",
"name": "ProvisionTest",
"NetworkName": "Test",
"model": "XC4055",
"desc": "Jane's player",
"setupId": "f2e1d0c9b8a7f6e5d4c3b2a1",
"setupName": "My Setup Package",
"userdata": ""
}___________________________________________________
Success Response
200: The existing provision record properties have been updated.
Failure Response
400: Either the request or request body is malformed and therefore invalid
401: The access token is invalid or not specified
403: The supplied access token, though valid, doesn't provide access to this method
415: The server cannot accept the data representation that you sent (as specified in the header)
5XX: Any 500 code is an internal server error
DELETE /?_id={string}
Removes a provision record having the specified ID in B-Deploy
Query String Parameter
- _id string required: The player database record identifier
___________________________________________________
Request Example
- _id is set to 1a2b3c4d5e6f7a8b9c0d1e2f
DELETE /rest-device/v2/device/?_id=1a2b3c4d5e6f7a8b9c0d1e2f HTTP/1.1
Host: provision.bsn.cloud
Content-Type: application/json
Authorization: {{Bearer Token}}
Accept: application/json
Accept-Encoding: gzip,deflate___________________________________________________
Success Response
200: The specified provision record has been removed
Failure Response
400: The request is malformed and therefore invalid
401: The access token is invalid or not specified
403: The supplied access token, though valid, doesn't provide access to this method
404: A provision record with the specified ID does not exist
5XX: Any 500 code is an internal server error
DELETE /?serial={string}
Removes a provision record related to a player having the specified serial number in B-Deploy
Query String Parameter
- serial string required: The player serial
___________________________________________________
Request Example
- serial is set to ABCD00000001
DELETE /rest-device/v2/device/?serial=ABCD00000001 HTTP/1.1
Host: provision.bsn.cloud
Content-Type: application/json
Authorization: {{Bearer Token}}
Accept: application/json
Accept-Encoding: gzip,deflate___________________________________________________
Success Response
200: The specified provision record has been removed
Failure Response
400: The request is malformed and therefore invalid
401: The access token is invalid or not specified
403: The supplied access token, though valid, doesn't provide access to this method
404: A provision record with the specified serial number does not exist
5XX: Any 500 code is an internal server error
DELETE /ids/{array}
Removes a collection of provision records having the specified identifiers in B-Deploy
Segment
array string[]
An array of provision record identifiers
___________________________________________________
Request Example
- array is set to ["1a2b3c4d5e6f7a8b9c0d1e2f"]
DELETE /rest-device/v2/device/ids/["1a2b3c4d5e6f7a8b9c0d1e2f"] HTTP/1.1
Host: provision.bsn.cloud
Connection: Keep-Alive
Authorization: {{Bearer Token}}
Accept: application/json
Accept-Encoding: gzip,deflate___________________________________________________
Success Response
200: The request is executed successfully and the indication of which records have been removed is in the response payload.
Response Example
{
"error": null,
"result": {
"deletedCount": 1,
"deletedIds": ["1a2b3c4d5e6f7a8b9c0d1e2f"],
"failedIds": [],
"message": "All players were deleted successfully"
}
}Failure Response
400: The request is malformed and therefore invalid
401: The access token is invalid or not specified
403: The supplied access token, though valid, doesn't provide access to this method
5XX: Any 500 code is an internal server error