Files, folders & stats

List, move and inspect what you have stored.

All endpoints below are under https://upload.basix.media/api/v1.

Method	Path	What it does	Scope
GET	`/files`	List files, newest first. `limit` 1-100 (default 50), `cursor`, `search` (matches the original file name).	upload
GET	`/files/<id>`	One file, with `sha256`, `createdAt`, `updatedAt`.	upload
DELETE	`/files/<id>`	Move the file to the trash. Answers `204`.	full
GET	`/files/<id>/stats?days=30`	Daily requests and bytes served. `days` 1-90.	upload
GET	`/files/top?days=7&by=views&limit=10`	Most served files. `days` 7 or 30, `by` `views` or `bandwidth`, `limit` 1-100.	upload
POST	`/folders`	Create a folder: `{ "path": "screenshots" }`. Returns `{ id, path }`. Calling it again returns the same folder.	upload
PATCH	`/folders/<id>`	Set retention: `{ "retentionDays": 30 }`, or `null` to clear.	full
DELETE	`/folders/<id>`	Delete an empty folder.	full
GET	`/trash`	Deleted files that can still be restored, with `purgesAt`.	upload
POST	`/trash/<id>`	Restore a deleted file.	full
DELETE	`/trash/<id>`	Destroy it now.	full

List response. Pass nextCursor back as cursor. It is null on the last page.

json

{
  "files": [
    {
      "id": "k7x2m9q4pz1a",
      "name": "potion.png",
      "path": "shop/potions/potion_x2.png",
      "url": "https://cdn.basix.media/a7k2m9x4/shop/potions/potion_x2.png",
      "size": "15320",
      "mime": "image/png",
      "createdAt": "2026-10-25T14:00:00.000Z"
    }
  ],
  "nextCursor": "MjAyNi0xMC0yNVQxNDowMDowMC4wMDBafGs3eDJtOXE0cHoxYQ"
}

curl "https://upload.basix.media/api/v1/files?limit=100" \
  -H "Authorization: Bearer $BASIX_KEY"

Stats responses:

json

{
  "id": "k7x2m9q4pz1a",
  "days": 30,
  "totals": { "requests": 1840, "bytes": "92160000" },
  "daily": [ { "date": "2026-10-24", "requests": 61, "bytes": "3050000" } ]
}

json

{
  "days": 7,
  "by": "views",
  "files": [ { "id": "k7x2m9q4pz1a", "path": "items/burger.png", "url": "...", "requests": 420, "bytes": "21000000" } ]
}

Stats are compiled nightly from CDN traffic and kept for 90 days.

Trash. A deleted file stops being served and leaves your quota at once. It stays restorable for the trash window of your plan (see Plans and limits). GET /trash returns it as windowDays. Restoring can fail with NOT_FOUND (window passed), QUOTA_EXCEEDED (no room) or PATH_CONFLICT (a live file now uses that path).

Retention. Off by default. Set it per folder: 7, 30, 90, 180 or 365 days. Expired files go to the trash, not to nothing. Files uploaded with retentionExempt: true (base64 and compatible endpoints) are never expired.

curl

curl -X POST https://upload.basix.media/api/v1/folders \
  -H "Authorization: Bearer $BASIX_KEY" -H "Content-Type: application/json" \
  -d '{ "path": "screenshots" }'

curl -X PATCH https://upload.basix.media/api/v1/folders/<id> \
  -H "Authorization: Bearer $BASIX_KEY" -H "Content-Type: application/json" \
  -d '{ "retentionDays": 30 }'

Try it on your own server

Create a free account and your API key is ready in about two minutes. 3 GB included, bandwidth never billed, no card needed.

Create a free account

← PreviousCDN URLs & image variants Next →Logs