BrickFTP™

REST API Integration

Note: We also have a Javascript API, which you can find information about here.

Our REST API is meant for people who require the highest level of integration between Brick and your 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.

Authentication

To use the REST API, you first need to enable it on the Site tab. When you do, it will display a REST API Key. This API Key must be provided in every API request. Note that this is different from the Javascript API Key. The REST API Key must be kept secure, as it allows full access to your site account via the API. If you feel that your API Key is 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.

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://.

The extension of the request will determine the response. So a request ending in .json will send back 'application/json' and .xml will return 'application/xml'

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

General API Operations

To read an object or list of objects, send a GET request. Each type of object (User, Group, etc.) has a URL that can be used for listing. Further, each object has its own URL that will allow you to retrieve all the information available about that object. Our response will be a JSON or XML document containing the object or the collection of objects.

To create or update an object, send a POST or PUT request, respectively. With these requests, and depending on what format data you are sending, you will need to set the Content-Type: application/json or Content-Type: application/xml header.

Here's a quick example of POST in XML to create a record, and PUT in JSON to update:

curl -u EB4585AD9FE0426781ED7C49252F8225:x -H 'Content-Type: application/xml' \
-d '<user><username>alice</username><password>secure123</password></user>' \ 
https://app.brickftp.com/api/rest/v1/users.xml
curl -u EB4585AD9FE0426781ED7C49252F8225:x -X PUT -H 'Content-Type: application/json' \
-d '{ "password": "secure789" }' https://app.brickftp.com/api/rest/v1/users/123.json

If successful, we will send the 201 Created (new objects) or 200 Success (existing objects) response code. We will also send a JSON/XML representation of the full object in the body of the response. In the event of a failure (username already taken, password not provided, etc.) we will send a 422 Unprocessable Entity status code, and put a JSON/XML representation of the errors in the body of the response.

To delete an object, send a DELETE request. It is not necessary to include a request body. We will respond with 200 Success.

curl -u EB4585AD9FE0426781ED7C49252F8225:x -X DELETE https://app.brickftp.com/api/rest/v1/users/123.xml

Users

Here are the operations for listing, showing, creating, updating, and deleting users. After each operation is either a sample request or sample response. An explanation of all the properties follows the operations.

List

GET /users.(json|xml)

Sample Response:

[
    {
        "id": 2,
        "username": "stork",
        "name": "Stork",
        "email": "",
        "notes": "Cake",
        "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": "zaphod@beeblebrox.com",
        "notes": "He's a great dude.",
        "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>Stork</name>
        <email></email>
        <notes>Cake</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>zaphod@beeblebrox.com</email>
        <notes>He's a great dude.</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

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

Sample Response:

{
    "id": 2,
    "username": "stork",
    "name": "Stork",
    "email": "",
    "notes": "Cake",
    "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>Stork</name>
    <email></email>
    <notes>Cake</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

POST /users.(json|xml)

Sample Request:

{
    "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>

Update

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

Sample Request:

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

Delete

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

The DELETE command doesn't require a request body. It will return 200 Success and an empty XML body.

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

Property Reference

id

integer

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 it's 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 API, though may be obtained with the Permissions API described below.

Groups

Here are the operations for listing, showing, creating, updating, and deleting groups. After each operation is either a sample request or sample response. An explanation of all the properties follows the operations.

List

GET /groups.(json|xml)

Sample Response:

[
    {
        "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

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

Sample Response:

{
    "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

POST /groups.(json|xml)

Sample Request:

{
    "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>

Update

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

Sample Request:

{
    "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>

Delete

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

The DELETE command doesn't require a request body. It will return 200 Success and an empty XML body.

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

Property Reference

id

integer

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.

Notifications

Here are the operations for listing, creating, and deleting notifications. After each operation is either a sample request or sample response. An explanation of all the properties follows the operations.

List

GET /notifications.(json|xml)

Sample Response:

[
    {
        "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

POST /notifications.(json|xml)

Sample Request:

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

Delete

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

The DELETE command doesn't require a request body. It will return 200 Success and an empty XML body.

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

Property Reference

id

integer

Unique identifier of each Nofification. Each notification is given an ID automatically upon creation.

path

string (5000)

Directory path for notifications. This must be slash-delimited.

user_id

integer

Unique identifier for the user being notified. Each user is given an ID automatically upon creation.

username

string (50)

Username for the user given by user_id. If this value is set during creation, the user_id is looked up from the username and set.

Permissions

Here are the operations for listing, creating, and deleting permissions. After each operation is either a sample request or sample response. An explanation of all the properties follows the operations.

List

GET /permissions.(json|xml)

Sample Response:

[
    {
        "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

POST /permissions.(json|xml)

Sample Request:

{
    "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>

Delete

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

The DELETE command doesn't require a request body. It will return 200 Success and an empty XML body.

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

Property Reference

id

integer

Unique identifier of each Permission. Each permission is given an ID automatically upon creation.

path

string (5000)

Directory path for notifications. This must be slash-delimited.

permission

enum

Value must be set to full, readonly, writeonly, or previewonly.

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, 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.

Questions?

We hope that this document helps you integrate our REST API. If you have any questions, please feel free to contact us.

If you would like a feature added to the API, let us know and we'll let you know whether it's possible.

Security Seals
credit card logos