Manage files and videos

// one page, newest first. Needs the private key.
const page = await fileboy.listFiles({
  mime: "image/",
  metadata: { orderId: "42" },
  limit: 25,
})
page.data.forEach(file => console.log(file.id, file.name, file.labels))

// the next page
if (page.nextCursor) {
  await fileboy.listFiles({ mime: "image/", metadata: { orderId: "42" }, cursor: page.nextCursor })
}

# one page, newest first. Needs the private key.
page = fileboy.list_files(mime: "image/", metadata: { orderId: "42" }, limit: 25)
page.items.each { |file| puts "#{file.id} #{file.name} #{file.labels}" }

# or walk every page
fileboy.each_file(mime: "image/") { |file| puts file.name }

# one page, newest first. Needs the private key.
page = client.list_files(mime="image/", metadata={"orderId": "42"}, limit=25)
for file in page.items:
    print(file.id, file.name, file.labels)

# or walk every page
for file in client.iter_files(mime="image/"):
    print(file.name)

// one page, newest first. Needs the private key.
$page = $fileboy->listFiles(['mime' => 'image/', 'metadata' => ['orderId' => '42'], 'limit' => 25]);
foreach ($page->data as $file) {
    echo $file->id, ' ', $file->name, "
";
}

// or walk every page
foreach ($fileboy->eachFile(['mime' => 'image/']) as $file) {
    echo $file->name, "
";
}

curl -G https://api.fileboy.io/files \
  -H "Authorization: token YOUR_SIGNED_TOKEN" \
  --data-urlencode "mime=image/" \
  --data-urlencode "metadata[orderId]=42" \
  --data-urlencode "limit=25"

// metadata is merged: a null value removes a key
const updated = await fileboy.updateFileData(file.id, {
  name: "invoice-1042-final.pdf",
  metadata: { status: "paid", draft: null },
  labels: { add: ["latest-invoice"] },
})

# metadata is merged: nil removes a key
updated = fileboy.update_file(
  file.id,
  name: "invoice-1042-final.pdf",
  metadata: { status: "paid", draft: nil },
  labels: { add: ["latest-invoice"] }
)

# metadata is merged: None removes a key
updated = client.update_file(
    file.id,
    name="invoice-1042-final.pdf",
    metadata={"status": "paid", "draft": None},
    add_labels=["latest-invoice"],
)

// metadata is merged: null removes a key
$updated = $fileboy->updateFile($file->id, [
    'name' => 'invoice-1042-final.pdf',
    'metadata' => ['status' => 'paid', 'draft' => null],
    'labels' => ['add' => ['latest-invoice']],
]);

curl -X PATCH https://api.fileboy.io/files/FILE_ID \
  -H "Authorization: token YOUR_SIGNED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"invoice-1042-final.pdf","metadata":{"status":"paid","draft":null},"labels":{"add":["latest-invoice"]}}'

import { notFoundError } from "@cd2/fileboy-node"

try {
  await fileboy.destroyFile(file.id)
} catch (e) {
  if (!notFoundError.is(e)) throw e // already gone is fine
}

begin
  fileboy.delete_file(file.id)
rescue Fileboy::NotFoundError
  # already gone is fine
end

try:
    client.delete_file(file.id)
except fileboy.NotFoundError:
    pass  # already gone is fine

try {
    $fileboy->deleteFile($file->id);
} catch (\Fileboy\Exception\NotFoundException $e) {
    // already gone is fine
}

curl -X DELETE https://api.fileboy.io/files/FILE_ID \
  -H "Authorization: token YOUR_SIGNED_TOKEN"
# 204 when deleted, 404 when there is no such file

// up to 100 ids. Unknown ids are reported, not thrown.
const { deleted, notFound, failed } = await fileboy.destroyFiles(ids)

# up to 100 ids. Unknown ids are reported, not raised.
result = fileboy.delete_files(ids)
result.deleted    # ids that were deleted
result.not_found  # unknown or already deleted
result.failed     # still there because storage was unreachable: send again

# up to 100 ids. Unknown ids are reported, not raised.
result = client.delete_files(ids)
result.deleted    # ids that were deleted
result.not_found  # unknown or already deleted
result.failed     # still there because storage was unreachable: send again

