Folders

Folders are APULODI's logical organization layer — a navigable tree over your files. They are designed to feel like a filesystem:

text

users/
users/avatars/
users/documents/
products/
products/images/

Folders are created automatically when you upload a file into a path — there is no create endpoint, and there is deliberately no delete/rename (changes happen by updating your files' path). They are metadata only: a folder never affects how or where your bytes are stored.

List folders

http

GET /v1/folders?path=users

Omit path (or pass "") to list the project root's folders.

bash

curl "https://api.apulodi.com/v1/folders?path=users" \
  -H "Authorization: Bearer $APULODI_API_KEY"

json

{
  "data": [
    {
      "id": "cm…",
      "name": "avatars",
      "path": "users/avatars",
      "parentId": "cm…",
      "createdAt": "2026-01-02T10:00:00.000Z"
    }
  ]
}

When the path does not exist, the response is { "data": [] }.

Using folders with uploads

Pass path when you initiate an upload:

json

{
  "filename": "avatar.jpg",
  "contentType": "image/jpeg",
  "size": 245123,
  "path": "users/avatars"
}

The full chain users → users/avatars is created if missing. Root-level files have path: null. Files in deleted folders keep their logical path.

Next: Multipart uploads — large files, chunked.

← Files

Multipart uploads →