LiquidFiles Documentation
LiquidFiles Documentation
On This Page

FileLink API

With the FileLink API, you can automate creating FileLinks from other applications using the API.

Create FileLink

Same as with the Filedrop and the standard messages based sending of files, you need to upload the files to the LiquidFiles server first and retrieve the attachment id before calling this File Request API, please see the Attachments API for instructions how to upload the files.

Request Info
Info Value
Request URL /link
Request VERB POST
Request Parameters
Parameter Type Description
attachment String The attachment ID of the uploaded file to create the FileLink for.
expires_at Date (Optional) The date when the FileLink will expire. Format: YYYY-MM-DD. Defaults to the number of days in the future as configured in the Groups config.
password String (Optional) Set a password before downloading of the FileLink.
download_receipt Boolean (Optional) Default: true. If set to false, the LiquidFiles system will not send download receipts when someone downloads a file using this FileLink.
require_authentication Boolean (Optional) If the FileLink requires authentication when downloading or not. The Default value is configured in the Users Group settings.

The http response codes are 200 OK if the File Request was successful, and 422 Unprocessable Entity if anything went wrong. In case of an error, there's also an error message with what went wrong.

Response Parameters
Parameter Type Description
id String The FileLink ID.
filename String The file name for the file attached to the FileLink.
size Integer The file size in bytes.
size_human String The file size in a human readable form (using KB, MB, GB, ...).
expires_at Date The date when the FileLink will expire. Format: YYYY-MM-DD.
send_download_confirmation Boolean If the LiquidFiles system will send download receipts when someone downloads a file using this FileLink or not.
require_authentication Boolean If the FileLink requires authentication when downloading or not.
url String The URL to this FileLink.
created_at DateTime When this FileLink was created.
updated_at DateTime When this FileLink was last updated.

Example Request in JSON

{"link":
  {
    "attachment":"fHbIuSIou38Txc0jVrobEp",
    "expires_at":"2017-01-01",
    "download_receipt":true,
    "require_authentication":true
  }
}

Example Response in JSON

{"link":
  {
    "id":"ZLa8RSQF2XDyrcVVMbrsNY",
    "filename":"screenshot.png",
    "send_download_confirmation":true,
    "require_authentication":true,
    "size":147874,
    "size_human":"144 KB",
    "expires_at":"2017-01-03",
    "url":"https://test.host/link/ZLa8RSQF2XDyrcVVMbrsNY",
    "created_at":"2016-12-19T21:56:08.719Z",
    "updated_at":"2016-12-19T21:56:08.719Z"
  }
}

Uploading Files

Uploading files to create a FileLink is very similar to the sending messages API, with the only change is the URL for the file upload. For detailed instructions how to to upload the file(s), please see the Attachments API.

Request Info
Info Value
Request URL /link/attachments/upload
Request VERB POST
Authentication Required
Headers
Info Value
username the Users API key
password not used (use 'x' if your programming API requires a value)
Content-Type (Optional) LiquidFiles first use the Content-Type HTTP header if that's set. If the Content-Type header is not set it will use this optional parameter. If neither are set, the Content-Type will be detected using the Linux `file` command.
Request Parameters
Parameter Type Description
filename String The filename of the uploaded file.
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).
Please note that with this binary upload, it's not possible to submit parameters using POST style embedded within the post. Instead, these parameters are submitted using GET style parameters following a question mark (?) on the URL.

Response

As a response to a successful File Upload you will receive an attachment response with the attributes outlined in the Attachment Attributes documentation.

Example: Create FileLink using bash and curl

#!/bin/bash

# Some nice variables
api_key="Y9fdTmZdv0THButt5ZONIY"
server="https://liquidfiles.example.com"

# Uploading the actual file and get attachment id for the file
attachment_id=`curl -X POST -H "Accept: application/json" --user "$api_key:x" --data-binary @bigfile.zip $server/link/attachments/upload | jq .attachment.id`

# Create the FileLink
cat <<EOF | curl -s -X POST --user "$api_key:x" -H "Accept: application/json" -H "Content-Type: application/json" -d @- $server/link
{"link":
  {"attachment":"$attachment_id"}
}
EOF

List FileLinks

You can list the available FileLinks using a GET request to /link like this:

Request Info
Info Value
Request URL /link
Request VERB GET
Request Parameters
Parameter Type Description
limit Integer (Optional) Limit the output of number of FileLinks to this value.

Response

The response will be a JSON Array with all available FileLinks.

Example: List FileLinks using bash and curl

#!/bin/bash

