API Documentation

TOC Navbar
curl curl
  • Introduction
  • Authentication with API Key
  • Authentication with a Session
  • Users
  • User API Keys
  • User Public Keys
  • Groups
  • Permissions
  • Notifications
  • History
  • Bundles
  • Behaviors
  • File and Folder Operations
  • File Uploading
  • Errors
  • Introduction

    API Endpoint

    https://SUBDOMAIN.brickftp.com/api/rest/v1/
    

    Replace SUBDOMAIN with your custom BrickFTP subdomain

    Welcome to the BrickFTP API! Our REST API is designed for people who require the highest level of integration between BrickFTP and their own application, website, or database.

    This is the same API used by the BrickFTP web interface, so everything you can do in the web UI can also be accomplished using the API.

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

    Authentication with API Key

    Authenticating with an API key is the recommended authentication method for most scenarios, and is the method used in the examples on this site. BrickFTP also supports authentication with user sessions.

    Example of authenticating with an API key

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/users.json \
      -u YOUR_API_KEY:x
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/users.xml \
      -u YOUR_API_KEY:x
    

    Make sure to replace SUBDOMAIN with your custom subdomain, and YOUR_API_KEY with your API key.

    To use the REST API with an API Key, first generate an API key from the web interface or via the API. Note that when using a user-specific API key, if the user is an administrator, you will have full access to the entire API. If the user is not an administrator, you will only be able to access files that user can access, and no access will be granted to site administration functions in the API.

    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.

    Authentication with a Session

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

    Logging in

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/sessions.json \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{"username": "motor", "password": "vroom"}'
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/sessions.xml \
      -X POST \
      -H 'Content-Type: application/xml' \
      -d '<session><username>motor</username><password>vroom</password></session>'
    

    Example Response

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

    To create a session, a POST request is made to /sessions with the user’s username and password.

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

    HTTP Request

    POST /sessions.(json|xml)

    Using a session

    Example Request

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

    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.

    Reauthentication

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/users/123.json \
      -b BrickAPI=8c2e9f493dd8a857d5cdddbb7bf64ece0b7fb599 \
      -X PUT \
      -H 'Content-Type: application/json' \
      -H 'X-BRICK-REAUTHENTICATION: password:YourPasswordHere' \
      -d '{"password": "NewPassword"}'
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/users/123.xml \
      -b BrickAPI=8c2e9f493dd8a857d5cdddbb7bf64ece0b7fb599 \
      -X PUT \
      -H 'Content-Type: application/xml' \
      -H 'X-BRICK-REAUTHENTICATION: password:YourPasswordHere' \
      -d '<user><password>NewPassword</password></user>'
    

    If authenticating to the API via a session cookie or session ID (as opposed to an API key), we require that you provide the session user’s password again in a X-BRICK-REAUTHENTICATION header for certain types of requests where we want to add an additional level of security. We call this process Reauthentication.

    Currently, reauthentication is required for the following actions:

    Logging out

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/sessions.json \
      -b BrickAPI=8c2e9f493dd8a857d5cdddbb7bf64ece0b7fb599 \
      -X DELETE
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/sessions.xml \
      -b BrickAPI=8c2e9f493dd8a857d5cdddbb7bf64ece0b7fb599 \
      -X DELETE
    

    Example Response

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

    User sessions can be ended by sending a DELETE request to /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 sending a DELETE request at this endpoint will always result in a response of an empty array, even if an invalid user session was passed in.

    HTTP Request

    DELETE /sessions.(json|xml)

    Users

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

    The user object

    Attribute Description
    id integer Globally unique identifier of each user. Each user is given an ID automatically upon creation.
    username string Username for the user. This is how the user will be displayed on the site. Maximum of 50 characters.
    authentication_method enum Authentication method for this user. Can be one of the following: password, ldap, or oauth_google. Default is password.
    last_login_at datetime The date and time of the most recent login for this user. This property is read-only.
    password string Password for the user. This property is write-only. It cannot be retrieved via the API.
    password_confirmation string Confirms the new password provided in the password field. This field is optional but will be validated if provided.
    authenticate_until datetime If set, the user will be blocked from logging in after this date.
    name string Real name of the user. For your reference. Maximum of 50 characters.
    email string E-Mail address of the user. Maximum of 50 characters.
    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 Allow user access via FTP/FTPS (port 21 or 990) interface. Default is true.
    sftp_permission boolean Allow user access via SFTP (port 22) interface. Default is true.
    dav_permission boolean Allow user access via WebDAV (port 443) interface. Default is true.
    restapi_permission boolean Allow user access the REST API, via HTTP/HTTPS (port 80 or 443), and the desktop application. Default is true.
    attachments_permission boolean Allow user to use Sharing tab in web interface to share files with anonymous users via a unique URL. Default is false.
    self_managed boolean Allow user to change their password and user information via the web interface. Default is true.
    require_password_change boolean Require user to change their password at their next login. Note: requires restapi_permission to be true, as password changes can only occur via the web interface. Default is false.
    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 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/. Limit of 250 characters.
    time_zone string File modification times will be displayed in this time zone. Default is Eastern Time (US & Canada).
    language string The language that BrickFTP will be displayed in, if the translation is available. Leave as default (null) to auto-detect or use the site setting.
    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 Permissions resource of the REST API.
    ssl_required enum Whether or not SSL encryption is required on all connections for this user. Can be one of the following: use_system_setting, always_require, or never_require. Default is use_system_setting.
    site_admin boolean If set to true, this user will be treated as a site-wide administrator. Default is false.
    receive_admin_alerts boolean Enable this user to receive alerts sent to site administrators. This property will only be accepted/returned if site_admin is true. Default is false.
    subscribe_to_newsletter boolean Add this user to the BrickFTP newsletter and our mailing list for notices about product updates. This property will only be accepted/returned if site_admin is true. Default is false.
    can_create_new_users boolean If true, this user will be able to create other users within groups where they have administrator privileges. Default is false.
    last_protocol_cipher string The encryption protocol (for HTTPS or FTPS) or ciphers (for SFTP) that this user last connected with. This property is read-only.
    lockout_expires datetime If the user has been locked out by Brute Force Login Protection, this will indicate when the lock expires. Otherwise this will be null. This property is read-only.
    admin_group_ids comma-separated integers IDs of the Groups that this user is an administrator of.

    List users

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/users.json \
      -u YOUR_API_KEY:x 
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/users.xml \
      -u YOUR_API_KEY:x 
    

    Example Response

    [
      {
        "id": 2,
        "username": "stork",
        "authentication_method": "password",
        "last_login_at": "2015-10-20T11:57:28-05:00",
        "authenticate_until": null,
        "name": "John",
        "email": "",
        "notes": "",
        "group_ids": "2",
        "ftp_permission": true,
        "sftp_permission": true,
        "dav_permission": true,
        "restapi_permission": true,
        "attachments_permission": true,
        "self_managed": true,
        "require_password_change": false,
        "allowed_ips": "",
        "user_root": "API",
        "time_zone": "Eastern Time (US & Canada)",
        "language": "",
        "ssl_required": "use_system_setting",
        "site_admin": false,
        "can_create_new_users": false,
        "last_protocol_cipher": "TLSv1.2; ECDHE-RSA-AES128-GCM-SHA256",
        "lockout_expires":null,
        "admin_group_ids": []
      },
      {
        "id": 3,
        "username": "zaphod",
        "authentication_method": "password",
        "last_login_at": "2015-11-10T18:03:51-05:00",
        "authenticate_until": null,
        "name": "Zaphod Beeblebrox",
        "email": "towel@example.com",
        "notes": "",
        "group_ids": "1",
        "ftp_permission": true,
        "sftp_permission": true,
        "dav_permission": true,
        "restapi_permission": true,
        "attachments_permission": true,
        "self_managed": true,
        "require_password_change": false,
        "allowed_ips": "",
        "user_root": "Zaphod",
        "time_zone":"Eastern Time (US & Canada)",
        "language": "",
        "ssl_required": "use_system_setting",
        "site_admin": false,
        "can_create_new_users": false,
        "last_protocol_cipher": "ssh; diffie-hellman-group-exchange-sha256 aes128-ctr hmac-sha2-256",
        "lockout_expires":null,
        "admin_group_ids": []
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <users type="array">
      <user>
        <id type="integer">2</id>
        <username>stork</username>
        <authentication_method type="symbol">password</authentication_method>
        <last_login_at type="dateTime">2015-10-20T11:57:28-05:00</last_login_at>
        <authenticate_until nil="true"/>
        <name>John</name>
        <email></email>
        <notes></notes>
        <group_ids>2</group_ids>
        <ftp_permission type="boolean">true</ftp_permission>
        <sftp_permission type="boolean">true</sftp_permission>
        <dav_permission type="boolean">true</dav_permission>
        <restapi_permission type="boolean">true</restapi_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>
        <time_zone>Eastern Time (US &amp; Canada)</time_zone>
        <language></language>
        <ssl_required type="symbol">use_system_setting</ssl_required>
        <site_admin type="boolean">false</site_admin>
        <can_create_new_users type="boolean">false</can_create_new_users>
        <last_protocol_cipher>TLSv1.2; ECDHE-RSA-AES256-GCM-SHA384</last_protocol_cipher>
        <lockout_expires nil="true"/>
        <admin_group_ids type="array"/>
      </user>
      <user>
        <id type="integer">3</id>
        <username>zaphod</username>
        <authentication_method type="symbol">password</authentication_method>
        <last_login_at type="dateTime">2015-11-10T18:03:51-05:00</last_login_at>
        <authenticate_until nil="true"/>
        <name>Zaphod Beeblebrox</name>
        <email>towel@example.com</email>
        <notes></notes>
        <group_ids>1</group_ids>
        <ftp_permission type="boolean">true</ftp_permission>
        <sftp_permission type="boolean">true</sftp_permission>
        <dav_permission type="boolean">true</dav_permission>
        <restapi_permission type="boolean">true</restapi_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>
        <time_zone>Eastern Time (US &amp; Canada)</time_zone>
        <language></language>
        <ssl_required type="symbol">use_system_setting</ssl_required>
        <site_admin type="boolean">false</site_admin>
        <can_create_new_users type="boolean">false</can_create_new_users>
        <last_protocol_cipher>ssh; diffie-hellman-group-exchange-sha256 aes128-ctr hmac-sha2-256</last_protocol_cipher>
        <lockout_expires nil="true"/>
        <admin_group_ids type="array"/>
      </user>
    </users>
    

    Returns a list of users on the current site.

    HTTP Request

    GET /users.(json|xml)

    Request URL Parameters

    Parameter Description
    page integer Optional page number of items to return in this request. Default: 1.
    per_page integer Optional requested number of items returned per request. Default: 1000. Leave blank for default (strongly recommended).

    Count users

    Example Request

    curl "https://SUBDOMAIN.brickftp.com/api/rest/v1/users.json?action=count" \
      -u YOUR_API_KEY:x
    
    curl "https://SUBDOMAIN.brickftp.com/api/rest/v1/users.xml?action=count" \
      -u YOUR_API_KEY:x
    

    Example Response

    {
      "data": {
        "count": 175
      },
      "type": "200-ok"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <result>
      <data>
        <count type="integer">175</count>
      </data>
      <type>200-ok</type>
    </result>
    

    Returns a count of the number of users for the current site.

    HTTP Request

    GET /users.(json|xml)?action=count

    Search users

    Example Request

    curl "https://SUBDOMAIN.brickftp.com/api/rest/v1/users.json?q\[username\]=stork" \
      -u YOUR_API_KEY:x 
    
    curl "https://SUBDOMAIN.brickftp.com/api/rest/v1/users.xml?q\[username\]=stork" \
      -u YOUR_API_KEY:x 
    

    Example Response

    {
      "id": 2,
      "username": "stork",
      "authentication_method": "password",
      "last_login_at": "2015-10-20T11:57:28-05:00",
      "authenticate_until": null,
      "name": "John",
      "email": "",
      "notes": "",
      "group_ids": "2",
      "ftp_permission": true,
      "sftp_permission": true,
      "dav_permission": true,
      "restapi_permission": true,
      "attachments_permission": true,
      "self_managed": true,
      "require_password_change": false,
      "allowed_ips": "",
      "user_root": "API",
      "time_zone": "Eastern Time (US & Canada)",
      "language": "",
      "ssl_required": "use_system_setting",
      "site_admin": false,
      "can_create_new_users": false,
      "last_protocol_cipher": "TLSv1.2; ECDHE-RSA-AES128-GCM-SHA256",
      "lockout_expires":null,
      "admin_group_ids": []
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <user>
      <id type="integer">2</id>
      <username>stork</username>
      <authentication_method type="symbol">password</authentication_method>
      <last_login_at type="dateTime">2015-10-20T11:57:28-05:00</last_login_at>
      <authenticate_until nil="true"/>
      <name>John</name>
      <email></email>
      <notes></notes>
      <group_ids>2</group_ids>
      <ftp_permission type="boolean">true</ftp_permission>
      <sftp_permission type="boolean">true</sftp_permission>
      <dav_permission type="boolean">true</dav_permission>
      <restapi_permission type="boolean">true</restapi_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>
      <time_zone>Eastern Time (US &amp; Canada)</time_zone>
      <language></language>
      <ssl_required type="symbol">use_system_setting</ssl_required>
      <site_admin type="boolean">false</site_admin>
      <can_create_new_users type="boolean">false</can_create_new_users>
      <last_protocol_cipher>TLSv1.2; ECDHE-RSA-AES256-GCM-SHA384</last_protocol_cipher>
      <lockout_expires nil="true"/>
      <admin_group_ids type="array"/>
    </user>
    

    Returns a single user based on their username rather than their ID.

    HTTP Request

    GET /users.(json|xml)?q[username]=stork

    Show a user

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/users/2.json \
      -u YOUR_API_KEY:x 
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/users/2.xml \
      -u YOUR_API_KEY:x 
    

    Example Response

    {
      "id": 2,
      "username": "stork",
      "authentication_method": "password",
      "last_login_at": "2015-10-20T11:57:28-05:00",
      "authenticate_until": null,
      "name": "John",
      "email": "",
      "notes": "",
      "group_ids": "2",
      "ftp_permission": true,
      "sftp_permission": true,
      "dav_permission": true,
      "restapi_permission": true,
      "attachments_permission": true,
      "self_managed": true,
      "require_password_change": false,
      "allowed_ips": "",
      "user_root": "API",
      "time_zone": "Eastern Time (US & Canada)",
      "language": "",
      "ssl_required": "use_system_setting",
      "site_admin": false,
      "can_create_new_users": false,
      "last_protocol_cipher": "TLSv1.2; ECDHE-RSA-AES128-GCM-SHA256",
      "lockout_expires":null,
      "admin_group_ids": []
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <user>
      <id type="integer">2</id>
      <username>stork</username>
      <authentication_method type="symbol">password</authentication_method>
      <last_login_at type="dateTime">2015-10-20T11:57:28-05:00</last_login_at>
      <authenticate_until nil="true"/>
      <name>John</name>
      <email></email>
      <notes></notes>
      <group_ids>2</group_ids>
      <ftp_permission type="boolean">true</ftp_permission>
      <sftp_permission type="boolean">true</sftp_permission>
      <dav_permission type="boolean">true</dav_permission>
      <restapi_permission type="boolean">true</restapi_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>
      <time_zone>Eastern Time (US &amp; Canada)</time_zone>
      <language></language>
      <ssl_required type="symbol">use_system_setting</ssl_required>
      <site_admin type="boolean">false</site_admin>
      <can_create_new_users type="boolean">false</can_create_new_users>
      <last_protocol_cipher>TLSv1.2; ECDHE-RSA-AES256-GCM-SHA384</last_protocol_cipher>
      <lockout_expires nil="true"/>
      <admin_group_ids type="array"/>
    </user>
    

    Returns a single user.

    HTTP Request

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

    Create a user

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/users.json \
      -u YOUR_API_KEY:x \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{"username": "johndoe", "password": "doejohn123"}'
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/users.xml \
      -u YOUR_API_KEY:x \
      -X POST \
      -H 'Content-Type: application/xml' \
      -d '<user><username>johndoe</username><password>doejohn123</password>'
    

    Example Response

    {
      "id": 76,
      "username": "johndoe",
      "authentication_method": "password",
      "last_login_at": null,
      "authenticate_until": null,
      "name": null,
      "email": null,
      "notes": null,
      "group_ids": "",
      "ftp_permission": true,
      "sftp_permission": true,
      "dav_permission": true,
      "restapi_permission": true,
      "attachments_permission": false,
      "self_managed": true,
      "require_password_change": false,
      "allowed_ips": null,
      "user_root": "",
      "time_zone": "Eastern Time (US & Canada)",
      "language": "",
      "ssl_required": "use_system_setting",
      "site_admin": false,
      "can_create_new_users": false,
      "last_protocol_cipher": null,
      "lockout_expires": null,
      "admin_group_ids": []
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <user>
      <id type="integer">76</id>
      <username>johndoe</username>
      <authentication_method type="symbol">password</authentication_method>
      <last_login_at nil="true"/>
      <authenticate_until nil="true"/>
      <name nil="true"/>
      <email nil="true"/>
      <notes nil="true"/>
      <group_ids></group_ids>
      <ftp_permission type="boolean">true</ftp_permission>
      <sftp_permission type="boolean">true</sftp_permission>
      <dav_permission type="boolean">true</dav_permission>
      <restapi_permission type="boolean">true</restapi_permission>
      <attachments_permission type="boolean">false</attachments_permission>
      <self_managed type="boolean">true</self_managed>
      <require_password_change type="boolean">false</require_password_change>
      <allowed_ips nil="true"/>
      <user_root></user_root>
      <time_zone>Eastern Time (US &amp; Canada)</time_zone>
      <language></language>
      <ssl_required type="symbol">use_system_setting</ssl_required>
      <site_admin type="boolean">false</site_admin>
      <can_create_new_users type="boolean">false</can_create_new_users>
      <last_protocol_cipher>TLSv1.2; ECDHE-RSA-AES256-GCM-SHA384</last_protocol_cipher>
      <lockout_expires nil="true"/>
      <admin_group_ids type="array"/>
    </user>
    

    Creates a new user on the current site.

    HTTP Request

    POST /users.(json|xml)

    Update a user

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/users/2.json \
      -u YOUR_API_KEY:x \
      -X PUT \
      -H 'Content-Type: application/json' \
      -d '{
            "password": "new_password", 
            "require_password_change": true
          }'
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/users/2.xml \
      -u YOUR_API_KEY:x \
      -X PUT \
      -H 'Content-Type: application/xml' \
      -d '<user>
            <password>new_password</password>
            <require_password_change>true</require_password_change>
          </user>'
    

    Example Response

    {
      "id": 2,
      "username": "stork",
      "authentication_method": "password",
      "last_login_at": "2015-10-20T11:57:28-05:00",
      "authenticate_until": null,
      "name": "John",
      "email": "",
      "notes": "",
      "group_ids": "2",
      "ftp_permission": true,
      "sftp_permission": true,
      "dav_permission": true,
      "restapi_permission": true,
      "attachments_permission": true,
      "self_managed": true,
      "require_password_change": true,
      "allowed_ips": "",
      "user_root": "API",
      "time_zone": "Eastern Time (US & Canada)",
      "language": "",
      "ssl_required": "use_system_setting",
      "site_admin": false,
      "can_create_new_users": false,
      "last_protocol_cipher": "TLSv1.2; ECDHE-RSA-AES128-GCM-SHA256",
      "lockout_expires":null,
      "admin_group_ids": []
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <user>
      <id type="integer">2</id>
      <username>stork</username>
      <authentication_method type="symbol">password</authentication_method>
      <last_login_at type="dateTime">2015-10-20T11:57:28-05:00</last_login_at>
      <authenticate_until nil="true"/>
      <name>John</name>
      <email></email>
      <notes></notes>
      <group_ids>2</group_ids>
      <ftp_permission type="boolean">true</ftp_permission>
      <sftp_permission type="boolean">true</sftp_permission>
      <dav_permission type="boolean">true</dav_permission>
      <restapi_permission type="boolean">true</restapi_permission>
      <attachments_permission type="boolean">true</attachments_permission>
      <self_managed type="boolean">true</self_managed>
      <require_password_change type="boolean">true</require_password_change>
      <allowed_ips></allowed_ips>
      <user_root>API</user_root>
      <time_zone>Eastern Time (US &amp; Canada)</time_zone>
      <language></language>
      <ssl_required type="symbol">use_system_setting</ssl_required>
      <site_admin type="boolean">false</site_admin>
      <can_create_new_users type="boolean">false</can_create_new_users>
      <last_protocol_cipher>TLSv1.2; ECDHE-RSA-AES256-GCM-SHA384</last_protocol_cipher>
      <lockout_expires nil="true"/>
      <admin_group_ids type="array"/>
    </user>
    

    Updates the specified user. For additional security, this method requires reauthentication when updating a password unless an API key is used.

    HTTP Request

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

    Delete a user

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/users/2.json \
      -u YOUR_API_KEY:x \
      -X DELETE 
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/users/2.xml \
      -u YOUR_API_KEY:x \
      -X DELETE 
    

    Example Response

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

    Deletes the specified user. For additional security, this method requires reauthentication when updating a password unless an API key is used.

    HTTP Request

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

    Unlock a user

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/user/2/unlock.json \
      -u YOUR_API_KEY:x \
      -X POST 
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/user/2/unlock.xml \
      -u YOUR_API_KEY:x \
      -X POST 
    

    Example Response

    {
      "id": 2,
      "username": "stork",
      "authentication_method": "password",
      "last_login_at": "2015-10-20T11:57:28-05:00",
      "authenticate_until": null,
      "name": "John",
      "email": "",
      "notes": "",
      "group_ids": "2",
      "ftp_permission": true,
      "sftp_permission": true,
      "dav_permission": true,
      "restapi_permission": true,
      "attachments_permission": true,
      "self_managed": true,
      "require_password_change": true,
      "allowed_ips": "",
      "user_root": "API",
      "time_zone": "Eastern Time (US & Canada)",
      "language": "",
      "ssl_required": "use_system_setting",
      "site_admin": false,
      "can_create_new_users": false,
      "last_protocol_cipher": "TLSv1.2; ECDHE-RSA-AES128-GCM-SHA256",
      "lockout_expires":null,
      "admin_group_ids": []
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <user>
      <id type="integer">2</id>
      <username>stork</username>
      <authentication_method type="symbol">password</authentication_method>
      <last_login_at type="dateTime">2015-10-20T11:57:28-05:00</last_login_at>
      <authenticate_until nil="true"/>
      <name>John</name>
      <email></email>
      <notes></notes>
      <group_ids>2</group_ids>
      <ftp_permission type="boolean">true</ftp_permission>
      <sftp_permission type="boolean">true</sftp_permission>
      <dav_permission type="boolean">true</dav_permission>
      <restapi_permission type="boolean">true</restapi_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>
      <time_zone>Eastern Time (US &amp; Canada)</time_zone>
      <language></language>
      <ssl_required type="symbol">use_system_setting</ssl_required>
      <site_admin type="boolean">false</site_admin>
      <can_create_new_users type="boolean">false</can_create_new_users>
      <last_protocol_cipher>TLSv1.2; ECDHE-RSA-AES256-GCM-SHA384</last_protocol_cipher>
      <lockout_expires nil="true"/>
      <admin_group_ids type="array"/>
    </user>
    

    Unlocks a user that has been locked out by Brute Force Login Protection.

    HTTP Request

    POST /users/:id/unlock.(json|xml)

    User API Keys

    The API Keys resource in the REST API allows you to operate on user API keys. This resource supports listing, creating, showing, and deleting user API keys.

    The API key object

    Attribute Description
    id integer Globally unique identifier of each user API key. Each user API key is given an ID automatically upon creation.
    key string The API key itself. This property is read-only.
    name string Name to identify the user API key. For your reference. Maximum of 100 characters.
    permission_set string The permission set for the user API key. Can be desktop_app or full.
    platform string The platform for the user API key. Can be win32, macos, linux, or none. Applies only to API keys with a permission_set of desktop_app.
    expires_at datetime The date that this API key is valid through.
    created_at datetime Creation date of the user API key. This property is read-only.

    List API keys

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/users/987/api_keys.json \
      -u YOUR_API_KEY:x 
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/users/987/api_keys.xml \
      -u YOUR_API_KEY:x 
    

    Example Response

    [
      {
        "id": 444,
        "name": "Desktop",
        "permission_set": "desktop_app",
        "platform": "macos",
        "expires_at": null,
        "created_at": "2016-10-07T14:41:51-04:00"
      },
      {
        "id": 999,
        "name": "My API key",
        "permission_set": "full",
        "platform": "none",
        "expires_at": "2017-11-01T02:59:59-04:00",
        "created_at": "2017-10-18T20:51:11-04:00"
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <api-keys type="array">
      <api-key>
        <id type="integer">444</id>
        <name>Desktop</name>
        <permission_set type="symbol">desktop_app</permission_set>
        <platform type="symbol">macos</platform>
        <expires_at nil="true"/>
        <created_at type="dateTime">2016-10-07T14:41:51-04:00</created_at>
      </api-key>
      <api-key>
        <id type="integer">999</id>
        <name>My API key</name>
        <permission_set type="symbol">full</permission_set>
        <platform type="symbol">none</platform>
        <expires_at type="dateTime">2017-11-01T02:59:59-04:00</expires_at>
        <created_at type="dateTime">2016-10-07T14:41:51-04:00</created_at>
      </api-key>
    </api-keys>
    

    Returns a list of all API keys for a user on the current site.

    HTTP Request

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

    Show an API key

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/api_keys/999.json \
      -u YOUR_API_KEY:x 
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/api_keys/999.xml \
      -u YOUR_API_KEY:x 
    

    Example Response

    {
      "id": 999,
      "name": "My API key",
      "permission_set": "full",
      "platform": "none",
      "expires_at": "2017-11-01T02:59:59-04:00",
      "created_at": "2017-10-18T20:51:11-04:00"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <api-key>
      <id type="integer">999</id>
      <name>My API key</name>
      <permission_set type="symbol">full</permission_set>
      <platform type="symbol">none</platform>
      <expires_at type="dateTime">2017-11-01T02:59:59-04:00</expires_at>
      <created_at type="dateTime">2017-10-18T20:51:11-04:00</created_at>
    </api-key>
    

    Returns a single API key.

    HTTP Request

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

    Create an API key

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/users/987/api_keys.json \
      -u YOUR_API_KEY:x \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{
            "name": "My API key", 
            "permission_set": "full"
          }'
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/users/987/api_keys.xml \
      -u YOUR_API_KEY:x \
      -X POST \
      -H 'Content-Type: application/xml' \
      -d '<api-key>
            <name>My API key</name>
            <permission_set>full</permission_set>
          </api-key>'
    

    Example Response

    {
      "id": 9898,
      "key": "86d3239a9082049503feba54c979e1d135239e524de6dd8d3486ba1e070cb5c4",
      "name": "My API key",
      "permission_set": "full",
      "platform": "none",
      "expires_at": null,
      "created_at": "2017-10-30T19:14:36-04:00"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <api-key>
      <id type="integer">8112</id>
      <key>86d3239a9082049503feba54c979e1d135239e524de6dd8d3486ba1e070cb5c4</key>
      <name>My API Key</name>
      <permission_set type="symbol">full</permission_set>
      <platform type="symbol">none</platform>
      <expires_at nil="true"/>
      <created_at type="dateTime">2017-10-30T19:14:36-04:00</created_at>
    </api-key>
    

    Creates a new API key for a user on the current site.

    HTTP Request

    POST /users/:id/api_keys.(json|xml)

    Delete an API key

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/api_keys/9898.json \
      -u YOUR_API_KEY:x \
      -X DELETE
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/api_keys/9898.xml \
      -u YOUR_API_KEY:x \
      -X DELETE
    

    Example Response

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

    Deletes the specified API key.

    HTTP Request

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

    User Public Keys

    The Public Keys resource in the REST API allows you to operate on user public SSH keys. This resource supports listing, creating, showing, and deleting public keys.

    The public key object

    Attribute Description
    id integer Globally unique identifier of each public key. Each public key is given an ID automatically upon creation.
    title string Title to identify the public key. For your reference. Maximum of 50 characters.
    fingerprint string RSA fingerprint of the public key. This property is read-only.
    public_key string The public key itself. This property is write-only. It cannot be retrieved via the API.
    created_at datetime Creation date of the public key. This property is read-only.

    List public keys

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/users/987/public_keys.json \
      -u YOUR_API_KEY:x 
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/users/987/public_keys.xml \
      -u YOUR_API_KEY:x 
    

    Example Response

    [
      {
        "id":1234,
        "title":"My key",
        "fingerprint":"01:23:45:67:89:dd:0a:06:a3:0b:6a:69:67:d2:5b:c7",
        "created_at":"2017-03-14T21:53:42-04:00"
      },
      {
        "id":5309,
        "title":"My other key",
        "fingerprint":"05:44:32:10:c7:5b:d2:67:69:6a:6b:69:67:d2:5b:c7",
        "created_at":"2017-06-21T08:07:32-04:00"
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <public-keys type="array">
      <public-key>
        <id type="integer">1234</id>
        <title>My key</title>
        <fingerprint>01:23:45:67:89:dd:0a:06:a3:0b:6a:69:67:d2:5b:c7</fingerprint>
        <created_at type="dateTime">2017-03-14T21:53:42-04:00</created_at>
      </public-key>
      <public-key>
        <id type="integer">5309</id>
        <title>My other key</title>
        <fingerprint>05:44:32:10:c7:5b:d2:67:69:6a:6b:69:67:d2:5b:c7</fingerprint>
        <created_at type="dateTime">2017-06-21T08:07:32-04:00</created_at>
      </public-key>
    </public-keys>
    

    Returns a list of all public keys for a user on the current site.

    HTTP Request

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

    Show a public key

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/public_keys/1234.json \
      -u YOUR_API_KEY:x 
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/public_keys/1234.xml \
      -u YOUR_API_KEY:x 
    

    Example Response

    {
      "id":1234,
      "title":"My key",
      "fingerprint":"01:23:45:67:89:dd:0a:06:a3:0b:6a:69:67:d2:5b:c7",
      "created_at":"2017-03-14T21:53:42-04:00"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <public-key>
      <id type="integer">1234</id>
      <title>My key</title>
      <fingerprint>01:23:45:67:89:dd:0a:06:a3:0b:6a:69:67:d2:5b:c7</fingerprint>
      <created_at type="dateTime">2017-03-14T21:53:42-04:00</created_at>
    </public-key>
    

    Returns a single public key.

    HTTP Request

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

    Create a public key

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/users/987/public_key.json \
      -u YOUR_API_KEY:x \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{
            "title": "My new key", 
            "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCnq8wc58VxUmBF75IIPrvol2Hc4+J1mrI6C+6xwlfv62n21ITeumZpMpR6UNIOjyo4bCC8/BZOsiAYn7UXmyYzrlIsX5IuSO1KvG+k+/vRBPexua1s3/kKWRGAloqNBsmoRTun5OgSMp++NaUTDJGRYenzgXKtCWXwGK5iQ0UCAvuhNDx+GhOcSVPzLweBx/h7Sy2EPZhFNf5Ex1fucAaBvxvKLyOqAieLzIIuyCCN5shqxXyH602QYg+JurTqYKB/FaCRA1+1w4uzxAAzaQuUyMS3clmySGiaq9LbvAIw0rItGU31AWyyaCuHmzI3642ShMDDS7tnfZQvWpoykcbF"
          }'
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/users/987/public_key.xml \
      -u YOUR_API_KEY:x \
      -X POST \
      -H 'Content-Type: application/xml' \
      -d '<public-key>
            <title>My new key</title>
            <public_key>ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCnq8wc58VxUmBF75IIPrvol2Hc4+J1mrI6C+6xwlfv62n21ITeumZpMpR6UNIOjyo4bCC8/BZOsiAYn7UXmyYzrlIsX5IuSO1KvG+k+/vRBPexua1s3/kKWRGAloqNBsmoRTun5OgSMp++NaUTDJGRYenzgXKtCWXwGK5iQ0UCAvuhNDx+GhOcSVPzLweBx/h7Sy2EPZhFNf5Ex1fucAaBvxvKLyOqAieLzIIuyCCN5shqxXyH602QYg+JurTqYKB/FaCRA1+1w4uzxAAzaQuUyMS3clmySGiaq9LbvAIw0rItGU31AWyyaCuHmzI3642ShMDDS7tnfZQvWpoykcbF</public_key>
          </public-key>'
    

    Example Response

    {
      "id":1234,
      "title":"My new key",
      "fingerprint":"01:23:45:67:89:dd:0a:06:a3:0b:6a:69:67:d2:5b:c7",
      "created_at":"2017-03-14T21:53:42-04:00"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <public-key>
      <id type="integer">1234</id>
      <title>My new key</title>
      <fingerprint>01:23:45:67:89:dd:0a:06:a3:0b:6a:69:67:d2:5b:c7</fingerprint>
      <created_at type="dateTime">2017-03-14T21:53:42-04:00</created_at>
    </public-key>
    

    Creates a new public key for a user on the current site.

    HTTP Request

    POST /users/:id/public_keys.(json|xml)

    Delete a public key

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/public_keys/1234.json \
      -u YOUR_API_KEY:x \
      -X DELETE
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/public_keys/1234.xml \
      -u YOUR_API_KEY:x \
      -X DELETE
    

    Example Response

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

    Deletes the specified public key.

    HTTP Request

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

    Groups

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

    The group object

    Attribute Description
    id integer Globally unique identifier of each group. Each group is given an ID automatically upon creation.
    name string Name of the group. This is how the group will be displayed on the site. Maximum of 50 characters.
    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.
    usernames string Usernames of the users that are in this group.
    admin_ids comma-separated integers IDs of the users that are in this group and are administrators of this group.

    List all groups

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/groups.json \
      -u YOUR_API_KEY:x 
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/groups.xml \
      -u YOUR_API_KEY:x 
    

    Example Response

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

    Returns a list of all groups on the current site.

    HTTP Request

    GET /groups.(json|xml)

    Show a group

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/groups/2.json \
      -u YOUR_API_KEY:x
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/groups/2.xml \
      -u YOUR_API_KEY:x
    

    Example Response

    {
      "id": 2,
      "name": "Operations",
      "notes": "Has access to Ops folders only",
      "user_ids": "2,9",
      "usernames": "stork,flynn",
      "admin_ids": []
    }
    
    <?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>
      <usernames>stork,flynn</usernames>
      <admin_ids type="array"/>
    </group>
    

    Returns a single group.

    HTTP Request

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

    Create a group

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/groups.json \
      -u YOUR_API_KEY:x \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{
            "name": "Chicago Office", 
            "user_ids": "3,7,9"
          }'
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/groups.xml \
      -u YOUR_API_KEY:x \
      -X POST \
      -H 'Content-Type: application/xml' \
      -d '<group>
            <name>Chicago Office</name>
            <user_ids>3,7,9</user_ids>
          </group>'
    

    Example Response

    {
      "id": 7,
      "name": "Chicago Office",
      "notes": "",
      "user_ids": "3,7,9",
      "usernames": "zaphod,ford,arthur",
      "admin_ids": []
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <group>
      <id type="integer">7</id>
      <name>Chicago Office</name>
      <notes></notes>
      <user_ids>3,7,9</user_ids>
      <usernames>zaphod,ford,arthur</usernames>
      <admin_ids type="array"/>
    </group>
    

    Creates a new group on the current site.

    HTTP Request

    POST /groups.(json|xml)

    Update a group

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/groups/12.json \
      -u YOUR_API_KEY:x \
      -X PUT \
      -H 'Content-Type: application/json' \
      -d '{"user_ids": "1841,2101,3001,3818,3297"}'
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/groups/12.xml \
      -u YOUR_API_KEY:x \
      -X PUT \
      -H 'Content-Type: application/xml' \
      -d '<group><user_ids>1841,2101,3001,3818,3297</user_ids></group>'
    

    Example Response

    {
      "id": 12,
      "name": "Remote",
      "notes": "",
      "user_ids": "1841,2101,3001,3818,3297",
      "usernames": "alpha,beta,gamma,delta,epsilon",
      "admin_ids": []
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <group>
      <id type="integer">12</id>
      <name>Remote</name>
      <notes></notes>
      <user_ids>1841,2101,3001,3818,3297</user_ids>
      <usernames>alpha,beta,gamma,delta,epsilon</usernames>
      <admin_ids type="array"/>
    </group>
    

    Updates the specified group.

    HTTP Request

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

    Delete a group

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/groups/2.json \
      -u YOUR_API_KEY:x \
      -X DELETE 
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/groups/2.xml \
      -u YOUR_API_KEY:x \
      -X DELETE 
    

    Example Response

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

    Deletes the specified group.

    HTTP Request

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

    Create a user in a group

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/groups/2345/users.json \
      -u YOUR_API_KEY:x \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{
            "user": {
              "username": "janesmith", 
              "email": "janesmith@example.com"
            }
          }'
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/groups/2345/users.xml \
      -u YOUR_API_KEY:x \
      -X POST \
      -H 'Content-Type: application/xml' \
      -d '<user>
            <username>janesmith</username>
            <email>janesmith@gmail.com</email>
          </user>'
    

    Example Response

    {
      "id": 77,
      "username": "janesmith",
      "authentication_method": "password",
      "last_login_at": null,
      "authenticate_until": null,
      "name": null,
      "email": "janesmith@example.com",
      "notes": null,
      "group_ids": "2345",
      "ftp_permission": true,
      "sftp_permission": true,
      "dav_permission": true,
      "restapi_permission": true,
      "attachments_permission": false,
      "self_managed": true,
      "require_password_change": false,
      "allowed_ips": null,
      "user_root": "",
      "time_zone": "Eastern Time (US & Canada)",
      "language": "",
      "ssl_required": "use_system_setting",
      "site_admin": false,
      "can_create_new_users": false,
      "last_protocol_cipher": null,
      "lockout_expires": null,
      "admin_group_ids": []
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <user>
      <id type="integer">77</id>
      <username>janesmith</username>
      <authentication_method type="symbol">password</authentication_method>
      <last_login_at nil="true"/>
      <authenticate_until nil="true"/>
      <name nil="true"/>
      <email>janesmith@example.com</email>
      <notes nil="true"/>
      <group_ids>2345</group_ids>
      <ftp_permission type="boolean">true</ftp_permission>
      <sftp_permission type="boolean">true</sftp_permission>
      <dav_permission type="boolean">true</dav_permission>
      <restapi_permission type="boolean">true</restapi_permission>
      <attachments_permission type="boolean">false</attachments_permission>
      <self_managed type="boolean">true</self_managed>
      <require_password_change type="boolean">false</require_password_change>
      <allowed_ips nil="true"/>
      <user_root></user_root>
      <time_zone>Eastern Time (US &amp; Canada)</time_zone>
      <language></language>
      <ssl_required type="symbol">use_system_setting</ssl_required>
      <site_admin type="boolean">false</site_admin>
      <can_create_new_users type="boolean">false</can_create_new_users>
      <last_protocol_cipher nil="true"/>
      <lockout_expires nil="true"/>
      <admin_group_ids type="array"/>
    </user>
    

    Creates a new user within a specified group. See the user object for the full list of attributes. Note that only the following attributes can be set via this endpoint: username, password, name, email, notes, require_password_change, user_root, group_ids, time_zone, language, authenticate_until.

    HTTP Request

    POST /groups/:group_id/users.(json|xml)

    Add a member

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/groups/2345/membersips/77.json \
      -u YOUR_API_KEY:x \
      -X PUT \
      -H 'Content-Type: application/json' \
      -d '{"membership": {"admin": "true"}}'
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/groups/2345/membersips/77.xml \
      -u YOUR_API_KEY:x \
      -X PUT \
      -H 'Content-Type: application/xml' \
      -d '<membership><admin>true</admin></membership>'
    

    Example Response

    {
      "id": 87654,
      "group_id": 2345,
      "user_id": 77,
      "admin": true
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <group-user>
      <id type="integer">87654</id>
      <group_id type="integer">2345</group_id>
      <user_id type="integer">77</user_id>
      <admin type="boolean">true</admin>
    </group-user>
    

    Adds a user to a group. By default, the member will not be an admin. If the user is already a member of the group, their attributes will be updated to match the request.

    HTTP Request

    PUT /groups/:group_id/memberships/:user_id.(json|xml)

    Returns a membership object with the following attributes:

    Attribute Description
    id integer Globally unique identifier for the membership.
    group_id integer ID of the group the membership is associated with.
    user_id integer ID of the user the membership is associated with.
    admin boolean Indicates whether the user is an administrator of the group.

    Update a member

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/groups/2345/membersips/77.json \
      -u YOUR_API_KEY:x \
      -X PATCH \
      -H 'Content-Type: application/json' \
      -d '{"membership": {"admin": "false"}}'
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/groups/2345/membersips/77.xml \
      -u YOUR_API_KEY:x \
      -X PATCH \
      -H 'Content-Type: application/xml' \
      -d '<membership><admin>false</admin></membership>'
    

    Example Response

    {
      "id": 87654,
      "group_id": 2345,
      "user_id": 77,
      "admin": false
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <group-user>
      <id type="integer">87654</id>
      <group_id type="integer">2345</group_id>
      <user_id type="integer">77</user_id>
      <admin type="boolean">false</admin>
    </group-user>
    

    Updates a user's group membership. No action will be taken if the user is not already in the group.

    HTTP Request

    PATCH /groups/:group_id/memberships/:user_id.(json|xml)

    Returns a membership object with the following attributes:

    Attribute Description
    id integer Globally unique identifier for the membership.
    group_id integer ID of the group the membership is associated with.
    user_id integer ID of the user the membership is associated with.
    admin boolean Indicates whether the user is an administrator of the group.

    Remove a member

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/groups/2345/membersips/77.json \
      -u YOUR_API_KEY:x \
      -X DELETE
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/groups/2345/membersips/77.xml \
      -u YOUR_API_KEY:x \
      -X DELETE
    

    Example Response

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

    Removes a user from a group. No action will be taken if the user is not already in the group.

    HTTP Request

    DELETE /groups/:group_id/memberships/:user_id.(json|xml)

    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.

    The permission object

    Attribute Description
    id integer Globally unique identifier of each permission. Each permission is given an ID automatically upon creation.
    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 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. Maximum of 50 characters.
    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.
    group_name string Name of the group, if group_id is set. This property is read-only.
    path string Folder path for the permission to apply to. This must be slash-delimited, but it must neither start nor end with a slash. Maximum of 5000 characters.
    permission enum Value must be set to full, readonly, writeonly, previewonly, or history, depending on the type of access to be granted by the Permission.
    recursive boolean If set to false, the permission will be non-recursive, and will not apply to subfolders of the folder specified by the path property. Default is true.

    List permissions

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/permissions.json \
      -u YOUR_API_KEY:x 
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/permissions.xml \
      -u YOUR_API_KEY:x 
    

    Example Response

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

    Returns a list of permissions on the current site. By default all permissions for the entire site are returned. When given a path parameter, then only permissions immediately relevant to the given path are returned. When using a path parameter, the result will include permissions on the current path and recursive permissions that are inherited from parent paths, except that lesser permissions will be excluded if a greater permission applies on the given path for a particular user or group.

    HTTP Request

    GET /permissions.(json|xml)

    Request URL Parameters

    Parameter Description
    path string Optional path to focus the result set on.

    Create a permission

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/permissions.json \
      -u YOUR_API_KEY:x \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{
            "path": "a/b/c/d", 
            "permission": "writeonly", 
            "user_id": "10"
          }'
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/permissions.xml \
      -u YOUR_API_KEY:x \
      -X POST \
      -H 'Content-Type: application/xml' \
      -d '<permission>
            <path>a/b/c/d</path>
            <permission>writeonly</permission>
            <user_id>10</user_id>
          </permission>'
    

    Example Response

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

    Creates a new permission record.

    HTTP Request

    POST /permissions.(json|xml)

    Delete a permission

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/permissions/3.json \
      -u YOUR_API_KEY:x \
      -X DELETE 
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/permissions/3.xml \
      -u YOUR_API_KEY:x \
      -X DELETE 
    

    Example Response

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

    Deletes the specified permission.

    HTTP Request

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

    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.

    The notification object

    Attribute Description
    id integer Globally unique identifier of each notification. Each notification is given an ID automatically upon creation.
    path string Folder path for notifications. This must be slash-delimited, but it must neither start nor end with a slash. Maximum of 5000 characters.
    user_id integer Unique identifier for the user being notified. Each user is given an ID automatically upon creation. You can look up user IDs by using the User resource of this REST API.
    username string 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. Maximum of 50 characters.
    send_interval string The send interval for notifications. Can be one of the following: five_minutes (default), fifteen_minutes, hourly, daily.
    unsubscribed boolean If true, the user has unsubscribed from receiving this notification. This property is read-only.

    List all notifications

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/notifications.json \
      -u YOUR_API_KEY:x
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/notifications.xml \
      -u YOUR_API_KEY:x
    

    Example Response

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

    Returns a list of all notifications on the current site.

    HTTP Request

    GET /notifications.(json|xml)

    Create a notification

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/notifications.json \
      -u YOUR_API_KEY:x \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{
            "path": "a/b/c/d", 
            "user_id": "10"
          }'
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/notifications.xml \
      -u YOUR_API_KEY:x \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '<notification>
            <path>a/b/c/d</path>
            <user_id>10</user_id>
          </notification>'
    

    Example Response

    {
      "id": "7",
      "path": "a/b/c/d",
      "user_id": "10",
      "username": "fred",
      "send_interval": "five_minutes",
      "unsubscribed": false
    }
    
    <notification>
      <id type="integer">7</id>
      <path>a/b/c/d</path>
      <user_id>10</user_id>
      <username>fred</username>
      <send_interval type="symbol">five_minutes</send_interval>
      <unsubscribed type="boolean">false</unsubscribed>
    </notification>
    

    Creates a new notification on the current site.

    HTTP Request

    POST /notifications.(json|xml)

    Delete a notification

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/notifications/7.json \
      -u YOUR_API_KEY:x \
      -X DELETE
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/notifications/7.xml \
      -u YOUR_API_KEY:x \
      -X DELETE
    

    Example Response

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

    Deletes the specified notification.

    HTTP Request

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

    History

    The History resource in the REST API allows you to obtain several different types of history records from your site.

    The history object

    Attribute Description
    id integer Globally unique identifier of each history entry.
    when datetime Date of the history entry.
    user_id integer ID of the user associated with the history entry.
    username string Username of the user associated with the history entry.
    action string Type of action that occurred. Will be one of the following: create, read, update, destroy, move, login, failedlogin, copy, user_create, user_destroy, group_create, group_destroy, permission_create, permission_destroy.
    failure_type string Type of failure that occurred, if any.
    path string Path of the file or folder associated with the history entry.
    source string Source path associated with the history entry.
    destination string Destination path associated with the history entry.
    targets object Object containing the target object(s) for user_create, user_destroy, group_create, group_destroy, permission_create, and permission_destroy actions.

    A user target will include an id and username. A group target will include an id and name. A permission target will include an id, permission, and a recursive parameter.
    ip string IP address associated with the history entry.
    interface string Interface associated with the history entry. Will be one of the following: web, ftp, robot, jsapi, restapi, sftp, dav.

    Retrieve site history

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/history.json \
      -u YOUR_API_KEY:x
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/history.xml \
      -u YOUR_API_KEY:x
    

    Example Response

    [
      {
        "id": 869831023,
        "when": "2015-09-19T22:30:20-04:00",
        "user_id": 12345,
        "username": "fred.admin",
        "action": "login",
        "ip": "172.19.113.171",
        "interface": "ftp"
      },
      {
        "id": 814350298,
        "when": "2015-06-25T14:32:20-04:00",
        "user_id": 12345,
        "username": "fred.admin",
        "action": "permission_create",
        "path": "Files for bob.user",
        "source": "Files for bob.user",
        "targets": {
          "user": {
            "id": 23451,
            "username": "bob.user"
          },
          "permission": {
            "id": 67543,
            "permission": "full",
            "recursive": true
          }
        },
        "ip": "172.19.113.171",
        "interface": "web"
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <history type="array">
      <event>
        <id type="integer">869831023</id>
        <when type="dateTime">2015-09-19T22:30:20-04:00</when>
        <user_id type="integer">12345</user_id>
        <username>fred.admin</username>
        <action>login</action>
        <ip>172.19.113.171</ip>
        <interface>ftp</interface>
      </event>
      <event>
        <id type="integer">814350298</id>
        <when type="dateTime">2015-06-25T14:32:20-04:00</when>
        <user_id type="integer">12345</user_id>
        <username>fred.admin</username>
        <action>permission_create</action>
        <path>Files for bob.user</path>
        <source>Files for bob.user</source>
        <targets>
          <user>
            <id type="integer">23451</id>
            <username>bob.user</username>
          </user>
          <permission>
            <id type="integer">67543</id>
            <permission>full</permission>
            <recursive type="boolean">true</recursive>
          </permission>
        </targets>
        <ip>172.19.113.171</ip>
        <interface>web</interface>
      </event>
    </history>
    

    Returns the entire history for the current site. The history starts with the most recent entries and proceeds back in time. There is a maximum number of records that will be returned with a single request (default 1000 or whatever value you provide as the per_page parameter, up to a maximum of 10,000).

    HTTP Request

    GET /history.(json|xml|html|xls|csv)

    Request URL Parameters

    Parameter Description
    page integer Optional page number of items to return in this request.
    per_page integer Optional requested number of items returned per request. Default: 1000, maximum: 10000. Leave blank for default (strongly recommended).
    start_at datetime Optional date and time in the history to start from.

    Retrieve login history

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/history/login.json \
      -u YOUR_API_KEY:x
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/history/login.xml \
      -u YOUR_API_KEY:x
    

    Example Response

    [
      {
        "id":904593281,
        "when":"2015-10-28T14:03:08-04:00",
        "user_id":54321,
        "username":"justice.london",
        "action":"login",
        "ip":"86.75.30.9",
        "interface":"web"
      },
      {
        "id":903766417,
        "when":"2015-10-27T15:06:43-04:00",
        "user_id":12345,
        "username":"fred.admin",
        "action":"login",
        "ip":"172.19.113.171",
        "interface":"web"
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <history type="array">
      <event>
        <id type="integer">904593281</id>
        <when type="dateTime">2015-10-28T14:03:08-04:00</when>
        <user_id type="integer">54321</user_id>
        <username>justice.london</username>
        <action>login</action>
        <ip>86.75.30.9</ip>
        <interface>web</interface>
      </event>
      <event>
        <id type="integer">903766417</id>
        <when type="dateTime">2015-10-27T15:06:43-04:00</when>
        <user_id type="integer">12345</user_id>
        <username>fred.admin</username>
        <action>login</action>
        <ip>172.19.113.171</ip>
        <interface>web</interface>
      </event>
    </history>
    

    Returns login history only. The history starts with the most recent entries and proceeds back in time. There is a maximum number of records that will be returned with a single request (default 1000 or whatever value you provide as the per_page parameter, up to a maximum of 10,000).

    HTTP Request

    GET /history/login.(json|xml|html|xls|csv)

    Request URL Parameters

    Parameter Description
    page integer Optional page number of items to return in this request.
    per_page integer Optional requested number of items returned per request. Default: 1000, maximum: 10000. Leave blank for default (strongly recommended).
    start_at datetime Optional date and time in the history to start from.

    Retrieve user history

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/history/users/54321.json \
      -u YOUR_API_KEY:x
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/history/users/54321.xml \
      -u YOUR_API_KEY:x
    

    Example Response

    [
      {
        "id":903767970,
        "when":"2015-10-27T15:09:55-04:00",
        "user_id":54321,
        "username":"justice.london",
        "action":"create",
        "path":"accounts.xls",
        "destination":"accounts.xls",
        "ip":"86.75.30.9",
        "interface":"ftp"
      },
      {
        "id":903766146,
        "when":"2015-10-27T15:05:55-04:00",
        "user_id":54321,
        "username":"justice.london",
        "action":"login",
        "ip":"86.75.30.9",
        "interface":"ftp"
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <history type="array">
      <event>
        <id type="integer">903767970</id>
        <when type="dateTime">2015-10-27T15:09:55-04:00</when>
        <user_id type="integer">54321</user_id>
        <username>justice.london</username>
        <action>create</action>
        <path>accounts.xls</path>
        <destination>accounts.xls</destination>
        <ip>86.75.30.9</ip>
        <interface>ftp</interface>
      </event>
      <event>
        <id type="integer">903766146</id>
        <when type="dateTime">2015-10-27T15:05:55-04:00</when>
        <user_id type="integer">54321</user_id>
        <username>justice.london</username>
        <action>login</action>
        <ip>86.75.30.9</ip>
        <interface>ftp</interface>
      </event>
    </history>
    

    Returns all history for a specific user. The history starts with the most recent entries and proceeds back in time. There is a maximum number of records that will be returned with a single request (default 1000 or whatever value you provide as the per_page parameter, up to a maximum of 10,000).

    HTTP Request

    GET /history/users/:user_id.(json|xml|html|xls|csv)

    Request URL Parameters

    Parameter Description
    page integer Optional page number of items to return in this request.
    per_page integer Optional requested number of items returned per request. Default: 1000, maximum: 10000. Leave blank for default (strongly recommended).
    start_at datetime Optional date and time in the history to start from.

    Retrieve folder history

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/history/folders/phun \
      -u YOUR_API_KEY:x \
      -H 'Accept: application/json'
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/history/folders/phun \
      -u YOUR_API_KEY:x \
      -H 'Accept: application/xml'
    

    Example Response

    [
      {
        "id":904650651,
        "when":"2015-10-28T15:50:52-04:00",
        "action":"read",
        "path":"phun/physics1.png",
        "source":"phun/physics1.png",
        "ip":"86.79.30.9",
        "interface":"web"
      },
      {
        "id":904649269,
        "when":"2015-10-28T15:48:24-04:00",
        "user_id":54321,
        "username":"justice.london",
        "action":"read",
        "path":"phun/physics1.png",
        "source":"phun/physics1.png",
        "ip":"86.75.30.9",
        "interface":"web"
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <history type="array">
      <event>
        <id type="integer">904650651</id>
        <when type="dateTime">2015-10-28T15:50:52-04:00</when>
        <action>read</action>
        <path>phun/physics1.png</path>
        <source>phun/physics1.png</source>
        <ip>86.75.30.9</ip>
        <interface>web</interface>
      </event>
      <event>
        <id type="integer">904649269</id>
        <when type="dateTime">2015-10-28T15:48:24-04:00</when>
        <user_id type="integer">54321</user_id>
        <username>justice.london</username>
        <action>read</action>
        <path>phun/physics1.png</path>
        <source>phun/physics1.png</source>
        <ip>86.75.30.9</ip>
        <interface>web</interface>
      </event>
    </history>
    

    Returns all history for a specific folder. The history starts with the most recent entries and proceeds back in time. There is a maximum number of records that will be returned with a single request (default 1000 or whatever value you provide as the per_page parameter, up to a maximum of 10,000).

    Note that this endpoint cannot accept a suffix to specify the return format (e.g. .json, .xml, .html, .xls, or .csv), so you should send an Accept header to specify the format. For more information about using the Accept header, see the Request and response format section under File and Folder Operations. For more information related to accessing folders, read the Specifying file path names section under File and Folder Operations.

    HTTP Request

    GET /history/folders/:path

    Request URL Parameters

    Parameter Description
    page integer Optional page number of items to return in this request.
    per_page integer Optional requested number of items returned per request. Default: 1000, maximum: 10000. Leave blank for default (strongly recommended).
    start_at datetime Optional date and time in the history to start from.

    Retrieve file history

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/history/files/archive.zip \
      -u YOUR_API_KEY:x \
      -H 'Accept: application/json'
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/history/files/archive.zip \
      -u YOUR_API_KEY:x \
      -H 'Accept: application/xml'
    

    Example Response

    [
      {
        "id":878672966,
        "when":"2015-09-30T18:58:39-04:00",
        "user_id":54321,
        "username":"justice.london",
        "action":"read",
        "path":"archive.zip",
        "source":"archive.zip",
        "ip":"86.75.30.9",
        "interface":"sftp"
      },
      {
        "id":878672238,
        "when":"2015-09-30T18:58:16-04:00",
        "user_id":12345,
        "username":"fred.admin",
        "action":"read",
         "path":"archive.zip",
        "source":"archive.zip",
        "ip":"172.19.113.171",
        "interface":"sftp"
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <history type="array">
      <event>
        <id type="integer">878672966</id>
        <when type="dateTime">2015-09-30T18:58:39-04:00</when>
        <user_id type="integer">54321</user_id>
        <username>justice.london</username>
        <action>read</action>
        <path>archive.zip</path>
        <source>archive.zip</source>
        <ip>86.75.30.9</ip>
        <interface>sftp</interface>
      </event>
      <event>
        <id type="integer">878672238</id>
        <when type="dateTime">2015-09-30T18:58:16-04:00</when>
        <user_id type="integer">12345</user_id>
        <username>fred.admin</username>
        <action>read</action>
        <path>archive.zip</path>
        <source>archive.zip</source>
        <ip>172.19.113.171</ip>
        <interface>sftp</interface>
      </event>
    </history>
    

    Returns all history for a specific file. The history starts with the most recent entries and proceeds back in time. There is a maximum number of records that will be returned with a single request (default 1000 or whatever value you provide as the per_page parameter, up to a maximum of 10,000).

    Note that this endpoint cannot accept a suffix to specify the return format (e.g. .json, .xml, .html, .xls, or .csv), so you should send an Accept header to specify the format. For more information about using the Accept header, see the Request and response format section under File and Folder Operations. For more information related to accessing folders, read the Specifying file path names section under File and Folder Operations.

    HTTP Request

    GET /history/files/:path

    Request URL Parameters

    Parameter Description
    page integer Optional page number of items to return in this request.
    per_page integer Optional requested number of items returned per request. Default: 1000, maximum: 10000. Leave blank for default (strongly recommended).
    start_at datetime Optional date and time in the history to start from.

    Bundles

    The Bundles resource in the REST API allows you to operate on QuickShare bundles. A bundle is a collection of one or more files that can be downloaded via a publicly accessible link. This resource supports listing, creating, showing, deleting, listing contents, and downloading bundles.

    The bundle object

    Attribute Description
    id integer Globally unique identifier of each bundle.
    code string Unique code string identifier for the bundle.
    url string Public sharing URL for the bundle.
    user_id integer ID of the user that created the bundle.
    created_at datetime Creation date of the bundle.
    paths array List of the paths associated with the bundle.
    password string Optional password to password-protect the bundle. This property is write-only. It cannot be retrieved via the API.

    List all bundles

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/bundles.json \
      -u YOUR_API_KEY:x 
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/bundles.xml \
      -u YOUR_API_KEY:x 
    

    Example Response

    [
      {
        "id":212228,
        "code":"4d3d3d3d3",
        "url":"https://site.brickftp.com/f/4d3d3d3d3",
        "user_id":12345,
        "created_at":"2015-10-14T12:52:25-04:00",
        "paths":[
          "accounts.xls"
        ]
      },
      {
        "id":212468,
        "code":"012345678",
        "url":"https://site.brickftp.com/f/012345678",
        "user_id":12345,
        "created_at":"2015-10-14T19:07:45-04:00",
        "paths":[
          "cloud/images",
          "cloud/documents",
          "backup.zip"
        ]
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <bundles type="array">
      <bundle>
        <id type="integer">212228</id>
        <code>4d3d3d3d3</code>
        <url>https://site.brickftp.com/f/4d3d3d3d3</url>
        <user_id type="integer">12345</user_id>
        <created_at type="dateTime">2015-10-14T12:52:25-04:00</created_at>
        <paths type="array">
          <path>accounts.xls</path>
        </paths>
      </bundle>
      <bundle>
        <id type="integer">212468</id>
        <code>012345678</code>
        <url>https://site.brickftp.com/f/012345678</url>
        <user_id type="integer">12345</user_id>
        <created_at type="dateTime">2015-10-14T19:07:45-04:00</created_at>
        <paths type="array">
          <path>cloud/images</path>
          <path>cloud/documents</path>
          <path>backup.zip</path>
        </paths>
      </bundle>
    </bundles>
    

    Returns a list of all bundles on the current site.

    HTTP Request

    GET /bundles.(json|xml)

    Show a bundle

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/bundles/212228.json \
      -u YOUR_API_KEY:x 
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/bundles/212228.xml \
      -u YOUR_API_KEY:x 
    

    Example Response

    {
      "id": 212228,
      "code": "4d3d3d3d3",
      "url":"https://site.brickftp.com/f/4d3d3d3d3",
      "user_id": 12345,
      "created_at": "2015-10-14T12:52:25-04:00",
      "paths": [
        "accounts.xls"
      ]
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <bundle>
      <id type="integer">212228</id>
      <code>4d3d3d3d3</code>
      <url>https://site.brickftp.com/f/4d3d3d3d3</url>
      <user_id type="integer">12345</user_id>
      <created_at type="dateTime">2015-10-14T12:52:25-04:00</created_at>
      <paths type="array">
        <path>accounts.xls</path>
      </paths>
    </bundle>
    

    Returns a single bundle.

    HTTP Request

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

    Create a bundle

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/bundles.json \
      -u YOUR_API_KEY:x \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{
            "paths": [
              "cloud/images", 
              "backup.zip"
            ],
            "password": "samplePassword"
          }'
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/bundles.xml \
      -u YOUR_API_KEY:x \
      -X POST \
      -H 'Content-Type: application/xml' \
      -d '<bundle>
            <paths>
              <path>cloud/images</path>
              <path>backup.zip</path>
            </paths>
            <password>samplePassword</password>
          </bundle>'
    

    Example Response

    {
      "id": 221260,
      "code": "a0b1c2d3e",
      "url":"https://site.brickftp.com/f/a0b1c2d3e",
      "user_id": null,
      "created_at": "2015-11-12T15:49:30-05:00",
      "paths": [
        "cloud/images",
        "backup.zip"
      ]
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <bundle>
      <id type="integer">221260</id>
      <code>a0b1c2d3e</code>
      <url>https://site.brickftp.com/f/a0b1c2d3e</url>
      <user_id nil="true"/>
      <created_at type="dateTime">2015-11-12T15:49:30-05:00</created_at>
      <paths type="array">
        <path>cloud/images</path>
        <path>backup.zip</path>
      </paths>
    </bundle>
    

    Creates a new bundle on the current site.

    HTTP Request

    POST /bundles.(json|xml)

    Delete a bundle

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/bundles/221260.json \
      -u YOUR_API_KEY:x \
      -X DELETE 
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/bundles/221260.xml \
      -u YOUR_API_KEY:x \
      -X DELETE 
    

    Example Response

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

    Deletes the specified bundle.

    HTTP Request

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

    List bundle contents

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/bundles/folders.json \
      -u YOUR_API_KEY:x \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{
            "code": "a0b1c2d3e",
            "host": "justin.brickftp.com",
            "password": "samplePassword"
          }'
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/bundles/folders.xml \
      -u YOUR_API_KEY:x \
      -X POST \
      -H 'Content-Type: application/xml' \
      -d '<bundle>
            <code>a0b1c2d3e</code>
            <host>justin.brickftp.com</host>
            <password>samplePassword</password>
          </bundle>'
    

    Example Response

    [
      {
        "path":"cloud",
        "type":"directory",
        "size":null,
        "crc32":null,
        "md5":null
      },
      {
        "path":"backup.zip",
        "type":"file",
        "size":209715200,
        "crc32":"674135a9",
        "md5":"3389a0b30e05ef6613ccbdae5d9ec0bd"
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <files type="array">
      <file>
        <path>cloud</path>
        <type>directory</type>
        <size nil="true"/>
        <crc32 nil="true"/>
        <md5 nil="true"/>
      </file>
      <file>
        <path>backup.zip</path>
        <type>file</type>
        <size type="integer">209715200</size>
        <crc32>674135a9</crc32>
        <md5>3389a0b30e05ef6613ccbdae5d9ec0bd</md5>
      </file>
    </files>
    

    Lists the contents of a bundle. When no path is specified, the contents of the root of the bundle will be listed. The contents of a subfolder can be listed by providing its path in the URL after /folders, for example: /bundles/folders/cloud/images. Alternatively, you can provide path as a parameter in the request body instead of in the URL.

    Note that if providing the path in the URL, you should send an Accept header to specify the format. For more information about using the Accept header, see the Request and response format section under File and Folder Operations. For more information related to specifying file paths, read the Specifying file path names section under File and Folder Operations. For details on the attributes in the response bodies from this endpoint, please see The file object.

    The password parameter is required only for bundles that are password-protected. If a bundle is password-protected and the password is missing or incorrect, an error message will specify that the correct password is required.

    HTTP Request

    POST /bundles/folders/:path

    POST /bundles/folders.(json|xml)

    Download a bundle

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/bundles/files.json \
      -u YOUR_API_KEY:x \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{
            "code": "a0b1c2d3e",
            "host": "justin.brickftp.com",
            "paths": [
              "cloud/images/image1.jpg",
              "backup.zip"
            ],
            "password": "samplePassword"
          }'
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/bundles/files.xml \
      -u YOUR_API_KEY:x \
      -X POST \
      -H 'Content-Type: application/xml' \
      -d '<bundle>
            <code>a0b1c2d3e</code>
            <host>justin.brickftp.com</host>
            <paths>
              <path>cloud/images/image1.jpg</path>
              <path>backup.zip</path>
            </paths>
            <password>samplePassword</password>
          </bundle>'
    

    Example Response

    [
      {
        "path":"cloud/images/image1.jpg",
        "type":"file",
        "size":842665,
        "crc32":"bb9d7277",
        "md5":"9a3ec51abac56e35d2865b376c9658ec",
        "download_uri":"https://s3.amazonaws.com/objects.brickftp.com/metadata/10099/2e2376c0-7527-0133-21fb-0a2d4abb99a7?AWSAccessKeyId=AKIAIEWLY3MN4YGZQOWA\u0026Signature=spXByI%2BBFThcB%2FwFkPUZcIXtRzE%3D\u0026Expires=1448404172\u0026response-content-disposition=attachment;%20filename=%22image1.jpg%22"
      },
      {
        "path":"backup.zip",
        "type":"file",
        "size":209715200,
        "crc32":"674135a9",
        "md5":"3389a0b30e05ef6613ccbdae5d9ec0bd",
        "download_uri":"https://s3.amazonaws.com/objects.brickftp.com/metadata/10099/dbf4f3d0-4a7a-0133-bd45-0ea6408b29c1?AWSAccessKeyId=AKIAIEWLY3MN4YGZQOWA\u0026Signature=ArRo7x7It2%2BQQwCmiapwTFAJBSE%3D\u0026Expires=1448404172\u0026response-content-disposition=attachment;%20filename=%22backup.zip%22"
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <files type="array">
      <file>
        <path>cloud/images/image1.jpg</path>
        <type>file</type>
        <size type="integer">842665</size>
        <crc32>bb9d7277</crc32>
        <md5>9a3ec51abac56e35d2865b376c9658ec</md5>
        <download_uri>https://s3.amazonaws.com/objects.brickftp.com/metadata/10099/2e2376c0-7527-0133-21fb-0a2d4abb99a7?AWSAccessKeyId=AKIAIEWLY3MN4YGZQOWA&amp;Signature=Y6jfiGgsqpuKdk3riXK1%2FqScIoc%3D&amp;Expires=1448404447&amp;response-content-disposition=attachment;%20filename=%22image1.jpg%22</download_uri>
      </file>
      <file>
        <path>backup.zip</path>
        <type>file</type>
        <size type="integer">209715200</size>
        <crc32>674135a9</crc32>
        <md5>3389a0b30e05ef6613ccbdae5d9ec0bd</md5>
        <download_uri>https://s3.amazonaws.com/objects.brickftp.com/metadata/10099/dbf4f3d0-4a7a-0133-bd45-0ea6408b29c1?AWSAccessKeyId=AKIAIEWLY3MN4YGZQOWA&amp;Signature=zXtt1jkk5Vq6mBKFSRQGa9i2S9c%3D&amp;Expires=1448404447&amp;response-content-disposition=attachment;%20filename=%22backup.zip%22</download_uri>
      </file>
    </files>
    

    Provides download URLs that will enable you to download the files in a bundle. The download URLs are direct URLs to Amazon S3 that have been signed by BrickFTP to provide temporary access to the files. The download links are valid for 3 minutes. For details on the attributes in the response bodies from this endpoint, please see The file object.

    The password parameter is required only for bundles that are password-protected. If a bundle is password-protected and the password is missing or incorrect, an error message will specify that the correct password is required.

    HTTP Request

    POST /bundles/files.(json|xml)

    Behaviors

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

    The behavior object

    Attribute Description
    id integer Globally unique identifier of each behavior.
    path string Folder path for behaviors. This must be slash-delimited, but it must neither start nor end with a slash. Maximum of 5000 characters.
    behavior string The behavior type. Can be one of the following: webhook, file_expiration, auto_encrypt, lock_subfolders.
    value array Array of values associated with the behavior.

    List all behaviors

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/behaviors.json \
      -u YOUR_API_KEY:x 
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/behaviors.xml \
      -u YOUR_API_KEY:x 
    

    Example Response

    [
      {
        "id": 38,
        "path":"Finance",
        "behavior":"webhook",
        "value":[
          "https://a.mywebhookhandler.com"
        ]
      },
      {
        "id": 39,
        "path":"cloud/images",
        "behavior":"webhook",
        "value":[
          "https://b.mywebhookhandler.com",
          "https://c.mywebhookhandler.com"
        ]
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <behaviors type="array">
      <behavior>
        <id type="integer">38</id>
        <path>Finance</path>
        <behavior>webhook</behavior>
        <value type="array">
          <value>https://a.mywebhookhandler.com</value>
        </value>
      </behavior>
      <behavior>
        <id type="integer">39</id>
        <path>cloud/images</path>
        <behavior>webhook</behavior>
        <value type="array">
          <value>https://b.mywebhookhandler.com</value>
          <value>https://c.mywebhookhandler.com</value>
        </value>
      </behavior>
    </behaviors>
    

    Returns a list of all behaviors on the current site.

    HTTP Request

    GET /behaviors.(json|xml)

    List behaviors for a folder

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/behaviors/folders/Incoming \
      -u YOUR_API_KEY:x \
      -H 'Accept: application/json'
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/behaviors/folders/Incoming \
      -u YOUR_API_KEY:x \
      -H 'Accept: application/xml'
    

    Example Response

    [
      {
        "id": 44,
        "path":"Incoming",
        "behavior":"webhook",
        "value":[
          "https://a.mywebhookhandler.com"
        ]
      },
      {
        "id": 45,
        "path":"Incoming",
        "behavior":"webhook",
        "value":[
          "https://b.mywebhookhandler.com"
        ]
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <behaviors type="array">
      <behavior>
        <path>Incoming</path>
        <behavior>webhook</behavior>
        <value type="array">
          <value>https://a.mywebhookhandler.com</value>
        </value>
      </behavior>
      <behavior>
        <path>Incoming</path>
        <behavior>webhook</behavior>
        <value type="array">
          <value>https://b.mywebhookhandler.com</value>
        </value>
      </behavior>
    </behaviors>
    

    Returns the behaviors that apply to the given path. By default, only behaviors applied directly on the the given path will be returned. If you would also like behaviors that are inherited from parent folders to be returned, the recursive query parameter can be passed in on the URL with the value of 1.

    Note that this endpoint cannot accept the .json or .xml suffix to specify the return format, so you should send an Accept header to specify the format. For more information about using the Accept header, read the Request and response format section under File and Folder Operations. For more information related to specifying paths, read the Specifying file path names section under File and Folder Operations.

    HTTP Request

    GET /behaviors/folders/:path

    Request URL Parameters

    Parameter Description
    recursive Optionally set to 1 to have response include behaviors inherited from parent folders.

    Show a behavior

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/behaviors/38.json \
      -u YOUR_API_KEY:x 
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/behaviors/38.xml \
      -u YOUR_API_KEY:x 
    

    Example Response

    {
      "id": 38,
      "path":"Finance",
      "behavior":"webhook",
      "value":[
        "https://a.mywebhookhandler.com"
      ]
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <behavior>
      <id type="integer">38</id>
      <path>Finance</path>
      <behavior>webhook</behavior>
      <value type="array">
        <value>https://a.mywebhookhandler.com</value>
      </value>
    </behavior>
    

    Returns a single behavior.

    HTTP Request

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

    Create a behavior

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/behaviors.json \
      -u YOUR_API_KEY:x \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{
            "path": "cloud/images",
            "behavior": "webhook", 
            "value": [
              "https://d.mywebhookhandler.com"
            ]
          }'
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/behaviors.xml \
      -u YOUR_API_KEY:x \
      -X POST \
      -H 'Content-Type: application/xml' \
      -d '<behavior>
            <path>cloud/images</path>
            <behavior>webhook</behavior>
            <value>
              <value>https://d.mywebhookhandler.com</value>
            </value>
          </behavior>'
    

    Example Response

    {
      "id": 39,
      "path":"cloud/images",
      "behavior":"webhook",
      "value":[
          "https://d.mywebhookhandler.com"
      ]
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <behavior>
      <id type="integer">39</id>
      <path>cloud/images</path>
      <behavior>webhook</behavior>
      <value type="array">
        <value>https://d.mywebhookhandler.com</value>
      </value>
    </behavior>
    

    Creates a new behavior.

    HTTP Request

    POST /behaviors.(json|xml)

    Update a behavior

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/behaviors/39.json \
      -u YOUR_API_KEY:x \
      -X PATCH \
      -H 'Content-Type: application/json' \
      -d '{
            "value": [
              "https://e.mywebhookhandler.com"
            ]
          }'
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/behaviors/39.xml \
      -u YOUR_API_KEY:x \
      -X PATCH \
      -H 'Content-Type: application/xml' \
      -d '<behavior>
            <value>
              <value>https://e.mywebhookhandler.com</value>
            </value>
          </behavior>'
    

    Example Response

    {
      "id": 39,
      "path":"cloud/images",
      "behavior":"webhook",
      "value":[
          "https://e.mywebhookhandler.com"
      ]
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <behavior>
      <id type="integer">39</id>
      <path>cloud/images</path>
      <behavior>webhook</behavior>
      <value type="array">
        <value>https://e.mywebhookhandler.com</value>
      </value>
    </behavior>
    

    Updates an existing behavior.

    HTTP Request

    PATCH /behaviors/:id.(json|xml)

    Delete a behavior

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/behaviors/39.json \
      -u YOUR_API_KEY:x \
      -X DELETE
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/behaviors/39.xml \
      -u YOUR_API_KEY:x \
      -X DELETE
    

    Example Response

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

    Deletes a behavior.

    HTTP Request

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

    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 the 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 (i.e. endpoints that begin with /files or /folders), the remainder 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, you will need to 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 (and other endpoints that include the path name directly, such as /history/files and /history/folders), 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.

    Valid Accept header values are as follows:

    application/json JSON
    application/xml XML
    text/html HTML (Only valid for /history/files and /history/folders)
    application/vnd.ms-excel XLS (Only valid for /history/files and /history/folders)
    text/csv CSV (Only valid for /history/files and /history/folders)

    The file/folder object

    Attribute Description
    id integer Globally unique identifier of each file.
    path string Full path of the file or folder. Maximum of 550 characters.
    display_name string Name of the file or folder without path.
    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.
    provided_mtime datetime Client-provided 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.
    region string The geographic region that a file is stored in.
    permissions string Your permissions on the file/folder. Will be one of the following: p (list/preview only), r (read-only), w (write-only), rw (read/write), rwd (read/write/delete).
    download_uri string URL to download the file, if requested.
    subfolders_locked? integer A value of 1 indicates that the Lock-subfolders setting is enabled on a folder.

    List folder contents

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/folders/Engineering%20Candidates/R%c3%a9sum%c3%a9s \
      -u YOUR_API_KEY:x \
      -H 'Accept: application/json'
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/folders/Engineering%20Candidates/R%c3%a9sum%c3%a9s \
      -u YOUR_API_KEY:x \
      -H 'Accept: application/xml'
    

    Example Response

    [
      {
        "id": 867530900,
        "path": "Engineering Candidates/R\u00e9sum\u00e9s/Needs Review",
        "display_name": "Needs Review",
        "type": "directory",
        "size": null,
        "mtime": "2014-05-15T20:26:18+00:00",
        "provided_mtime": "2014-05-15T20:26:26+00:00",
        "crc32": null,
        "md5": null,
        "permissions": "rwd",
        "subfolders_locked?": null
      },
      {
        "id": 113883112,
        "path": "Engineering Candidates/R\u00e9sum\u00e9s/John Smith.docx",
        "display_name": "John Smith.docx",
        "type": "file",
        "size": 61440,
        "mtime": "2014-05-15T18:34:51+00:00",
        "provided_mtime": "2014-05-15T18:34:51+00:00",
        "crc32": "f341cc60",
        "md5": "b67236f5bcd29d1307d574fb9fe585b5",
        "region": "us-east-1",
        "permissions": "rwd"
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <files type="array">
      <file>
        <id type="integer">867530900</id>
        <path>Engineering Candidates/Résumés/Needs Review</path>
        <display_name>Needs Review</display_name>
        <type>directory</type>
        <size nil="true"/>
        <mtime type="datetime">2014-05-15T20:26:18+00:00</mtime>
        <provided_mtime type="dateTime">2014-05-15T20:26:26+00:00</provided_mtime>
        <crc32 nil="true"/>
        <md5 nil="true"/>
        <permissions>rwd</permissions>
        <subfolders_locked? nil="true"/>
      </file>
      <file>
        <id type="integer">113883112</id>
        <path>Engineering Candidates/Résumés/John Smith.docx</path>
        <display_name>John Smith.docx</display_name>
        <type>file</type>
        <size type="integer">61440</size>
        <mtime type="datetime">2014-05-15T18:34:51+00:00</mtime>
        <provided_mtime type="datetime">2014-05-15T18:34:51+00:00</provided_mtime>
        <crc32>f341cc60</crc32>
        <md5>b67236f5bcd29d1307d574fb9fe585b5</md5>
        <region>us-east-1</region>
        <permissions>rwd</permissions>
      </file>
    </files>
    

    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.

    HTTP Request

    GET /folders/:path

    Optional Request URL Parameters

    Parameter Description
    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.

    Create a folder

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/folders/Images \
      -u YOUR_API_KEY:x \
      -X POST \
      -H 'Accept: application/json'
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/folders/Images \
      -u YOUR_API_KEY:x \
      -X POST \
      -H 'Accept: application/xml'
    

    Example Response

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

    Creates a folder.

    HTTP Request

    POST /folders/:path_and_folder_name

    Count folder contents recursively

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/folders/Images?action=count \
      -u YOUR_API_KEY:x \
      -H 'Accept: application/json'
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/folders/Images?action=count \
      -u YOUR_API_KEY:x \
      -H 'Accept: application/xml'
    

    Example Response

    {
      "type":"200-ok",
      "data":
      {
        "count":123
      }
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <result>
      <type>200-ok</type>
      <data>
        <count type="integer">123</count>
      </data>
    </result>
    

    Returns the combined total number of files and subfolders in a given folder recursively.

    HTTP Request

    GET /folders/:path_and_folder_name?action=count

    Count folder contents non-recursively

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/folders/Documents?action=count_nrs \
      -u YOUR_API_KEY:x \
      -H 'Accept: application/json'
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/folders/Documents?action=count_nrs \
      -u YOUR_API_KEY:x \
      -H 'Accept: application/xml'
    

    Example Response

    {
      "type":"200-ok",
      "data":
      {
        "count":
        {
          "files": 5,
          "folders": 10
        }
      }
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <result>
      <type>200-ok</type>
      <data>
        <count>
          <files type="integer">5</files>
          <folders type="integer">10</folders>
        </count>
      </data>
    </result>
    

    Returns the number of files and folders, separately, located inside a given folder (non-recursively).

    HTTP Request

    GET /folders/:path_and_folder_name?action=count_nrs

    Get folder size

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/folders/Documents?action=size \
      -u YOUR_API_KEY:x \
      -H 'Accept: application/json'
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/folders/Documents?action=size \
      -u YOUR_API_KEY:x \
      -H 'Accept: application/xml'
    

    Example Response

    {
      "type":"200-ok",
      "data":
      {
        "size": 12345
      }
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <result>
      <type>200-ok</type>
      <data>
        <size type="integer">12345</size>
      </data>
    </result>
    

    Returns the size (in bytes) of the specified folder, recursively.

    HTTP Request

    GET /folders/:path_and_folder_name?action=size

    Download a file

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/files/Engineering%20Candidates/John%20Smith.docx \
      -u YOUR_API_KEY:x \
      -H 'Accept: application/json'
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/files/Engineering%20Candidates/John%20Smith.docx \
      -u YOUR_API_KEY:x \
      -H 'Accept: application/xml'
    

    Example Response

    {
      "id": 4233161221,
      "path": "Engineering Candidates/John Smith.docx",
      "display_name": "John Smith.docx",
      "type": "file",
      "size": 61440,
      "mtime": "2014-05-15T18:34:51+00:00",
      "provided_mtime": "2014-05-15T18:34:51+00:00",
      "crc32": "f341cc60",
      "md5": "b67236f5bcd29d1307d574fb9fe585b5",
      "region": "us-east-1",
      "permissions": "rwd",
      "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>
      <id type="integer">4233161221</id>
      <path>Engineering Candidates/John Smith.docx</path>
      <display_name>John Smith.docx</display_name>
      <type>file</type>
      <size type="integer">61440</size>
      <mtime type="datetime">2014-05-15T18:34:51+00:00</mtime>
      <provided_mtime type="datetime">2014-05-15T18:34:51+00:00</provided_mtime>
      <crc32>f341cc60</crc32>
      <md5>b67236f5bcd29d1307d574fb9fe585b5</md5>
      <region>us-east-1</region>
      <permissions>rwd</permissions>
      <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>
    

    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 are 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_uri field to be omitted in the response and no download action to be logged.

    HTTP Request

    GET /files/:path_and_filename

    Request URL Parameters

    Parameter Description
    action Optionally set to stat to have the download_uri field omitted in the response and no download action logged.

    Move or rename a file or folder

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/folders/Engineering%20Candidates/John%20Smith.docx \
      -u YOUR_API_KEY:x \
      -X POST \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -d '{
            "move-destination": "/DESTINATION_PATH_AND_FILENAME.EXT"
          }'
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/folders/Engineering%20Candidates/John%20Smith.docx \
      -u YOUR_API_KEY:x \
      -X POST \
      -H 'Content-Type: application/xml' \
      -H 'Accept: application/xml' \
      -d '<file>
            <move-destination>/DESTINATION_PATH_AND_FILENAME.EXT</move-destination>
          </file>'
    

    Example Response

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

    Moves or renames a file or folder to the destination provided in the move-destination parameter in the request body. Note that a move/rename will fail if the destination already exists.

    HTTP Request

    POST /files/:source_path_and_filename

    Copy a file or folder

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/folders/Engineering%20Candidates/John%20Smith.docx \
      -u YOUR_API_KEY:x \
      -X POST \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -d '{
            "copy-destination": "/DESTINATION_PATH_AND_FILENAME.EXT"
          }'
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/folders/Engineering%20Candidates/John%20Smith.docx \
      -u YOUR_API_KEY:x \
      -X POST \
      -H 'Content-Type: application/xml' \
      -H 'Accept: application/xml' \
      -d '<file>
            <copy-destination>/DESTINATION_PATH_AND_FILENAME.EXT</copy-destination>
          </file>'
    

    Example Response

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

    Copies a file or folder to the destination provided in the copy-destination parameter in the request body. Note that a copy will fail if the destination already exists.

    Optionally, provide the parameter structure and set it to any value to only copy the folder structure without copying any files.

    HTTP Request

    POST /files/:source_path_and_filename

    Delete a file or folder

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/files/Engineering%20Candidates/John%20Smith.docx \
      -u YOUR_API_KEY:x \
      -X DELETE \
      -H 'Accept: application/json'
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/files/Engineering%20Candidates/John%20Smith.docx \
      -u YOUR_API_KEY:x \
      -X DELETE \
      -H 'Accept: application/xml'
    

    Example Response

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

    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.

    HTTP Request

    DELETE /files/:path_or_filename

    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. Start a new upload by sending a request to REST API to indicate intent to upload a file.
    2. Upload the file to the URL(s) provided by the REST API, possibly in parts via multiple uploads.
    3. Complete the upload by notifying the REST API that the file upload has completed.

    The upload object

    Attribute Description
    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.
    upload_uri string The URL where the file is uploaded to.
    partsize integer Recommended size of upload. When uploading file pieces, 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. 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.

    Starting a new upload

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/files/NewFile.txt \
      -u YOUR_API_KEY:x \
      -X POST \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -d '{
            "action": "put"
          }'
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/files/NewFile.txt \
      -u YOUR_API_KEY:x \
      -X POST \
      -H 'Content-Type: application/xml' \
      -H 'Accept: application/xml' \
      -d '<file>
            <action>put</action>
          </file>'
    

    Example Response

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

    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.

    HTTP Request

    POST /files/:path_and_filename

    Uploading the file or file parts

    Example Request

    curl "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" \
      --upload-file filename.ext
    

    At this point, you are to send a PUT request to the returned upload_uri with the file data, along with the headers and parameters provided to you from BrickFTP.

    The upload_uri link is signed by BrickFTP and must be used within 15 minutes. You will receive an HTTP 200 response with no body upon successful upload.

    Should you wish to upload the file in multiple parts (required if the file size exceeds 5 GB) you will need to request an additional upload URL for the next part.

    Requesting additional upload URLs

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/files/NewFile.txt \
      -u YOUR_API_KEY:x \
      -X POST \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -d '{
            "action": "put",
            "ref": "put-378670",
            "part": 2
          }'
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/files/NewFile.txt \
      -u YOUR_API_KEY:x \
      -X POST \
      -H 'Content-Type: application/xml' \
      -H 'Accept: application/xml' \
      -d '<file>
            <action>put</action>
            <ref>put-378670</ref>
            <part>2</part>
          </file>'
    

    Example Response

    {
      "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=2&uploadId=xQDI8q.aDdWdWIvSpRGLOFqnPQqJoMGZ88r9g_q7z2gW6U4rNZx8Zb_Wh9m07TDJM1x4rCTM18UCzdXaYjJu.SBH89LAiA4ye698TfMPyam4BO7ifs7HLuiBPrEW.zIz&X-Amz-Signature=57c440731898fb55c6866af734757185dbbccba7741259ade453c30120e32c6h",
      "partsize":5242880,
      "part_number":2,
      "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&X-Amz-Credential=AKIAIEWLY3MN4YGZQOWA%2F20140516%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20140516T221456Z&X-Amz-Expires=180&X-Amz-SignedHeaders=host&partNumber=2&uploadId=xQDI8q.aDdWdWIvSpRGLOFqnPQqJoMGZ88r9g_q7z2gW6U4rNZx8Zb_Wh9m07TDJM1x4rCTM18UCzdXaYjJu.SBH89LAiA4ye698TfMPyam4BO7ifs7HLuiBPrEW.zIz&X-Amz-Signature=57c440731898fb55c6866af734757185dbbccba7741259ade453c30120e32c6h</upload_uri>
      <partsize type="integer">5242880</partsize>
      <part_number type="integer">2</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>
    

    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.

    HTTP Request

    POST /files/:path_and_filename

    Completing an upload

    Example Request

    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/files/NewFile.txt \
      -u YOUR_API_KEY:x \
      -X POST \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -d '{
            "action": "end",
            "ref": "put-378670"
          }'
    
    curl https://SUBDOMAIN.brickftp.com/api/rest/v1/files/NewFile.txt \
      -u YOUR_API_KEY:x \
      -X POST \
      -H 'Content-Type: application/xml' \
      -H 'Accept: application/xml' \
      -d '<file>
            <action>end</action>
            <ref>put-378670</ref>
          </file>'
    

    Example Response

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

    After uploading the file to the file storage environment, 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.

    HTTP Request

    POST /files/:path_and_filename

    Errors

    Example Response: Invalid API key (401)

    {
      "error": "Unauthorized",
      "http-code": "401"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <error>
      <message>Unauthorized</message>
      <http-code>401</http-code>
    </error>
    

    Example Response: Invalid username or password (401)

    {
      "error": "invalid username or password",
      "http-code": "401",
      "errors": [
        {
          "type": "401-invalid-username-or-password",
          "message": "invalid username or password"
        }
      ]
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <error>
      <message>invalid username or password</message>
      <http-code>401</http-code>
      <errors type="array">
        <error>
          <type>401-invalid-username-or-password</type>
          <message>invalid username or password</message>
        </error>
      </errors>
    </error>
    

    Example Response: No permission to access resource (403)

    {
      "error": "Forbidden",
      "http-code": "403"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <error>
      <message>Forbidden</message>
      <http-code>403</http-code>
    </error>
    

    The BrickFTP API returns standard HTTP success (2xx) or error (4xx, 5xx) status codes. For errors, the response body will typically include additional information about the error.

    HTTP status codes

    Code Description
    200 - OK The request was successful.
    201 - Created The resource was successfully created.
    400 - Bad request Bad request.
    401 - Unauthorized Your API key or username/password is invalid.
    403 - Forbidden You don't have permission to access this resource.
    404 - Not found The resource does not exist.
    422 - Unprocessable entity The request could not be processed.
    50x - Server error An error occured with our API.