TOC Navbar
cURL cURL Ruby PHP
  • Introduction
  • Authentication with API Key
  • Authentication with a Session
  • Errors
  • Api Keys
  • Automations
  • Behaviors
  • Bundles
  • Certificates
  • Files/Folders
  • File Uploading
  • Groups
  • Histories
  • Locks
  • Notifications
  • Permissions
  • Public Keys
  • Remote Servers
  • Requests
  • Sessions
  • Site
  • Sso Strategies
  • Styles
  • Two Factor Authentication Methods
  • Users
  • Introduction

    Welcome to the Files.com API and SDK documentation! Our REST API and SDKs are designed for people who require the highest level of integration between Files.com and their own application, website, or database.

    The Files.com web interface, Desktop app, and FTP backend uses this exact same API, so everything you can do in the UI can also be accomplished using the API or with one of our SDKs.

    REST 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, PATCH, and DELETE.

    Per-Language SDKs

    SDKs in Ruby and PHP are available for download using the typical package manager for each language.

    It is our goal to create new language SDKs. Please reach out to us and let us know your language of choice, so we can prioritize getting you an SDK in your language.

    We already have plans to release SDKs in DotNet (C#), Elixir, Go, Java, Javascript/Node, and Python.

    OpenAPI (f/k/a Swagger) v2 Definition File

    Files.com also publishes a OpenAPI/Swagger v2 Definition File for the API. This swagger_doc.json file includes much of the information available on this documentation site in a machine-readable JSON format.

    The most common use of the OpenAPI definition file is in conjunction with API debugging tools like Postman.

    It can also be used to generate SDKs in languages that we don't support, but we'd prefer that you reach out to us if you find yourself in that situation. We'd much rather provide an officially supported SDK.

    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.

    Files.com also supports authentication with user sessions.

    Example of authenticating with an API key

    curl https://SUBDOMAIN.files.com/api/rest/v1/users.json \
      -u YOUR_API_KEY:x
    
    curl https://SUBDOMAIN.files.com/api/rest/v1/users.xml \
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    # Alternatively, you can specify the API key on a per-request basis in the final parameter to any method or initializer.
    Files::User.new(params, api_key: 'YOUR_API_KEY')
    
    \Files::configure(array('api_key' => 'YOUR_API_KEY'));
    
    # Alternatively, you can specify the API key on a per-request basis in the final parameter to any method or initializer.
    new \Files\User($params, array('api_key' => 'YOUR_API_KEY'));
    

    Make sure to replace YOUR_API_KEY with your API key.

    To use the API or SDKs with an API Key, first generate an API key from the web interface or via the API or an SDK.

    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.

    SDKs can be configured to use a single API key or you can pass the API key to each individual method on the SDK.

    Authentication with a Session

    You can also authenticate to the REST API or SDKs 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.

    Logging in

    Example Request

    curl https://SUBDOMAIN.files.com/api/rest/v1/sessions.json \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{"username": "motor", "password": "vroom"}'
    
    curl https://SUBDOMAIN.files.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.files.com/api/rest/v1/users.json \
      -H 'X-BrickAPI-Auth: 8c2e9f493dd8a857d5cdddbb7bf64ece0b7fb599'
    
    curl https://SUBDOMAIN.files.com/api/rest/v1/users.xml \
      -H 'X-BrickAPI-Auth: 8c2e9f493dd8a857d5cdddbb7bf64ece0b7fb599'
    

    Once a session has been created, you authenticate to the REST API by sending a header called X-BrickAPI-Auth set to the value of the session ID.

    Reauthentication

    Example Request

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

    If authenticating to the API via a 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.files.com/api/rest/v1/sessions.json \
      -H 'X-BrickAPI-Auth: 8c2e9f493dd8a857d5cdddbb7bf64ece0b7fb599' \
      -X DELETE
    
    curl https://SUBDOMAIN.files.com/api/rest/v1/sessions.xml \
      -H 'X-BrickAPI-Auth: 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 ID is passed in via the X-BrickAPI-Auth header, 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)

    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 Files.com API returns standard HTTP success (2xx) or error (4xx, 5xx) status codes.

    Some errors contain additional information in the response body. We have not been perfectly consistent with the formatting of these errors and will be standardizing them in the future.

    HTTP status codes

    Code Description
    200 - OK The request was successful.
    201 - Created The resource was successfully created.
    204 - No response The request was successful. The only difference between a 200 and 204 is the lack of response provided by that endpoint.
    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. Usually this is due to validation error of a parameter, but it could also be something like a username already taken, folder already existing, etc.
    5xx - Server error An error occured with our API. Wait some time and then try again. If you get a 500 repeatedly, it may be a bug. Please report it.

    Api Keys

    The ApiKeys resource in the REST API allows you to operate on ApiKeys.

    The ApiKey object

    Example ApiKey Object

    {
      "id": 1,
      "created_at": "2000-01-01 01:00:00 UTC",
      "expires_at": "2000-01-01 01:00:00 UTC",
      "key": "[key]",
      "name": "My Main API Key",
      "permission_set": "full",
      "platform": "win32",
      "user_id": 1
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <api-key>
      <id type="integer">1</id>
      <created_at type="dateTime">2000-01-01T01:00:00Z</created_at>
      <expires_at type="dateTime">2000-01-01T01:00:00Z</expires_at>
      <key>[key]</key>
      <name>My Main API Key</name>
      <permission_set>full</permission_set>
      <platform>win32</platform>
      <user_id type="integer">1</user_id>
    </api-key>
    
    
    Attribute Description
    id int64 API Key ID
    created_at date-time Time which API Key was created
    expires_at date-time API Key expiration date
    key string API Key actual key string
    name string Internal name for the API Key. For your use.
    permission_set string Permissions for this API Key. Will be either full or desktop_app. Keys with the desktop_app permission set only have the ability to do the functions provided in our Desktop App (File and Share Link operations.) We hope to offer additional permission sets in the future, such as for a Site Admin to give a key with no administrator privileges. If you have ideas for permission sets, please let us know.
    platform string If this API key represents a Desktop app, what platform was it created on?
    user_id int64 User ID for the owner of this API Key. May be blank for Site-wide API Keys.

    Show API Key

    Example Request

    curl https://app.files.com/api/rest/v1/api_keys/{id}.json \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/api_keys/{id}.xml ]
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::ApiKey.find(id)
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\ApiKey::find($id);
    

    Example Response

    {
      "id": 1,
      "created_at": "2000-01-01 01:00:00 UTC",
      "expires_at": "2000-01-01 01:00:00 UTC",
      "key": "[key]",
      "name": "My Main API Key",
      "permission_set": "full",
      "platform": "win32",
      "user_id": 1
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <api-key>
      <id type="integer">1</id>
      <created_at type="dateTime">2000-01-01T01:00:00Z</created_at>
      <expires_at type="dateTime">2000-01-01T01:00:00Z</expires_at>
      <key>[key]</key>
      <name>My Main API Key</name>
      <permission_set>full</permission_set>
      <platform>win32</platform>
      <user_id type="integer">1</user_id>
    </api-key>
    
    

    HTTPS Request

    GET /api_keys/{id}

    Request Parameters

    Parameter Description
    id int64 Required API Key ID.

    List site-wide API Keys

    Example Request

    curl https://app.files.com/api/rest/v1/site/api_keys.json \
      -H 'Content-Type: application/json' \
      -d '{"with_users":true}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/site/api_keys.xml ]
      -H 'Content-Type: application/xml' \
      -d '<api-keys>
           <with_users type="boolean">true</with_users>
         </api-keys>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Site.api_keys(
      with_users: true
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Site::apiKeys(array(
      'with_users' => true
    ));
    

    Example Response

    [
      {
        "id": 1,
        "created_at": "2000-01-01 01:00:00 UTC",
        "expires_at": "2000-01-01 01:00:00 UTC",
        "key": "[key]",
        "name": "My Main API Key",
        "permission_set": "full",
        "platform": "win32",
        "user_id": 1
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <api-keys type="array">
      <api-key>
        <id type="integer">1</id>
        <created_at type="dateTime">2000-01-01T01:00:00Z</created_at>
        <expires_at type="dateTime">2000-01-01T01:00:00Z</expires_at>
        <key>[key]</key>
        <name>My Main API Key</name>
        <permission_set>full</permission_set>
        <platform>win32</platform>
        <user_id type="integer">1</user_id>
      </api-key>
    </api-keys>
    
    

    HTTPS Request

    GET /site/api_keys

    Request Parameters

    Parameter Description
    with_users boolean Shows associated user ids if set.

    List user's API keys

    Example Request

    curl https://app.files.com/api/rest/v1/users/{id}/api_keys.json \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/users/{id}/api_keys.xml ]
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    user = Files::User.find(1)
    user.api_keys
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $user = \Files\User->find(1);
    $user->apiKeys();
    

    Example Response

    [
      {
        "id": 1,
        "created_at": "2000-01-01 01:00:00 UTC",
        "expires_at": "2000-01-01 01:00:00 UTC",
        "key": "[key]",
        "name": "My Main API Key",
        "permission_set": "full",
        "platform": "win32",
        "user_id": 1
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <api-keys type="array">
      <api-key>
        <id type="integer">1</id>
        <created_at type="dateTime">2000-01-01T01:00:00Z</created_at>
        <expires_at type="dateTime">2000-01-01T01:00:00Z</expires_at>
        <key>[key]</key>
        <name>My Main API Key</name>
        <permission_set>full</permission_set>
        <platform>win32</platform>
        <user_id type="integer">1</user_id>
      </api-key>
    </api-keys>
    
    

    HTTPS Request

    GET /users/{id}/api_keys

    Request Parameters

    Parameter Description
    id int64 Required User ID.

    List current user's API Keys

    Example Request

    curl https://app.files.com/api/rest/v1/user/api_keys.json \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/user/api_keys.xml ]
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::User.api_keys
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\User::apiKeys();
    

    Example Response

    [
      {
        "id": 1,
        "created_at": "2000-01-01 01:00:00 UTC",
        "expires_at": "2000-01-01 01:00:00 UTC",
        "key": "[key]",
        "name": "My Main API Key",
        "permission_set": "full",
        "platform": "win32",
        "user_id": 1
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <api-keys type="array">
      <api-key>
        <id type="integer">1</id>
        <created_at type="dateTime">2000-01-01T01:00:00Z</created_at>
        <expires_at type="dateTime">2000-01-01T01:00:00Z</expires_at>
        <key>[key]</key>
        <name>My Main API Key</name>
        <permission_set>full</permission_set>
        <platform>win32</platform>
        <user_id type="integer">1</user_id>
      </api-key>
    </api-keys>
    
    

    HTTPS Request

    GET /user/api_keys

    Create API key for user

    Example Request

    curl https://app.files.com/api/rest/v1/users/{id}/api_keys.json \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{"name":"API Key Name","permission_set":"full","expires_at":"2000-01-01 01:00:00 UTC"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/users/{id}/api_keys.xml ]
      -X POST \
      -H 'Content-Type: application/xml' \
      -d '<api-key>
           <name>API Key Name</name>
           <permission_set>full</permission_set>
           <expires_at type="dateTime">2000-01-01T01:00:00Z</expires_at>
         </api-key>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    user = Files::User.find(1)
    user.create_api_key(
      name: "API Key Name",
      permission_set: "full",
      expires_at: "2000-01-01 01:00:00 UTC"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $user = \Files\User->find(1);
    $user->createApiKey(array(
      'name' => "API Key Name", 
      'permission_set' => "full", 
      'expires_at' => "2000-01-01 01:00:00 UTC"
    ));
    

    Example Response

    {
      "id": 1,
      "created_at": "2000-01-01 01:00:00 UTC",
      "expires_at": "2000-01-01 01:00:00 UTC",
      "key": "[key]",
      "name": "My Main API Key",
      "permission_set": "full",
      "platform": "win32",
      "user_id": 1
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <api-key>
      <id type="integer">1</id>
      <created_at type="dateTime">2000-01-01T01:00:00Z</created_at>
      <expires_at type="dateTime">2000-01-01T01:00:00Z</expires_at>
      <key>[key]</key>
      <name>My Main API Key</name>
      <permission_set>full</permission_set>
      <platform>win32</platform>
      <user_id type="integer">1</user_id>
    </api-key>
    
    

    HTTPS Request

    POST /users/{id}/api_keys

    Request Parameters

    Parameter Description
    id int64 Required User ID.
    name string Required Public name for this API key.
    permission_set string Leave blank, or set to desktop_app to restrict the key to only desktop app functions.
    expires_at string Have the key expire at this date/time.

    Create site-wide API Key

    Example Request

    curl https://app.files.com/api/rest/v1/site/api_keys.json \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{"name":"API Key Name","permission_set":"full","expires_at":"2000-01-01 01:00:00 UTC"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/site/api_keys.xml ]
      -X POST \
      -H 'Content-Type: application/xml' \
      -d '<api-key>
           <name>API Key Name</name>
           <permission_set>full</permission_set>
           <expires_at type="dateTime">2000-01-01T01:00:00Z</expires_at>
         </api-key>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Site.create_api_key(
      name: "API Key Name", 
      permission_set: "full", 
      expires_at: "2000-01-01 01:00:00 UTC"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Site::createApiKey(array(
      'name' => "API Key Name", 
      'permission_set' => "full", 
      'expires_at' => "2000-01-01 01:00:00 UTC"
    ));
    

    Example Response

    {
      "id": 1,
      "created_at": "2000-01-01 01:00:00 UTC",
      "expires_at": "2000-01-01 01:00:00 UTC",
      "key": "[key]",
      "name": "My Main API Key",
      "permission_set": "full",
      "platform": "win32",
      "user_id": 1
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <api-key>
      <id type="integer">1</id>
      <created_at type="dateTime">2000-01-01T01:00:00Z</created_at>
      <expires_at type="dateTime">2000-01-01T01:00:00Z</expires_at>
      <key>[key]</key>
      <name>My Main API Key</name>
      <permission_set>full</permission_set>
      <platform>win32</platform>
      <user_id type="integer">1</user_id>
    </api-key>
    
    

    HTTPS Request

    POST /site/api_keys

    Request Parameters

    Parameter Description
    name string Required Internal name of the site-wide API key.
    permission_set string Leave blank, or set to desktop_app to restrict the key to only desktop app functions.
    expires_at string Have the key expire at this date/time.

    Create API Key for current user

    Example Request

    curl https://app.files.com/api/rest/v1/user/api_keys.json \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{"name":"My Primary API Key","permission_set":"full","expires_at":"2000-01-01 01:00:00 UTC"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/user/api_keys.xml ]
      -X POST \
      -H 'Content-Type: application/xml' \
      -d '<api-key>
           <name>My Primary API Key</name>
           <permission_set>full</permission_set>
           <expires_at type="dateTime">2000-01-01T01:00:00Z</expires_at>
         </api-key>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::User.create_api_key(
      name: "My Primary API Key", 
      permission_set: "full", 
      expires_at: "2000-01-01 01:00:00 UTC"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\User::createApiKey(array(
      'name' => "My Primary API Key", 
      'permission_set' => "full", 
      'expires_at' => "2000-01-01 01:00:00 UTC"
    ));
    

    Example Response

    {
      "id": 1,
      "created_at": "2000-01-01 01:00:00 UTC",
      "expires_at": "2000-01-01 01:00:00 UTC",
      "key": "[key]",
      "name": "My Main API Key",
      "permission_set": "full",
      "platform": "win32",
      "user_id": 1
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <api-key>
      <id type="integer">1</id>
      <created_at type="dateTime">2000-01-01T01:00:00Z</created_at>
      <expires_at type="dateTime">2000-01-01T01:00:00Z</expires_at>
      <key>[key]</key>
      <name>My Main API Key</name>
      <permission_set>full</permission_set>
      <platform>win32</platform>
      <user_id type="integer">1</user_id>
    </api-key>
    
    

    HTTPS Request

    POST /user/api_keys

    Request Parameters

    Parameter Description
    name string Required Internal name for key. For your reference only.
    permission_set string Leave blank, or set to desktop_app to restrict the key to only desktop app functions.
    expires_at string Have the key expire at this date/time.

    Update API Key

    Example Request

    curl https://app.files.com/api/rest/v1/api_keys/{id}.json \
      -X PATCH \
      -H 'Content-Type: application/json' \
      -d '{"name":"My Key","permission_set":"full","expires_at":"2000-01-01 01:00:00 UTC"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/api_keys/{id}.xml ]
      -X PATCH \
      -H 'Content-Type: application/xml' \
      -d '<api-key>
           <name>My Key</name>
           <permission_set>full</permission_set>
           <expires_at type="dateTime">2000-01-01T01:00:00Z</expires_at>
         </api-key>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    api_key = Files::ApiKey.find(1)
    api_key.update(
      name: "My Key",
      permission_set: "full",
      expires_at: "2000-01-01 01:00:00 UTC"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $api_key = \Files\ApiKey->find(1);
    $api_key->update(array(
      'name' => "My Key", 
      'permission_set' => "full", 
      'expires_at' => "2000-01-01 01:00:00 UTC"
    ));
    

    Example Response

    {
      "id": 1,
      "created_at": "2000-01-01 01:00:00 UTC",
      "expires_at": "2000-01-01 01:00:00 UTC",
      "key": "[key]",
      "name": "My Main API Key",
      "permission_set": "full",
      "platform": "win32",
      "user_id": 1
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <api-key>
      <id type="integer">1</id>
      <created_at type="dateTime">2000-01-01T01:00:00Z</created_at>
      <expires_at type="dateTime">2000-01-01T01:00:00Z</expires_at>
      <key>[key]</key>
      <name>My Main API Key</name>
      <permission_set>full</permission_set>
      <platform>win32</platform>
      <user_id type="integer">1</user_id>
    </api-key>
    
    

    HTTPS Request

    PATCH /api_keys/{id}

    Request Parameters

    Parameter Description
    id int64 Required API Key ID.
    name string Internal name for key. For your reference only.
    permission_set string Leave blank, or set to 'desktop_app' to restrict the key to only desktop app functions.
    expires_at string Have the key expire at this date/time.

    Update current API key. (Requires current API connection to be using an API key.)

    Example Request

    curl https://app.files.com/api/rest/v1/api_key.json \
      -X PATCH \
      -H 'Content-Type: application/json' \
      -d '{"name":"My Key","permission_set":"full","expires_at":"2000-01-01 01:00:00 UTC"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/api_key.xml ]
      -X PATCH \
      -H 'Content-Type: application/xml' \
      -d '<api-key>
           <name>My Key</name>
           <permission_set>full</permission_set>
           <expires_at type="dateTime">2000-01-01T01:00:00Z</expires_at>
         </api-key>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::ApiKey.update(
      name: "My Key", 
      permission_set: "full", 
      expires_at: "2000-01-01 01:00:00 UTC"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\ApiKey::update(array(
      'name' => "My Key", 
      'permission_set' => "full", 
      'expires_at' => "2000-01-01 01:00:00 UTC"
    ));
    

    Example Response

    {
      "id": 1,
      "created_at": "2000-01-01 01:00:00 UTC",
      "expires_at": "2000-01-01 01:00:00 UTC",
      "key": "[key]",
      "name": "My Main API Key",
      "permission_set": "full",
      "platform": "win32",
      "user_id": 1
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <api-key>
      <id type="integer">1</id>
      <created_at type="dateTime">2000-01-01T01:00:00Z</created_at>
      <expires_at type="dateTime">2000-01-01T01:00:00Z</expires_at>
      <key>[key]</key>
      <name>My Main API Key</name>
      <permission_set>full</permission_set>
      <platform>win32</platform>
      <user_id type="integer">1</user_id>
    </api-key>
    
    

    HTTPS Request

    PATCH /api_key

    Request Parameters

    Parameter Description
    name string Internal name for key. For your reference only.
    permission_set string Leave blank, or set to desktop_app to restrict the key to only desktop app functions.
    expires_at string Have the key expire at this date/time.

    Delete API Key

    Example Request

    curl https://app.files.com/api/rest/v1/api_keys/{id}.json \
      -X DELETE \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/api_keys/{id}.xml ]
      -X DELETE \
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    api_key = Files::ApiKey.find(1)
    api_key.delete
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $api_key = \Files\ApiKey->find(1);
    $api_key->delete();
    

    Example Response

    No response.
    
    No response.
    

    HTTPS Request

    DELETE /api_keys/{id}

    Request Parameters

    Parameter Description
    id int64 Required API Key ID.

    Delete current API key. (Requires current API connection to be using an API key.)

    Example Request

    curl https://app.files.com/api/rest/v1/api_key.json \
      -X DELETE \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/api_key.xml ]
      -X DELETE \
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::ApiKey.delete
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\ApiKey::delete();
    

    Example Response

    No response.
    
    No response.
    

    HTTPS Request

    DELETE /api_key

    Automations

    The Automations resource in the REST API allows you to operate on Automations. Automations allow you to automate workflows on your Files.com site.

    Automations are different from Behaviors because Behaviors are associated with a current folder, while Automations apply across your entire site. Although Automations may have a Path specified, it can be a glob (which includes wildcards), which affects multiple folders. Additionally, paths in Automations can refer to folders which don't yet exist.

    Automations are never removed when folders are removed, while Behaviors are removed when the associated folder is removed.

    Automation Types

    There are currently three types of automations: Create Folder, Request File, and Request Move.

    Create Folder Automation

    The Create Folder automation creates folders on a schedule.

    Example Use case: Our business files sales tax for each division in 11 states every quarter. I want to create the folders where those sales tax forms and data will be collected.

    I could create a Create Folder automation as follows:

    Request File Automation

    The Request File automation requests a file (optionally from a specific user) if it does not exist.

    Example Use case: Continuing our Sales Tax example from above, once the folders are created for the 11 states, our Bookkeeper needs to upload a .xlsx file containing the sales records for each state.

    We can create a Request File automation as follows:

    Note that the %p1, %p2 amd %p3 are references back into the folder hierarchy (parent 1, parent 2, etc), so that the file will be named with the state name and the quarter name in the file. Example: SalesByState-NV-2017-Quarter-ending-Dec-31.xlsx

    Now, let's say that our Tax Accountant is in charge of filing the actual state tax return once the Excel doc is completed by the Bookkeeper. We can create another Automation to let him know when it's his turn to operate:

    So the accountant will take the excel from the bookkeeper, generate the state tax return, and then upload it as a PDF, ready for the CFO to sign. How does the CFO know when to sign? You guessed it, another Automation will let him know when it's ready:

    This Automation looks in every nested subfolder of AcccountingAndTax (that's the /**/ in the path). And it looks for any filename containing the filename string -Unsigned-. That's the cue to the CFO that something needs his signature.

    Rather than specifying the exact destination filename, we can specify a Destination Replace From and To in order to generate the new filename from the old filename.

    So if StateSalesTaxReturn-Unsigned-NV-2017-q4.pdf is uploaded, this Automation will trigger and expect the file StateSalesTaxReturn-Signed-NV-2017-q4.pdf from the CFO.

    You could then put in place another rule for the Tax Accountant or Bookkeeper to go do the actual filing once a signature is in place.

    Request Move Automation

    The Request Move automation requests that a file be moved. This is an alternate way to implement approval workflows.

    A variant of the Request File automation, this Automation creates requests that a user or group move a file, presumably indicating that they've taken some action on it.

    Example Use case: Action Verb uses Files.com to collect invoices from its Contractors, who upload new invoices into their own folder structure that only they have permissions to. That structure looks like this:

    The contractor has full permissions to the New/ folder, but only read-only permissions to Paid/. This allows them to upload and update new invoices, but only view invoices that are already paid. (Cool!)

    But, as we grow to dozens of contractors, it becomes a tough task for Accounts Payable to check all the New folders daily.

    To ensure Contractors get paid timely, we might set up Request Move automation:

    Help us build the future of Automations

    Do you have an idea for something that would work well as a Files.com Automation? Let us know! We are actively improving the types of automations offered on our platform.

    The Automation object

    Example Automation Object

    {
      "id": 1,
      "automation": "create_folder",
      "source": "",
      "destination": "",
      "destination_replace_from": "",
      "destination_replace_to": "",
      "interval": "week",
      "next_process_on": "2020-01-01",
      "path": "",
      "realtime": true,
      "user_id": 1,
      "user_ids": [
    
      ],
      "group_ids": [
    
      ]
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <automation>
      <id type="integer">1</id>
      <automation>create_folder</automation>
      <source></source>
      <destination></destination>
      <destination_replace_from></destination_replace_from>
      <destination_replace_to></destination_replace_to>
      <interval>week</interval>
      <next_process_on>2020-01-01</next_process_on>
      <path></path>
      <realtime type="boolean">true</realtime>
      <user_id type="integer">1</user_id>
      <user_ids type="array"/>
      <group_ids type="array"/>
    </automation>
    
    
    Attribute Description
    id int64 Automation ID
    automation string Automation type. One of: create_folder, request_file, request_move
    source string Source Path
    destination string Destination Path
    destination_replace_from string If set, this string in the destination path will be replaced with the value in destination_replace_to.
    destination_replace_to string If set, this string will replace the value destination_replace_from in the destination filename. You can use special patterns here.
    interval string How often to run this automation? One of: day, week, week_end, month, month_end, quarter, quarter_end, year, year_end
    next_process_on string Date this automation will next run.
    path string Path on which this Automation runs. Supports globs. This must be slash-delimited, but it must neither start nor end with a slash. Maximum of 5000 characters.
    realtime boolean Does this automation run in real time? This is a read-only property based on automation type.
    user_id int64 User ID of the Automation's creator.
    user_ids array IDs of Users for the Automation (i.e. who to Request File from)
    group_ids array IDs of Groups for the Automation (i.e. who to Request File from)

    List Automations

    Example Request

    curl https://app.files.com/api/rest/v1/automations.json \
      -H 'Content-Type: application/json' \
      -d '{"automation":"create_folder"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/automations.xml ]
      -H 'Content-Type: application/xml' \
      -d '<automations>
           <automation>create_folder</automation>
         </automations>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Automation.list(
      automation: "create_folder"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Automation::list(array(
      'automation' => "create_folder"
    ));
    

    Example Response

    [
      {
        "id": 1,
        "automation": "create_folder",
        "source": "",
        "destination": "",
        "destination_replace_from": "",
        "destination_replace_to": "",
        "interval": "week",
        "next_process_on": "2020-01-01",
        "path": "",
        "realtime": true,
        "user_id": 1,
        "user_ids": [
    
        ],
        "group_ids": [
    
        ]
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <automations type="array">
      <automation>
        <id type="integer">1</id>
        <automation>create_folder</automation>
        <source></source>
        <destination></destination>
        <destination_replace_from></destination_replace_from>
        <destination_replace_to></destination_replace_to>
        <interval>week</interval>
        <next_process_on>2020-01-01</next_process_on>
        <path></path>
        <realtime type="boolean">true</realtime>
        <user_id type="integer">1</user_id>
        <user_ids type="array"/>
        <group_ids type="array"/>
      </automation>
    </automations>
    
    

    HTTPS Request

    GET /automations

    Request Parameters

    Parameter Description
    automation string Type of automation to filter by.

    Show Automation

    Example Request

    curl https://app.files.com/api/rest/v1/automations/{id}.json \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/automations/{id}.xml ]
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Automation.find(id)
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Automation::find($id);
    

    Example Response

    {
      "id": 1,
      "automation": "create_folder",
      "source": "",
      "destination": "",
      "destination_replace_from": "",
      "destination_replace_to": "",
      "interval": "week",
      "next_process_on": "2020-01-01",
      "path": "",
      "realtime": true,
      "user_id": 1,
      "user_ids": [
    
      ],
      "group_ids": [
    
      ]
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <automation>
      <id type="integer">1</id>
      <automation>create_folder</automation>
      <source></source>
      <destination></destination>
      <destination_replace_from></destination_replace_from>
      <destination_replace_to></destination_replace_to>
      <interval>week</interval>
      <next_process_on>2020-01-01</next_process_on>
      <path></path>
      <realtime type="boolean">true</realtime>
      <user_id type="integer">1</user_id>
      <user_ids type="array"/>
      <group_ids type="array"/>
    </automation>
    
    

    HTTPS Request

    GET /automations/{id}

    Request Parameters

    Parameter Description
    id int64 Required Automation ID

    Create Automation

    Example Request

    curl https://app.files.com/api/rest/v1/automations.json \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{"automation":"create_folder","source":"source","destination":"destination","interval":"year"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/automations.xml ]
      -X POST \
      -H 'Content-Type: application/xml' \
      -d '<automation>
           <automation>create_folder</automation>
           <source>source</source>
           <destination>destination</destination>
           <interval>year</interval>
         </automation>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Automation.create(
      automation: "create_folder", 
      source: "source", 
      destination: "destination", 
      interval: "year"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Automation::create(array(
      'automation' => "create_folder", 
      'source' => "source", 
      'destination' => "destination", 
      'interval' => "year"
    ));
    

    Example Response

    {
      "id": 1,
      "automation": "create_folder",
      "source": "",
      "destination": "",
      "destination_replace_from": "",
      "destination_replace_to": "",
      "interval": "week",
      "next_process_on": "2020-01-01",
      "path": "",
      "realtime": true,
      "user_id": 1,
      "user_ids": [
    
      ],
      "group_ids": [
    
      ]
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <automation>
      <id type="integer">1</id>
      <automation>create_folder</automation>
      <source></source>
      <destination></destination>
      <destination_replace_from></destination_replace_from>
      <destination_replace_to></destination_replace_to>
      <interval>week</interval>
      <next_process_on>2020-01-01</next_process_on>
      <path></path>
      <realtime type="boolean">true</realtime>
      <user_id type="integer">1</user_id>
      <user_ids type="array"/>
      <group_ids type="array"/>
    </automation>
    
    

    HTTPS Request

    POST /automations

    Request Parameters

    Parameter Description
    automation string Required Type of automation. One of: create_folder, request_file, request_move
    source string Source Path
    destination string Destination Path
    destination_replace_from string If set, this string in the destination path will be replaced with the value in destination_replace_to.
    destination_replace_to string If set, this string will replace the value destination_replace_from in the destination filename. You can use special patterns here.
    interval string How often to run this automation? One of: day, week, week_end, month, month_end, quarter, quarter_end, year, year_end
    path string Path on which this Automation runs. Supports globs.
    user_ids string A list of user IDs the automation is associated with. If sent as a string, it should be comma-delimited.
    group_ids string A list of group IDs the automation is associated with. If sent as a string, it should be comma-delimited.

    Update Automation

    Example Request

    curl https://app.files.com/api/rest/v1/automations/{id}.json \
      -X PATCH \
      -H 'Content-Type: application/json' \
      -d '{"automation":"create_folder","source":"source","destination":"destination","interval":"year"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/automations/{id}.xml ]
      -X PATCH \
      -H 'Content-Type: application/xml' \
      -d '<automation>
           <automation>create_folder</automation>
           <source>source</source>
           <destination>destination</destination>
           <interval>year</interval>
         </automation>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    automation = Files::Automation.find(1)
    automation.update(
      automation: "create_folder",
      source: "source",
      destination: "destination",
      interval: "year"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $automation = \Files\Automation->find(1);
    $automation->update(array(
      'automation' => "create_folder", 
      'source' => "source", 
      'destination' => "destination", 
      'interval' => "year"
    ));
    

    Example Response

    {
      "id": 1,
      "automation": "create_folder",
      "source": "",
      "destination": "",
      "destination_replace_from": "",
      "destination_replace_to": "",
      "interval": "week",
      "next_process_on": "2020-01-01",
      "path": "",
      "realtime": true,
      "user_id": 1,
      "user_ids": [
    
      ],
      "group_ids": [
    
      ]
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <automation>
      <id type="integer">1</id>
      <automation>create_folder</automation>
      <source></source>
      <destination></destination>
      <destination_replace_from></destination_replace_from>
      <destination_replace_to></destination_replace_to>
      <interval>week</interval>
      <next_process_on>2020-01-01</next_process_on>
      <path></path>
      <realtime type="boolean">true</realtime>
      <user_id type="integer">1</user_id>
      <user_ids type="array"/>
      <group_ids type="array"/>
    </automation>
    
    

    HTTPS Request

    PATCH /automations/{id}

    Request Parameters

    Parameter Description
    id int64 Required Automation ID
    automation string Required Type of automation. One of: create_folder, request_file, request_move
    source string Source Path
    destination string Destination Path
    destination_replace_from string If set, this string in the destination path will be replaced with the value in destination_replace_to.
    destination_replace_to string If set, this string will replace the value destination_replace_from in the destination filename. You can use special patterns here.
    interval string How often to run this automation? One of: day, week, week_end, month, month_end, quarter, quarter_end, year, year_end
    path string Path on which this Automation runs. Supports globs.
    user_ids string A list of user IDs the automation is associated with. If sent as a string, it should be comma-delimited.
    group_ids string A list of group IDs the automation is associated with. If sent as a string, it should be comma-delimited.

    Delete Automation

    Example Request

    curl https://app.files.com/api/rest/v1/automations/{id}.json \
      -X DELETE \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/automations/{id}.xml ]
      -X DELETE \
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    automation = Files::Automation.find(1)
    automation.delete
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $automation = \Files\Automation->find(1);
    $automation->delete();
    

    Example Response

    No response.
    
    No response.
    

    HTTPS Request

    DELETE /automations/{id}

    Request Parameters

    Parameter Description
    id int64 Required Automation ID.

    Behaviors

    The Behaviors resource in the REST API allows you to operate on Behaviors.

    Behaviors are the API resource for what are also known as Folder Settings. Every behavior is associated with a folder.

    Depending on the behavior, it may also operate on child folders. It may be overridable at the child folder level or maybe can be added to at the child folder level. The exact options for each behavior type are explained in the table below.

    Additionally, some behaviors are visible to non-admins, and others are even settable by non-admins. All the details are below.

    Each behavior uses a different format for storings its settings value. Next to each behavior type is an example value. Our API and SDKs currently require that the value for behaviors be sent as raw JSON within the value field. Our SDK generator and API documentation generator doesn't fully keep up with this requirement, so if you need any help finding the exact syntax to use for your language or use case, just reach out.

    Behavior types

    append_timestamp

    Example Value

    {
      "format": "-YYYY-MM-DDThh:mm:ssZ",
      "timezone": "Z"
    }
    

    Append a timestamp to filenames of all files uploaded to this folder. This is often used in conjunction with Automations and remote server sync to ensure file organization.

    Value Hash Parameters  
    format Format for the timestamp. You may use anything accepted by the standard UNIX date command.
    timezone Accepts any valid timezone value from the web interface. Send Z for UTC/Zulu time.
    Details  
    Settable by non-admins? No
    Visible to non-admins? Yes
    Multiple per folder? No, may only be set once per folder.
    Effect in child folders Applies, may not be overridden.

    auto_encrypt

    Files will be automatically encrypted after uploading using your provided GPG key.

    This Behavior is often used on our HIPAA accounts to convert data into a format unreadable by even us. GPG is an asymmetric encryption type (which means it uses public keys and private keys). Because you are only providing us your public key and keeping your private key, we won't be able to read anything once it has been GPG encrypted.

    Example Value

    {
      "algorithm": "PGP/GPG",
      "suffix": ".gpg",
      "key": "[your GPG public key]"
    }
    
    Value Hash Parameters  
    algorithm Must be set to PGP/GPG. If we support other options in the future (like OpenSSL), we will amend this option.
    suffix Suffix to apply to filenames once they've been uploaded.
    key Your GPG public key. Please be sure not to send your private key here. If that happens, we try to detect it and disable the behavior for your security.
    Details  
    Settable by non-admin users? No
    Visible to non-admin users? Yes
    Multiple per folder? No, may only be set once per folder.
    Effect in child folders Applies, may be disabled or overridden.

    create_user_folders

    Create a folder here for new users when they are added. This Behavior is typically used to implement home folders for users. It's also a good building block for more advanced automations and workflows.

    Example Value

    {
      "permission": "full",
      "existing_users": true,
      "group_id": 1
    }
    
    Value Hash Parameters  
    permission What permission level to give the user on his or her new folder? Takes the same options as the Permissions endpoint.
    existing_users Apply this behavior to existing users or only newly added users?
    group_id Only apply this behavior to users who are members of this group ID.
    Details  
    Settable by non-admin users? No
    Visible to non-admin users? No
    Multiple per folder? Yes
    Effect in child folders No effect

    file_expiration

    Files in this folder will expire (be deleted) after a certain number of days. This is most often used for compliance purposes where different types of data may need different retention settings. It's also great for managing your costs. You can retain different data for less time than others.

    Value is stored as an Integer (not a hash/array) representing the number of days.

    Example Value

    30
    
    Details  
    Settable by non-admin users? No
    Visible to non-admin users? Yes
    Multiple per folder? No, may only be set once per folder.
    Effect in child folders Applies, may be disabled or overridden.

    inbox

    This folder operates as an inbox where anonymous users can upload files without logging in.

    Example Value

    {
      "key": "application-forms",
      "show_on_login_page": true,
      "title": "Submit Your Job Applications Here",
      "description": "Thanks for coming to the Files.com Job Application Page",
      "help_text": "If you have trouble here, please contact your recruiter."
    }
    
    Value Hash Parameters  
    key URL key used for the inbox.
    show_on_login_page Show this inbox on the login page of your website. Only settable by admins.
    title Title of the Inbox
    description Description of the inbox shown on the actual inbox page.
    help_text Help text shown on the inbox page.
    Details  
    Settable by non-admin users? Yes
    Visible to non-admin users? Yes
    Multiple per folder? Yes
    Effect in child folders No effect

    limit_file_extensions

    Limit the allowed extensions of files being uploaded to this folder.

    Example Value

    [
      "xls",
      "csv"
    ]
    

    Value is stored as an Array (not a hash) of extensions.

    Details  
    Settable by non-admin users? No
    Visible to non-admin users? Yes
    Multiple per folder? No, may only be set once per folder.
    Effect in child folders Applies, may not be overridden.

    limit_file_regex

    Limit the filenames of files in this folder according to a regular expression.

    Example Value

    [
      "/Document-.*/"
    ]
    

    Value is stored as a single-element Array (not a hash) containing the regular expression, which must start and end with slashes.

    Details  
    Settable by non-admin users? No
    Visible to non-admin users? Yes
    Multiple per folder? No, may only be set once per folder.
    Effect in child folders Applies, may not be overridden.

    lock_subfolders

    The subfolder structure of this folder may not be changed. This is useful in conjunction with workflows and automations to ensure your folder structure stays as you expect.

    This behavior does not require that a value be set.

    Details  
    Settable by non-admin users? No
    Visible to non-admin users? Yes
    Multiple per folder? No, may only be set once per folder.
    Effect in child folders Applies, may not be overridden.

    remote_server_sync

    Sync this folder to a remote FTP, SFTP, or Amazon S3 Bucket. One-way and two-way sync options are supported.

    Example Value

    {
      "remote_server_id": "1",
      "direction": "two_way",
      "keep_after_copy": "keep",
      "remote_path": ""
    }
    
    Value Hash Parameters  
    direction One way or two way sync? Valid values: push_to_server, pull_from_server, two_way
    remote_server_id ID of the remote server to sync with. See the Remote Servers API resource for managing these.
    keep_after_copy If one-way syncing, should we delete or keep files after sync?
    remote_path Path on remote server to sync with
    Details  
    Settable by non-admin users? No
    Visible to non-admin users? No
    Multiple per folder? Yes
    Effect in child folders Applies, may not be overridden.

    serve_publicly

    Files in this folder are served via a public HTTPS URL at https://SUBDOMAIN.hosted-by-files.com/...

    This feature works with common static site generators such as Jekyll and Middleman, and allows any static web assets or website to be hosted. It's a great way to get extra mileage out of your Files.com account and avoid having to pay for separate web hosting.

    Example Value

    {
      "key": "public-photos",
      "show_index": true
    }
    
    Value Hash Parameters  
    key URL path for where the stuff is publicly hosted. It will look like https://SUBDOMAIN.hosted-by-files.com/{key}/
    show_index Show an index page listing the folder contents?
    Details  
    Settable by non-admin users? No
    Visible to non-admin users? Yes
    Multiple per folder? No, may only be set once per folder.
    Effect in child folders Applies, may not be overridden.

    storage_region

    Files in this folder are stored in a certain geographical region. If you set this Behavior on an existing folder, we will migrate existing files to the new location automatically.

    Example Value

    "us-east-1"
    

    Value is stored as a String. Valid region values:

    Value String Region Description
    us-east-1 USA, Virginia
    ap-southeast-2 Australia, Sydney
    ca-central-1 Canada, Toronto
    eu-west-2 EU - UK, London
    eu-central-1 EU - Germany, Frankfurt
    ap-northeast-1 Japan, Tokyo
    ap-southeast-1 Singapore
    Details  
    Settable by non-admin users? No
    Visible to non-admin users? Yes
    Multiple per folder? No, may only be set once per folder.
    Effect in child folders Applies, and may be overridden.

    webhook

    Sends an HTTP(S) request to a remote server whenever certain actions occur on a folder. Webhooks are often used to integrate Files.com with other services.

    Example Value

    {
      "urls": [
        "https://mysite.com/url..."
      ],
      "method": "POST",
      "encoding": "RAW",
      "triggers": [
        "create",
        "read",
        "update",
        "destroy",
        "move",
        "copy"
      ]
    }
    
    Value Hash Parameters  
    urls Array of URLs to send the webhook to.
    method Default: GET. May also be set to POST.
    triggers Leave blank to send webhooks on any action on this folder. Or, for specific actions, you may specify an array of action types. Valid values are: create, read, update, destroy, move, copy.
    encoding May be JSON, XML, or RAW. If set to RAW or left blank, we will deliver the webhook using the HTTP GET params or POST body. If JSON or XML, we will encode the payload accordingly and send a matching Content-Type header.
    Details  
    Settable by non-admin users? No
    Visible to non-admin users? Yes
    Multiple per folder? Yes
    Effect in child folders Applies, and may not be overridden. Additional webhooks may be added in child folders.

    The Behavior object

    Example Behavior Object

    {
      "id": 1,
      "behavior": "webhook",
      "path": "",
      "value": {
        "method": "GET"
      }
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <behavior>
      <id type="integer">1</id>
      <behavior>webhook</behavior>
      <path></path>
      <value>{ "method": "GET" }</value>
    </behavior>
    
    
    Attribute Description
    id int64 Folder behavior ID
    behavior string Behavior type.
    path string Folder path This must be slash-delimited, but it must neither start nor end with a slash. Maximum of 5000 characters.
    value object Settings for this behavior. See the section above for an example value to provide here. Formatting is different for each Behavior type. May be sent as nested JSON or a single JSON-encoded string. If using XML encoding for the API call, this data must be sent as a JSON-encoded string.

    List Behaviors

    Example Request

    curl https://app.files.com/api/rest/v1/behaviors.json \
      -H 'Content-Type: application/json' \
      -d '{"behavior":"webhook"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/behaviors.xml ]
      -H 'Content-Type: application/xml' \
      -d '<behaviors>
           <behavior>webhook</behavior>
         </behaviors>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Behavior.list(
      behavior: "webhook"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Behavior::list(array(
      'behavior' => "webhook"
    ));
    

    Example Response

    [
      {
        "id": 1,
        "behavior": "webhook",
        "path": "",
        "value": {
          "method": "GET"
        }
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <behaviors type="array">
      <behavior>
        <id type="integer">1</id>
        <behavior>webhook</behavior>
        <path></path>
        <value>{ "method": "GET" }</value>
      </behavior>
    </behaviors>
    
    

    HTTPS Request

    GET /behaviors

    Request Parameters

    Parameter Description
    behavior string If set, only shows folder behaviors matching this behavior type.

    List Behaviors by path

    Example Request

    curl https://app.files.com/api/rest/v1/behaviors/folders/{path} \
      -H 'Content-Type: application/json' \
      -d '{"behavior":"webhook"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/behaviors/folders/{path} ]
      -H 'Content-Type: application/xml' \
      -d '<behaviors>
           <behavior>webhook</behavior>
         </behaviors>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Behavior.folders(path, 
      behavior: "webhook"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Behavior::folders($path, array(
      'behavior' => "webhook"
    ));
    

    Example Response

    [
      {
        "id": 1,
        "behavior": "webhook",
        "path": "",
        "value": {
          "method": "GET"
        }
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <behaviors type="array">
      <behavior>
        <id type="integer">1</id>
        <behavior>webhook</behavior>
        <path></path>
        <value>{ "method": "GET" }</value>
      </behavior>
    </behaviors>
    
    

    HTTPS Request

    GET /behaviors/folders/?*path

    Request Parameters

    Parameter Description
    path string Required Path to search.
    recursive string Show behaviors below this path?
    behavior string If set only shows folder behaviors matching this behavior type.

    Show Behavior

    Example Request

    curl https://app.files.com/api/rest/v1/behaviors/{id}.json \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/behaviors/{id}.xml ]
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Behavior.find(id)
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Behavior::find($id);
    

    Example Response

    {
      "id": 1,
      "behavior": "webhook",
      "path": "",
      "value": {
        "method": "GET"
      }
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <behavior>
      <id type="integer">1</id>
      <behavior>webhook</behavior>
      <path></path>
      <value>{ "method": "GET" }</value>
    </behavior>
    
    

    HTTPS Request

    GET /behaviors/{id}

    Request Parameters

    Parameter Description
    id int64 Required Behavior ID

    Create Behavior

    Example Request

    curl https://app.files.com/api/rest/v1/behaviors.json \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{"value":"{\"method\": \"GET\"}","path":"path","behavior":"webhook"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/behaviors.xml ]
      -X POST \
      -H 'Content-Type: application/xml' \
      -d '<behavior>
           <value>{"method": "GET"}</value>
           <path>path</path>
           <behavior>webhook</behavior>
         </behavior>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Behavior.create(
      value: "{\"method\": \"GET\"}", 
      path: "path", 
      behavior: "webhook"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Behavior::create(array(
      'value' => "{\"method\": \"GET\"}", 
      'path' => "path", 
      'behavior' => "webhook"
    ));
    

    Example Response

    {
      "id": 1,
      "behavior": "webhook",
      "path": "",
      "value": {
        "method": "GET"
      }
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <behavior>
      <id type="integer">1</id>
      <behavior>webhook</behavior>
      <path></path>
      <value>{ "method": "GET" }</value>
    </behavior>
    
    

    HTTPS Request

    POST /behaviors

    Request Parameters

    Parameter Description
    value string The value of the folder behavior. Can be a integer, array, or hash depending on the type of folder behavior.
    path string Required Folder behaviors path.
    behavior string Required Behavior type.

    Update Behavior

    Example Request

    curl https://app.files.com/api/rest/v1/behaviors/{id}.json \
      -X PATCH \
      -H 'Content-Type: application/json' \
      -d '{"value":"{\"method\": \"GET\"}"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/behaviors/{id}.xml ]
      -X PATCH \
      -H 'Content-Type: application/xml' \
      -d '<behavior>
           <value>{"method": "GET"}</value>
         </behavior>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    behavior = Files::Behavior.find(1)
    behavior.update(
      value: "{\"method\": \"GET\"}"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $behavior = \Files\Behavior->find(1);
    $behavior->update(array(
      'value' => "{\"method\": \"GET\"}"
    ));
    

    Example Response

    {
      "id": 1,
      "behavior": "webhook",
      "path": "",
      "value": {
        "method": "GET"
      }
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <behavior>
      <id type="integer">1</id>
      <behavior>webhook</behavior>
      <path></path>
      <value>{ "method": "GET" }</value>
    </behavior>
    
    

    HTTPS Request

    PATCH /behaviors/{id}

    Request Parameters

    Parameter Description
    id int64 Required Behavior ID
    value string The value of the folder behavior. Can be a integer, array, or hash depending on the type of folder behavior.

    Delete Behavior

    Example Request

    curl https://app.files.com/api/rest/v1/behaviors/{id}.json \
      -X DELETE \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/behaviors/{id}.xml ]
      -X DELETE \
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    behavior = Files::Behavior.find(1)
    behavior.delete
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $behavior = \Files\Behavior->find(1);
    $behavior->delete();
    

    Example Response

    No response.
    
    No response.
    

    HTTPS Request

    DELETE /behaviors/{id}

    Request Parameters

    Parameter Description
    id int64 Required Behavior ID.

    Bundles

    The Bundles resource in the REST API allows you to operate on Bundles. Bundles are the API/SDK term for the feature called Share Links in the web interface. The API provides the full set of actions related to Share Links, including sending them via E-Mail.

    Please note that we very closely monitor the E-Mailing feature and any abuse will result in disabling of your site.

    The Bundle object

    Example Bundle Object

    {
      "code": "abc123",
      "created_at": "2000-01-01 01:00:00 UTC",
      "description": "The public description of the bundle.",
      "expires_at": "2000-01-01 01:00:00 UTC",
      "paths": [
    
      ],
      "id": 1,
      "note": "The internal note on the bundle.",
      "password_protected": true,
      "url": "https://subdomain.files.com/f/12345678",
      "user_id": 1,
      "username": "user"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <bundle>
      <code>abc123</code>
      <created_at type="dateTime">2000-01-01T01:00:00Z</created_at>
      <description>The public description of the bundle.</description>
      <expires_at type="dateTime">2000-01-01T01:00:00Z</expires_at>
      <paths type="array"/>
      <id type="integer">1</id>
      <note>The internal note on the bundle.</note>
      <password_protected type="boolean">true</password_protected>
      <url>https://subdomain.files.com/f/12345678</url>
      <user_id type="integer">1</user_id>
      <username>user</username>
    </bundle>
    
    
    Attribute Description
    code string Bundle code. This code forms the end part of the Public URL.
    created_at date-time Bundle created at date/time
    description string Public description
    expires_at date-time Bundle expiration date/time
    paths array A list of paths in this bundle
    id int64 Bundle ID
    note string Bundle internal note
    password_protected boolean Is this bundle password protected?
    url string Public URL of Share Link
    user_id int64 Bundle creator user ID
    username string Bundle creator username

    List Bundles

    Example Request

    curl https://app.files.com/api/rest/v1/bundles.json \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/bundles.xml ]
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Bundle.list
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Bundle::list();
    

    Example Response

    [
      {
        "code": "abc123",
        "created_at": "2000-01-01 01:00:00 UTC",
        "description": "The public description of the bundle.",
        "expires_at": "2000-01-01 01:00:00 UTC",
        "paths": [
    
        ],
        "id": 1,
        "note": "The internal note on the bundle.",
        "password_protected": true,
        "url": "https://subdomain.files.com/f/12345678",
        "user_id": 1,
        "username": "user"
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <bundles type="array">
      <bundle>
        <code>abc123</code>
        <created_at type="dateTime">2000-01-01T01:00:00Z</created_at>
        <description>The public description of the bundle.</description>
        <expires_at type="dateTime">2000-01-01T01:00:00Z</expires_at>
        <paths type="array"/>
        <id type="integer">1</id>
        <note>The internal note on the bundle.</note>
        <password_protected type="boolean">true</password_protected>
        <url>https://subdomain.files.com/f/12345678</url>
        <user_id type="integer">1</user_id>
        <username>user</username>
      </bundle>
    </bundles>
    
    

    HTTPS Request

    GET /bundles

    Show Bundle

    Example Request

    curl https://app.files.com/api/rest/v1/bundles/{id}.json \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/bundles/{id}.xml ]
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Bundle.find(id)
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Bundle::find($id);
    

    Example Response

    {
      "code": "abc123",
      "created_at": "2000-01-01 01:00:00 UTC",
      "description": "The public description of the bundle.",
      "expires_at": "2000-01-01 01:00:00 UTC",
      "paths": [
    
      ],
      "id": 1,
      "note": "The internal note on the bundle.",
      "password_protected": true,
      "url": "https://subdomain.files.com/f/12345678",
      "user_id": 1,
      "username": "user"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <bundle>
      <code>abc123</code>
      <created_at type="dateTime">2000-01-01T01:00:00Z</created_at>
      <description>The public description of the bundle.</description>
      <expires_at type="dateTime">2000-01-01T01:00:00Z</expires_at>
      <paths type="array"/>
      <id type="integer">1</id>
      <note>The internal note on the bundle.</note>
      <password_protected type="boolean">true</password_protected>
      <url>https://subdomain.files.com/f/12345678</url>
      <user_id type="integer">1</user_id>
      <username>user</username>
    </bundle>
    
    

    HTTPS Request

    GET /bundles/{id}

    Request Parameters

    Parameter Description
    id int64 Required Bundle ID

    Create Bundle

    Example Request

    curl https://app.files.com/api/rest/v1/bundles.json \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{"paths":["file.txt"],"password":"Password","expires_at":"2000-01-01 01:00:00 UTC","description":"Public description","note":"Internal Note"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/bundles.xml ]
      -X POST \
      -H 'Content-Type: application/xml' \
      -d '<bundle>
           <paths type="array">
             <path>file.txt</path>
           </paths>
           <password>Password</password>
           <expires_at type="dateTime">2000-01-01T01:00:00Z</expires_at>
           <description>Public description</description>
           <note>Internal Note</note>
         </bundle>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Bundle.create(
      paths: ["file.txt"], 
      password: "Password", 
      expires_at: "2000-01-01 01:00:00 UTC", 
      description: "Public description", 
      note: "Internal Note"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Bundle::create(array(
      'paths' => ["file.txt"], 
      'password' => "Password", 
      'expires_at' => "2000-01-01 01:00:00 UTC", 
      'description' => "Public description", 
      'note' => "Internal Note"
    ));
    

    Example Response

    {
      "code": "abc123",
      "created_at": "2000-01-01 01:00:00 UTC",
      "description": "The public description of the bundle.",
      "expires_at": "2000-01-01 01:00:00 UTC",
      "paths": [
    
      ],
      "id": 1,
      "note": "The internal note on the bundle.",
      "password_protected": true,
      "url": "https://subdomain.files.com/f/12345678",
      "user_id": 1,
      "username": "user"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <bundle>
      <code>abc123</code>
      <created_at type="dateTime">2000-01-01T01:00:00Z</created_at>
      <description>The public description of the bundle.</description>
      <expires_at type="dateTime">2000-01-01T01:00:00Z</expires_at>
      <paths type="array"/>
      <id type="integer">1</id>
      <note>The internal note on the bundle.</note>
      <password_protected type="boolean">true</password_protected>
      <url>https://subdomain.files.com/f/12345678</url>
      <user_id type="integer">1</user_id>
      <username>user</username>
    </bundle>
    
    

    HTTPS Request

    POST /bundles

    Request Parameters

    Parameter Description
    paths array(string) Required A list of paths to include in this bundle.
    password string Password for this bundle.
    expires_at string Bundle expiration date/time.
    description string Bundle public description
    note string Bundle internal note

    Example Request

    curl https://app.files.com/api/rest/v1/bundles/{id}/share.json \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{"to":["johndoe@gmail.com"],"note":"Just a note."}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/bundles/{id}/share.xml ]
      -X POST \
      -H 'Content-Type: application/xml' \
      -d '<bundle>
           <to type="array">
             <to>johndoe@gmail.com</to>
           </to>
           <note>Just a note.</note>
         </bundle>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    bundle = Files::Bundle.find(1)
    bundle.share(
      to: ["johndoe@gmail.com"],
      note: "Just a note."
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $bundle = \Files\Bundle->find(1);
    $bundle->share(array(
      'to' => ["johndoe@gmail.com"], 
      'note' => "Just a note."
    ));
    

    Example Response

    No response.
    
    No response.
    

    HTTPS Request

    POST /bundles/{id}/share

    Request Parameters

    Parameter Description
    id int64 Required Bundle ID.
    to array(string) Required A list of email addresses to share this bundle with.
    note string Note to include in email.

    Delete Bundle

    Example Request

    curl https://app.files.com/api/rest/v1/bundles/{id}.json \
      -X DELETE \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/bundles/{id}.xml ]
      -X DELETE \
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    bundle = Files::Bundle.find(1)
    bundle.delete
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $bundle = \Files\Bundle->find(1);
    $bundle->delete();
    

    Example Response

    No response.
    
    No response.
    

    HTTPS Request

    DELETE /bundles/{id}

    Request Parameters

    Parameter Description
    id int64 Required Bundle ID.

    Certificates

    The Certificates resource in the REST API allows you to operate on Certificates. These API endpoints are only used for maintaining custom SSL Certificates for your Files.com site. Files.com is also capable of registering SSL certificates itself, so this is only required if you have specific security requirements to use your own certificate.

    The Certificate object

    Example Certificate Object

    {
      "id": 1,
      "certificate": "[certificate]",
      "created_at": "2000-01-01 01:00:00 UTC",
      "display_status": "Available",
      "domains": [
    
      ],
      "expires_at": "2000-01-01 01:00:00 UTC",
      "brick_managed": true,
      "intermediates": "[certificates]",
      "ip_addresses": [
    
      ],
      "issuer": "",
      "name": "My Certificate",
      "key_type": "RSA-4096",
      "request": "[CSR]",
      "status": "Available",
      "subject": "my-custom-domain.com",
      "updated_at": "2000-01-01 01:00:00 UTC"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <certificate>
      <id type="integer">1</id>
      <certificate>[certificate]</certificate>
      <created_at type="dateTime">2000-01-01T01:00:00Z</created_at>
      <display_status>Available</display_status>
      <domains type="array"/>
      <expires_at type="dateTime">2000-01-01T01:00:00Z</expires_at>
      <brick_managed type="boolean">true</brick_managed>
      <intermediates>[certificates]</intermediates>
      <ip_addresses type="array"/>
      <issuer></issuer>
      <name>My Certificate</name>
      <key_type>RSA-4096</key_type>
      <request>[CSR]</request>
      <status>Available</status>
      <subject>my-custom-domain.com</subject>
      <updated_at type="dateTime">2000-01-01T01:00:00Z</updated_at>
    </certificate>
    
    
    Attribute Description
    id int64 Certificate ID
    certificate string Full text of SSL certificate
    created_at date-time Certificate created at
    display_status string Certificate status. (One of Request Generated, New, Active, Active/Expired, Expired, or Available)
    domains array Domains on this certificate other than files.com domains
    expires_at date-time Certificate expiration date/time
    brick_managed boolean Is this certificate automatically managed and renewed by Files.com?
    intermediates string Intermediate certificates
    ip_addresses array A list of IP addresses associated with this SSL Certificate
    issuer string X509 issuer
    name string Descriptive name of certificate
    key_type string Type of key
    request string Certificate signing request text
    status string Certificate status (Request Generated, New, Active, Active/Expired, Expired, or Available)
    subject string X509 Subject name
    updated_at date-time Certificated last updated at

    List SSL Certificates

    Example Request

    curl https://app.files.com/api/rest/v1/certificates.json \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/certificates.xml ]
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Certificate.list
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Certificate::list();
    

    Example Response

    [
      {
        "id": 1,
        "certificate": "[certificate]",
        "created_at": "2000-01-01 01:00:00 UTC",
        "display_status": "Available",
        "domains": [
    
        ],
        "expires_at": "2000-01-01 01:00:00 UTC",
        "brick_managed": true,
        "intermediates": "[certificates]",
        "ip_addresses": [
    
        ],
        "issuer": "",
        "name": "My Certificate",
        "key_type": "RSA-4096",
        "request": "[CSR]",
        "status": "Available",
        "subject": "my-custom-domain.com",
        "updated_at": "2000-01-01 01:00:00 UTC"
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <certificates type="array">
      <certificate>
        <id type="integer">1</id>
        <certificate>[certificate]</certificate>
        <created_at type="dateTime">2000-01-01T01:00:00Z</created_at>
        <display_status>Available</display_status>
        <domains type="array"/>
        <expires_at type="dateTime">2000-01-01T01:00:00Z</expires_at>
        <brick_managed type="boolean">true</brick_managed>
        <intermediates>[certificates]</intermediates>
        <ip_addresses type="array"/>
        <issuer></issuer>
        <name>My Certificate</name>
        <key_type>RSA-4096</key_type>
        <request>[CSR]</request>
        <status>Available</status>
        <subject>my-custom-domain.com</subject>
        <updated_at type="dateTime">2000-01-01T01:00:00Z</updated_at>
      </certificate>
    </certificates>
    
    

    HTTPS Request

    GET /certificates

    Show SSL Certificate

    Example Request

    curl https://app.files.com/api/rest/v1/certificates/{id}.json \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/certificates/{id}.xml ]
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Certificate.find(id)
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Certificate::find($id);
    

    Example Response

    {
      "id": 1,
      "certificate": "[certificate]",
      "created_at": "2000-01-01 01:00:00 UTC",
      "display_status": "Available",
      "domains": [
    
      ],
      "expires_at": "2000-01-01 01:00:00 UTC",
      "brick_managed": true,
      "intermediates": "[certificates]",
      "ip_addresses": [
    
      ],
      "issuer": "",
      "name": "My Certificate",
      "key_type": "RSA-4096",
      "request": "[CSR]",
      "status": "Available",
      "subject": "my-custom-domain.com",
      "updated_at": "2000-01-01 01:00:00 UTC"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <certificate>
      <id type="integer">1</id>
      <certificate>[certificate]</certificate>
      <created_at type="dateTime">2000-01-01T01:00:00Z</created_at>
      <display_status>Available</display_status>
      <domains type="array"/>
      <expires_at type="dateTime">2000-01-01T01:00:00Z</expires_at>
      <brick_managed type="boolean">true</brick_managed>
      <intermediates>[certificates]</intermediates>
      <ip_addresses type="array"/>
      <issuer></issuer>
      <name>My Certificate</name>
      <key_type>RSA-4096</key_type>
      <request>[CSR]</request>
      <status>Available</status>
      <subject>my-custom-domain.com</subject>
      <updated_at type="dateTime">2000-01-01T01:00:00Z</updated_at>
    </certificate>
    
    

    HTTPS Request

    GET /certificates/{id}

    Request Parameters

    Parameter Description
    id int64 Required SSL Certificate ID.

    Create CSR or import existing SSL Certificate

    Example Request

    curl https://app.files.com/api/rest/v1/certificates.json \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{"name":"Name","certificate_domain":"domain.com","key_type":"RSA-4096","certificate":"[certificate]","intermediates":"[certificates]"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/certificates.xml ]
      -X POST \
      -H 'Content-Type: application/xml' \
      -d '<certificate>
           <name>Name</name>
           <certificate_domain>domain.com</certificate_domain>
           <key_type>RSA-4096</key_type>
           <certificate>[certificate]</certificate>
           <intermediates>[certificates]</intermediates>
         </certificate>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Certificate.create(
      name: "Name", 
      certificate_domain: "domain.com", 
      key_type: "RSA-4096", 
      certificate: "[certificate]", 
      intermediates: "[certificates]"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Certificate::create(array(
      'name' => "Name", 
      'certificate_domain' => "domain.com", 
      'key_type' => "RSA-4096", 
      'certificate' => "[certificate]", 
      'intermediates' => "[certificates]"
    ));
    

    Example Response

    {
      "id": 1,
      "certificate": "[certificate]",
      "created_at": "2000-01-01 01:00:00 UTC",
      "display_status": "Available",
      "domains": [
    
      ],
      "expires_at": "2000-01-01 01:00:00 UTC",
      "brick_managed": true,
      "intermediates": "[certificates]",
      "ip_addresses": [
    
      ],
      "issuer": "",
      "name": "My Certificate",
      "key_type": "RSA-4096",
      "request": "[CSR]",
      "status": "Available",
      "subject": "my-custom-domain.com",
      "updated_at": "2000-01-01 01:00:00 UTC"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <certificate>
      <id type="integer">1</id>
      <certificate>[certificate]</certificate>
      <created_at type="dateTime">2000-01-01T01:00:00Z</created_at>
      <display_status>Available</display_status>
      <domains type="array"/>
      <expires_at type="dateTime">2000-01-01T01:00:00Z</expires_at>
      <brick_managed type="boolean">true</brick_managed>
      <intermediates>[certificates]</intermediates>
      <ip_addresses type="array"/>
      <issuer></issuer>
      <name>My Certificate</name>
      <key_type>RSA-4096</key_type>
      <request>[CSR]</request>
      <status>Available</status>
      <subject>my-custom-domain.com</subject>
      <updated_at type="dateTime">2000-01-01T01:00:00Z</updated_at>
    </certificate>
    
    

    HTTPS Request

    POST /certificates

    Request Parameters

    Parameter Description
    name string Required Internal name of the SSL certificate.
    certificate_domain string Domain for certificate.
    certificate_country string Country.
    certificate_state_or_province string State or province.
    certificate_city_or_locale string City or locale.
    certificate_company_name string Company name.
    csr_ou1 string Department name or organization unit 1
    csr_ou2 string Department name or organization unit 2
    csr_ou3 string Department name or organization unit 3
    certificate_email_address string Email address for the certificate owner.
    key_type string Any supported key type. Defaults to RSA-4096.
    key_type_confirm_given string Confirms the key type.
    certificate string The certificate. PEM or PKCS7 formats accepted.
    private_key string Certificate private key.
    password string Certificate password.
    intermediates string Intermediate certificates. PEM or PKCS7 formats accepted.

    Deactivate SSL Certificate

    Example Request

    curl https://app.files.com/api/rest/v1/certificates/{id}/deactivate.json \
      -X POST \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/certificates/{id}/deactivate.xml ]
      -X POST \
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    certificate = Files::Certificate.find(1)
    certificate.deactivate
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $certificate = \Files\Certificate->find(1);
    $certificate->deactivate();
    

    Example Response

    No response.
    
    No response.
    

    HTTPS Request

    POST /certificates/{id}/deactivate

    Request Parameters

    Parameter Description
    id int64 Required SSL Certificate ID.

    Activate SSL Certificate

    Example Request

    curl https://app.files.com/api/rest/v1/certificates/{id}/activate.json \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{"replace_cert":""}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/certificates/{id}/activate.xml ]
      -X POST \
      -H 'Content-Type: application/xml' \
      -d '<certificate>
           <replace_cert></replace_cert>
         </certificate>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    certificate = Files::Certificate.find(1)
    certificate.activate(
      replace_cert: ""
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $certificate = \Files\Certificate->find(1);
    $certificate->activate(array(
      'replace_cert' => ""
    ));
    

    Example Response

    No response.
    
    No response.
    

    HTTPS Request

    POST /certificates/{id}/activate

    Request Parameters

    Parameter Description
    id int64 Required SSL Certificate ID.
    replace_cert string Leave blank, set to any or new_ips.

    Update SSL Certificate

    Example Request

    curl https://app.files.com/api/rest/v1/certificates/{id}.json \
      -X PATCH \
      -H 'Content-Type: application/json' \
      -d '{"name":"My Certificate","intermediates":"[certificates]","certificate":"[certificate]"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/certificates/{id}.xml ]
      -X PATCH \
      -H 'Content-Type: application/xml' \
      -d '<certificate>
           <name>My Certificate</name>
           <intermediates>[certificates]</intermediates>
           <certificate>[certificate]</certificate>
         </certificate>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    certificate = Files::Certificate.find(1)
    certificate.update(
      name: "My Certificate",
      intermediates: "[certificates]",
      certificate: "[certificate]"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $certificate = \Files\Certificate->find(1);
    $certificate->update(array(
      'name' => "My Certificate", 
      'intermediates' => "[certificates]", 
      'certificate' => "[certificate]"
    ));
    

    Example Response

    {
      "id": 1,
      "certificate": "[certificate]",
      "created_at": "2000-01-01 01:00:00 UTC",
      "display_status": "Available",
      "domains": [
    
      ],
      "expires_at": "2000-01-01 01:00:00 UTC",
      "brick_managed": true,
      "intermediates": "[certificates]",
      "ip_addresses": [
    
      ],
      "issuer": "",
      "name": "My Certificate",
      "key_type": "RSA-4096",
      "request": "[CSR]",
      "status": "Available",
      "subject": "my-custom-domain.com",
      "updated_at": "2000-01-01 01:00:00 UTC"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <certificate>
      <id type="integer">1</id>
      <certificate>[certificate]</certificate>
      <created_at type="dateTime">2000-01-01T01:00:00Z</created_at>
      <display_status>Available</display_status>
      <domains type="array"/>
      <expires_at type="dateTime">2000-01-01T01:00:00Z</expires_at>
      <brick_managed type="boolean">true</brick_managed>
      <intermediates>[certificates]</intermediates>
      <ip_addresses type="array"/>
      <issuer></issuer>
      <name>My Certificate</name>
      <key_type>RSA-4096</key_type>
      <request>[CSR]</request>
      <status>Available</status>
      <subject>my-custom-domain.com</subject>
      <updated_at type="dateTime">2000-01-01T01:00:00Z</updated_at>
    </certificate>
    
    

    HTTPS Request

    PATCH /certificates/{id}

    Request Parameters

    Parameter Description
    id int64 Required SSL Certificate ID.
    name string Internal certificate name.
    intermediates string Any intermediate certificates. PEM or PKCS7 formats accepted.
    certificate string The certificate. PEM or PKCS7 formats accepted.

    Delete SSL Certificate

    Example Request

    curl https://app.files.com/api/rest/v1/certificates/{id}.json \
      -X DELETE \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/certificates/{id}.xml ]
      -X DELETE \
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    certificate = Files::Certificate.find(1)
    certificate.delete
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $certificate = \Files\Certificate->find(1);
    $certificate->delete();
    

    Example Response

    No response.
    
    No response.
    

    HTTPS Request

    DELETE /certificates/{id}

    Request Parameters

    Parameter Description
    id int64 Required SSL Certificate ID.

    Files/Folders

    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.

    Using SDKs for File/Folder operations

    Wherever possible, Files.com SDKs have implemented file operation interfaces that are as idiomatic as possible in your target language. Meaning that operating on a remote file on Files.com is as close as possible to operating on a local file.

    We will be expanding the documentation on SDK file operations soon, but in the mean time, you can review the SDK's README file to learn more.

    We strongly recommend using SDKs for file/folder operations if we have one in your language. The SDKs take care of all the complexity for you.

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

    MIME Type Description
    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 object

    Example File Object

    {
      "id": 1,
      "path": "path/file.txt",
      "display_name": "file.txt",
      "type": "file",
      "size": 1024,
      "mtime": "2000-01-01 01:00:00 UTC",
      "provided_mtime": "2000-01-01 01:00:00 UTC",
      "crc32": "70976923",
      "md5": "17c54824e9931a4688ca032d03f6663c",
      "region": "us-east-1",
      "permissions": "rpw",
      "subfolders_locked?": true,
      "download_uri": "https://mysite.files.com/...",
      "priority_color": "red",
      "preview_id": 1,
      "preview": ""
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <file>
      <id type="integer">1</id>
      <path>path/file.txt</path>
      <display_name>file.txt</display_name>
      <type>file</type>
      <size type="integer">1024</size>
      <mtime type="dateTime">2000-01-01T01:00:00Z</mtime>
      <provided_mtime type="dateTime">2000-01-01T01:00:00Z</provided_mtime>
      <crc32>70976923</crc32>
      <md5>17c54824e9931a4688ca032d03f6663c</md5>
      <region>us-east-1</region>
      <permissions>rpw</permissions>
      <subfolders_locked? type="boolean">true</subfolders_locked?>
      <download_uri>https://mysite.files.com/...</download_uri>
      <priority_color>red</priority_color>
      <preview_id type="integer">1</preview_id>
      <preview></preview>
    </file>
    
    
    Attribute Description
    id int64 File/Folder ID
    path string File/Folder path This must be slash-delimited, but it must neither start nor end with a slash. Maximum of 5000 characters.
    display_name string File/Folder display name
    type string Type: directory or file.
    size int64 File/Folder size
    mtime date-time File last modified date/time, according to the server. This is the timestamp of the last Files.com operation of the file, regardless of what modified timestamp was sent.
    provided_mtime date-time File last modified date/time, according to the client who set it. Files.com allows desktop, FTP, SFTP, and WebDAV clients to set modified at times. This allows Desktop<->Cloud syncing to preserve modified at times.
    crc32 string File CRC32 checksum. This is sometimes delayed, so if you get a blank response, wait and try again.
    md5 string File MD5 checksum. This is sometimes delayed, so if you get a blank response, wait and try again.
    region string Region location
    permissions string A short string representing the current user's permissions. Can be r,w,p, or any combination
    subfolders_locked? boolean Are subfolders locked and unable to be modified?
    download_uri string Link to download file. Provided only in response to a download request.
    priority_color string Bookmark/priority color of file/folder
    preview_id int64 File preview ID
    preview File preview

    Download file

    Example Request

    curl https://app.files.com/api/rest/v1/files/{path} \
      -H 'Content-Type: application/json' \
      -d '{"with_previews":true,"with_priority_color":true}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/files/{path} ]
      -H 'Content-Type: application/xml' \
      -d '<file>
           <with_previews type="boolean">true</with_previews>
           <with_priority_color type="boolean">true</with_priority_color>
         </file>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::File.download(path, 
      with_previews: true, 
      with_priority_color: true
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\File::download($path, array(
      'with_previews' => true, 
      'with_priority_color' => true
    ));
    

    Example Response

    {
      "id": 1,
      "path": "path/file.txt",
      "display_name": "file.txt",
      "type": "file",
      "size": 1024,
      "mtime": "2000-01-01 01:00:00 UTC",
      "provided_mtime": "2000-01-01 01:00:00 UTC",
      "crc32": "70976923",
      "md5": "17c54824e9931a4688ca032d03f6663c",
      "region": "us-east-1",
      "permissions": "rpw",
      "subfolders_locked?": true,
      "download_uri": "https://mysite.files.com/...",
      "priority_color": "red",
      "preview_id": 1,
      "preview": ""
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <file>
      <id type="integer">1</id>
      <path>path/file.txt</path>
      <display_name>file.txt</display_name>
      <type>file</type>
      <size type="integer">1024</size>
      <mtime type="dateTime">2000-01-01T01:00:00Z</mtime>
      <provided_mtime type="dateTime">2000-01-01T01:00:00Z</provided_mtime>
      <crc32>70976923</crc32>
      <md5>17c54824e9931a4688ca032d03f6663c</md5>
      <region>us-east-1</region>
      <permissions>rpw</permissions>
      <subfolders_locked? type="boolean">true</subfolders_locked?>
      <download_uri>https://mysite.files.com/...</download_uri>
      <priority_color>red</priority_color>
      <preview_id type="integer">1</preview_id>
      <preview></preview>
    </file>
    
    

    HTTPS Request

    GET /files/?*path

    Request Parameters

    Parameter Description
    action string Can be blank, redirect or stat.
    path string Required File path.
    with_previews boolean Include file preview information?
    with_priority_color boolean Include file priority color information?

    Upload file

    Uploading files via REST is a multi-step process and it's covered in the File Uploading section.

    Upload file to existing path (replace file)

    Example Request

    curl https://app.files.com/api/rest/v1/files/{path} \
      -X PUT \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/files/{path} ]
      -X PUT \
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::File.update(path)
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\File::update($path);
    

    Example Response

    {
      "id": 1,
      "path": "path/file.txt",
      "display_name": "file.txt",
      "type": "file",
      "size": 1024,
      "mtime": "2000-01-01 01:00:00 UTC",
      "provided_mtime": "2000-01-01 01:00:00 UTC",
      "crc32": "70976923",
      "md5": "17c54824e9931a4688ca032d03f6663c",
      "region": "us-east-1",
      "permissions": "rpw",
      "subfolders_locked?": true,
      "download_uri": "https://mysite.files.com/...",
      "priority_color": "red",
      "preview_id": 1,
      "preview": ""
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <file>
      <id type="integer">1</id>
      <path>path/file.txt</path>
      <display_name>file.txt</display_name>
      <type>file</type>
      <size type="integer">1024</size>
      <mtime type="dateTime">2000-01-01T01:00:00Z</mtime>
      <provided_mtime type="dateTime">2000-01-01T01:00:00Z</provided_mtime>
      <crc32>70976923</crc32>
      <md5>17c54824e9931a4688ca032d03f6663c</md5>
      <region>us-east-1</region>
      <permissions>rpw</permissions>
      <subfolders_locked? type="boolean">true</subfolders_locked?>
      <download_uri>https://mysite.files.com/...</download_uri>
      <priority_color>red</priority_color>
      <preview_id type="integer">1</preview_id>
      <preview></preview>
    </file>
    
    

    HTTPS Request

    PUT /files/?*path

    Request Parameters

    Parameter Description
    path string Required Path

    Update file/folder metadata

    Example Request

    curl https://app.files.com/api/rest/v1/files/{path} \
      -X PATCH \
      -H 'Content-Type: application/json' \
      -d '{"provided_mtime":"2000-01-01 01:00:00 UTC","priority_color":"red"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/files/{path} ]
      -X PATCH \
      -H 'Content-Type: application/xml' \
      -d '<file>
           <provided_mtime type="dateTime">2000-01-01T01:00:00Z</provided_mtime>
           <priority_color>red</priority_color>
         </file>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::File.update(path, 
      provided_mtime: "2000-01-01 01:00:00 UTC", 
      priority_color: "red"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\File::update($path, array(
      'provided_mtime' => "2000-01-01 01:00:00 UTC", 
      'priority_color' => "red"
    ));
    

    Example Response

    {
      "id": 1,
      "path": "path/file.txt",
      "display_name": "file.txt",
      "type": "file",
      "size": 1024,
      "mtime": "2000-01-01 01:00:00 UTC",
      "provided_mtime": "2000-01-01 01:00:00 UTC",
      "crc32": "70976923",
      "md5": "17c54824e9931a4688ca032d03f6663c",
      "region": "us-east-1",
      "permissions": "rpw",
      "subfolders_locked?": true,
      "download_uri": "https://mysite.files.com/...",
      "priority_color": "red",
      "preview_id": 1,
      "preview": ""
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <file>
      <id type="integer">1</id>
      <path>path/file.txt</path>
      <display_name>file.txt</display_name>
      <type>file</type>
      <size type="integer">1024</size>
      <mtime type="dateTime">2000-01-01T01:00:00Z</mtime>
      <provided_mtime type="dateTime">2000-01-01T01:00:00Z</provided_mtime>
      <crc32>70976923</crc32>
      <md5>17c54824e9931a4688ca032d03f6663c</md5>
      <region>us-east-1</region>
      <permissions>rpw</permissions>
      <subfolders_locked? type="boolean">true</subfolders_locked?>
      <download_uri>https://mysite.files.com/...</download_uri>
      <priority_color>red</priority_color>
      <preview_id type="integer">1</preview_id>
      <preview></preview>
    </file>
    
    

    HTTPS Request

    PATCH /files/?*path

    Request Parameters

    Parameter Description
    path string Required Path
    provided_mtime string Modified time of file.
    priority_color string Priority/Bookmark color of file.

    Delete file/folder

    Example Request

    curl https://app.files.com/api/rest/v1/files/{path} \
      -X DELETE \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/files/{path} ]
      -X DELETE \
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::File.delete(path)
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\File::delete($path);
    

    Example Response

    No response.
    
    No response.
    

    HTTPS Request

    DELETE /files/?*path

    Request Parameters

    Parameter Description
    path string Required Path

    The Folder object

    Example Folder Object

    {
      "id": 1,
      "path": "path/file.txt",
      "display_name": "file.txt",
      "type": "file",
      "size": 1024,
      "mtime": "2000-01-01 01:00:00 UTC",
      "provided_mtime": "2000-01-01 01:00:00 UTC",
      "crc32": "70976923",
      "md5": "17c54824e9931a4688ca032d03f6663c",
      "region": "us-east-1",
      "permissions": "rpw",
      "subfolders_locked?": true,
      "download_uri": "https://mysite.files.com/...",
      "priority_color": "red",
      "preview_id": 1,
      "preview": ""
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <folder>
      <id type="integer">1</id>
      <path>path/file.txt</path>
      <display_name>file.txt</display_name>
      <type>file</type>
      <size type="integer">1024</size>
      <mtime type="dateTime">2000-01-01T01:00:00Z</mtime>
      <provided_mtime type="dateTime">2000-01-01T01:00:00Z</provided_mtime>
      <crc32>70976923</crc32>
      <md5>17c54824e9931a4688ca032d03f6663c</md5>
      <region>us-east-1</region>
      <permissions>rpw</permissions>
      <subfolders_locked? type="boolean">true</subfolders_locked?>
      <download_uri>https://mysite.files.com/...</download_uri>
      <priority_color>red</priority_color>
      <preview_id type="integer">1</preview_id>
      <preview></preview>
    </folder>
    
    
    Attribute Description
    id int64 File/Folder ID
    path string File/Folder path This must be slash-delimited, but it must neither start nor end with a slash. Maximum of 5000 characters.
    display_name string File/Folder display name
    type string Type: directory or file.
    size int64 File/Folder size
    mtime date-time File last modified date/time, according to the server. This is the timestamp of the last Files.com operation of the file, regardless of what modified timestamp was sent.
    provided_mtime date-time File last modified date/time, according to the client who set it. Files.com allows desktop, FTP, SFTP, and WebDAV clients to set modified at times. This allows Desktop<->Cloud syncing to preserve modified at times.
    crc32 string File CRC32 checksum. This is sometimes delayed, so if you get a blank response, wait and try again.
    md5 string File MD5 checksum. This is sometimes delayed, so if you get a blank response, wait and try again.
    region string Region location
    permissions string A short string representing the current user's permissions. Can be r,w,p, or any combination
    subfolders_locked? boolean Are subfolders locked and unable to be modified?
    download_uri string Link to download file. Provided only in response to a download request.
    priority_color string Bookmark/priority color of file/folder
    preview_id int64 File preview ID
    preview File preview

    List folder

    Example Request

    curl https://app.files.com/api/rest/v1/folders/{path} \
      -H 'Content-Type: application/json' \
      -d '{"page":1,"per_page":1,"search_all":true,"with_preview":true,"with_priority_color":true}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/folders/{path} ]
      -H 'Content-Type: application/xml' \
      -d '<folders>
           <page type="integer">1</page>
           <per_page type="integer">1</per_page>
           <search_all type="boolean">true</search_all>
           <with_preview type="boolean">true</with_preview>
           <with_priority_color type="boolean">true</with_priority_color>
         </folders>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Folder.list(path, 
      page: 1, 
      per_page: 1, 
      search_all: true, 
      with_preview: true, 
      with_priority_color: true
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Folder::list($path, array(
      'page' => 1, 
      'per_page' => 1, 
      'search_all' => true, 
      'with_preview' => true, 
      'with_priority_color' => true
    ));
    

    Example Response

    [
      {
        "id": 1,
        "path": "path/file.txt",
        "display_name": "file.txt",
        "type": "file",
        "size": 1024,
        "mtime": "2000-01-01 01:00:00 UTC",
        "provided_mtime": "2000-01-01 01:00:00 UTC",
        "crc32": "70976923",
        "md5": "17c54824e9931a4688ca032d03f6663c",
        "region": "us-east-1",
        "permissions": "rpw",
        "subfolders_locked?": true,
        "download_uri": "https://mysite.files.com/...",
        "priority_color": "red",
        "preview_id": 1,
        "preview": ""
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <folders type="array">
      <folder>
        <id type="integer">1</id>
        <path>path/file.txt</path>
        <display_name>file.txt</display_name>
        <type>file</type>
        <size type="integer">1024</size>
        <mtime type="dateTime">2000-01-01T01:00:00Z</mtime>
        <provided_mtime type="dateTime">2000-01-01T01:00:00Z</provided_mtime>
        <crc32>70976923</crc32>
        <md5>17c54824e9931a4688ca032d03f6663c</md5>
        <region>us-east-1</region>
        <permissions>rpw</permissions>
        <subfolders_locked? type="boolean">true</subfolders_locked?>
        <download_uri>https://mysite.files.com/...</download_uri>
        <priority_color>red</priority_color>
        <preview_id type="integer">1</preview_id>
        <preview></preview>
      </folder>
    </folders>
    
    

    HTTPS Request

    GET /folders/?*path

    Request Parameters

    Parameter Description
    path string Required Folder path.
    action string Action to take. Can be count, count_nrs (non recursive), size, permissions, or blank.
    filter string Specify to filter folders/files list by name.
    page int64 Current page in folders/files list.
    per_page int64 Number of folders/files to show per page.
    preview_size string Request a preview size. Can be small (default), large, xlarge, or pdf.
    search_all boolean Search entire site?
    with_preview boolean Include file preview information?
    with_priority_color boolean Include file priority color information?

    Create folder

    Example Request

    curl https://app.files.com/api/rest/v1/folders/{path} \
      -X POST \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/folders/{path} ]
      -X POST \
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Folder.create(path)
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Folder::create($path);
    

    Example Response

    No response.
    
    No response.
    

    HTTPS Request

    POST /folders/?*path

    Request Parameters

    Parameter Description
    path string Required Path

    File Uploading

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

    If you are using an SDK, you do not need to worry about any of this process, it's all handled for you by the SDK.

    REST API upload steps

    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.files.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.files.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.files.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.files.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.files.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 Files.com.

    The upload_uri link is signed by Files.com 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.files.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.files.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.files.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.files.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.files.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.files.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

    Groups

    The Groups resource in the REST API allows you to operate on Groups.

    The Group object

    Example Group Object

    {
      "id": 1,
      "admin_ids": [
    
      ],
      "name": "owners",
      "notes": "",
      "user_ids": [
    
      ],
      "usernames": [
    
      ]
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <group>
      <id type="integer">1</id>
      <admin_ids type="array"/>
      <name>owners</name>
      <notes></notes>
      <user_ids type="array"/>
      <usernames type="array"/>
    </group>
    
    
    Attribute Description
    id int64 Group ID
    admin_ids array List of user IDs who are group administrators
    name string Group name
    notes string Notes about this group
    user_ids array List of user IDs who belong to this group
    usernames array List of usernames who belong to this group

    List groups

    Example Request

    curl https://app.files.com/api/rest/v1/groups.json \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/groups.xml ]
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Group.list
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Group::list();
    

    Example Response

    [
      {
        "id": 1,
        "admin_ids": [
    
        ],
        "name": "owners",
        "notes": "",
        "user_ids": [
    
        ],
        "usernames": [
    
        ]
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <groups type="array">
      <group>
        <id type="integer">1</id>
        <admin_ids type="array"/>
        <name>owners</name>
        <notes></notes>
        <user_ids type="array"/>
        <usernames type="array"/>
      </group>
    </groups>
    
    

    HTTPS Request

    GET /groups

    Show group

    Example Request

    curl https://app.files.com/api/rest/v1/groups/{id}.json \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/groups/{id}.xml ]
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Group.find(id)
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Group::find($id);
    

    Example Response

    {
      "id": 1,
      "admin_ids": [
    
      ],
      "name": "owners",
      "notes": "",
      "user_ids": [
    
      ],
      "usernames": [
    
      ]
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <group>
      <id type="integer">1</id>
      <admin_ids type="array"/>
      <name>owners</name>
      <notes></notes>
      <user_ids type="array"/>
      <usernames type="array"/>
    </group>
    
    

    HTTPS Request

    GET /groups/{id}

    Request Parameters

    Parameter Description
    id int64 Required Group ID.

    Create group

    Example Request

    curl https://app.files.com/api/rest/v1/groups.json \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{"name":"owners"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/groups.xml ]
      -X POST \
      -H 'Content-Type: application/xml' \
      -d '<group>
           <name>owners</name>
         </group>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Group.create(
      name: "owners"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Group::create(array(
      'name' => "owners"
    ));
    

    Example Response

    {
      "id": 1,
      "admin_ids": [
    
      ],
      "name": "owners",
      "notes": "",
      "user_ids": [
    
      ],
      "usernames": [
    
      ]
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <group>
      <id type="integer">1</id>
      <admin_ids type="array"/>
      <name>owners</name>
      <notes></notes>
      <user_ids type="array"/>
      <usernames type="array"/>
    </group>
    
    

    HTTPS Request

    POST /groups

    Request Parameters

    Parameter Description
    name string Group name.
    notes string Group notes.
    user_ids string A list of user ids. If sent as a string, should be comma-delimited.
    admin_ids string A list of group admin user ids. If sent as a string, should be comma-delimited.

    Update group

    Example Request

    curl https://app.files.com/api/rest/v1/groups/{id}.json \
      -X PUT \
      -H 'Content-Type: application/json' \
      -d '{"name":"owners"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/groups/{id}.xml ]
      -X PUT \
      -H 'Content-Type: application/xml' \
      -d '<group>
           <name>owners</name>
         </group>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    group = Files::Group.find(1)
    group.update(
      name: "owners"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $group = \Files\Group->find(1);
    $group->update(array(
      'name' => "owners"
    ));
    

    Example Response

    {
      "id": 1,
      "admin_ids": [
    
      ],
      "name": "owners",
      "notes": "",
      "user_ids": [
    
      ],
      "usernames": [
    
      ]
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <group>
      <id type="integer">1</id>
      <admin_ids type="array"/>
      <name>owners</name>
      <notes></notes>
      <user_ids type="array"/>
      <usernames type="array"/>
    </group>
    
    

    HTTPS Request

    PUT /groups/{id}

    Request Parameters

    Parameter Description
    id int64 Required Group ID.
    name string Group name.
    notes string Group notes.
    user_ids string A list of user ids. If sent as a string, should be comma-delimited.
    admin_ids string A list of group admin user ids. If sent as a string, should be comma-delimited.

    Add a User to a Group

    Example Request

    curl https://app.files.com/api/rest/v1/groups/{id}/memberships/{user_id}.json \
      -X PUT \
      -H 'Content-Type: application/json' \
      -d '{"user_id":1,"admin":true}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/groups/{id}/memberships/{user_id}.xml ]
      -X PUT \
      -H 'Content-Type: application/xml' \
      -d '<group>
           <user_id type="integer">1</user_id>
           <admin type="boolean">true</admin>
         </group>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    group = Files::Group.find(1)
    group.update_memberships_user_id(
      user_id: 1,
      admin: true
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $group = \Files\Group->find(1);
    $group->updateMembershipsUserId(array(
      'user_id' => 1, 
      'admin' => true
    ));
    

    Example Response

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

    HTTPS Request

    PUT /groups/{id}/memberships/{user_id}

    Request Parameters

    Parameter Description
    user_id int64 Required User ID to add to group.
    admin boolean Is the user a group administrator?
    id int64 Required

    Update group membership

    Example Request

    curl https://app.files.com/api/rest/v1/groups/{id}/memberships/{user_id}.json \
      -X PATCH \
      -H 'Content-Type: application/json' \
      -d '{"user_id":1,"admin":true}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/groups/{id}/memberships/{user_id}.xml ]
      -X PATCH \
      -H 'Content-Type: application/xml' \
      -d '<group>
           <user_id type="integer">1</user_id>
           <admin type="boolean">true</admin>
         </group>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    group = Files::Group.find(1)
    group.update_user(
      user_id: 1,
      admin: true
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $group = \Files\Group->find(1);
    $group->updateUser(array(
      'user_id' => 1, 
      'admin' => true
    ));
    

    Example Response

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

    HTTPS Request

    PATCH /groups/{id}/memberships/{user_id}

    Request Parameters

    Parameter Description
    user_id int64 Required User ID to add to group.
    admin boolean Is the user a group administrator?
    id int64 Required

    Delete group

    Example Request

    curl https://app.files.com/api/rest/v1/groups/{id}.json \
      -X DELETE \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/groups/{id}.xml ]
      -X DELETE \
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    group = Files::Group.find(1)
    group.delete
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $group = \Files\Group->find(1);
    $group->delete();
    

    Example Response

    No response.
    
    No response.
    

    HTTPS Request

    DELETE /groups/{id}

    Request Parameters

    Parameter Description
    id int64 Required Group ID.

    Delete group membership

    Example Request

    curl https://app.files.com/api/rest/v1/groups/{id}/memberships/{user_id}.json \
      -X DELETE \
      -H 'Content-Type: application/json' \
      -d '{"user_id":1}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/groups/{id}/memberships/{user_id}.xml ]
      -X DELETE \
      -H 'Content-Type: application/xml' \
      -d '<group>
           <user_id type="integer">1</user_id>
         </group>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    group = Files::Group.find(1)
    group.delete_user(
      user_id: 1
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $group = \Files\Group->find(1);
    $group->deleteUser(array(
      'user_id' => 1
    ));
    

    Example Response

    No response.
    
    No response.
    

    HTTPS Request

    DELETE /groups/{id}/memberships/{user_id}

    Request Parameters

    Parameter Description
    id int64 Required Group ID.
    user_id int64 Required User ID to add to group.

    Histories

    The Histories resource in the REST API allows you to operate on Histories.

    The History object

    Example History Object

    {
      "id": 1,
      "when": "2000-01-01 01:00:00 UTC",
      "destination": "/to_path",
      "display": "full",
      "ip": "192.283.128.182",
      "path": "path",
      "source": "/from_path",
      "targets": [
    
      ],
      "user_id": 1,
      "username": "user",
      "action": "create",
      "failure_type": "none",
      "interface": "web"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <history>
      <id type="integer">1</id>
      <when type="dateTime">2000-01-01T01:00:00Z</when>
      <destination>/to_path</destination>
      <display>full</display>
      <ip>192.283.128.182</ip>
      <path>path</path>
      <source>/from_path</source>
      <targets type="array"/>
      <user_id type="integer">1</user_id>
      <username>user</username>
      <action>create</action>
      <failure_type>none</failure_type>
      <interface>web</interface>
    </history>
    
    
    Attribute Description
    id int64 Action ID
    when date-time Action occurrence date/time
    destination string The destination path for this action, if applicable
    display string Display format
    ip string IP Address that performed this action
    path string Path This must be slash-delimited, but it must neither start nor end with a slash. Maximum of 5000 characters.
    source string The source path for this action, if applicable
    targets array Targets
    user_id int64 User ID
    username string Username
    action string Type of action. Can be create, read, update, destroy, move, login, failedlogin, copy, user_create, user_update, user_destroy, group_create, group_update, group_destroy, permission_create, permission_destroy, api_key_create, api_key_update, or api_key_destroy
    failure_type string Failure type. If action was a user login or session failure, why did it fail? Can be expired_trial, account_overdue, locked_out, ip_mismatch, password_mismatch, site_mismatch, username_not_found, none, no_ftp_permission, no_web_permission, no_directory, errno_enoent, no_sftp_permission, no_dav_permission, no_restapi_permission, key_mismatch, region_mismatch, or expired_access
    interface string Interface on which this action occurred.

    List history for specific file

    Example Request

    curl https://app.files.com/api/rest/v1/history/files(/*path).json \
      -H 'Content-Type: application/json' \
      -d '{"page":1,"per_page":1,"display":"full"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/history/files(/*path).xml ]
      -H 'Content-Type: application/xml' \
      -d '<histories>
           <page type="integer">1</page>
           <per_page type="integer">1</per_page>
           <display>full</display>
         </histories>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::History.list_for_file(path, 
      page: 1, 
      per_page: 1, 
      display: "full"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\History::listForFile($path, array(
      'page' => 1, 
      'per_page' => 1, 
      'display' => "full"
    ));
    

    Example Response

    [
      {
        "id": 1,
        "when": "2000-01-01 01:00:00 UTC",
        "destination": "/to_path",
        "display": "full",
        "ip": "192.283.128.182",
        "path": "path",
        "source": "/from_path",
        "targets": [
    
        ],
        "user_id": 1,
        "username": "user",
        "action": "create",
        "failure_type": "none",
        "interface": "web"
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <histories type="array">
      <history>
        <id type="integer">1</id>
        <when type="dateTime">2000-01-01T01:00:00Z</when>
        <destination>/to_path</destination>
        <display>full</display>
        <ip>192.283.128.182</ip>
        <path>path</path>
        <source>/from_path</source>
        <targets type="array"/>
        <user_id type="integer">1</user_id>
        <username>user</username>
        <action>create</action>
        <failure_type>none</failure_type>
        <interface>web</interface>
      </history>
    </histories>
    
    

    HTTPS Request

    GET /history/files(/*path)

    Request Parameters

    Parameter Description
    path string History path.
    page int64 Current page.
    per_page int64 History actions per page.
    start_at string Leave blank or set to a date/time to filter earlier entries.
    end_at string Leave blank or set to a date/time to filter later entries.
    display string Display format. Leave blank or set to full or parent.

    List history for specific folder

    Example Request

    curl https://app.files.com/api/rest/v1/history/folders(/*path).json \
      -H 'Content-Type: application/json' \
      -d '{"page":1,"per_page":1,"display":"full"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/history/folders(/*path).xml ]
      -H 'Content-Type: application/xml' \
      -d '<histories>
           <page type="integer">1</page>
           <per_page type="integer">1</per_page>
           <display>full</display>
         </histories>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::History.list_for_folder(path, 
      page: 1, 
      per_page: 1, 
      display: "full"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\History::listForFolder($path, array(
      'page' => 1, 
      'per_page' => 1, 
      'display' => "full"
    ));
    

    Example Response

    [
      {
        "id": 1,
        "when": "2000-01-01 01:00:00 UTC",
        "destination": "/to_path",
        "display": "full",
        "ip": "192.283.128.182",
        "path": "path",
        "source": "/from_path",
        "targets": [
    
        ],
        "user_id": 1,
        "username": "user",
        "action": "create",
        "failure_type": "none",
        "interface": "web"
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <histories type="array">
      <history>
        <id type="integer">1</id>
        <when type="dateTime">2000-01-01T01:00:00Z</when>
        <destination>/to_path</destination>
        <display>full</display>
        <ip>192.283.128.182</ip>
        <path>path</path>
        <source>/from_path</source>
        <targets type="array"/>
        <user_id type="integer">1</user_id>
        <username>user</username>
        <action>create</action>
        <failure_type>none</failure_type>
        <interface>web</interface>
      </history>
    </histories>
    
    

    HTTPS Request

    GET /history/folders(/*path)

    Request Parameters

    Parameter Description
    path string History path.
    page int64 Current page.
    per_page int64 History actions per page.
    start_at string Leave blank or set to a date/time to filter earlier entries.
    end_at string Leave blank or set to a date/time to filter later entries.
    display string Display format. Leave blank or set to full or parent.

    List history for specific user

    Example Request

    curl https://app.files.com/api/rest/v1/history/users/{user_id}.json \
      -H 'Content-Type: application/json' \
      -d '{"page":1,"per_page":1,"display":"full"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/history/users/{user_id}.xml ]
      -H 'Content-Type: application/xml' \
      -d '<histories>
           <page type="integer">1</page>
           <per_page type="integer">1</per_page>
           <display>full</display>
         </histories>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::History.list_for_user(user_id, 
      page: 1, 
      per_page: 1, 
      display: "full"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\History::listForUser($user_id, array(
      'page' => 1, 
      'per_page' => 1, 
      'display' => "full"
    ));
    

    Example Response

    [
      {
        "id": 1,
        "when": "2000-01-01 01:00:00 UTC",
        "destination": "/to_path",
        "display": "full",
        "ip": "192.283.128.182",
        "path": "path",
        "source": "/from_path",
        "targets": [
    
        ],
        "user_id": 1,
        "username": "user",
        "action": "create",
        "failure_type": "none",
        "interface": "web"
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <histories type="array">
      <history>
        <id type="integer">1</id>
        <when type="dateTime">2000-01-01T01:00:00Z</when>
        <destination>/to_path</destination>
        <display>full</display>
        <ip>192.283.128.182</ip>
        <path>path</path>
        <source>/from_path</source>
        <targets type="array"/>
        <user_id type="integer">1</user_id>
        <username>user</username>
        <action>create</action>
        <failure_type>none</failure_type>
        <interface>web</interface>
      </history>
    </histories>
    
    

    HTTPS Request

    GET /history/users/{user_id}

    Request Parameters

    Parameter Description
    user_id int64 Required User ID.
    page int64 Current page.
    per_page int64 History actions per page.
    start_at string Leave blank or set to a date/time to filter earlier entries.
    end_at string Leave blank or set to a date/time to filter later entries.
    display string Display format. Leave blank or set to full or parent.

    List site login history

    Example Request

    curl https://app.files.com/api/rest/v1/history/login.json \
      -H 'Content-Type: application/json' \
      -d '{"page":1,"per_page":1,"display":"full"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/history/login.xml ]
      -H 'Content-Type: application/xml' \
      -d '<histories>
           <page type="integer">1</page>
           <per_page type="integer">1</per_page>
           <display>full</display>
         </histories>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::History.list_logins(
      page: 1, 
      per_page: 1, 
      display: "full"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\History::listLogins(array(
      'page' => 1, 
      'per_page' => 1, 
      'display' => "full"
    ));
    

    Example Response

    [
      {
        "id": 1,
        "when": "2000-01-01 01:00:00 UTC",
        "destination": "/to_path",
        "display": "full",
        "ip": "192.283.128.182",
        "path": "path",
        "source": "/from_path",
        "targets": [
    
        ],
        "user_id": 1,
        "username": "user",
        "action": "create",
        "failure_type": "none",
        "interface": "web"
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <histories type="array">
      <history>
        <id type="integer">1</id>
        <when type="dateTime">2000-01-01T01:00:00Z</when>
        <destination>/to_path</destination>
        <display>full</display>
        <ip>192.283.128.182</ip>
        <path>path</path>
        <source>/from_path</source>
        <targets type="array"/>
        <user_id type="integer">1</user_id>
        <username>user</username>
        <action>create</action>
        <failure_type>none</failure_type>
        <interface>web</interface>
      </history>
    </histories>
    
    

    HTTPS Request

    GET /history/login

    Request Parameters

    Parameter Description
    page int64 Login actions page.
    per_page int64 Login actions to display per page.
    start_at string Leave blank or set to a date/time to filter earlier entries.
    end_at string Leave blank or set to a date/time to filter later entries.
    display string Display format. Leave blank or set to full or parent.

    List site actions history

    Example Request

    curl https://app.files.com/api/rest/v1/history.json \
      -H 'Content-Type: application/json' \
      -d '{"page":1,"per_page":1,"display":"full"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/history.xml ]
      -H 'Content-Type: application/xml' \
      -d '<histories>
           <page type="integer">1</page>
           <per_page type="integer">1</per_page>
           <display>full</display>
         </histories>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::History.list(
      page: 1, 
      per_page: 1, 
      display: "full"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\History::list(array(
      'page' => 1, 
      'per_page' => 1, 
      'display' => "full"
    ));
    

    Example Response

    [
      {
        "id": 1,
        "when": "2000-01-01 01:00:00 UTC",
        "destination": "/to_path",
        "display": "full",
        "ip": "192.283.128.182",
        "path": "path",
        "source": "/from_path",
        "targets": [
    
        ],
        "user_id": 1,
        "username": "user",
        "action": "create",
        "failure_type": "none",
        "interface": "web"
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <histories type="array">
      <history>
        <id type="integer">1</id>
        <when type="dateTime">2000-01-01T01:00:00Z</when>
        <destination>/to_path</destination>
        <display>full</display>
        <ip>192.283.128.182</ip>
        <path>path</path>
        <source>/from_path</source>
        <targets type="array"/>
        <user_id type="integer">1</user_id>
        <username>user</username>
        <action>create</action>
        <failure_type>none</failure_type>
        <interface>web</interface>
      </history>
    </histories>
    
    

    HTTPS Request

    GET /history

    Request Parameters

    Parameter Description
    page int64 Site actions page.
    per_page int64 Site actions to display per page.
    start_at string Leave blank or set to a date/time to filter earlier entries.
    end_at string Leave blank or set to a date/time to filter later entries.
    display string Display format. Leave blank or set to full or parent.

    Locks

    The Locks resource in the REST API allows you to operate on Locks. Locks are not used by Files.com's web interface, but can be used by your applications to implement locking and concurrency features.

    Our lock feature is designed to emulate the locking feature offered by WebDAV. You can read the WebDAV spec and understand how all of the below endpoints work.

    Files.com's WebDAV implementation does leverage this locking API.

    The Lock object

    Example Lock Object

    {
      "timeout": 43200,
      "depth": "infinity",
      "owner": "user",
      "path": "locked_file",
      "scope": "shared",
      "token": "17c54824e9931a4688ca032d03f6663c",
      "type": "write",
      "user_id": 1,
      "username": "username"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <lock>
      <timeout type="integer">43200</timeout>
      <depth>infinity</depth>
      <owner>user</owner>
      <path>locked_file</path>
      <scope>shared</scope>
      <token>17c54824e9931a4688ca032d03f6663c</token>
      <type>write</type>
      <user_id type="integer">1</user_id>
      <username>username</username>
    </lock>
    
    
    Attribute Description
    timeout int64 Lock timeout
    depth string Lock depth (0 or infinity)
    owner string Owner of lock. This can be any arbitrary string.
    path string Path This must be slash-delimited, but it must neither start nor end with a slash. Maximum of 5000 characters.
    scope string Lock scope(shared or exclusive)
    token string Lock token. Use to release lock.
    type string Lock type
    user_id int64 Lock creator user ID
    username string Lock creator username

    List locks at path

    Example Request

    curl https://app.files.com/api/rest/v1/locks/{path} \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/locks/{path} ]
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Lock.list(path)
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Lock::list($path);
    

    Example Response

    [
      {
        "timeout": 43200,
        "depth": "infinity",
        "owner": "user",
        "path": "locked_file",
        "scope": "shared",
        "token": "17c54824e9931a4688ca032d03f6663c",
        "type": "write",
        "user_id": 1,
        "username": "username"
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <locks type="array">
      <lock>
        <timeout type="integer">43200</timeout>
        <depth>infinity</depth>
        <owner>user</owner>
        <path>locked_file</path>
        <scope>shared</scope>
        <token>17c54824e9931a4688ca032d03f6663c</token>
        <type>write</type>
        <user_id type="integer">1</user_id>
        <username>username</username>
      </lock>
    </locks>
    
    

    HTTPS Request

    GET /locks/?*path

    Request Parameters

    Parameter Description
    path string Required

    Create lock

    Example Request

    curl https://app.files.com/api/rest/v1/locks/{path} \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{"timeout":1}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/locks/{path} ]
      -X POST \
      -H 'Content-Type: application/xml' \
      -d '<lock>
           <timeout type="integer">1</timeout>
         </lock>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Lock.create(path, 
      timeout: 1
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Lock::create($path, array(
      'timeout' => 1
    ));
    

    Example Response

    {
      "timeout": 43200,
      "depth": "infinity",
      "owner": "user",
      "path": "locked_file",
      "scope": "shared",
      "token": "17c54824e9931a4688ca032d03f6663c",
      "type": "write",
      "user_id": 1,
      "username": "username"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <lock>
      <timeout type="integer">43200</timeout>
      <depth>infinity</depth>
      <owner>user</owner>
      <path>locked_file</path>
      <scope>shared</scope>
      <token>17c54824e9931a4688ca032d03f6663c</token>
      <type>write</type>
      <user_id type="integer">1</user_id>
      <username>username</username>
    </lock>
    
    

    HTTPS Request

    POST /locks/?*path

    Request Parameters

    Parameter Description
    path string Required Path
    timeout int64 Lock timeout length

    Delete lock

    Example Request

    curl https://app.files.com/api/rest/v1/locks/{path} \
      -X DELETE \
      -H 'Content-Type: application/json' \
      -d '{"token":"token"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/locks/{path} ]
      -X DELETE \
      -H 'Content-Type: application/xml' \
      -d '<lock>
           <token>token</token>
         </lock>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Lock.delete(path, 
      token: "token"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Lock::delete($path, array(
      'token' => "token"
    ));
    

    Example Response

    No response.
    
    No response.
    

    HTTPS Request

    DELETE /locks/?*path

    Request Parameters

    Parameter Description
    path string Required Path
    token string Required Lock token

    Notifications

    The Notifications resource in the REST API allows you to operate on Notifications. Notifications are our feature that send E-Mails when new files are uploaded into a folder.

    The Notification object

    Example Notification Object

    {
      "id": 1,
      "group_id": 1,
      "group_name": "",
      "notify_user_actions": true,
      "notify_on_copy": true,
      "path": "path",
      "send_interval": "fifteen_minutes",
      "unsubscribed": true,
      "unsubscribed_reason": "",
      "user_id": 1,
      "username": "User"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <notification>
      <id type="integer">1</id>
      <group_id type="integer">1</group_id>
      <group_name></group_name>
      <notify_user_actions type="boolean">true</notify_user_actions>
      <notify_on_copy type="boolean">true</notify_on_copy>
      <path>path</path>
      <send_interval>fifteen_minutes</send_interval>
      <unsubscribed type="boolean">true</unsubscribed>
      <unsubscribed_reason></unsubscribed_reason>
      <user_id type="integer">1</user_id>
      <username>User</username>
    </notification>
    
    
    Attribute Description
    id int64 Notification ID
    group_id int64 Notification group id
    group_name string Group name if applicable
    notify_user_actions boolean Trigger notification on notification user actions?
    notify_on_copy boolean Triggers notification when moving or copying files to this path
    path string Folder path to notify on This must be slash-delimited, but it must neither start nor end with a slash. Maximum of 5000 characters.
    send_interval string The time interval that notifications are aggregated to. Can be five_minutes, fifteen_minutes, hourly, or daily
    unsubscribed boolean Is the user unsubscribed from this notification?
    unsubscribed_reason string The reason that the user unsubscribed. Can be none, unsubscribe_link_clicked, mail_bounced, or mail_marked_as_spam.
    user_id int64 Notification user ID
    username string Notification username

    List notifications

    Example Request

    curl https://app.files.com/api/rest/v1/notifications.json \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/notifications.xml ]
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Notification.list
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Notification::list();
    

    Example Response

    [
      {
        "id": 1,
        "group_id": 1,
        "group_name": "",
        "notify_user_actions": true,
        "notify_on_copy": true,
        "path": "path",
        "send_interval": "fifteen_minutes",
        "unsubscribed": true,
        "unsubscribed_reason": "",
        "user_id": 1,
        "username": "User"
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <notifications type="array">
      <notification>
        <id type="integer">1</id>
        <group_id type="integer">1</group_id>
        <group_name></group_name>
        <notify_user_actions type="boolean">true</notify_user_actions>
        <notify_on_copy type="boolean">true</notify_on_copy>
        <path>path</path>
        <send_interval>fifteen_minutes</send_interval>
        <unsubscribed type="boolean">true</unsubscribed>
        <unsubscribed_reason></unsubscribed_reason>
        <user_id type="integer">1</user_id>
        <username>User</username>
      </notification>
    </notifications>
    
    

    HTTPS Request

    GET /notifications

    Create notification

    Example Request

    curl https://app.files.com/api/rest/v1/notifications.json \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{"group_id":1,"notify_on_copy":true,"notify_user_actions":true,"path":"path","send_interval":"daily","user_id":1,"username":"User"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/notifications.xml ]
      -X POST \
      -H 'Content-Type: application/xml' \
      -d '<notification>
           <group_id type="integer">1</group_id>
           <notify_on_copy type="boolean">true</notify_on_copy>
           <notify_user_actions type="boolean">true</notify_user_actions>
           <path>path</path>
           <send_interval>daily</send_interval>
           <user_id type="integer">1</user_id>
           <username>User</username>
         </notification>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Notification.create(
      group_id: 1, 
      notify_on_copy: true, 
      notify_user_actions: true, 
      path: "path", 
      send_interval: "daily", 
      user_id: 1, 
      username: "User"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Notification::create(array(
      'group_id' => 1, 
      'notify_on_copy' => true, 
      'notify_user_actions' => true, 
      'path' => "path", 
      'send_interval' => "daily", 
      'user_id' => 1, 
      'username' => "User"
    ));
    

    Example Response

    {
      "id": 1,
      "group_id": 1,
      "group_name": "",
      "notify_user_actions": true,
      "notify_on_copy": true,
      "path": "path",
      "send_interval": "fifteen_minutes",
      "unsubscribed": true,
      "unsubscribed_reason": "",
      "user_id": 1,
      "username": "User"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <notification>
      <id type="integer">1</id>
      <group_id type="integer">1</group_id>
      <group_name></group_name>
      <notify_user_actions type="boolean">true</notify_user_actions>
      <notify_on_copy type="boolean">true</notify_on_copy>
      <path>path</path>
      <send_interval>fifteen_minutes</send_interval>
      <unsubscribed type="boolean">true</unsubscribed>
      <unsubscribed_reason></unsubscribed_reason>
      <user_id type="integer">1</user_id>
      <username>User</username>
    </notification>
    
    

    HTTPS Request

    POST /notifications

    Request Parameters

    Parameter Description
    group_id int64 The ID of the group to notify. Provide user_id, username or group_id.
    notify_on_copy boolean If true, copying or moving resources into this path will trigger a notification, in addition to just uploads.
    notify_user_actions boolean If true actions initiated by the user will still result in a notification
    path string Path
    send_interval string The time interval that notifications are aggregated by. Can be five_minutes, fifteen_minutes, hourly, or daily.
    user_id int64 The id of the user to notify. Provide user_id, username or group_id.
    username string The username of the user to notify. Provide user_id, username or group_id.

    Update notification

    Example Request

    curl https://app.files.com/api/rest/v1/notifications/{id}.json \
      -X PUT \
      -H 'Content-Type: application/json' \
      -d '{"notify_on_copy":true,"notify_user_actions":true,"send_interval":"daily"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/notifications/{id}.xml ]
      -X PUT \
      -H 'Content-Type: application/xml' \
      -d '<notification>
           <notify_on_copy type="boolean">true</notify_on_copy>
           <notify_user_actions type="boolean">true</notify_user_actions>
           <send_interval>daily</send_interval>
         </notification>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    notification = Files::Notification.find(1)
    notification.update(
      notify_on_copy: true,
      notify_user_actions: true,
      send_interval: "daily"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $notification = \Files\Notification->find(1);
    $notification->update(array(
      'notify_on_copy' => true, 
      'notify_user_actions' => true, 
      'send_interval' => "daily"
    ));
    

    Example Response

    {
      "id": 1,
      "group_id": 1,
      "group_name": "",
      "notify_user_actions": true,
      "notify_on_copy": true,
      "path": "path",
      "send_interval": "fifteen_minutes",
      "unsubscribed": true,
      "unsubscribed_reason": "",
      "user_id": 1,
      "username": "User"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <notification>
      <id type="integer">1</id>
      <group_id type="integer">1</group_id>
      <group_name></group_name>
      <notify_user_actions type="boolean">true</notify_user_actions>
      <notify_on_copy type="boolean">true</notify_on_copy>
      <path>path</path>
      <send_interval>fifteen_minutes</send_interval>
      <unsubscribed type="boolean">true</unsubscribed>
      <unsubscribed_reason></unsubscribed_reason>
      <user_id type="integer">1</user_id>
      <username>User</username>
    </notification>
    
    

    HTTPS Request

    PUT /notifications/{id}

    Request Parameters

    Parameter Description
    notify_on_copy boolean If true, copying or moving resources into this path will trigger a notification, in addition to just uploads.
    notify_user_actions boolean If true actions initiated by the user will still result in a notification
    send_interval string The time interval that notifications are aggregated by. Can be five_minutes, fifteen_minutes, hourly, or daily.
    id int64 Required

    Delete notification

    Example Request

    curl https://app.files.com/api/rest/v1/notifications/{id}.json \
      -X DELETE \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/notifications/{id}.xml ]
      -X DELETE \
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    notification = Files::Notification.find(1)
    notification.delete
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $notification = \Files\Notification->find(1);
    $notification->delete();
    

    Example Response

    No response.
    
    No response.
    

    HTTPS Request

    DELETE /notifications/{id}

    Request Parameters

    Parameter Description
    id int64 Required Notification ID.

    Permissions

    The Permissions resource in the REST API allows you to operate on Permissions.

    The Permission object

    Example Permission Object

    {
      "id": 1,
      "user_id": 1,
      "username": "Sser",
      "group_id": 1,
      "group_name": "",
      "path": "",
      "permission": "full",
      "recursive": true
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <permission>
      <id type="integer">1</id>
      <user_id type="integer">1</user_id>
      <username>Sser</username>
      <group_id type="integer">1</group_id>
      <group_name></group_name>
      <path></path>
      <permission>full</permission>
      <recursive type="boolean">true</recursive>
    </permission>
    
    
    Attribute Description
    id int64 Permission ID
    user_id int64 User ID
    username string User's username
    group_id int64 Group ID
    group_name string Group name if applicable
    path string Folder path This must be slash-delimited, but it must neither start nor end with a slash. Maximum of 5000 characters.
    permission string Permission type. Can be full, readonly, writeonly, previewonly, or history
    recursive boolean Does this permission apply to subfolders?

    List permissions

    Example Request

    curl https://app.files.com/api/rest/v1/permissions.json \
      -H 'Content-Type: application/json' \
      -d '{"path":""}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/permissions.xml ]
      -H 'Content-Type: application/xml' \
      -d '<permissions>
           <path></path>
         </permissions>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Permission.list(
      path: ""
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Permission::list(array(
      'path' => ""
    ));
    

    Example Response

    [
      {
        "id": 1,
        "user_id": 1,
        "username": "Sser",
        "group_id": 1,
        "group_name": "",
        "path": "",
        "permission": "full",
        "recursive": true
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <permissions type="array">
      <permission>
        <id type="integer">1</id>
        <user_id type="integer">1</user_id>
        <username>Sser</username>
        <group_id type="integer">1</group_id>
        <group_name></group_name>
        <path></path>
        <permission>full</permission>
        <recursive type="boolean">true</recursive>
      </permission>
    </permissions>
    
    

    HTTPS Request

    GET /permissions

    Request Parameters

    Parameter Description
    path string Permission path.

    List group's permissions

    Example Request

    curl https://app.files.com/api/rest/v1/groups/{id}/permissions.json \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/groups/{id}/permissions.xml ]
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    group = Files::Group.find(1)
    group.permissions
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $group = \Files\Group->find(1);
    $group->permissions();
    

    Example Response

    [
      {
        "id": 1,
        "user_id": 1,
        "username": "Sser",
        "group_id": 1,
        "group_name": "",
        "path": "",
        "permission": "full",
        "recursive": true
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <permissions type="array">
      <permission>
        <id type="integer">1</id>
        <user_id type="integer">1</user_id>
        <username>Sser</username>
        <group_id type="integer">1</group_id>
        <group_name></group_name>
        <path></path>
        <permission>full</permission>
        <recursive type="boolean">true</recursive>
      </permission>
    </permissions>
    
    

    HTTPS Request

    GET /groups/{id}/permissions

    Request Parameters

    Parameter Description
    id int64 Required Group ID.

    List user's permissions

    Example Request

    curl https://app.files.com/api/rest/v1/users/{id}/permissions.json \
      -H 'Content-Type: application/json' \
      -d '{"include_groups":true}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/users/{id}/permissions.xml ]
      -H 'Content-Type: application/xml' \
      -d '<permissions>
           <include_groups type="boolean">true</include_groups>
         </permissions>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    user = Files::User.find(1)
    user.permissions(
      include_groups: true
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $user = \Files\User->find(1);
    $user->permissions(array(
      'include_groups' => true
    ));
    

    Example Response

    [
      {
        "id": 1,
        "user_id": 1,
        "username": "Sser",
        "group_id": 1,
        "group_name": "",
        "path": "",
        "permission": "full",
        "recursive": true
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <permissions type="array">
      <permission>
        <id type="integer">1</id>
        <user_id type="integer">1</user_id>
        <username>Sser</username>
        <group_id type="integer">1</group_id>
        <group_name></group_name>
        <path></path>
        <permission>full</permission>
        <recursive type="boolean">true</recursive>
      </permission>
    </permissions>
    
    

    HTTPS Request

    GET /users/{id}/permissions

    Request Parameters

    Parameter Description
    id int64 Required User ID.
    include_groups boolean Include group permissions?

    Create permission

    Example Request

    curl https://app.files.com/api/rest/v1/permissions.json \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{"group_id":1,"permission":"full","recursive":true,"user_id":1,"username":"Sser"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/permissions.xml ]
      -X POST \
      -H 'Content-Type: application/xml' \
      -d '<permission>
           <group_id type="integer">1</group_id>
           <permission>full</permission>
           <recursive type="boolean">true</recursive>
           <user_id type="integer">1</user_id>
           <username>Sser</username>
         </permission>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Permission.create(
      group_id: 1, 
      permission: "full", 
      recursive: true, 
      user_id: 1, 
      username: "Sser"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Permission::create(array(
      'group_id' => 1, 
      'permission' => "full", 
      'recursive' => true, 
      'user_id' => 1, 
      'username' => "Sser"
    ));
    

    Example Response

    {
      "id": 1,
      "user_id": 1,
      "username": "Sser",
      "group_id": 1,
      "group_name": "",
      "path": "",
      "permission": "full",
      "recursive": true
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <permission>
      <id type="integer">1</id>
      <user_id type="integer">1</user_id>
      <username>Sser</username>
      <group_id type="integer">1</group_id>
      <group_name></group_name>
      <path></path>
      <permission>full</permission>
      <recursive type="boolean">true</recursive>
    </permission>
    
    

    HTTPS Request

    POST /permissions

    Request Parameters

    Parameter Description
    group_id int64 Group ID
    path string Folder path
    permission object Permission type. Can be full, readonly, writeonly, previewonly, or history
    recursive boolean Apply to subfolders recursively?
    user_id int64 User ID. Provide username or user_id
    username string User username. Provide username or user_id

    Delete permission

    Example Request

    curl https://app.files.com/api/rest/v1/permissions/{id}.json \
      -X DELETE \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/permissions/{id}.xml ]
      -X DELETE \
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    permission = Files::Permission.find(1)
    permission.delete
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $permission = \Files\Permission->find(1);
    $permission->delete();
    

    Example Response

    No response.
    
    No response.
    

    HTTPS Request

    DELETE /permissions/{id}

    Request Parameters

    Parameter Description
    id int64 Required Permission ID.

    Public Keys

    The PublicKeys resource in the REST API allows you to operate on PublicKeys. Public keys are used by Users who want to connect via SFTP/SSH. (Note that our SSH support is limited to file operations only, no shell is provided.)

    The PublicKey object

    Example PublicKey Object

    {
      "id": 1,
      "created_at": "2000-01-01 01:00:00 UTC",
      "fingerprint": "43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8",
      "title": "My public key"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <public-key>
      <id type="integer">1</id>
      <created_at type="dateTime">2000-01-01T01:00:00Z</created_at>
      <fingerprint>43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8</fingerprint>
      <title>My public key</title>
    </public-key>
    
    
    Attribute Description
    id int64 Public key ID
    created_at date-time Public key created at date/time
    fingerprint string Public key fingerprint
    title string Public key title

    Show SSH public key

    Example Request

    curl https://app.files.com/api/rest/v1/public_keys/{id}.json \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/public_keys/{id}.xml ]
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::PublicKey.find(id)
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\PublicKey::find($id);
    

    Example Response

    {
      "id": 1,
      "created_at": "2000-01-01 01:00:00 UTC",
      "fingerprint": "43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8",
      "title": "My public key"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <public-key>
      <id type="integer">1</id>
      <created_at type="dateTime">2000-01-01T01:00:00Z</created_at>
      <fingerprint>43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8</fingerprint>
      <title>My public key</title>
    </public-key>
    
    

    HTTPS Request

    GET /public_keys/{id}

    Request Parameters

    Parameter Description
    id int64 Required SSH public key ID.

    List current user's SSH public keys

    Example Request

    curl https://app.files.com/api/rest/v1/user/public_keys.json \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/user/public_keys.xml ]
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::User.public_keys
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\User::publicKeys();
    

    Example Response

    [
      {
        "id": 1,
        "created_at": "2000-01-01 01:00:00 UTC",
        "fingerprint": "43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8",
        "title": "My public key"
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <public-keys type="array">
      <public-key>
        <id type="integer">1</id>
        <created_at type="dateTime">2000-01-01T01:00:00Z</created_at>
        <fingerprint>43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8</fingerprint>
        <title>My public key</title>
      </public-key>
    </public-keys>
    
    

    HTTPS Request

    GET /user/public_keys

    List user's SSH public keys

    Example Request

    curl https://app.files.com/api/rest/v1/users/{id}/public_keys.json \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/users/{id}/public_keys.xml ]
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    user = Files::User.find(1)
    user.public_keys
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $user = \Files\User->find(1);
    $user->publicKeys();
    

    Example Response

    [
      {
        "id": 1,
        "created_at": "2000-01-01 01:00:00 UTC",
        "fingerprint": "43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8",
        "title": "My public key"
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <public-keys type="array">
      <public-key>
        <id type="integer">1</id>
        <created_at type="dateTime">2000-01-01T01:00:00Z</created_at>
        <fingerprint>43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8</fingerprint>
        <title>My public key</title>
      </public-key>
    </public-keys>
    
    

    HTTPS Request

    GET /users/{id}/public_keys

    Request Parameters

    Parameter Description
    id int64 Required User ID.

    Create SSH public key on current user

    Example Request

    curl https://app.files.com/api/rest/v1/user/public_keys.json \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{"title":"My Main Key","public_key":"public_key"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/user/public_keys.xml ]
      -X POST \
      -H 'Content-Type: application/xml' \
      -d '<public-key>
           <title>My Main Key</title>
           <public_key>public_key</public_key>
         </public-key>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::User.create_public_key(
      title: "My Main Key", 
      public_key: "public_key"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\User::createPublicKey(array(
      'title' => "My Main Key", 
      'public_key' => "public_key"
    ));
    

    Example Response

    {
      "id": 1,
      "created_at": "2000-01-01 01:00:00 UTC",
      "fingerprint": "43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8",
      "title": "My public key"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <public-key>
      <id type="integer">1</id>
      <created_at type="dateTime">2000-01-01T01:00:00Z</created_at>
      <fingerprint>43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8</fingerprint>
      <title>My public key</title>
    </public-key>
    
    

    HTTPS Request

    POST /user/public_keys

    Request Parameters

    Parameter Description
    title string Required Internal reference for key.
    public_key string Required Actual contents of SSH key.

    Create SSH public key on a user

    Example Request

    curl https://app.files.com/api/rest/v1/users/{id}/public_keys.json \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{"title":"SSH Key Name","public_key":"[key]"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/users/{id}/public_keys.xml ]
      -X POST \
      -H 'Content-Type: application/xml' \
      -d '<public-key>
           <title>SSH Key Name</title>
           <public_key>[key]</public_key>
         </public-key>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    user = Files::User.find(1)
    user.create_public_key(
      title: "SSH Key Name",
      public_key: "[key]"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $user = \Files\User->find(1);
    $user->createPublicKey(array(
      'title' => "SSH Key Name", 
      'public_key' => "[key]"
    ));
    

    Example Response

    {
      "id": 1,
      "created_at": "2000-01-01 01:00:00 UTC",
      "fingerprint": "43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8",
      "title": "My public key"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <public-key>
      <id type="integer">1</id>
      <created_at type="dateTime">2000-01-01T01:00:00Z</created_at>
      <fingerprint>43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8</fingerprint>
      <title>My public key</title>
    </public-key>
    
    

    HTTPS Request

    POST /users/{id}/public_keys

    Request Parameters

    Parameter Description
    id int64 Required User ID.
    title string Required Internal reference for key.
    public_key string Required Actual contents of SSH key.

    Delete SSH public key

    Example Request

    curl https://app.files.com/api/rest/v1/public_keys/{id}.json \
      -X DELETE \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/public_keys/{id}.xml ]
      -X DELETE \
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    public_key = Files::PublicKey.find(1)
    public_key.delete
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $public_key = \Files\PublicKey->find(1);
    $public_key->delete();
    

    Example Response

    No response.
    
    No response.
    

    HTTPS Request

    DELETE /public_keys/{id}

    Request Parameters

    Parameter Description
    id int64 Required SSH public key ID.

    Remote Servers

    The RemoteServers resource in the REST API allows you to operate on RemoteServers. Remote servers are used with the remote_server_sync Behavior.

    Remote Servers can be either an FTP server, SFTP server, or S3 bucket. Other remote server types, such as Box, Dropbox, Rackspace Files, etc., are coming soon.

    As such, not every attribute will apply to every remote server.

    FTP Servers require that you specify their hostname, port, username, password, and a value for ssl. Optionally, provide server_certificate.

    SFTP Servers require that you specify their hostname, port, username, password or private_key, and a value for ssl. Optionally, provide server_certificate.

    S3 Buckets require that you specify their s3_bucket name, and s3_region. Optionally provide a aws_access_key, and aws_secret_key. If you don't provide credentials, you will need to use AWS to grant us access to your bucket.

    The RemoteServer object

    Example RemoteServer Object

    {
      "id": 1,
      "aws_access_key": "[aws access key]",
      "aws_secret_key": "[aws secret key]",
      "hostname": "remote-server.com",
      "name": "My Remote server",
      "password": "[password]",
      "port": 1,
      "private_key": "[private key]",
      "s3_bucket": "my-bucket",
      "s3_region": "us-east-1",
      "server_certificate": "[certificate]",
      "server_type": "s3",
      "ssl": "always",
      "username": "user"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <remote-server>
      <id type="integer">1</id>
      <aws_access_key>[aws access key]</aws_access_key>
      <aws_secret_key>[aws secret key]</aws_secret_key>
      <hostname>remote-server.com</hostname>
      <name>My Remote server</name>
      <password>[password]</password>
      <port type="integer">1</port>
      <private_key>[private key]</private_key>
      <s3_bucket>my-bucket</s3_bucket>
      <s3_region>us-east-1</s3_region>
      <server_certificate>[certificate]</server_certificate>
      <server_type>s3</server_type>
      <ssl>always</ssl>
      <username>user</username>
    </remote-server>
    
    
    Attribute Description
    id int64 Remote server ID
    aws_access_key string AWS Access Key, if connecting to S3
    aws_secret_key string AWS Secret Key, if connecting to S3
    hostname string Hostname or IP address
    name string Internal name for your reference
    password string Remote server password. For FTP or SFTP without private key authentication.
    port int64 Port for remote server. Not needed for S3.
    private_key string Private key. Needed for SFTP if authenticating via private key.
    s3_bucket string S3 bucket name
    s3_region string S3 region
    server_certificate string Remote server certificate
    server_type string Remote server type.
    ssl string Should we require SSL?
    username string Remote server username. Not needed for S3 buckets.

    List Remote Servers

    Example Request

    curl https://app.files.com/api/rest/v1/remote_servers.json \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/remote_servers.xml ]
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::RemoteServer.list
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\RemoteServer::list();
    

    Example Response

    [
      {
        "id": 1,
        "aws_access_key": "[aws access key]",
        "aws_secret_key": "[aws secret key]",
        "hostname": "remote-server.com",
        "name": "My Remote server",
        "password": "[password]",
        "port": 1,
        "private_key": "[private key]",
        "s3_bucket": "my-bucket",
        "s3_region": "us-east-1",
        "server_certificate": "[certificate]",
        "server_type": "s3",
        "ssl": "always",
        "username": "user"
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <remote-servers type="array">
      <remote-server>
        <id type="integer">1</id>
        <aws_access_key>[aws access key]</aws_access_key>
        <aws_secret_key>[aws secret key]</aws_secret_key>
        <hostname>remote-server.com</hostname>
        <name>My Remote server</name>
        <password>[password]</password>
        <port type="integer">1</port>
        <private_key>[private key]</private_key>
        <s3_bucket>my-bucket</s3_bucket>
        <s3_region>us-east-1</s3_region>
        <server_certificate>[certificate]</server_certificate>
        <server_type>s3</server_type>
        <ssl>always</ssl>
        <username>user</username>
      </remote-server>
    </remote-servers>
    
    

    HTTPS Request

    GET /remote_servers

    Show Remote Server

    Example Request

    curl https://app.files.com/api/rest/v1/remote_servers/{id}.json \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/remote_servers/{id}.xml ]
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::RemoteServer.find(id)
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\RemoteServer::find($id);
    

    Example Response

    {
      "id": 1,
      "aws_access_key": "[aws access key]",
      "aws_secret_key": "[aws secret key]",
      "hostname": "remote-server.com",
      "name": "My Remote server",
      "password": "[password]",
      "port": 1,
      "private_key": "[private key]",
      "s3_bucket": "my-bucket",
      "s3_region": "us-east-1",
      "server_certificate": "[certificate]",
      "server_type": "s3",
      "ssl": "always",
      "username": "user"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <remote-server>
      <id type="integer">1</id>
      <aws_access_key>[aws access key]</aws_access_key>
      <aws_secret_key>[aws secret key]</aws_secret_key>
      <hostname>remote-server.com</hostname>
      <name>My Remote server</name>
      <password>[password]</password>
      <port type="integer">1</port>
      <private_key>[private key]</private_key>
      <s3_bucket>my-bucket</s3_bucket>
      <s3_region>us-east-1</s3_region>
      <server_certificate>[certificate]</server_certificate>
      <server_type>s3</server_type>
      <ssl>always</ssl>
      <username>user</username>
    </remote-server>
    
    

    HTTPS Request

    GET /remote_servers/{id}

    Request Parameters

    Parameter Description
    id int64 Required Remote Server ID

    Create Remote Server

    Example Request

    curl https://app.files.com/api/rest/v1/remote_servers.json \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{"aws_access_key":"[aws access key]","aws_secret_key":"[aws secret key]","hostname":"remote-server.com","name":"My Remote server","password":"[password]","port":1,"private_key":"[private key]","s3_bucket":"my-bucket","s3_region":"us-east-1","server_certificate":"[certificate]","server_type":"s3","ssl":"always","username":"user"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/remote_servers.xml ]
      -X POST \
      -H 'Content-Type: application/xml' \
      -d '<remote-server>
           <aws_access_key>[aws access key]</aws_access_key>
           <aws_secret_key>[aws secret key]</aws_secret_key>
           <hostname>remote-server.com</hostname>
           <name>My Remote server</name>
           <password>[password]</password>
           <port type="integer">1</port>
           <private_key>[private key]</private_key>
           <s3_bucket>my-bucket</s3_bucket>
           <s3_region>us-east-1</s3_region>
           <server_certificate>[certificate]</server_certificate>
           <server_type>s3</server_type>
           <ssl>always</ssl>
           <username>user</username>
         </remote-server>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::RemoteServer.create(
      aws_access_key: "[aws access key]", 
      aws_secret_key: "[aws secret key]", 
      hostname: "remote-server.com", 
      name: "My Remote server", 
      password: "[password]", 
      port: 1, 
      private_key: "[private key]", 
      s3_bucket: "my-bucket", 
      s3_region: "us-east-1", 
      server_certificate: "[certificate]", 
      server_type: "s3", 
      ssl: "always", 
      username: "user"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\RemoteServer::create(array(
      'aws_access_key' => "[aws access key]", 
      'aws_secret_key' => "[aws secret key]", 
      'hostname' => "remote-server.com", 
      'name' => "My Remote server", 
      'password' => "[password]", 
      'port' => 1, 
      'private_key' => "[private key]", 
      's3_bucket' => "my-bucket", 
      's3_region' => "us-east-1", 
      'server_certificate' => "[certificate]", 
      'server_type' => "s3", 
      'ssl' => "always", 
      'username' => "user"
    ));
    

    Example Response

    {
      "id": 1,
      "aws_access_key": "[aws access key]",
      "aws_secret_key": "[aws secret key]",
      "hostname": "remote-server.com",
      "name": "My Remote server",
      "password": "[password]",
      "port": 1,
      "private_key": "[private key]",
      "s3_bucket": "my-bucket",
      "s3_region": "us-east-1",
      "server_certificate": "[certificate]",
      "server_type": "s3",
      "ssl": "always",
      "username": "user"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <remote-server>
      <id type="integer">1</id>
      <aws_access_key>[aws access key]</aws_access_key>
      <aws_secret_key>[aws secret key]</aws_secret_key>
      <hostname>remote-server.com</hostname>
      <name>My Remote server</name>
      <password>[password]</password>
      <port type="integer">1</port>
      <private_key>[private key]</private_key>
      <s3_bucket>my-bucket</s3_bucket>
      <s3_region>us-east-1</s3_region>
      <server_certificate>[certificate]</server_certificate>
      <server_type>s3</server_type>
      <ssl>always</ssl>
      <username>user</username>
    </remote-server>
    
    

    HTTPS Request

    POST /remote_servers

    Request Parameters

    Parameter Description
    aws_access_key string AWS Access Key.
    aws_secret_key string AWS secret key.
    hostname string Hostname.
    name string Internal reference name for server.
    password string Password if needed.
    port string Port.
    private_key string Private key if needed.
    s3_bucket string S3 bucket name.
    s3_region string S3 region.
    server_certificate string Certificate for this server.
    server_type string Type of server. Can be ftp, sftp, or s3.
    ssl string SSL requirements. Can be if_available, require, require_implicit, never.
    username string Server username if needed.

    Update Remote Server

    Example Request

    curl https://app.files.com/api/rest/v1/remote_servers/{id}.json \
      -X PATCH \
      -H 'Content-Type: application/json' \
      -d '{"aws_access_key":"[aws access key]","aws_secret_key":"[aws secret key]","hostname":"remote-server.com","name":"My Remote server","password":"[password]","port":1,"private_key":"[private key]","s3_bucket":"my-bucket","s3_region":"us-east-1","server_certificate":"[certificate]","server_type":"s3","ssl":"always","username":"user"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/remote_servers/{id}.xml ]
      -X PATCH \
      -H 'Content-Type: application/xml' \
      -d '<remote-server>
           <aws_access_key>[aws access key]</aws_access_key>
           <aws_secret_key>[aws secret key]</aws_secret_key>
           <hostname>remote-server.com</hostname>
           <name>My Remote server</name>
           <password>[password]</password>
           <port type="integer">1</port>
           <private_key>[private key]</private_key>
           <s3_bucket>my-bucket</s3_bucket>
           <s3_region>us-east-1</s3_region>
           <server_certificate>[certificate]</server_certificate>
           <server_type>s3</server_type>
           <ssl>always</ssl>
           <username>user</username>
         </remote-server>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    remote_server = Files::RemoteServer.find(1)
    remote_server.update(
      aws_access_key: "[aws access key]",
      aws_secret_key: "[aws secret key]",
      hostname: "remote-server.com",
      name: "My Remote server",
      password: "[password]",
      port: 1,
      private_key: "[private key]",
      s3_bucket: "my-bucket",
      s3_region: "us-east-1",
      server_certificate: "[certificate]",
      server_type: "s3",
      ssl: "always",
      username: "user"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $remote_server = \Files\RemoteServer->find(1);
    $remote_server->update(array(
      'aws_access_key' => "[aws access key]", 
      'aws_secret_key' => "[aws secret key]", 
      'hostname' => "remote-server.com", 
      'name' => "My Remote server", 
      'password' => "[password]", 
      'port' => 1, 
      'private_key' => "[private key]", 
      's3_bucket' => "my-bucket", 
      's3_region' => "us-east-1", 
      'server_certificate' => "[certificate]", 
      'server_type' => "s3", 
      'ssl' => "always", 
      'username' => "user"
    ));
    

    Example Response

    {
      "id": 1,
      "aws_access_key": "[aws access key]",
      "aws_secret_key": "[aws secret key]",
      "hostname": "remote-server.com",
      "name": "My Remote server",
      "password": "[password]",
      "port": 1,
      "private_key": "[private key]",
      "s3_bucket": "my-bucket",
      "s3_region": "us-east-1",
      "server_certificate": "[certificate]",
      "server_type": "s3",
      "ssl": "always",
      "username": "user"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <remote-server>
      <id type="integer">1</id>
      <aws_access_key>[aws access key]</aws_access_key>
      <aws_secret_key>[aws secret key]</aws_secret_key>
      <hostname>remote-server.com</hostname>
      <name>My Remote server</name>
      <password>[password]</password>
      <port type="integer">1</port>
      <private_key>[private key]</private_key>
      <s3_bucket>my-bucket</s3_bucket>
      <s3_region>us-east-1</s3_region>
      <server_certificate>[certificate]</server_certificate>
      <server_type>s3</server_type>
      <ssl>always</ssl>
      <username>user</username>
    </remote-server>
    
    

    HTTPS Request

    PATCH /remote_servers/{id}

    Request Parameters

    Parameter Description
    id int64 Required Remote Server ID
    aws_access_key string AWS Access Key.
    aws_secret_key string AWS secret key.
    hostname string Hostname.
    name string Internal reference name for server.
    password string Password if needed.
    port string Port.
    private_key string Private key if needed.
    s3_bucket string S3 bucket name.
    s3_region string S3 region.
    server_certificate string Certificate for this server.
    server_type string Type of server. Can be ftp, sftp, or s3.
    ssl string SSL requirements. Can be if_available, require, require_implicit, never.
    username string Server username if needed.

    Delete Remote Server

    Example Request

    curl https://app.files.com/api/rest/v1/remote_servers/{id}.json \
      -X DELETE \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/remote_servers/{id}.xml ]
      -X DELETE \
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    remote_server = Files::RemoteServer.find(1)
    remote_server.delete
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $remote_server = \Files\RemoteServer->find(1);
    $remote_server->delete();
    

    Example Response

    No response.
    
    No response.
    

    HTTPS Request

    DELETE /remote_servers/{id}

    Request Parameters

    Parameter Description
    id int64 Required Remote Server ID.

    Requests

    The Requests resource in the REST API allows you to operate on Requests.

    The Request object

    Example Request Object

    {
      "id": 1,
      "path": "",
      "source": "",
      "destination": "",
      "automation_id": "",
      "user_display_name": ""
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <request>
      <id type="integer">1</id>
      <path></path>
      <source></source>
      <destination></destination>
      <automation_id></automation_id>
      <user_display_name></user_display_name>
    </request>
    
    
    Attribute Description
    id int64 Request ID
    path string Folder path This must be slash-delimited, but it must neither start nor end with a slash. Maximum of 5000 characters.
    source string Source filename, if applicable
    destination string Destination filename
    automation_id string ID of automation that created request
    user_display_name string User making the request (if applicable)

    List Requests

    Example Request

    curl https://app.files.com/api/rest/v1/requests.json \
      -H 'Content-Type: application/json' \
      -d '{"mine":true}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/requests.xml ]
      -H 'Content-Type: application/xml' \
      -d '<requests>
           <mine type="boolean">true</mine>
         </requests>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Request.list(
      mine: true
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Request::list(array(
      'mine' => true
    ));
    

    Example Response

    [
      {
        "id": 1,
        "path": "",
        "source": "",
        "destination": "",
        "automation_id": "",
        "user_display_name": ""
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <requests type="array">
      <request>
        <id type="integer">1</id>
        <path></path>
        <source></source>
        <destination></destination>
        <automation_id></automation_id>
        <user_display_name></user_display_name>
      </request>
    </requests>
    
    

    HTTPS Request

    GET /requests

    Request Parameters

    Parameter Description
    mine boolean Only show requests of the current user? (Defaults to true if current user is not a site admin.)

    List Requests by path

    Example Request

    curl https://app.files.com/api/rest/v1/requests/folders/{path} \
      -H 'Content-Type: application/json' \
      -d '{"mine":true}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/requests/folders/{path} ]
      -H 'Content-Type: application/xml' \
      -d '<requests>
           <mine type="boolean">true</mine>
         </requests>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Request.folders(path, 
      mine: true
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Request::folders($path, array(
      'mine' => true
    ));
    

    Example Response

    [
      {
        "id": 1,
        "path": "",
        "source": "",
        "destination": "",
        "automation_id": "",
        "user_display_name": ""
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <requests type="array">
      <request>
        <id type="integer">1</id>
        <path></path>
        <source></source>
        <destination></destination>
        <automation_id></automation_id>
        <user_display_name></user_display_name>
      </request>
    </requests>
    
    

    HTTPS Request

    GET /requests/folders/?*path

    Request Parameters

    Parameter Description
    path string Required Path to search.
    mine boolean Only show requests of the current user? (Defaults to true if current user is not a site admin.)

    Create Request

    Example Request

    curl https://app.files.com/api/rest/v1/requests.json \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{"path":"path","destination":"destination"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/requests.xml ]
      -X POST \
      -H 'Content-Type: application/xml' \
      -d '<request>
           <path>path</path>
           <destination>destination</destination>
         </request>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Request.create(
      path: "path", 
      destination: "destination"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Request::create(array(
      'path' => "path", 
      'destination' => "destination"
    ));
    

    Example Response

    {
      "id": 1,
      "path": "",
      "source": "",
      "destination": "",
      "automation_id": "",
      "user_display_name": ""
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <request>
      <id type="integer">1</id>
      <path></path>
      <source></source>
      <destination></destination>
      <automation_id></automation_id>
      <user_display_name></user_display_name>
    </request>
    
    

    HTTPS Request

    POST /requests

    Request Parameters

    Parameter Description
    path string Required Folder path on which to request the file.
    destination string Required Destination filename (without extension) to request.
    user_ids string A list of user IDs to request the file from. If sent as a string, it should be comma-delimited.
    group_ids string A list of group IDs to request the file from. If sent as a string, it should be comma-delimited.

    Delete Request

    Example Request

    curl https://app.files.com/api/rest/v1/requests/{id}.json \
      -X DELETE \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/requests/{id}.xml ]
      -X DELETE \
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    request = Files::Request.find(1)
    request.delete
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $request = \Files\Request->find(1);
    $request->delete();
    

    Example Response

    No response.
    
    No response.
    

    HTTPS Request

    DELETE /requests/{id}

    Request Parameters

    Parameter Description
    id int64 Required Request ID.

    Sessions

    The Sessions resource in the REST API allows you to operate on Sessions.

    You may use a Session to make further API calls using our REST API or SDKs as a specific user. This is the only way to use the API if you know a username/password but not an API key.

    The Session object

    Example Session Object

    {
      "id": 1,
      "language": "en",
      "login_token": "@tok-randomcode",
      "login_token_domain": "https://mysite.files.com",
      "max_dir_listing_size": 1,
      "multiple_regions": true,
      "root_path": "",
      "site_id": 1,
      "ssl_required": true,
      "tls_disabled": true,
      "two_factor_setup_needed": true,
      "allowed_2fa_method_sms": true,
      "allowed_2fa_method_totp": true,
      "allowed_2fa_method_u2f": true,
      "allowed_2fa_method_yubi": true,
      "use_provided_modified_at": true,
      "windows_mode_ftp": true
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <session>
      <id type="integer">1</id>
      <language>en</language>
      <login_token>@tok-randomcode</login_token>
      <login_token_domain>https://mysite.files.com</login_token_domain>
      <max_dir_listing_size type="integer">1</max_dir_listing_size>
      <multiple_regions type="boolean">true</multiple_regions>
      <root_path></root_path>
      <site_id type="integer">1</site_id>
      <ssl_required type="boolean">true</ssl_required>
      <tls_disabled type="boolean">true</tls_disabled>
      <two_factor_setup_needed type="boolean">true</two_factor_setup_needed>
      <allowed_2fa_method_sms type="boolean">true</allowed_2fa_method_sms>
      <allowed_2fa_method_totp type="boolean">true</allowed_2fa_method_totp>
      <allowed_2fa_method_u2f type="boolean">true</allowed_2fa_method_u2f>
      <allowed_2fa_method_yubi type="boolean">true</allowed_2fa_method_yubi>
      <use_provided_modified_at type="boolean">true</use_provided_modified_at>
      <windows_mode_ftp type="boolean">true</windows_mode_ftp>
    </session>
    
    
    Attribute Description
    id int64 Session ID
    language string Session language
    login_token string Login token. If set, this token will allow your user to log in via browser at the domain in login_token_domain.
    login_token_domain string Domain to use with login_token.
    max_dir_listing_size int64 Maximum number of files to retrieve per folder for a directory listing. This is based on the user's plan.
    multiple_regions boolean Can access multiple regions?
    root_path string Initial root path to start the user's session in.
    site_id int64 Site ID
    ssl_required boolean Is SSL required for this user? (If so, ensure all your communications with this user use SSL.)
    tls_disabled boolean Is strong TLS disabled for this user? (If this is set to true, the site administrator has signaled that it is ok to use less secure TLS versions for this user.)
    two_factor_setup_needed boolean If true, this user needs to add a Two Factor Authentication method before performing any further actions.
    allowed_2fa_method_sms boolean Sent only if 2FA setup is needed. Is SMS two factor authentication allowed?
    allowed_2fa_method_totp boolean Sent only if 2FA setup is needed. Is TOTP two factor authentication allowed?
    allowed_2fa_method_u2f boolean Sent only if 2FA setup is needed. Is U2F two factor authentication allowed?
    allowed_2fa_method_yubi boolean Sent only if 2FA setup is needed. Is Yubikey two factor authentication allowed?
    use_provided_modified_at boolean Allow the user to provide file/folder modified at dates? If false, the server will always use the current date/time.
    windows_mode_ftp boolean Does this user want to use Windows line-ending emulation? (CR vs CRLF)

    Create user session (log in)

    Example Request

    curl https://app.files.com/api/rest/v1/sessions.json \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{"username":"username","password":"password","otp":"123456"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/sessions.xml ]
      -X POST \
      -H 'Content-Type: application/xml' \
      -d '<session>
           <username>username</username>
           <password>password</password>
           <otp>123456</otp>
         </session>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Session.create(
      username: "username", 
      password: "password", 
      otp: "123456"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Session::create(array(
      'username' => "username", 
      'password' => "password", 
      'otp' => "123456"
    ));
    

    Example Response

    {
      "id": 1,
      "language": "en",
      "login_token": "@tok-randomcode",
      "login_token_domain": "https://mysite.files.com",
      "max_dir_listing_size": 1,
      "multiple_regions": true,
      "root_path": "",
      "site_id": 1,
      "ssl_required": true,
      "tls_disabled": true,
      "two_factor_setup_needed": true,
      "allowed_2fa_method_sms": true,
      "allowed_2fa_method_totp": true,
      "allowed_2fa_method_u2f": true,
      "allowed_2fa_method_yubi": true,
      "use_provided_modified_at": true,
      "windows_mode_ftp": true
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <session>
      <id type="integer">1</id>
      <language>en</language>
      <login_token>@tok-randomcode</login_token>
      <login_token_domain>https://mysite.files.com</login_token_domain>
      <max_dir_listing_size type="integer">1</max_dir_listing_size>
      <multiple_regions type="boolean">true</multiple_regions>
      <root_path></root_path>
      <site_id type="integer">1</site_id>
      <ssl_required type="boolean">true</ssl_required>
      <tls_disabled type="boolean">true</tls_disabled>
      <two_factor_setup_needed type="boolean">true</two_factor_setup_needed>
      <allowed_2fa_method_sms type="boolean">true</allowed_2fa_method_sms>
      <allowed_2fa_method_totp type="boolean">true</allowed_2fa_method_totp>
      <allowed_2fa_method_u2f type="boolean">true</allowed_2fa_method_u2f>
      <allowed_2fa_method_yubi type="boolean">true</allowed_2fa_method_yubi>
      <use_provided_modified_at type="boolean">true</use_provided_modified_at>
      <windows_mode_ftp type="boolean">true</windows_mode_ftp>
    </session>
    
    

    HTTPS Request

    POST /sessions

    Request Parameters

    Parameter Description
    username string Username to sign in as
    password string Password for sign in
    otp string If this user has a 2FA device, provide its OTP or code here.

    Delete user session (log out)

    Example Request

    curl https://app.files.com/api/rest/v1/sessions.json \
      -X DELETE \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/sessions.xml ]
      -X DELETE \
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Session.delete
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Session::delete();
    

    Example Response

    No response.
    
    No response.
    

    HTTPS Request

    DELETE /sessions

    Site

    The Site resource in the REST API allows you to operate on your Site. This is the place you'll come to update site settings, as well as manage sitewide API keys.

    Most site settings can be set via the API.

    The Site object

    Example Site Object

    {
      "allowed_2fa_method_sms": true,
      "allowed_2fa_method_totp": true,
      "allowed_2fa_method_u2f": true,
      "allowed_2fa_method_yubi": true,
      "admin_user_id": 1,
      "allowed_file_types": "",
      "allowed_ips": "",
      "ask_about_overwrites": true,
      "bundle_expiration": 1,
      "bundle_password_required": true,
      "color2_left": "#0066a7",
      "color2_link": "#d34f5d",
      "color2_text": "#0066a7",
      "color2_top": "#000000",
      "color2_top_text": "#ffffff",
      "created_at": "2000-01-01 01:00:00 UTC",
      "currency": "USD",
      "custom_namespace": true,
      "days_to_retain_backups": 30,
      "default_time_zone": "Pacific Time (US & Canada)",
      "desktop_app": true,
      "desktop_app_session_ip_pinning": true,
      "desktop_app_session_lifetime": 1,
      "disable_notifications": true,
      "disable_password_reset": true,
      "domain": "my-custom-domain.com",
      "email": "john.doe@files.com",
      "hipaa": true,
      "icon128": "",
      "icon16": "",
      "icon32": "",
      "icon48": "",
      "immutable_files_set_at": "2000-01-01 01:00:00 UTC",
      "include_password_in_welcome_email": true,
      "language": "en",
      "ldap_base_dn": "",
      "ldap_domain": "mysite.com",
      "ldap_enabled": true,
      "ldap_group_action": "disabled",
      "ldap_group_exclusion": "",
      "ldap_group_inclusion": "",
      "ldap_host": "ldap.site.com",
      "ldap_host_2": "ldap2.site.com",
      "ldap_host_3": "ldap3.site.com",
      "ldap_port": 1,
      "ldap_secure": true,
      "ldap_type": "open_ldap",
      "ldap_user_action": "disabled",
      "ldap_user_include_groups": "",
      "ldap_username": "[ldap username]",
      "ldap_username_field": "sAMAccountName",
      "login_help_text": "Login page help text.",
      "logo": "",
      "max_prior_passwords": 1,
      "name": "My Site",
      "next_billing_amount": "",
      "next_billing_date": "Apr 20",
      "opt_out_global": true,
      "overage_notified_at": "2000-01-01 01:00:00 UTC",
      "overage_notify": true,
      "overdue": true,
      "password_min_length": 1,
      "password_require_letter": true,
      "password_require_mixed": true,
      "password_require_number": true,
      "password_require_special": true,
      "password_validity_days": 1,
      "phone": "555-555-5555",
      "require_2fa": true,
      "require_2fa_stop_time": "2000-01-01 01:00:00 UTC",
      "session": "",
      "session_pinned_by_ip": true,
      "sftp_user_root_enabled": true,
      "show_request_access_link": true,
      "site_footer": "",
      "site_header": "",
      "smtp_address": "smtp.my-mail-server.com",
      "smtp_authentication": "plain",
      "smtp_from": "me@my-mail-server.com",
      "smtp_port": 25,
      "smtp_username": "mail",
      "session_expiry": 6,
      "ssl_required": true,
      "subdomain": "mysite",
      "switch_to_plan_date": "2000-01-01 01:00:00 UTC",
      "tls_disabled": true,
      "trial_days_left": 1,
      "trial_until": "2000-01-01 01:00:00 UTC",
      "updated_at": "2000-01-01 01:00:00 UTC",
      "use_provided_modified_at": true,
      "user": "",
      "user_lockout": true,
      "user_lockout_lock_period": 1,
      "user_lockout_tries": 1,
      "user_lockout_within": 6,
      "welcome_custom_text": "Welcome to my site!",
      "welcome_email_cc": "",
      "welcome_email_enabled": true,
      "windows_mode_ftp": true
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <site>
      <allowed_2fa_method_sms type="boolean">true</allowed_2fa_method_sms>
      <allowed_2fa_method_totp type="boolean">true</allowed_2fa_method_totp>
      <allowed_2fa_method_u2f type="boolean">true</allowed_2fa_method_u2f>
      <allowed_2fa_method_yubi type="boolean">true</allowed_2fa_method_yubi>
      <admin_user_id type="integer">1</admin_user_id>
      <allowed_file_types></allowed_file_types>
      <allowed_ips></allowed_ips>
      <ask_about_overwrites type="boolean">true</ask_about_overwrites>
      <bundle_expiration type="integer">1</bundle_expiration>
      <bundle_password_required type="boolean">true</bundle_password_required>
      <color2_left>#0066a7</color2_left>
      <color2_link>#d34f5d</color2_link>
      <color2_text>#0066a7</color2_text>
      <color2_top>#000000</color2_top>
      <color2_top_text>#ffffff</color2_top_text>
      <created_at type="dateTime">2000-01-01T01:00:00Z</created_at>
      <currency>USD</currency>
      <custom_namespace type="boolean">true</custom_namespace>
      <days_to_retain_backups type="integer">30</days_to_retain_backups>
      <default_time_zone>Pacific Time (US &amp; Canada)</default_time_zone>
      <desktop_app type="boolean">true</desktop_app>
      <desktop_app_session_ip_pinning type="boolean">true</desktop_app_session_ip_pinning>
      <desktop_app_session_lifetime type="integer">1</desktop_app_session_lifetime>
      <disable_notifications type="boolean">true</disable_notifications>
      <disable_password_reset type="boolean">true</disable_password_reset>
      <domain>my-custom-domain.com</domain>
      <email>john.doe@files.com</email>
      <hipaa type="boolean">true</hipaa>
      <icon128></icon128>
      <icon16></icon16>
      <icon32></icon32>
      <icon48></icon48>
      <immutable_files_set_at type="dateTime">2000-01-01T01:00:00Z</immutable_files_set_at>
      <include_password_in_welcome_email type="boolean">true</include_password_in_welcome_email>
      <language>en</language>
      <ldap_base_dn></ldap_base_dn>
      <ldap_domain>mysite.com</ldap_domain>
      <ldap_enabled type="boolean">true</ldap_enabled>
      <ldap_group_action>disabled</ldap_group_action>
      <ldap_group_exclusion></ldap_group_exclusion>
      <ldap_group_inclusion></ldap_group_inclusion>
      <ldap_host>ldap.site.com</ldap_host>
      <ldap_host_2>ldap2.site.com</ldap_host_2>
      <ldap_host_3>ldap3.site.com</ldap_host_3>
      <ldap_port type="integer">1</ldap_port>
      <ldap_secure type="boolean">true</ldap_secure>
      <ldap_type>open_ldap</ldap_type>
      <ldap_user_action>disabled</ldap_user_action>
      <ldap_user_include_groups></ldap_user_include_groups>
      <ldap_username>[ldap username]</ldap_username>
      <ldap_username_field>sAMAccountName</ldap_username_field>
      <login_help_text>Login page help text.</login_help_text>
      <logo></logo>
      <max_prior_passwords type="integer">1</max_prior_passwords>
      <name>My Site</name>
      <next_billing_amount></next_billing_amount>
      <next_billing_date>Apr 20</next_billing_date>
      <opt_out_global type="boolean">true</opt_out_global>
      <overage_notified_at type="dateTime">2000-01-01T01:00:00Z</overage_notified_at>
      <overage_notify type="boolean">true</overage_notify>
      <overdue type="boolean">true</overdue>
      <password_min_length type="integer">1</password_min_length>
      <password_require_letter type="boolean">true</password_require_letter>
      <password_require_mixed type="boolean">true</password_require_mixed>
      <password_require_number type="boolean">true</password_require_number>
      <password_require_special type="boolean">true</password_require_special>
      <password_validity_days type="integer">1</password_validity_days>
      <phone>555-555-5555</phone>
      <require_2fa type="boolean">true</require_2fa>
      <require_2fa_stop_time type="dateTime">2000-01-01T01:00:00Z</require_2fa_stop_time>
      <session></session>
      <session_pinned_by_ip type="boolean">true</session_pinned_by_ip>
      <sftp_user_root_enabled type="boolean">true</sftp_user_root_enabled>
      <show_request_access_link type="boolean">true</show_request_access_link>
      <site_footer></site_footer>
      <site_header></site_header>
      <smtp_address>smtp.my-mail-server.com</smtp_address>
      <smtp_authentication>plain</smtp_authentication>
      <smtp_from>me@my-mail-server.com</smtp_from>
      <smtp_port type="integer">25</smtp_port>
      <smtp_username>mail</smtp_username>
      <session_expiry type="integer">6</session_expiry>
      <ssl_required type="boolean">true</ssl_required>
      <subdomain>mysite</subdomain>
      <switch_to_plan_date type="dateTime">2000-01-01T01:00:00Z</switch_to_plan_date>
      <tls_disabled type="boolean">true</tls_disabled>
      <trial_days_left type="integer">1</trial_days_left>
      <trial_until type="dateTime">2000-01-01T01:00:00Z</trial_until>
      <updated_at type="dateTime">2000-01-01T01:00:00Z</updated_at>
      <use_provided_modified_at type="boolean">true</use_provided_modified_at>
      <user></user>
      <user_lockout type="boolean">true</user_lockout>
      <user_lockout_lock_period type="integer">1</user_lockout_lock_period>
      <user_lockout_tries type="integer">1</user_lockout_tries>
      <user_lockout_within type="integer">6</user_lockout_within>
      <welcome_custom_text>Welcome to my site!</welcome_custom_text>
      <welcome_email_cc></welcome_email_cc>
      <welcome_email_enabled type="boolean">true</welcome_email_enabled>
      <windows_mode_ftp type="boolean">true</windows_mode_ftp>
    </site>
    
    
    Attribute Description
    allowed_2fa_method_sms boolean Is SMS two factor authentication allowed?
    allowed_2fa_method_totp boolean Is TOTP two factor authentication allowed?
    allowed_2fa_method_u2f boolean Is U2F two factor authentication allowed?
    allowed_2fa_method_yubi boolean Is yubikey two factor authentication allowed?
    admin_user_id int64 User ID for the main site administrator
    allowed_file_types string List of allowed file types
    allowed_ips string List of allowed IP addresses
    ask_about_overwrites boolean If false, rename conflicting files instead of asking for overwrite confirmation. Only applies to web interface.
    bundle_expiration int64 Default Bundle expiration in days
    bundle_password_required boolean Do Bundles require password protection?
    color2_left string Page link and button color
    color2_link string Top bar link color
    color2_text string Page link and button color
    color2_top string Top bar background color
    color2_top_text string Top bar text color
    created_at date-time Time this site was created
    currency string Preferred currency
    custom_namespace boolean Is this site using a custom namespace for users?
    days_to_retain_backups int64 Number of days to keep deleted files
    default_time_zone string Site default time zone
    desktop_app boolean Is the desktop app enabled?
    desktop_app_session_ip_pinning boolean Is desktop app session IP pinning enabled?
    desktop_app_session_lifetime int64 Desktop app session lifetime (in hours)
    disable_notifications boolean Are notifications disabled?
    disable_password_reset boolean Is password reset disabled?
    domain string Custom domain
    email email Main email for this site
    hipaa boolean Is there a signed HIPAA BAA between Files.com and this site?
    icon128 Branded icon 128x128
    icon16 Branded icon 16x16
    icon32 Branded icon 32x32
    icon48 Branded icon 48x48
    immutable_files_set_at date-time Can files be modified?
    include_password_in_welcome_email boolean Include password in emails to new users?
    language string Site default language
    ldap_base_dn string Base DN for looking up users in LDAP server
    ldap_domain string Domain name that will be appended to usernames
    ldap_enabled boolean Main LDAP setting: is LDAP enabled?
    ldap_group_action string Should we sync groups from LDAP server?
    ldap_group_exclusion string Comma or newline separated list of group names (with optional wildcards) to exclude when syncing.
    ldap_group_inclusion string Comma or newline separated list of group names (with optional wildcards) to include when syncing.
    ldap_host string LDAP host
    ldap_host_2 string LDAP backup host
    ldap_host_3 string LDAP backup host
    ldap_port int64 LDAP port
    ldap_secure boolean Use secure LDAP?
    ldap_type string LDAP type. Can be active_directory or open_ldap
    ldap_user_action string Should we sync users from LDAP server?
    ldap_user_include_groups string Comma or newline separated list of group names (with optional wildcards) - if provided, only users in these groups will be added or synced.
    ldap_username string Username for signing in to LDAP server.
    ldap_username_field string LDAP username field. Can be SAMAccountName or userPrincipalName
    login_help_text string Login help text
    logo Branded logo
    max_prior_passwords int64 Number of prior passwords to disallow
    name string Site name
    next_billing_amount float Next billing amount
    next_billing_date string Next billing date
    opt_out_global boolean Opt out of global emails?
    overage_notified_at date-time Last time the site was notified about an overage
    overage_notify boolean Notify site email of overages?
    overdue boolean Is this site's billing overdue?
    password_min_length int64 Shortest password length for users
    password_require_letter boolean Require a letter in passwords?
    password_require_mixed boolean Require lower and upper case letters in passwords?
    password_require_number boolean Require a number in passwords?
    password_require_special boolean Require special characters in password?
    password_validity_days int64 Number of days password is valid
    phone string Site phone number
    require_2fa boolean Require two-factor authentication for all users?
    require_2fa_stop_time date-time If set, requirement for two-factor authentication has been scheduled to end on this date-time.
    session Current session
    session_pinned_by_ip boolean Are sessions locked to the same IP? (i.e. do users need to log in again if they change IPs?)
    sftp_user_root_enabled boolean Use user FTP roots also for SFTP?
    show_request_access_link boolean Show request access link for users without access? Currently unused.
    site_footer string Custom site footer text
    site_header string Custom site header text
    smtp_address string SMTP server hostname or IP
    smtp_authentication string SMTP server authentication type
    smtp_from string From address to use when mailing through custom SMTP
    smtp_port int64 SMTP server port
    smtp_username string SMTP server username
    session_expiry int64 Session expiry in hours
    ssl_required boolean Is SSL required? Disabling this is insecure.
    subdomain string Site subdomain
    switch_to_plan_date date-time If switching plans, when does the new plan take effect?
    tls_disabled boolean Is TLS disabled(site setting)?
    trial_days_left int64 Number of days left in trial
    trial_until date-time When does this Site trial expire?
    updated_at date-time Last time this Site was updated
    use_provided_modified_at boolean Allow uploaders to set provided_modified_at for uploaded files?
    user User of current session
    user_lockout boolean Will users be locked out after incorrect login attempts?
    user_lockout_lock_period int64 How many hours to lock user out for failed password?
    user_lockout_tries int64 Number of login tries within user_lockout_within hours before users are locked out
    user_lockout_within int64 Number of hours for user lockout window
    welcome_custom_text string Custom text send in user welcome email
    welcome_email_cc email Include this email in welcome emails if enabled
    welcome_email_enabled boolean Will the welcome email be sent to new users?
    windows_mode_ftp boolean Does FTP user Windows emulation mode?

    Show site settings

    Example Request

    curl https://app.files.com/api/rest/v1/site.json \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/site.xml ]
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Site.get
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Site::get();
    

    Example Response

    {
      "allowed_2fa_method_sms": true,
      "allowed_2fa_method_totp": true,
      "allowed_2fa_method_u2f": true,
      "allowed_2fa_method_yubi": true,
      "admin_user_id": 1,
      "allowed_file_types": "",
      "allowed_ips": "",
      "ask_about_overwrites": true,
      "bundle_expiration": 1,
      "bundle_password_required": true,
      "color2_left": "#0066a7",
      "color2_link": "#d34f5d",
      "color2_text": "#0066a7",
      "color2_top": "#000000",
      "color2_top_text": "#ffffff",
      "created_at": "2000-01-01 01:00:00 UTC",
      "currency": "USD",
      "custom_namespace": true,
      "days_to_retain_backups": 30,
      "default_time_zone": "Pacific Time (US & Canada)",
      "desktop_app": true,
      "desktop_app_session_ip_pinning": true,
      "desktop_app_session_lifetime": 1,
      "disable_notifications": true,
      "disable_password_reset": true,
      "domain": "my-custom-domain.com",
      "email": "john.doe@files.com",
      "hipaa": true,
      "icon128": "",
      "icon16": "",
      "icon32": "",
      "icon48": "",
      "immutable_files_set_at": "2000-01-01 01:00:00 UTC",
      "include_password_in_welcome_email": true,
      "language": "en",
      "ldap_base_dn": "",
      "ldap_domain": "mysite.com",
      "ldap_enabled": true,
      "ldap_group_action": "disabled",
      "ldap_group_exclusion": "",
      "ldap_group_inclusion": "",
      "ldap_host": "ldap.site.com",
      "ldap_host_2": "ldap2.site.com",
      "ldap_host_3": "ldap3.site.com",
      "ldap_port": 1,
      "ldap_secure": true,
      "ldap_type": "open_ldap",
      "ldap_user_action": "disabled",
      "ldap_user_include_groups": "",
      "ldap_username": "[ldap username]",
      "ldap_username_field": "sAMAccountName",
      "login_help_text": "Login page help text.",
      "logo": "",
      "max_prior_passwords": 1,
      "name": "My Site",
      "next_billing_amount": "",
      "next_billing_date": "Apr 20",
      "opt_out_global": true,
      "overage_notified_at": "2000-01-01 01:00:00 UTC",
      "overage_notify": true,
      "overdue": true,
      "password_min_length": 1,
      "password_require_letter": true,
      "password_require_mixed": true,
      "password_require_number": true,
      "password_require_special": true,
      "password_validity_days": 1,
      "phone": "555-555-5555",
      "require_2fa": true,
      "require_2fa_stop_time": "2000-01-01 01:00:00 UTC",
      "session": "",
      "session_pinned_by_ip": true,
      "sftp_user_root_enabled": true,
      "show_request_access_link": true,
      "site_footer": "",
      "site_header": "",
      "smtp_address": "smtp.my-mail-server.com",
      "smtp_authentication": "plain",
      "smtp_from": "me@my-mail-server.com",
      "smtp_port": 25,
      "smtp_username": "mail",
      "session_expiry": 6,
      "ssl_required": true,
      "subdomain": "mysite",
      "switch_to_plan_date": "2000-01-01 01:00:00 UTC",
      "tls_disabled": true,
      "trial_days_left": 1,
      "trial_until": "2000-01-01 01:00:00 UTC",
      "updated_at": "2000-01-01 01:00:00 UTC",
      "use_provided_modified_at": true,
      "user": "",
      "user_lockout": true,
      "user_lockout_lock_period": 1,
      "user_lockout_tries": 1,
      "user_lockout_within": 6,
      "welcome_custom_text": "Welcome to my site!",
      "welcome_email_cc": "",
      "welcome_email_enabled": true,
      "windows_mode_ftp": true
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <site>
      <allowed_2fa_method_sms type="boolean">true</allowed_2fa_method_sms>
      <allowed_2fa_method_totp type="boolean">true</allowed_2fa_method_totp>
      <allowed_2fa_method_u2f type="boolean">true</allowed_2fa_method_u2f>
      <allowed_2fa_method_yubi type="boolean">true</allowed_2fa_method_yubi>
      <admin_user_id type="integer">1</admin_user_id>
      <allowed_file_types></allowed_file_types>
      <allowed_ips></allowed_ips>
      <ask_about_overwrites type="boolean">true</ask_about_overwrites>
      <bundle_expiration type="integer">1</bundle_expiration>
      <bundle_password_required type="boolean">true</bundle_password_required>
      <color2_left>#0066a7</color2_left>
      <color2_link>#d34f5d</color2_link>
      <color2_text>#0066a7</color2_text>
      <color2_top>#000000</color2_top>
      <color2_top_text>#ffffff</color2_top_text>
      <created_at type="dateTime">2000-01-01T01:00:00Z</created_at>
      <currency>USD</currency>
      <custom_namespace type="boolean">true</custom_namespace>
      <days_to_retain_backups type="integer">30</days_to_retain_backups>
      <default_time_zone>Pacific Time (US &amp; Canada)</default_time_zone>
      <desktop_app type="boolean">true</desktop_app>
      <desktop_app_session_ip_pinning type="boolean">true</desktop_app_session_ip_pinning>
      <desktop_app_session_lifetime type="integer">1</desktop_app_session_lifetime>
      <disable_notifications type="boolean">true</disable_notifications>
      <disable_password_reset type="boolean">true</disable_password_reset>
      <domain>my-custom-domain.com</domain>
      <email>john.doe@files.com</email>
      <hipaa type="boolean">true</hipaa>
      <icon128></icon128>
      <icon16></icon16>
      <icon32></icon32>
      <icon48></icon48>
      <immutable_files_set_at type="dateTime">2000-01-01T01:00:00Z</immutable_files_set_at>
      <include_password_in_welcome_email type="boolean">true</include_password_in_welcome_email>
      <language>en</language>
      <ldap_base_dn></ldap_base_dn>
      <ldap_domain>mysite.com</ldap_domain>
      <ldap_enabled type="boolean">true</ldap_enabled>
      <ldap_group_action>disabled</ldap_group_action>
      <ldap_group_exclusion></ldap_group_exclusion>
      <ldap_group_inclusion></ldap_group_inclusion>
      <ldap_host>ldap.site.com</ldap_host>
      <ldap_host_2>ldap2.site.com</ldap_host_2>
      <ldap_host_3>ldap3.site.com</ldap_host_3>
      <ldap_port type="integer">1</ldap_port>
      <ldap_secure type="boolean">true</ldap_secure>
      <ldap_type>open_ldap</ldap_type>
      <ldap_user_action>disabled</ldap_user_action>
      <ldap_user_include_groups></ldap_user_include_groups>
      <ldap_username>[ldap username]</ldap_username>
      <ldap_username_field>sAMAccountName</ldap_username_field>
      <login_help_text>Login page help text.</login_help_text>
      <logo></logo>
      <max_prior_passwords type="integer">1</max_prior_passwords>
      <name>My Site</name>
      <next_billing_amount></next_billing_amount>
      <next_billing_date>Apr 20</next_billing_date>
      <opt_out_global type="boolean">true</opt_out_global>
      <overage_notified_at type="dateTime">2000-01-01T01:00:00Z</overage_notified_at>
      <overage_notify type="boolean">true</overage_notify>
      <overdue type="boolean">true</overdue>
      <password_min_length type="integer">1</password_min_length>
      <password_require_letter type="boolean">true</password_require_letter>
      <password_require_mixed type="boolean">true</password_require_mixed>
      <password_require_number type="boolean">true</password_require_number>
      <password_require_special type="boolean">true</password_require_special>
      <password_validity_days type="integer">1</password_validity_days>
      <phone>555-555-5555</phone>
      <require_2fa type="boolean">true</require_2fa>
      <require_2fa_stop_time type="dateTime">2000-01-01T01:00:00Z</require_2fa_stop_time>
      <session></session>
      <session_pinned_by_ip type="boolean">true</session_pinned_by_ip>
      <sftp_user_root_enabled type="boolean">true</sftp_user_root_enabled>
      <show_request_access_link type="boolean">true</show_request_access_link>
      <site_footer></site_footer>
      <site_header></site_header>
      <smtp_address>smtp.my-mail-server.com</smtp_address>
      <smtp_authentication>plain</smtp_authentication>
      <smtp_from>me@my-mail-server.com</smtp_from>
      <smtp_port type="integer">25</smtp_port>
      <smtp_username>mail</smtp_username>
      <session_expiry type="integer">6</session_expiry>
      <ssl_required type="boolean">true</ssl_required>
      <subdomain>mysite</subdomain>
      <switch_to_plan_date type="dateTime">2000-01-01T01:00:00Z</switch_to_plan_date>
      <tls_disabled type="boolean">true</tls_disabled>
      <trial_days_left type="integer">1</trial_days_left>
      <trial_until type="dateTime">2000-01-01T01:00:00Z</trial_until>
      <updated_at type="dateTime">2000-01-01T01:00:00Z</updated_at>
      <use_provided_modified_at type="boolean">true</use_provided_modified_at>
      <user></user>
      <user_lockout type="boolean">true</user_lockout>
      <user_lockout_lock_period type="integer">1</user_lockout_lock_period>
      <user_lockout_tries type="integer">1</user_lockout_tries>
      <user_lockout_within type="integer">6</user_lockout_within>
      <welcome_custom_text>Welcome to my site!</welcome_custom_text>
      <welcome_email_cc></welcome_email_cc>
      <welcome_email_enabled type="boolean">true</welcome_email_enabled>
      <windows_mode_ftp type="boolean">true</windows_mode_ftp>
    </site>
    
    

    HTTPS Request

    GET /site

    List IP addresses

    Example Request

    curl https://app.files.com/api/rest/v1/site/ip_addresses.json \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/site/ip_addresses.xml ]
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Site.ip_addresses
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Site::ipAddresses();
    

    Example Response

    {
      "associated_with": "Site",
      "group_id": 1,
      "ip_addresses": [
    
      ]
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <site>
      <associated_with>Site</associated_with>
      <group_id type="integer">1</group_id>
      <ip_addresses type="array"/>
    </site>
    
    

    HTTPS Request

    GET /site/ip_addresses

    Update site settings

    Example Request

    curl https://app.files.com/api/rest/v1/site.json \
      -X PATCH \
      -H 'Content-Type: application/json' \
      -d '{"name":"My Site","subdomain":"mysite","domain":"my-custom-domain.com","email":"john.doe@files.com","bundle_expiration":1,"overage_notify":true,"welcome_email_enabled":true,"ask_about_overwrites":true,"show_request_access_link":true,"welcome_custom_text":"Welcome to my site!","language":"en","windows_mode_ftp":true,"default_time_zone":"Pacific Time (US & Canada)","desktop_app":true,"desktop_app_session_ip_pinning":true,"desktop_app_session_lifetime":1,"session_expiry":1,"ssl_required":true,"tls_disabled":true,"user_lockout":true,"user_lockout_tries":1,"user_lockout_within":1,"user_lockout_lock_period":1,"include_password_in_welcome_email":true,"days_to_retain_backups":1,"max_prior_passwords":1,"password_validity_days":1,"password_min_length":1,"password_require_letter":true,"password_require_mixed":true,"password_require_special":true,"password_require_number":true,"sftp_user_root_enabled":true,"disable_password_reset":true,"immutable_files":true,"session_pinned_by_ip":true,"bundle_password_required":true,"allowed_2fa_method_sms":true,"allowed_2fa_method_u2f":true,"allowed_2fa_method_totp":true,"allowed_2fa_method_yubi":true,"require_2fa":true,"color2_top":"#000000","color2_left":"#0066a7","color2_link":"#d34f5d","color2_text":"#0066a7","color2_top_text":"#ffffff","login_help_text":"Login page help text.","smtp_address":"smtp.my-mail-server.com","smtp_authentication":"plain","smtp_from":"me@my-mail-server.com","smtp_username":"mail","smtp_port":1,"ldap_enabled":true,"ldap_type":"open_ldap","ldap_host":"ldap.site.com","ldap_host_2":"ldap2.site.com","ldap_host_3":"ldap3.site.com","ldap_port":1,"ldap_secure":true,"ldap_username":"[ldap username]","ldap_username_field":"sAMAccountName","ldap_domain":"mysite.com","ldap_user_action":"disabled","ldap_group_action":"disabled","opt_out_global":true,"use_provided_modified_at":true,"custom_namespace":true,"days_until_2fa_required":1,"disable_2fa_with_delay":true,"remove_icons":true}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/site.xml ]
      -X PATCH \
      -H 'Content-Type: application/xml' \
      -d '<site>
           <name>My Site</name>
           <subdomain>mysite</subdomain>
           <domain>my-custom-domain.com</domain>
           <email>john.doe@files.com</email>
           <bundle_expiration type="integer">1</bundle_expiration>
           <overage_notify type="boolean">true</overage_notify>
           <welcome_email_enabled type="boolean">true</welcome_email_enabled>
           <ask_about_overwrites type="boolean">true</ask_about_overwrites>
           <show_request_access_link type="boolean">true</show_request_access_link>
           <welcome_custom_text>Welcome to my site!</welcome_custom_text>
           <language>en</language>
           <windows_mode_ftp type="boolean">true</windows_mode_ftp>
           <default_time_zone>Pacific Time (US &amp; Canada)</default_time_zone>
           <desktop_app type="boolean">true</desktop_app>
           <desktop_app_session_ip_pinning type="boolean">true</desktop_app_session_ip_pinning>
           <desktop_app_session_lifetime type="integer">1</desktop_app_session_lifetime>
           <session_expiry type="integer">1</session_expiry>
           <ssl_required type="boolean">true</ssl_required>
           <tls_disabled type="boolean">true</tls_disabled>
           <user_lockout type="boolean">true</user_lockout>
           <user_lockout_tries type="integer">1</user_lockout_tries>
           <user_lockout_within type="integer">1</user_lockout_within>
           <user_lockout_lock_period type="integer">1</user_lockout_lock_period>
           <include_password_in_welcome_email type="boolean">true</include_password_in_welcome_email>
           <days_to_retain_backups type="integer">1</days_to_retain_backups>
           <max_prior_passwords type="integer">1</max_prior_passwords>
           <password_validity_days type="integer">1</password_validity_days>
           <password_min_length type="integer">1</password_min_length>
           <password_require_letter type="boolean">true</password_require_letter>
           <password_require_mixed type="boolean">true</password_require_mixed>
           <password_require_special type="boolean">true</password_require_special>
           <password_require_number type="boolean">true</password_require_number>
           <sftp_user_root_enabled type="boolean">true</sftp_user_root_enabled>
           <disable_password_reset type="boolean">true</disable_password_reset>
           <immutable_files type="boolean">true</immutable_files>
           <session_pinned_by_ip type="boolean">true</session_pinned_by_ip>
           <bundle_password_required type="boolean">true</bundle_password_required>
           <allowed_2fa_method_sms type="boolean">true</allowed_2fa_method_sms>
           <allowed_2fa_method_u2f type="boolean">true</allowed_2fa_method_u2f>
           <allowed_2fa_method_totp type="boolean">true</allowed_2fa_method_totp>
           <allowed_2fa_method_yubi type="boolean">true</allowed_2fa_method_yubi>
           <require_2fa type="boolean">true</require_2fa>
           <color2_top>#000000</color2_top>
           <color2_left>#0066a7</color2_left>
           <color2_link>#d34f5d</color2_link>
           <color2_text>#0066a7</color2_text>
           <color2_top_text>#ffffff</color2_top_text>
           <login_help_text>Login page help text.</login_help_text>
           <smtp_address>smtp.my-mail-server.com</smtp_address>
           <smtp_authentication>plain</smtp_authentication>
           <smtp_from>me@my-mail-server.com</smtp_from>
           <smtp_username>mail</smtp_username>
           <smtp_port type="integer">1</smtp_port>
           <ldap_enabled type="boolean">true</ldap_enabled>
           <ldap_type>open_ldap</ldap_type>
           <ldap_host>ldap.site.com</ldap_host>
           <ldap_host_2>ldap2.site.com</ldap_host_2>
           <ldap_host_3>ldap3.site.com</ldap_host_3>
           <ldap_port type="integer">1</ldap_port>
           <ldap_secure type="boolean">true</ldap_secure>
           <ldap_username>[ldap username]</ldap_username>
           <ldap_username_field>sAMAccountName</ldap_username_field>
           <ldap_domain>mysite.com</ldap_domain>
           <ldap_user_action>disabled</ldap_user_action>
           <ldap_group_action>disabled</ldap_group_action>
           <opt_out_global type="boolean">true</opt_out_global>
           <use_provided_modified_at type="boolean">true</use_provided_modified_at>
           <custom_namespace type="boolean">true</custom_namespace>
           <days_until_2fa_required type="integer">1</days_until_2fa_required>
           <disable_2fa_with_delay type="boolean">true</disable_2fa_with_delay>
           <remove_icons type="boolean">true</remove_icons>
         </site>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Site.update(
      name: "My Site", 
      subdomain: "mysite", 
      domain: "my-custom-domain.com", 
      email: "john.doe@files.com", 
      bundle_expiration: 1, 
      overage_notify: true, 
      welcome_email_enabled: true, 
      ask_about_overwrites: true, 
      show_request_access_link: true, 
      welcome_custom_text: "Welcome to my site!", 
      language: "en", 
      windows_mode_ftp: true, 
      default_time_zone: "Pacific Time (US & Canada)", 
      desktop_app: true, 
      desktop_app_session_ip_pinning: true, 
      desktop_app_session_lifetime: 1, 
      session_expiry: 1, 
      ssl_required: true, 
      tls_disabled: true, 
      user_lockout: true, 
      user_lockout_tries: 1, 
      user_lockout_within: 1, 
      user_lockout_lock_period: 1, 
      include_password_in_welcome_email: true, 
      days_to_retain_backups: 1, 
      max_prior_passwords: 1, 
      password_validity_days: 1, 
      password_min_length: 1, 
      password_require_letter: true, 
      password_require_mixed: true, 
      password_require_special: true, 
      password_require_number: true, 
      sftp_user_root_enabled: true, 
      disable_password_reset: true, 
      immutable_files: true, 
      session_pinned_by_ip: true, 
      bundle_password_required: true, 
      allowed_2fa_method_sms: true, 
      allowed_2fa_method_u2f: true, 
      allowed_2fa_method_totp: true, 
      allowed_2fa_method_yubi: true, 
      require_2fa: true, 
      color2_top: "#000000", 
      color2_left: "#0066a7", 
      color2_link: "#d34f5d", 
      color2_text: "#0066a7", 
      color2_top_text: "#ffffff", 
      login_help_text: "Login page help text.", 
      smtp_address: "smtp.my-mail-server.com", 
      smtp_authentication: "plain", 
      smtp_from: "me@my-mail-server.com", 
      smtp_username: "mail", 
      smtp_port: 1, 
      ldap_enabled: true, 
      ldap_type: "open_ldap", 
      ldap_host: "ldap.site.com", 
      ldap_host_2: "ldap2.site.com", 
      ldap_host_3: "ldap3.site.com", 
      ldap_port: 1, 
      ldap_secure: true, 
      ldap_username: "[ldap username]", 
      ldap_username_field: "sAMAccountName", 
      ldap_domain: "mysite.com", 
      ldap_user_action: "disabled", 
      ldap_group_action: "disabled", 
      opt_out_global: true, 
      use_provided_modified_at: true, 
      custom_namespace: true, 
      days_until_2fa_required: 1, 
      disable_2fa_with_delay: true, 
      remove_icons: true
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Site::update(array(
      'name' => "My Site", 
      'subdomain' => "mysite", 
      'domain' => "my-custom-domain.com", 
      'email' => "john.doe@files.com", 
      'bundle_expiration' => 1, 
      'overage_notify' => true, 
      'welcome_email_enabled' => true, 
      'ask_about_overwrites' => true, 
      'show_request_access_link' => true, 
      'welcome_custom_text' => "Welcome to my site!", 
      'language' => "en", 
      'windows_mode_ftp' => true, 
      'default_time_zone' => "Pacific Time (US & Canada)", 
      'desktop_app' => true, 
      'desktop_app_session_ip_pinning' => true, 
      'desktop_app_session_lifetime' => 1, 
      'session_expiry' => 1, 
      'ssl_required' => true, 
      'tls_disabled' => true, 
      'user_lockout' => true, 
      'user_lockout_tries' => 1, 
      'user_lockout_within' => 1, 
      'user_lockout_lock_period' => 1, 
      'include_password_in_welcome_email' => true, 
      'days_to_retain_backups' => 1, 
      'max_prior_passwords' => 1, 
      'password_validity_days' => 1, 
      'password_min_length' => 1, 
      'password_require_letter' => true, 
      'password_require_mixed' => true, 
      'password_require_special' => true, 
      'password_require_number' => true, 
      'sftp_user_root_enabled' => true, 
      'disable_password_reset' => true, 
      'immutable_files' => true, 
      'session_pinned_by_ip' => true, 
      'bundle_password_required' => true, 
      'allowed_2fa_method_sms' => true, 
      'allowed_2fa_method_u2f' => true, 
      'allowed_2fa_method_totp' => true, 
      'allowed_2fa_method_yubi' => true, 
      'require_2fa' => true, 
      'color2_top' => "#000000", 
      'color2_left' => "#0066a7", 
      'color2_link' => "#d34f5d", 
      'color2_text' => "#0066a7", 
      'color2_top_text' => "#ffffff", 
      'login_help_text' => "Login page help text.", 
      'smtp_address' => "smtp.my-mail-server.com", 
      'smtp_authentication' => "plain", 
      'smtp_from' => "me@my-mail-server.com", 
      'smtp_username' => "mail", 
      'smtp_port' => 1, 
      'ldap_enabled' => true, 
      'ldap_type' => "open_ldap", 
      'ldap_host' => "ldap.site.com", 
      'ldap_host_2' => "ldap2.site.com", 
      'ldap_host_3' => "ldap3.site.com", 
      'ldap_port' => 1, 
      'ldap_secure' => true, 
      'ldap_username' => "[ldap username]", 
      'ldap_username_field' => "sAMAccountName", 
      'ldap_domain' => "mysite.com", 
      'ldap_user_action' => "disabled", 
      'ldap_group_action' => "disabled", 
      'opt_out_global' => true, 
      'use_provided_modified_at' => true, 
      'custom_namespace' => true, 
      'days_until_2fa_required' => 1, 
      'disable_2fa_with_delay' => true, 
      'remove_icons' => true
    ));
    

    Example Response

    {
      "allowed_2fa_method_sms": true,
      "allowed_2fa_method_totp": true,
      "allowed_2fa_method_u2f": true,
      "allowed_2fa_method_yubi": true,
      "admin_user_id": 1,
      "allowed_file_types": "",
      "allowed_ips": "",
      "ask_about_overwrites": true,
      "bundle_expiration": 1,
      "bundle_password_required": true,
      "color2_left": "#0066a7",
      "color2_link": "#d34f5d",
      "color2_text": "#0066a7",
      "color2_top": "#000000",
      "color2_top_text": "#ffffff",
      "created_at": "2000-01-01 01:00:00 UTC",
      "currency": "USD",
      "custom_namespace": true,
      "days_to_retain_backups": 30,
      "default_time_zone": "Pacific Time (US & Canada)",
      "desktop_app": true,
      "desktop_app_session_ip_pinning": true,
      "desktop_app_session_lifetime": 1,
      "disable_notifications": true,
      "disable_password_reset": true,
      "domain": "my-custom-domain.com",
      "email": "john.doe@files.com",
      "hipaa": true,
      "icon128": "",
      "icon16": "",
      "icon32": "",
      "icon48": "",
      "immutable_files_set_at": "2000-01-01 01:00:00 UTC",
      "include_password_in_welcome_email": true,
      "language": "en",
      "ldap_base_dn": "",
      "ldap_domain": "mysite.com",
      "ldap_enabled": true,
      "ldap_group_action": "disabled",
      "ldap_group_exclusion": "",
      "ldap_group_inclusion": "",
      "ldap_host": "ldap.site.com",
      "ldap_host_2": "ldap2.site.com",
      "ldap_host_3": "ldap3.site.com",
      "ldap_port": 1,
      "ldap_secure": true,
      "ldap_type": "open_ldap",
      "ldap_user_action": "disabled",
      "ldap_user_include_groups": "",
      "ldap_username": "[ldap username]",
      "ldap_username_field": "sAMAccountName",
      "login_help_text": "Login page help text.",
      "logo": "",
      "max_prior_passwords": 1,
      "name": "My Site",
      "next_billing_amount": "",
      "next_billing_date": "Apr 20",
      "opt_out_global": true,
      "overage_notified_at": "2000-01-01 01:00:00 UTC",
      "overage_notify": true,
      "overdue": true,
      "password_min_length": 1,
      "password_require_letter": true,
      "password_require_mixed": true,
      "password_require_number": true,
      "password_require_special": true,
      "password_validity_days": 1,
      "phone": "555-555-5555",
      "require_2fa": true,
      "require_2fa_stop_time": "2000-01-01 01:00:00 UTC",
      "session": "",
      "session_pinned_by_ip": true,
      "sftp_user_root_enabled": true,
      "show_request_access_link": true,
      "site_footer": "",
      "site_header": "",
      "smtp_address": "smtp.my-mail-server.com",
      "smtp_authentication": "plain",
      "smtp_from": "me@my-mail-server.com",
      "smtp_port": 25,
      "smtp_username": "mail",
      "session_expiry": 6,
      "ssl_required": true,
      "subdomain": "mysite",
      "switch_to_plan_date": "2000-01-01 01:00:00 UTC",
      "tls_disabled": true,
      "trial_days_left": 1,
      "trial_until": "2000-01-01 01:00:00 UTC",
      "updated_at": "2000-01-01 01:00:00 UTC",
      "use_provided_modified_at": true,
      "user": "",
      "user_lockout": true,
      "user_lockout_lock_period": 1,
      "user_lockout_tries": 1,
      "user_lockout_within": 6,
      "welcome_custom_text": "Welcome to my site!",
      "welcome_email_cc": "",
      "welcome_email_enabled": true,
      "windows_mode_ftp": true
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <site>
      <allowed_2fa_method_sms type="boolean">true</allowed_2fa_method_sms>
      <allowed_2fa_method_totp type="boolean">true</allowed_2fa_method_totp>
      <allowed_2fa_method_u2f type="boolean">true</allowed_2fa_method_u2f>
      <allowed_2fa_method_yubi type="boolean">true</allowed_2fa_method_yubi>
      <admin_user_id type="integer">1</admin_user_id>
      <allowed_file_types></allowed_file_types>
      <allowed_ips></allowed_ips>
      <ask_about_overwrites type="boolean">true</ask_about_overwrites>
      <bundle_expiration type="integer">1</bundle_expiration>
      <bundle_password_required type="boolean">true</bundle_password_required>
      <color2_left>#0066a7</color2_left>
      <color2_link>#d34f5d</color2_link>
      <color2_text>#0066a7</color2_text>
      <color2_top>#000000</color2_top>
      <color2_top_text>#ffffff</color2_top_text>
      <created_at type="dateTime">2000-01-01T01:00:00Z</created_at>
      <currency>USD</currency>
      <custom_namespace type="boolean">true</custom_namespace>
      <days_to_retain_backups type="integer">30</days_to_retain_backups>
      <default_time_zone>Pacific Time (US &amp; Canada)</default_time_zone>
      <desktop_app type="boolean">true</desktop_app>
      <desktop_app_session_ip_pinning type="boolean">true</desktop_app_session_ip_pinning>
      <desktop_app_session_lifetime type="integer">1</desktop_app_session_lifetime>
      <disable_notifications type="boolean">true</disable_notifications>
      <disable_password_reset type="boolean">true</disable_password_reset>
      <domain>my-custom-domain.com</domain>
      <email>john.doe@files.com</email>
      <hipaa type="boolean">true</hipaa>
      <icon128></icon128>
      <icon16></icon16>
      <icon32></icon32>
      <icon48></icon48>
      <immutable_files_set_at type="dateTime">2000-01-01T01:00:00Z</immutable_files_set_at>
      <include_password_in_welcome_email type="boolean">true</include_password_in_welcome_email>
      <language>en</language>
      <ldap_base_dn></ldap_base_dn>
      <ldap_domain>mysite.com</ldap_domain>
      <ldap_enabled type="boolean">true</ldap_enabled>
      <ldap_group_action>disabled</ldap_group_action>
      <ldap_group_exclusion></ldap_group_exclusion>
      <ldap_group_inclusion></ldap_group_inclusion>
      <ldap_host>ldap.site.com</ldap_host>
      <ldap_host_2>ldap2.site.com</ldap_host_2>
      <ldap_host_3>ldap3.site.com</ldap_host_3>
      <ldap_port type="integer">1</ldap_port>
      <ldap_secure type="boolean">true</ldap_secure>
      <ldap_type>open_ldap</ldap_type>
      <ldap_user_action>disabled</ldap_user_action>
      <ldap_user_include_groups></ldap_user_include_groups>
      <ldap_username>[ldap username]</ldap_username>
      <ldap_username_field>sAMAccountName</ldap_username_field>
      <login_help_text>Login page help text.</login_help_text>
      <logo></logo>
      <max_prior_passwords type="integer">1</max_prior_passwords>
      <name>My Site</name>
      <next_billing_amount></next_billing_amount>
      <next_billing_date>Apr 20</next_billing_date>
      <opt_out_global type="boolean">true</opt_out_global>
      <overage_notified_at type="dateTime">2000-01-01T01:00:00Z</overage_notified_at>
      <overage_notify type="boolean">true</overage_notify>
      <overdue type="boolean">true</overdue>
      <password_min_length type="integer">1</password_min_length>
      <password_require_letter type="boolean">true</password_require_letter>
      <password_require_mixed type="boolean">true</password_require_mixed>
      <password_require_number type="boolean">true</password_require_number>
      <password_require_special type="boolean">true</password_require_special>
      <password_validity_days type="integer">1</password_validity_days>
      <phone>555-555-5555</phone>
      <require_2fa type="boolean">true</require_2fa>
      <require_2fa_stop_time type="dateTime">2000-01-01T01:00:00Z</require_2fa_stop_time>
      <session></session>
      <session_pinned_by_ip type="boolean">true</session_pinned_by_ip>
      <sftp_user_root_enabled type="boolean">true</sftp_user_root_enabled>
      <show_request_access_link type="boolean">true</show_request_access_link>
      <site_footer></site_footer>
      <site_header></site_header>
      <smtp_address>smtp.my-mail-server.com</smtp_address>
      <smtp_authentication>plain</smtp_authentication>
      <smtp_from>me@my-mail-server.com</smtp_from>
      <smtp_port type="integer">25</smtp_port>
      <smtp_username>mail</smtp_username>
      <session_expiry type="integer">6</session_expiry>
      <ssl_required type="boolean">true</ssl_required>
      <subdomain>mysite</subdomain>
      <switch_to_plan_date type="dateTime">2000-01-01T01:00:00Z</switch_to_plan_date>
      <tls_disabled type="boolean">true</tls_disabled>
      <trial_days_left type="integer">1</trial_days_left>
      <trial_until type="dateTime">2000-01-01T01:00:00Z</trial_until>
      <updated_at type="dateTime">2000-01-01T01:00:00Z</updated_at>
      <use_provided_modified_at type="boolean">true</use_provided_modified_at>
      <user></user>
      <user_lockout type="boolean">true</user_lockout>
      <user_lockout_lock_period type="integer">1</user_lockout_lock_period>
      <user_lockout_tries type="integer">1</user_lockout_tries>
      <user_lockout_within type="integer">6</user_lockout_within>
      <welcome_custom_text>Welcome to my site!</welcome_custom_text>
      <welcome_email_cc></welcome_email_cc>
      <welcome_email_enabled type="boolean">true</welcome_email_enabled>
      <windows_mode_ftp type="boolean">true</windows_mode_ftp>
    </site>
    
    

    HTTPS Request

    PATCH /site

    Request Parameters

    Parameter Description
    name string Site name
    subdomain string Site subdomain
    domain string Custom domain
    email string Main email for this site
    bundle_expiration int64 Default Bundle expiration in days
    overage_notify boolean Notify site email of overages?
    welcome_email_enabled boolean Will the welcome email be sent to new users?
    ask_about_overwrites boolean If false, rename conflicting files instead of asking for overwrite confirmation. Only applies to web interface.
    show_request_access_link boolean Show request access link for users without access? Currently unused.
    welcome_email_cc string Include this email in welcome emails if enabled
    welcome_custom_text string Custom text send in user welcome email
    language string Site default language
    windows_mode_ftp boolean Does FTP user Windows emulation mode?
    default_time_zone string Site default time zone
    desktop_app boolean Is the desktop app enabled?
    desktop_app_session_ip_pinning boolean Is desktop app session IP pinning enabled?
    desktop_app_session_lifetime int64 Desktop app session lifetime (in hours)
    session_expiry int64 Session expiry in hours
    ssl_required boolean Is SSL required? Disabling this is insecure.
    tls_disabled boolean Is TLS disabled(site setting)?
    user_lockout boolean Will users be locked out after incorrect login attempts?
    user_lockout_tries int64 Number of login tries within user_lockout_within hours before users are locked out
    user_lockout_within int64 Number of hours for user lockout window
    user_lockout_lock_period int64 How many hours to lock user out for failed password?
    include_password_in_welcome_email boolean Include password in emails to new users?
    allowed_file_types string List of allowed file types
    allowed_ips string List of allowed IP addresses
    days_to_retain_backups int64 Number of days to keep deleted files
    max_prior_passwords int64 Number of prior passwords to disallow
    password_validity_days int64 Number of days password is valid
    password_min_length int64 Shortest password length for users
    password_require_letter boolean Require a letter in passwords?
    password_require_mixed boolean Require lower and upper case letters in passwords?
    password_require_special boolean Require special characters in password?
    password_require_number boolean Require a number in passwords?
    sftp_user_root_enabled boolean Use user FTP roots also for SFTP?
    disable_password_reset boolean Is password reset disabled?
    immutable_files boolean Are files protected from modification?
    session_pinned_by_ip boolean Are sessions locked to the same IP? (i.e. do users need to log in again if they change IPs?)
    bundle_password_required boolean Do Bundles require password protection?
    allowed_2fa_method_sms boolean Is SMS two factor authentication allowed?
    allowed_2fa_method_u2f boolean Is U2F two factor authentication allowed?
    allowed_2fa_method_totp boolean Is TOTP two factor authentication allowed?
    allowed_2fa_method_yubi boolean Is yubikey two factor authentication allowed?
    require_2fa boolean Require two-factor authentication for all users?
    color2_top string Top bar background color
    color2_left string Page link and button color
    color2_link string Top bar link color
    color2_text string Page link and button color
    color2_top_text string Top bar text color
    site_header string Custom site header text
    site_footer string Custom site footer text
    login_help_text string Login help text
    icon16 object Branded icon 16x16
    icon32 object Branded icon 32x32
    icon48 object Branded icon 48x48
    icon128 object Branded icon 128x128
    logo object Branded logo
    smtp_address string SMTP server hostname or IP
    smtp_authentication string SMTP server authentication type
    smtp_from string From address to use when mailing through custom SMTP
    smtp_username string SMTP server username
    smtp_port int64 SMTP server port
    ldap_enabled boolean Main LDAP setting: is LDAP enabled?
    ldap_type string LDAP type. Can be active_directory or open_ldap
    ldap_host string LDAP host
    ldap_host_2 string LDAP backup host
    ldap_host_3 string LDAP backup host
    ldap_port int64 LDAP port
    ldap_secure boolean Use secure LDAP?
    ldap_username string Username for signing in to LDAP server.
    ldap_username_field string LDAP username field. Can be SAMAccountName or userPrincipalName
    ldap_domain string Domain name that will be appended to usernames
    ldap_user_action string Should we sync users from LDAP server?
    ldap_group_action string Should we sync groups from LDAP server?
    ldap_user_include_groups string Comma or newline separated list of group names (with optional wildcards) - if provided, only users in these groups will be added or synced.
    ldap_group_exclusion string Comma or newline separated list of group names (with optional wildcards) to exclude when syncing.
    ldap_group_inclusion string Comma or newline separated list of group names (with optional wildcards) to include when syncing.
    ldap_base_dn string Base DN for looking up users in LDAP server
    opt_out_global boolean Opt out of global emails?
    use_provided_modified_at boolean Allow uploaders to set provided_modified_at for uploaded files?
    custom_namespace boolean Is this site using a custom namespace for users?
    days_until_2fa_required int64
    disable_2fa_with_delay boolean
    ldap_password_change string New LDAP password.
    ldap_password_change_confirmation string Confirm new LDAP password.
    remove_icons boolean
    smtp_password string

    Sso Strategies

    The SsoStrategies resource in the REST API allows you to operate on SsoStrategies. An SSO Strategy is a method for allowing users to sign in via another identity provider, such as Okta or Auth0.

    It is rare that you will need to use API endpoints for managing these, and we recommend instead managing these via the web interface. Nevertheless, we share the API documentation here.

    The SsoStrategy object

    Example SsoStrategy Object

    {
      "provider": "okta",
      "id": 1,
      "subdomain": "my-site",
      "provision_users": true,
      "provision_groups": true,
      "provision_group_default": "Employees",
      "provision_group_exclusion": "Employees",
      "provision_group_inclusion": "Employees",
      "provision_group_required": "",
      "provision_attachments_permission": true,
      "provision_dav_permission": true,
      "provision_ftp_permission": true,
      "provision_sftp_permission": true,
      "provision_time_zone": "Eastern Time (US & Canada)"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <sso-strategy>
      <provider>okta</provider>
      <id type="integer">1</id>
      <subdomain>my-site</subdomain>
      <provision_users type="boolean">true</provision_users>
      <provision_groups type="boolean">true</provision_groups>
      <provision_group_default>Employees</provision_group_default>
      <provision_group_exclusion>Employees</provision_group_exclusion>
      <provision_group_inclusion>Employees</provision_group_inclusion>
      <provision_group_required></provision_group_required>
      <provision_attachments_permission type="boolean">true</provision_attachments_permission>
      <provision_dav_permission type="boolean">true</provision_dav_permission>
      <provision_ftp_permission type="boolean">true</provision_ftp_permission>
      <provision_sftp_permission type="boolean">true</provision_sftp_permission>
      <provision_time_zone>Eastern Time (US &amp; Canada)</provision_time_zone>
    </sso-strategy>
    
    
    Attribute Description
    provider string Provider name
    id int64 ID
    subdomain string Subdomain
    provision_users boolean Auto-provision users?
    provision_groups boolean Auto-provision group membership based on group memberships on the SSO side?
    provision_group_default string Comma-separated list of group names for groups to automatically add all auto-provisioned users to.
    provision_group_exclusion string Comma-separated list of group names for groups (with optional wildcards) that will be excluded from auto-provisioning.
    provision_group_inclusion string Comma-separated list of group names for groups (with optional wildcards) that will be auto-provisioned.
    provision_group_required string Comma or newline separated list of group names (with optional wildcards) to require membership for user provisioning.
    provision_attachments_permission boolean Auto-provisioned users get Sharing permission?
    provision_dav_permission boolean Auto-provisioned users get WebDAV permission?
    provision_ftp_permission boolean Auto-provisioned users get FTP permission?
    provision_sftp_permission boolean Auto-provisioned users get SFTP permission?
    provision_time_zone string Default time zone for auto provisioned users.

    List Sso Strategies

    Example Request

    curl https://app.files.com/api/rest/v1/sso_strategies.json \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/sso_strategies.xml ]
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::SsoStrategy.list
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\SsoStrategy::list();
    

    Example Response

    [
      {
        "provider": "okta",
        "id": 1,
        "subdomain": "my-site",
        "provision_users": true,
        "provision_groups": true,
        "provision_group_default": "Employees",
        "provision_group_exclusion": "Employees",
        "provision_group_inclusion": "Employees",
        "provision_group_required": "",
        "provision_attachments_permission": true,
        "provision_dav_permission": true,
        "provision_ftp_permission": true,
        "provision_sftp_permission": true,
        "provision_time_zone": "Eastern Time (US & Canada)"
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <sso-strategies type="array">
      <sso-strategy>
        <provider>okta</provider>
        <id type="integer">1</id>
        <subdomain>my-site</subdomain>
        <provision_users type="boolean">true</provision_users>
        <provision_groups type="boolean">true</provision_groups>
        <provision_group_default>Employees</provision_group_default>
        <provision_group_exclusion>Employees</provision_group_exclusion>
        <provision_group_inclusion>Employees</provision_group_inclusion>
        <provision_group_required></provision_group_required>
        <provision_attachments_permission type="boolean">true</provision_attachments_permission>
        <provision_dav_permission type="boolean">true</provision_dav_permission>
        <provision_ftp_permission type="boolean">true</provision_ftp_permission>
        <provision_sftp_permission type="boolean">true</provision_sftp_permission>
        <provision_time_zone>Eastern Time (US &amp; Canada)</provision_time_zone>
      </sso-strategy>
    </sso-strategies>
    
    

    HTTPS Request

    GET /sso_strategies

    Show Sso Strategy

    Example Request

    curl https://app.files.com/api/rest/v1/sso_strategies/{id}.json \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/sso_strategies/{id}.xml ]
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::SsoStrategy.find(id)
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\SsoStrategy::find($id);
    

    Example Response

    {
      "provider": "okta",
      "id": 1,
      "subdomain": "my-site",
      "provision_users": true,
      "provision_groups": true,
      "provision_group_default": "Employees",
      "provision_group_exclusion": "Employees",
      "provision_group_inclusion": "Employees",
      "provision_group_required": "",
      "provision_attachments_permission": true,
      "provision_dav_permission": true,
      "provision_ftp_permission": true,
      "provision_sftp_permission": true,
      "provision_time_zone": "Eastern Time (US & Canada)"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <sso-strategy>
      <provider>okta</provider>
      <id type="integer">1</id>
      <subdomain>my-site</subdomain>
      <provision_users type="boolean">true</provision_users>
      <provision_groups type="boolean">true</provision_groups>
      <provision_group_default>Employees</provision_group_default>
      <provision_group_exclusion>Employees</provision_group_exclusion>
      <provision_group_inclusion>Employees</provision_group_inclusion>
      <provision_group_required></provision_group_required>
      <provision_attachments_permission type="boolean">true</provision_attachments_permission>
      <provision_dav_permission type="boolean">true</provision_dav_permission>
      <provision_ftp_permission type="boolean">true</provision_ftp_permission>
      <provision_sftp_permission type="boolean">true</provision_sftp_permission>
      <provision_time_zone>Eastern Time (US &amp; Canada)</provision_time_zone>
    </sso-strategy>
    
    

    HTTPS Request

    GET /sso_strategies/{id}

    Request Parameters

    Parameter Description
    id int64 Required Sso Strategy ID

    Create Sso Strategy

    Example Request

    curl https://app.files.com/api/rest/v1/sso_strategies.json \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{"provider":"okta","subdomain":"subdomain","client_id":"[client id]","client_secret":"[client secret]","provision_users":true,"provision_groups":true,"provision_group_default":"Employees","provision_group_exclusion":"Employees","provision_group_inclusion":"Employees","provision_attachments_permission":true,"provision_dav_permission":true,"provision_ftp_permission":true,"provision_sftp_permission":true,"provision_time_zone":"Eastern Time (US & Canada)"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/sso_strategies.xml ]
      -X POST \
      -H 'Content-Type: application/xml' \
      -d '<sso-strategy>
           <provider>okta</provider>
           <subdomain>subdomain</subdomain>
           <client_id>[client id]</client_id>
           <client_secret>[client secret]</client_secret>
           <provision_users type="boolean">true</provision_users>
           <provision_groups type="boolean">true</provision_groups>
           <provision_group_default>Employees</provision_group_default>
           <provision_group_exclusion>Employees</provision_group_exclusion>
           <provision_group_inclusion>Employees</provision_group_inclusion>
           <provision_attachments_permission type="boolean">true</provision_attachments_permission>
           <provision_dav_permission type="boolean">true</provision_dav_permission>
           <provision_ftp_permission type="boolean">true</provision_ftp_permission>
           <provision_sftp_permission type="boolean">true</provision_sftp_permission>
           <provision_time_zone>Eastern Time (US &amp; Canada)</provision_time_zone>
         </sso-strategy>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::SsoStrategy.create(
      provider: "okta", 
      subdomain: "subdomain", 
      client_id: "[client id]", 
      client_secret: "[client secret]", 
      provision_users: true, 
      provision_groups: true, 
      provision_group_default: "Employees", 
      provision_group_exclusion: "Employees", 
      provision_group_inclusion: "Employees", 
      provision_attachments_permission: true, 
      provision_dav_permission: true, 
      provision_ftp_permission: true, 
      provision_sftp_permission: true, 
      provision_time_zone: "Eastern Time (US & Canada)"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\SsoStrategy::create(array(
      'provider' => "okta", 
      'subdomain' => "subdomain", 
      'client_id' => "[client id]", 
      'client_secret' => "[client secret]", 
      'provision_users' => true, 
      'provision_groups' => true, 
      'provision_group_default' => "Employees", 
      'provision_group_exclusion' => "Employees", 
      'provision_group_inclusion' => "Employees", 
      'provision_attachments_permission' => true, 
      'provision_dav_permission' => true, 
      'provision_ftp_permission' => true, 
      'provision_sftp_permission' => true, 
      'provision_time_zone' => "Eastern Time (US & Canada)"
    ));
    

    Example Response

    {
      "provider": "okta",
      "id": 1,
      "subdomain": "my-site",
      "provision_users": true,
      "provision_groups": true,
      "provision_group_default": "Employees",
      "provision_group_exclusion": "Employees",
      "provision_group_inclusion": "Employees",
      "provision_group_required": "",
      "provision_attachments_permission": true,
      "provision_dav_permission": true,
      "provision_ftp_permission": true,
      "provision_sftp_permission": true,
      "provision_time_zone": "Eastern Time (US & Canada)"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <sso-strategy>
      <provider>okta</provider>
      <id type="integer">1</id>
      <subdomain>my-site</subdomain>
      <provision_users type="boolean">true</provision_users>
      <provision_groups type="boolean">true</provision_groups>
      <provision_group_default>Employees</provision_group_default>
      <provision_group_exclusion>Employees</provision_group_exclusion>
      <provision_group_inclusion>Employees</provision_group_inclusion>
      <provision_group_required></provision_group_required>
      <provision_attachments_permission type="boolean">true</provision_attachments_permission>
      <provision_dav_permission type="boolean">true</provision_dav_permission>
      <provision_ftp_permission type="boolean">true</provision_ftp_permission>
      <provision_sftp_permission type="boolean">true</provision_sftp_permission>
      <provision_time_zone>Eastern Time (US &amp; Canada)</provision_time_zone>
    </sso-strategy>
    
    

    HTTPS Request

    POST /sso_strategies

    Request Parameters

    Parameter Description
    provider string Required One of the following: google, auth0, okta, atlassian_oauth2, azure_oauth2, box_oauth2, dropbox_oauth2, slack, ubuntu
    subdomain string Subdomain or domain name for your auth provider. Example: https://[subdomain].okta.com/
    client_id string OAuth Client ID for your auth provider.
    client_secret string OAuth Client Secret for your auth provider.
    provision_users boolean Auto-provision users?
    provision_groups boolean Auto-provision group memberships?
    provision_group_default string Comma-separated list of group names for groups to automatically add all auto-provisioned users to.
    provision_group_exclusion string Comma-separated list of group names for groups (with optional wildcards) that will be excluded from auto-provisioning.
    provision_group_inclusion string Comma-separated list of group names for groups (with optional wildcards) that will be auto-provisioned.
    provision_group_required string Comma or newline separated list of group names (with optional wildcards) to require membership for user provisioning.
    provision_attachments_permission boolean Provisioned users to get sharing permission?
    provision_dav_permission boolean Provisioned users to get WebDAV permission?
    provision_ftp_permission boolean Provisioned users to get FTP permission?
    provision_sftp_permission boolean Provisioned users to get SFTP permission?
    provision_time_zone string Default timezone to use for provisioned users

    Update Sso Strategy

    Example Request

    curl https://app.files.com/api/rest/v1/sso_strategies/{id}.json \
      -X PATCH \
      -H 'Content-Type: application/json' \
      -d '{"provider":"okta","subdomain":"subdomain","client_id":"[client id]","client_secret":"[client secret]","provision_users":true,"provision_groups":true,"provision_group_default":"Employees","provision_group_exclusion":"Employees","provision_group_inclusion":"Employees","provision_attachments_permission":true,"provision_dav_permission":true,"provision_ftp_permission":true,"provision_sftp_permission":true,"provision_time_zone":"Eastern Time (US & Canada)"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/sso_strategies/{id}.xml ]
      -X PATCH \
      -H 'Content-Type: application/xml' \
      -d '<sso-strategy>
           <provider>okta</provider>
           <subdomain>subdomain</subdomain>
           <client_id>[client id]</client_id>
           <client_secret>[client secret]</client_secret>
           <provision_users type="boolean">true</provision_users>
           <provision_groups type="boolean">true</provision_groups>
           <provision_group_default>Employees</provision_group_default>
           <provision_group_exclusion>Employees</provision_group_exclusion>
           <provision_group_inclusion>Employees</provision_group_inclusion>
           <provision_attachments_permission type="boolean">true</provision_attachments_permission>
           <provision_dav_permission type="boolean">true</provision_dav_permission>
           <provision_ftp_permission type="boolean">true</provision_ftp_permission>
           <provision_sftp_permission type="boolean">true</provision_sftp_permission>
           <provision_time_zone>Eastern Time (US &amp; Canada)</provision_time_zone>
         </sso-strategy>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    sso_strategy = Files::SsoStrategy.find(1)
    sso_strategy.update(
      provider: "okta",
      subdomain: "subdomain",
      client_id: "[client id]",
      client_secret: "[client secret]",
      provision_users: true,
      provision_groups: true,
      provision_group_default: "Employees",
      provision_group_exclusion: "Employees",
      provision_group_inclusion: "Employees",
      provision_attachments_permission: true,
      provision_dav_permission: true,
      provision_ftp_permission: true,
      provision_sftp_permission: true,
      provision_time_zone: "Eastern Time (US & Canada)"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $sso_strategy = \Files\SsoStrategy->find(1);
    $sso_strategy->update(array(
      'provider' => "okta", 
      'subdomain' => "subdomain", 
      'client_id' => "[client id]", 
      'client_secret' => "[client secret]", 
      'provision_users' => true, 
      'provision_groups' => true, 
      'provision_group_default' => "Employees", 
      'provision_group_exclusion' => "Employees", 
      'provision_group_inclusion' => "Employees", 
      'provision_attachments_permission' => true, 
      'provision_dav_permission' => true, 
      'provision_ftp_permission' => true, 
      'provision_sftp_permission' => true, 
      'provision_time_zone' => "Eastern Time (US & Canada)"
    ));
    

    Example Response

    {
      "provider": "okta",
      "id": 1,
      "subdomain": "my-site",
      "provision_users": true,
      "provision_groups": true,
      "provision_group_default": "Employees",
      "provision_group_exclusion": "Employees",
      "provision_group_inclusion": "Employees",
      "provision_group_required": "",
      "provision_attachments_permission": true,
      "provision_dav_permission": true,
      "provision_ftp_permission": true,
      "provision_sftp_permission": true,
      "provision_time_zone": "Eastern Time (US & Canada)"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <sso-strategy>
      <provider>okta</provider>
      <id type="integer">1</id>
      <subdomain>my-site</subdomain>
      <provision_users type="boolean">true</provision_users>
      <provision_groups type="boolean">true</provision_groups>
      <provision_group_default>Employees</provision_group_default>
      <provision_group_exclusion>Employees</provision_group_exclusion>
      <provision_group_inclusion>Employees</provision_group_inclusion>
      <provision_group_required></provision_group_required>
      <provision_attachments_permission type="boolean">true</provision_attachments_permission>
      <provision_dav_permission type="boolean">true</provision_dav_permission>
      <provision_ftp_permission type="boolean">true</provision_ftp_permission>
      <provision_sftp_permission type="boolean">true</provision_sftp_permission>
      <provision_time_zone>Eastern Time (US &amp; Canada)</provision_time_zone>
    </sso-strategy>
    
    

    HTTPS Request

    PATCH /sso_strategies/{id}

    Request Parameters

    Parameter Description
    id int64 Required Sso Strategy ID
    provider string Required One of the following: google, auth0, okta, atlassian_oauth2, azure_oauth2, box_oauth2, dropbox_oauth2, slack, ubuntu
    subdomain string Subdomain or domain name for your auth provider. Example: https://[subdomain].okta.com/
    client_id string OAuth Client ID for your auth provider.
    client_secret string OAuth Client Secret for your auth provider.
    provision_users boolean Auto-provision users?
    provision_groups boolean Auto-provision group memberships?
    provision_group_default string Comma-separated list of group names for groups to automatically add all auto-provisioned users to.
    provision_group_exclusion string Comma-separated list of group names for groups (with optional wildcards) that will be excluded from auto-provisioning.
    provision_group_inclusion string Comma-separated list of group names for groups (with optional wildcards) that will be auto-provisioned.
    provision_group_required string Comma or newline separated list of group names (with optional wildcards) to require membership for user provisioning.
    provision_attachments_permission boolean Provisioned users to get sharing permission?
    provision_dav_permission boolean Provisioned users to get WebDAV permission?
    provision_ftp_permission boolean Provisioned users to get FTP permission?
    provision_sftp_permission boolean Provisioned users to get SFTP permission?
    provision_time_zone string Default timezone to use for provisioned users

    Delete Sso Strategy

    Example Request

    curl https://app.files.com/api/rest/v1/sso_strategies/{id}.json \
      -X DELETE \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/sso_strategies/{id}.xml ]
      -X DELETE \
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    sso_strategy = Files::SsoStrategy.find(1)
    sso_strategy.delete
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $sso_strategy = \Files\SsoStrategy->find(1);
    $sso_strategy->delete();
    

    Example Response

    No response.
    
    No response.
    

    HTTPS Request

    DELETE /sso_strategies/{id}

    Request Parameters

    Parameter Description
    id int64 Required Sso Strategy ID.

    Styles

    The Styles resource in the REST API allows you to operate on Styles. Styles are custom sets of branding that can be applied on a per-folder basis. Currently these only support Logos per folder, but in the future we may extend these to also support colors. If you want to see that, please let us know so we can add your vote to the list.

    The Style object

    Example Style Object

    {
      "logo": "",
      "path": "",
      "thumbnail": ""
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <style>
      <logo></logo>
      <path></path>
      <thumbnail></thumbnail>
    </style>
    
    
    Attribute Description
    logo Logo
    path string Folder path This must be slash-delimited, but it must neither start nor end with a slash. Maximum of 5000 characters.
    thumbnail Logo thumbnail

    Update style

    Example Request

    curl https://app.files.com/api/rest/v1/styles/{path} \
      -X PUT \
      -H 'Content-Type: application/json' \
      -d '{"file":"file"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/styles/{path} ]
      -X PUT \
      -H 'Content-Type: application/xml' \
      -d '<style>
           <file>file</file>
         </style>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Style.update(path, 
      file: "file"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Style::update($path, array(
      'file' => "file"
    ));
    

    Example Response

    {
      "logo": "",
      "path": "",
      "thumbnail": ""
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <style>
      <logo></logo>
      <path></path>
      <thumbnail></thumbnail>
    </style>
    
    

    HTTPS Request

    PUT /styles/?*path

    Request Parameters

    Parameter Description
    path string Required Style path.
    file file Required Logo for custom branding.

    Delete style

    Example Request

    curl https://app.files.com/api/rest/v1/styles/{path} \
      -X DELETE \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/styles/{path} ]
      -X DELETE \
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::Style.delete(path)
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\Style::delete($path);
    

    Example Response

    No response.
    
    No response.
    

    HTTPS Request

    DELETE /styles/?*path

    Request Parameters

    Parameter Description
    path string Required Style path.

    Two Factor Authentication Methods

    The TwoFactorAuthenticationMethods resource in the REST API allows you to operate on TwoFactorAuthenticationMethods.

    The TwoFactorAuthenticationMethod object

    Example TwoFactorAuthenticationMethod Object

    {
      "id": 1,
      "method_type": "yubi",
      "name": "Yubikey",
      "phone_number": "(555) 555-5555",
      "phone_number_country": "US",
      "phone_number_national_format": "+15555555555",
      "setup_expired": true,
      "setup_complete": true,
      "setup_expires_at": "2000-01-01 01:00:00 UTC",
      "totp_provisioning_uri": "https://...",
      "u2f_app_id": "app id",
      "u2f_registration_requests": [
    
      ]
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <two-factor-authentication-method>
      <id type="integer">1</id>
      <method_type>yubi</method_type>
      <name>Yubikey</name>
      <phone_number>(555) 555-5555</phone_number>
      <phone_number_country>US</phone_number_country>
      <phone_number_national_format>+15555555555</phone_number_national_format>
      <setup_expired type="boolean">true</setup_expired>
      <setup_complete type="boolean">true</setup_complete>
      <setup_expires_at type="dateTime">2000-01-01T01:00:00Z</setup_expires_at>
      <totp_provisioning_uri>https://...</totp_provisioning_uri>
      <u2f_app_id>app id</u2f_app_id>
      <u2f_registration_requests type="array"/>
    </two-factor-authentication-method>
    
    
    Attribute Description
    id int64 2fa ID
    method_type string Type of 2fa. Can be totp, yubi, sms, or u2f
    name string 2fa name
    phone_number string 2fa phone number (if SMS)
    phone_number_country string 2fa phone number country (if SMS)
    phone_number_national_format string 2fa phone number national format (if SMS)
    setup_expired boolean 2fa setup expired?
    setup_complete boolean 2fa setup complete?
    setup_expires_at date-time 2fa setup expires at this date/time (typically 10 minutes after a new method is created)
    totp_provisioning_uri string TOTP provisioning URI (if TOTP)
    u2f_app_id string U2F app ID (if U2F)
    u2f_registration_requests array U2F registration requests (if U2F)

    List current user's 2FA methods

    Example Request

    curl https://app.files.com/api/rest/v1/2fa.json \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/2fa.xml ]
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::TwoFactorAuthenticationMethod.get
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\TwoFactorAuthenticationMethod::get();
    

    Example Response

    [
      {
        "id": 1,
        "method_type": "yubi",
        "name": "Yubikey",
        "phone_number": "(555) 555-5555",
        "phone_number_country": "US",
        "phone_number_national_format": "+15555555555",
        "setup_expired": true,
        "setup_complete": true,
        "setup_expires_at": "2000-01-01 01:00:00 UTC",
        "totp_provisioning_uri": "https://...",
        "u2f_app_id": "app id",
        "u2f_registration_requests": [
    
        ]
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <two-factor-authentication-methods type="array">
      <two-factor-authentication-method>
        <id type="integer">1</id>
        <method_type>yubi</method_type>
        <name>Yubikey</name>
        <phone_number>(555) 555-5555</phone_number>
        <phone_number_country>US</phone_number_country>
        <phone_number_national_format>+15555555555</phone_number_national_format>
        <setup_expired type="boolean">true</setup_expired>
        <setup_complete type="boolean">true</setup_complete>
        <setup_expires_at type="dateTime">2000-01-01T01:00:00Z</setup_expires_at>
        <totp_provisioning_uri>https://...</totp_provisioning_uri>
        <u2f_app_id>app id</u2f_app_id>
        <u2f_registration_requests type="array"/>
      </two-factor-authentication-method>
    </two-factor-authentication-methods>
    
    

    HTTPS Request

    GET /2fa

    Create 2FA method on current user

    Example Request

    curl https://app.files.com/api/rest/v1/2fa.json \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{"method_type":"sms","name":"My Verizon Phone","phone_number":"+12223334444"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/2fa.xml ]
      -X POST \
      -H 'Content-Type: application/xml' \
      -d '<two-factor-authentication-method>
           <method_type>sms</method_type>
           <name>My Verizon Phone</name>
           <phone_number>+12223334444</phone_number>
         </two-factor-authentication-method>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::TwoFactorAuthenticationMethod.create(
      method_type: "sms", 
      name: "My Verizon Phone", 
      phone_number: "+12223334444"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\TwoFactorAuthenticationMethod::create(array(
      'method_type' => "sms", 
      'name' => "My Verizon Phone", 
      'phone_number' => "+12223334444"
    ));
    

    Example Response

    {
      "id": 1,
      "method_type": "yubi",
      "name": "Yubikey",
      "phone_number": "(555) 555-5555",
      "phone_number_country": "US",
      "phone_number_national_format": "+15555555555",
      "setup_expired": true,
      "setup_complete": true,
      "setup_expires_at": "2000-01-01 01:00:00 UTC",
      "totp_provisioning_uri": "https://...",
      "u2f_app_id": "app id",
      "u2f_registration_requests": [
    
      ]
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <two-factor-authentication-method>
      <id type="integer">1</id>
      <method_type>yubi</method_type>
      <name>Yubikey</name>
      <phone_number>(555) 555-5555</phone_number>
      <phone_number_country>US</phone_number_country>
      <phone_number_national_format>+15555555555</phone_number_national_format>
      <setup_expired type="boolean">true</setup_expired>
      <setup_complete type="boolean">true</setup_complete>
      <setup_expires_at type="dateTime">2000-01-01T01:00:00Z</setup_expires_at>
      <totp_provisioning_uri>https://...</totp_provisioning_uri>
      <u2f_app_id>app id</u2f_app_id>
      <u2f_registration_requests type="array"/>
    </two-factor-authentication-method>
    
    

    HTTPS Request

    POST /2fa

    Request Parameters

    Parameter Description
    method_type string Required One of: u2f, sms, totp, yubi
    name string Internal name, for reference only.
    phone_number string If method_type=sms, provide phone number.

    Generate (and send if applicable) a one time password for current user's primary 2FA method

    Example Request

    curl https://app.files.com/api/rest/v1/2fa/send_code.json \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{"u2f_only":true}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/2fa/send_code.xml ]
      -X POST \
      -H 'Content-Type: application/xml' \
      -d '<two-factor-authentication-methods>
           <u2f_only type="boolean">true</u2f_only>
         </two-factor-authentication-methods>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::TwoFactorAuthenticationMethod.send_code(
      u2f_only: true
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\TwoFactorAuthenticationMethod::sendCode(array(
      'u2f_only' => true
    ));
    

    Example Response

    [
      {
        "app_id": "[app id]",
        "challenge": "[challenge]",
        "sign_request": "[sign request]"
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <two-factor-authentication-methods type="array">
      <two-factor-authentication-method>
        <app_id>[app id]</app_id>
        <challenge>[challenge]</challenge>
        <sign_request>[sign request]</sign_request>
      </two-factor-authentication-method>
    </two-factor-authentication-methods>
    
    

    HTTPS Request

    POST /2fa/send_code

    Request Parameters

    Parameter Description
    u2f_only boolean Set to true to only generate an OTP for U2F (FIDO) keys and skip things like SMS.

    Update 2FA method

    Example Request

    curl https://app.files.com/api/rest/v1/2fa/{id}.json \
      -X PATCH \
      -H 'Content-Type: application/json' \
      -d '{"otp":"123456","name":"My Verizon Phone"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/2fa/{id}.xml ]
      -X PATCH \
      -H 'Content-Type: application/xml' \
      -d '<two-factor-authentication-method>
           <otp>123456</otp>
           <name>My Verizon Phone</name>
         </two-factor-authentication-method>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    two_factor_authentication_method = Files::TwoFactorAuthenticationMethod.find(1)
    two_factor_authentication_method.update(
      otp: "123456",
      name: "My Verizon Phone"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $two_factor_authentication_method = \Files\TwoFactorAuthenticationMethod->find(1);
    $two_factor_authentication_method->update(array(
      'otp' => "123456", 
      'name' => "My Verizon Phone"
    ));
    

    Example Response

    {
      "id": 1,
      "method_type": "yubi",
      "name": "Yubikey",
      "phone_number": "(555) 555-5555",
      "phone_number_country": "US",
      "phone_number_national_format": "+15555555555",
      "setup_expired": true,
      "setup_complete": true,
      "setup_expires_at": "2000-01-01 01:00:00 UTC",
      "totp_provisioning_uri": "https://...",
      "u2f_app_id": "app id",
      "u2f_registration_requests": [
    
      ]
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <two-factor-authentication-method>
      <id type="integer">1</id>
      <method_type>yubi</method_type>
      <name>Yubikey</name>
      <phone_number>(555) 555-5555</phone_number>
      <phone_number_country>US</phone_number_country>
      <phone_number_national_format>+15555555555</phone_number_national_format>
      <setup_expired type="boolean">true</setup_expired>
      <setup_complete type="boolean">true</setup_complete>
      <setup_expires_at type="dateTime">2000-01-01T01:00:00Z</setup_expires_at>
      <totp_provisioning_uri>https://...</totp_provisioning_uri>
      <u2f_app_id>app id</u2f_app_id>
      <u2f_registration_requests type="array"/>
    </two-factor-authentication-method>
    
    

    HTTPS Request

    PATCH /2fa/{id}

    Request Parameters

    Parameter Description
    id int64 Required 2FA Method ID.
    otp string Current value of OTP, Yubikey string, or U2F response value. U2F response value requires a json stringified object containing fields clientData, keyHandle, and signatureData.
    name string New name for 2FA method.

    Delete 2FA method

    Example Request

    curl https://app.files.com/api/rest/v1/2fa/{id}.json \
      -X DELETE \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/2fa/{id}.xml ]
      -X DELETE \
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    two_factor_authentication_method = Files::TwoFactorAuthenticationMethod.find(1)
    two_factor_authentication_method.delete
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $two_factor_authentication_method = \Files\TwoFactorAuthenticationMethod->find(1);
    $two_factor_authentication_method->delete();
    

    Example Response

    No response.
    
    No response.
    

    HTTPS Request

    DELETE /2fa/{id}

    Request Parameters

    Parameter Description
    id int64 Required 2FA Method ID.

    Users

    The Users resource in the REST API allows you to operate on Users.

    The User object

    Example User Object

    {
      "id": 1,
      "admin_group_ids": [
    
      ],
      "allowed_ips": "127.0.0.1",
      "attachments_permission": true,
      "authenticate_until": "2000-01-01 01:00:00 UTC",
      "authentication_method": "password",
      "bypass_site_allowed_ips": true,
      "dav_permission": true,
      "email": "john.doe@files.com",
      "ftp_permission": true,
      "group_ids": [
    
      ],
      "language": "en",
      "last_login_at": "2000-01-01 01:00:00 UTC",
      "last_protocol_cipher": "",
      "lockout_expires": "2000-01-01 01:00:00 UTC",
      "name": "John Doe",
      "notes": "Internal notes on this user.",
      "password_set_at": "2000-01-01 01:00:00 UTC",
      "password_validity_days": 1,
      "public_keys_count": 1,
      "receive_admin_alerts": true,
      "require_2fa": true,
      "require_password_change": true,
      "restapi_permission": true,
      "self_managed": true,
      "sftp_permission": true,
      "site_admin": true,
      "ssl_required": "always_require",
      "sso_strategy_id": 1,
      "subscribe_to_newsletter": true,
      "externally_managed": true,
      "time_zone": "Pacific Time (US & Canada)",
      "type_of_2fa": "",
      "user_root": "",
      "username": "user"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <user>
      <id type="integer">1</id>
      <admin_group_ids type="array"/>
      <allowed_ips>127.0.0.1</allowed_ips>
      <attachments_permission type="boolean">true</attachments_permission>
      <authenticate_until type="dateTime">2000-01-01T01:00:00Z</authenticate_until>
      <authentication_method>password</authentication_method>
      <bypass_site_allowed_ips type="boolean">true</bypass_site_allowed_ips>
      <dav_permission type="boolean">true</dav_permission>
      <email>john.doe@files.com</email>
      <ftp_permission type="boolean">true</ftp_permission>
      <group_ids type="array"/>
      <language>en</language>
      <last_login_at type="dateTime">2000-01-01T01:00:00Z</last_login_at>
      <last_protocol_cipher></last_protocol_cipher>
      <lockout_expires type="dateTime">2000-01-01T01:00:00Z</lockout_expires>
      <name>John Doe</name>
      <notes>Internal notes on this user.</notes>
      <password_set_at type="dateTime">2000-01-01T01:00:00Z</password_set_at>
      <password_validity_days type="integer">1</password_validity_days>
      <public_keys_count type="integer">1</public_keys_count>
      <receive_admin_alerts type="boolean">true</receive_admin_alerts>
      <require_2fa type="boolean">true</require_2fa>
      <require_password_change type="boolean">true</require_password_change>
      <restapi_permission type="boolean">true</restapi_permission>
      <self_managed type="boolean">true</self_managed>
      <sftp_permission type="boolean">true</sftp_permission>
      <site_admin type="boolean">true</site_admin>
      <ssl_required>always_require</ssl_required>
      <sso_strategy_id type="integer">1</sso_strategy_id>
      <subscribe_to_newsletter type="boolean">true</subscribe_to_newsletter>
      <externally_managed type="boolean">true</externally_managed>
      <time_zone>Pacific Time (US &amp; Canada)</time_zone>
      <type_of_2fa></type_of_2fa>
      <user_root></user_root>
      <username>user</username>
    </user>
    
    
    Attribute Description
    id int64 User ID
    admin_group_ids array List of group IDs of which this user is an administrator
    allowed_ips string A list of allowed IPs if applicable. Newline delimited
    attachments_permission boolean Can the user create Bundles (aka Share Links)? This field will be aliased or renamed in the future to bundles_permission.
    authenticate_until date-time Scheduled Date/Time at which user will be deactivated
    authentication_method string How is this user authenticated? One of password, ldap, or sso
    bypass_site_allowed_ips boolean Allow this user to skip site-wide IP blacklists?
    dav_permission boolean Can the user connect with WebDAV?
    email email User email address
    ftp_permission boolean Can the user access with FTP/FTPS?
    group_ids array List of group IDs of which this user is a member
    language string Preferred language
    last_login_at date-time User's last login time
    last_protocol_cipher string The last protocol and cipher used
    lockout_expires date-time Time in the future that the user will no longer be locked out if applicable
    name string User's full name
    notes string Any internal notes on the user
    password_set_at date-time Last time the user's password was set
    password_validity_days int64 Number of days to allow user to use the same password
    public_keys_count int64 Number of public keys associated with this user
    receive_admin_alerts boolean Should the user receive admin alerts such a certificate expiration notifications and overages?
    require_2fa boolean Is 2fa required to sign in?
    require_password_change boolean Is a password change required upon next user login?
    restapi_permission boolean Can this user access the REST API?
    self_managed boolean Does this user manage it's own credentials or is it a shared/bot user?
    sftp_permission boolean Can the user access with SFTP?
    site_admin boolean Is the user an administrator for this site?
    ssl_required string SSL required setting. Can be system_setting, always_require, or never_require.
    sso_strategy_id int64 SSO (Single Sign On) strategy ID for the user, if applicable.
    subscribe_to_newsletter boolean Is the user subscribed to the newsletter?
    externally_managed boolean Is this user managed by an external source (such as LDAP)?
    time_zone string User time zone
    type_of_2fa string Type(s) of 2FA methods in use. Will be either sms, totp, u2f, yubi, or multiple values sorted alphabetically and joined by an underscore.
    user_root string Root folder for FTP (and optionally SFTP if the appropriate site-wide setting is set.) Note that this is not used for API, Desktop, or Web interface.
    username string User's username

    List users

    Example Request

    curl https://app.files.com/api/rest/v1/users.json \
      -H 'Content-Type: application/json' \
      -d '{"page":1,"per_page":1}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/users.xml ]
      -H 'Content-Type: application/xml' \
      -d '<users>
           <page type="integer">1</page>
           <per_page type="integer">1</per_page>
         </users>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::User.list(
      page: 1, 
      per_page: 1
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\User::list(array(
      'page' => 1, 
      'per_page' => 1
    ));
    

    Example Response

    [
      {
        "id": 1,
        "admin_group_ids": [
    
        ],
        "allowed_ips": "127.0.0.1",
        "attachments_permission": true,
        "authenticate_until": "2000-01-01 01:00:00 UTC",
        "authentication_method": "password",
        "bypass_site_allowed_ips": true,
        "dav_permission": true,
        "email": "john.doe@files.com",
        "ftp_permission": true,
        "group_ids": [
    
        ],
        "language": "en",
        "last_login_at": "2000-01-01 01:00:00 UTC",
        "last_protocol_cipher": "",
        "lockout_expires": "2000-01-01 01:00:00 UTC",
        "name": "John Doe",
        "notes": "Internal notes on this user.",
        "password_set_at": "2000-01-01 01:00:00 UTC",
        "password_validity_days": 1,
        "public_keys_count": 1,
        "receive_admin_alerts": true,
        "require_2fa": true,
        "require_password_change": true,
        "restapi_permission": true,
        "self_managed": true,
        "sftp_permission": true,
        "site_admin": true,
        "ssl_required": "always_require",
        "sso_strategy_id": 1,
        "subscribe_to_newsletter": true,
        "externally_managed": true,
        "time_zone": "Pacific Time (US & Canada)",
        "type_of_2fa": "",
        "user_root": "",
        "username": "user"
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <users type="array">
      <user>
        <id type="integer">1</id>
        <admin_group_ids type="array"/>
        <allowed_ips>127.0.0.1</allowed_ips>
        <attachments_permission type="boolean">true</attachments_permission>
        <authenticate_until type="dateTime">2000-01-01T01:00:00Z</authenticate_until>
        <authentication_method>password</authentication_method>
        <bypass_site_allowed_ips type="boolean">true</bypass_site_allowed_ips>
        <dav_permission type="boolean">true</dav_permission>
        <email>john.doe@files.com</email>
        <ftp_permission type="boolean">true</ftp_permission>
        <group_ids type="array"/>
        <language>en</language>
        <last_login_at type="dateTime">2000-01-01T01:00:00Z</last_login_at>
        <last_protocol_cipher></last_protocol_cipher>
        <lockout_expires type="dateTime">2000-01-01T01:00:00Z</lockout_expires>
        <name>John Doe</name>
        <notes>Internal notes on this user.</notes>
        <password_set_at type="dateTime">2000-01-01T01:00:00Z</password_set_at>
        <password_validity_days type="integer">1</password_validity_days>
        <public_keys_count type="integer">1</public_keys_count>
        <receive_admin_alerts type="boolean">true</receive_admin_alerts>
        <require_2fa type="boolean">true</require_2fa>
        <require_password_change type="boolean">true</require_password_change>
        <restapi_permission type="boolean">true</restapi_permission>
        <self_managed type="boolean">true</self_managed>
        <sftp_permission type="boolean">true</sftp_permission>
        <site_admin type="boolean">true</site_admin>
        <ssl_required>always_require</ssl_required>
        <sso_strategy_id type="integer">1</sso_strategy_id>
        <subscribe_to_newsletter type="boolean">true</subscribe_to_newsletter>
        <externally_managed type="boolean">true</externally_managed>
        <time_zone>Pacific Time (US &amp; Canada)</time_zone>
        <type_of_2fa></type_of_2fa>
        <user_root></user_root>
        <username>user</username>
      </user>
    </users>
    
    

    HTTPS Request

    GET /users

    Request Parameters

    Parameter Description
    ids string Comma-separated list of user ids to include in results.
    page int64 Current page.
    per_page int64 Users per page.
    q[username] string List users matching username.
    q[email] string List users matching email.
    q[notes] string List users matching notes field.
    q[admin] string If true, list only admin users.
    q[allowed_ips] string If set, list only users with overridden allowed IP setting.
    q[password_validity_days] string If set, list only users with overridden password validity days setting.
    q[ssl_required] string If set, list only users with overridden SSL required setting.
    search string Searches for partial matches of name, username, or email.
    action string If set to 'count' returns the current site user count.

    Show user

    Example Request

    curl https://app.files.com/api/rest/v1/users/{id}.json \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/users/{id}.xml ]
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::User.find(id)
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\User::find($id);
    

    Example Response

    {
      "id": 1,
      "admin_group_ids": [
    
      ],
      "allowed_ips": "127.0.0.1",
      "attachments_permission": true,
      "authenticate_until": "2000-01-01 01:00:00 UTC",
      "authentication_method": "password",
      "bypass_site_allowed_ips": true,
      "dav_permission": true,
      "email": "john.doe@files.com",
      "ftp_permission": true,
      "group_ids": [
    
      ],
      "language": "en",
      "last_login_at": "2000-01-01 01:00:00 UTC",
      "last_protocol_cipher": "",
      "lockout_expires": "2000-01-01 01:00:00 UTC",
      "name": "John Doe",
      "notes": "Internal notes on this user.",
      "password_set_at": "2000-01-01 01:00:00 UTC",
      "password_validity_days": 1,
      "public_keys_count": 1,
      "receive_admin_alerts": true,
      "require_2fa": true,
      "require_password_change": true,
      "restapi_permission": true,
      "self_managed": true,
      "sftp_permission": true,
      "site_admin": true,
      "ssl_required": "always_require",
      "sso_strategy_id": 1,
      "subscribe_to_newsletter": true,
      "externally_managed": true,
      "time_zone": "Pacific Time (US & Canada)",
      "type_of_2fa": "",
      "user_root": "",
      "username": "user"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <user>
      <id type="integer">1</id>
      <admin_group_ids type="array"/>
      <allowed_ips>127.0.0.1</allowed_ips>
      <attachments_permission type="boolean">true</attachments_permission>
      <authenticate_until type="dateTime">2000-01-01T01:00:00Z</authenticate_until>
      <authentication_method>password</authentication_method>
      <bypass_site_allowed_ips type="boolean">true</bypass_site_allowed_ips>
      <dav_permission type="boolean">true</dav_permission>
      <email>john.doe@files.com</email>
      <ftp_permission type="boolean">true</ftp_permission>
      <group_ids type="array"/>
      <language>en</language>
      <last_login_at type="dateTime">2000-01-01T01:00:00Z</last_login_at>
      <last_protocol_cipher></last_protocol_cipher>
      <lockout_expires type="dateTime">2000-01-01T01:00:00Z</lockout_expires>
      <name>John Doe</name>
      <notes>Internal notes on this user.</notes>
      <password_set_at type="dateTime">2000-01-01T01:00:00Z</password_set_at>
      <password_validity_days type="integer">1</password_validity_days>
      <public_keys_count type="integer">1</public_keys_count>
      <receive_admin_alerts type="boolean">true</receive_admin_alerts>
      <require_2fa type="boolean">true</require_2fa>
      <require_password_change type="boolean">true</require_password_change>
      <restapi_permission type="boolean">true</restapi_permission>
      <self_managed type="boolean">true</self_managed>
      <sftp_permission type="boolean">true</sftp_permission>
      <site_admin type="boolean">true</site_admin>
      <ssl_required>always_require</ssl_required>
      <sso_strategy_id type="integer">1</sso_strategy_id>
      <subscribe_to_newsletter type="boolean">true</subscribe_to_newsletter>
      <externally_managed type="boolean">true</externally_managed>
      <time_zone>Pacific Time (US &amp; Canada)</time_zone>
      <type_of_2fa></type_of_2fa>
      <user_root></user_root>
      <username>user</username>
    </user>
    
    

    HTTPS Request

    GET /users/{id}

    Request Parameters

    Parameter Description
    id int64 Required User ID.

    List current user's group memberships

    Example Request

    curl https://app.files.com/api/rest/v1/user/groups.json \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/user/groups.xml ]
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::User.groups
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\User::groups();
    

    Example Response

    [
      {
        "id": 1,
        "admin": true,
        "name": "My Group",
        "usernames": [
    
        ]
      }
    ]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <users type="array">
      <user>
        <id type="integer">1</id>
        <admin type="boolean">true</admin>
        <name>My Group</name>
        <usernames type="array"/>
      </user>
    </users>
    
    

    HTTPS Request

    GET /user/groups

    Create user

    Example Request

    curl https://app.files.com/api/rest/v1/users.json \
      -X POST \
      -H 'Content-Type: application/json' \
      -d '{"email":"john.doe@files.com","allowed_ips":"127.0.0.1","attachments_permission":true,"authenticate_until":"2000-01-01 01:00:00 UTC","authentication_method":"password","bypass_site_allowed_ips":true,"dav_permission":true,"ftp_permission":true,"language":"en","name":"John Doe","notes":"Internal notes on this user.","password_validity_days":1,"receive_admin_alerts":true,"require_password_change":true,"restapi_permission":true,"self_managed":true,"sftp_permission":true,"site_admin":true,"ssl_required":"always_require","sso_strategy_id":1,"subscribe_to_newsletter":true,"time_zone":"Pacific Time (US & Canada)","username":"user"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/users.xml ]
      -X POST \
      -H 'Content-Type: application/xml' \
      -d '<user>
           <email>john.doe@files.com</email>
           <allowed_ips>127.0.0.1</allowed_ips>
           <attachments_permission type="boolean">true</attachments_permission>
           <authenticate_until type="dateTime">2000-01-01T01:00:00Z</authenticate_until>
           <authentication_method>password</authentication_method>
           <bypass_site_allowed_ips type="boolean">true</bypass_site_allowed_ips>
           <dav_permission type="boolean">true</dav_permission>
           <ftp_permission type="boolean">true</ftp_permission>
           <language>en</language>
           <name>John Doe</name>
           <notes>Internal notes on this user.</notes>
           <password_validity_days type="integer">1</password_validity_days>
           <receive_admin_alerts type="boolean">true</receive_admin_alerts>
           <require_password_change type="boolean">true</require_password_change>
           <restapi_permission type="boolean">true</restapi_permission>
           <self_managed type="boolean">true</self_managed>
           <sftp_permission type="boolean">true</sftp_permission>
           <site_admin type="boolean">true</site_admin>
           <ssl_required>always_require</ssl_required>
           <sso_strategy_id type="integer">1</sso_strategy_id>
           <subscribe_to_newsletter type="boolean">true</subscribe_to_newsletter>
           <time_zone>Pacific Time (US &amp; Canada)</time_zone>
           <username>user</username>
         </user>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::User.create(
      email: "john.doe@files.com", 
      allowed_ips: "127.0.0.1", 
      attachments_permission: true, 
      authenticate_until: "2000-01-01 01:00:00 UTC", 
      authentication_method: "password", 
      bypass_site_allowed_ips: true, 
      dav_permission: true, 
      ftp_permission: true, 
      language: "en", 
      name: "John Doe", 
      notes: "Internal notes on this user.", 
      password_validity_days: 1, 
      receive_admin_alerts: true, 
      require_password_change: true, 
      restapi_permission: true, 
      self_managed: true, 
      sftp_permission: true, 
      site_admin: true, 
      ssl_required: "always_require", 
      sso_strategy_id: 1, 
      subscribe_to_newsletter: true, 
      time_zone: "Pacific Time (US & Canada)", 
      username: "user"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\User::create(array(
      'email' => "john.doe@files.com", 
      'allowed_ips' => "127.0.0.1", 
      'attachments_permission' => true, 
      'authenticate_until' => "2000-01-01 01:00:00 UTC", 
      'authentication_method' => "password", 
      'bypass_site_allowed_ips' => true, 
      'dav_permission' => true, 
      'ftp_permission' => true, 
      'language' => "en", 
      'name' => "John Doe", 
      'notes' => "Internal notes on this user.", 
      'password_validity_days' => 1, 
      'receive_admin_alerts' => true, 
      'require_password_change' => true, 
      'restapi_permission' => true, 
      'self_managed' => true, 
      'sftp_permission' => true, 
      'site_admin' => true, 
      'ssl_required' => "always_require", 
      'sso_strategy_id' => 1, 
      'subscribe_to_newsletter' => true, 
      'time_zone' => "Pacific Time (US & Canada)", 
      'username' => "user"
    ));
    

    Example Response

    {
      "id": 1,
      "admin_group_ids": [
    
      ],
      "allowed_ips": "127.0.0.1",
      "attachments_permission": true,
      "authenticate_until": "2000-01-01 01:00:00 UTC",
      "authentication_method": "password",
      "bypass_site_allowed_ips": true,
      "dav_permission": true,
      "email": "john.doe@files.com",
      "ftp_permission": true,
      "group_ids": [
    
      ],
      "language": "en",
      "last_login_at": "2000-01-01 01:00:00 UTC",
      "last_protocol_cipher": "",
      "lockout_expires": "2000-01-01 01:00:00 UTC",
      "name": "John Doe",
      "notes": "Internal notes on this user.",
      "password_set_at": "2000-01-01 01:00:00 UTC",
      "password_validity_days": 1,
      "public_keys_count": 1,
      "receive_admin_alerts": true,
      "require_2fa": true,
      "require_password_change": true,
      "restapi_permission": true,
      "self_managed": true,
      "sftp_permission": true,
      "site_admin": true,
      "ssl_required": "always_require",
      "sso_strategy_id": 1,
      "subscribe_to_newsletter": true,
      "externally_managed": true,
      "time_zone": "Pacific Time (US & Canada)",
      "type_of_2fa": "",
      "user_root": "",
      "username": "user"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <user>
      <id type="integer">1</id>
      <admin_group_ids type="array"/>
      <allowed_ips>127.0.0.1</allowed_ips>
      <attachments_permission type="boolean">true</attachments_permission>
      <authenticate_until type="dateTime">2000-01-01T01:00:00Z</authenticate_until>
      <authentication_method>password</authentication_method>
      <bypass_site_allowed_ips type="boolean">true</bypass_site_allowed_ips>
      <dav_permission type="boolean">true</dav_permission>
      <email>john.doe@files.com</email>
      <ftp_permission type="boolean">true</ftp_permission>
      <group_ids type="array"/>
      <language>en</language>
      <last_login_at type="dateTime">2000-01-01T01:00:00Z</last_login_at>
      <last_protocol_cipher></last_protocol_cipher>
      <lockout_expires type="dateTime">2000-01-01T01:00:00Z</lockout_expires>
      <name>John Doe</name>
      <notes>Internal notes on this user.</notes>
      <password_set_at type="dateTime">2000-01-01T01:00:00Z</password_set_at>
      <password_validity_days type="integer">1</password_validity_days>
      <public_keys_count type="integer">1</public_keys_count>
      <receive_admin_alerts type="boolean">true</receive_admin_alerts>
      <require_2fa type="boolean">true</require_2fa>
      <require_password_change type="boolean">true</require_password_change>
      <restapi_permission type="boolean">true</restapi_permission>
      <self_managed type="boolean">true</self_managed>
      <sftp_permission type="boolean">true</sftp_permission>
      <site_admin type="boolean">true</site_admin>
      <ssl_required>always_require</ssl_required>
      <sso_strategy_id type="integer">1</sso_strategy_id>
      <subscribe_to_newsletter type="boolean">true</subscribe_to_newsletter>
      <externally_managed type="boolean">true</externally_managed>
      <time_zone>Pacific Time (US &amp; Canada)</time_zone>
      <type_of_2fa></type_of_2fa>
      <user_root></user_root>
      <username>user</username>
    </user>
    
    

    HTTPS Request

    POST /users

    Request Parameters

    Parameter Description
    change_password string Used for changing a password on an existing user.
    change_password_confirmation string Optional, but if provided, we will ensure that it matches the value sent in change_password.
    email string User's email.
    grant_permission string Permission to grant on the user root. Can be blank or full, read, write, preview, or history.
    group_ids string A list of group ids to associate this user with. Comma delimited.
    password string User password.
    password_confirmation string Optional, but if provided, we will ensure that it matches the value sent in password.
    allowed_ips string A list of allowed IPs if applicable. Newline delimited
    attachments_permission boolean Can the user create Bundles (aka Share Links)? This field will be aliased or renamed in the future to bundles_permission.
    authenticate_until string Scheduled Date/Time at which user will be deactivated
    authentication_method string How is this user authenticated? One of password, ldap, or sso
    bypass_site_allowed_ips boolean Allow this user to skip site-wide IP blacklists?
    dav_permission boolean Can the user connect with WebDAV?
    ftp_permission boolean Can the user access with FTP/FTPS?
    language string Preferred language
    name string User's full name
    notes string Any internal notes on the user
    password_validity_days int64 Number of days to allow user to use the same password
    receive_admin_alerts boolean Should the user receive admin alerts such a certificate expiration notifications and overages?
    require_password_change boolean Is a password change required upon next user login?
    restapi_permission boolean Can this user access the REST API?
    self_managed boolean Does this user manage it's own credentials or is it a shared/bot user?
    sftp_permission boolean Can the user access with SFTP?
    site_admin boolean Is the user an administrator for this site?
    ssl_required string SSL required setting. Can be system_setting, always_require, or never_require.
    sso_strategy_id int64 SSO (Single Sign On) strategy ID for the user, if applicable.
    subscribe_to_newsletter boolean Is the user subscribed to the newsletter?
    time_zone string User time zone
    user_root string Root folder for FTP (and optionally SFTP if the appropriate site-wide setting is set.) Note that this is not used for API, Desktop, or Web interface.
    username string User's username

    Unlock user who has been locked out due to failed logins

    Example Request

    curl https://app.files.com/api/rest/v1/users/{id}/unlock.json \
      -X POST \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/users/{id}/unlock.xml ]
      -X POST \
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    user = Files::User.find(1)
    user.unlock
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $user = \Files\User->find(1);
    $user->unlock();
    

    Example Response

    {
      "id": 1,
      "admin_group_ids": [
    
      ],
      "allowed_ips": "127.0.0.1",
      "attachments_permission": true,
      "authenticate_until": "2000-01-01 01:00:00 UTC",
      "authentication_method": "password",
      "bypass_site_allowed_ips": true,
      "dav_permission": true,
      "email": "john.doe@files.com",
      "ftp_permission": true,
      "group_ids": [
    
      ],
      "language": "en",
      "last_login_at": "2000-01-01 01:00:00 UTC",
      "last_protocol_cipher": "",
      "lockout_expires": "2000-01-01 01:00:00 UTC",
      "name": "John Doe",
      "notes": "Internal notes on this user.",
      "password_set_at": "2000-01-01 01:00:00 UTC",
      "password_validity_days": 1,
      "public_keys_count": 1,
      "receive_admin_alerts": true,
      "require_2fa": true,
      "require_password_change": true,
      "restapi_permission": true,
      "self_managed": true,
      "sftp_permission": true,
      "site_admin": true,
      "ssl_required": "always_require",
      "sso_strategy_id": 1,
      "subscribe_to_newsletter": true,
      "externally_managed": true,
      "time_zone": "Pacific Time (US & Canada)",
      "type_of_2fa": "",
      "user_root": "",
      "username": "user"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <user>
      <id type="integer">1</id>
      <admin_group_ids type="array"/>
      <allowed_ips>127.0.0.1</allowed_ips>
      <attachments_permission type="boolean">true</attachments_permission>
      <authenticate_until type="dateTime">2000-01-01T01:00:00Z</authenticate_until>
      <authentication_method>password</authentication_method>
      <bypass_site_allowed_ips type="boolean">true</bypass_site_allowed_ips>
      <dav_permission type="boolean">true</dav_permission>
      <email>john.doe@files.com</email>
      <ftp_permission type="boolean">true</ftp_permission>
      <group_ids type="array"/>
      <language>en</language>
      <last_login_at type="dateTime">2000-01-01T01:00:00Z</last_login_at>
      <last_protocol_cipher></last_protocol_cipher>
      <lockout_expires type="dateTime">2000-01-01T01:00:00Z</lockout_expires>
      <name>John Doe</name>
      <notes>Internal notes on this user.</notes>
      <password_set_at type="dateTime">2000-01-01T01:00:00Z</password_set_at>
      <password_validity_days type="integer">1</password_validity_days>
      <public_keys_count type="integer">1</public_keys_count>
      <receive_admin_alerts type="boolean">true</receive_admin_alerts>
      <require_2fa type="boolean">true</require_2fa>
      <require_password_change type="boolean">true</require_password_change>
      <restapi_permission type="boolean">true</restapi_permission>
      <self_managed type="boolean">true</self_managed>
      <sftp_permission type="boolean">true</sftp_permission>
      <site_admin type="boolean">true</site_admin>
      <ssl_required>always_require</ssl_required>
      <sso_strategy_id type="integer">1</sso_strategy_id>
      <subscribe_to_newsletter type="boolean">true</subscribe_to_newsletter>
      <externally_managed type="boolean">true</externally_managed>
      <time_zone>Pacific Time (US &amp; Canada)</time_zone>
      <type_of_2fa></type_of_2fa>
      <user_root></user_root>
      <username>user</username>
    </user>
    
    

    HTTPS Request

    POST /users/{id}/unlock

    Request Parameters

    Parameter Description
    id int64 Required User ID.

    Resend user welcome email

    Example Request

    curl https://app.files.com/api/rest/v1/users/{id}/resend_welcome_email.json \
      -X POST \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/users/{id}/resend_welcome_email.xml ]
      -X POST \
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    user = Files::User.find(1)
    user.resend_welcome_email
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $user = \Files\User->find(1);
    $user->resendWelcomeEmail();
    

    Example Response

    {
      "id": 1,
      "admin_group_ids": [
    
      ],
      "allowed_ips": "127.0.0.1",
      "attachments_permission": true,
      "authenticate_until": "2000-01-01 01:00:00 UTC",
      "authentication_method": "password",
      "bypass_site_allowed_ips": true,
      "dav_permission": true,
      "email": "john.doe@files.com",
      "ftp_permission": true,
      "group_ids": [
    
      ],
      "language": "en",
      "last_login_at": "2000-01-01 01:00:00 UTC",
      "last_protocol_cipher": "",
      "lockout_expires": "2000-01-01 01:00:00 UTC",
      "name": "John Doe",
      "notes": "Internal notes on this user.",
      "password_set_at": "2000-01-01 01:00:00 UTC",
      "password_validity_days": 1,
      "public_keys_count": 1,
      "receive_admin_alerts": true,
      "require_2fa": true,
      "require_password_change": true,
      "restapi_permission": true,
      "self_managed": true,
      "sftp_permission": true,
      "site_admin": true,
      "ssl_required": "always_require",
      "sso_strategy_id": 1,
      "subscribe_to_newsletter": true,
      "externally_managed": true,
      "time_zone": "Pacific Time (US & Canada)",
      "type_of_2fa": "",
      "user_root": "",
      "username": "user"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <user>
      <id type="integer">1</id>
      <admin_group_ids type="array"/>
      <allowed_ips>127.0.0.1</allowed_ips>
      <attachments_permission type="boolean">true</attachments_permission>
      <authenticate_until type="dateTime">2000-01-01T01:00:00Z</authenticate_until>
      <authentication_method>password</authentication_method>
      <bypass_site_allowed_ips type="boolean">true</bypass_site_allowed_ips>
      <dav_permission type="boolean">true</dav_permission>
      <email>john.doe@files.com</email>
      <ftp_permission type="boolean">true</ftp_permission>
      <group_ids type="array"/>
      <language>en</language>
      <last_login_at type="dateTime">2000-01-01T01:00:00Z</last_login_at>
      <last_protocol_cipher></last_protocol_cipher>
      <lockout_expires type="dateTime">2000-01-01T01:00:00Z</lockout_expires>
      <name>John Doe</name>
      <notes>Internal notes on this user.</notes>
      <password_set_at type="dateTime">2000-01-01T01:00:00Z</password_set_at>
      <password_validity_days type="integer">1</password_validity_days>
      <public_keys_count type="integer">1</public_keys_count>
      <receive_admin_alerts type="boolean">true</receive_admin_alerts>
      <require_2fa type="boolean">true</require_2fa>
      <require_password_change type="boolean">true</require_password_change>
      <restapi_permission type="boolean">true</restapi_permission>
      <self_managed type="boolean">true</self_managed>
      <sftp_permission type="boolean">true</sftp_permission>
      <site_admin type="boolean">true</site_admin>
      <ssl_required>always_require</ssl_required>
      <sso_strategy_id type="integer">1</sso_strategy_id>
      <subscribe_to_newsletter type="boolean">true</subscribe_to_newsletter>
      <externally_managed type="boolean">true</externally_managed>
      <time_zone>Pacific Time (US &amp; Canada)</time_zone>
      <type_of_2fa></type_of_2fa>
      <user_root></user_root>
      <username>user</username>
    </user>
    
    

    HTTPS Request

    POST /users/{id}/resend_welcome_email

    Request Parameters

    Parameter Description
    id int64 Required User ID.

    Trigger 2FA Reset process for user who has lost access to their existing 2FA methods

    Example Request

    curl https://app.files.com/api/rest/v1/users/{id}/2fa/reset.json \
      -X POST \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/users/{id}/2fa/reset.xml ]
      -X POST \
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    user = Files::User.find(1)
    user.user_2fa_reset
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $user = \Files\User->find(1);
    $user->user2faReset();
    

    Example Response

    No response.
    
    No response.
    

    HTTPS Request

    POST /users/{id}/2fa/reset

    Request Parameters

    Parameter Description
    id int64 Required 2FA Method ID.

    Update user

    Example Request

    curl https://app.files.com/api/rest/v1/users/{id}.json \
      -X PUT \
      -H 'Content-Type: application/json' \
      -d '{"email":"john.doe@files.com","allowed_ips":"127.0.0.1","attachments_permission":true,"authenticate_until":"2000-01-01 01:00:00 UTC","authentication_method":"password","bypass_site_allowed_ips":true,"dav_permission":true,"ftp_permission":true,"language":"en","name":"John Doe","notes":"Internal notes on this user.","password_validity_days":1,"receive_admin_alerts":true,"require_password_change":true,"restapi_permission":true,"self_managed":true,"sftp_permission":true,"site_admin":true,"ssl_required":"always_require","sso_strategy_id":1,"subscribe_to_newsletter":true,"time_zone":"Pacific Time (US & Canada)","username":"user"}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/users/{id}.xml ]
      -X PUT \
      -H 'Content-Type: application/xml' \
      -d '<user>
           <email>john.doe@files.com</email>
           <allowed_ips>127.0.0.1</allowed_ips>
           <attachments_permission type="boolean">true</attachments_permission>
           <authenticate_until type="dateTime">2000-01-01T01:00:00Z</authenticate_until>
           <authentication_method>password</authentication_method>
           <bypass_site_allowed_ips type="boolean">true</bypass_site_allowed_ips>
           <dav_permission type="boolean">true</dav_permission>
           <ftp_permission type="boolean">true</ftp_permission>
           <language>en</language>
           <name>John Doe</name>
           <notes>Internal notes on this user.</notes>
           <password_validity_days type="integer">1</password_validity_days>
           <receive_admin_alerts type="boolean">true</receive_admin_alerts>
           <require_password_change type="boolean">true</require_password_change>
           <restapi_permission type="boolean">true</restapi_permission>
           <self_managed type="boolean">true</self_managed>
           <sftp_permission type="boolean">true</sftp_permission>
           <site_admin type="boolean">true</site_admin>
           <ssl_required>always_require</ssl_required>
           <sso_strategy_id type="integer">1</sso_strategy_id>
           <subscribe_to_newsletter type="boolean">true</subscribe_to_newsletter>
           <time_zone>Pacific Time (US &amp; Canada)</time_zone>
           <username>user</username>
         </user>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    user = Files::User.find(1)
    user.update(
      email: "john.doe@files.com",
      allowed_ips: "127.0.0.1",
      attachments_permission: true,
      authenticate_until: "2000-01-01 01:00:00 UTC",
      authentication_method: "password",
      bypass_site_allowed_ips: true,
      dav_permission: true,
      ftp_permission: true,
      language: "en",
      name: "John Doe",
      notes: "Internal notes on this user.",
      password_validity_days: 1,
      receive_admin_alerts: true,
      require_password_change: true,
      restapi_permission: true,
      self_managed: true,
      sftp_permission: true,
      site_admin: true,
      ssl_required: "always_require",
      sso_strategy_id: 1,
      subscribe_to_newsletter: true,
      time_zone: "Pacific Time (US & Canada)",
      username: "user"
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $user = \Files\User->find(1);
    $user->update(array(
      'email' => "john.doe@files.com", 
      'allowed_ips' => "127.0.0.1", 
      'attachments_permission' => true, 
      'authenticate_until' => "2000-01-01 01:00:00 UTC", 
      'authentication_method' => "password", 
      'bypass_site_allowed_ips' => true, 
      'dav_permission' => true, 
      'ftp_permission' => true, 
      'language' => "en", 
      'name' => "John Doe", 
      'notes' => "Internal notes on this user.", 
      'password_validity_days' => 1, 
      'receive_admin_alerts' => true, 
      'require_password_change' => true, 
      'restapi_permission' => true, 
      'self_managed' => true, 
      'sftp_permission' => true, 
      'site_admin' => true, 
      'ssl_required' => "always_require", 
      'sso_strategy_id' => 1, 
      'subscribe_to_newsletter' => true, 
      'time_zone' => "Pacific Time (US & Canada)", 
      'username' => "user"
    ));
    

    Example Response

    {
      "id": 1,
      "admin_group_ids": [
    
      ],
      "allowed_ips": "127.0.0.1",
      "attachments_permission": true,
      "authenticate_until": "2000-01-01 01:00:00 UTC",
      "authentication_method": "password",
      "bypass_site_allowed_ips": true,
      "dav_permission": true,
      "email": "john.doe@files.com",
      "ftp_permission": true,
      "group_ids": [
    
      ],
      "language": "en",
      "last_login_at": "2000-01-01 01:00:00 UTC",
      "last_protocol_cipher": "",
      "lockout_expires": "2000-01-01 01:00:00 UTC",
      "name": "John Doe",
      "notes": "Internal notes on this user.",
      "password_set_at": "2000-01-01 01:00:00 UTC",
      "password_validity_days": 1,
      "public_keys_count": 1,
      "receive_admin_alerts": true,
      "require_2fa": true,
      "require_password_change": true,
      "restapi_permission": true,
      "self_managed": true,
      "sftp_permission": true,
      "site_admin": true,
      "ssl_required": "always_require",
      "sso_strategy_id": 1,
      "subscribe_to_newsletter": true,
      "externally_managed": true,
      "time_zone": "Pacific Time (US & Canada)",
      "type_of_2fa": "",
      "user_root": "",
      "username": "user"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <user>
      <id type="integer">1</id>
      <admin_group_ids type="array"/>
      <allowed_ips>127.0.0.1</allowed_ips>
      <attachments_permission type="boolean">true</attachments_permission>
      <authenticate_until type="dateTime">2000-01-01T01:00:00Z</authenticate_until>
      <authentication_method>password</authentication_method>
      <bypass_site_allowed_ips type="boolean">true</bypass_site_allowed_ips>
      <dav_permission type="boolean">true</dav_permission>
      <email>john.doe@files.com</email>
      <ftp_permission type="boolean">true</ftp_permission>
      <group_ids type="array"/>
      <language>en</language>
      <last_login_at type="dateTime">2000-01-01T01:00:00Z</last_login_at>
      <last_protocol_cipher></last_protocol_cipher>
      <lockout_expires type="dateTime">2000-01-01T01:00:00Z</lockout_expires>
      <name>John Doe</name>
      <notes>Internal notes on this user.</notes>
      <password_set_at type="dateTime">2000-01-01T01:00:00Z</password_set_at>
      <password_validity_days type="integer">1</password_validity_days>
      <public_keys_count type="integer">1</public_keys_count>
      <receive_admin_alerts type="boolean">true</receive_admin_alerts>
      <require_2fa type="boolean">true</require_2fa>
      <require_password_change type="boolean">true</require_password_change>
      <restapi_permission type="boolean">true</restapi_permission>
      <self_managed type="boolean">true</self_managed>
      <sftp_permission type="boolean">true</sftp_permission>
      <site_admin type="boolean">true</site_admin>
      <ssl_required>always_require</ssl_required>
      <sso_strategy_id type="integer">1</sso_strategy_id>
      <subscribe_to_newsletter type="boolean">true</subscribe_to_newsletter>
      <externally_managed type="boolean">true</externally_managed>
      <time_zone>Pacific Time (US &amp; Canada)</time_zone>
      <type_of_2fa></type_of_2fa>
      <user_root></user_root>
      <username>user</username>
    </user>
    
    

    HTTPS Request

    PUT /users/{id}

    Request Parameters

    Parameter Description
    id int64 Required User ID to update.
    change_password string Used for changing a password on an existing user.
    change_password_confirmation string Optional, but if provided, we will ensure that it matches the value sent in change_password.
    email string User's email.
    grant_permission string Permission to grant on the user root. Can be blank or full, read, write, preview, or history.
    group_ids string A list of group ids to associate this user with. Comma delimited.
    password string User password.
    password_confirmation string Optional, but if provided, we will ensure that it matches the value sent in password.
    allowed_ips string A list of allowed IPs if applicable. Newline delimited
    attachments_permission boolean Can the user create Bundles (aka Share Links)? This field will be aliased or renamed in the future to bundles_permission.
    authenticate_until string Scheduled Date/Time at which user will be deactivated
    authentication_method string How is this user authenticated? One of password, ldap, or sso
    bypass_site_allowed_ips boolean Allow this user to skip site-wide IP blacklists?
    dav_permission boolean Can the user connect with WebDAV?
    ftp_permission boolean Can the user access with FTP/FTPS?
    language string Preferred language
    name string User's full name
    notes string Any internal notes on the user
    password_validity_days int64 Number of days to allow user to use the same password
    receive_admin_alerts boolean Should the user receive admin alerts such a certificate expiration notifications and overages?
    require_password_change boolean Is a password change required upon next user login?
    restapi_permission boolean Can this user access the REST API?
    self_managed boolean Does this user manage it's own credentials or is it a shared/bot user?
    sftp_permission boolean Can the user access with SFTP?
    site_admin boolean Is the user an administrator for this site?
    ssl_required string SSL required setting. Can be system_setting, always_require, or never_require.
    sso_strategy_id int64 SSO (Single Sign On) strategy ID for the user, if applicable.
    subscribe_to_newsletter boolean Is the user subscribed to the newsletter?
    time_zone string User time zone
    user_root string Root folder for FTP (and optionally SFTP if the appropriate site-wide setting is set.) Note that this is not used for API, Desktop, or Web interface.
    username string User's username

    Update current user

    Example Request

    curl https://app.files.com/api/rest/v1/user.json \
      -X PATCH \
      -H 'Content-Type: application/json' \
      -d '{"change_password":"password","change_password_confirmation":"password","email":"johndoe@gmail.com","time_zone":"Pacific Time (US & Canada)","language":"en","skip_welcome_screen":true,"announcements_read":true}' \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/user.xml ]
      -X PATCH \
      -H 'Content-Type: application/xml' \
      -d '<user>
           <change_password>password</change_password>
           <change_password_confirmation>password</change_password_confirmation>
           <email>johndoe@gmail.com</email>
           <time_zone>Pacific Time (US &amp; Canada)</time_zone>
           <language>en</language>
           <skip_welcome_screen type="boolean">true</skip_welcome_screen>
           <announcements_read type="boolean">true</announcements_read>
         </user>'
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    Files::User.update(
      change_password: "password", 
      change_password_confirmation: "password", 
      email: "johndoe@gmail.com", 
      time_zone: "Pacific Time (US & Canada)", 
      language: "en", 
      skip_welcome_screen: true, 
      announcements_read: true
    )
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    \Files\User::update(array(
      'change_password' => "password", 
      'change_password_confirmation' => "password", 
      'email' => "johndoe@gmail.com", 
      'time_zone' => "Pacific Time (US & Canada)", 
      'language' => "en", 
      'skip_welcome_screen' => true, 
      'announcements_read' => true
    ));
    

    Example Response

    {
      "id": 1,
      "admin_group_ids": [
    
      ],
      "allowed_ips": "127.0.0.1",
      "attachments_permission": true,
      "authenticate_until": "2000-01-01 01:00:00 UTC",
      "authentication_method": "password",
      "bypass_site_allowed_ips": true,
      "dav_permission": true,
      "email": "john.doe@files.com",
      "ftp_permission": true,
      "group_ids": [
    
      ],
      "language": "en",
      "last_login_at": "2000-01-01 01:00:00 UTC",
      "last_protocol_cipher": "",
      "lockout_expires": "2000-01-01 01:00:00 UTC",
      "name": "John Doe",
      "notes": "Internal notes on this user.",
      "password_set_at": "2000-01-01 01:00:00 UTC",
      "password_validity_days": 1,
      "public_keys_count": 1,
      "receive_admin_alerts": true,
      "require_2fa": true,
      "require_password_change": true,
      "restapi_permission": true,
      "self_managed": true,
      "sftp_permission": true,
      "site_admin": true,
      "ssl_required": "always_require",
      "sso_strategy_id": 1,
      "subscribe_to_newsletter": true,
      "externally_managed": true,
      "time_zone": "Pacific Time (US & Canada)",
      "type_of_2fa": "",
      "user_root": "",
      "username": "user"
    }
    
    <?xml version="1.0" encoding="UTF-8"?>
    <user>
      <id type="integer">1</id>
      <admin_group_ids type="array"/>
      <allowed_ips>127.0.0.1</allowed_ips>
      <attachments_permission type="boolean">true</attachments_permission>
      <authenticate_until type="dateTime">2000-01-01T01:00:00Z</authenticate_until>
      <authentication_method>password</authentication_method>
      <bypass_site_allowed_ips type="boolean">true</bypass_site_allowed_ips>
      <dav_permission type="boolean">true</dav_permission>
      <email>john.doe@files.com</email>
      <ftp_permission type="boolean">true</ftp_permission>
      <group_ids type="array"/>
      <language>en</language>
      <last_login_at type="dateTime">2000-01-01T01:00:00Z</last_login_at>
      <last_protocol_cipher></last_protocol_cipher>
      <lockout_expires type="dateTime">2000-01-01T01:00:00Z</lockout_expires>
      <name>John Doe</name>
      <notes>Internal notes on this user.</notes>
      <password_set_at type="dateTime">2000-01-01T01:00:00Z</password_set_at>
      <password_validity_days type="integer">1</password_validity_days>
      <public_keys_count type="integer">1</public_keys_count>
      <receive_admin_alerts type="boolean">true</receive_admin_alerts>
      <require_2fa type="boolean">true</require_2fa>
      <require_password_change type="boolean">true</require_password_change>
      <restapi_permission type="boolean">true</restapi_permission>
      <self_managed type="boolean">true</self_managed>
      <sftp_permission type="boolean">true</sftp_permission>
      <site_admin type="boolean">true</site_admin>
      <ssl_required>always_require</ssl_required>
      <sso_strategy_id type="integer">1</sso_strategy_id>
      <subscribe_to_newsletter type="boolean">true</subscribe_to_newsletter>
      <externally_managed type="boolean">true</externally_managed>
      <time_zone>Pacific Time (US &amp; Canada)</time_zone>
      <type_of_2fa></type_of_2fa>
      <user_root></user_root>
      <username>user</username>
    </user>
    
    

    HTTPS Request

    PATCH /user

    Request Parameters

    Parameter Description
    change_password string New password
    change_password_confirmation string Confirm new password (optional, but if provided it will be validated against the value in change_password)
    email string User's email address
    time_zone string User's time zone
    language string User's language (2 digit ISO code, lowercase)
    skip_welcome_screen boolean Hide the welcome screen in web UI?
    announcements_read boolean Has this user read the latest announcements?

    Delete user

    Example Request

    curl https://app.files.com/api/rest/v1/users/{id}.json \
      -X DELETE \
      -u YOUR_API_KEY:x
    
    curl https://app.files.com/api/rest/v1/users/{id}.xml ]
      -X DELETE \
      -u YOUR_API_KEY:x
    
    Files.api_key = 'YOUR_API_KEY'
    
    user = Files::User.find(1)
    user.delete
    
    \Files\Files::setApiKey('YOUR_API_KEY');
    
    $user = \Files\User->find(1);
    $user->delete();
    

    Example Response

    No response.
    
    No response.
    

    HTTPS Request

    DELETE /users/{id}

    Request Parameters

    Parameter Description
    id int64 Required User ID.