Documentation & Reference Center

mobile menu

REST API

Our REST API is meant for people who require the highest level of integration between Brick and their own application, website, or database.

The REST API uses plain JSON or XML over HTTP. Resources (such as Users or Groups) are manipulated individually using the 4 HTTP verbs: GET, POST, PUT, and DELETE.

https://app.brickftp.com/api/rest/v1 is the base URL for all API requests. Do not use a custom subdomain or domain name, even if one is configured for your account. Also, be sure that you are connecting via https://. Two extensions – .json and .xml are supported as extensions to be appended to the request endpoint for the purpose of determining the response type. So a request ending in .json will send back application/json and .xml will return application/xml.

Authentication

BrickFTP allows you to connect to the REST API via 2 different methods, outlined below.

Method 1: API Key

To use the REST API with the REST API Key, you first need to enable the REST API on the Configuration section. Once you’ve enabled the REST API, BrickFTP will show you your REST API key at that time. Make sure you keep this key secure, as it allows full access to your account. This API Key must be provided in every API request. If you ever feel that your API Key may be compromised, please contact us immediately to disable it!

The REST API uses HTTP Basic Authentication to collect the API Key. You should pass in the API Key as the Username field in HTTP Basic Authentication. The password field may be left blank, or you may use a dummy value, such as x.

Here’s an example of authenticating the the API using cURL, assuming EB4585AD9FE0426781ED7C49252F8225 is your API key:

curl -u EB4585AD9FE0426781ED7C49252F8225:x https://app.brickftp.com/api/rest/v1/users.json

Currently BrickFTP only supports a single REST API key per account, however, we plan to expand this capability in the future to support multiple REST API keys with different permission levels.

Method 2: User Sessions

You can also authenticate to the REST API by creating a user session using the username and password of an active user. If the user is a Site Admin, the session will have full access to the entire API. Sessions created from regular user accounts will only be able to access files that user can access, and no access will be granted to site administration functions in the API.

To create a session, a POST request is made to https://app.brickftp.com/api/rest/v1/sessions with the user’s username and password as per this example:

Logging In

POST /sessions.(json|xml)

Sample Request Body

{
  "username": "motor",
  "password": "vroom"
}
<session>
  <username>motor</username>
  <password>vroom</password>
</session>

Sample Response

200 Success

{
  "id": "8c2e9f493dd8a857d5cdddbb7bf64ece0b7fb599"
}
<?xml version="1.0" encoding="UTF-8"?>
<session>
  <id>8c2e9f493dd8a857d5cdddbb7bf64ece0b7fb599</id>
</session>

The id field in the response is the session ID that must be provided to subsequent requests in order to use this session.

Using a Session To Authenticate Requests

Once a session has been created, you authenticate to the REST API by sending a cookie called BrickAPI set to the value of the session ID. Here is an example using curl:

curl -b BrickAPI=8c2e9f493dd8a857d5cdddbb7bf64ece0b7fb599 https://app.brickftp.com/api/rest/v1/users.json

Logging Out

User sessions can be ended by using a DELETE call to https://app.brickftp.com/api/rest/v1/sessions. If a valid user session is passed in by cookie, then that user session will be deleted, which is similar to the user logging out. Note that calling DELETE at this endpoint will always result in a response of an empty array, even if an invalid user session was passed in.

Sample Response

[]
<?xml version="1.0" encoding="UTF-8"?>
<nil-classes type="array"/>

Users

The Users resource in the REST API allows you to operate on users. This resource supports listing, creating, showing, updating, and deleting users.

Index

This endpoint lists all users on the current site.

GET /users.(json|xml)

No request body necessary.

Sample Response

200 Success

[
  {
    "id": 2,
    "username": "stork",
    "name": "John",
    "email": "",
    "notes": "",
    "group_ids": "2",
    "ftp_permission": true,
    "web_permission": true,
    "attachments_permission": true,
    "self_managed": true,
    "require_password_change": false,
    "allowed_ips": "",
    "user_root": "API"
  },
  {
    "id": 3,
    "username": "zaphod",
    "name": "Zaphod Beeblebrox",
    "email": "towel@example.com",
    "notes": "",
    "group_ids": "1",
    "ftp_permission": true,
    "web_permission": true,
    "attachments_permission": true,
    "self_managed": true,
    "require_password_change": false,
    "allowed_ips": "",
    "user_root": "Zaphod"
  }
]
<?xml version="1.0" encoding="UTF-8"?>
<users type="array">
  <user>
    <id type="integer">2</id>
    <username>stork</username>
    <name>John</name>
    <email></email>
    <notes></notes>
    <group_ids></group_ids>
    <ftp_permission type="boolean">true</ftp_permission>
    <web_permission type="boolean">true</web_permission>
    <attachments_permission type="boolean">true</attachments_permission>
    <self_managed type="boolean">true</self_managed>
    <require_password_change type="boolean">false</require_password_change>
    <allowed_ips></allowed_ips>
    <user_root>API</user_root>
  </user>
  <user>
    <id type="integer">3</id>
    <username>zaphod</username>
    <name>Zaphod Beeblebrox</name>
    <email>towel@example.com</email>
    <notes></notes>
    <group_ids></group_ids>
    <ftp_permission type="boolean">true</ftp_permission>
    <web_permission type="boolean">true</web_permission>
    <attachments_permission type="boolean">true</attachments_permission>
    <self_managed type="boolean">true</self_managed>
    <require_password_change type="boolean">false</require_password_change>
    <allowed_ips></allowed_ips>
    <user_root>Zaphod</user_root>
  </user>
