LDWS Storage Endpoints

13 min

GET /v1/files/:path/

Lists directories and files in the requested path.

Segment

:path string: The path to the directories or files

Query String Parameter

raw optional: If the path is for a storage device, this will return its raw contents. For example, the request below would be GET /api/v1/files/sd/?raw

contents optional: If a file is specified, this will return the contents of that file

Request Example

The example request parameters and headers are set as follows:

:path is set to /sd/autorun.brs/

GET /api/v1/files/sd/autorun.brs/ HTTP/1.1
Host: {{playerIP}}
Authorization: {{DigestAuth}}
Accept: application/json

Downloading a File From Player Storage

To directly download a file from player storage, add ?contents&stream to the end of the URL. Here is a sample workflow (assuming a base URL of http://192.168.0.00/api/v1):

Create a snapshot on the SD card under the remote_snapshots using POST /v1/snapshot

The response will be the name of the snapshot (for example, img-2021-12-29-10-49-27.jpg).

To directly download the snapshot created on the player: GET http://192.168.0.12/api/v1/files/sd/remote_snapshots/img-2021-12-29-10-49-27.jpg?contents&stream

If you enter only ?contents, you get the file in the base64 encoding.

Response Body

This method returns the metadata for a directory or file (assuming the raw query string parameter is not set):

name string: Name of the directory or file

type string: Either a directory or file

path string: The path, for example, "sd"

mime string: mime type (available only for type "file")

stat object: Directory stats from the "fs" module

fileSize int: The size of the filesystem

streamable bool: This is always true for files. If the path is a directory, this is not returned

contents string: The contents of the specified file

Response Example

{
    "data": {
        "result": {
            "name": "sd/autorun.brs",
            "type": "file",
            "path": "sd/autorun.brs",
            "mime": "application/octet-stream",
            "stat": {
                "dev": 45921,
                "mode": 33277,
                "nlink": 1,
                "uid": 0,
                "gid": 1003,
                "rdev": 0,
                "blksize": 32768,
                "ino": 40,
                "size": 1144340,
                "blocks": 2240,
                "atimeMs": 1699401600000,
                "mtimeMs": 1699423824000,
                "ctimeMs": 1699423824440,
                "birthtimeMs": 0,
                "atime": "2023-11-08T00:00:00.000Z",
                "mtime": "2023-11-08T06:10:24.000Z",
                "ctime": "2023-11-08T06:10:24.440Z",
                "birthtime": "1970-01-01T00:00:00.000Z"
            },
            "fileSize": 1144340,
            "streamable": true
        }
    }
}

Response Example when Returning File Contents

Note that once you have the data string, you will have to decode it (for example, with the atob method in JavaScript).

{
  "data": {
    "result": {
        "mimeType": null,
        "name": "autorun.brs",
        "contents": "TGlicmFyeSAiYXV0b3B....<very-large-data-string>..."
    }
}

POST /v1/files/:path/

Renames a file in the path (which should include the file name).

Segment

:path string: The path to a file

Request Body

name string: The new file name

Request Example

The example request parameters and headers are set as follows:

:path is set to /sd/test.txt/

POST /api/v1/files/sd/test.txt/ HTTP/1.1
Host: {{playerIP}}
Authorization: {{DigestAuth}}
Accept: application/json
Content-Type: application/json
Content-Length: 21

This is the example request body:

"name": "newname.txt"

Response

The player will return a 200 success or 404 or 500 error message.

Success Response Body

{
  "data": {
    "result": {
      "success": true
    }
  }
}

PUT /v1/files/:path/

Uploads files or creates directories. The request body needs to be of type multipart /form-data (see RFC 7578). If you add one or more parameters of type file (the name of the parameter does not matter), it will upload the selected file(s).

To create a directory, remove the form-data from the body, and add the directory as the URL parameter, :path. See the example below.

Segment

:path string: The path is the folder in which you want to upload the file.

Request Body

The files as form data, as shown in the example below.

Request Example (File)

The example request parameters and headers are set as follows:

path is set to sd

PUT /api/v1/files/sd/ HTTP/1.1
Host: {{playerIP}}
Authorization: {{DigestAuth}}
Content-Length: 227
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="/path/to/file/test.txt"
Content-Type: text/plain

(data)
------WebKitFormBoundary7MA4YWxkTrZu0gW--

Response Body

success bool: A flag that indicates if the operation succeeded or not

results string[]: The names of the files that were successfully created

Response Example (Plain Text File)

{
    "data": {
        "result": {
            "success": true,
            "results": [
                "test.txt"
            ]
        }
    }
}

Request Example (Folder)

PUT /api/v1/files/sd/testfolder/
Host: {{playerIP}}
Authorization: {{DigestAuth}}
Accept: application/json, application/vnd.bsn.error+json

Response Example (Folder)

{
    "data": {
        "result": {
            "success": true
        }
    }
}

DELETE /v1/files/:path/

Removes a file or directory

Segment

:path string: The path to the file or directory

Request Example

The example request parameters and headers are set as follows:

:path is set to sd/test.txt

DELETE /api/v1/files/sd/test.txt/ HTTP/1.1
Host: {{playerIP}}
Authorization: {{DigestAuth}}
Accept: application/json

Response

The player will return a 200 success or 404 or 500 error message.

Success Response Body

{
  "data": {
    "result": {
      "success": true
    }
  }
}

PUT /v1/storage/encryption/

Encrypts the selected media storage. Note that reformatting the storage device will erase its contents. This endpoint is available in BOS version 9.0.197 and later.

Request Body

filePath string required: The path to the media storage (for example, “/sd”)

settings object:

type string required: The encryption method. The options are: ‘brightsign-key', 'unique-key', 'password', and 'none'. The options map to devicecustomization StorageEncryptionOptions ('brightsign-key' is "brightsign_key", 'unique-key' is "generate_key", 'password' is "passphrase". 'none' is "none").

password string optional: The password used to encrypt media storage, if any. This field is required if settings.type is “password“.

format bool optional: Whether or not the storage device should be reformatted. By default, the storage will be reformatted.

doProvision bool optional: Whether the player should be automatically provisioned with BSN.Cloud. By default, the player will not be automatically provisioned.

Request Example

The example request parameters and headers are set as follows:

PUT /api/v1/storage/encryption/ HTTP/1.1
Host: {{playerIP}}
Authorization: {{DigestAuth}}
Accept: application/json

This is the example request body:

{
  "filePath": "/sd",
  "settings": {
    "type": "password",
    "password": "abc",
    "format": true,
    "doProvision": true
  }
}

Success Response Body and Example

success bool: Indicates if the encryption succeeded or not

reboot bool: Whether or not the player will reboot

{
    "data": {
        "result": {
            "success": true,
            "reboot": false
        }
    }
}

Error Response Body and Example

error string: Any error messages associated with the operation

{
    "data": {
        "error": {
            "status": 400,
            "message": "Storage is already encrypted. Please decrypt it first."
        }
    }
}

LDWS Storage Endpoints

GET /v1/files/:path/

﻿

POST /v1/files/:path/

PUT /v1/files/:path/

DELETE /v1/files/:path/

PUT /v1/storage/encryption/