Key Concepts

File Data

Every stored fileboy has a set of common features where are either provided by you when you upload a file, or computed by us when we store one.

• id a unique identifier used to retrieve a file.
• name a identifying name which can help you to organize files. File names are optional so may be undefined, but we will try to extract it from whatever you upload.
• fileSize the size of the file in bytes.
• mime the type of file uploaded such as image/png or application/pdf.
• createdAt the time and date the file was uploaded at.
• metadata optional data that can be sent during upload, this could be used for anything you want, such as alt text for images, filenames, name of the user who uploaded the file. Metadata is searchable so can be used to identify and group files. The data must be a JSON object with only string values:

  { "author": "bob", "usage": "header" }

  is fine, but

  { "popularity": 2 }

  is not.
  metadata can also be edited from your application files index page, where you can add, edit and remove keys and values
• diesAt indicates when a file will be removed if not marked as permanent. See temporary uploads for more information.
• signed a boolean indicating whether the upload was approved by your servers or whether it was an anonymous upload.

App Keys

When you create an app you will get given a public key and a private key. The public key is used to identify your app, you will need to supply this when uploading files to fileboy. Your private key should be kept a secret and never shared. You will need this key when performing administrative tasks such as deleting files and marking files as permanent.

Temporary Uploads

When a file is uploaded to Fileboy we check to see if it was sent by a known source such as your own servers (i.e it is signed with your private key) if it is, then we store the file and mark is as permanent. However, if the upload is not verified, then the file will be marked as temporary and assigned a diesAt time. The diesAt time will be 24 hours from when the file was uploaded.

When this time has been reached the file will be removed and will no longer be accessible.

Temporary files can be marked as permanent after they have been uploaded by sending a "save" request from your server. Doing this will nullify the diesAt time and therefore the file will be stored permanently.

Transformations

A transformation is a live mutation of file data, requested by you and performed by us. They allow you to deliver content in the most convenient manner for your users. The type of transformations available to you change depending on the filetype, for instance you can resize and compress image files or request Excel documents as CSV files. We classify all these mutations as transforms.

For a list of current transformation options see the transformation section of the docs.

File Labels

File labels provide a way of referencing files without relying on their randomly generated ids. You can manage labels from your app dashboard, meaning that you can embed an image tag for "logo_thumbnail" in your application, then pick which file you want it to point to later on.

Once you've created a file label, you can use it at the API (or with one of our libraries) by joining it to your public key with a + symbol:

MY_PUBLIC_KEY + "+" + myLabel

"3b7da6aa-00a7-40df-86fb-8e1258491989+logo_thumbnail"

You can change which file the label points to at any time, allowing you to update files in-place without redeploying your application.