</users>

Show

This endpoint shows a single user.

GET /users/:id.(json|xml)

No request body necessary.

Sample Response

200 Success

{
  "id": 2,
  "username": "stork",
  "name": "John",
  "email": "",
  "notes": "",
  "group_ids": "2",
  "ftp_permission": true,
  "web_permission": true,
  "attachments_permission": true,
  "self_managed": true,
  "require_password_change": false,
  "allowed_ips": "",
  "user_root": "API"
}
<?xml version="1.0" encoding="UTF-8"?>
<user>
  <id type="integer">2</id>
  <username>stork</username>
  <name>John</name>
  <email></email>
  <notes></notes>
  <group_ids></group_ids>
  <ftp_permission type="boolean">true</ftp_permission>
  <web_permission type="boolean">true</web_permission>
  <attachments_permission type="boolean">true</attachments_permission>
  <self_managed type="boolean">true</self_managed>
  <require_password_change type="boolean">false</require_password_change>
  <allowed_ips></allowed_ips>
  <user_root>API</user_root>
</user>

Create

This endpoint creates a new user on the current site.

POST /users.(json|xml)

Sample Request Body

{
  "username": "johndoe",
  "password": "doejohn123",
  "name": "John Doe",
  "email": "john@example.com",
  "notes": "CTO",
  "group_ids": "3,4",
  "ftp_permission": true,
  "web_permission": true,
  "attachments_permission": false,
  "self_managed": true,
  "require_password_change": false,
  "grant_permission": "read"
}
<user>
  <username>johndoe</username>
  <password>doejohn123</password>
  <name>John Doe</name>
  <email>john@example.com</email>
  <notes>CTO</notes>
  <group_ids>3,4</group_ids>
  <ftp_permission>true</ftp_permission>
  <web_permission>true</web_permission>
  <attachments_permission>false</attachments_permission>
  <self_managed>true</self_managed>
  <require_password_change>false</require_password_change>
  <allowed_ips></allowed_ips>
  <user_root></user_root>
  <grant_permission>read</grant_permission>
</user>

Sample Response

201 Created

Same as the Show endpoint.

Update

This method updates an existing user.

PUT /users/:id.(json|xml)

Sample Request Body

{
  "password": "new_password",
  "require_password_change": true
}
<user>
  <password>new_password</password>
  <require_password_change>true</require_password_change>
</user>

Sample Response

200 Success

Same as the Show endpoint.

Delete

This endpoint deletes a user.

DELETE /users/:id.(json|xml)

No request body necessary.

Sample Response

200 Success

[]
<?xml version="1.0" encoding="UTF-8"?>
<nil-classes type="array"/>

Property Reference

The following properties are used in the request and response bodies for the User resource.

id integer Globally unique identifier of each User. Each user is given an ID automatically upon creation.
username string (50) Username for the user. This is how the user will be displayed on the site.
password string Password for the user. This property is write-only. It cannot be retrieved via the API.
name string (50) Real name of the user. For your reference.
email string (50) E-Mail address of the user.
notes text You may use this property to store any additional information you require. There are no restrictions on its formatting.
group_ids comma separated integers IDs of the Groups that this user is in.
ftp_permission boolean (default: true) Allow user access via FTP/FTPS (port 21 or 990) interface.
web_permission boolean (default: true) Allow user access via HTTP/HTTPS (port 80 or 443) interface.
attachments_permission boolean (default: false) Allow user to use Sharing tab in web interface to share files with anonymous users via a unique URL.
self_managed boolean (default: true) Allow user to change their password and user information via the web interface.
require_password_change boolean (default: false) Require user to change their password at their next login. Note: requires web_permission to be true, as password changes can only occur via the web interface.
allowed_ips text List allowed IPs, one per line. You may specify a range in CIDR format, such as 192.168.1.0/27. Leave blank to allow all IPs. If you are also restricting IP addresses on the Site tab, users matching in either place will be allowed to log in.
user_root string (250) Folder to show as the root when this user logs in via the FTP interface. Make sure this folder exists, as it will not be automatically created. Does not apply to the web interface! This should not contain a leading slash, but must contain a trailing slash. Example: Users/jenny/
grant_permission enum Value must be set to full, read, write, preview, read+write, or preview+write. The user will be granted that permission on their FTP root folder as defined by the user_root. This property is write-only. It cannot be retrieved via the User resource of the REST API, though may be obtained with the Permission resource of the REST API described below.

