# Pearl REST API check storage status and eject media

Storage endpoints report how much space a Pearl device has left, what media is installed, and whether files are being transferred to it.

*Applies to: Pearl-2, Pearl Mini, Pearl Nexus, Pearl Nano.*

| Method and path | What it does |
| --- | --- |
| `GET /system/storages` | Lists the storage IDs on the device |
| `GET /system/storages/{stid}/status` | Reports state, capacity, and free space |
| `GET /system/storages/{stid}/transfer/status` | Reports file transfer progress |
| `POST /system/storages/{stid}/control/eject` | Safely ejects removable storage |

**Storage IDs** are `main`, `external`, and `maintenance`.

**Storage states** are `ready`, `nodev` (no device present), `dev` (device found but not mounted), `devro` (write-protected), and `formatting`. When the state is `ready`, the response also reports `media_type` — `hd` for a SATA or NVMe drive, `sdcard` for an SD/MMC card, or `usb` for a USB drive — plus `total` and `free` in bytes.

```json
{
  "status": "ok",
  "result": { "state": "ready", "media_type": "sdcard", "total": 15809413120, "free": 11821019136 }
}
```

**Ejecting.** The main storage does not support eject, and calling the endpoint against it returns HTTP 405 with the message `Storage 'main' does not support eject`. Use eject on removable storage before physically removing it.

**Transfer status.** Transfer states are `completed`, `disabled`, `nomedia`, and `running`. A `session` block reports `started` and `completed` timestamps and `total` and `processed` counts and byte sizes, alongside `current_time`. Pass `storage=true` to include the storage status in the same response.

Transfer progress is not shown when the storage is used together with Automatic File Upload. The main storage does not support transfer, and calling that endpoint against it returns HTTP 405 with the message `Storage 'main' does not support transfer`.

An unknown storage ID returns 404 with a message such as `Storage 'wrongname' not found`.

> product: pearl-family · topic: other · source: pearl-rest-api.md · updated: Oct 7, 2026