Files

Endpoint references for uploading, fetching, listing, updating and deleting files. Listing, updating and deleting are the management endpoints: they need your private key and only ever touch your own app's files.

Get a file

Returns the file's contents. Reading a file does not need a key. The id can also be PUBLIC_KEY+LABEL.

GET

1
https://api.fileboy.io/files/get/:id/:filename

URL Params

The id of the file to fetch

filename optional

Specify the name of the file, overriding the saved value. This may still have an extension appended to it.

Query Params

download optional

If present, the file will be downloaded instead of opened.

Example

REQUEST

1
curl -X GET 'https://api.fileboy.io/files/get/9d44134a-0fac-4c6f-86bc-18780e8e0a45' --output ./file.txt

RESPONSE

1
// The file's bytes

Get file data

Fetches information about a file. Reading does not need a key.

GET

1
https://api.fileboy.io/files/data/:id

URL Params

The id of the file to fetch, or PUBLIC_KEY+LABEL

Response

id string

Unique file id

name string

File name

originalFilename string

The name of the file when it was uploaded, if available

mime string

Mime type of the file, eg. "image/png"

metadata object (key-value pairs)

Custom data provided with the upload

fileSize number

Size of the file in bytes

hash string

SHA1 hash of the file's contents

signed boolean

Whether the file was uploaded using a signed request

diesAt string or null

Timestamp when the file will be automatically deleted, if ever

createdAt string

Timestamp when the file was created

Example

REQUEST

1
curl https://api.fileboy.io/files/data/9d44134a-0fac-4c6f-86bc-18780e8e0a45

RESPONSE

1
2
3
4
5
6
7
8
9
10
11
12
{ "data": {
    "id": "9d44134a-0fac-4c6f-86bc-18780e8e0a45",
    "name": "logo.png",
    "originalFilename": "logo.png",
    "mime": "image/png",
    "metadata": { "orderId": "42" },
    "fileSize": 3535,
    "hash": "823e867b3ea91b9acb742ee12d5d31b4cb560137",
    "signed": true,
    "diesAt": null,
    "createdAt": "2026-08-24T15:06:19Z"
  } }

Get a file's share page

The data behind the file's share page, https://fileboy.io/f/:id: name, type, size and the URLs to show and download. 404 share_page_not_found unless the page is turned on. A file that needs a signed URL needs a signed share link's fb_exp and fb_sig (401 signature_required without), and the URLs in the answer are then signed with the same expiry.

GET

1
https://api.fileboy.io/files/:id/share

URL Params

The id of the file. Labels are not accepted.

Response

data.name string

The file's name.

data.mime string

The file's type.

data.fileSize number

Bytes.

data.width, data.height number | null

An image's size in pixels.

data.access "public" | "signed"

Whether it was opened with a signed share link.

data.expiresAt string | null

When a signed link and its URLs stop working.

data.urls object

view, download, images (resized previews for srcset) and thumbnail (a JPEG for link previews).

Example

REQUEST

1
curl https://api.fileboy.io/files/9d44134a-0fac-4c6f-86bc-18780e8e0a45/share

RESPONSE

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "data": {
    "id": "9d44134a-0fac-4c6f-86bc-18780e8e0a45",
    "name": "logo.png",
    "mime": "image/png",
    "fileSize": 48213,
    "createdAt": "2026-11-01T10:00:00Z",
    "width": 800,
    "height": 600,
    "access": "public",
    "expiresAt": null,
    "urls": {
      "view": "https://api.fileboy.io/files/get/9d44134a-0fac-4c6f-86bc-18780e8e0a45",
      "download": "https://api.fileboy.io/files/get/9d44134a-0fac-4c6f-86bc-18780e8e0a45?download",
      "images": [
        { "width": 640, "url": "https://api.fileboy.io/images/get/9d44...?transform=resize:640x_~upscale:false;format:auto" },
        { "width": 800, "url": "https://api.fileboy.io/images/get/9d44...?transform=resize:800x_~upscale:false;format:auto" }
      ],
      "thumbnail": "https://api.fileboy.io/images/get/9d44...?transform=resize:1200x_~upscale:false;format:jpg"
    }
  }
}

Upload file

Creates a new file. You can either provide the file data directly, or a URL for Fileboy to fetch it from.

POST

1
https://api.fileboy.io/files/upload

Body

file binary data, required unless a URL is provided

The content of the file to upload, as a multipart form field

url string

Source to obtain the file data from, required unless a file is provided

expect string or string[], optional

Expected mime type to be returned from the URL. The upload will fail if the response does not match it.

data string, optional

