List Storage

Use this endpoint to browse storage one level at a time. It returns the folders and files directly inside the path you ask for, and does not descend into subfolders.

Endpoint

GET /storage

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

Query parameters

string

default:""

Folder to list, relative to the storage root. Omit it or pass an empty string to list the root.photos · photos/2026/spring

Response

Returns one level. Folders carry only their name and path: to get item counts or preview thumbnails for them, call folder summaries for the folders you actually render. That split keeps this endpoint’s latency independent of how many subfolders a level holds.

{
  "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"
    }
  ]
}

string

The normalized folder that was listed. Empty string for the root.

array

Subfolders of this level, sorted by name.

Show Folder object

string

Folder name, without any parent path.

string

Full path relative to the storage root. Pass this back as path to descend into it, or as the {path} segment of the other storage endpoints.

array

Files in this level, sorted by name.

Show File object

string

File name, without any parent 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.

number

Size in bytes. May be absent on cloud storage backends that do not report it for a given object.

string

ISO 8601 last-modified timestamp. May be absent for the same reason as size.

Status codes:

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

Examples

List the root:

curl http://localhost:3000/storage \
  -H "Authorization: Bearer <api_key>"

List one folder:

curl "http://localhost:3000/storage?path=photos/2026" \
  -H "Authorization: Bearer <api_key>"

There is no endpoint that returns the whole tree in one call. Walk the tree by calling this endpoint once per folder, using each folder’s path.

Stats & Folder Summaries

Item counts and preview thumbnails, plus aggregate usage.

File Metadata

Get size and timestamps for a specific file.

Move File or Folder

Move a file or folder into a different parent folder.

Delete

Remove a file or a folder and its cached variants.

Overview

Media

Files

Storage

Cache

Video Processing

API Keys

System

Endpoint

Query parameters

Response

Examples

Stats & Folder Summaries

File Metadata

Move File or Folder

Delete

​Endpoint

​Query parameters

​Response

​Examples

​Related

Stats & Folder Summaries

File Metadata

Move File or Folder

Delete

Endpoint

Query parameters

Response

Examples

Related