Groups

The Groups resource in the REST API allows you to operate on groups. This resource supports listing, creating, showing, updating, and deleting groups.

Index

This endpoint lists all groups on the current site.

GET /groups.(json|xml)

No request body necessary.

Sample Response

200 Success

[
  {
    "id": 3,
    "name": "HR",
    "notes": "Has access to HR folders only",
    "user_ids": ""
  },
  {
    "id": 1,
    "name": "Management",
    "notes": "Has access to all areas: Ops, HR, and Board",
    "user_ids": "3"
  },
  {
    "id": 2,
    "name": "Operations",
    "notes": "Has access to Ops folders only",
    "user_ids": "2,9"
  }
]
<?xml version="1.0" encoding="UTF-8"?>
<groups type="array">
  <group>
    <id type="integer">3</id>
    <name>HR</name>
    <notes>Has access to HR folders only</notes>
    <user_ids>9</user_ids>
  </group>
  <group>
    <id type="integer">1</id>
    <name>Management</name>
    <notes>Has access to all areas: Ops, HR, and Board</notes>
    <user_ids>3</user_ids>
  </group>
  <group>
    <id type="integer">2</id>
    <name>Operations</name>
    <notes>Has access to Ops folders only</notes>
    <user_ids>2,9</user_ids>
  </group>
</groups>

Show

This endpoint shows a single group.

GET /groups/:id.(json|xml)

No request body necessary.

Sample Response

200 Success

{
  "id": 2,
  "name": "Operations",
  "notes": "Has access to Ops folders only",
  "user_ids": "2,10"
}
<?xml version="1.0" encoding="UTF-8"?>
<group>
  <id type="integer">2</id>
  <name>Operations</name>
  <notes>Has access to Ops folders only</notes>
  <user_ids>2,9</user_ids>
</group>

Create

This endpoint creates a new group on the current site.

POST /groups.(json|xml)

Sample Request Body

{
  "name": "Chicago Office",
  "notes": "For members of our Chicago Office",
  "user_ids": "3,7,9"
}
<group>
  <name>Chicago Office</name>
  <notes>For members of our Chicago Office</notes>
  <user_ids>3,7,9</user_ids>
</group>

Sample Response

201 Created

Same as Show endpoint.

Update

This method updates an existing group.

PUT /groups/:id.(json|xml)

Sample Request Body

{
  "notes": "Submitting this will change this note, but not the name or group membership."
}
<group>
  <notes>Submitting this will change this note, but not the name or group membership.</notes>
</group>

Sample Response

200 Success

Same as Show endpoint.

Delete

This endpoint deletes a group.

DELETE /groups/:id.(json|xml)

No request body necessary.

Sample Response

200 Success

[]
<?xml version="1.0" encoding="UTF-8"?>
<nil-classes type="array"/>

Property Reference

The following properties are used in the request and response bodies for the Group resource.

id integer Globally unique identifier of each Group. Each group is given an ID automatically upon creation.
name string (50) Name of the Group. This is how the group will be displayed on the site.
notes text You may use this property to store any additional information you require. There are no restrictions on its formatting.
user_ids comma separated integers IDs of the Users that are in this group.

Permissions

The Permissions resource in the REST API allows you to operate on Permissions. A Permission is a single authorization for a single User or Group to access a single Folder at a specific access level. This resource supports listing, creating, and deleting permissions.

Index

This endpoint shows all Permissions on the current Site.

GET /permissions.(json|xml)

No request body necessary.

Sample Response

200 Success

[
  {
    "id": 2,
    "path": "a/b/c",
    "permission": "writeonly",
    "group_id": null,
    "user_id": 5
  },
  {
    "id": 3,
    "path": "a/b",
    "permission": "readonly",
    "group_id": 2,
    "user_id": null
  }
]
<?xml version="1.0" encoding="UTF-8"?>
<permissions type="array">
  <permission>
    <id type="integer">2</id>
    <path>a/b/c</path>
    <permission type="symbol">writeonly</permission>
    <group_id nil="true" />
    <user_id type="integer">5</user_id>
  </permission>
  <permission>
    <id type="integer">3</id>
    <path>a/b</path>
    <permission type="symbol">readonly</permission>
    <group_id type="integer">2</group_id>
    <user_id nil="true" />
  </permission>