JSON encoded data to accompany a multipart upload

data.name string, optional, default is the uploaded file's name

File name

data.metadata object (key-value pairs), optional, default is {}

Custom data to be saved with the file

Response

data object

The new file, with the same fields as Get file data.

Example

REQUEST - File Data and Meta data

1
curl -X POST 'https://api.fileboy.io/files/upload' -H 'Authorization: public 9d44134a-0fac-4c6f-86bc-18780e8e0a45' -F 'file=@./logo.png' -F 'data={"name":"logo.png","metadata":{"alt":"The Fileboy logo"}}'

REQUEST - Using url for file

1
curl -X POST 'https://api.fileboy.io/files/upload' -H 'Authorization: public 9d44134a-0fac-4c6f-86bc-18780e8e0a45' -H 'Content-Type: application/json' -d '{"url":"http://www.example.com/logo.png"}'

RESPONSE

1
2
3
4
5
6
7
8
9
10
11
12
{ "data": {
    "id": "9d44134a-0fac-4c6f-86bc-18780e8e0a45",
    "name": "logo.png",
    "originalFilename": "logo.png",
    "mime": "image/png",
    "metadata": { "orderId": "42" },
    "fileSize": 3535,
    "hash": "823e867b3ea91b9acb742ee12d5d31b4cb560137",
    "signed": true,
    "diesAt": null,
    "createdAt": "2026-08-24T15:06:19Z"
  }, "accessToken": "" }

List files

Lists your app's files, newest first by default, one page at a time. Images Fileboy generates when resizing, and the parts of videos, are not listed. All filters combine. Needs a token signed with your private key. A public key, or a token limited to uploads or reads, is answered with 403 private_key_required.

GET

1
https://api.fileboy.io/files

Query Params

limit number, optional, default is 50

Page size, 1 to 100.

cursor string, optional

The nextCursor of the previous page. Use it with the same filters and sort. Paging is stable: files added or deleted while you page are never skipped or repeated.

sort createdAt | name | fileSize, optional, default is createdAt

What to sort by.

order asc | desc, optional

Defaults to desc, except for sort=name which defaults to asc.

label string, optional

Only the file this label points at.

mime string, optional

Only files whose type starts with this, like "image/" or "application/pdf".

name string, optional

Only files whose name contains this text, ignoring case.

hash string, optional

Only files with this SHA1 hash.

metadata[key] string, optional

Only files whose metadata has this key and exactly this value. Repeat for more pairs (up to 20), or send one JSON object as metadata={"orderId":"42"}.

createdBefore date or date-time, optional

Only files created before this, like 2026-01-31 or 2026-01-31T09:30:00Z.

createdAfter date or date-time, optional

Only files created after this.

Response

data object[]

The files on this page, each with the fields of Get file data plus labels.

Each file

id string

Unique file id

name string

File name

originalFilename string

The name of the file when it was uploaded, if available

mime string

Mime type of the file, eg. "image/png"

metadata object (key-value pairs)

Custom data provided with the upload

fileSize number

Size of the file in bytes

hash string

SHA1 hash of the file's contents

signed boolean

Whether the file was uploaded using a signed request

diesAt string or null

Timestamp when the file will be automatically deleted, if ever

createdAt string

Timestamp when the file was created

labels string[]

Labels that point at this file

nextCursor string or null

Pass as cursor to get the next page. Null on the last page.

Example

REQUEST - Images for one order

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

REQUEST - The next page

1
curl -G 'https://api.fileboy.io/files' -H 'Authorization: token 0000000....' --data-urlencode 'cursor=eyJzIjoiY3JlYXRlZEF0Ii...'

RESPONSE

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "data": [{
    "id": "9d44134a-0fac-4c6f-86bc-18780e8e0a45",
    "name": "logo.png",
    "originalFilename": "logo.png",
    "mime": "image/png",
    "metadata": { "orderId": "42" },
    "fileSize": 3535,
    "hash": "823e867b3ea91b9acb742ee12d5d31b4cb560137",
    "signed": true,
    "diesAt": null,
    "createdAt": "2026-08-24T15:06:19Z",
    "labels": ["logo"]
  }],
  "nextCursor": "eyJzIjoiY3JlYXRlZEF0IiwiZCI6dHJ1ZSwi..."
}

Update a file

Changes a file's name, type, metadata or labels. Only the fields you send change, and the stored bytes never change. Metadata is merged into the existing metadata: keys you send are set, a null value removes a key and every other key stays. Send replaceMetadata: true to make metadata the complete new metadata instead. A label points at one file, so adding a label that is on another file moves it to this one. Needs a token signed with your private key. A public key, or a token limited to uploads or reads, is answered with 403 private_key_required.

