---
title: LDWS Storage Endpoints
slug: develop/ldws-storage-endpoints
docTags: 
createdAt: 2025-03-11T07:03:32.132Z
---

## GET /v1/files/\:path/ 

Lists directories and files in the requested path.

**Segment**

- `:path` <font color="#704ae0">string</font>: The path to the directories or files

**Query String Parameter**

- `raw` <font color="#01a0af">optional</font>: 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` <font color="#01a0af">optional</font>: 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/`

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

:::hint{type="success"}
**Downloading a File From Player Storage&#xFEFF;**

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*):

1. Create a snapshot on the SD card under the remote\_snapshots using POST /v1/snapshot
2. The response will be the name of the snapshot (for example, *img-2021-12-29-10-49-27.jpg*).
3. 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*
4. 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` <font color="#704ae0">string</font>: Name of the directory or file
- `type` <font color="#704ae0">string</font>: Either a directory or file
- `path` <font color="#704ae0">string</font>: The path, for example, "sd"
- `mime` <font color="#704ae0">string</font>: mime type (available only for type "file")
- `stat` <font color="#704ae0">object</font>: Directory stats from the "fs" module
- `fileSize` <font color="#704ae0">int</font>: The size of the filesystem
- `streamable` <font color="#704ae0">bool</font>: This is always `true` for files. If the path is a directory, this is not returned
- `contents` <font color="#704ae0">string</font>: The contents of the specified file

**Response Example**

```json
{
    "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).

```json
{
  "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` <font color="#704ae0">string</font>: The path to a file

**Request Body**

- `name` <font color="#704ae0">string</font>: The new file name

**Request Example**

The example request parameters and headers are set as follows:

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

```text
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:

```json
"name": "newname.txt"
```

**Response**

The player will return a <font color="#15803D">200</font> success or <font color="#B91C1C">404</font> or <font color="#B91C1C">500</font> error message.

**Success Response Body**

```json
{
  "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](https://datatracker.ietf.org/doc/html/rfc7578)). 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` <font color="#704ae0">string</font>: 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`

```text
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` <font color="#704ae0">bool</font>: A flag that indicates if the operation succeeded or not
- `results` <font color="#704ae0">string[]</font>: The names of the files that were successfully created

**Response Example (Plain Text File)**

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

**Request Example (Folder)**

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

**Response Example (Folder)**

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

## DELETE /v1/files/\:path/ 

Removes a file or directory

**Segment**

- `:path` <font color="#704ae0">string</font>: 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`

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

**Response**

The player will return a <font color="#15803D">200</font> success or <font color="#B91C1C">404</font> or <font color="#B91C1C">500</font> error message.

**Success Response Body**

```json
{
  "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` <font color="#704ae0">string</font> <font color="#01a0af">required</font>: The path to the media storage (for example, “/sd”)
- `settings` <font color="#704ae0">object</font>:
  - `type` <font color="#704ae0">string</font> <font color="#01a0af">required</font>: The encryption method. The options are: `‘brightsign-key'`, `'unique-key'`, `'password'`, and `'none'`. The options map to [devicecustomization StorageEncryptionOptions](docId\:WRjDIgxWn_0yNjrUjRm3d) (`'brightsign-key'` is `"brightsign_key"`, `'unique-key'` is `"generate_key"`, `'password'` is `"passphrase"`. `'none'` is `"none"`).
  - `password` <font color="#704ae0">string</font> <font color="#01a0af">optional</font>: The password used to encrypt media storage, if any. This field is required if `settings.type` is `“password“`.
  - `format` <font color="#704ae0">bool</font> <font color="#01a0af">optional</font>: Whether or not the storage device should be reformatted. By default, the storage will be reformatted.
  - `doProvision` <font color="#704ae0">bool</font> <font color="#01a0af">optional</font>: Whether the player should be automatically provisioned with BSN.Cloud. By default, the player will not be automatically provisioned.

**Request Example&#x20;**

The example request parameters and headers are set as follows:

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

This is the example request body:

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

**Success** **Response Body and Example**

- `success` <font color="#704ae0">bool</font>: Indicates if the encryption succeeded or not
- `reboot` <font color="#704ae0">bool</font>: Whether or not the player will reboot

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

**Error Response Body and Example**

- `error` <font color="#704ae0">string</font>: Any error messages associated with the operation&#x20;

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