</permissions>

Create

This endpoint creates a new Permission record.

POST /permissions.(json|xml)

Sample Request Body

{
  "path": "a/b/c/d",
  "permission": "writeonly",
  "user_id": "10",
}
<permission>
  <path>a/b/c/d</path>
  <permission>writeonly</permission>
  <user_id>10</user_id>
</permission>

Sample Response

201 Created

{
  "id": 3,
  "path": "a/b/c/d",
  "permission": "writeonly",
  "group_id": null,
  "user_id": 10
}
<?xml version="1.0" encoding="UTF-8"?>
<permission>
  <id type="integer">3</id>
  <path>a/b/c/d</path>
  <permission type="symbol">writeonly</permission>
  <group_id nil="true" />
  <user_id type="integer">10</user_id>
</permission>

Delete

This endpoint deletes a permission record.

DELETE /permissions/:id.(json|xml)

No request body necessary.

Sample Response

200 Success

[]
<?xml version="1.0" encoding="UTF-8"?>
<nil-classes type="array"/>

Property Reference

The following properties are used in the request and response bodies for the Permission resource.

id integer Globally unique identifier of each Permission. Each permission is given an ID automatically upon creation.
path string (5000) Folder path for the permission to apply to. This must be slash-delimited, but it must neither start nor end with a slash.
permission enum Value must be set to full, readonly, writeonly, or previewonly, depending on the type of access to be granted by the Permission.
user_id integer Unique identifier for the user being granted a permission. Each user is given an ID automatically upon creation. The user_id and group_id fields cannot both be set.
username string (50) Username for the user, if user_id is set. If this value is set during creation and user_id is not set, the user_id is looked up from the username and set.
group_id integer Unique identifier for the group being granted a permission. Each group is given an ID automatically upon creation. The user_id and group_id fields cannot both be set.

Notifications

The Notifications resource in the REST API allows you to operate on Notifications. A Notification is a record that attaches a User to a specific folder path and causes that user to receive email notifications when files are created or updated in that path or any subpath of that path. This resource supports listing, creating, and deleting notifications.

Index

This endpoint shows all Notifications on the current Site.

GET /notifications.(json|xml)

Sample Response

200 Success

[
  {
    "id": 2,
    "path": "a/b/c",
    "username": "stork",
    "user_id": 5
  },
  {
    "id": 3,
    "path": "a/b",
    "username": "zaphod",
    "user_id": 6
  }
]
<?xml version="1.0" encoding="UTF-8"?>
<notifications type="array">
  <notification>
    <id type="integer">2</id>
    <path>a/b/c</path>
    <username>stork</username>
    <user_id type="integer">5</user_id>
  </notification>
  <notification>
    <id type="integer">3</id>
    <path>a/b</path>
    <username>zaphod</username>
    <user_id type="integer">6</user_id>
  </notification>
</notifications>

Create

The create endpoint creates a notification record.

POST /notifications.(json|xml)

Sample Request Body

{
  "path": "a/b/c/d",
  "user_id": "10",
}
<notification>
  <path>johndoe</path>
  <user_id>10</user_id>
</notification>

Sample Response

201 Created

{
  "id": "7",
  "path": "a/b/c/d",
  "user_id": "10",
  "username": "fred"
}
<notification>
  <id type="integer">7</id>
  <path>johndoe</path>
  <user_id>10</user_id>
  <username>fred</username>
</notification>

Delete

The delete endpoint deletes a notification record.

DELETE /notifications/:id.(json|xml)

No request body necessary.

Sample Response

200 Success

[]
<?xml version="1.0" encoding="UTF-8"?>
<nil-classes type="array"/>

Property Reference

The following properties are used in the request and response bodies for the Notification resource.

id integer Globally unique identifier of each Nofification. Each notification is given an ID automatically upon creation.
path string (5000) Folde path for notifications. TThis must be slash-delimited, but it must neither start nor end with a slash.
user_id integer Unique identifier for the user being notified. Each user is given an ID automatically upon creation. You can look up usser IDs by using the User resource of this REST API.
username string (50) Username for the user given by user_id. If this value is set during creation and user_id is not set, the user_id is looked up from the username and set.

File and Folder Operations

The File and Folder resources in the REST API allow you to operate on files and folders. While the two resources are similar, they are not exactly same same, so pay close attention to the documentation to ensure that you are operating on the correct REST Resource for the operation you are trying to perform.