PATCH

1
https://api.fileboy.io/files/:id

URL Params

id string

The id of the file to update, or PUBLIC_KEY+LABEL.

Body

name string, optional

A new name for the file, 1 to 1024 characters.

mime string, optional

A new type for the file, like "image/png". This changes the Content-Type the file is served with.

metadata object (key-value pairs), optional

Pairs to set, null to remove a key. Up to 100 keys per request, keys up to 128 characters and values up to 4096. The stored metadata is limited to 16 KB.

replaceMetadata boolean, optional, default is false

Replace all the metadata with metadata instead of merging. Values cannot be null.

labels { add?: string[], remove?: string[] }, optional

Labels to point at this file or to take off it. Up to 20 of each. Label names have no spaces and none of - + / \ ? # % &.

sharePage boolean, optional

Turn the file's share page (https://fileboy.io/f/:id) on or off. It still follows the file's read access. See Share pages in the Delivery docs.

Response

data object

The file as it is now, with the fields of Get file data plus labels and sharePage.

Example

REQUEST

1
curl -X PATCH 'https://api.fileboy.io/files/9d44134a-0fac-4c6f-86bc-18780e8e0a45' -H 'Authorization: token 0000000....' -H 'Content-Type: application/json' --data '{"name":"new name.png","metadata":{"status":"approved","draft":null},"labels":{"add":["hero"]}}'

RESPONSE

1
2
3
4
5
6
7
8
9
10
11
12
13
{ "data": {
    "id": "9d44134a-0fac-4c6f-86bc-18780e8e0a45",
    "name": "new name.png",
    "originalFilename": "logo.png",
    "mime": "image/png",
    "metadata": { "orderId": "42" },
    "fileSize": 3535,
    "hash": "823e867b3ea91b9acb742ee12d5d31b4cb560137",
    "signed": true,
    "diesAt": null,
    "createdAt": "2026-08-24T15:06:19Z",
    "labels": ["hero"]
  } }

Delete a file

Removes a file, its stored data and any cached resized copies of it, and sends a file.deleted webhook. Answers 404 if there is no such file, which includes a file that was already deleted and a file that belongs to another app, so a repeated delete can treat 404 as done. If storage cannot be reached the answer is 500, nothing is deleted and the request can be repeated. Needs a token signed with your private key. A public key, or a token limited to uploads or reads, is answered with 403 private_key_required.

DELETE

1
https://api.fileboy.io/files/:id

URL Params

id string

The id of the file to delete, or PUBLIC_KEY+LABEL.

Response

(no body) 204

The file is gone.

Example

REQUEST

1
curl -X DELETE 'https://api.fileboy.io/files/9d44134a-0fac-4c6f-86bc-18780e8e0a45' -H 'Authorization: token 0000000....'

RESPONSE

1
// 204 No Content

Delete several files

Deletes up to 100 files in one request. Ids that are unknown, belong to another app or are already deleted are listed in notFound and are not an error, so the same request can be sent again safely. A file whose stored data cannot be removed is left as it was and listed in failed: send it again. One file.deleted webhook is sent per deleted file. Needs a token signed with your private key. A public key, or a token limited to uploads or reads, is answered with 403 private_key_required.

POST

1
https://api.fileboy.io/files/delete

Body

ids string[]

The ids of the files to delete, 1 to 100 of them.

Response

data.deleted string[]

Files that were deleted.

data.notFound string[]

Unknown ids, other apps' files and files that were already deleted.

data.failed { id, message }[]

Files that are still there because storage could not be reached.

Example

REQUEST

1
curl -X POST 'https://api.fileboy.io/files/delete' -H 'Authorization: token 0000000....' -H 'Content-Type: application/json' --data '{"ids":["9d44134a-0fac-4c6f-86bc-18780e8e0a45","5f0c2f3e-6f4e-4a4c-8c9c-1f5f0a1b2c3d"]}'

RESPONSE

1
2
3
4
5
6
7
{
  "data": {
    "deleted": ["9d44134a-0fac-4c6f-86bc-18780e8e0a45"],
    "notFound": ["5f0c2f3e-6f4e-4a4c-8c9c-1f5f0a1b2c3d"],
    "failed": []
  }
}

Api reference

Get a fileGet file dataGet a file's share pageUpload fileList filesUpdate a fileDelete a fileDelete several files

Getting Started

Uploads

Delivery

Video

Libraries

API Reference

Files

Get a file

Get file data

Upload file

List files

Update a file

Delete a file

Delete several files

Api reference