# Some nice variables
api_key="Y9fdTmZdv0THButt5ZONIY"
server="https://liquidfiles.example.com"

curl -X GET --user "$api_key:x" -H "Accept: application/json" -H "Content-Type: application/json" $server/link?limit=2

Example Response

{"links":
  [
    {
      "id":"pOIcoQ1NbJ8Lmp19hd9Vo3",
      "filename":"screenshot.png",
      "send_download_confirmation":true,
      "require_authentication":true,
      "size":147874,
      "size_human":"144 KB",
      "expires_at":"2017-01-03",
      "url":"https://test.host/link/pOIcoQ1NbJ8Lmp19hd9Vo3",
      "created_at":"2016-12-19T21:54:54.000Z",
      "updated_at":"2016-12-19T21:54:54.000Z"
    },
    {
      "id":"ZLa8RSQF2XDyrcVVMbrsNY",
      "filename":"another screenshot.png",
      "send_download_confirmation":true,
      "require_authentication":true,
      "size":147874,
      "size_human":"144 KB",
      "expires_at":"2017-01-03",
      "url":"https://lfapp.dev/link/ZLa8RSQF2XDyrcVVMbrsNY",
      "created_at":"2016-12-19T21:56:08.000Z",
      "updated_at":"2016-12-19T21:56:08.000Z"
    }
  ]
}

Deleting a FileLink

Request URL: /link/link_id
Request VERB: DELETE

Example Delete FileLink using bash and curl

#!/bin/bash

# Some nice variables
api_key="Y9fdTmZdv0THButt5ZONIY"
server="https://liquidfiles.example.com"

curl -X DELETE --user "$api_key:x" -H "Accept: application/json" -H "Content-Type: application/json" $server/link/tzMNVK0sbpXFFlld65s4Ly

Response Code

There are three possible response codes as a result of the request:

200: Success - The FileLink was deleted.
404: Not Found - The FileLink ID wasn't found.
422: Not Permitted - The Request wasn't permitted.

Updating Parameters

When you have added a FileLink and you want to change some parameters such expiration date, authentication and download notifications.

Updating Require Authentication

Request URL: /link/link_id/update_authentication
Request VERB: PUT
  Parameters:
    require_authentication:     # Boolean. True if users should be required to authenticate to download.

Example Update Require Authentication using bash and curl

#!/bin/bash

# Some nice variables
api_key="Y9fdTmZdv0THButt5ZONIY"
server="https://liquidfiles.example.com"

curl -X PUT --user "$api_key:x" -H "Accept: application/json" -H "Content-Type: application/json" -d '{"require_authentication":false}' $server/link/tzMNVK0sbpXFFlld65s4Ly/update_authentication

Response Code

There are three possible response codes as a result of the request:

200: Success - The request change was carried out successfully.
404: Not Found - The FileLink ID wasn't found.
422: Not Permitted - The Request wasn't permitted, i.e. the user is not allowed to change if the download should be authenticated or not.

Updating Download Notification

Request URL: /link/link_id/update_download_confirmation
Request VERB: PUT
  Parameters:
    send_download_confirmation:     # Boolean. True if download notificaions should be sent.

Example Update Download Notification using bash and curl

#!/bin/bash

# Some nice variables
api_key="Y9fdTmZdv0THButt5ZONIY"
server="https://liquidfiles.example.com"

curl -X PUT --user "$api_key:x" -H "Accept: application/json" -H "Content-Type: application/json" -d '{"send_download_confirmation":false}' $server/link/tzMNVK0sbpXFFlld65s4Ly/update_download_confirmation

Response Code

There are three possible response codes as a result of the request:

200: Success - The request change was carried out successfully.
404: Not Found - The FileLink ID wasn't found.
422: Not Permitted - The Request wasn't permitted.

Updating Expires At

Request URL: /link/link_id/update_expires_at
Request VERB: PUT
  Parameters:
    expires_at:     # Date. Expiration date in YYYY-MM-DD.

Example Update Expires At using bash and curl

#!/bin/bash

# Some nice variables
api_key="Y9fdTmZdv0THButt5ZONIY"
server="https://liquidfiles.example.com"

curl -X PUT --user "$api_key:x" -H "Accept: application/json" -H "Content-Type: application/json" -d '{"expires_at":"2015-04-18"}' $server/link/tzMNVK0sbpXFFlld65s4Ly/update_expires_at

Response Code

There are three possible response codes as a result of the request:

200: Success - The request change was carried out successfully.
404: Not Found - The FileLink ID wasn't found.
422: Not Permitted - The Request wasn't permitted.