Specifying File Path Names

When accessing the File and Folder resources in the REST API (URLs in the REST API with endpoints that begin with /files or /folders), the remainer of the URL specifies the path to a file or folder being operated on. Operations on those endpoints in particular, without a file name, specify the operation applies to the Root Folder of your site.

For example, to retrieve a file called Hello.txt, a GET request would be sent to /files/Hello.txt.

If special characters exist in the path name, encode them in UTF-8 first and then URL encode the bytes. For example, to list the contents of a folder with a complete path of Engineering Candidates/Résumés, a GET request would be sent to /folders/Engineering%20Candidates/R%c3%a9sum%c3%a9s.

Request and Response Format

The BrickFTP REST API supports both JSON and XML for both request data and response data. The REST API does not assume the request and response formats are the same, and determines each independently to allow them to be different. On all requests, the request data format is determined from the Content-Type header in the request.

For the response, the REST API normally looks at the file extension (.json or .xml) or the Accept header in the request. However, for requests sent to the /files and /folders interfaces, any file extension is assumed to be part of the file name being operated on and does not affect the response format. Therefore, when using this part of the REST API, please send an Accept header to set the response format. Currently, the default format is JSON if no Accept header is sent, but is subject to change, and therefore sending the Accept header with a value of application/json is recommended.

Folders: Index

The index endpoint lists the contents of the folder provided in the URL. Remember that a blank URL refers to the root folder. So for example, you can list the contents of the root folder using the REST API by sending a GET request to /folders. Another folder can be listed by inserting its complete path in that URL after /folders, for example: /folders/employee/engineering.

There is a maximum number of entries in the folder that will be listed with a single request (default 1000 or whatever value you provide as the per_page parameter). So if exactly that many entries are returned you will need to increment the value of the page parameter in subsequent queries to continue listing the folder.

GET /folders/:path

Request URL Parameters

You may provide any of the following parameters via the query string to modify the processing of the index request.

page integer Page number of items to return in this request.
per_page integer Requested number of items returned per request. Maximum: 5000, leave blank for default (strongly recommended).
search string Only return items matching the given search text.
sort_by[path] enum Sort by file name, and value is either asc or desc to indicate normal or reverse sort. (Note that sort_by[path] = asc is the default.)
sort_by[size] enum Sort by file size, and value is either asc or desc to indicate smaller files first or larger files first, respectively.
sort_by[modified_at_datetime] enum Sort by modification time, and value is either asc or desc to indicate older files first or newer files first, respectively.

Note that these parameters are to be provided in the query string. No request body parameters are accepted.

Sample Response

200 Success

[
  {
    "path": "Engineering Candidates/R\u00e9sum\u00e9s/Needs Review",
    "type": "directory",
    "size": null,
    "mtime": "2014-05-15T20:26:18+00:00",
    "crc32": null,
    "md5": null
  },
  {
    "path": "Engineering Candidates/R\u00e9sum\u00e9s/John Smith.docx",
    "type": "file",
    "size": 61440,
    "mtime": "2014-05-15T18:34:51+00:00",
    "crc32": "f341cc60",
    "md5": "b67236f5bcd29d1307d574fb9fe585b5"
  },
  {
    "path": "Engineering Candidates/R\u00e9sum\u00e9s/Mary Jones.pdf",
    "type": "file",
    "size": 19946,
    "mtime": "2014-05-15T18:36:03+00:00",
    "crc32": "a720a234",
    "md5": "02c442ecc0d499bf443fa8fd444c2933"
  }
]
<?xml version="1.0" encoding="UTF-8"?>
<files type="array">
  <file>
    <path>Engineering Candidates/Résumés/Needs Review</path>
    <type>directory</type>
    <size nil="true"/>
    <mtime type="datetime">2014-05-15T20:26:18+00:00</mtime>
    <crc32 nil="true"/>
    <md5 nil="true"/>
  </file>
  <file>
    <path>Engineering Candidates/Résumés/John Smith.docx</path>
    <type>file</type>
    <size type="integer">61440</size>
    <mtime type="datetime">2014-05-15T18:34:51+00:00</mtime>
    <crc32>f341cc60</crc32>
    <md5>b67236f5bcd29d1307d574fb9fe585b5</md5>
  </file>
  <file>
    <path>Engineering Candidates/Résumés/Mary Jones.pdf</path>
    <type>file</type>
    <size type="integer">19946</size>
    <mtime type="datetime">2014-05-15T18:36:03+00:00</mtime>
    <crc32>a720a234</crc32>
    <md5>02c442ecc0d499bf443fa8fd444c2933</md5>
  </file>
</files>

Folders: Create

The create endpoint creates a folder.