// up to 100 ids. Unknown ids are reported, not thrown.
$result = $fileboy->deleteFiles($ids);
$result->deleted;    // ids that were deleted
$result->notFound;   // unknown or already deleted
$result->failed;     // still there because storage was unreachable: send again

curl -X POST https://api.fileboy.io/files/delete \
  -H "Authorization: token YOUR_SIGNED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ids":["FILE_ID_1","FILE_ID_2"]}'

// needs the private key: the answer can hold the GPS position and serial numbers
const exif = await fileboy.getFileExif(file.id)
exif.fields.model // "iPhone 15 Pro"
exif.fields.shutterSpeed // "1/60"
exif.fields.dateTaken // "2026-02-19T14:22:37.146-08:00"
exif.fields.gps // { latitude: 51.5007, longitude: -0.1246, altitude: 13.21 } or null

// without GPS, place names, serial numbers or the owner, to show your own users
const shareable = await fileboy.getFileExif(file.id, { personal: false })

# needs the private key: the answer can hold the GPS position and serial numbers
exif = fileboy.fetch_file_exif(file.id)
exif.fields.model         # => "iPhone 15 Pro"
exif.fields.date_taken    # => "2026-02-19T14:22:37.146-08:00"
exif.fields.gps&.latitude # => 51.5007

shareable = fileboy.fetch_file_exif(file.id, personal: false)

# needs the private key: the answer can hold the GPS position and serial numbers
exif = client.get_file_exif(file.id)
exif.fields.model       # "iPhone 15 Pro"
exif.fields.date_taken  # "2026-02-19T14:22:37.146-08:00"
exif.fields.gps         # ExifGps(latitude=51.5007, longitude=-0.1246, altitude=13.21) or None

shareable = client.get_file_exif(file.id, personal=False)

// needs the private key: the answer can hold the GPS position and serial numbers
$exif = $fileboy->getFileExif($file->id);
echo $exif->fields->model;          // iPhone 15 Pro
echo $exif->fields->dateTaken;      // 2026-02-19T14:22:37.146-08:00
$exif->fields->gps?->latitude;      // 51.5007, or null

$shareable = $fileboy->getFileExif($file->id, personal: false);

curl https://api.fileboy.io/files/FILE_ID/exif \
  -H "Authorization: token YOUR_SIGNED_TOKEN"

# without the personal data
curl "https://api.fileboy.io/files/FILE_ID/exif?personal=false" \
  -H "Authorization: token YOUR_SIGNED_TOKEN"

// 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

const { data: videos } = await fileboy.listVideos({ status: "ready", limit: 20 })

await fileboy.updateVideo(videos[0].id, { name: "Launch day" })
await fileboy.destroyVideo(videos[0].id) // original, renditions, posters and transcripts

page = fileboy.list_videos(status: "ready", limit: 20)

fileboy.update_video(page.items.first.id, name: "Launch day")
fileboy.delete_video(page.items.first.id) # original, renditions, posters and transcripts

page = client.list_videos(status="ready", limit=20)

client.update_video(page.items[0].id, name="Launch day")
client.delete_video(page.items[0].id)  # original, renditions, posters and transcripts

$page = $fileboy->listVideos(['status' => 'ready', 'limit' => 20]);

$fileboy->updateVideo($page->data[0]->id, 'Launch day');
$fileboy->deleteVideo($page->data[0]->id); // original, renditions, posters and transcripts

curl -G https://api.fileboy.io/videos -H "Authorization: token YOUR_SIGNED_TOKEN" -d status=ready
curl -X DELETE https://api.fileboy.io/videos/VIDEO_ID -H "Authorization: token YOUR_SIGNED_TOKEN"

const labels = await fileboy.listLabels()
await fileboy.createLabel("hero", { fileId: file.id })
await fileboy.destroyLabel("hero") // the file is kept

labels = fileboy.list_labels
fileboy.create_label("hero", file_id: file.id)
fileboy.delete_label("hero") # the file is kept

labels = client.list_labels()
client.create_label("hero", file_id=file.id)
client.delete_label("hero")  # the file is kept

