LiquidFiles Documentation
LiquidFiles Documentation


The LiquidFiles API is a REST based API that uses JSON to interact with it.

With the API, you can send and receive files from other resources and since it's based on current web standards, you can use pretty much any language or any platform, as long as you can make standardised web calls.

Throughout the API documentation, we refer a lot to examples using curl which is a cross platform tool that is easy to add parameters with to test responses from the system. Curl is available on most platforms including Windows at

Content-Type and Accept Headers

If you look at a typical API request, you will see two headers, Content-Type and Accept:

curl -X POST --user gXvoqaFzd1jYQ9f13sPO06:x \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{"user": {"email": ""}}' \
  • The Accept header tells what you format I want to receive the response in.
  • The Content-Type header tells what format you are sending the request data in. In the example above, that's {"user": {"email": ""}} which is data in JSON format so the Content-Type is set to application/json.

The only supported value for Accept is application/json when using the API. The typical value for Content-Type is also application/json but lets say you're uploading a file "image.gif" then the Content-Type (what you're sending) would be image/gif where's the Accept (how you want this to be processed, or how you want the response) would be application/json.

curl -X POST --user gXvoqaFzd1jYQ9f13sPO06:x \
     -H "Accept: application/json" \
     -H "Content-Type: image/gif" \
     --data-binary @image.gif \

As a side note, when the browser is sending the Accept header set to text/html, this is how LiquidFiles knows to treat the request as a browser HTML session instead of an API session. Accept text/html is also the default in many tools so if you don't set Accept to application/json specifically, it will likely default to text/html and you'll receive a HTML page as a response.

You don't need to set the Content-Type header when you're not sending any data. For instance the following API call:

curl -X GET --user gXvoqaFzd1jYQ9f13sPO06:x \
     -H "Accept: application/json" \

-X GET in the example above is not necessary because curl will default to GET if no method is set. And you can see that in this case we're not sending any data so no need for a Content-Type header, only the Accept header is needed to tell LiquidFiles this is a JSON API request.

Deprecation Warning

LiquidFiles up to v3.6 treated requests with Content-Type set to application/json with no Accept header as an API request. From LiquidFiles v3.7 onwards requires the Accept header to be set to application/json for the request to be processed as an API request.

HTTP Verbs

Going back a few years, the entire web used only either GET requests or POST requests and seeing other request types was seen as a potential security problem. With modern REST based standards, this has changed and we now frequently utilise more of the available http verbs at our disposal. These would include:

GET List or view data. An example would be to list all available messages.
POST Create a user, group or other object, or to send data. You will use this when sending messages.
DELETE To delete an uploaded file, delete a user, group or other data.
PUT/PATCH To change a value of an already created object, like changing the download authorization setting of an existing FileLink.

Response Status Codes

The LiquidFiles appliance will respond with a http status code. The most common status codes would include:

200 Everything went fine (user found, file uploaded ok, message sent successfully)
401 Unauthorized, API key or User authentication failed
422 Something went wrong and the request could not be completed (Email and/or password incorrect, invalid file, invalid message)
500 Something went very wrong. This could happen if the system is expecting a value between 0-100 and you send a 1Mb picture of a cat, and similar situations.