POST /folders/:path_and_folder_name

No request body or query string parameters necessary.

Sample Response

201 Created

[]
<?xml version="1.0" encoding="UTF-8"?>
<nil-classes type="array"/>

Folders: Delete, Move, Rename, Copy

The Folders resource does not provide endpoints for delete, move, rename or copy. However, you can find endpoints for these actions on the Files resource (described below) and it is perfectly okay to perform these operations on folders and files through that resource.

Files: Download

This endpoint provides a download URL that will enable you to download a file. The download URL is a direct URL to Amazon S3 that has been signed by BrickFTP to provide temporary access to the file. The download links is valid for 3 minutes.

By default this request assumes that the file will be downloaded, and therefore a download action is logged for the user that is logged into the REST API session. If downloading the file is not desired, but rather one is just looking at the information associated with the file such as the MD5 checksum or file size, then the action query parameter can be passed in on the URL with the value of stat. This causes the download_url field to be omitted in the response and no download action to be logged.

GET /files/:path_and_filename

No request body necessary. Optional query string parameter action=stat.

Sample Response

200 Success

{
  "path": "Engineering Candidates/John Smith.docx",
  "type": "file",
  "size": 61440,
  "mtime": "2014-05-15T18:34:51+00:00",
  "crc32": "f341cc60",
  "md5": "b67236f5bcd29d1307d574fb9fe585b5",
  "download_uri": "https://s3.amazonaws.com/objects.brickftp.com/metadata/1/84c6ecd0-be8d-0131-dd53-12b5580f0798?AWSAccessKeyId=AKIAIEWLY3MN4YGZQOWA&Signature=8GtrTVcKyPXrchpieNII%2Fo8DzMU%3D&Expires=1400217125&response-content-disposition=attachment;%20filename=%22John%20Smith.docx%22"
}
<?xml version="1.0" encoding="UTF-8"?>
<file>
  <path>Engineering Candidates/John Smith.docx</path>
  <type>file</type>
  <size type="integer">61440</size>
  <mtime type="datetime">2014-05-15T18:34:51+00:00</mtime>
  <crc32>f341cc60</crc32>
  <md5>b67236f5bcd29d1307d574fb9fe585b5</md5>
  <download_uri>https://s3.amazonaws.com/objects.brickftp.com/metadata/1/84c6ecd0-be8d-0131-dd53-12b5580f0798?AWSAccessKeyId=AKIAIEWLY3MN4YGZQOWA&amp;Signature=8GtrTVcKyPXrchpieNII%2Fo8DzMU%3D&amp;Expires=1400217125&amp;response-content-disposition=attachment;%20filename=%22John%20Smith.docx%22</download_uri>
</file>

Files: Upload

The File resource supports uploading files, however in order to support huge files (up to 5TB), the procedure requires multiple steps. See the next section in this guide for full documentation.

Files: Move/Rename

This endpoint moves or renames a file or folder to the destination provided in the move-destination parameter in the request body.

POST /files/:source_path_and_filename

Sample Request

{
  "move-destination": "/DESTINATION_PATH_AND_FILENAME.EXT",
}
<file>
  <move-destination>/DESTINATION_PATH_AND_FILENAME.EXT</move-destination>
</file>

Sample Response

200 Success

[]
<?xml version="1.0" encoding="UTF-8"?>
<nil-classes type="array"/>

Files: Copy

This endpoint copies a file or folder to the destination provided in the copy-destination parameter in the request body.

POST /files/:source_path_and_filename

Sample Request Body

{
  "copy-destination": "/DESTINATION_PATH_AND_FILENAME.EXT",
}
<file>
  <copy-destination>/DESTINATION_PATH_AND_FILENAME.EXT</copy-destination>
</file>

Sample Response

200 Success

[]
<?xml version="1.0" encoding="UTF-8"?>
<nil-classes type="array"/>

Files: Delete

This endpoint deletes a file or folder.

Note that this operation works for both files and folders, but normally it will only work on empty folders. If you want to recursively delete a folder and all its contents, send the request with a Depth header with the value set to infinity.

DELETE /files/:path_or_filename

Sample Response

200 Success

[]
<?xml version="1.0" encoding="UTF-8"?>
<nil-classes type="array"/>

Property Reference

The following properties are used in the request and response bodies for the File and Folder resources.

path string(550) Full path of the file or folder.
type enum Either file or directory (meaning folder)
size integer Size of the file in bytes. Will be 0 for a folder.
mtime datetime Date of the file/folder’s last modification.
crc32 string CRC32 for the file, if available.
md5 string MD5 hash for the file, if available.
download_uri string URL to download the file, if requested.

File Uploading

