LiquidFiles Documentation

The most common use of the API is to use it to send files.

Before sending our first file, a little bit a background information is required. When LiquidFiles sends a file, it really sends a message, with files attached to it. Same with a FileLink, it's a FileLink object with a file (attachment) attached to it. The Message or FileLink is what has all the meta data such as expiration and it's when the message expires that the files attached to it gets deleted as well.

Sending large files is difficult. If it was easy, a product such as LiquidFiles wouldn't be needed in the first place. To upload the actual file to the LiquidFiles system, we have three different methods — Binary Uploads, HTML Form Based Uploads or JSON based uploads.

Upload Method Overview

JSON Based Uploads

The typical modern web based API format is JSON, which is a text based format that is also used by LiquidFiles for all LiquidFiles API functions. It's a simple, well documented format that is strictly text based, which means that we have to Base64 encode binary data (which basically stretches 3 bytes of binary data over 4 bytes only using text characters) that is a lot less efficient than either the binary or the HTML based upload methods, but has the benifit of being able to be easily defined in API. If you're sending smaller files (sensitive PDF documents that are fairly small for instance), this is the easiest to use.

Binary Uploads

This is the method that's used by all the builtin LiquidFiles functions. So if you upload a file using the web interface, the Outlook plugin, Mac plugin and so on, it's using the binary upload method. It's basically sending the raw binary data to the LiquidFiles system and is the most efficient way of uploading files to a web server. It is also probably the most complex/least supported in terms of support from external libraries if you want to incorporate this into an existing project.

HTML Form Based Uploads

This is the previous method used by the builtin LiquidFiles functions and mimics what happens when someone uses a HTML (multipart/form-data) form element to upload files. This is now considered legacy and you should if possible use the Binary Upload method instead. The HTML Form Based Upload is the method that's been used on the web for uploading files since it was first introduced way back in the 1990s. It's a very well documented way of uploading files, but adds some preamble to the actual data and requires web server plugins to process the file on the server side so is not as efficient as uploading files using the binary upload method.

Please see the Form Based Attachment Upload documenation for further information.

JSON based uploads

JSON is what's being used for all other aspects of the LiquidFiles but when it comes to sending files it poses a bit of a problem. Consider the following example request:

  {"attachments": [{

Since JSON is a text based protocol, we can't just insert binary data in it in the "data" tag. The standard programatical solution to problems like this is to Base64 encode the binary data into something that can be transmitted over text. This works, but using Base64 encoding has several problems though, some of which include:

  • Aproximately 33% file size increase. We're taking 3 bytes or binary data and spreading over 4 bytes using only the text writable characters. With large files, this leads to a significant increase.
  • It's impossible to do any fancy server side file handling. The entire JSON request will be loaded into the web application. Normally when files are sent using LiquidFiles, the web server (nginx) takes care of the binary file data and the web application only deals with moving files around but the actual file data never passes through the web application. This keeps LiquidFiles fast and efficient. If you sent a 1Gb file using this method, first it would be 1.3Gb transferred (Base64) and this would be loaded (twice - raw Base64 data and decoded) into the memory of LiquidFiles before it could write it to disk. This is very slow and inefficient.
  • With these limitations, the maximum message size (all files combined) you can send with this method is 100 Mb. While this should still be plenty for most applications, if you send files near that size on a regular basis, it's the recommendation to switch to the form based upload mechanism instead.

When sending files using JSON, you add it directly into the message. Please see the Sending Files API documentation for an example how to send files directly using Base64 encoded file data.

Binary Data Uploads

There's two parts to a HTML POST statement, it's the body of the POST and it's the parameters. In a traditional HTML post, the parameters are hidden within the body of the POST, but there's no reason they have to. With the LiquidFiles binary upload method, we're actually using GET style parameters to pass additional information. It looks like this:

Request Info
Info Value
Request URL /attachments/binary_upload
Request Parameters
Parameter Type Description
filename String The filename of the uploaded file.
filename String (Optional) Content-Type of the uploaded file. Will detect using the Linux `file` command if not provided.
pool_id Integer (optional) If this file is for a pool.
chunks Integer (optional) When uploading files in chunks (in pieces), these are the total number of pieces there is.
chunk Integer optional and required when chunks is set) When uploading files in chunks, this is the current chunk number, with the first chunk being chunk number 0 (zero).
Response Parameters
Parameter Type Description
id String The Attachment ID
filename String The Attachment Filename
size Integer Exact File Size in Bytes
size_human String Approximate, human friendly, file size (11.2 MB, 23.3 KB, ...)
content_type String The Content-Type
checksum String SHA-256 Checksum
crc32 String CRC32 Checksum
assembled Boolean True if the attachment has been assembled or not (when uploading multiple chunks)
virus_scan_required Boolean True if the attachment is required to be Virus Scanned.
virus_scanned Boolean True if the attachment has been Virus Scanned.
virus_scanned_at DateTime When the Virus Scanner last scanned this attachment.
content_blocked Boolean True if the attachment has been blocked (by the Virus Scanner or ActionScript).
content_blocked_message String If the attachment has been blocked, this will display the reason.
actionscript String If the attachment needs to be scanned by an ActionScript Upload script, this will list the name of that script.
actionscript_scanned Boolean True if the ActionScript scan has been performed.
actionscript_scanned_at DateTime When the ActionScript was executed.
processed Boolean True when the attachment has completed all required Assembly, Checksum, Virus and ActionScript scanning.
processed_at DateTime When the Attachment completed all required processing.
available Boolean True if the file is available for download or not. Please note that this is user context sensitive. If the user is an Admin or if a file is required to be virus scanned and you have a setting in Admin → Configuration → Settings that Local Users can download files that are not virus scanned, then if the current user is a local user, this available will be true regardless if the virus_scan has completed or not. For external users or if Local Users are not permitted to download files that haven't been virus scanned, this will be false unless the virus scan has completed with no virus detected.
expires_at DateTime When the Attachment has been attached to at least one Message or FileLink, this is when the last Message or FileLink expires.
created_at DateTime When the Attachment was created.

Example Using curl

The Response has been formatted for readability (added indendation and linebreaks).

curl -X POST --user "ojubiigauS2TxTy4ovk6Ph:x" -H "Content-Type: application/json" --data-binary "@someimage.gif"

    "size_human":"44.3 KB"