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

Base URL for these endpoints:  ***https\://ws.bsn.cloud/rest/v1/***

*\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_*

## GET /files/\{:path}/ 

Lists the directories and/or files in a path

**Segment**

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

**Query String Parameter**

- `raw` <font color="#01a0af">optional</font>: Returns the raw contents of a directory
- `contents` <font color="#01a0af">optional</font>: If a file is specified, this will return the contents of that file

**Request Example**

```text
GET /rest/v1/files/sd/autorun.brs/?destinationType=player&destinationName={{deviceSerial}} HTTP/1.1
Host: ws.bsn.cloud
Authorization: Bearer {{UserAccessToken}}
Accept: application/json, application/vnd.bsn.error+json
```

**Response Body**

- `type` <font color="#704ae0">string</font>: Either a directory or file
- `path` <font color="#704ae0">string</font>: The path, for example, "sd"
- `stat` <font color="#704ae0">object</font>: Directory stats from the "fs" module
- `files` <font color="#704ae0">object[ ]</font>: 
  - `name` <font color="#704ae0">string</font>:  Name of the file or directory
  - `type` <font color="#704ae0">string</font>:  Either "file" or "dir"
  - `path` <font color="#704ae0">string</font>: The relative path of the file or directory
  - `stat` <font color="#704ae0">object</font>: File stats from the “fs” module
  - `mime` <font color="#704ae0">string</font>: mime type (available only for type "file")
- `storageInfo` <font color="#704ae0">object</font>: If the path in the URL is a storage device, this returns information about the storage device. For more information, see [storageinfo](docId\:RoZ3o77EuxtyZvj_dSPin). 
- `fileSystemType` <font color="#704ae0">string</font>: The type of filesystem (for example, "fat32")
- `stats` <font color="#704ae0">object</font>:
  - `blockSize` <font color="#704ae0">int</font>: The size of a native block
  - `bytesFree` <font color="#704ae0">int</font>: The amount of free space
  - `filesFree` <font color="#704ae0">int</font>: The number of used inodes
  - `filesUsed` <font color="#704ae0">int</font>: The number of free inodes
  - `isReadOnly` <font color="#704ae0">bool</font>: A flag indicating whether the filesystem is read only
  - `sizeBytes` <font color="#704ae0">int</font>: The amount of total space
- `mountedOn` <font color="#704ae0">string</font>: The location where the file system is mounted (for example, "/storage/sd")
- `contents` <font color="#704ae0">object[ ]</font>:
  - `name` <font color="#704ae0">string</font>: The name of the file or directory
  - `type` <font color="#704ae0">string</font>: Either "file" or "dir"
  - `path` <font color="#704ae0">string</font>: The absolute path of the file or directory
  - `stat` <font color="#704ae0">object</font>: The statistics from the "fs" module 
  - `mime` <font color="#704ae0">string</font>: mime type (available only for type "file")
  - `children` <font color="#704ae0">object[ ]</font>: This is available only for directory types and will have the same format as "contents

**Response Body if Returning Contents**

- `name` <font color="#704ae0">string</font>: The name of the file
- `mimeType` <font color="#704ae0">string</font>: Mime type of the file
- `contents` <font color="#704ae0">string</font>: The contents of the file

**Response Examples**

```json
{
    "route": "/v1/files/sd/autorun.brs",
    "method": "GET",
    "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
        }
    }
}
```

If you passed in a `contents` query paramter in your request, you should expect a response like the one below. Note that once you have the data string, you will have to decode it (for example, with the `atob` method in JavaScript).

```json
{
    "route": "/v1/files/sd/autorun.brs",
    "method": "GET",
    "data": {
        "result": {
            "mimeType": null,
            "name": "autorun.brs",
            "contents": "TGlicmFyeSAiYXV0b3B....<very-large-data-string>..."
        }
    }
}
```

## PUT /files/\{:path}

Uploads a new file or folder to the player storage

:::hint{type="info"}
If you are uploading zip and media files, you should use BOS version 8.5.44 or 9.0.101 or later.
:::

**Segment**

- `path` <font color="#704ae0">string</font>: The path is the folder in which you want to upload the file (for example: `"/sd"`).

**Request Body**

- `files` <font color="#704ae0">object[]</font>:
  - `fileName` <font color="#704ae0">string</font>: The name of the file
  - `fileContents` <font color="#704ae0">string</font>: The content of the file. It can be provided as plain text or as Data URL.
  - `fileType` <font color="#704ae0">string</font>: Mime type

**Request Example (File)**

The following request example would be used with one of the two request body examples (Plain Text or Data URL) below:

```text
PUT /rest/v1/files/sd/?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: 196
```

In the request body examples below, use the [FileReader's readAsText()](https://developer.mozilla.org/en-US/docs/Web/API/FileReader/readAsText) or [readAsDataURL()](https://developer.mozilla.org/en-US/docs/Web/API/FileReader/readAsDataURL) method to derive the `fileContents` value.

**Plain Text Request Body**: Any file with mime type "text/\*", or any “brs”, “json”, “js”, “xml”, “rtf” extension, can be sent as plain text using [FileReader's readAsText()](https://developer.mozilla.org/en-US/docs/Web/API/FileReader/readAsText) method:

```json
{
    "data": {
        "fileUploadPath": "/sd",
        "files": [
            {
                "fileName": "test.txt",
                "fileContents": "Lorem Ipsum",
                "fileType": "text/plain"
            }
        ]
    }
}
```

**Data URL Request Body**: For all other file types, including zip and media files, use the data URL format using [FileReader's readAsDataURL()](https://developer.mozilla.org/en-US/docs/Web/API/FileReader/readAsDataURL) method:

```json
{
    "data": {
        "fileUploadPath": "/sd",
        "files": [
            {
                "fileName": "image.png",
                "fileContents": "data:image/png;base64,DQpJbnRlcmZh.....",
                "fileType": "image/png"
            }
        ]
    }
}
```

**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"
            ]
        }
    },
    "route": "/v1/files/sd",
    "method": "PUT"
}
```

**Request Example (Folder)**

```text
PUT /rest/v1/files/sd/testfolder/?destinationType=player&destinationName={{deviceSerial}}
Host: ws.bsn.cloud
Authorization: Bearer {{UserAccessToken}}
Accept: application/json, application/vnd.bsn.error+json
```

**Response Example (Folder)**

```json
{
    "route": "/v1/files/sd/testfolder/",
    "method": "PUT",
    "data": {
        "result": {
            "success": true
        }
    }
}
```

## POST /files/\{:path}/ 

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

**Segment**

- `path` <font color="#704ae0">string</font>: The path to the file (for example, `/sd`)

**Request Example**

```text
POST /rest/v1/files/sd/test.txt/?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: 57
```

This is the example request body:

```json
{
    "data": {
        "name": "newname.txt"
    }
}
```

**Response Body**

The player will return a success or error message.

## DELETE /files/\{:path}/ 

Deletes a file from the player storage

**Segment**

- `path` <font color="#704ae0">string</font>: The path to the file (for example,`/sd`)

**Request Example**

```text
DELETE /rest/v1/files/sd/test.txt/?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 will return a success or error message.