In order to support huge files (up to 5TB), the procedure to upload files requires multiple steps. We will explain the procedure here.

Overview of Uploading

Uploading files using the REST API is done in 3 stages.

  1. Send a request to REST API to indicate intent to upload a file.
  2. Upload file to Amazon S3 to URL(s) given by REST API, possibly in parts via multiple uploads.
  3. Notify the REST API that the file upload is complete.

Starting a New Upload

The first request to upload a new file is a POST request to /files/PATH_AND_FILENAME.EXT with an action parameter with the value of put.

POST /files/:path_and_filename

Sample Request Body

{
  "action": "put"
}
<file>
  <action>put</action>
</file>

Sample Response

200 Success

{
  "ref": "put-378670",
  "path": "NewFile.txt",
  "action": "put/write",
  "ask_about_overwrites": false,
  "http_method": "PUT",
  "upload_uri": "https://s3.amazonaws.com/objects.brickftp.com/metadata/1/6eee7ad0-bf75-0131-71fc-0eeabbd7a8b4?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIEWLY3MN4YGZQOWA%2F20140516%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20140516T221456Z&X-Amz-Expires=180&X-Amz-SignedHeaders=host&partNumber=1&uploadId=xQDI8q.aDdWdWIvSpRGLOFqnPQqJoMGZ88r9g_q7z2gW6U4rNZx8Zb_Wh9m07TDJM1x4rCTM18UCzdXaYjJu.SBH89LAiA4ye698TfMPyam4BO7ifs7HLuiBPrEW.zIz&X-Amz-Signature=69bc7be37c8c42096e78aa4ff752f073ea890481c5f76eac5ad40a5ab9466997",
  "partsize":5242880,
  "part_number":1,
  "available_parts":10000,
  "send": {
    "partsize": "required-parameter Content-Length",
    "partdata": "body"
  },
  "headers": {},
  "parameters": {}
}
<?xml version="1.0" encoding="UTF-8"?>
<upload>
  <ref>put-378670</ref>
  <path>NewFile.txt</path>
  <action>put/write</action>
  <ask_about_overwrites type="boolean">false</ask_about_overwrites>
  <http_method>PUT</http_method>
  <upload_uri>https://s3.amazonaws.com/objects.brickftp.com/metadata/1/6eee7ad0-bf75-0131-71fc-0eeabbd7a8b4?X-Amz-Algorithm=AWS4-HMAC-SHA256&amp;X-Amz-Credential=AKIAIEWLY3MN4YGZQOWA%2F20140516%2Fus-east-1%2Fs3%2Faws4_request&amp;X-Amz-Date=20140516T221456Z&amp;X-Amz-Expires=180&amp;X-Amz-SignedHeaders=host&amp;partNumber=1&amp;uploadId=xQDI8q.aDdWdWIvSpRGLOFqnPQqJoMGZ88r9g_q7z2gW6U4rNZx8Zb_Wh9m07TDJM1x4rCTM18UCzdXaYjJu.SBH89LAiA4ye698TfMPyam4BO7ifs7HLuiBPrEW.zIz&amp;X-Amz-Signature=69bc7be37c8c42096e78aa4ff752f073ea890481c5f76eac5ad40a5ab9466997</upload_uri>
  <partsize type="integer">5242880</partsize>
  <part_number type="integer">1</part_number>
  <available_parts type="integer">10000</available_parts>
  <send>
    <partsize>required-parameter Content-Length</partsize>
    <partdata>body</partdata>
  </send>
  <headers></headers>
  <parameters></parameters>
</upload>

Property Reference

ref string Unique identifier to reference this file upload. This identifier is needed for subsequent requests to the REST API to complete the upload or request more upload URLs.
http_method string Value is PUT or POST, and is the HTTP method used when uploading the file to S3 at the upload_uri. This value will always be PUT for this particular action, but other actions may return POST.
upload_uri string The URL where the file is uploaded to.
partsize integer Recommended size of upload. When uploading file pieces to Amazon S3, the piece sizes are required to be between 5 MB and 5 GB (except the last part). This value provides a recommended size to upload for this part without adding another part.
part_number integer Number of this part, which is always between 1 and 10,000, and will always be 1 for the first upload URL at the beginning of uploading a new file.
available_parts integer Number of parts available for this upload. For new file uploads this value is always 10,000, but it may be smaller for other uploads. When requesting more upload URLs from the REST API, the part numbers must be between 1 and this number.
headers key-value pairs A list of required headers and their exact values to send in the file upload. It may be empty if no headers with fixed values are required.
parameters key-value pairs A list of required parameters and their exact values to send in the file upload. If any values are in this array, it is implied that the upload request is formatted appropriately to send form data parameters. It will always be empty if the body of the request is specified to be where the file upload data goes (see send below).
send key-value pairs This is an array of values to be sent in the file upload request up to Amazon S3. Possible sub-values are partsize, partdata, file, and Content-Type:
  • file: where to put the file data for the entire file upload
  • partdata: where to put the file data for this part
  • partsize: where to put the size of the upload for this file part
  • Content-Type: where to put the Content-Type of the file (which can have no bearing on the file’s actual type)
