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.

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.

Example Request in JSON

cat <<EOF | \
  curl -X POST -H "Authorization: Bearer Y9fdTmZdv0THButt5ZONIY" \
       -H "Accept: application/json" \
       -H "Content-Type: application/json" \
       -d @- https://liquidfiles.company.com/link
{"link":
  {
    "attachment":"fHbIuSIou38Txc0jVrobEp",
    "expires_at":"2017-01-01",
    "download_receipt":true,
    "require_authentication":true
  }
}
EOF

Example Response in JSON

{"link":
  {
    "id":"ZLa8RSQF2XDyrcVVMbrsNY",
    "filename":"screenshot.png",
    "send_download_confirmation":true,
    "require_authentication":true,
    "size":147874,
    "size_human":"144 KB",
    "file_count":2,
    "total_size":295748,
    "total_size_human":"289 KB",
    "filenames":["screenshot.png","diagram.png"],
    "attachments":[
      {
        "id":"fHbIuSIou38Txc0jVrobEp",
        "filename":"screenshot.png",
        "size":147874,
        "size_human":"144 KB",
        "content_type":"image/png",
        "caption":null
      },
      {
        "id":"a8RsQF2XDyrcVVMbrsNYZL",
        "filename":"diagram.png",
        "size":147874,
        "size_human":"144 KB",
        "content_type":"image/png",
        "caption":"System overview"
      }
    ],
    "expires_at":"2017-01-03",
    "url":"https://liquidfiles.company.com/link/ZLa8RSQF2XDyrcVVMbrsNY",
    "slug":null,
    "display_mode":"icons",
    "allow_download":true,
    "allow_direct_links":false,
    "recipient_limitations":[],
    "header_html":null,
    "footer_html":null,
    "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 upload the file(s), please see the Attachments API.

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 "Authorization: Bearer $api_key" \
  -H "Accept: application/json" \
  --data-binary @bigfile.zip $server/link/attachments/upload | \
  jq .attachment.id`

# Create the FileLink
cat <<EOF | curl -s -X POST -H "Authorization: Bearer $api_key" \
  -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:

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 -H "Authorization: Bearer $api_key" \
     -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

Example Delete FileLink using bash and curl

#!/bin/bash

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

curl -X DELETE -H "Authorization: Bearer $api_key" \
     -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:

Managing Files on a FileLink

A FileLink can hold multiple files (up to the group's filelink_max_files limit). You can add and remove files on a live FileLink without changing its URL or losing the download log. All of the endpoints below are owner-only and, when called with Accept: application/json, return the updated FileLink in the same shape as Create FileLink.

Add a File

First upload the file using the Upload File endpoint to obtain an attachment id, then attach it to the FileLink. Adding a file that is already attached is a no-op (no duplicate is created).

Example Add a File using bash and curl

#!/bin/bash

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

curl -X POST -H "Authorization: Bearer $api_key" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{"secure_id":"a8RsQF2XDyrcVVMbrsNYZL"}' \
     $server/link/tzMNVK0sbpXFFlld65s4Ly/attachments

Remove a File

Removes a file from the FileLink. If no other FileLink or message references the underlying file, the file itself is also deleted.

Example Remove a File using bash and curl

#!/bin/bash

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

curl -X DELETE -H "Authorization: Bearer $api_key" \
     -H "Accept: application/json" \
     $server/link/tzMNVK0sbpXFFlld65s4Ly/attachments/a8RsQF2XDyrcVVMbrsNYZL

Reorder Files

Sets the order of the files in the FileLink (the order they are presented in to recipients). Submit the complete list of attachment ids in the desired order.

Example Reorder Files using bash and curl

#!/bin/bash

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

curl -X POST -H "Authorization: Bearer $api_key" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{"ordered_secure_ids":["a8RsQF2XDyrcVVMbrsNYZL","fHbIuSIou38Txc0jVrobEp"]}' \
     $server/link/tzMNVK0sbpXFFlld65s4Ly/attachments/reorder

Set a File Caption

Sets (or clears, when blank) the caption shown beneath a file in the gallery and single-file views. The caption is stored per FileLink, so the same file can have different captions in different FileLinks.

Example Set a Caption using bash and curl

#!/bin/bash

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

curl -X PUT -H "Authorization: Bearer $api_key" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{"caption":"Front elevation, revision B"}' \
     $server/link/tzMNVK0sbpXFFlld65s4Ly/attachments/a8RsQF2XDyrcVVMbrsNYZL

Updating Parameters

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

Updating Require Authentication

Example Update Require Authentication using bash and curl

#!/bin/bash

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

curl -X PUT -H "Authorization: Bearer $api_key" \
     -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:

Updating Download Notification

Example Update Download Notification using bash and curl

#!/bin/bash

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

curl -X PUT -H "Authorization: Bearer $api_key" \
     -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:

Updating Expires At

Example Update Expires At using bash and curl

#!/bin/bash

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

curl -X PUT -H "Authorization: Bearer $api_key" \
     -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:

The endpoints below were added in v4.3. They all use the PUT verb against /link/link_id/<action> and share the same response codes: 200 on success, 404 if the FileLink id wasn't found, and 422 if the change wasn't permitted (typically because the user's group doesn't allow that capability, or the change conflicts with another setting — see Updating Direct Links). On success, a request with Accept: application/json returns the updated FileLink.

Updating Password

Sets or clears the password required before downloading. Requires the group permission filelink_can_use_password.

Example Update Password using bash and curl

curl -X PUT -H "Authorization: Bearer $api_key" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{"password":"correct horse battery staple"}' \
     $server/link/tzMNVK0sbpXFFlld65s4Ly/update_password

Updating Custom URL

Sets a memorable custom URL slug for the FileLink (e.g. /link/support_documents) instead of the default 22-character id. The original id-based URL continues to work. Submit a blank value to remove the custom URL. Requires the group permission filelink_can_change_url. If the group setting filelink_custom_url_prefix_email is on, the slug is automatically prefixed with the owner's email user-part. A 422 is returned if the slug is already in use, reserved, or otherwise invalid.

Example Update Custom URL using bash and curl

curl -X PUT -H "Authorization: Bearer $api_key" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{"slug_input":"support_documents"}' \
     $server/link/tzMNVK0sbpXFFlld65s4Ly/update_slug

Updating Display Mode

Sets how the files are presented on the FileLink page. Requires the matching group permission for the chosen mode. gallery additionally requires the FileLink to contain at least one image or video.

Example Update Display Mode using bash and curl

curl -X PUT -H "Authorization: Bearer $api_key" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{"display_mode":"gallery"}' \
     $server/link/tzMNVK0sbpXFFlld65s4Ly/update_display_mode

Enabling / Disabling Downloads

Controls whether recipients can download the files (allow_download = true) or can only view them in the browser (allow_download = false, "view-only" mode). Requires the group permission filelink_can_disable_downloads. Disabling downloads is not compatible with direct links being enabled — see Updating Direct Links.

Example Disable Downloads using bash and curl

curl -X PUT -H "Authorization: Bearer $api_key" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{"allow_download":false}' \
     $server/link/tzMNVK0sbpXFFlld65s4Ly/update_allow_download

Updating Direct Links

Enables or disables direct (hot-link) URLs, which let a file's bytes be embedded directly on a third-party page (e.g. in an <img> or <video> tag). Requires the group permission filelink_can_use_direct_links. Because direct links bypass the FileLink page, they cannot be enabled while the FileLink requires authentication, has a password, or has downloads disabled — attempting to do so returns 422 with an explanation. Turning direct links off is always allowed.

Example Enable Direct Links using bash and curl

curl -X PUT -H "Authorization: Bearer $api_key" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{"allow_direct_links":true}' \
     $server/link/tzMNVK0sbpXFFlld65s4Ly/update_direct_links

When direct links are enabled, each file's direct URL has the form /link/link_id/raw/filename.

Recipient Limitations

Sets an allowlist of email addresses and/or bare domains that may pass the authentication gate. Only enforced when the FileLink has require_authentication on. Requires the same group permission as authentication (filelink_can_change_require_authentication). Submit a blank value to clear the list.

Example Set Recipient Limitations using bash and curl

curl -X PUT -H "Authorization: Bearer $api_key" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{"recipient_limitations":"jane@example.com, partner.com"}' \
     $server/link/tzMNVK0sbpXFFlld65s4Ly/update_recipient_limitations

Updating Header / Footer

Sets the custom HTML header (shown above the file list) and footer (shown below it) on the FileLink page. Requires the group permission filelink_can_customise_header_footer. The HTML is rendered through Liquid and then sanitised, and may use FileLink variables such as , and . Submit a blank value to clear the header or footer.

Example Update Header using bash and curl

curl -X PUT -H "Authorization: Bearer $api_key" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{"header_html":"<h2>Documents for </h2>"}' \
     $server/link/tzMNVK0sbpXFFlld65s4Ly/update_header