Folders

Put files in folders, nest folders inside each other, and browse them like a drive in the dashboard or through the API.

How folders work

A file is in one folder, or in none. Files that are in no folder are at the top level, which is where every file uploaded before folders existed still is. Folders can hold files and other folders, up to 20 levels deep, and an app can have up to 10,000 of them.

Folders only organise files. A folder is never part of a file's URL, so renaming or moving a folder, or moving a file to another folder, never changes a link. Keep storing the file's ID (or a label) as you do today.

Folder names are 1 to 255 characters, can contain spaces, and cannot contain

. Two folders in the same place cannot have the same name, ignoring case, so a path such as

/Products/Shoes

always means one folder. Paths are matched ignoring case too.

Folders do not change who can read a file. A file's read permission and signed URLs work exactly the same in any folder, and the public file details endpoint does not show which folder a file is in.

In the dashboard

The Files page of each app shows the folders at the top of the list. Open one to see what is inside, with breadcrumbs back up. From there you can:

create a folder with New folder, inside the one you have open;
upload straight into the open folder, with the button or by dropping files;
select files and choose Move to put them in another folder;
rename, move or delete a folder from its row, or from the top of its page;
search the open folder and everything below it.

A file's own page shows its folder under Settings, with a Move button.

From your server

The folder endpoints need your private key, like the rest of the management API. The Node, Ruby, Python and PHP libraries have a method for each.

// mkdir -p: makes any folder on the path that is missing
const shoes = await fileboy.createFolder({ path: "/Products/Shoes" })

await fileboy.uploadFileFromPath("./red.png", { folderPath: "/Products/Shoes" })
const page = await fileboy.listFiles({ folderId: shoes.id }) // or { folderPath: "/Products", recursive: true }

await fileboy.moveFiles([file.id], { folderId: shoes.id }) // { folderId: null } is the top level
await fileboy.updateFolder(shoes.id, { name: "Trainers" }) // links to the files don't change
await fileboy.destroyFolder(shoes.id, { contents: "moveToParent" })

shoes = fileboy.create_folder(path: "/Products/Shoes")

fileboy.upload_file("red.png", folder_path: "/Products/Shoes")
page = fileboy.list_files(folder_id: shoes.id)

fileboy.move_files([file.id], folder_id: shoes.id)
fileboy.update_folder(shoes.id, name: "Trainers")
fileboy.delete_folder(shoes.id, contents: "moveToParent")

shoes = client.create_folder(path="/Products/Shoes")

client.upload_file("red.png", folder_path="/Products/Shoes")
page = client.list_files(folder_id=shoes.id)

client.move_files([file.id], shoes.id)
client.update_folder(shoes.id, name="Trainers")
client.delete_folder(shoes.id, contents="moveToParent")

$shoes = $fileboy->createFolder(path: '/Products/Shoes');

$fileboy->uploadFile('red.png', folderPath: '/Products/Shoes');
$page = $fileboy->listFiles(['folderId' => $shoes->id]);

$fileboy->moveFiles([$file->id], $shoes->id);
$fileboy->updateFolder($shoes->id, ['name' => 'Trainers']);
$fileboy->deleteFolder($shoes->id, 'moveToParent');

curl -X POST https://api.fileboy.io/folders \
  -H "Authorization: token YOUR_SIGNED_TOKEN" -H "Content-Type: application/json" \
  -d '{"path":"/Products/Shoes"}'
curl -G https://api.fileboy.io/files -H "Authorization: token YOUR_SIGNED_TOKEN" \
  --data-urlencode folderPath=/Products/Shoes

Create a folder with a

name

(and a

parentId

to put it inside another), or with a

path

to make every missing folder on it at once. A path that already exists is not an error: you get the folder back, so it is safe to call before every upload.

Uploading into a folder

Send

folderId

folderPath

with the upload, next to

name

and

metadata

. The upload response includes the file's

folderId

and

folderPath

An upload signed with your private key creates any folders on

folderPath

that are missing. Uploads from a browser, with the public key or an access token, can only use folders that already exist: a missing folder is a

404 folder_not_found

and nothing is stored. That way visitors can drop files into the folder you chose, but cannot add folders to your app. Create the folder from your server first.

React

1
2
3
4
5
6
7
8
import { MultiFileUploader } from "@cd2/fileboy-react"

<MultiFileUploader
  folderPath="/uploads/avatars"
  onFilesUploaded={files => save(files)}
/>

Browser script

1
<input type="hidden" data-fileboy="folderPath=/uploads/avatars" name="avatar" />

Listing files by folder

GET /files

takes

folderId

(or

root

for files in no folder) or

folderPath

, and

recursive=true

to include the files in every folder below. It combines with the other filters, such as

mime

and

metadata

. Without a folder filter it lists every file in the app, in any folder, as it always has.

GET /folders

lists folders: all of them, the top level with

parentId=root

, or the ones inside a folder. Each has its

path

, its

parentId

and how many files and folders are directly inside.

GET /folders/:id

adds

ancestors

, the folders above it, for breadcrumbs.

Deleting a folder

DELETE /folders/:id

only deletes an empty folder unless you say what should happen to what is inside, with

contents

```
refuse
```
(the default): a folder with anything in it is a
```
409 folder_not_empty
```
, and nothing changes.
```
moveToParent
```
: its files and folders move up a level (to the top level, for a top-level folder) and only the folder is deleted.
```
delete
```
: the folder, its subfolders and every file in them are deleted, stored data included, with a
```
file.deleted
```
webhook for each file. Up to 1,000 files; empty bigger folders with bulk delete first.

Deleting a file on its own just takes it out of its folder. The folder stays.

Folders

How folders workIn the dashboardFrom your serverUploading into a folderListing files by folderDeleting a folder

Getting Started

Uploads

Delivery

Video

Libraries

API Reference

Folders

How folders work

In the dashboard

From your server

Uploading into a folder

Listing files by folder

Deleting a folder

Folders