Possible values for these parameters:
  • body: this information is the body of the PUT or POST request
  • required-header <header name>: this information goes in the named header
  • required-parameter <parameter name>: this information goes in the named parameter, and implies this request is formatted appropriately to send form data parameters
path string Intended destination path of the file upload. Path may change upon finalization, depending on existance of another upload to the same location and the site's overwrite setting.
action string Value is always write or put for this action.
ask_about_overwrites boolean If true, a file by this name already exists and will be overwritten when this upload completes if it continues.

Uploading the Parts to Amazon S3

At this point, you are to send a PUT request to Amazon S3 at the endpoint provided by BrickFTP with the file data and the headers and parameters provided to you from BrickFTP.

The download link provided is signed by BrickFTP and must be used within 15 minutes.

Should you wish to upload the file in multiple parts (and indeed you are required to use multiple parts if the file size exceeds 5 GB), you will need to request a new upload URL for the second part.

Sample Upload Header and Body

PUT /objects.brickftp.com/metadata/1234/75118536-1bd1-0132-7c06-4b9bfda8587d?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIEWLY3MN4YGZQOWA%2F20150730%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20150730T052059Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&partNumber=1&uploadId=0yauyO3.a_LIxPCFAf3WmSu1AWPv7xGiBGLDJGZp47qEM_VKoLgAs6T2CEjfxPrl83ZVVIDaBnrZdnDjYo3bwVpa9JC_gGHNNQbpBtpPR_Gj0wXTbalyjVBmfTFPzuci&X-Amz-Signature=NH.8Uzx4CQWTK4TscCGXDNL1leRY5fg4bGMR94oXgV1MOp.MmysIYcgpAkSfO3f4 HTTP/1.1
Host: s3.amazonaws.com
Content-Length: 41

This is a test upload file to BrickFTP.

Requesting Upload URLs

Once an upload has been opened and before it is completed, additional upload URLs can be requested from the REST API. Send a POST request to /files/PATH_AND_FILENAME.EXT with parameter action set to put, parameter ref set to the reference ID returned at the start of the upload, and parameter part set to the part number the upload URL should refer to. The part number can be the same as one previously used if a new URL is required, either because the part is to be re-uploaded or because a prior upload attempt failed and the prior URL’s signature has expired.

POST /files/:path_and_filename

Sample Request

{
  "action": "put",
  "ref": "put-378670",
  "part": 2
}
<file>
  <action>put</action>
  <ref>put-378670</ref>
  <part>2</part>
</file>

Sample Response

200 Success

Same as in Starting a New Upload.

Completing an Upload

After uploading the file to Amazon S3, the REST API needs to be notified that the upload was completed. This is done by sending another POST request to /files/PATH_AND_FILENAME.EXT with parameter action set to end and parameter ref set to the reference ID returned at the start of the upload.

POST /files/:path_and_filename

Sample Request Body

{
  "action": "end",
  "ref": "put-378670"
}
<file>
  <action>end</action>
  <ref>put-378670</ref>
</file>

Sample Response

200 Success

{
  "path": "NewFile.txt",
  "type": "file",
  "size": 412,
  "mtime": "2014-05-17T05:14:35+00:00",
  "crc32": null,
  "md5": null
}
<?xml version="1.0" encoding="UTF-8"?>
<file>
  <path>NewFile.txt</path>
  <type>file</type>
  <size type="integer">412</size>
  <mtime type="datetime">2014-05-17T05:14:35+00:00</mtime>
  <crc32 nil="true"/>
  <md5 nil="true"/>
</file>

Restarting or Appending to Prior Upload

Once an upload has already been completed and now data needs to be added to it, you can send a POST request to /files/PATH_AND_FILENAME.EXT with parameter action set to put and parameter restart set to the number of bytes to keep at the beginning of the file (this should normally equal the current file size). The request and response formats are the same as starting an upload for a new file, but the value of available_parts in the response will always be less than 10,000 by the number of parts needed to be reserved by BrickFTP to copy over the existing file data.

POST /files/:path_and_filename

Sample Request Body

{
  "action": "put",
  "restart": 412
}
<file>
  <action>put</action>
  <restart>412</restart>
</file>

Sample Response

200 Success

Same as in Starting a New Upload.