$labels = $fileboy->listLabels();
$fileboy->createLabel('hero', $file->id);
$fileboy->deleteLabel('hero'); // the file is kept

curl -X POST https://api.fileboy.io/labels \
  -H "Authorization: token YOUR_SIGNED_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"hero","fileId":"FILE_ID"}'

// The description shows on the watch page. Tags and metadata are private.
const video = await fileboy.updateVideo(videoId, {
  description: "Our launch, in two minutes.",
  tags: { add: ["launch"], remove: ["draft"] }, // or a list to replace them
  metadata: { orderId: "42", draft: null }, // merged, null removes a key
})

// Videos with every one of the tags and all of the pairs
const { data } = await fileboy.listVideos({ tags: ["launch"], metadata: { orderId: "42" } })

# The description shows on the watch page. Tags and metadata are private.
video = fileboy.update_video(video_id, description: "Our launch, in two minutes.",
                                       tags: { add: ["launch"], remove: ["draft"] },
                                       metadata: { orderId: "42", draft: nil })

# Videos with every one of the tags and all of the pairs
page = fileboy.list_videos(tags: ["launch"], metadata: { orderId: "42" })

# The description shows on the watch page. Tags and metadata are private.
video = client.update_video(video_id, description="Our launch, in two minutes.",
                            add_tags=["launch"], remove_tags=["draft"],
                            metadata={"orderId": "42", "draft": None})

# Videos with every one of the tags and all of the pairs
page = client.list_videos(tags=["launch"], metadata={"orderId": "42"})

// The description shows on the watch page. Tags and metadata are private.
$video = $fileboy->updateVideo($videoId, [
    'description' => 'Our launch, in two minutes.',
    'tags' => ['add' => ['launch'], 'remove' => ['draft']],
    'metadata' => ['orderId' => '42', 'draft' => null],
]);

// Videos with every one of the tags and all of the pairs
$page = $fileboy->listVideos(['tags' => ['launch'], 'metadata' => ['orderId' => '42']]);

curl -X PATCH https://api.fileboy.io/videos/VIDEO_ID \
  -H "Authorization: token YOUR_SIGNED_TOKEN" -H "Content-Type: application/json" \
  -d '{"description":"Our launch, in two minutes.","tags":{"add":["launch"]},"metadata":{"orderId":"42"}}'

curl -G https://api.fileboy.io/videos -H "Authorization: token YOUR_SIGNED_TOKEN" \
  -d tags=launch --data-urlencode 'metadata[orderId]=42'

const usage = await fileboy.getUsage()
console.log(usage.files, usage.storageBytes, usage.limits.storageBytes)

usage = fileboy.fetch_usage
puts "#{usage.files} files, #{usage.storage_bytes} bytes"

usage = client.get_usage()
print(usage.files, usage.storage_bytes, usage.limits.storage_bytes)

$usage = $fileboy->getUsage();
echo $usage->files, ' files, ', $usage->storageBytes, " bytes
";

curl https://api.fileboy.io/usage -H "Authorization: token YOUR_SIGNED_TOKEN"

const storage = await fileboy.getStorageUsage({ days: 90 })
console.log(storage.kinds.videoRenditions.bytes, storage.largestFiles[0]?.name)
for (const day of storage.history) console.log(day.date, day.storageBytes)

storage = fileboy.fetch_storage_usage(days: 90)
puts storage.kinds["videoRenditions"].bytes, storage.largest_files.first&.name
storage.history.each { |day| puts "#{day.date} #{day.storage_bytes}" }

storage = client.get_storage_usage(days=90)
print(storage.kinds["videoRenditions"].bytes, storage.largest_files[0].name if storage.largest_files else None)
for day in storage.history:
    print(day.date, day.storage_bytes)

$storage = $fileboy->getStorageUsage(['days' => 90]);
echo $storage->kinds['videoRenditions']['bytes'], "\n";
foreach ($storage->history as $day) { echo $day['date'], ' ', $day['storageBytes'], "\n"; }

curl 'https://api.fileboy.io/usage/storage?days=90' -H "Authorization: token YOUR_SIGNED_TOKEN"