> For the complete documentation index, see [llms.txt](https://docs.blynk.io/en/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blynk.io/en/html-widget-developer-guide/device-files-and-assets.md).

# Device Files & Assets

Show images stored in the bound device's file storage or in the organization's assets, and upload or delete device files. Feature-detect each method — an older host can lack them — and leave that part of the widget out where it's missing.

| Method                             | Resolves with                    | Permission          |
| ---------------------------------- | -------------------------------- | ------------------- |
| `getDeviceFiles()`                 | The bound device's files         | `VIEW_DEVICE_FILES` |
| `getDeviceFile(selector)`          | One device file record           | `VIEW_DEVICE_FILES` |
| `getDeviceFileBlob(fileId)`        | The file content as a `Blob`     | `VIEW_DEVICE_FILES` |
| `uploadDeviceFile(file, options?)` | Settles once the file is stored  | `EDIT_DEVICE_FILES` |
| `deleteDeviceFile(fileId)`         | Settles once the file is deleted | `EDIT_DEVICE_FILES` |
| `getAssets()`                      | The organization's assets        | `VIEW_ASSETS`       |
| `getAsset(selector)`               | One asset record                 | `VIEW_ASSETS`       |
| `getAssetBlob(assetId)`            | The asset content as a `Blob`    | `VIEW_ASSETS`       |

**Selectors and IDs**

* A file or asset **selector** is a plain object with **exactly one** of `id` (an integer from 1 to 2147483647) or `fileName` (a string of 1 to 255 characters). Anything else rejects with `invalid_selector`.
* `fileId` and `assetId` are integers from 1 to 2147483647. Anything else rejects with `invalid_request` (`details.argument` names the parameter).
* Records carry the `id` and `fileName` you can select by. Read other fields defensively.

**Limits**

* At most **50** file and asset requests per widget can be pending at once; more reject with `too_many_requests`.
* Lists, records and deletes time out after **30 seconds**; content and uploads after **120 seconds** (`request_timeout`).

***

### List device files

> Returns the files stored for the bound device.

```js
bridge.getDeviceFiles()  // → Promise<DeviceFile[]>
```

**Parameters:** none. **Rejects with** `too_many_requests`, `request_timeout`, `server_error`, `device_unavailable`, `bridge_destroyed`.

### Get a device file

> Returns one device file record, selected by ID or file name.

```js
bridge.getDeviceFile(selector)  // → Promise<DeviceFile>
```

| Name       | Type     | Required | Description                |
| ---------- | -------- | -------- | -------------------------- |
| `selector` | `object` | yes      | `{ id }` or `{ fileName }` |

**Rejects with** `invalid_selector`, plus the list errors.

### Get device file content

> Returns a device file's content as a `Blob` with the file's content type.

```js
bridge.getDeviceFileBlob(fileId)  // → Promise<Blob>
```

| Name     | Type     | Required | Description           |
| -------- | -------- | -------- | --------------------- |
| `fileId` | `number` | yes      | ID from a file record |

Show it with `URL.createObjectURL(blob)`, and call `URL.revokeObjectURL()` when the element goes away. Content calls can take up to 120 seconds — show a placeholder per item, not one spinner for the whole grid.

**Rejects with** `invalid_request`, plus the list errors.

### Upload a device file

> Stores an image in the bound device's file storage.

```js
bridge.uploadDeviceFile(file, options?)  // → Promise
```

**Parameters**

| Name               | Type           | Required | Description                                                                |
| ------------------ | -------------- | -------- | -------------------------------------------------------------------------- |
| `file`             | `Blob \| File` | yes      | The content, e.g. from `<input type="file" accept=".png,.jpg,.jpeg,.ico">` |
| `options.fileName` | `string`       | no       | Name to store it under. Defaults to `file.name`. Trimmed before use        |

**Rules:** `.png`, `.jpg`, `.jpeg` or `.ico`; 1 byte to 10 MiB; one upload per widget at a time.

**Rejects with**

| Code                                                   | When                                                                                                      |
| ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| `invalid_request`                                      | `file` isn't a `Blob` or `File`, or `options` has a key other than `fileName`                             |
| `invalid_file_name`                                    | Empty after trimming, longer than 255 characters, `.` or `..`, or contains `/`, `\` or control characters |
| `unsupported_file_type`                                | The extension isn't `.png`, `.jpg`, `.jpeg` or `.ico` (`details.allowed` lists them)                      |
| `file_empty`                                           | Zero bytes                                                                                                |
| `file_too_large`                                       | Over 10 MiB (`details: { size, limit }`)                                                                  |
| `upload_in_progress`                                   | Another upload from this widget hasn't settled yet                                                        |
| `too_many_requests`, `request_timeout`, `server_error` | As for the other file calls                                                                               |

Check extension, size and name yourself before calling, so the user gets an inline reason rather than only the error toast. Disable the upload control until the Promise settles, then re-read the list.

### Delete a device file

> Deletes one file from the bound device's storage.

```js
bridge.deleteDeviceFile(fileId)  // → Promise
```

| Name     | Type     | Required | Description           |
| -------- | -------- | -------- | --------------------- |
| `fileId` | `number` | yes      | ID from a file record |

Ask for an inline confirmation first. **Rejects with** `invalid_request`, plus the list errors.

### List, get and read assets

> Organization assets — a logo, a floor plan — work like device files, read-only.

```js
bridge.getAssets()             // → Promise<Asset[]>
bridge.getAsset(selector)      // → Promise<Asset>     selector: { id } or { fileName }
bridge.getAssetBlob(assetId)   // → Promise<Blob>
```

Same selectors, limits and errors as the device-file calls.

**Example — a photo grid with upload**

```js
const canView = await bridge.isPermissionAllowed('VIEW_DEVICE_FILES').catch(() => false);
const canEdit = await bridge.isPermissionAllowed('EDIT_DEVICE_FILES').catch(() => false);

async function renderFiles() {
  grid.replaceChildren();
  const files = await bridge.getDeviceFiles().catch(() => []);
  files.forEach(f => {
    const img = document.createElement('img');
    img.alt = f.fileName;
    grid.appendChild(img);
    bridge.getDeviceFileBlob(f.id)
      .then(blob => { img.src = URL.createObjectURL(blob); })
      .catch(() => img.classList.add('failed'));
  });
}

uploadInput.addEventListener('change', async () => {
  const file = uploadInput.files[0];
  if (!file) return;
  uploadButton.disabled = true;
  try {
    await bridge.uploadDeviceFile(file);
    await renderFiles();
  } catch (e) {
    showInlineError(e.code);
  } finally {
    uploadButton.disabled = false;
    uploadInput.value = '';
  }
});

if (canView && typeof bridge.getDeviceFiles === 'function') renderFiles();
uploadButton.hidden = !canEdit;
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.blynk.io/en/html-widget-developer-guide/device-files-and-assets.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
