> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openinary.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# List Storage

> List the folders and files in one storage level

Browse storage one level at a time. The response holds the folders and files directly inside the path you ask for, and never descends into subfolders.

```
GET /storage
```

```bash theme={null}
curl "https://cdn.openinary.dev/storage?path=photos/2026" \
  -H "Authorization: Bearer <api_key>"
```

Omit `path`, or pass an empty string, to list the root. No endpoint returns the whole tree: walk it by calling this one once per folder, using each folder's `path`.

**Auth:** API key required. A dashboard session cookie also works.

## Query parameters

| Param | Type | Default | Description |
| - | - | - | - |
| `path` | string | `""` | Folder to list, relative to the storage root, e.g. `photos/2026`. |

## Response

```json theme={null}
{
  "path": "photos",
  "folders": [{ "name": "2026", "path": "photos/2026" }],
  "files": [
    {
      "name": "portrait.jpg",
      "path": "photos/portrait.jpg",
      "size": 248192,
      "mtime": "2026-03-15T10:30:00.000Z"
    }
  ]
}
```

| Field | Type | Description |
| - | - | - |
| `path` | string | The normalized folder that was listed. Empty for the root |
| `folders` | array | Subfolders of this level, sorted by name |
| `files` | array | Files in this level, sorted by name |

Folder object:

* `name`, string: folder name, without any parent path
* `path`, string: full path relative to the storage root. Pass it back as `path` to descend into it, or as the `{path}` segment of the other storage endpoints

File object:

* `name`, string: file name, without any parent path
* `path`, string: full path relative to the storage root. Use it as the `{path}` segment of the other storage endpoints, and after `/t/` to deliver the file
* `size`, number: size in bytes. May be absent on cloud storage backends that do not report it for a given object
* `mtime`, string: ISO 8601 last-modified timestamp. May be absent for the same reason as `size`

Folders carry only their name and path. For item counts or preview thumbnails, call [folder summaries](https://docs.openinary.dev/api-reference/storage/stats.md#folder-summaries) for the folders you actually render, which keeps this endpoint's latency independent of how many subfolders a level holds.

| Code | Meaning |
| - | - |
| `200` | Level returned |
| `400` | `path` escapes the storage root or is malformed |
| `500` | Storage backend failed to list |

## Related

> [card] [Stats & Folder Summaries](https://docs.openinary.dev/api-reference/storage/stats.md)
>
> Item counts and preview thumbnails, plus aggregate usage.

> [card] [File Metadata](https://docs.openinary.dev/api-reference/storage/metadata.md)
>
> Get size and timestamps for a specific file.

> [card] [Move File or Folder](https://docs.openinary.dev/api-reference/storage/move.md)
>
> Move a file or folder into a different parent folder.

> [card] [Delete](https://docs.openinary.dev/api-reference/storage/delete.md)
>
> Remove a file or a folder and its cached variants.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.