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 \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://SUBDOMAIN.files.com/api/rest/v1/users.xml \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

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.

You may provide the key to the API one of two ways. The simplest way is to set the X-FilesAPI-Key header with the value of the key.

Alternatively, you may use HTTP Basic Authentication. 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-FilesAPI-Auth: 8c2e9f493dd8a857d5cdddbb7bf64ece0b7fb599'

curl https://SUBDOMAIN.files.com/api/rest/v1/users.xml \
  -H 'X-FilesAPI-Auth: 8c2e9f493dd8a857d5cdddbb7bf64ece0b7fb599'

Once a session has been created, you authenticate to the REST API by sending a header called X-FilesAPI-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-FilesAPI-Auth: 8c2e9f493dd8a857d5cdddbb7bf64ece0b7fb599' \
  -H 'X-Files-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-FilesAPI-Auth: 8c2e9f493dd8a857d5cdddbb7bf64ece0b7fb599' \
  -H 'X-Files-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-Files-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:

Changing the password of a User
Deleting a User

Logging out

Example Request

curl https://SUBDOMAIN.files.com/api/rest/v1/sessions.json \
  -H 'X-FilesAPI-Auth: 8c2e9f493dd8a857d5cdddbb7bf64ece0b7fb599' \
  -X DELETE

curl https://SUBDOMAIN.files.com/api/rest/v1/sessions.xml \
  -H 'X-FilesAPI-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-FilesAPI-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.

Account Line Items

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

The AccountLineItem object

Example AccountLineItem Object

{
  "id": 1,
  "amount": "",
  "balance": "",
  "created_at": "2000-01-01T01:00:00Z",
  "currency": "USD",
  "download_uri": "https://url...",
  "invoice_line_items": [

  ],
  "method": "paypal",
  "payment_line_items": [

  ],
  "payment_reversed_at": "2000-01-01T01:00:00Z",
  "payment_type": "",
  "site_name": "My Site",
  "type": "invoice",
  "updated_at": "2000-01-01T01:00:00Z"
}

<?xml version="1.0" encoding="UTF-8"?>
<account-line-item>
  <id type="integer">1</id>
  <amount></amount>
  <balance></balance>
  <created_at>2000-01-01T01:00:00Z</created_at>
  <currency>USD</currency>
  <download_uri>https://url...</download_uri>
  <invoice_line_items type="array"/>
  <method>paypal</method>
  <payment_line_items type="array"/>
  <payment_reversed_at>2000-01-01T01:00:00Z</payment_reversed_at>
  <payment_type></payment_type>
  <site_name>My Site</site_name>
  <type>invoice</type>
  <updated_at>2000-01-01T01:00:00Z</updated_at>
</account-line-item>

Attribute	Description
id int64	Line item Id
amount double	Line item amount
balance double	Line item balance
created_at date-time	Line item created at
currency string	Line item currency
download_uri string	Line item download uri
invoice_line_items array	Associated invoice line items
method string	Line item payment method
payment_line_items array	Associated payment line items
payment_reversed_at date-time	Date/time payment was reversed if applicable
payment_type string	Type of payment if applicable
site_name string	Site name this line item is for
type string	Type of line item, either payment or invoice
updated_at date-time	Line item updated at

List Invoices

Example Request

curl "https://app.files.com/api/rest/v1/invoices.json?page=1&per_page=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/invoices.xml?page=1&per_page=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::Invoice.list(
  page: 1, 
  per_page: 1
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\Invoice::list(array(
  'page' => 1, 
  'per_page' => 1
));

Example Response

[
  {
    "id": 1,
    "amount": "",
    "balance": "",
    "created_at": "2000-01-01T01:00:00Z",
    "currency": "USD",
    "download_uri": "https://url...",
    "invoice_line_items": [

    ],
    "method": "paypal",
    "payment_line_items": [

    ],
    "payment_reversed_at": "2000-01-01T01:00:00Z",
    "payment_type": "",
    "site_name": "My Site",
    "type": "invoice",
    "updated_at": "2000-01-01T01:00:00Z"
  }
]

<?xml version="1.0" encoding="UTF-8"?>
<account-line-items type="array">
  <account-line-item>
    <id type="integer">1</id>
    <amount></amount>
    <balance></balance>
    <created_at>2000-01-01T01:00:00Z</created_at>
    <currency>USD</currency>
    <download_uri>https://url...</download_uri>
    <invoice_line_items type="array"/>
    <method>paypal</method>
    <payment_line_items type="array"/>
    <payment_reversed_at>2000-01-01T01:00:00Z</payment_reversed_at>
    <payment_type></payment_type>
    <site_name>My Site</site_name>
    <type>invoice</type>
    <updated_at>2000-01-01T01:00:00Z</updated_at>
  </account-line-item>
</account-line-items>

HTTPS Request

GET /invoices

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Deprecated: If set to `count` returns a count of matching records rather than the records themselves.

List Payments

Example Request

curl "https://app.files.com/api/rest/v1/payments.json?page=1&per_page=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/payments.xml?page=1&per_page=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::Payment.list(
  page: 1, 
  per_page: 1
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\Payment::list(array(
  'page' => 1, 
  'per_page' => 1
));

Example Response

[
  {
    "id": 1,
    "amount": "",
    "balance": "",
    "created_at": "2000-01-01T01:00:00Z",
    "currency": "USD",
    "download_uri": "https://url...",
    "invoice_line_items": [

    ],
    "method": "paypal",
    "payment_line_items": [

    ],
    "payment_reversed_at": "2000-01-01T01:00:00Z",
    "payment_type": "",
    "site_name": "My Site",
    "type": "invoice",
    "updated_at": "2000-01-01T01:00:00Z"
  }
]

<?xml version="1.0" encoding="UTF-8"?>
<account-line-items type="array">
  <account-line-item>
    <id type="integer">1</id>
    <amount></amount>
    <balance></balance>
    <created_at>2000-01-01T01:00:00Z</created_at>
    <currency>USD</currency>
    <download_uri>https://url...</download_uri>
    <invoice_line_items type="array"/>
    <method>paypal</method>
    <payment_line_items type="array"/>
    <payment_reversed_at>2000-01-01T01:00:00Z</payment_reversed_at>
    <payment_type></payment_type>
    <site_name>My Site</site_name>
    <type>invoice</type>
    <updated_at>2000-01-01T01:00:00Z</updated_at>
  </account-line-item>
</account-line-items>

HTTPS Request

GET /payments

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Deprecated: If set to `count` returns a count of matching records rather than the records themselves.

Show Invoice

Example Request

curl https://app.files.com/api/rest/v1/invoices/{id}.json \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/invoices/{id}.xml \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::Invoice.find(id)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\Invoice::find($id);

Example Response

{
  "id": 1,
  "amount": "",
  "balance": "",
  "created_at": "2000-01-01T01:00:00Z",
  "currency": "USD",
  "download_uri": "https://url...",
  "invoice_line_items": [

  ],
  "method": "paypal",
  "payment_line_items": [

  ],
  "payment_reversed_at": "2000-01-01T01:00:00Z",
  "payment_type": "",
  "site_name": "My Site",
  "type": "invoice",
  "updated_at": "2000-01-01T01:00:00Z"
}

<?xml version="1.0" encoding="UTF-8"?>
<account-line-item>
  <id type="integer">1</id>
  <amount></amount>
  <balance></balance>
  <created_at>2000-01-01T01:00:00Z</created_at>
  <currency>USD</currency>
  <download_uri>https://url...</download_uri>
  <invoice_line_items type="array"/>
  <method>paypal</method>
  <payment_line_items type="array"/>
  <payment_reversed_at>2000-01-01T01:00:00Z</payment_reversed_at>
  <payment_type></payment_type>
  <site_name>My Site</site_name>
  <type>invoice</type>
  <updated_at>2000-01-01T01:00:00Z</updated_at>
</account-line-item>

HTTPS Request

GET /invoices/{id}

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
id int64 Required	Invoice ID.

Show Payment

Example Request

curl https://app.files.com/api/rest/v1/payments/{id}.json \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/payments/{id}.xml \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::Payment.find(id)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\Payment::find($id);

Example Response

{
  "id": 1,
  "amount": "",
  "balance": "",
  "created_at": "2000-01-01T01:00:00Z",
  "currency": "USD",
  "download_uri": "https://url...",
  "invoice_line_items": [

  ],
  "method": "paypal",
  "payment_line_items": [

  ],
  "payment_reversed_at": "2000-01-01T01:00:00Z",
  "payment_type": "",
  "site_name": "My Site",
  "type": "invoice",
  "updated_at": "2000-01-01T01:00:00Z"
}

<?xml version="1.0" encoding="UTF-8"?>
<account-line-item>
  <id type="integer">1</id>
  <amount></amount>
  <balance></balance>
  <created_at>2000-01-01T01:00:00Z</created_at>
  <currency>USD</currency>
  <download_uri>https://url...</download_uri>
  <invoice_line_items type="array"/>
  <method>paypal</method>
  <payment_line_items type="array"/>
  <payment_reversed_at>2000-01-01T01:00:00Z</payment_reversed_at>
  <payment_type></payment_type>
  <site_name>My Site</site_name>
  <type>invoice</type>
  <updated_at>2000-01-01T01:00:00Z</updated_at>
</account-line-item>

HTTPS Request

GET /payments/{id}

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
id int64 Required	Payment ID.

Actions

All File and Login actions on Files.com are recorded and can be queried via our History API.

The Action object

Example Action Object

{
  "id": 1,
  "path": "path",
  "when": "2000-01-01T01:00:00Z",
  "destination": "/to_path",
  "display": "Actual text of the action here.",
  "ip": "192.283.128.182",
  "source": "/from_path",
  "targets": [

  ],
  "user_id": 1,
  "username": "user",
  "action": "create",
  "failure_type": "none",
  "interface": "web"
}

<?xml version="1.0" encoding="UTF-8"?>
<action>
  <id type="integer">1</id>
  <path>path</path>
  <when>2000-01-01T01:00:00Z</when>
  <destination>/to_path</destination>
  <display>Actual text of the action here.</display>
  <ip>192.283.128.182</ip>
  <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>
</action>

Attribute	Description
id int64	Action ID
path string	Path This must be slash-delimited, but it must neither start nor end with a slash. Maximum of 5000 characters.
when date-time	Action occurrence date/time
destination string	The destination path for this action, if applicable
display string	Friendly displayed output
ip string	IP Address that performed this action
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 Possible values: `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`, `api_key_destroy`
failure_type string	Failure type. If action was a user login or session failure, why did it fail? Possible values: `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`, `expired_access`, `desktop_ip_mismatch`, `desktop_api_key_not_used_quickly_enough`, `disabled`
interface string	Interface on which this action occurred. Possible values: `web`, `ftp`, `robot`, `jsapi`, `webdesktopapi`, `sftp`, `dav`, `desktop`, `restapi`, `scim`

List history for specific file

Example Request

curl "https://app.files.com/api/rest/v1/history/files(/*path).json?display=Actual text of the action here.&page=1&per_page=1&action=create" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/history/files(/*path).xml?display=Actual text of the action here.&page=1&per_page=1&action=create" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::History.list_for_file(path, 
  display: "Actual text of the action here.", 
  page: 1, 
  per_page: 1, 
  action: "create"
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\History::listForFile($path, array(
  'display' => "Actual text of the action here.", 
  'page' => 1, 
  'per_page' => 1, 
  'action' => "create"
));

Example Response

[
  {
    "id": 1,
    "path": "path",
    "when": "2000-01-01T01:00:00Z",
    "destination": "/to_path",
    "display": "Actual text of the action here.",
    "ip": "192.283.128.182",
    "source": "/from_path",
    "targets": [

    ],
    "user_id": 1,
    "username": "user",
    "action": "create",
    "failure_type": "none",
    "interface": "web"
  }
]

<?xml version="1.0" encoding="UTF-8"?>
<actions type="array">
  <action>
    <id type="integer">1</id>
    <path>path</path>
    <when>2000-01-01T01:00:00Z</when>
    <destination>/to_path</destination>
    <display>Actual text of the action here.</display>
    <ip>192.283.128.182</ip>
    <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>
  </action>
</actions>

HTTPS Request

GET /history/files(/*path)

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
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`.
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Deprecated: If set to `count` returns a count of matching records rather than the records themselves.
path string Required	Path to operate on.

List history for specific folder

Example Request

curl "https://app.files.com/api/rest/v1/history/folders(/*path).json?display=Actual text of the action here.&page=1&per_page=1&action=create" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/history/folders(/*path).xml?display=Actual text of the action here.&page=1&per_page=1&action=create" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::History.list_for_folder(path, 
  display: "Actual text of the action here.", 
  page: 1, 
  per_page: 1, 
  action: "create"
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\History::listForFolder($path, array(
  'display' => "Actual text of the action here.", 
  'page' => 1, 
  'per_page' => 1, 
  'action' => "create"
));

Example Response

[
  {
    "id": 1,
    "path": "path",
    "when": "2000-01-01T01:00:00Z",
    "destination": "/to_path",
    "display": "Actual text of the action here.",
    "ip": "192.283.128.182",
    "source": "/from_path",
    "targets": [

    ],
    "user_id": 1,
    "username": "user",
    "action": "create",
    "failure_type": "none",
    "interface": "web"
  }
]

<?xml version="1.0" encoding="UTF-8"?>
<actions type="array">
  <action>
    <id type="integer">1</id>
    <path>path</path>
    <when>2000-01-01T01:00:00Z</when>
    <destination>/to_path</destination>
    <display>Actual text of the action here.</display>
    <ip>192.283.128.182</ip>
    <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>
  </action>
</actions>

HTTPS Request

GET /history/folders(/*path)

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
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`.
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Deprecated: If set to `count` returns a count of matching records rather than the records themselves.
path string Required	Path to operate on.

List history for specific user

Example Request

curl "https://app.files.com/api/rest/v1/history/users/{user_id}.json?display=Actual text of the action here.&page=1&per_page=1&action=create" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/history/users/{user_id}.xml?display=Actual text of the action here.&page=1&per_page=1&action=create" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::History.list_for_user(user_id, 
  display: "Actual text of the action here.", 
  page: 1, 
  per_page: 1, 
  action: "create"
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\History::listForUser($user_id, array(
  'display' => "Actual text of the action here.", 
  'page' => 1, 
  'per_page' => 1, 
  'action' => "create"
));

Example Response

[
  {
    "id": 1,
    "path": "path",
    "when": "2000-01-01T01:00:00Z",
    "destination": "/to_path",
    "display": "Actual text of the action here.",
    "ip": "192.283.128.182",
    "source": "/from_path",
    "targets": [

    ],
    "user_id": 1,
    "username": "user",
    "action": "create",
    "failure_type": "none",
    "interface": "web"
  }
]

<?xml version="1.0" encoding="UTF-8"?>
<actions type="array">
  <action>
    <id type="integer">1</id>
    <path>path</path>
    <when>2000-01-01T01:00:00Z</when>
    <destination>/to_path</destination>
    <display>Actual text of the action here.</display>
    <ip>192.283.128.182</ip>
    <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>
  </action>
</actions>

HTTPS Request

GET /history/users/{user_id}

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Request Parameters

Parameter	Description
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`.
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Deprecated: If set to `count` returns a count of matching records rather than the records themselves.
user_id int64 Required	User ID.

Example Request

curl "https://app.files.com/api/rest/v1/history/login.json?display=Actual text of the action here.&page=1&per_page=1&action=create" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/history/login.xml?display=Actual text of the action here.&page=1&per_page=1&action=create" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::History.list_logins(
  display: "Actual text of the action here.", 
  page: 1, 
  per_page: 1, 
  action: "create"
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\History::listLogins(array(
  'display' => "Actual text of the action here.", 
  'page' => 1, 
  'per_page' => 1, 
  'action' => "create"
));

Example Response

[
  {
    "id": 1,
    "path": "path",
    "when": "2000-01-01T01:00:00Z",
    "destination": "/to_path",
    "display": "Actual text of the action here.",
    "ip": "192.283.128.182",
    "source": "/from_path",
    "targets": [

    ],
    "user_id": 1,
    "username": "user",
    "action": "create",
    "failure_type": "none",
    "interface": "web"
  }
]

<?xml version="1.0" encoding="UTF-8"?>
<actions type="array">
  <action>
    <id type="integer">1</id>
    <path>path</path>
    <when>2000-01-01T01:00:00Z</when>
    <destination>/to_path</destination>
    <display>Actual text of the action here.</display>
    <ip>192.283.128.182</ip>
    <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>
  </action>
</actions>

HTTPS Request

GET /history/login

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Request Parameters

Parameter	Description
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`.
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Deprecated: If set to `count` returns a count of matching records rather than the records themselves.

List site full action history

Example Request

curl "https://app.files.com/api/rest/v1/history.json?display=Actual text of the action here.&page=1&per_page=1&action=create" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/history.xml?display=Actual text of the action here.&page=1&per_page=1&action=create" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::History.list(
  display: "Actual text of the action here.", 
  page: 1, 
  per_page: 1, 
  action: "create"
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\History::list(array(
  'display' => "Actual text of the action here.", 
  'page' => 1, 
  'per_page' => 1, 
  'action' => "create"
));

Example Response

[
  {
    "id": 1,
    "path": "path",
    "when": "2000-01-01T01:00:00Z",
    "destination": "/to_path",
    "display": "Actual text of the action here.",
    "ip": "192.283.128.182",
    "source": "/from_path",
    "targets": [

    ],
    "user_id": 1,
    "username": "user",
    "action": "create",
    "failure_type": "none",
    "interface": "web"
  }
]

<?xml version="1.0" encoding="UTF-8"?>
<actions type="array">
  <action>
    <id type="integer">1</id>
    <path>path</path>
    <when>2000-01-01T01:00:00Z</when>
    <destination>/to_path</destination>
    <display>Actual text of the action here.</display>
    <ip>192.283.128.182</ip>
    <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>
  </action>
</actions>

HTTPS Request

GET /history

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Request Parameters

Parameter	Description
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`.
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Deprecated: If set to `count` returns a count of matching records rather than the records themselves.

Api Keys

API Keys allow programmatic access to your Site. API keys confer all the permissions of the user who owns them. If an API key is created without a user owner, it is considered a site-wide API key, which has full permissions to do anything on the Site.

The ApiKey object

Example ApiKey Object

{
  "id": 1,
  "descriptive_label": "Site-wide API key for https://site.files.com/ (key ID #1)",
  "created_at": "2000-01-01T01:00:00Z",
  "expires_at": "2000-01-01T01:00:00Z",
  "key": "[key]",
  "last_use_at": "2000-01-01T01:00:00Z",
  "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>
  <descriptive_label>Site-wide API key for https://site.files.com/ (key ID #1)</descriptive_label>
  <created_at>2000-01-01T01:00:00Z</created_at>
  <expires_at>2000-01-01T01:00:00Z</expires_at>
  <key>[key]</key>
  <last_use_at>2000-01-01T01:00:00Z</last_use_at>
  <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
descriptive_label string	Unique label that describes this API key. Useful for external systems where you may have API keys from multiple accounts and want a human-readable label for each key.
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
last_use_at date-time	API Key last used - note this value is only updated once per 3 hour period, so the 'actual' time of last use may be up to 3 hours later than this timestamp.
name string	Internal name for the API Key. For your use.
permission_set string	Permissions for this API Key. 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. Possible values: `none`, `full`, `desktop_app`, `sync_app`
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.

List Api Keys

Example Request

curl "https://app.files.com/api/rest/v1/api_keys.json?user_id=1&page=1&per_page=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/api_keys.xml?user_id=1&page=1&per_page=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::ApiKey.list(
  user_id: 1, 
  page: 1, 
  per_page: 1
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\ApiKey::list(array(
  'user_id' => 1, 
  'page' => 1, 
  'per_page' => 1
));

Example Response

[
  {
    "id": 1,
    "descriptive_label": "Site-wide API key for https://site.files.com/ (key ID #1)",
    "created_at": "2000-01-01T01:00:00Z",
    "expires_at": "2000-01-01T01:00:00Z",
    "key": "[key]",
    "last_use_at": "2000-01-01T01:00:00Z",
    "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>
    <descriptive_label>Site-wide API key for https://site.files.com/ (key ID #1)</descriptive_label>
    <created_at>2000-01-01T01:00:00Z</created_at>
    <expires_at>2000-01-01T01:00:00Z</expires_at>
    <key>[key]</key>
    <last_use_at>2000-01-01T01:00:00Z</last_use_at>
    <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 /api_keys

Authentication Required

Not available to user API keys or sessions from users that are marked as Shared/Bot users.

Request Parameters

Parameter	Description
user_id int64	User ID. Provide a value of `0` to operate the current session's user.
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Deprecated: If set to `count` returns a count of matching records rather than the records themselves.

Show information about 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 \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/api_key.xml \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::ApiKey.find_current

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\ApiKey::findCurrent();

Example Response

{
  "id": 1,
  "descriptive_label": "Site-wide API key for https://site.files.com/ (key ID #1)",
  "created_at": "2000-01-01T01:00:00Z",
  "expires_at": "2000-01-01T01:00:00Z",
  "key": "[key]",
  "last_use_at": "2000-01-01T01:00:00Z",
  "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>
  <descriptive_label>Site-wide API key for https://site.files.com/ (key ID #1)</descriptive_label>
  <created_at>2000-01-01T01:00:00Z</created_at>
  <expires_at>2000-01-01T01:00:00Z</expires_at>
  <key>[key]</key>
  <last_use_at>2000-01-01T01:00:00Z</last_use_at>
  <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_key

Authentication Required

Available to all authenticated keys or sessions.

Show Api Key

Example Request

curl https://app.files.com/api/rest/v1/api_keys/{id}.json \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/api_keys/{id}.xml \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::ApiKey.find(id)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\ApiKey::find($id);

Example Response

{
  "id": 1,
  "descriptive_label": "Site-wide API key for https://site.files.com/ (key ID #1)",
  "created_at": "2000-01-01T01:00:00Z",
  "expires_at": "2000-01-01T01:00:00Z",
  "key": "[key]",
  "last_use_at": "2000-01-01T01:00:00Z",
  "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>
  <descriptive_label>Site-wide API key for https://site.files.com/ (key ID #1)</descriptive_label>
  <created_at>2000-01-01T01:00:00Z</created_at>
  <expires_at>2000-01-01T01:00:00Z</expires_at>
  <key>[key]</key>
  <last_use_at>2000-01-01T01:00:00Z</last_use_at>
  <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}

Authentication Required

Not available to user API keys or sessions from users that are marked as Shared/Bot users.

Request Parameters

Parameter	Description
id int64 Required	Api Key ID.

Create Api Key

Example Request

curl https://app.files.com/api/rest/v1/api_keys.json \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"user_id":1,"name":"My Key","permission_set":"full","expires_at":"2000-01-01T01:00:00Z"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/api_keys.xml \
  -X POST \
  -H 'Content-Type: application/xml' \
  -d '<api-key>
       <user_id type="integer">1</user_id>
       <name>My Key</name>
       <permission_set>full</permission_set>
       <expires_at>2000-01-01T01:00:00Z</expires_at>
     </api-key>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::ApiKey.create(
  user_id: 1, 
  name: "My Key", 
  permission_set: "full", 
  expires_at: "2000-01-01T01:00:00Z"
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\ApiKey::create(array(
  'user_id' => 1, 
  'name' => "My Key", 
  'permission_set' => "full", 
  'expires_at' => "2000-01-01T01:00:00Z"
));

Example Response

{
  "id": 1,
  "descriptive_label": "Site-wide API key for https://site.files.com/ (key ID #1)",
  "created_at": "2000-01-01T01:00:00Z",
  "expires_at": "2000-01-01T01:00:00Z",
  "key": "[key]",
  "last_use_at": "2000-01-01T01:00:00Z",
  "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>
  <descriptive_label>Site-wide API key for https://site.files.com/ (key ID #1)</descriptive_label>
  <created_at>2000-01-01T01:00:00Z</created_at>
  <expires_at>2000-01-01T01:00:00Z</expires_at>
  <key>[key]</key>
  <last_use_at>2000-01-01T01:00:00Z</last_use_at>
  <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 /api_keys

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
user_id int64	User ID. Provide a value of `0` to operate the current session's user.
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-01T01:00:00Z"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

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>2000-01-01T01:00:00Z</expires_at>
     </api-key>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::ApiKey.update_current(
  name: "My Key", 
  permission_set: "full", 
  expires_at: "2000-01-01T01:00:00Z"
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\ApiKey::updateCurrent(array(
  'name' => "My Key", 
  'permission_set' => "full", 
  'expires_at' => "2000-01-01T01:00:00Z"
));

Example Response

{
  "id": 1,
  "descriptive_label": "Site-wide API key for https://site.files.com/ (key ID #1)",
  "created_at": "2000-01-01T01:00:00Z",
  "expires_at": "2000-01-01T01:00:00Z",
  "key": "[key]",
  "last_use_at": "2000-01-01T01:00:00Z",
  "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>
  <descriptive_label>Site-wide API key for https://site.files.com/ (key ID #1)</descriptive_label>
  <created_at>2000-01-01T01:00:00Z</created_at>
  <expires_at>2000-01-01T01:00:00Z</expires_at>
  <key>[key]</key>
  <last_use_at>2000-01-01T01:00:00Z</last_use_at>
  <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

Authentication Required

Available to all authenticated keys or sessions.

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.

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-01T01:00:00Z"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

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>2000-01-01T01:00:00Z</expires_at>
     </api-key>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

api_key = Files::ApiKey.find(id)
api_key.update(
  name: "My Key",
  permission_set: "full",
  expires_at: "2000-01-01T01:00:00Z"
)

\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-01T01:00:00Z"
));

Example Response

{
  "id": 1,
  "descriptive_label": "Site-wide API key for https://site.files.com/ (key ID #1)",
  "created_at": "2000-01-01T01:00:00Z",
  "expires_at": "2000-01-01T01:00:00Z",
  "key": "[key]",
  "last_use_at": "2000-01-01T01:00:00Z",
  "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>
  <descriptive_label>Site-wide API key for https://site.files.com/ (key ID #1)</descriptive_label>
  <created_at>2000-01-01T01:00:00Z</created_at>
  <expires_at>2000-01-01T01:00:00Z</expires_at>
  <key>[key]</key>
  <last_use_at>2000-01-01T01:00:00Z</last_use_at>
  <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}

Authentication Required

Not available to user API keys or sessions from users that are marked as Shared/Bot users.

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.

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 \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/api_key.xml \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::ApiKey.delete_current

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\ApiKey::deleteCurrent();

Example Response

No response.

No response.

HTTPS Request

DELETE /api_key

Authentication Required

Available to all authenticated keys or sessions.

Delete Api Key

Example Request

curl https://app.files.com/api/rest/v1/api_keys/{id}.json \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/api_keys/{id}.xml \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

api_key = Files::ApiKey.find(id)
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}

Authentication Required

Not available to user API keys or sessions from users that are marked as Shared/Bot users.

Request Parameters

Parameter	Description
id int64 Required	Api Key ID.

As2 Keys

AS2 Public keys are used by Users who want to connect an AS2 (Applicability Statement v2) compatible client.

The As2Key object

Example As2Key Object

{
  "id": 1,
  "as2_partnership_name": "Test",
  "created_at": "2000-01-01T01:00:00Z",
  "fingerprint": "cf:cb:d3:26:52:6c:55:88:83:17:13:cf:e7:70:eb:1b:32:37:38:c0"
}

<?xml version="1.0" encoding="UTF-8"?>
<as2-key>
  <id type="integer">1</id>
  <as2_partnership_name>Test</as2_partnership_name>
  <created_at>2000-01-01T01:00:00Z</created_at>
  <fingerprint>cf:cb:d3:26:52:6c:55:88:83:17:13:cf:e7:70:eb:1b:32:37:38:c0</fingerprint>
</as2-key>

Attribute	Description
id int64	AS2 Key ID
as2_partnership_name string	AS2 Partnership Name
created_at date-time	AS2 Key created at date/time
fingerprint string	Public key fingerprint
user_id int64	User ID. Provide a value of `0` to operate the current session's user.
public_key string	Actual contents of Public key.

List As2 Keys

Example Request

curl "https://app.files.com/api/rest/v1/as2_keys.json?user_id=1&page=1&per_page=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/as2_keys.xml?user_id=1&page=1&per_page=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::As2Key.list(
  user_id: 1, 
  page: 1, 
  per_page: 1
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\As2Key::list(array(
  'user_id' => 1, 
  'page' => 1, 
  'per_page' => 1
));

Example Response

[
  {
    "id": 1,
    "as2_partnership_name": "Test",
    "created_at": "2000-01-01T01:00:00Z",
    "fingerprint": "cf:cb:d3:26:52:6c:55:88:83:17:13:cf:e7:70:eb:1b:32:37:38:c0"
  }
]

<?xml version="1.0" encoding="UTF-8"?>
<as2-keys type="array">
  <as2-key>
    <id type="integer">1</id>
    <as2_partnership_name>Test</as2_partnership_name>
    <created_at>2000-01-01T01:00:00Z</created_at>
    <fingerprint>cf:cb:d3:26:52:6c:55:88:83:17:13:cf:e7:70:eb:1b:32:37:38:c0</fingerprint>
  </as2-key>
</as2-keys>

HTTPS Request

GET /as2_keys

Authentication Required

Not available to user API keys or sessions from users that are marked as Shared/Bot users.

Request Parameters

Parameter	Description
user_id int64	User ID. Provide a value of `0` to operate the current session's user.
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Deprecated: If set to `count` returns a count of matching records rather than the records themselves.

Show As2 Key

Example Request

curl https://app.files.com/api/rest/v1/as2_keys/{id}.json \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/as2_keys/{id}.xml \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::As2Key.find(id)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\As2Key::find($id);

Example Response

{
  "id": 1,
  "as2_partnership_name": "Test",
  "created_at": "2000-01-01T01:00:00Z",
  "fingerprint": "cf:cb:d3:26:52:6c:55:88:83:17:13:cf:e7:70:eb:1b:32:37:38:c0"
}

<?xml version="1.0" encoding="UTF-8"?>
<as2-key>
  <id type="integer">1</id>
  <as2_partnership_name>Test</as2_partnership_name>
  <created_at>2000-01-01T01:00:00Z</created_at>
  <fingerprint>cf:cb:d3:26:52:6c:55:88:83:17:13:cf:e7:70:eb:1b:32:37:38:c0</fingerprint>
</as2-key>

HTTPS Request

GET /as2_keys/{id}

Authentication Required

Not available to user API keys or sessions from users that are marked as Shared/Bot users.

Request Parameters

Parameter	Description
id int64 Required	As2 Key ID.

Create As2 Key

Example Request

curl https://app.files.com/api/rest/v1/as2_keys.json \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"user_id":1,"as2_partnership_name":"Test","public_key":"public_key"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/as2_keys.xml \
  -X POST \
  -H 'Content-Type: application/xml' \
  -d '<as2-key>
       <user_id type="integer">1</user_id>
       <as2_partnership_name>Test</as2_partnership_name>
       <public_key>public_key</public_key>
     </as2-key>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::As2Key.create(
  user_id: 1, 
  as2_partnership_name: "Test", 
  public_key: "public_key"
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\As2Key::create(array(
  'user_id' => 1, 
  'as2_partnership_name' => "Test", 
  'public_key' => "public_key"
));

Example Response

{
  "id": 1,
  "as2_partnership_name": "Test",
  "created_at": "2000-01-01T01:00:00Z",
  "fingerprint": "cf:cb:d3:26:52:6c:55:88:83:17:13:cf:e7:70:eb:1b:32:37:38:c0"
}

<?xml version="1.0" encoding="UTF-8"?>
<as2-key>
  <id type="integer">1</id>
  <as2_partnership_name>Test</as2_partnership_name>
  <created_at>2000-01-01T01:00:00Z</created_at>
  <fingerprint>cf:cb:d3:26:52:6c:55:88:83:17:13:cf:e7:70:eb:1b:32:37:38:c0</fingerprint>
</as2-key>

HTTPS Request

POST /as2_keys

Authentication Required

Not available to user API keys or sessions from users that are marked as Shared/Bot users.

Request Parameters

Parameter	Description
user_id int64	User ID. Provide a value of `0` to operate the current session's user.
as2_partnership_name string Required	AS2 Partnership Name
public_key string Required	Actual contents of Public key.

Update As2 Key

Example Request

curl https://app.files.com/api/rest/v1/as2_keys/{id}.json \
  -X PATCH \
  -H 'Content-Type: application/json' \
  -d '{"as2_partnership_name":"Test"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/as2_keys/{id}.xml \
  -X PATCH \
  -H 'Content-Type: application/xml' \
  -d '<as2-key>
       <as2_partnership_name>Test</as2_partnership_name>
     </as2-key>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

as2_key = Files::As2Key.find(id)
as2_key.update(
  as2_partnership_name: "Test"
)

\Files\Files::setApiKey('YOUR_API_KEY');

$as2_key = \Files\As2Key->find(1);
$as2_key->update(array(
  'as2_partnership_name' => "Test"
));

Example Response

{
  "id": 1,
  "as2_partnership_name": "Test",
  "created_at": "2000-01-01T01:00:00Z",
  "fingerprint": "cf:cb:d3:26:52:6c:55:88:83:17:13:cf:e7:70:eb:1b:32:37:38:c0"
}

<?xml version="1.0" encoding="UTF-8"?>
<as2-key>
  <id type="integer">1</id>
  <as2_partnership_name>Test</as2_partnership_name>
  <created_at>2000-01-01T01:00:00Z</created_at>
  <fingerprint>cf:cb:d3:26:52:6c:55:88:83:17:13:cf:e7:70:eb:1b:32:37:38:c0</fingerprint>
</as2-key>

HTTPS Request

PATCH /as2_keys/{id}

Authentication Required

Not available to user API keys or sessions from users that are marked as Shared/Bot users.

Request Parameters

Parameter	Description
id int64 Required	As2 Key ID.
as2_partnership_name string Required	AS2 Partnership Name

Delete As2 Key

Example Request

curl https://app.files.com/api/rest/v1/as2_keys/{id}.json \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/as2_keys/{id}.xml \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

as2_key = Files::As2Key.find(id)
as2_key.delete

\Files\Files::setApiKey('YOUR_API_KEY');

$as2_key = \Files\As2Key->find(1);
$as2_key->delete();

Example Response

No response.

No response.

HTTPS Request

DELETE /as2_keys/{id}

Authentication Required

Not available to user API keys or sessions from users that are marked as Shared/Bot users.

Request Parameters

Parameter	Description
id int64 Required	As2 Key ID.

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:

Interval: quarter_end
Path: /AccountingAndTax/SalesTax/State/*/
Destination: %Y/Quarter-ending-%m-%d

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:

Path: /AccountingAndTax/SalesTax/State/*/*/*/
Destination: SalesByState-%p3-%p2-%p1
Group IDs: 123 (representing the Bookkeepers group)

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:

Path: /AccountingAndTax/SalesTax/State/*/*/%/
Source: SalesByState-%p3-%p2-%p1
Destination: StateSalesTaxReturn-Unsigned-%p3-%p2-%p1
Group IDs: 124 (representing the Tax Accountants group) Group: Tax Accountants

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:

Path: /AccountingAndTax/**/
Source: *-Unsigned-*
Destination Replace From: -Unsigned-
Destination Replace To: -Signed-
Group IDs: 125 (representing the CFO group)

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:

/Accounts Payable/Contractors/[contractor]/New/
/Accounts Payable/Contractors/[contractor]/Paid/

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:

Path: /AccountsPayable/Contractors/*/New/
Source: *
Destination: ../Paid/
Group IDs: 126 (representing the Accounts Payable group)

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 Possible values: `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?page=1&per_page=1&automation=create_folder" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/automations.xml?page=1&per_page=1&automation=create_folder" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::Automation.list(
  page: 1, 
  per_page: 1, 
  automation: "create_folder"
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\Automation::list(array(
  'page' => 1, 
  'per_page' => 1, 
  '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

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Request Parameters

Parameter	Description
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Deprecated: If set to `count` returns a count of matching records rather than the records themselves.
automation string	Type of automation to filter by.

Show Automation

Example Request

curl https://app.files.com/api/rest/v1/automations/{id}.json \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/automations/{id}.xml \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

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}

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

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"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

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>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

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

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

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"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

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>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

automation = Files::Automation.find(id)
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}

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

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 \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/automations/{id}.xml \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

automation = Files::Automation.find(id)
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}

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Request Parameters

Parameter	Description
id int64 Required	Automation ID.

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

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.

Behavior Details
Behavior type	`webhook`
Visible to non-admins?	No
Requires attachment?	No
Effect on Child Folders	In effect. Behaviors can also be set on child, to be also in 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

Behavior Details
Behavior type	`file_expiration`
Visible to non-admins?	Yes
Requires attachment?	No
Effect on Child Folders	In effect. Can be overridden by adding a behavior to the child.

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.

Behavior Details
Behavior type	`auto_encrypt`
Visible to non-admins?	Yes
Requires attachment?	No
Effect on Child Folders	In effect. Can be overridden by adding a behavior to the child.

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.

Behavior Details
Behavior type	`lock_subfolders`
Visible to non-admins?	Yes
Requires attachment?	No
Effect on Child Folders	In effect, cannot 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

Behavior Details
Behavior type	`storage_region`
Visible to non-admins?	Yes
Requires attachment?	No
Effect on Child Folders	In effect. Can be overridden by adding a behavior to the child.

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?

Behavior Details
Behavior type	`serve_publicly`
Visible to non-admins?	Yes
Requires attachment?	No
Effect on Child Folders	In effect. Behaviors can also be set on child, to be also in effect.

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.

Behavior Details
Behavior type	`create_user_folders`
Visible to non-admins?	No
Requires attachment?	No
Effect on Child Folders	In effect. Behaviors can also be set on child, to be also in effect.

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

Behavior Details
Behavior type	`remote_server_sync`
Visible to non-admins?	No
Requires attachment?	No
Effect on Child Folders	In effect. Behaviors can also be set on child, to be also in effect.

Inbox

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

Example Value

{
  "key": "application-forms",
  "title": "Submit Your Job Applications Here",
  "description": "Thanks for coming to the Files.com Job Application Page",
  "show_on_login_page": true,
  "require_registration": true,
  "help_text": "If you have trouble here, please contact your recruiter."
}

Value Hash Parameters
`key`	URL key used for the inbox.
`dont_separate_submissions_by_folder`	Do not create subfolders for files uploaded to this inbox. Note: there are subtle security pitfalls with allowing anonymous uploads from multiple users to live in the same folder. We strongly discourage use of this option unless absolutely required.
`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.
`require_registration`	Show a registration page that captures the uploader's name and email address?
`password`	Password to authenticate to inbox.

Behavior Details
Behavior type	`inbox`
Visible to non-admins?	Yes
Requires attachment?	No
Effect on Child Folders	In effect. Behaviors can also be set on child, to be also in effect.

Append Timestamp

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.

Example Value

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

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.

Behavior Details
Behavior type	`append_timestamp`
Visible to non-admins?	Yes
Requires attachment?	No
Effect on Child Folders	In effect, cannot be overridden.

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.

Behavior Details
Behavior type	`limit_file_extensions`
Visible to non-admins?	Yes
Requires attachment?	No
Effect on Child Folders	In effect, cannot 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.

Behavior Details
Behavior type	`limit_file_regex`
Visible to non-admins?	Yes
Requires attachment?	No
Effect on Child Folders	In effect, cannot be overridden.

Amazon Sns

Sends a notification via Amazon SNS whenever certain actions occur on a folder.

Example Value

{
  "arns": [
    "ARN..."
  ],
  "triggers": [
    "create",
    "read",
    "update",
    "destroy",
    "move",
    "copy"
  ],
  "aws_credentials": {
    "access_key_id": "ACCESS_KEY_ID",
    "region": "us-east-1",
    "secret_access_key": "SECRET_ACCESS_KEY"
  }
}

Value Hash Parameters
`arns`	Array of ARNs to send the notifications to.
`triggers`	Leave blank to send an SNS notification 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`.
`aws_credentials`	AWS IAM Credentials to use for sending SNS requests. Must include `access_key_id`, and `secret_access_key`.

Behavior Details
Behavior type	`amazon_sns`
Visible to non-admins?	No
Requires attachment?	No
Effect on Child Folders	In effect. Behaviors can also be set on child, to be also in effect.

Watermark

Adds a watermark to any image preview generated for an image in this folder.

{
  "gravity": "SouthWest",
  "max_height_or_width": 20,
  "transparency": 25
}

Value Hash Parameters
`gravity`	Where to locate the watermark? Valid values: `Center`, `East`, `NorthEast`, `North`, `NorthWest`, `SouthEast`, `South`, `SouthWest`, `West`
`max_height_or_width`	Max width/height as percent of image preview.
`transparency`	Percentage applied to the watermark.

Behavior Details
Behavior type	`watermark`
Visible to non-admins?	Yes
Requires attachment?	Yes
Effect on Child Folders	In effect, cannot be overridden.

The Behavior object

Example Behavior Object

{
  "id": 1,
  "path": "",
  "attachment_url": "",
  "behavior": "webhook",
  "value": {
    "method": "GET"
  }
}

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

Attribute	Description
id int64	Folder behavior ID
path string	Folder path This must be slash-delimited, but it must neither start nor end with a slash. Maximum of 5000 characters.
attachment_url string	URL for attached file
behavior string	Behavior type.
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.
attachment_file file	Certain behaviors may require a file, for instance, the "watermark" behavior requires a watermark image

List Behaviors

Example Request

curl "https://app.files.com/api/rest/v1/behaviors.json?page=1&per_page=1&behavior=webhook" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/behaviors.xml?page=1&per_page=1&behavior=webhook" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::Behavior.list(
  page: 1, 
  per_page: 1, 
  behavior: "webhook"
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\Behavior::list(array(
  'page' => 1, 
  'per_page' => 1, 
  'behavior' => "webhook"
));

Example Response

[
  {
    "id": 1,
    "path": "",
    "attachment_url": "",
    "behavior": "webhook",
    "value": {
      "method": "GET"
    }
  }
]

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

HTTPS Request

GET /behaviors

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Deprecated: If set to `count` returns a count of matching records rather than the records themselves.
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}?page=1&per_page=1&behavior=webhook" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/behaviors/folders/{path}?page=1&per_page=1&behavior=webhook" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::Behavior.list_for(path, 
  page: 1, 
  per_page: 1, 
  behavior: "webhook"
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\Behavior::listFor($path, array(
  'page' => 1, 
  'per_page' => 1, 
  'behavior' => "webhook"
));

Example Response

[
  {
    "id": 1,
    "path": "",
    "attachment_url": "",
    "behavior": "webhook",
    "value": {
      "method": "GET"
    }
  }
]

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

HTTPS Request

GET /behaviors/folders/?*path

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Deprecated: If set to `count` returns a count of matching records rather than the records themselves.
path string Required	Path to operate on.
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 \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/behaviors/{id}.xml \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::Behavior.find(id)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\Behavior::find($id);

Example Response

{
  "id": 1,
  "path": "",
  "attachment_url": "",
  "behavior": "webhook",
  "value": {
    "method": "GET"
  }
}

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

HTTPS Request

GET /behaviors/{id}

Authentication Required

Available to all authenticated keys or sessions.

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"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

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>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

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,
  "path": "",
  "attachment_url": "",
  "behavior": "webhook",
  "value": {
    "method": "GET"
  }
}

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

HTTPS Request

POST /behaviors

Authentication Required

Available to all authenticated keys or sessions.

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.
attachment_file file	Certain behaviors may require a file, for instance, the "watermark" behavior requires a watermark image
path string Required	Folder behaviors path.
behavior string Required	Behavior type.

Test webhook

Example Request

curl https://app.files.com/api/rest/v1/behaviors/webhook/test.json \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://www.site.com/...","method":"GET","encoding":"RAW"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/behaviors/webhook/test.xml \
  -X POST \
  -H 'Content-Type: application/xml' \
  -d '<behavior>
       <url>https://www.site.com/...</url>
       <method>GET</method>
       <encoding>RAW</encoding>
     </behavior>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::Behavior.webhook_test(
  url: "https://www.site.com/...", 
  method: "GET", 
  encoding: "RAW"
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\Behavior::webhookTest(array(
  'url' => "https://www.site.com/...", 
  'method' => "GET", 
  'encoding' => "RAW"
));

Example Response

No response.

No response.

HTTPS Request

POST /behaviors/webhook/test

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Folder Admin permissions.

Request Parameters

Parameter	Description
url string Required	URL for testing the webhook.
method string	HTTP method(GET or POST).
encoding string	HTTP encoding method. Can be JSON, XML, or RAW (form data).

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\"}"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

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>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

behavior = Files::Behavior.find(id)
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,
  "path": "",
  "attachment_url": "",
  "behavior": "webhook",
  "value": {
    "method": "GET"
  }
}

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

HTTPS Request

PATCH /behaviors/{id}

Authentication Required

Available to all authenticated keys or sessions.

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.
attachment_file file	Certain behaviors may require a file, for instance, the "watermark" behavior requires a watermark image

Delete Behavior

Example Request

curl https://app.files.com/api/rest/v1/behaviors/{id}.json \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/behaviors/{id}.xml \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

behavior = Files::Behavior.find(id)
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}

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
id int64 Required	Behavior ID.

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

{
  "id": 1,
  "code": "abc123",
  "created_at": "2000-01-01T01:00:00Z",
  "description": "The public description of the bundle.",
  "expires_at": "2000-01-01T01:00:00Z",
  "paths": [

  ],
  "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>
  <id type="integer">1</id>
  <code>abc123</code>
  <created_at>2000-01-01T01:00:00Z</created_at>
  <description>The public description of the bundle.</description>
  <expires_at>2000-01-01T01:00:00Z</expires_at>
  <paths type="array"/>
  <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
id int64	Bundle ID
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
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
password string	Password for this bundle.

List Bundles

Example Request

curl "https://app.files.com/api/rest/v1/bundles.json?user_id=1&page=1&per_page=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/bundles.xml?user_id=1&page=1&per_page=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::Bundle.list(
  user_id: 1, 
  page: 1, 
  per_page: 1
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\Bundle::list(array(
  'user_id' => 1, 
  'page' => 1, 
  'per_page' => 1
));

Example Response

[
  {
    "id": 1,
    "code": "abc123",
    "created_at": "2000-01-01T01:00:00Z",
    "description": "The public description of the bundle.",
    "expires_at": "2000-01-01T01:00:00Z",
    "paths": [

    ],
    "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>
    <id type="integer">1</id>
    <code>abc123</code>
    <created_at>2000-01-01T01:00:00Z</created_at>
    <description>The public description of the bundle.</description>
    <expires_at>2000-01-01T01:00:00Z</expires_at>
    <paths type="array"/>
    <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

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
user_id int64	User ID. Provide a value of `0` to operate the current session's user.
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Deprecated: If set to `count` returns a count of matching records rather than the records themselves.

Show Bundle

Example Request

curl https://app.files.com/api/rest/v1/bundles/{id}.json \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/bundles/{id}.xml \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::Bundle.find(id)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\Bundle::find($id);

Example Response

{
  "id": 1,
  "code": "abc123",
  "created_at": "2000-01-01T01:00:00Z",
  "description": "The public description of the bundle.",
  "expires_at": "2000-01-01T01:00:00Z",
  "paths": [

  ],
  "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>
  <id type="integer">1</id>
  <code>abc123</code>
  <created_at>2000-01-01T01:00:00Z</created_at>
  <description>The public description of the bundle.</description>
  <expires_at>2000-01-01T01:00:00Z</expires_at>
  <paths type="array"/>
  <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}

Authentication Required

Available to all authenticated keys or sessions.

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 '{"user_id":1,"paths":["file.txt"],"password":"Password","expires_at":"2000-01-01T01:00:00Z","description":"Public description","note":"Internal Note","code":"abc123"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/bundles.xml \
  -X POST \
  -H 'Content-Type: application/xml' \
  -d '<bundle>
       <user_id type="integer">1</user_id>
       <paths type="array">
         <path>file.txt</path>
       </paths>
       <password>Password</password>
       <expires_at>2000-01-01T01:00:00Z</expires_at>
       <description>Public description</description>
       <note>Internal Note</note>
       <code>abc123</code>
     </bundle>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::Bundle.create(
  user_id: 1, 
  paths: ["file.txt"], 
  password: "Password", 
  expires_at: "2000-01-01T01:00:00Z", 
  description: "Public description", 
  note: "Internal Note", 
  code: "abc123"
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\Bundle::create(array(
  'user_id' => 1, 
  'paths' => ["file.txt"], 
  'password' => "Password", 
  'expires_at' => "2000-01-01T01:00:00Z", 
  'description' => "Public description", 
  'note' => "Internal Note", 
  'code' => "abc123"
));

Example Response

{
  "id": 1,
  "code": "abc123",
  "created_at": "2000-01-01T01:00:00Z",
  "description": "The public description of the bundle.",
  "expires_at": "2000-01-01T01:00:00Z",
  "paths": [

  ],
  "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>
  <id type="integer">1</id>
  <code>abc123</code>
  <created_at>2000-01-01T01:00:00Z</created_at>
  <description>The public description of the bundle.</description>
  <expires_at>2000-01-01T01:00:00Z</expires_at>
  <paths type="array"/>
  <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

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
user_id int64	User ID. Provide a value of `0` to operate the current session's user.
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
code string	Bundle name

Send email(s) with a link to bundle

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."}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

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>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

bundle = Files::Bundle.find(id)
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

Authentication Required

Available to all authenticated keys or sessions.

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 \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/bundles/{id}.xml \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

bundle = Files::Bundle.find(id)
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}

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
id int64 Required	Bundle ID.

Dns Records

This resource allows retrieving the DNS records that are needed to configure custom DNS for a Site.

The DnsRecord object

Example DnsRecord Object

{
  "id": "customdomain.com-CNAME-site.files.com",
  "domain": "my-custom-domain.com",
  "rrtype": "CNAME",
  "value": "mysite.files.com"
}

<?xml version="1.0" encoding="UTF-8"?>
<dns-record>
  <id>customdomain.com-CNAME-site.files.com</id>
  <domain>my-custom-domain.com</domain>
  <rrtype>CNAME</rrtype>
  <value>mysite.files.com</value>
</dns-record>

Attribute	Description
id string	Unique label for DNS record; used by Zapier and other integrations.
domain string	DNS record domain name
rrtype string	DNS record type
value string	DNS record value

Show site DNS configuration

Example Request

curl "https://app.files.com/api/rest/v1/dns_records.json?page=1&per_page=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/dns_records.xml?page=1&per_page=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::DnsRecord.list(
  page: 1, 
  per_page: 1
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\DnsRecord::list(array(
  'page' => 1, 
  'per_page' => 1
));

Example Response

[
  {
    "id": "customdomain.com-CNAME-site.files.com",
    "domain": "my-custom-domain.com",
    "rrtype": "CNAME",
    "value": "mysite.files.com"
  }
]

<?xml version="1.0" encoding="UTF-8"?>
<dns-records type="array">
  <dns-record>
    <id>customdomain.com-CNAME-site.files.com</id>
    <domain>my-custom-domain.com</domain>
    <rrtype>CNAME</rrtype>
    <value>mysite.files.com</value>
  </dns-record>
</dns-records>

HTTPS Request

GET /dns_records

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Request Parameters

Parameter	Description
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Deprecated: If set to `count` returns a count of matching records rather than the records themselves.

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-01T01:00:00Z",
  "provided_mtime": "2000-01-01T01:00:00Z",
  "crc32": "70976923",
  "md5": "17c54824e9931a4688ca032d03f6663c",
  "mime_type": "application/octet-stream",
  "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>2000-01-01T01:00:00Z</mtime>
  <provided_mtime>2000-01-01T01:00:00Z</provided_mtime>
  <crc32>70976923</crc32>
  <md5>17c54824e9931a4688ca032d03f6663c</md5>
  <mime_type>application/octet-stream</mime_type>
  <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.
mime_type string	MIME Type. This is determined by the filename extension and is not stored separately internally.
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
action string	The action to perform. Can be `append`, `attachment`, `end`, `upload`, `put`, or may not exist
length int64	Length of file.
mkdir_parents boolean	Create parent directories if they do not exist?
part int64	Part if uploading a part.
parts int64	How many parts to fetch?
ref string
restart int64	File byte offset to restart from.
structure string	If copying folder, copy just the structure?
with_rename boolean	Allow file rename instead of overwrite?

Download file

Example Request

curl "https://app.files.com/api/rest/v1/files/{path}?id=1&with_previews=true&with_priority_color=true" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/files/{path}?id=1&with_previews=true&with_priority_color=true" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

file = Files::File.find(path)
file.download(
  id: 1,
  with_previews: true,
  with_priority_color: true
)

\Files\Files::setApiKey('YOUR_API_KEY');

$file = \Files\File->find(1);
$file->download(array(
  'id' => 1, 
  '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-01T01:00:00Z",
  "provided_mtime": "2000-01-01T01:00:00Z",
  "crc32": "70976923",
  "md5": "17c54824e9931a4688ca032d03f6663c",
  "mime_type": "application/octet-stream",
  "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>2000-01-01T01:00:00Z</mtime>
  <provided_mtime>2000-01-01T01:00:00Z</provided_mtime>
  <crc32>70976923</crc32>
  <md5>17c54824e9931a4688ca032d03f6663c</md5>
  <mime_type>application/octet-stream</mime_type>
  <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

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
path string Required	Path to operate on.
action string	Can be blank, `redirect` or `stat`. If set to `stat`, we will return file information but without a download URL, and without logging a download. If set to `redirect` we will serve a 302 redirect directly to the file. This is used for integrations with Zapier, and is not recommended for most integrations.
id int64	If provided, lookup the file by id instead of path.
with_previews boolean	Include file preview information?
with_priority_color boolean	Include file priority color information?

List Folders by path

Example Request

curl "https://app.files.com/api/rest/v1/folders/{path}?page=1&per_page=1&search_all=true&with_priority_color=true" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/folders/{path}?page=1&per_page=1&search_all=true&with_priority_color=true" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::Folder.list_for(path, 
  page: 1, 
  per_page: 1, 
  search_all: true, 
  with_priority_color: true
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\Folder::listFor($path, array(
  'page' => 1, 
  'per_page' => 1, 
  'search_all' => true, 
  'with_priority_color' => true
));

Example Response

[
  {
    "id": 1,
    "path": "path/file.txt",
    "display_name": "file.txt",
    "type": "file",
    "size": 1024,
    "mtime": "2000-01-01T01:00:00Z",
    "provided_mtime": "2000-01-01T01:00:00Z",
    "crc32": "70976923",
    "md5": "17c54824e9931a4688ca032d03f6663c",
    "mime_type": "application/octet-stream",
    "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"?>
<files type="array">
  <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>2000-01-01T01:00:00Z</mtime>
    <provided_mtime>2000-01-01T01:00:00Z</provided_mtime>
    <crc32>70976923</crc32>
    <md5>17c54824e9931a4688ca032d03f6663c</md5>
    <mime_type>application/octet-stream</mime_type>
    <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>
</files>

HTTPS Request

GET /folders/?*path

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Action to take. Can be `count`, `count_nrs` (non recursive), `size`, `permissions`, or blank.
path string Required	Path to operate on.
cursor string	Send cursor to resume an existing list from the point at which you left off. Get a cursor from an existing list via the X-Files-Cursor header.
filter string	If specified, will to filter folders/files list by this string. Wildcards of `*` and `?` are acceptable here.
preview_size string	Request a preview size. Can be `small` (default), `large`, `xlarge`, or `pdf`.
search string	If `search_all` is `true`, provide the search string here. Otherwise, this parameter acts like an alias of `filter`.
search_all boolean	Search entire site?
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.

Copy file/folder

Example Request

curl https://app.files.com/api/rest/v1/file_actions/copy/{path} \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"destination":"destination"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/file_actions/copy/{path} \
  -X POST \
  -H 'Content-Type: application/xml' \
  -d '<file>
       <destination>destination</destination>
     </file>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

file_action = Files::FileAction.find(path)
file_action.copy(
  destination: "destination"
)

\Files\Files::setApiKey('YOUR_API_KEY');

$file_action = \Files\FileAction->find(1);
$file_action->copy(array(
  'destination' => "destination"
));

Example Response

No response.

No response.

HTTPS Request

POST /file_actions/copy/?*path

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
path string Required	Path to operate on.
destination string Required	Copy destination path.

Move file/folder

Example Request

curl https://app.files.com/api/rest/v1/file_actions/move/{path} \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"destination":"destination"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/file_actions/move/{path} \
  -X POST \
  -H 'Content-Type: application/xml' \
  -d '<file>
       <destination>destination</destination>
     </file>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

file_action = Files::FileAction.find(path)
file_action.move(
  destination: "destination"
)

\Files\Files::setApiKey('YOUR_API_KEY');

$file_action = \Files\FileAction->find(1);
$file_action->move(array(
  'destination' => "destination"
));

Example Response

No response.

No response.

HTTPS Request

POST /file_actions/move/?*path

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
path string Required	Path to operate on.
destination string Required	Move destination path.

Create folder

Example Request

curl https://app.files.com/api/rest/v1/folders/{path} \
  -X POST \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/folders/{path} \
  -X POST \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::Folder.create(path)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\Folder::create($path);

Example Response

{
  "id": 1,
  "path": "path/file.txt",
  "display_name": "file.txt",
  "type": "file",
  "size": 1024,
  "mtime": "2000-01-01T01:00:00Z",
  "provided_mtime": "2000-01-01T01:00:00Z",
  "crc32": "70976923",
  "md5": "17c54824e9931a4688ca032d03f6663c",
  "mime_type": "application/octet-stream",
  "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>2000-01-01T01:00:00Z</mtime>
  <provided_mtime>2000-01-01T01:00:00Z</provided_mtime>
  <crc32>70976923</crc32>
  <md5>17c54824e9931a4688ca032d03f6663c</md5>
  <mime_type>application/octet-stream</mime_type>
  <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

POST /folders/?*path

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
path string Required	Path to operate on.

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-01T01:00:00Z","priority_color":"red"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/files/{path} \
  -X PATCH \
  -H 'Content-Type: application/xml' \
  -d '<file>
       <provided_mtime>2000-01-01T01:00:00Z</provided_mtime>
       <priority_color>red</priority_color>
     </file>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

file = Files::File.find(path)
file.update(
  provided_mtime: "2000-01-01T01:00:00Z",
  priority_color: "red"
)

\Files\Files::setApiKey('YOUR_API_KEY');

$file = \Files\File->find(1);
$file->update(array(
  'provided_mtime' => "2000-01-01T01:00:00Z", 
  'priority_color' => "red"
));

Example Response

{
  "id": 1,
  "path": "path/file.txt",
  "display_name": "file.txt",
  "type": "file",
  "size": 1024,
  "mtime": "2000-01-01T01:00:00Z",
  "provided_mtime": "2000-01-01T01:00:00Z",
  "crc32": "70976923",
  "md5": "17c54824e9931a4688ca032d03f6663c",
  "mime_type": "application/octet-stream",
  "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>2000-01-01T01:00:00Z</mtime>
  <provided_mtime>2000-01-01T01:00:00Z</provided_mtime>
  <crc32>70976923</crc32>
  <md5>17c54824e9931a4688ca032d03f6663c</md5>
  <mime_type>application/octet-stream</mime_type>
  <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

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
path string Required	Path to operate on.
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}?recursive=true" \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/files/{path}?recursive=true" \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

file = Files::File.find(path)
file.delete(
  recursive: true
)

\Files\Files::setApiKey('YOUR_API_KEY');

$file = \Files\File->find(1);
$file->delete(array(
  'recursive' => true
));

Example Response

No response.

No response.

HTTPS Request

DELETE /files/?*path

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
path string Required	Path to operate on.
recursive boolean	If true, will recursively delete folers. Otherwise, will error on non-empty folders. For legacy reasons, this parameter may also be provided as the HTTP header `Depth: Infinity`

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:

Start a new upload by sending a request to REST API to indicate intent to upload a file.
Upload the file to the URL(s) provided by the REST API, possibly in parts via multiple uploads.
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://example-upload-proxy-url.com/path/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://example-upload-proxy-url.com/path/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://example-upload-proxy-url.com/path/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://example-upload-proxy-url.com/path/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://example-upload-proxy-url.com/path/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

File Comments

File Comments are comments attached to a file by a user.

The FileComment object

Example FileComment Object

{
  "id": 1,
  "body": "What a great file!",
  "reactions": [

  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<file-comment>
  <id type="integer">1</id>
  <body>What a great file!</body>
  <reactions type="array"/>
</file-comment>

Attribute	Description
id int64	File Comment ID
body string	Comment body.
reactions array	Reactions to this comment.
path string	File path.

List File Comments by path

Example Request

curl "https://app.files.com/api/rest/v1/file_comments/files/{path}?page=1&per_page=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/file_comments/files/{path}?page=1&per_page=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::FileComment.list_for(path, 
  page: 1, 
  per_page: 1
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\FileComment::listFor($path, array(
  'page' => 1, 
  'per_page' => 1
));

Example Response

[
  {
    "id": 1,
    "body": "What a great file!",
    "reactions": [

    ]
  }
]

<?xml version="1.0" encoding="UTF-8"?>
<file-comments type="array">
  <file-comment>
    <id type="integer">1</id>
    <body>What a great file!</body>
    <reactions type="array"/>
  </file-comment>
</file-comments>

HTTPS Request

GET /file_comments/files/?*path

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Deprecated: If set to `count` returns a count of matching records rather than the records themselves.
path string Required	Path to operate on.

Create File Comment

Example Request

curl https://app.files.com/api/rest/v1/file_comments.json \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"body":"body","path":"path"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/file_comments.xml \
  -X POST \
  -H 'Content-Type: application/xml' \
  -d '<file-comment>
       <body>body</body>
       <path>path</path>
     </file-comment>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::FileComment.create(
  body: "body", 
  path: "path"
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\FileComment::create(array(
  'body' => "body", 
  'path' => "path"
));

Example Response

{
  "id": 1,
  "body": "What a great file!",
  "reactions": [

  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<file-comment>
  <id type="integer">1</id>
  <body>What a great file!</body>
  <reactions type="array"/>
</file-comment>

HTTPS Request

POST /file_comments

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
body string Required	Comment body.
path string Required	File path.

Update File Comment

Example Request

curl https://app.files.com/api/rest/v1/file_comments/{id}.json \
  -X PATCH \
  -H 'Content-Type: application/json' \
  -d '{"body":"body"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/file_comments/{id}.xml \
  -X PATCH \
  -H 'Content-Type: application/xml' \
  -d '<file-comment>
       <body>body</body>
     </file-comment>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

file_comment = Files::FileComment.find(id)
file_comment.update(
  body: "body"
)

\Files\Files::setApiKey('YOUR_API_KEY');

$file_comment = \Files\FileComment->find(1);
$file_comment->update(array(
  'body' => "body"
));

Example Response

{
  "id": 1,
  "body": "What a great file!",
  "reactions": [

  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<file-comment>
  <id type="integer">1</id>
  <body>What a great file!</body>
  <reactions type="array"/>
</file-comment>

HTTPS Request

PATCH /file_comments/{id}

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
id int64 Required	File Comment ID.
body string Required	Comment body.

Delete File Comment

Example Request

curl https://app.files.com/api/rest/v1/file_comments/{id}.json \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/file_comments/{id}.xml \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

file_comment = Files::FileComment.find(id)
file_comment.delete

\Files\Files::setApiKey('YOUR_API_KEY');

$file_comment = \Files\FileComment->find(1);
$file_comment->delete();

Example Response

No response.

No response.

HTTPS Request

DELETE /file_comments/{id}

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
id int64 Required	File Comment ID.

File Comment Reactions

File Comment Reactionss are reactions that are attached to a comment on a file.

The FileCommentReaction object

Example FileCommentReaction Object

{
  "id": 1,
  "emoji": "👍"
}

<?xml version="1.0" encoding="UTF-8"?>
<file-comment-reaction>
  <id type="integer">1</id>
  <emoji>👍</emoji>
</file-comment-reaction>

Attribute	Description
id int64	Reaction ID
emoji string	Emoji used in the reaction.
user_id int64	User ID. Provide a value of `0` to operate the current session's user.
file_comment_id int64	ID of file comment to attach reaction to.

Create File Comment Reaction

Example Request

curl https://app.files.com/api/rest/v1/file_comment_reactions.json \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"user_id":1,"file_comment_id":1,"emoji":"emoji"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/file_comment_reactions.xml \
  -X POST \
  -H 'Content-Type: application/xml' \
  -d '<file-comment-reaction>
       <user_id type="integer">1</user_id>
       <file_comment_id type="integer">1</file_comment_id>
       <emoji>emoji</emoji>
     </file-comment-reaction>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::FileCommentReaction.create(
  user_id: 1, 
  file_comment_id: 1, 
  emoji: "emoji"
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\FileCommentReaction::create(array(
  'user_id' => 1, 
  'file_comment_id' => 1, 
  'emoji' => "emoji"
));

Example Response

{
  "id": 1,
  "emoji": "👍"
}

<?xml version="1.0" encoding="UTF-8"?>
<file-comment-reaction>
  <id type="integer">1</id>
  <emoji>👍</emoji>
</file-comment-reaction>

HTTPS Request

POST /file_comment_reactions

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
user_id int64	User ID. Provide a value of `0` to operate the current session's user.
file_comment_id int64 Required	ID of file comment to attach reaction to.
emoji string Required	Emoji to react with.

Delete File Comment Reaction

Example Request

curl https://app.files.com/api/rest/v1/file_comment_reactions/{id}.json \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/file_comment_reactions/{id}.xml \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

file_comment_reaction = Files::FileCommentReaction.find(id)
file_comment_reaction.delete

\Files\Files::setApiKey('YOUR_API_KEY');

$file_comment_reaction = \Files\FileCommentReaction->find(1);
$file_comment_reaction->delete();

Example Response

No response.

No response.

HTTPS Request

DELETE /file_comment_reactions/{id}

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
id int64 Required	File Comment Reaction ID.

File Part Uploads

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

The FilePartUpload object

Example FilePartUpload Object

{
  "send": "",
  "action": "upload/direct",
  "ask_about_overwrites": true,
  "available_parts": "",
  "expires": "",
  "headers": "",
  "http_method": "POST",
  "next_partsize": "",
  "parameters": "",
  "part_number": "",
  "partsize": "",
  "path": "path",
  "ref": "upload-1",
  "upload_uri": ""
}

<?xml version="1.0" encoding="UTF-8"?>
<file-part-upload>
  <send></send>
  <action>upload/direct</action>
  <ask_about_overwrites type="boolean">true</ask_about_overwrites>
  <available_parts></available_parts>
  <expires></expires>
  <headers></headers>
  <http_method>POST</http_method>
  <next_partsize></next_partsize>
  <parameters></parameters>
  <part_number></part_number>
  <partsize></partsize>
  <path>path</path>
  <ref>upload-1</ref>
  <upload_uri></upload_uri>
</file-part-upload>

Attribute	Description
send object	Content-Type and File to send
action string	Type of upload
ask_about_overwrites boolean	If false, rename conflicting files instead of asking for overwrite confirmation
available_parts string	Currently unused
expires string	Currently unused
headers object	Additional upload headers
http_method string	Upload method, usually POST
next_partsize string	Currently unused
parameters string	Additional upload parameters
part_number string	Currently unused
partsize string	Currently unused
path string	Upload path This must be slash-delimited, but it must neither start nor end with a slash. Maximum of 5000 characters.
ref string	Reference name for this upload part
upload_uri string	URI to upload this part to

Begin file upload

Example Request

curl https://app.files.com/api/rest/v1/file_actions/begin_upload/{path} \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"mkdir_parents":true,"part":1,"parts":1,"ref":"upload-1","restart":1,"with_rename":true}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/file_actions/begin_upload/{path} \
  -X POST \
  -H 'Content-Type: application/xml' \
  -d '<file-part-upload>
       <mkdir_parents type="boolean">true</mkdir_parents>
       <part type="integer">1</part>
       <parts type="integer">1</parts>
       <ref>upload-1</ref>
       <restart type="integer">1</restart>
       <with_rename type="boolean">true</with_rename>
     </file-part-upload>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

file_action = Files::FileAction.find(path)
file_action.begin_upload(
  mkdir_parents: true,
  part: 1,
  parts: 1,
  ref: "upload-1",
  restart: 1,
  with_rename: true
)

\Files\Files::setApiKey('YOUR_API_KEY');

$file_action = \Files\FileAction->find(1);
$file_action->beginUpload(array(
  'mkdir_parents' => true, 
  'part' => 1, 
  'parts' => 1, 
  'ref' => "upload-1", 
  'restart' => 1, 
  'with_rename' => true
));

Example Response

{
  "send": "",
  "action": "upload/direct",
  "ask_about_overwrites": true,
  "available_parts": "",
  "expires": "",
  "headers": "",
  "http_method": "POST",
  "next_partsize": "",
  "parameters": "",
  "part_number": "",
  "partsize": "",
  "path": "path",
  "ref": "upload-1",
  "upload_uri": ""
}

<?xml version="1.0" encoding="UTF-8"?>
<file-part-upload>
  <send></send>
  <action>upload/direct</action>
  <ask_about_overwrites type="boolean">true</ask_about_overwrites>
  <available_parts></available_parts>
  <expires></expires>
  <headers></headers>
  <http_method>POST</http_method>
  <next_partsize></next_partsize>
  <parameters></parameters>
  <part_number></part_number>
  <partsize></partsize>
  <path>path</path>
  <ref>upload-1</ref>
  <upload_uri></upload_uri>
</file-part-upload>

HTTPS Request

POST /file_actions/begin_upload/?*path

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
path string Required	Path to operate on.
mkdir_parents boolean	Create parent directories if they do not exist?
part int64	Part if uploading a part.
parts int64	How many parts to fetch?
ref string
restart int64	File byte offset to restart from.
with_rename boolean	Allow file rename instead of overwrite?

Groups

Groups are a powerful tool for permissions and user management on Files.com. Users can belong to multiple groups.

All permissions can be managed via Groups, and Groups can also be synced to your identity platform via LDAP or SCIM.

Files.com's Group Admin feature allows you to define Group Admins, who then have access to add and remove users within their groups.

The Group object

Example Group Object

{
  "id": 1,
  "name": "owners",
  "admin_ids": [

  ],
  "notes": "",
  "user_ids": [

  ],
  "usernames": [

  ]
}

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

Attribute	Description
id int64	Group ID
name string	Group name
admin_ids array	List of user IDs who are group administrators (separated by commas)
notes string	Notes about this group
user_ids array	List of user IDs who belong to this group (separated by commas)
usernames array	List of usernames who belong to this group (separated by commas)

List Groups

Example Request

curl "https://app.files.com/api/rest/v1/groups.json?page=1&per_page=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/groups.xml?page=1&per_page=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::Group.list(
  page: 1, 
  per_page: 1
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\Group::list(array(
  'page' => 1, 
  'per_page' => 1
));

Example Response

[
  {
    "id": 1,
    "name": "owners",
    "admin_ids": [

    ],
    "notes": "",
    "user_ids": [

    ],
    "usernames": [

    ]
  }
]

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

HTTPS Request

GET /groups

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Folder Admin permissions.

Request Parameters

Parameter	Description
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Deprecated: If set to `count` returns a count of matching records rather than the records themselves.
ids string	Comma-separated list of group ids to include in results.

Show Group

Example Request

curl https://app.files.com/api/rest/v1/groups/{id}.json \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/groups/{id}.xml \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::Group.find(id)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\Group::find($id);

Example Response

{
  "id": 1,
  "name": "owners",
  "admin_ids": [

  ],
  "notes": "",
  "user_ids": [

  ],
  "usernames": [

  ]
}

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

HTTPS Request

GET /groups/{id}

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Folder Admin permissions.

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"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/groups.xml \
  -X POST \
  -H 'Content-Type: application/xml' \
  -d '<group>
       <name>owners</name>
     </group>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

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,
  "name": "owners",
  "admin_ids": [

  ],
  "notes": "",
  "user_ids": [

  ],
  "usernames": [

  ]
}

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

HTTPS Request

POST /groups

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

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 PATCH \
  -H 'Content-Type: application/json' \
  -d '{"name":"owners"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/groups/{id}.xml \
  -X PATCH \
  -H 'Content-Type: application/xml' \
  -d '<group>
       <name>owners</name>
     </group>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

group = Files::Group.find(id)
group.update(
  name: "owners"
)

\Files\Files::setApiKey('YOUR_API_KEY');

$group = \Files\Group->find(1);
$group->update(array(
  'name' => "owners"
));

Example Response

{
  "id": 1,
  "name": "owners",
  "admin_ids": [

  ],
  "notes": "",
  "user_ids": [

  ],
  "usernames": [

  ]
}

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

HTTPS Request

PATCH /groups/{id}

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

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.

Delete Group

Example Request

curl https://app.files.com/api/rest/v1/groups/{id}.json \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/groups/{id}.xml \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

group = Files::Group.find(id)
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}

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Request Parameters

Parameter	Description
id int64 Required	Group ID.

Group Users

A GroupUser describes the membership of a User within a Group.

The GroupUser object

Example GroupUser Object

{
  "name": "My Group",
  "id": 1,
  "admin": true,
  "usernames": [

  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<group-user>
  <name>My Group</name>
  <id type="integer">1</id>
  <admin type="boolean">true</admin>
  <usernames type="array"/>
</group-user>

Attribute	Description
name string	Group name
id int64	Group ID
admin boolean	Is this user an administrator of this group?
usernames array	A list of usernames for users in this group
group_id int64	Group ID to add user to.
user_id int64	User ID to add to group.

List Group Users

Example Request

curl "https://app.files.com/api/rest/v1/group_users.json?user_id=1&page=1&per_page=1&group_id=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/group_users.xml?user_id=1&page=1&per_page=1&group_id=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::GroupUser.list(
  user_id: 1, 
  page: 1, 
  per_page: 1, 
  group_id: 1
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\GroupUser::list(array(
  'user_id' => 1, 
  'page' => 1, 
  'per_page' => 1, 
  'group_id' => 1
));

Example Response

[
  {
    "name": "My Group",
    "id": 1,
    "admin": true,
    "usernames": [

    ]
  }
]

<?xml version="1.0" encoding="UTF-8"?>
<group-users type="array">
  <group-user>
    <name>My Group</name>
    <id type="integer">1</id>
    <admin type="boolean">true</admin>
    <usernames type="array"/>
  </group-user>
</group-users>

HTTPS Request

GET /group_users

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
user_id int64	User ID. If provided, will return groups of which this user is a member.
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Deprecated: If set to `count` returns a count of matching records rather than the records themselves.
group_id int64	Group ID. If provided, will return members of this group.

Update Group User

Example Request

curl https://app.files.com/api/rest/v1/group_users/{id}.json \
  -X PATCH \
  -H 'Content-Type: application/json' \
  -d '{"group_id":1,"user_id":1,"admin":true}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/group_users/{id}.xml \
  -X PATCH \
  -H 'Content-Type: application/xml' \
  -d '<group-user>
       <group_id type="integer">1</group_id>
       <user_id type="integer">1</user_id>
       <admin type="boolean">true</admin>
     </group-user>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

group_user = Files::GroupUser.find(id)
group_user.update(
  group_id: 1,
  user_id: 1,
  admin: true
)

\Files\Files::setApiKey('YOUR_API_KEY');

$group_user = \Files\GroupUser->find(1);
$group_user->update(array(
  'group_id' => 1, 
  'user_id' => 1, 
  'admin' => true
));

Example Response

{
  "name": "My Group",
  "id": 1,
  "admin": true,
  "usernames": [

  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<group-user>
  <name>My Group</name>
  <id type="integer">1</id>
  <admin type="boolean">true</admin>
  <usernames type="array"/>
</group-user>

HTTPS Request

PATCH /group_users/{id}

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Request Parameters

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

Delete Group User

Example Request

curl https://app.files.com/api/rest/v1/group_users/{id}.json \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/group_users/{id}.xml \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

group_user = Files::GroupUser.find(id)
group_user.delete

\Files\Files::setApiKey('YOUR_API_KEY');

$group_user = \Files\GroupUser->find(1);
$group_user->delete();

Example Response

No response.

No response.

HTTPS Request

DELETE /group_users/{id}

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Request Parameters

Parameter	Description
id int64 Required	Group User ID.

History Exports

The History Export resource on the API is used to export historical action (history) logs. We store recent action logs in a separate location from archived logs. This API is used to query historical logs that aren't available in the regular History API because they've aged out.

All queries against the archive must be submitted as Exports. (Even our Web UI creates an Export behind the scenes.)

Actions that are less than 24 hours old may not be available in this API. (But, they may also be made available earlier on a best-effort basis.) Thus, if you want to see all history for a given file or folder, you should query both this API and the "live" History API.

That's exactly what our Web UI does.

The best practice that we follow and recommend when doing a query against both APIs is to use a value of yesterday's midnight Eastern time as the end_at for queries against the HistoryExport API and as the start_at for queries against the History API. This ensures that you retrieve all entries, with no overlap.

We use Amazon Athena behind the scenes for processing these queries, and as such, have powerful search capabilities. We've done our best to expose search capabilities via this History Export API.

In any query field in this API, you may specify multiple values separated by commas. That means that commas cannot be searched for themselves, and neither can single quotation marks.

We do not currently partition data by date on the backend, so all queries result in a full scan of the entire data lake. This means that all queries will take about the same amount of time to complete, and we incur about the same cost per query internally. We don't typically bill our customers for these queries, assuming usage is occasional and manual.

If you intend to use this API for high volume or automated use, please contact us with more information about your use case. We may decide to change the backend data schema to match your use case more closely, and we may also need to charge an additional cost per query.

The HistoryExport object

Example HistoryExport Object

{
  "id": 1,
  "start_at": "2000-01-01T01:00:00Z",
  "end_at": "2000-01-01T01:00:00Z",
  "status": "ready",
  "query_action": "read",
  "query_interface": "ftp",
  "query_user_id": 1,
  "query_file_id": 1,
  "query_parent_id": 1,
  "query_path": "MyFile.txt",
  "query_folder": "Folder",
  "query_src": "SrcFolder",
  "query_destination": "DestFolder",
  "query_ip": "127.0.0.1",
  "query_username": "jerry",
  "query_failure_type": "bad_password",
  "query_target_id": 1,
  "query_target_name": "full",
  "query_target_permission": "full",
  "query_target_user_id": 1,
  "query_target_username": "jerry",
  "query_target_platform": "windows",
  "query_target_permission_set": "desktop_app"
}

<?xml version="1.0" encoding="UTF-8"?>
<history-export>
  <id type="integer">1</id>
  <start_at>2000-01-01T01:00:00Z</start_at>
  <end_at>2000-01-01T01:00:00Z</end_at>
  <status>ready</status>
  <query_action>read</query_action>
  <query_interface>ftp</query_interface>
  <query_user_id type="integer">1</query_user_id>
  <query_file_id type="integer">1</query_file_id>
  <query_parent_id type="integer">1</query_parent_id>
  <query_path>MyFile.txt</query_path>
  <query_folder>Folder</query_folder>
  <query_src>SrcFolder</query_src>
  <query_destination>DestFolder</query_destination>
  <query_ip>127.0.0.1</query_ip>
  <query_username>jerry</query_username>
  <query_failure_type>bad_password</query_failure_type>
  <query_target_id type="integer">1</query_target_id>
  <query_target_name>full</query_target_name>
  <query_target_permission>full</query_target_permission>
  <query_target_user_id type="integer">1</query_target_user_id>
  <query_target_username>jerry</query_target_username>
  <query_target_platform>windows</query_target_platform>
  <query_target_permission_set>desktop_app</query_target_permission_set>
</history-export>

Attribute	Description
id int64	History Export ID
start_at date-time	Start date/time of export range.
end_at date-time	End date/time of export range.
status string	Status of export. Will be: `building` or `ready`
query_action string	Filter results by this this action type. Valid values: `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`, `api_key_destroy`
query_interface string	Filter results by this this interface type. Valid values: `web`, `ftp`, `robot`, `jsapi`, `webdesktopapi`, `sftp`, `dav`, `desktop`, `restapi`, `scim`
query_user_id int64	Return results that are actions performed by the user indiciated by this User ID
query_file_id int64	Return results that are file actions related to the file indicated by this File ID
query_parent_id int64	Return results that are file actions inside the parent folder specified by this folder ID
query_path string	Return results that are file actions related to this path.
query_folder string	Return results that are file actions related to files or folders inside this folder path.
query_src string	Return results that are file moves originating from this path.
query_destination string	Return results that are file moves with this path as destination.
query_ip string	Filter results by this IP address.
query_username string	Filter results by this username.
query_failure_type string	If searching for Histories about login failures, this parameter restricts results to failures of this specific type. Valid values: `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`, `expired_access`, `desktop_ip_mismatch`, `desktop_api_key_not_used_quickly_enough`, `disabled`
query_target_id int64	If searching for Histories about specific objects (such as Users, or API Keys), this paremeter restricts results to objects that match this ID.
query_target_name string	If searching for Histories about Users, Groups or other objects with names, this parameter restricts results to objects with this name/username.
query_target_permission string	If searching for Histories about Permisisons, this parameter restricts results to permissions of this level.
query_target_user_id int64	If searching for Histories about API keys, this parameter restricts results to API keys created by/for this user ID.
query_target_username string	If searching for Histories about API keys, this parameter restricts results to API keys created by/for this username.
query_target_platform string	If searching for Histories about API keys, this parameter restricts results to API keys associated with this platform.
query_target_permission_set string	If searching for Histories about API keys, this parameter restricts results to API keys with this permission set.
user_id int64	User ID. Provide a value of `0` to operate the current session's user.

List History Exports

Example Request

curl "https://app.files.com/api/rest/v1/history_exports.json?user_id=1&page=1&per_page=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/history_exports.xml?user_id=1&page=1&per_page=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::HistoryExport.list(
  user_id: 1, 
  page: 1, 
  per_page: 1
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\HistoryExport::list(array(
  'user_id' => 1, 
  'page' => 1, 
  'per_page' => 1
));

Example Response

[
  {
    "id": 1,
    "start_at": "2000-01-01T01:00:00Z",
    "end_at": "2000-01-01T01:00:00Z",
    "status": "ready",
    "query_action": "read",
    "query_interface": "ftp",
    "query_user_id": 1,
    "query_file_id": 1,
    "query_parent_id": 1,
    "query_path": "MyFile.txt",
    "query_folder": "Folder",
    "query_src": "SrcFolder",
    "query_destination": "DestFolder",
    "query_ip": "127.0.0.1",
    "query_username": "jerry",
    "query_failure_type": "bad_password",
    "query_target_id": 1,
    "query_target_name": "full",
    "query_target_permission": "full",
    "query_target_user_id": 1,
    "query_target_username": "jerry",
    "query_target_platform": "windows",
    "query_target_permission_set": "desktop_app"
  }
]

<?xml version="1.0" encoding="UTF-8"?>
<history-exports type="array">
  <history-export>
    <id type="integer">1</id>
    <start_at>2000-01-01T01:00:00Z</start_at>
    <end_at>2000-01-01T01:00:00Z</end_at>
    <status>ready</status>
    <query_action>read</query_action>
    <query_interface>ftp</query_interface>
    <query_user_id type="integer">1</query_user_id>
    <query_file_id type="integer">1</query_file_id>
    <query_parent_id type="integer">1</query_parent_id>
    <query_path>MyFile.txt</query_path>
    <query_folder>Folder</query_folder>
    <query_src>SrcFolder</query_src>
    <query_destination>DestFolder</query_destination>
    <query_ip>127.0.0.1</query_ip>
    <query_username>jerry</query_username>
    <query_failure_type>bad_password</query_failure_type>
    <query_target_id type="integer">1</query_target_id>
    <query_target_name>full</query_target_name>
    <query_target_permission>full</query_target_permission>
    <query_target_user_id type="integer">1</query_target_user_id>
    <query_target_username>jerry</query_target_username>
    <query_target_platform>windows</query_target_platform>
    <query_target_permission_set>desktop_app</query_target_permission_set>
  </history-export>
</history-exports>

HTTPS Request

GET /history_exports

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
user_id int64	User ID. Provide a value of `0` to operate the current session's user.
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Deprecated: If set to `count` returns a count of matching records rather than the records themselves.

Show History Export

Example Request

curl https://app.files.com/api/rest/v1/history_exports/{id}.json \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/history_exports/{id}.xml \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::HistoryExport.find(id)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\HistoryExport::find($id);

Example Response

{
  "id": 1,
  "start_at": "2000-01-01T01:00:00Z",
  "end_at": "2000-01-01T01:00:00Z",
  "status": "ready",
  "query_action": "read",
  "query_interface": "ftp",
  "query_user_id": 1,
  "query_file_id": 1,
  "query_parent_id": 1,
  "query_path": "MyFile.txt",
  "query_folder": "Folder",
  "query_src": "SrcFolder",
  "query_destination": "DestFolder",
  "query_ip": "127.0.0.1",
  "query_username": "jerry",
  "query_failure_type": "bad_password",
  "query_target_id": 1,
  "query_target_name": "full",
  "query_target_permission": "full",
  "query_target_user_id": 1,
  "query_target_username": "jerry",
  "query_target_platform": "windows",
  "query_target_permission_set": "desktop_app"
}

<?xml version="1.0" encoding="UTF-8"?>
<history-export>
  <id type="integer">1</id>
  <start_at>2000-01-01T01:00:00Z</start_at>
  <end_at>2000-01-01T01:00:00Z</end_at>
  <status>ready</status>
  <query_action>read</query_action>
  <query_interface>ftp</query_interface>
  <query_user_id type="integer">1</query_user_id>
  <query_file_id type="integer">1</query_file_id>
  <query_parent_id type="integer">1</query_parent_id>
  <query_path>MyFile.txt</query_path>
  <query_folder>Folder</query_folder>
  <query_src>SrcFolder</query_src>
  <query_destination>DestFolder</query_destination>
  <query_ip>127.0.0.1</query_ip>
  <query_username>jerry</query_username>
  <query_failure_type>bad_password</query_failure_type>
  <query_target_id type="integer">1</query_target_id>
  <query_target_name>full</query_target_name>
  <query_target_permission>full</query_target_permission>
  <query_target_user_id type="integer">1</query_target_user_id>
  <query_target_username>jerry</query_target_username>
  <query_target_platform>windows</query_target_platform>
  <query_target_permission_set>desktop_app</query_target_permission_set>
</history-export>

HTTPS Request

GET /history_exports/{id}

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
id int64 Required	History Export ID.

Create History Export

Example Request

curl https://app.files.com/api/rest/v1/history_exports.json \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"user_id":1,"start_at":"2000-01-01T01:00:00Z","end_at":"2000-01-01T01:00:00Z","query_action":"read","query_interface":"ftp","query_user_id":1,"query_file_id":1,"query_parent_id":1,"query_path":"MyFile.txt","query_folder":"Folder","query_src":"SrcFolder","query_destination":"DestFolder","query_ip":"127.0.0.1","query_username":"jerry","query_failure_type":"bad_password","query_target_id":1,"query_target_name":"full","query_target_permission":"full","query_target_user_id":1,"query_target_username":"jerry","query_target_platform":"windows","query_target_permission_set":"desktop_app"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/history_exports.xml \
  -X POST \
  -H 'Content-Type: application/xml' \
  -d '<history-export>
       <user_id type="integer">1</user_id>
       <start_at>2000-01-01T01:00:00Z</start_at>
       <end_at>2000-01-01T01:00:00Z</end_at>
       <query_action>read</query_action>
       <query_interface>ftp</query_interface>
       <query_user_id type="integer">1</query_user_id>
       <query_file_id type="integer">1</query_file_id>
       <query_parent_id type="integer">1</query_parent_id>
       <query_path>MyFile.txt</query_path>
       <query_folder>Folder</query_folder>
       <query_src>SrcFolder</query_src>
       <query_destination>DestFolder</query_destination>
       <query_ip>127.0.0.1</query_ip>
       <query_username>jerry</query_username>
       <query_failure_type>bad_password</query_failure_type>
       <query_target_id type="integer">1</query_target_id>
       <query_target_name>full</query_target_name>
       <query_target_permission>full</query_target_permission>
       <query_target_user_id type="integer">1</query_target_user_id>
       <query_target_username>jerry</query_target_username>
       <query_target_platform>windows</query_target_platform>
       <query_target_permission_set>desktop_app</query_target_permission_set>
     </history-export>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::HistoryExport.create(
  user_id: 1, 
  start_at: "2000-01-01T01:00:00Z", 
  end_at: "2000-01-01T01:00:00Z", 
  query_action: "read", 
  query_interface: "ftp", 
  query_user_id: 1, 
  query_file_id: 1, 
  query_parent_id: 1, 
  query_path: "MyFile.txt", 
  query_folder: "Folder", 
  query_src: "SrcFolder", 
  query_destination: "DestFolder", 
  query_ip: "127.0.0.1", 
  query_username: "jerry", 
  query_failure_type: "bad_password", 
  query_target_id: 1, 
  query_target_name: "full", 
  query_target_permission: "full", 
  query_target_user_id: 1, 
  query_target_username: "jerry", 
  query_target_platform: "windows", 
  query_target_permission_set: "desktop_app"
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\HistoryExport::create(array(
  'user_id' => 1, 
  'start_at' => "2000-01-01T01:00:00Z", 
  'end_at' => "2000-01-01T01:00:00Z", 
  'query_action' => "read", 
  'query_interface' => "ftp", 
  'query_user_id' => 1, 
  'query_file_id' => 1, 
  'query_parent_id' => 1, 
  'query_path' => "MyFile.txt", 
  'query_folder' => "Folder", 
  'query_src' => "SrcFolder", 
  'query_destination' => "DestFolder", 
  'query_ip' => "127.0.0.1", 
  'query_username' => "jerry", 
  'query_failure_type' => "bad_password", 
  'query_target_id' => 1, 
  'query_target_name' => "full", 
  'query_target_permission' => "full", 
  'query_target_user_id' => 1, 
  'query_target_username' => "jerry", 
  'query_target_platform' => "windows", 
  'query_target_permission_set' => "desktop_app"
));

Example Response

{
  "id": 1,
  "start_at": "2000-01-01T01:00:00Z",
  "end_at": "2000-01-01T01:00:00Z",
  "status": "ready",
  "query_action": "read",
  "query_interface": "ftp",
  "query_user_id": 1,
  "query_file_id": 1,
  "query_parent_id": 1,
  "query_path": "MyFile.txt",
  "query_folder": "Folder",
  "query_src": "SrcFolder",
  "query_destination": "DestFolder",
  "query_ip": "127.0.0.1",
  "query_username": "jerry",
  "query_failure_type": "bad_password",
  "query_target_id": 1,
  "query_target_name": "full",
  "query_target_permission": "full",
  "query_target_user_id": 1,
  "query_target_username": "jerry",
  "query_target_platform": "windows",
  "query_target_permission_set": "desktop_app"
}

<?xml version="1.0" encoding="UTF-8"?>
<history-export>
  <id type="integer">1</id>
  <start_at>2000-01-01T01:00:00Z</start_at>
  <end_at>2000-01-01T01:00:00Z</end_at>
  <status>ready</status>
  <query_action>read</query_action>
  <query_interface>ftp</query_interface>
  <query_user_id type="integer">1</query_user_id>
  <query_file_id type="integer">1</query_file_id>
  <query_parent_id type="integer">1</query_parent_id>
  <query_path>MyFile.txt</query_path>
  <query_folder>Folder</query_folder>
  <query_src>SrcFolder</query_src>
  <query_destination>DestFolder</query_destination>
  <query_ip>127.0.0.1</query_ip>
  <query_username>jerry</query_username>
  <query_failure_type>bad_password</query_failure_type>
  <query_target_id type="integer">1</query_target_id>
  <query_target_name>full</query_target_name>
  <query_target_permission>full</query_target_permission>
  <query_target_user_id type="integer">1</query_target_user_id>
  <query_target_username>jerry</query_target_username>
  <query_target_platform>windows</query_target_platform>
  <query_target_permission_set>desktop_app</query_target_permission_set>
</history-export>

HTTPS Request

POST /history_exports

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
user_id int64	User ID. Provide a value of `0` to operate the current session's user.
start_at string	Start date/time of export range.
end_at string	End date/time of export range.
query_action string	Filter results by this this action type. Valid values: `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`, `api_key_destroy`
query_interface string	Filter results by this this interface type. Valid values: `web`, `ftp`, `robot`, `jsapi`, `webdesktopapi`, `sftp`, `dav`, `desktop`, `restapi`, `scim`
query_user_id int64	Return results that are actions performed by the user indiciated by this User ID
query_file_id int64	Return results that are file actions related to the file indicated by this File ID
query_parent_id int64	Return results that are file actions inside the parent folder specified by this folder ID
query_path string	Return results that are file actions related to this path.
query_folder string	Return results that are file actions related to files or folders inside this folder path.
query_src string	Return results that are file moves originating from this path.
query_destination string	Return results that are file moves with this path as destination.
query_ip string	Filter results by this IP address.
query_username string	Filter results by this username.
query_failure_type string	If searching for Histories about login failures, this parameter restricts results to failures of this specific type. Valid values: `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`, `expired_access`, `desktop_ip_mismatch`, `desktop_api_key_not_used_quickly_enough`, `disabled`
query_target_id int64	If searching for Histories about specific objects (such as Users, or API Keys), this paremeter restricts results to objects that match this ID.
query_target_name string	If searching for Histories about Users, Groups or other objects with names, this parameter restricts results to objects with this name/username.
query_target_permission string	If searching for Histories about Permisisons, this parameter restricts results to permissions of this level.
query_target_user_id int64	If searching for Histories about API keys, this parameter restricts results to API keys created by/for this user ID.
query_target_username string	If searching for Histories about API keys, this parameter restricts results to API keys created by/for this username.
query_target_platform string	If searching for Histories about API keys, this parameter restricts results to API keys associated with this platform.
query_target_permission_set string	If searching for Histories about API keys, this parameter restricts results to API keys with this permission set.

Delete History Export

Example Request

curl https://app.files.com/api/rest/v1/history_exports/{id}.json \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/history_exports/{id}.xml \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

history_export = Files::HistoryExport.find(id)
history_export.delete

\Files\Files::setApiKey('YOUR_API_KEY');

$history_export = \Files\HistoryExport->find(1);
$history_export->delete();

Example Response

No response.

No response.

HTTPS Request

DELETE /history_exports/{id}

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
id int64 Required	History Export ID.

Ip Addresses

Customers who maintain custom firewall configurations may require knowing the public IP addresses of Files.com's edge servers.

This API resource provides an updated list of IP addresses that you can use to automate keeping your firewall's configuration up to date.

The IpAddress object

Example IpAddress Object

{
  "id": "Site",
  "associated_with": "Site",
  "group_id": 1,
  "ip_addresses": [

  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<ip-address>
  <id>Site</id>
  <associated_with>Site</associated_with>
  <group_id type="integer">1</group_id>
  <ip_addresses type="array"/>
</ip-address>

Attribute	Description
id string	Unique label for list; used by Zapier and other integrations.
associated_with string	The object that this public IP address list is associated with.
group_id int64	Group ID
ip_addresses array	A list of IP addresses.

List Ip Addresses

Example Request

curl "https://app.files.com/api/rest/v1/ip_addresses.json?page=1&per_page=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/ip_addresses.xml?page=1&per_page=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::IpAddress.list(
  page: 1, 
  per_page: 1
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\IpAddress::list(array(
  'page' => 1, 
  'per_page' => 1
));

Example Response

[
  {
    "id": "Site",
    "associated_with": "Site",
    "group_id": 1,
    "ip_addresses": [

    ]
  }
]

<?xml version="1.0" encoding="UTF-8"?>
<ip-addresses type="array">
  <ip-address>
    <id>Site</id>
    <associated_with>Site</associated_with>
    <group_id type="integer">1</group_id>
    <ip_addresses type="array"/>
  </ip-address>
</ip-addresses>

HTTPS Request

GET /ip_addresses

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Request Parameters

Parameter	Description
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Deprecated: If set to `count` returns a count of matching records rather than the records themselves.

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 offering and desktop app does leverage this locking API.

The Lock object

Example Lock Object

{
  "path": "locked_file",
  "timeout": 43200,
  "depth": "infinity",
  "owner": "user",
  "scope": "shared",
  "token": "17c54824e9931a4688ca032d03f6663c",
  "type": "write",
  "user_id": 1,
  "username": "username"
}

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

Attribute	Description
path string	Path This must be slash-delimited, but it must neither start nor end with a slash. Maximum of 5000 characters.
timeout int64	Lock timeout
depth string	Lock depth (0 or infinity)
owner string	Owner of lock. This can be any arbitrary string.
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 by path

Example Request

curl "https://app.files.com/api/rest/v1/locks/{path}?page=1&per_page=1&include_children=true" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/locks/{path}?page=1&per_page=1&include_children=true" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::Lock.list_for(path, 
  page: 1, 
  per_page: 1, 
  include_children: true
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\Lock::listFor($path, array(
  'page' => 1, 
  'per_page' => 1, 
  'include_children' => true
));

Example Response

[
  {
    "path": "locked_file",
    "timeout": 43200,
    "depth": "infinity",
    "owner": "user",
    "scope": "shared",
    "token": "17c54824e9931a4688ca032d03f6663c",
    "type": "write",
    "user_id": 1,
    "username": "username"
  }
]

<?xml version="1.0" encoding="UTF-8"?>
<locks type="array">
  <lock>
    <path>locked_file</path>
    <timeout type="integer">43200</timeout>
    <depth>infinity</depth>
    <owner>user</owner>
    <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

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Deprecated: If set to `count` returns a count of matching records rather than the records themselves.
path string Required	Path to operate on.
include_children boolean	Include locks from children objects?

Create Lock

Example Request

curl https://app.files.com/api/rest/v1/locks/{path} \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"timeout":1}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

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>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

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

{
  "path": "locked_file",
  "timeout": 43200,
  "depth": "infinity",
  "owner": "user",
  "scope": "shared",
  "token": "17c54824e9931a4688ca032d03f6663c",
  "type": "write",
  "user_id": 1,
  "username": "username"
}

<?xml version="1.0" encoding="UTF-8"?>
<lock>
  <path>locked_file</path>
  <timeout type="integer">43200</timeout>
  <depth>infinity</depth>
  <owner>user</owner>
  <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

Authentication Required

Available to all authenticated keys or sessions.

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}?token=token" \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/locks/{path}?token=token" \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

lock = Files::Lock.find(path)
lock.delete(
  token: "token"
)

\Files\Files::setApiKey('YOUR_API_KEY');

$lock = \Files\Lock->find(1);
$lock->delete(array(
  'token' => "token"
));

Example Response

No response.

No response.

HTTPS Request

DELETE /locks/?*path

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
path string Required	Path
token string Required	Lock token

Messages

Messages are part of Files.com's project management features and represent a message posted by a user to a project.

The Message object

Example Message Object

{
  "id": 1,
  "subject": "Files.com Account Upgrade",
  "body": "We should upgrade our Files.com account!",
  "comments": [

  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<message>
  <id type="integer">1</id>
  <subject>Files.com Account Upgrade</subject>
  <body>We should upgrade our Files.com account!</body>
  <comments type="array"/>
</message>

Attribute	Description
id int64	Message ID
subject string	Message subject.
body string	Message body.
comments array	Comments.
user_id int64	User ID. Provide a value of `0` to operate the current session's user.
project_id int64	Project to attach the message to.

List Messages

Example Request

curl "https://app.files.com/api/rest/v1/messages.json?user_id=1&page=1&per_page=1&project_id=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/messages.xml?user_id=1&page=1&per_page=1&project_id=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::Message.list(
  user_id: 1, 
  page: 1, 
  per_page: 1, 
  project_id: 1
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\Message::list(array(
  'user_id' => 1, 
  'page' => 1, 
  'per_page' => 1, 
  'project_id' => 1
));

Example Response

[
  {
    "id": 1,
    "subject": "Files.com Account Upgrade",
    "body": "We should upgrade our Files.com account!",
    "comments": [

    ]
  }
]

<?xml version="1.0" encoding="UTF-8"?>
<messages type="array">
  <message>
    <id type="integer">1</id>
    <subject>Files.com Account Upgrade</subject>
    <body>We should upgrade our Files.com account!</body>
    <comments type="array"/>
  </message>
</messages>

HTTPS Request

GET /messages

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
user_id int64	User ID. Provide a value of `0` to operate the current session's user.
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Deprecated: If set to `count` returns a count of matching records rather than the records themselves.
project_id int64 Required	Project to return messages for.

Show Message

Example Request

curl https://app.files.com/api/rest/v1/messages/{id}.json \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/messages/{id}.xml \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::Message.find(id)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\Message::find($id);

Example Response

{
  "id": 1,
  "subject": "Files.com Account Upgrade",
  "body": "We should upgrade our Files.com account!",
  "comments": [

  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<message>
  <id type="integer">1</id>
  <subject>Files.com Account Upgrade</subject>
  <body>We should upgrade our Files.com account!</body>
  <comments type="array"/>
</message>

HTTPS Request

GET /messages/{id}

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
id int64 Required	Message ID.

Create Message

Example Request

curl https://app.files.com/api/rest/v1/messages.json \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"user_id":1,"project_id":1,"subject":"subject","body":"body"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/messages.xml \
  -X POST \
  -H 'Content-Type: application/xml' \
  -d '<message>
       <user_id type="integer">1</user_id>
       <project_id type="integer">1</project_id>
       <subject>subject</subject>
       <body>body</body>
     </message>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::Message.create(
  user_id: 1, 
  project_id: 1, 
  subject: "subject", 
  body: "body"
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\Message::create(array(
  'user_id' => 1, 
  'project_id' => 1, 
  'subject' => "subject", 
  'body' => "body"
));

Example Response

{
  "id": 1,
  "subject": "Files.com Account Upgrade",
  "body": "We should upgrade our Files.com account!",
  "comments": [

  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<message>
  <id type="integer">1</id>
  <subject>Files.com Account Upgrade</subject>
  <body>We should upgrade our Files.com account!</body>
  <comments type="array"/>
</message>

HTTPS Request

POST /messages

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
user_id int64	User ID. Provide a value of `0` to operate the current session's user.
project_id int64 Required	Project to attach the message to.
subject string Required	Message subject.
body string Required	Message body.

Update Message

Example Request

curl https://app.files.com/api/rest/v1/messages/{id}.json \
  -X PATCH \
  -H 'Content-Type: application/json' \
  -d '{"project_id":1,"subject":"subject","body":"body"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/messages/{id}.xml \
  -X PATCH \
  -H 'Content-Type: application/xml' \
  -d '<message>
       <project_id type="integer">1</project_id>
       <subject>subject</subject>
       <body>body</body>
     </message>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

message = Files::Message.find(id)
message.update(
  project_id: 1,
  subject: "subject",
  body: "body"
)

\Files\Files::setApiKey('YOUR_API_KEY');

$message = \Files\Message->find(1);
$message->update(array(
  'project_id' => 1, 
  'subject' => "subject", 
  'body' => "body"
));

Example Response

{
  "id": 1,
  "subject": "Files.com Account Upgrade",
  "body": "We should upgrade our Files.com account!",
  "comments": [

  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<message>
  <id type="integer">1</id>
  <subject>Files.com Account Upgrade</subject>
  <body>We should upgrade our Files.com account!</body>
  <comments type="array"/>
</message>

HTTPS Request

PATCH /messages/{id}

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
id int64 Required	Message ID.
project_id int64 Required	Project to attach the message to.
subject string Required	Message subject.
body string Required	Message body.

Delete Message

Example Request

curl https://app.files.com/api/rest/v1/messages/{id}.json \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/messages/{id}.xml \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

message = Files::Message.find(id)
message.delete

\Files\Files::setApiKey('YOUR_API_KEY');

$message = \Files\Message->find(1);
$message->delete();

Example Response

No response.

No response.

HTTPS Request

DELETE /messages/{id}

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
id int64 Required	Message ID.

Message Comments

A message comment represents a comment made by a user on a message.

The MessageComment object

Example MessageComment Object

{
  "id": 1,
  "body": "What a great idea, thank you!",
  "reactions": [

  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<message-comment>
  <id type="integer">1</id>
  <body>What a great idea, thank you!</body>
  <reactions type="array"/>
</message-comment>

Attribute	Description
id int64	Message Comment ID
body string	Comment body.
reactions array	Reactions to this comment.
user_id int64	User ID. Provide a value of `0` to operate the current session's user.

List Message Comments

Example Request

curl "https://app.files.com/api/rest/v1/message_comments.json?user_id=1&page=1&per_page=1&message_id=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/message_comments.xml?user_id=1&page=1&per_page=1&message_id=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::MessageComment.list(
  user_id: 1, 
  page: 1, 
  per_page: 1, 
  message_id: 1
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\MessageComment::list(array(
  'user_id' => 1, 
  'page' => 1, 
  'per_page' => 1, 
  'message_id' => 1
));

Example Response

[
  {
    "id": 1,
    "body": "What a great idea, thank you!",
    "reactions": [

    ]
  }
]

<?xml version="1.0" encoding="UTF-8"?>
<message-comments type="array">
  <message-comment>
    <id type="integer">1</id>
    <body>What a great idea, thank you!</body>
    <reactions type="array"/>
  </message-comment>
</message-comments>

HTTPS Request

GET /message_comments

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
user_id int64	User ID. Provide a value of `0` to operate the current session's user.
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Deprecated: If set to `count` returns a count of matching records rather than the records themselves.
message_id int64 Required	Message comment to return comments for.

Show Message Comment

Example Request

curl https://app.files.com/api/rest/v1/message_comments/{id}.json \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/message_comments/{id}.xml \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::MessageComment.find(id)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\MessageComment::find($id);

Example Response

{
  "id": 1,
  "body": "What a great idea, thank you!",
  "reactions": [

  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<message-comment>
  <id type="integer">1</id>
  <body>What a great idea, thank you!</body>
  <reactions type="array"/>
</message-comment>

HTTPS Request

GET /message_comments/{id}

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
id int64 Required	Message Comment ID.

Create Message Comment

Example Request

curl https://app.files.com/api/rest/v1/message_comments.json \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"user_id":1,"body":"body"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/message_comments.xml \
  -X POST \
  -H 'Content-Type: application/xml' \
  -d '<message-comment>
       <user_id type="integer">1</user_id>
       <body>body</body>
     </message-comment>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::MessageComment.create(
  user_id: 1, 
  body: "body"
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\MessageComment::create(array(
  'user_id' => 1, 
  'body' => "body"
));

Example Response

{
  "id": 1,
  "body": "What a great idea, thank you!",
  "reactions": [

  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<message-comment>
  <id type="integer">1</id>
  <body>What a great idea, thank you!</body>
  <reactions type="array"/>
</message-comment>

HTTPS Request

POST /message_comments

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
user_id int64	User ID. Provide a value of `0` to operate the current session's user.
body string Required	Comment body.

Update Message Comment

Example Request

curl https://app.files.com/api/rest/v1/message_comments/{id}.json \
  -X PATCH \
  -H 'Content-Type: application/json' \
  -d '{"body":"body"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/message_comments/{id}.xml \
  -X PATCH \
  -H 'Content-Type: application/xml' \
  -d '<message-comment>
       <body>body</body>
     </message-comment>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

message_comment = Files::MessageComment.find(id)
message_comment.update(
  body: "body"
)

\Files\Files::setApiKey('YOUR_API_KEY');

$message_comment = \Files\MessageComment->find(1);
$message_comment->update(array(
  'body' => "body"
));

Example Response

{
  "id": 1,
  "body": "What a great idea, thank you!",
  "reactions": [

  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<message-comment>
  <id type="integer">1</id>
  <body>What a great idea, thank you!</body>
  <reactions type="array"/>
</message-comment>

HTTPS Request

PATCH /message_comments/{id}

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
id int64 Required	Message Comment ID.
body string Required	Comment body.

Delete Message Comment

Example Request

curl https://app.files.com/api/rest/v1/message_comments/{id}.json \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/message_comments/{id}.xml \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

message_comment = Files::MessageComment.find(id)
message_comment.delete

\Files\Files::setApiKey('YOUR_API_KEY');

$message_comment = \Files\MessageComment->find(1);
$message_comment->delete();

Example Response

No response.

No response.

HTTPS Request

DELETE /message_comments/{id}

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
id int64 Required	Message Comment ID.

Message Comment Reactions

A message comment reaction represents a reaction emoji made by a user on a message comment.

The MessageCommentReaction object

Example MessageCommentReaction Object

{
  "id": 1,
  "emoji": "👍"
}

<?xml version="1.0" encoding="UTF-8"?>
<message-comment-reaction>
  <id type="integer">1</id>
  <emoji>👍</emoji>
</message-comment-reaction>

Attribute	Description
id int64	Reaction ID
emoji string	Emoji used in the reaction.
user_id int64	User ID. Provide a value of `0` to operate the current session's user.

List Message Comment Reactions

Example Request

curl "https://app.files.com/api/rest/v1/message_comment_reactions.json?user_id=1&page=1&per_page=1&message_comment_id=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/message_comment_reactions.xml?user_id=1&page=1&per_page=1&message_comment_id=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::MessageCommentReaction.list(
  user_id: 1, 
  page: 1, 
  per_page: 1, 
  message_comment_id: 1
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\MessageCommentReaction::list(array(
  'user_id' => 1, 
  'page' => 1, 
  'per_page' => 1, 
  'message_comment_id' => 1
));

Example Response

[
  {
    "id": 1,
    "emoji": "👍"
  }
]

<?xml version="1.0" encoding="UTF-8"?>
<message-comment-reactions type="array">
  <message-comment-reaction>
    <id type="integer">1</id>
    <emoji>👍</emoji>
  </message-comment-reaction>
</message-comment-reactions>

HTTPS Request

GET /message_comment_reactions

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
user_id int64	User ID. Provide a value of `0` to operate the current session's user.
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Deprecated: If set to `count` returns a count of matching records rather than the records themselves.
message_comment_id int64 Required	Message comment to return reactions for.

Show Message Comment Reaction

Example Request

curl https://app.files.com/api/rest/v1/message_comment_reactions/{id}.json \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/message_comment_reactions/{id}.xml \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::MessageCommentReaction.find(id)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\MessageCommentReaction::find($id);

Example Response

{
  "id": 1,
  "emoji": "👍"
}

<?xml version="1.0" encoding="UTF-8"?>
<message-comment-reaction>
  <id type="integer">1</id>
  <emoji>👍</emoji>
</message-comment-reaction>

HTTPS Request

GET /message_comment_reactions/{id}

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
id int64 Required	Message Comment Reaction ID.

Create Message Comment Reaction

Example Request

curl https://app.files.com/api/rest/v1/message_comment_reactions.json \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"user_id":1,"emoji":"emoji"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/message_comment_reactions.xml \
  -X POST \
  -H 'Content-Type: application/xml' \
  -d '<message-comment-reaction>
       <user_id type="integer">1</user_id>
       <emoji>emoji</emoji>
     </message-comment-reaction>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::MessageCommentReaction.create(
  user_id: 1, 
  emoji: "emoji"
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\MessageCommentReaction::create(array(
  'user_id' => 1, 
  'emoji' => "emoji"
));

Example Response

{
  "id": 1,
  "emoji": "👍"
}

<?xml version="1.0" encoding="UTF-8"?>
<message-comment-reaction>
  <id type="integer">1</id>
  <emoji>👍</emoji>
</message-comment-reaction>

HTTPS Request

POST /message_comment_reactions

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
user_id int64	User ID. Provide a value of `0` to operate the current session's user.
emoji string Required	Emoji to react with.

Delete Message Comment Reaction

Example Request

curl https://app.files.com/api/rest/v1/message_comment_reactions/{id}.json \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/message_comment_reactions/{id}.xml \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

message_comment_reaction = Files::MessageCommentReaction.find(id)
message_comment_reaction.delete

\Files\Files::setApiKey('YOUR_API_KEY');

$message_comment_reaction = \Files\MessageCommentReaction->find(1);
$message_comment_reaction->delete();

Example Response

No response.

No response.

HTTPS Request

DELETE /message_comment_reactions/{id}

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
id int64 Required	Message Comment Reaction ID.

Message Reactions

A message reaction represents a reaction emoji made by a user on a message.

The MessageReaction object

Example MessageReaction Object

{
  "id": 1,
  "emoji": "👍"
}

<?xml version="1.0" encoding="UTF-8"?>
<message-reaction>
  <id type="integer">1</id>
  <emoji>👍</emoji>
</message-reaction>

Attribute	Description
id int64	Reaction ID
emoji string	Emoji used in the reaction.
user_id int64	User ID. Provide a value of `0` to operate the current session's user.

List Message Reactions

Example Request

curl "https://app.files.com/api/rest/v1/message_reactions.json?user_id=1&page=1&per_page=1&message_id=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/message_reactions.xml?user_id=1&page=1&per_page=1&message_id=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::MessageReaction.list(
  user_id: 1, 
  page: 1, 
  per_page: 1, 
  message_id: 1
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\MessageReaction::list(array(
  'user_id' => 1, 
  'page' => 1, 
  'per_page' => 1, 
  'message_id' => 1
));

Example Response

[
  {
    "id": 1,
    "emoji": "👍"
  }
]

<?xml version="1.0" encoding="UTF-8"?>
<message-reactions type="array">
  <message-reaction>
    <id type="integer">1</id>
    <emoji>👍</emoji>
  </message-reaction>
</message-reactions>

HTTPS Request

GET /message_reactions

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
user_id int64	User ID. Provide a value of `0` to operate the current session's user.
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Deprecated: If set to `count` returns a count of matching records rather than the records themselves.
message_id int64 Required	Message to return reactions for.

Show Message Reaction

Example Request

curl https://app.files.com/api/rest/v1/message_reactions/{id}.json \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/message_reactions/{id}.xml \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::MessageReaction.find(id)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\MessageReaction::find($id);

Example Response

{
  "id": 1,
  "emoji": "👍"
}

<?xml version="1.0" encoding="UTF-8"?>
<message-reaction>
  <id type="integer">1</id>
  <emoji>👍</emoji>
</message-reaction>

HTTPS Request

GET /message_reactions/{id}

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
id int64 Required	Message Reaction ID.

Create Message Reaction

Example Request

curl https://app.files.com/api/rest/v1/message_reactions.json \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"user_id":1,"emoji":"emoji"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/message_reactions.xml \
  -X POST \
  -H 'Content-Type: application/xml' \
  -d '<message-reaction>
       <user_id type="integer">1</user_id>
       <emoji>emoji</emoji>
     </message-reaction>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::MessageReaction.create(
  user_id: 1, 
  emoji: "emoji"
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\MessageReaction::create(array(
  'user_id' => 1, 
  'emoji' => "emoji"
));

Example Response

{
  "id": 1,
  "emoji": "👍"
}

<?xml version="1.0" encoding="UTF-8"?>
<message-reaction>
  <id type="integer">1</id>
  <emoji>👍</emoji>
</message-reaction>

HTTPS Request

POST /message_reactions

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
user_id int64	User ID. Provide a value of `0` to operate the current session's user.
emoji string Required	Emoji to react with.

Delete Message Reaction

Example Request

curl https://app.files.com/api/rest/v1/message_reactions/{id}.json \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/message_reactions/{id}.xml \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

message_reaction = Files::MessageReaction.find(id)
message_reaction.delete

\Files\Files::setApiKey('YOUR_API_KEY');

$message_reaction = \Files\MessageReaction->find(1);
$message_reaction->delete();

Example Response

No response.

No response.

HTTPS Request

DELETE /message_reactions/{id}

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
id int64 Required	Message Reaction ID.

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,
  "path": "path",
  "group_id": 1,
  "group_name": "",
  "notify_user_actions": true,
  "notify_on_copy": true,
  "send_interval": "fifteen_minutes",
  "unsubscribed": true,
  "unsubscribed_reason": "",
  "user_id": 1,
  "username": "User",
  "suppressed_email": "suppressed_email"
}

<?xml version="1.0" encoding="UTF-8"?>
<notification>
  <id type="integer">1</id>
  <path>path</path>
  <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>
  <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>
  <suppressed_email>suppressed_email</suppressed_email>
</notification>

Attribute	Description
id int64	Notification ID
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.
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
send_interval string	The time interval that notifications are aggregated to Possible values: `five_minutes`, `fifteen_minutes`, `hourly`, `daily`
unsubscribed boolean	Is the user unsubscribed from this notification?
unsubscribed_reason string	The reason that the user unsubscribed Possible values: `none`, `unsubscribe_link_clicked`, `mail_bounced`, `mail_marked_as_spam`
user_id int64	Notification user ID
username string	Notification username
suppressed_email boolean	If true, it means that the recipient at this user's email address has manually unsubscribed from all emails, or had their email "hard bounce", which means that we are unable to send mail to this user's current email address. Notifications will resume if the user changes their email address.

List Notifications

Example Request

curl "https://app.files.com/api/rest/v1/notifications.json?user_id=1&page=1&per_page=1&group_id=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/notifications.xml?user_id=1&page=1&per_page=1&group_id=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::Notification.list(
  user_id: 1, 
  page: 1, 
  per_page: 1, 
  group_id: 1
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\Notification::list(array(
  'user_id' => 1, 
  'page' => 1, 
  'per_page' => 1, 
  'group_id' => 1
));

Example Response

[
  {
    "id": 1,
    "path": "path",
    "group_id": 1,
    "group_name": "",
    "notify_user_actions": true,
    "notify_on_copy": true,
    "send_interval": "fifteen_minutes",
    "unsubscribed": true,
    "unsubscribed_reason": "",
    "user_id": 1,
    "username": "User",
    "suppressed_email": "suppressed_email"
  }
]

<?xml version="1.0" encoding="UTF-8"?>
<notifications type="array">
  <notification>
    <id type="integer">1</id>
    <path>path</path>
    <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>
    <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>
    <suppressed_email>suppressed_email</suppressed_email>
  </notification>
</notifications>

HTTPS Request

GET /notifications

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
user_id int64	Show notifications for this User ID.
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Deprecated: If set to `count` returns a count of matching records rather than the records themselves.
group_id int64	Show notifications for this Group ID.

Show Notification

Example Request

curl https://app.files.com/api/rest/v1/notifications/{id}.json \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/notifications/{id}.xml \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::Notification.find(id)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\Notification::find($id);

Example Response

{
  "id": 1,
  "path": "path",
  "group_id": 1,
  "group_name": "",
  "notify_user_actions": true,
  "notify_on_copy": true,
  "send_interval": "fifteen_minutes",
  "unsubscribed": true,
  "unsubscribed_reason": "",
  "user_id": 1,
  "username": "User",
  "suppressed_email": "suppressed_email"
}

<?xml version="1.0" encoding="UTF-8"?>
<notification>
  <id type="integer">1</id>
  <path>path</path>
  <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>
  <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>
  <suppressed_email>suppressed_email</suppressed_email>
</notification>

HTTPS Request

GET /notifications/{id}

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
id int64 Required	Notification ID.

Create Notification

Example Request

curl https://app.files.com/api/rest/v1/notifications.json \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"user_id":1,"notify_on_copy":true,"notify_user_actions":true,"send_interval":"daily","group_id":1,"path":"path","username":"User"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/notifications.xml \
  -X POST \
  -H 'Content-Type: application/xml' \
  -d '<notification>
       <user_id type="integer">1</user_id>
       <notify_on_copy type="boolean">true</notify_on_copy>
       <notify_user_actions type="boolean">true</notify_user_actions>
       <send_interval>daily</send_interval>
       <group_id type="integer">1</group_id>
       <path>path</path>
       <username>User</username>
     </notification>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::Notification.create(
  user_id: 1, 
  notify_on_copy: true, 
  notify_user_actions: true, 
  send_interval: "daily", 
  group_id: 1, 
  path: "path", 
  username: "User"
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\Notification::create(array(
  'user_id' => 1, 
  'notify_on_copy' => true, 
  'notify_user_actions' => true, 
  'send_interval' => "daily", 
  'group_id' => 1, 
  'path' => "path", 
  'username' => "User"
));

Example Response

{
  "id": 1,
  "path": "path",
  "group_id": 1,
  "group_name": "",
  "notify_user_actions": true,
  "notify_on_copy": true,
  "send_interval": "fifteen_minutes",
  "unsubscribed": true,
  "unsubscribed_reason": "",
  "user_id": 1,
  "username": "User",
  "suppressed_email": "suppressed_email"
}

<?xml version="1.0" encoding="UTF-8"?>
<notification>
  <id type="integer">1</id>
  <path>path</path>
  <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>
  <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>
  <suppressed_email>suppressed_email</suppressed_email>
</notification>

HTTPS Request

POST /notifications

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
user_id int64	The id of the user 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
send_interval string	The time interval that notifications are aggregated by. Can be `five_minutes`, `fifteen_minutes`, `hourly`, or `daily`.
group_id int64	The ID of the group to notify. Provide `user_id`, `username` or `group_id`.
path string	Path
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 PATCH \
  -H 'Content-Type: application/json' \
  -d '{"notify_on_copy":true,"notify_user_actions":true,"send_interval":"daily"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/notifications/{id}.xml \
  -X PATCH \
  -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>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

notification = Files::Notification.find(id)
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,
  "path": "path",
  "group_id": 1,
  "group_name": "",
  "notify_user_actions": true,
  "notify_on_copy": true,
  "send_interval": "fifteen_minutes",
  "unsubscribed": true,
  "unsubscribed_reason": "",
  "user_id": 1,
  "username": "User",
  "suppressed_email": "suppressed_email"
}

<?xml version="1.0" encoding="UTF-8"?>
<notification>
  <id type="integer">1</id>
  <path>path</path>
  <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>
  <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>
  <suppressed_email>suppressed_email</suppressed_email>
</notification>

HTTPS Request

PATCH /notifications/{id}

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
id int64 Required	Notification 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
send_interval string	The time interval that notifications are aggregated by. Can be `five_minutes`, `fifteen_minutes`, `hourly`, or `daily`.

Delete Notification

Example Request

curl https://app.files.com/api/rest/v1/notifications/{id}.json \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/notifications/{id}.xml \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

notification = Files::Notification.find(id)
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}

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
id int64 Required	Notification ID.

Permissions

Permission objects represent the grant of permissions to a user or group.

They are specific to a path and can be either recursive or nonrecursive into the subfolders of that path.

The Permission object

Example Permission Object

{
  "id": 1,
  "path": "",
  "user_id": 1,
  "username": "Sser",
  "group_id": 1,
  "group_name": "",
  "permission": "full",
  "recursive": true
}

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

Attribute	Description
id int64	Permission ID
path string	Folder path This must be slash-delimited, but it must neither start nor end with a slash. Maximum of 5000 characters.
user_id int64	User ID
username string	User's username
group_id int64	Group ID
group_name string	Group name if applicable
permission string	Permission type Possible values: `full`, `readonly`, `writeonly`, `previewonly`, `history`, `admin`
recursive boolean	Does this permission apply to subfolders?

List Permissions

Example Request

curl "https://app.files.com/api/rest/v1/permissions.json?page=1&per_page=1&group_id=1&user_id=1&include_groups=true" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/permissions.xml?page=1&per_page=1&group_id=1&user_id=1&include_groups=true" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::Permission.list(path, 
  page: 1, 
  per_page: 1, 
  group_id: 1, 
  user_id: 1, 
  include_groups: true
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\Permission::list($path, array(
  'page' => 1, 
  'per_page' => 1, 
  'group_id' => 1, 
  'user_id' => 1, 
  'include_groups' => true
));

Example Response

[
  {
    "id": 1,
    "path": "",
    "user_id": 1,
    "username": "Sser",
    "group_id": 1,
    "group_name": "",
    "permission": "full",
    "recursive": true
  }
]

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

HTTPS Request

GET /permissions

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Deprecated: If set to `count` returns a count of matching records rather than the records themselves.
path string	Permission path. If provided, will scope permissions to this path.
group_id string	Group ID. If provided, will scope permissions to this group.
user_id string	User ID. If provided, will scope permissions to this user.
include_groups boolean	If searching by user or group, also include user's permissions that are inherited from its groups?

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"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

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>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::Permission.create(path, 
  group_id: 1, 
  permission: "full", 
  recursive: true, 
  user_id: 1, 
  username: "Sser"
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\Permission::create($path, array(
  'group_id' => 1, 
  'permission' => "full", 
  'recursive' => true, 
  'user_id' => 1, 
  'username' => "Sser"
));

Example Response

{
  "id": 1,
  "path": "",
  "user_id": 1,
  "username": "Sser",
  "group_id": 1,
  "group_name": "",
  "permission": "full",
  "recursive": true
}

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

HTTPS Request

POST /permissions

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
group_id int64	Group ID
path string	Folder path
permission string	Permission type. Can be `admin`, `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 \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/permissions/{id}.xml \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::Permission.delete(id)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\Permission::delete($id);

Example Response

No response.

No response.

HTTPS Request

DELETE /permissions/{id}

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
id int64 Required	Permission ID.

Projects

Projects are associated with a folder and add project management features to that folder.

The Project object

Example Project Object

{
  "id": 1,
  "global_access": "none"
}

<?xml version="1.0" encoding="UTF-8"?>
<project>
  <id type="integer">1</id>
  <global_access>none</global_access>
</project>

Attribute	Description
id int64	Project ID
global_access string	Global access settings Possible values: `none`, `anyone_with_read`, `anyone_with_full`

List Projects

Example Request

curl "https://app.files.com/api/rest/v1/projects.json?page=1&per_page=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/projects.xml?page=1&per_page=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::Project.list(
  page: 1, 
  per_page: 1
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\Project::list(array(
  'page' => 1, 
  'per_page' => 1
));

Example Response

[
  {
    "id": 1,
    "global_access": "none"
  }
]

<?xml version="1.0" encoding="UTF-8"?>
<projects type="array">
  <project>
    <id type="integer">1</id>
    <global_access>none</global_access>
  </project>
</projects>

HTTPS Request

GET /projects

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Request Parameters

Parameter	Description
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Deprecated: If set to `count` returns a count of matching records rather than the records themselves.

Show Project

Example Request

curl https://app.files.com/api/rest/v1/projects/{id}.json \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/projects/{id}.xml \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::Project.find(id)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\Project::find($id);

Example Response

{
  "id": 1,
  "global_access": "none"
}

<?xml version="1.0" encoding="UTF-8"?>
<project>
  <id type="integer">1</id>
  <global_access>none</global_access>
</project>

HTTPS Request

GET /projects/{id}

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Request Parameters

Parameter	Description
id int64 Required	Project ID.

Create Project

Example Request

curl https://app.files.com/api/rest/v1/projects.json \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"global_access":"global_access"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/projects.xml \
  -X POST \
  -H 'Content-Type: application/xml' \
  -d '<project>
       <global_access>global_access</global_access>
     </project>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::Project.create(
  global_access: "global_access"
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\Project::create(array(
  'global_access' => "global_access"
));

Example Response

{
  "id": 1,
  "global_access": "none"
}

<?xml version="1.0" encoding="UTF-8"?>
<project>
  <id type="integer">1</id>
  <global_access>none</global_access>
</project>

HTTPS Request

POST /projects

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Request Parameters

Parameter	Description
global_access string Required	Global permissions. Can be: `none`, `anyone_with_read`, `anyone_with_full`.

Update Project

Example Request

curl https://app.files.com/api/rest/v1/projects/{id}.json \
  -X PATCH \
  -H 'Content-Type: application/json' \
  -d '{"global_access":"global_access"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/projects/{id}.xml \
  -X PATCH \
  -H 'Content-Type: application/xml' \
  -d '<project>
       <global_access>global_access</global_access>
     </project>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

project = Files::Project.find(id)
project.update(
  global_access: "global_access"
)

\Files\Files::setApiKey('YOUR_API_KEY');

$project = \Files\Project->find(1);
$project->update(array(
  'global_access' => "global_access"
));

Example Response

{
  "id": 1,
  "global_access": "none"
}

<?xml version="1.0" encoding="UTF-8"?>
<project>
  <id type="integer">1</id>
  <global_access>none</global_access>
</project>

HTTPS Request

PATCH /projects/{id}

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Request Parameters

Parameter	Description
id int64 Required	Project ID.
global_access string Required	Global permissions. Can be: `none`, `anyone_with_read`, `anyone_with_full`.

Delete Project

Example Request

curl https://app.files.com/api/rest/v1/projects/{id}.json \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/projects/{id}.xml \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

project = Files::Project.find(id)
project.delete

\Files\Files::setApiKey('YOUR_API_KEY');

$project = \Files\Project->find(1);
$project->delete();

Example Response

No response.

No response.

HTTPS Request

DELETE /projects/{id}

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Request Parameters

Parameter	Description
id int64 Required	Project ID.

Public Keys

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,
  "title": "My public key",
  "created_at": "2000-01-01T01:00:00Z",
  "fingerprint": "43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8"
}

<?xml version="1.0" encoding="UTF-8"?>
<public-key>
  <id type="integer">1</id>
  <title>My public key</title>
  <created_at>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>
</public-key>

Attribute	Description
id int64	Public key ID
title string	Public key title
created_at date-time	Public key created at date/time
fingerprint string	Public key fingerprint
user_id int64	User ID. Provide a value of `0` to operate the current session's user.
public_key string	Actual contents of SSH key.

List Public Keys

Example Request

curl "https://app.files.com/api/rest/v1/public_keys.json?user_id=1&page=1&per_page=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/public_keys.xml?user_id=1&page=1&per_page=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::PublicKey.list(
  user_id: 1, 
  page: 1, 
  per_page: 1
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\PublicKey::list(array(
  'user_id' => 1, 
  'page' => 1, 
  'per_page' => 1
));

Example Response

[
  {
    "id": 1,
    "title": "My public key",
    "created_at": "2000-01-01T01:00:00Z",
    "fingerprint": "43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8"
  }
]

<?xml version="1.0" encoding="UTF-8"?>
<public-keys type="array">
  <public-key>
    <id type="integer">1</id>
    <title>My public key</title>
    <created_at>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>
  </public-key>
</public-keys>

HTTPS Request

GET /public_keys

Authentication Required

Not available to user API keys or sessions from users that are marked as Shared/Bot users.

Request Parameters

Parameter	Description
user_id int64	User ID. Provide a value of `0` to operate the current session's user.
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Deprecated: If set to `count` returns a count of matching records rather than the records themselves.

Show Public Key

Example Request

curl https://app.files.com/api/rest/v1/public_keys/{id}.json \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/public_keys/{id}.xml \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::PublicKey.find(id)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\PublicKey::find($id);

Example Response

{
  "id": 1,
  "title": "My public key",
  "created_at": "2000-01-01T01:00:00Z",
  "fingerprint": "43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8"
}

<?xml version="1.0" encoding="UTF-8"?>
<public-key>
  <id type="integer">1</id>
  <title>My public key</title>
  <created_at>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>
</public-key>

HTTPS Request

GET /public_keys/{id}

Authentication Required

Not available to user API keys or sessions from users that are marked as Shared/Bot users.

Request Parameters

Parameter	Description
id int64 Required	Public Key ID.

Create Public Key

Example Request

curl https://app.files.com/api/rest/v1/public_keys.json \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"user_id":1,"title":"My Main Key","public_key":"public_key"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/public_keys.xml \
  -X POST \
  -H 'Content-Type: application/xml' \
  -d '<public-key>
       <user_id type="integer">1</user_id>
       <title>My Main Key</title>
       <public_key>public_key</public_key>
     </public-key>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::PublicKey.create(
  user_id: 1, 
  title: "My Main Key", 
  public_key: "public_key"
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\PublicKey::create(array(
  'user_id' => 1, 
  'title' => "My Main Key", 
  'public_key' => "public_key"
));

Example Response

{
  "id": 1,
  "title": "My public key",
  "created_at": "2000-01-01T01:00:00Z",
  "fingerprint": "43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8"
}

<?xml version="1.0" encoding="UTF-8"?>
<public-key>
  <id type="integer">1</id>
  <title>My public key</title>
  <created_at>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>
</public-key>

HTTPS Request

POST /public_keys

Authentication Required

Not available to user API keys or sessions from users that are marked as Shared/Bot users.

Request Parameters

Parameter	Description
user_id int64	User ID. Provide a value of `0` to operate the current session's user.
title string Required	Internal reference for key.
public_key string Required	Actual contents of SSH key.

Update Public Key

Example Request

curl https://app.files.com/api/rest/v1/public_keys/{id}.json \
  -X PATCH \
  -H 'Content-Type: application/json' \
  -d '{"title":"My Main Key"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/public_keys/{id}.xml \
  -X PATCH \
  -H 'Content-Type: application/xml' \
  -d '<public-key>
       <title>My Main Key</title>
     </public-key>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

public_key = Files::PublicKey.find(id)
public_key.update(
  title: "My Main Key"
)

\Files\Files::setApiKey('YOUR_API_KEY');

$public_key = \Files\PublicKey->find(1);
$public_key->update(array(
  'title' => "My Main Key"
));

Example Response

{
  "id": 1,
  "title": "My public key",
  "created_at": "2000-01-01T01:00:00Z",
  "fingerprint": "43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8"
}

<?xml version="1.0" encoding="UTF-8"?>
<public-key>
  <id type="integer">1</id>
  <title>My public key</title>
  <created_at>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>
</public-key>

HTTPS Request

PATCH /public_keys/{id}

Authentication Required

Not available to user API keys or sessions from users that are marked as Shared/Bot users.

Request Parameters

Parameter	Description
id int64 Required	Public Key ID.
title string Required	Internal reference for key.

Delete Public Key

Example Request

curl https://app.files.com/api/rest/v1/public_keys/{id}.json \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/public_keys/{id}.xml \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

public_key = Files::PublicKey.find(id)
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}

Authentication Required

Not available to user API keys or sessions from users that are marked as Shared/Bot users.

Request Parameters

Parameter	Description
id int64 Required	Public Key ID.

Remote Servers

Remote servers are used with the remote_server_sync Behavior.

Remote Servers can be either an FTP server, SFTP server, S3 bucket, Google Cloud Storage, Wasabi, Backblaze B2 Cloud Storage, or WebDAV. Other remote server types, such as Box, Dropbox, OneDrive, Google Drive, and Azure Blob Storage, are coming soon.

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.

Google Cloud Storage requires that you specify google_cloud_storage_bucket, google_cloud_storage_project_id, and google_cloud_storage_credentials_json.

Wasabi requires wasabi_bucket, wasabi_region, wasabi_access_key, and wasabi_secret_key.

Backblaze B2 Cloud Storage backblaze_b2_bucket, backblaze_b2_s3_endpoint, backblaze_b2_application_key, and backblaze_b2_key_id. (Requires S3 Compatible API) See https://help.backblaze.com/hc/en-us/articles/360047425453

WebDAV Servers require that you specify their hostname, username, and password.

The RemoteServer object

Example RemoteServer Object

{
  "id": 1,
  "authentication_method": "password",
  "hostname": "remote-server.com",
  "name": "My Remote server",
  "port": 1,
  "max_connections": 1,
  "s3_bucket": "my-bucket",
  "s3_region": "us-east-1",
  "server_certificate": "[certificate]",
  "server_type": "s3",
  "ssl": "always",
  "username": "user",
  "google_cloud_storage_bucket": "my-bucket",
  "google_cloud_storage_project_id": "my-project",
  "backblaze_b2_s3_endpoint": "s3.us-west-001.backblazeb2.com",
  "backblaze_b2_bucket": "my-bucket",
  "wasabi_bucket": "us-west-1",
  "wasabi_region": "my-bucket"
}

<?xml version="1.0" encoding="UTF-8"?>
<remote-server>
  <id type="integer">1</id>
  <authentication_method>password</authentication_method>
  <hostname>remote-server.com</hostname>
  <name>My Remote server</name>
  <port type="integer">1</port>
  <max_connections type="integer">1</max_connections>
  <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>
  <google_cloud_storage_bucket>my-bucket</google_cloud_storage_bucket>
  <google_cloud_storage_project_id>my-project</google_cloud_storage_project_id>
  <backblaze_b2_s3_endpoint>s3.us-west-001.backblazeb2.com</backblaze_b2_s3_endpoint>
  <backblaze_b2_bucket>my-bucket</backblaze_b2_bucket>
  <wasabi_bucket>us-west-1</wasabi_bucket>
  <wasabi_region>my-bucket</wasabi_region>
</remote-server>

Attribute	Description
id int64	Remote server ID
authentication_method string	Type of authentication method
hostname string	Hostname or IP address
name string	Internal name for your reference
port int64	Port for remote server. Not needed for S3.
max_connections int64	Max number of parallel connections. Ignored for S3 connections (we will parallelize these as much as possible).
s3_bucket string	S3 bucket name
s3_region string	S3 region
server_certificate string	Remote server certificate Possible values: `require_match`, `allow_any`
server_type string	Remote server type. Possible values: `ftp`, `sftp`, `s3`, `google_cloud_storage`, `webdav`, `wasabi`, `backblaze_b2`
ssl string	Should we require SSL? Possible values: `if_available`, `require`, `require_implicit`, `never`
username string	Remote server username. Not needed for S3 buckets.
google_cloud_storage_bucket string	Google Cloud Storage bucket name
google_cloud_storage_project_id string	Google Cloud Project ID
backblaze_b2_s3_endpoint string	Backblaze B2 Cloud Storage S3 Endpoint
backblaze_b2_bucket string	Backblaze B2 Cloud Storage Bucket name
wasabi_bucket string	Wasabi region
wasabi_region string	Wasabi Bucket name
aws_access_key string	AWS Access Key.
aws_secret_key string	AWS secret key.
password string	Password if needed.
private_key string	Private key if needed.
google_cloud_storage_credentials_json string	A JSON file that contains the private key. To generate see https://cloud.google.com/storage/docs/json_api/v1/how-tos/authorizing#APIKey
wasabi_access_key string	Wasabi access key.
wasabi_secret_key string	Wasabi secret key.
backblaze_b2_key_id string	Backblaze B2 Cloud Storage keyID.
backblaze_b2_application_key string	Backblaze B2 Cloud Storage applicationKey.

List Remote Servers

Example Request

curl "https://app.files.com/api/rest/v1/remote_servers.json?page=1&per_page=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/remote_servers.xml?page=1&per_page=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::RemoteServer.list(
  page: 1, 
  per_page: 1
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\RemoteServer::list(array(
  'page' => 1, 
  'per_page' => 1
));

Example Response

[
  {
    "id": 1,
    "authentication_method": "password",
    "hostname": "remote-server.com",
    "name": "My Remote server",
    "port": 1,
    "max_connections": 1,
    "s3_bucket": "my-bucket",
    "s3_region": "us-east-1",
    "server_certificate": "[certificate]",
    "server_type": "s3",
    "ssl": "always",
    "username": "user",
    "google_cloud_storage_bucket": "my-bucket",
    "google_cloud_storage_project_id": "my-project",
    "backblaze_b2_s3_endpoint": "s3.us-west-001.backblazeb2.com",
    "backblaze_b2_bucket": "my-bucket",
    "wasabi_bucket": "us-west-1",
    "wasabi_region": "my-bucket"
  }
]

<?xml version="1.0" encoding="UTF-8"?>
<remote-servers type="array">
  <remote-server>
    <id type="integer">1</id>
    <authentication_method>password</authentication_method>
    <hostname>remote-server.com</hostname>
    <name>My Remote server</name>
    <port type="integer">1</port>
    <max_connections type="integer">1</max_connections>
    <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>
    <google_cloud_storage_bucket>my-bucket</google_cloud_storage_bucket>
    <google_cloud_storage_project_id>my-project</google_cloud_storage_project_id>
    <backblaze_b2_s3_endpoint>s3.us-west-001.backblazeb2.com</backblaze_b2_s3_endpoint>
    <backblaze_b2_bucket>my-bucket</backblaze_b2_bucket>
    <wasabi_bucket>us-west-1</wasabi_bucket>
    <wasabi_region>my-bucket</wasabi_region>
  </remote-server>
</remote-servers>

HTTPS Request

GET /remote_servers

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Request Parameters

Parameter	Description
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Deprecated: If set to `count` returns a count of matching records rather than the records themselves.

Show Remote Server

Example Request

curl https://app.files.com/api/rest/v1/remote_servers/{id}.json \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/remote_servers/{id}.xml \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::RemoteServer.find(id)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\RemoteServer::find($id);

Example Response

{
  "id": 1,
  "authentication_method": "password",
  "hostname": "remote-server.com",
  "name": "My Remote server",
  "port": 1,
  "max_connections": 1,
  "s3_bucket": "my-bucket",
  "s3_region": "us-east-1",
  "server_certificate": "[certificate]",
  "server_type": "s3",
  "ssl": "always",
  "username": "user",
  "google_cloud_storage_bucket": "my-bucket",
  "google_cloud_storage_project_id": "my-project",
  "backblaze_b2_s3_endpoint": "s3.us-west-001.backblazeb2.com",
  "backblaze_b2_bucket": "my-bucket",
  "wasabi_bucket": "us-west-1",
  "wasabi_region": "my-bucket"
}

<?xml version="1.0" encoding="UTF-8"?>
<remote-server>
  <id type="integer">1</id>
  <authentication_method>password</authentication_method>
  <hostname>remote-server.com</hostname>
  <name>My Remote server</name>
  <port type="integer">1</port>
  <max_connections type="integer">1</max_connections>
  <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>
  <google_cloud_storage_bucket>my-bucket</google_cloud_storage_bucket>
  <google_cloud_storage_project_id>my-project</google_cloud_storage_project_id>
  <backblaze_b2_s3_endpoint>s3.us-west-001.backblazeb2.com</backblaze_b2_s3_endpoint>
  <backblaze_b2_bucket>my-bucket</backblaze_b2_bucket>
  <wasabi_bucket>us-west-1</wasabi_bucket>
  <wasabi_region>my-bucket</wasabi_region>
</remote-server>

HTTPS Request

GET /remote_servers/{id}

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

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 '{"hostname":"remote-server.com","name":"My Remote server","max_connections":1,"port":1,"s3_bucket":"my-bucket","s3_region":"us-east-1","server_certificate":"[certificate]","server_type":"s3","ssl":"always","username":"user","google_cloud_storage_bucket":"my-bucket","google_cloud_storage_project_id":"my-project","backblaze_b2_bucket":"my-bucket","backblaze_b2_s3_endpoint":"s3.us-west-001.backblazeb2.com","wasabi_bucket":"us-west-1","wasabi_region":"my-bucket"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/remote_servers.xml \
  -X POST \
  -H 'Content-Type: application/xml' \
  -d '<remote-server>
       <hostname>remote-server.com</hostname>
       <name>My Remote server</name>
       <max_connections type="integer">1</max_connections>
       <port type="integer">1</port>
       <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>
       <google_cloud_storage_bucket>my-bucket</google_cloud_storage_bucket>
       <google_cloud_storage_project_id>my-project</google_cloud_storage_project_id>
       <backblaze_b2_bucket>my-bucket</backblaze_b2_bucket>
       <backblaze_b2_s3_endpoint>s3.us-west-001.backblazeb2.com</backblaze_b2_s3_endpoint>
       <wasabi_bucket>us-west-1</wasabi_bucket>
       <wasabi_region>my-bucket</wasabi_region>
     </remote-server>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::RemoteServer.create(
  hostname: "remote-server.com", 
  name: "My Remote server", 
  max_connections: 1, 
  port: 1, 
  s3_bucket: "my-bucket", 
  s3_region: "us-east-1", 
  server_certificate: "[certificate]", 
  server_type: "s3", 
  ssl: "always", 
  username: "user", 
  google_cloud_storage_bucket: "my-bucket", 
  google_cloud_storage_project_id: "my-project", 
  backblaze_b2_bucket: "my-bucket", 
  backblaze_b2_s3_endpoint: "s3.us-west-001.backblazeb2.com", 
  wasabi_bucket: "us-west-1", 
  wasabi_region: "my-bucket"
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\RemoteServer::create(array(
  'hostname' => "remote-server.com", 
  'name' => "My Remote server", 
  'max_connections' => 1, 
  'port' => 1, 
  's3_bucket' => "my-bucket", 
  's3_region' => "us-east-1", 
  'server_certificate' => "[certificate]", 
  'server_type' => "s3", 
  'ssl' => "always", 
  'username' => "user", 
  'google_cloud_storage_bucket' => "my-bucket", 
  'google_cloud_storage_project_id' => "my-project", 
  'backblaze_b2_bucket' => "my-bucket", 
  'backblaze_b2_s3_endpoint' => "s3.us-west-001.backblazeb2.com", 
  'wasabi_bucket' => "us-west-1", 
  'wasabi_region' => "my-bucket"
));

Example Response

{
  "id": 1,
  "authentication_method": "password",
  "hostname": "remote-server.com",
  "name": "My Remote server",
  "port": 1,
  "max_connections": 1,
  "s3_bucket": "my-bucket",
  "s3_region": "us-east-1",
  "server_certificate": "[certificate]",
  "server_type": "s3",
  "ssl": "always",
  "username": "user",
  "google_cloud_storage_bucket": "my-bucket",
  "google_cloud_storage_project_id": "my-project",
  "backblaze_b2_s3_endpoint": "s3.us-west-001.backblazeb2.com",
  "backblaze_b2_bucket": "my-bucket",
  "wasabi_bucket": "us-west-1",
  "wasabi_region": "my-bucket"
}

<?xml version="1.0" encoding="UTF-8"?>
<remote-server>
  <id type="integer">1</id>
  <authentication_method>password</authentication_method>
  <hostname>remote-server.com</hostname>
  <name>My Remote server</name>
  <port type="integer">1</port>
  <max_connections type="integer">1</max_connections>
  <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>
  <google_cloud_storage_bucket>my-bucket</google_cloud_storage_bucket>
  <google_cloud_storage_project_id>my-project</google_cloud_storage_project_id>
  <backblaze_b2_s3_endpoint>s3.us-west-001.backblazeb2.com</backblaze_b2_s3_endpoint>
  <backblaze_b2_bucket>my-bucket</backblaze_b2_bucket>
  <wasabi_bucket>us-west-1</wasabi_bucket>
  <wasabi_region>my-bucket</wasabi_region>
</remote-server>

HTTPS Request

POST /remote_servers

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Request Parameters

Parameter	Description
aws_access_key string	AWS Access Key.
aws_secret_key string	AWS secret key.
password string	Password if needed.
private_key string	Private key if needed.
google_cloud_storage_credentials_json string	A JSON file that contains the private key. To generate see https://cloud.google.com/storage/docs/json_api/v1/how-tos/authorizing#APIKey
wasabi_access_key string	Wasabi access key.
wasabi_secret_key string	Wasabi secret key.
backblaze_b2_key_id string	Backblaze B2 Cloud Storage keyID.
backblaze_b2_application_key string	Backblaze B2 Cloud Storage applicationKey.
hostname string	Hostname or IP address
name string	Internal name for your reference
max_connections int64	Max number of parallel connections. Ignored for S3 connections (we will parallelize these as much as possible).
port int64	Port for remote server. Not needed for S3.
s3_bucket string	S3 bucket name
s3_region string	S3 region
server_certificate string	Remote server certificate Possible values: `require_match`, `allow_any`
server_type string	Remote server type. Possible values: `ftp`, `sftp`, `s3`, `google_cloud_storage`, `webdav`, `wasabi`, `backblaze_b2`
ssl string	Should we require SSL? Possible values: `if_available`, `require`, `require_implicit`, `never`
username string	Remote server username. Not needed for S3 buckets.
google_cloud_storage_bucket string	Google Cloud Storage bucket name
google_cloud_storage_project_id string	Google Cloud Project ID
backblaze_b2_bucket string	Backblaze B2 Cloud Storage Bucket name
backblaze_b2_s3_endpoint string	Backblaze B2 Cloud Storage S3 Endpoint
wasabi_bucket string	Wasabi region
wasabi_region string	Wasabi Bucket name

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 '{"hostname":"remote-server.com","name":"My Remote server","max_connections":1,"port":1,"s3_bucket":"my-bucket","s3_region":"us-east-1","server_certificate":"[certificate]","server_type":"s3","ssl":"always","username":"user","google_cloud_storage_bucket":"my-bucket","google_cloud_storage_project_id":"my-project","backblaze_b2_bucket":"my-bucket","backblaze_b2_s3_endpoint":"s3.us-west-001.backblazeb2.com","wasabi_bucket":"us-west-1","wasabi_region":"my-bucket"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/remote_servers/{id}.xml \
  -X PATCH \
  -H 'Content-Type: application/xml' \
  -d '<remote-server>
       <hostname>remote-server.com</hostname>
       <name>My Remote server</name>
       <max_connections type="integer">1</max_connections>
       <port type="integer">1</port>
       <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>
       <google_cloud_storage_bucket>my-bucket</google_cloud_storage_bucket>
       <google_cloud_storage_project_id>my-project</google_cloud_storage_project_id>
       <backblaze_b2_bucket>my-bucket</backblaze_b2_bucket>
       <backblaze_b2_s3_endpoint>s3.us-west-001.backblazeb2.com</backblaze_b2_s3_endpoint>
       <wasabi_bucket>us-west-1</wasabi_bucket>
       <wasabi_region>my-bucket</wasabi_region>
     </remote-server>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

remote_server = Files::RemoteServer.find(id)
remote_server.update(
  hostname: "remote-server.com",
  name: "My Remote server",
  max_connections: 1,
  port: 1,
  s3_bucket: "my-bucket",
  s3_region: "us-east-1",
  server_certificate: "[certificate]",
  server_type: "s3",
  ssl: "always",
  username: "user",
  google_cloud_storage_bucket: "my-bucket",
  google_cloud_storage_project_id: "my-project",
  backblaze_b2_bucket: "my-bucket",
  backblaze_b2_s3_endpoint: "s3.us-west-001.backblazeb2.com",
  wasabi_bucket: "us-west-1",
  wasabi_region: "my-bucket"
)

\Files\Files::setApiKey('YOUR_API_KEY');

$remote_server = \Files\RemoteServer->find(1);
$remote_server->update(array(
  'hostname' => "remote-server.com", 
  'name' => "My Remote server", 
  'max_connections' => 1, 
  'port' => 1, 
  's3_bucket' => "my-bucket", 
  's3_region' => "us-east-1", 
  'server_certificate' => "[certificate]", 
  'server_type' => "s3", 
  'ssl' => "always", 
  'username' => "user", 
  'google_cloud_storage_bucket' => "my-bucket", 
  'google_cloud_storage_project_id' => "my-project", 
  'backblaze_b2_bucket' => "my-bucket", 
  'backblaze_b2_s3_endpoint' => "s3.us-west-001.backblazeb2.com", 
  'wasabi_bucket' => "us-west-1", 
  'wasabi_region' => "my-bucket"
));

Example Response

{
  "id": 1,
  "authentication_method": "password",
  "hostname": "remote-server.com",
  "name": "My Remote server",
  "port": 1,
  "max_connections": 1,
  "s3_bucket": "my-bucket",
  "s3_region": "us-east-1",
  "server_certificate": "[certificate]",
  "server_type": "s3",
  "ssl": "always",
  "username": "user",
  "google_cloud_storage_bucket": "my-bucket",
  "google_cloud_storage_project_id": "my-project",
  "backblaze_b2_s3_endpoint": "s3.us-west-001.backblazeb2.com",
  "backblaze_b2_bucket": "my-bucket",
  "wasabi_bucket": "us-west-1",
  "wasabi_region": "my-bucket"
}

<?xml version="1.0" encoding="UTF-8"?>
<remote-server>
  <id type="integer">1</id>
  <authentication_method>password</authentication_method>
  <hostname>remote-server.com</hostname>
  <name>My Remote server</name>
  <port type="integer">1</port>
  <max_connections type="integer">1</max_connections>
  <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>
  <google_cloud_storage_bucket>my-bucket</google_cloud_storage_bucket>
  <google_cloud_storage_project_id>my-project</google_cloud_storage_project_id>
  <backblaze_b2_s3_endpoint>s3.us-west-001.backblazeb2.com</backblaze_b2_s3_endpoint>
  <backblaze_b2_bucket>my-bucket</backblaze_b2_bucket>
  <wasabi_bucket>us-west-1</wasabi_bucket>
  <wasabi_region>my-bucket</wasabi_region>
</remote-server>

HTTPS Request

PATCH /remote_servers/{id}

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Request Parameters

Parameter	Description
id int64 Required	Remote Server ID.
aws_access_key string	AWS Access Key.
aws_secret_key string	AWS secret key.
password string	Password if needed.
private_key string	Private key if needed.
google_cloud_storage_credentials_json string	A JSON file that contains the private key. To generate see https://cloud.google.com/storage/docs/json_api/v1/how-tos/authorizing#APIKey
wasabi_access_key string	Wasabi access key.
wasabi_secret_key string	Wasabi secret key.
backblaze_b2_key_id string	Backblaze B2 Cloud Storage keyID.
backblaze_b2_application_key string	Backblaze B2 Cloud Storage applicationKey.
hostname string	Hostname or IP address
name string	Internal name for your reference
max_connections int64	Max number of parallel connections. Ignored for S3 connections (we will parallelize these as much as possible).
port int64	Port for remote server. Not needed for S3.
s3_bucket string	S3 bucket name
s3_region string	S3 region
server_certificate string	Remote server certificate Possible values: `require_match`, `allow_any`
server_type string	Remote server type. Possible values: `ftp`, `sftp`, `s3`, `google_cloud_storage`, `webdav`, `wasabi`, `backblaze_b2`
ssl string	Should we require SSL? Possible values: `if_available`, `require`, `require_implicit`, `never`
username string	Remote server username. Not needed for S3 buckets.
google_cloud_storage_bucket string	Google Cloud Storage bucket name
google_cloud_storage_project_id string	Google Cloud Project ID
backblaze_b2_bucket string	Backblaze B2 Cloud Storage Bucket name
backblaze_b2_s3_endpoint string	Backblaze B2 Cloud Storage S3 Endpoint
wasabi_bucket string	Wasabi region
wasabi_region string	Wasabi Bucket name

Delete Remote Server

Example Request

curl https://app.files.com/api/rest/v1/remote_servers/{id}.json \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/remote_servers/{id}.xml \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

remote_server = Files::RemoteServer.find(id)
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}

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Request Parameters

Parameter	Description
id int64 Required	Remote Server ID.

Requests

A Request represents a file that should be uploaded by a specific user or group.

Requests can either be manually created and managed, or managed automatically by an Automation.

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

List Requests

Example Request

curl "https://app.files.com/api/rest/v1/requests.json?page=1&per_page=1&mine=true" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/requests.xml?page=1&per_page=1&mine=true" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::Request.list(path, 
  page: 1, 
  per_page: 1, 
  mine: true
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\Request::list($path, array(
  'page' => 1, 
  'per_page' => 1, 
  '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

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Deprecated: If set to `count` returns a count of matching records rather than the records themselves.
mine boolean	Only show requests of the current user? (Defaults to true if current user is not a site admin.)
path string	Path to show requests for. If omitted, shows all paths. Send `/` to represent the root directory.

List Requests

Example Request

curl "https://app.files.com/api/rest/v1/requests/folders/{path}?page=1&per_page=1&mine=true" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/requests/folders/{path}?page=1&per_page=1&mine=true" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

request = Files::Request.find(path)
request.folders(
  page: 1,
  per_page: 1,
  mine: true
)

\Files\Files::setApiKey('YOUR_API_KEY');

$request = \Files\Request->find(1);
$request->folders(array(
  'page' => 1, 
  'per_page' => 1, 
  '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

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Deprecated: If set to `count` returns a count of matching records rather than the records themselves.
mine boolean	Only show requests of the current user? (Defaults to true if current user is not a site admin.)
path string	Path to show requests for. If omitted, shows all paths. Send `/` to represent the root directory.

Create Request

Example Request

curl https://app.files.com/api/rest/v1/requests.json \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"destination":"destination"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/requests.xml \
  -X POST \
  -H 'Content-Type: application/xml' \
  -d '<request>
       <destination>destination</destination>
     </request>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::Request.create(path, 
  destination: "destination"
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\Request::create($path, array(
  '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

Authentication Required

Available to all authenticated keys or sessions.

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 \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/requests/{id}.xml \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::Request.delete(id)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\Request::delete($id);

Example Response

No response.

No response.

HTTPS Request

DELETE /requests/{id}

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
id int64 Required	Request ID.

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,
  "read_only": "en",
  "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>
  <read_only>en</read_only>
  <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?
read_only boolean	Is this session read only?
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)
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.
partial_session_id string	Identifier for a partially-completed login

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"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

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>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

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,
  "read_only": "en",
  "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>
  <read_only>en</read_only>
  <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

Authentication Required

No authentication required; you may call this endpoint without a key or session.

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.
partial_session_id string	Identifier for a partially-completed login

Delete user session (log out)

Example Request

curl https://app.files.com/api/rest/v1/sessions.json \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/sessions.xml \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

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

Authentication Required

No authentication required; you may call this endpoint without a key or session.

Sites

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

{
  "name": "My Site",
  "allowed_2fa_method_sms": true,
  "allowed_2fa_method_totp": true,
  "allowed_2fa_method_u2f": true,
  "allowed_2fa_method_yubi": true,
  "admin_user_id": 1,
  "allow_bundle_names": true,
  "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-01T01:00:00Z",
  "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",
  "folder_permissions_groups_only": true,
  "hipaa": true,
  "icon128": "",
  "icon16": "",
  "icon32": "",
  "icon48": "",
  "immutable_files_set_at": "2000-01-01T01:00:00Z",
  "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,
  "next_billing_amount": "",
  "next_billing_date": "Apr 20",
  "opt_out_global": true,
  "overage_notified_at": "2000-01-01T01:00:00Z",
  "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_require_unbreached": true,
  "password_requirements_apply_to_bundles": true,
  "password_validity_days": 1,
  "phone": "555-555-5555",
  "require_2fa": true,
  "require_2fa_stop_time": "2000-01-01T01:00:00Z",
  "require_2fa_user_type": "`site_admins`",
  "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.0,
  "ssl_required": true,
  "subdomain": "mysite",
  "switch_to_plan_date": "2000-01-01T01:00:00Z",
  "tls_disabled": true,
  "trial_days_left": 1,
  "trial_until": "2000-01-01T01:00:00Z",
  "updated_at": "2000-01-01T01:00:00Z",
  "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,
  "welcome_screen": "user_controlled",
  "windows_mode_ftp": true,
  "disable_users_from_inactivity_period_days": 1
}

<?xml version="1.0" encoding="UTF-8"?>
<site>
  <name>My Site</name>
  <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>
  <allow_bundle_names type="boolean">true</allow_bundle_names>
  <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>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>
  <folder_permissions_groups_only type="boolean">true</folder_permissions_groups_only>
  <hipaa type="boolean">true</hipaa>
  <icon128></icon128>
  <icon16></icon16>
  <icon32></icon32>
  <icon48></icon48>
  <immutable_files_set_at>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>
  <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>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_require_unbreached type="boolean">true</password_require_unbreached>
  <password_requirements_apply_to_bundles type="boolean">true</password_requirements_apply_to_bundles>
  <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>2000-01-01T01:00:00Z</require_2fa_stop_time>
  <require_2fa_user_type>`site_admins`</require_2fa_user_type>
  <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="float">6.0</session_expiry>
  <ssl_required type="boolean">true</ssl_required>
  <subdomain>mysite</subdomain>
  <switch_to_plan_date>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>2000-01-01T01:00:00Z</trial_until>
  <updated_at>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>
  <welcome_screen>user_controlled</welcome_screen>
  <windows_mode_ftp type="boolean">true</windows_mode_ftp>
  <disable_users_from_inactivity_period_days type="integer">1</disable_users_from_inactivity_period_days>
</site>

Attribute	Description
name string	Site name
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
allow_bundle_names boolean	Are manual Bundle names allowed?
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	Site-wide 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
folder_permissions_groups_only boolean	If true, permissions for this site must be bound to a group (not a user). Otherwise, permissions must be bound to a user.
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? Possible values: `disabled`, `add_groups`, `sync_groups`
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 Possible values: `active_directory`, `open_ldap`
ldap_user_action string	Should we sync users from LDAP server? Possible values: `disabled`, `add_users`, `sync_users`
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 Possible values: `sAMAccountName`, `userPrincipalName`
login_help_text string	Login help text
logo	Branded logo
max_prior_passwords int64	Number of prior passwords to disallow
next_billing_amount double	Next billing amount
next_billing_date string	Next billing date
opt_out_global boolean	Use servers in the USA only?
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_require_unbreached boolean	Require passwords that have not been previously breached? (see https://haveibeenpwned.com/)
password_requirements_apply_to_bundles boolean	Require bundles' passwords, and passwords for other items (inboxes, public shares, etc.) to conform to the same requirements as users' passwords?
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.
require_2fa_user_type string	What type of user is required to use two-factor authentication (when require_2fa is set to `true` for this site)? Possible values: `all`, `folder_and_site_admins`, `site_admins`
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 double	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?
welcome_screen string	Does the welcome screen appear? Possible values: `enabled`, `hidden`, `disabled`
windows_mode_ftp boolean	Does FTP user Windows emulation mode?
disable_users_from_inactivity_period_days int64	If greater than zero, users will unable to login if they do not show activity within this number of days.

Show site settings

Example Request

curl https://app.files.com/api/rest/v1/site.json \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/site.xml \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::Site.get

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\Site::get();

Example Response

{
  "name": "My Site",
  "allowed_2fa_method_sms": true,
  "allowed_2fa_method_totp": true,
  "allowed_2fa_method_u2f": true,
  "allowed_2fa_method_yubi": true,
  "admin_user_id": 1,
  "allow_bundle_names": true,
  "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-01T01:00:00Z",
  "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",
  "folder_permissions_groups_only": true,
  "hipaa": true,
  "icon128": "",
  "icon16": "",
  "icon32": "",
  "icon48": "",
  "immutable_files_set_at": "2000-01-01T01:00:00Z",
  "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,
  "next_billing_amount": "",
  "next_billing_date": "Apr 20",
  "opt_out_global": true,
  "overage_notified_at": "2000-01-01T01:00:00Z",
  "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_require_unbreached": true,
  "password_requirements_apply_to_bundles": true,
  "password_validity_days": 1,
  "phone": "555-555-5555",
  "require_2fa": true,
  "require_2fa_stop_time": "2000-01-01T01:00:00Z",
  "require_2fa_user_type": "`site_admins`",
  "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.0,
  "ssl_required": true,
  "subdomain": "mysite",
  "switch_to_plan_date": "2000-01-01T01:00:00Z",
  "tls_disabled": true,
  "trial_days_left": 1,
  "trial_until": "2000-01-01T01:00:00Z",
  "updated_at": "2000-01-01T01:00:00Z",
  "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,
  "welcome_screen": "user_controlled",
  "windows_mode_ftp": true,
  "disable_users_from_inactivity_period_days": 1
}

<?xml version="1.0" encoding="UTF-8"?>
<site>
  <name>My Site</name>
  <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>
  <allow_bundle_names type="boolean">true</allow_bundle_names>
  <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>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>
  <folder_permissions_groups_only type="boolean">true</folder_permissions_groups_only>
  <hipaa type="boolean">true</hipaa>
  <icon128></icon128>
  <icon16></icon16>
  <icon32></icon32>
  <icon48></icon48>
  <immutable_files_set_at>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>
  <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>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_require_unbreached type="boolean">true</password_require_unbreached>
  <password_requirements_apply_to_bundles type="boolean">true</password_requirements_apply_to_bundles>
  <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>2000-01-01T01:00:00Z</require_2fa_stop_time>
  <require_2fa_user_type>`site_admins`</require_2fa_user_type>
  <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="float">6.0</session_expiry>
  <ssl_required type="boolean">true</ssl_required>
  <subdomain>mysite</subdomain>
  <switch_to_plan_date>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>2000-01-01T01:00:00Z</trial_until>
  <updated_at>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>
  <welcome_screen>user_controlled</welcome_screen>
  <windows_mode_ftp type="boolean">true</windows_mode_ftp>
  <disable_users_from_inactivity_period_days type="integer">1</disable_users_from_inactivity_period_days>
</site>

HTTPS Request

GET /site

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

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","allow_bundle_names":true,"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,"folder_permissions_groups_only":true,"welcome_screen":"user_controlled","session_expiry":6.0,"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,"password_require_unbreached":true,"sftp_user_root_enabled":true,"disable_password_reset":true,"immutable_files":true,"session_pinned_by_ip":true,"bundle_password_required":true,"password_requirements_apply_to_bundles":true,"opt_out_global":true,"use_provided_modified_at":true,"custom_namespace":true,"disable_users_from_inactivity_period_days":1,"allowed_2fa_method_sms":true,"allowed_2fa_method_u2f":true,"allowed_2fa_method_totp":true,"allowed_2fa_method_yubi":true,"require_2fa":true,"require_2fa_user_type":"`site_admins`","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","icon16_delete":true,"icon32_delete":true,"icon48_delete":true,"icon128_delete":true,"logo_delete":true,"disable_2fa_with_delay":true}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

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>
       <allow_bundle_names type="boolean">true</allow_bundle_names>
       <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>
       <folder_permissions_groups_only type="boolean">true</folder_permissions_groups_only>
       <welcome_screen>user_controlled</welcome_screen>
       <session_expiry type="float">6.0</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>
       <password_require_unbreached type="boolean">true</password_require_unbreached>
       <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>
       <password_requirements_apply_to_bundles type="boolean">true</password_requirements_apply_to_bundles>
       <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>
       <disable_users_from_inactivity_period_days type="integer">1</disable_users_from_inactivity_period_days>
       <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>
       <require_2fa_user_type>`site_admins`</require_2fa_user_type>
       <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>
       <icon16_delete type="boolean">true</icon16_delete>
       <icon32_delete type="boolean">true</icon32_delete>
       <icon48_delete type="boolean">true</icon48_delete>
       <icon128_delete type="boolean">true</icon128_delete>
       <logo_delete type="boolean">true</logo_delete>
       <disable_2fa_with_delay type="boolean">true</disable_2fa_with_delay>
     </site>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::Site.update(
  name: "My Site", 
  subdomain: "mysite", 
  domain: "my-custom-domain.com", 
  email: "john.doe@files.com", 
  allow_bundle_names: true, 
  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, 
  folder_permissions_groups_only: true, 
  welcome_screen: "user_controlled", 
  session_expiry: 6.0, 
  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, 
  password_require_unbreached: true, 
  sftp_user_root_enabled: true, 
  disable_password_reset: true, 
  immutable_files: true, 
  session_pinned_by_ip: true, 
  bundle_password_required: true, 
  password_requirements_apply_to_bundles: true, 
  opt_out_global: true, 
  use_provided_modified_at: true, 
  custom_namespace: true, 
  disable_users_from_inactivity_period_days: 1, 
  allowed_2fa_method_sms: true, 
  allowed_2fa_method_u2f: true, 
  allowed_2fa_method_totp: true, 
  allowed_2fa_method_yubi: true, 
  require_2fa: true, 
  require_2fa_user_type: "`site_admins`", 
  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", 
  icon16_delete: true, 
  icon32_delete: true, 
  icon48_delete: true, 
  icon128_delete: true, 
  logo_delete: true, 
  disable_2fa_with_delay: 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", 
  'allow_bundle_names' => true, 
  '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, 
  'folder_permissions_groups_only' => true, 
  'welcome_screen' => "user_controlled", 
  'session_expiry' => 6.0, 
  '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, 
  'password_require_unbreached' => true, 
  'sftp_user_root_enabled' => true, 
  'disable_password_reset' => true, 
  'immutable_files' => true, 
  'session_pinned_by_ip' => true, 
  'bundle_password_required' => true, 
  'password_requirements_apply_to_bundles' => true, 
  'opt_out_global' => true, 
  'use_provided_modified_at' => true, 
  'custom_namespace' => true, 
  'disable_users_from_inactivity_period_days' => 1, 
  'allowed_2fa_method_sms' => true, 
  'allowed_2fa_method_u2f' => true, 
  'allowed_2fa_method_totp' => true, 
  'allowed_2fa_method_yubi' => true, 
  'require_2fa' => true, 
  'require_2fa_user_type' => "`site_admins`", 
  '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", 
  'icon16_delete' => true, 
  'icon32_delete' => true, 
  'icon48_delete' => true, 
  'icon128_delete' => true, 
  'logo_delete' => true, 
  'disable_2fa_with_delay' => true
));

Example Response

{
  "name": "My Site",
  "allowed_2fa_method_sms": true,
  "allowed_2fa_method_totp": true,
  "allowed_2fa_method_u2f": true,
  "allowed_2fa_method_yubi": true,
  "admin_user_id": 1,
  "allow_bundle_names": true,
  "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-01T01:00:00Z",
  "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",
  "folder_permissions_groups_only": true,
  "hipaa": true,
  "icon128": "",
  "icon16": "",
  "icon32": "",
  "icon48": "",
  "immutable_files_set_at": "2000-01-01T01:00:00Z",
  "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,
  "next_billing_amount": "",
  "next_billing_date": "Apr 20",
  "opt_out_global": true,
  "overage_notified_at": "2000-01-01T01:00:00Z",
  "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_require_unbreached": true,
  "password_requirements_apply_to_bundles": true,
  "password_validity_days": 1,
  "phone": "555-555-5555",
  "require_2fa": true,
  "require_2fa_stop_time": "2000-01-01T01:00:00Z",
  "require_2fa_user_type": "`site_admins`",
  "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.0,
  "ssl_required": true,
  "subdomain": "mysite",
  "switch_to_plan_date": "2000-01-01T01:00:00Z",
  "tls_disabled": true,
  "trial_days_left": 1,
  "trial_until": "2000-01-01T01:00:00Z",
  "updated_at": "2000-01-01T01:00:00Z",
  "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,
  "welcome_screen": "user_controlled",
  "windows_mode_ftp": true,
  "disable_users_from_inactivity_period_days": 1
}

<?xml version="1.0" encoding="UTF-8"?>
<site>
  <name>My Site</name>
  <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>
  <allow_bundle_names type="boolean">true</allow_bundle_names>
  <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>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>
  <folder_permissions_groups_only type="boolean">true</folder_permissions_groups_only>
  <hipaa type="boolean">true</hipaa>
  <icon128></icon128>
  <icon16></icon16>
  <icon32></icon32>
  <icon48></icon48>
  <immutable_files_set_at>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>
  <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>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_require_unbreached type="boolean">true</password_require_unbreached>
  <password_requirements_apply_to_bundles type="boolean">true</password_requirements_apply_to_bundles>
  <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>2000-01-01T01:00:00Z</require_2fa_stop_time>
  <require_2fa_user_type>`site_admins`</require_2fa_user_type>
  <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="float">6.0</session_expiry>
  <ssl_required type="boolean">true</ssl_required>
  <subdomain>mysite</subdomain>
  <switch_to_plan_date>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>2000-01-01T01:00:00Z</trial_until>
  <updated_at>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>
  <welcome_screen>user_controlled</welcome_screen>
  <windows_mode_ftp type="boolean">true</windows_mode_ftp>
  <disable_users_from_inactivity_period_days type="integer">1</disable_users_from_inactivity_period_days>
</site>

HTTPS Request

PATCH /site

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

The X-Files-Reauthentication header is required for any requests including the following parameters: email, require_2fa, require_2fa_user_type, disable_2fa_with_delay.

Request Parameters

Parameter	Description
name string	Site name
subdomain string	Site subdomain
domain string	Custom domain
email string	Main email for this site
allow_bundle_names boolean	Are manual Bundle names allowed?
bundle_expiration int64	Site-wide 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)
folder_permissions_groups_only boolean	If true, permissions for this site must be bound to a group (not a user). Otherwise, permissions must be bound to a user.
welcome_screen string	Does the welcome screen appear?
session_expiry number	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_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?
password_require_unbreached boolean	Require passwords that have not been previously breached? (see https://haveibeenpwned.com/)
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?
password_requirements_apply_to_bundles boolean	Require bundles' passwords, and passwords for other items (inboxes, public shares, etc.) to conform to the same requirements as users' passwords?
opt_out_global boolean	Use servers in the USA only?
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?
disable_users_from_inactivity_period_days int64	If greater than zero, users will unable to login if they do not show activity within this number of days.
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?
require_2fa_user_type string	What type of user is required to use two-factor authentication (when require_2fa is set to `true` for this site)?
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
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
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
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
icon16_file file
icon16_delete boolean	If true, will delete the file stored in icon16
icon32_file file
icon32_delete boolean	If true, will delete the file stored in icon32
icon48_file file
icon48_delete boolean	If true, will delete the file stored in icon48
icon128_file file
icon128_delete boolean	If true, will delete the file stored in icon128
logo_file file
logo_delete boolean	If true, will delete the file stored in logo
disable_2fa_with_delay boolean	If set to true, we will begin the process of disabling 2FA on this site.
ldap_password_change string	New LDAP password.
ldap_password_change_confirmation string	Confirm new LDAP password.
smtp_password string	Password for SMTP server.

Sso Strategies

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

{
  "protocol": "okta",
  "provider": "okta",
  "id": 1,
  "saml_provider_cert_fingerprint": "",
  "saml_provider_issuer_url": "",
  "saml_provider_metadata_url": "",
  "saml_provider_slo_target_url": "",
  "saml_provider_sso_target_url": "",
  "scim_authentication_method": "",
  "scim_username": "",
  "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>
  <protocol>okta</protocol>
  <provider>okta</provider>
  <id type="integer">1</id>
  <saml_provider_cert_fingerprint></saml_provider_cert_fingerprint>
  <saml_provider_issuer_url></saml_provider_issuer_url>
  <saml_provider_metadata_url></saml_provider_metadata_url>
  <saml_provider_slo_target_url></saml_provider_slo_target_url>
  <saml_provider_sso_target_url></saml_provider_sso_target_url>
  <scim_authentication_method></scim_authentication_method>
  <scim_username></scim_username>
  <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
protocol string	SSO Protocol Possible values: `oauth2`, `openid2`, `saml`
provider string	Provider name Possible values: `google`, `auth0`, `okta`, `atlassian`, `azure`, `box`, `dropbox`, `slack`, `ubuntu`, `onelogin`, `saml`, `idaptive`
id int64	ID
saml_provider_cert_fingerprint string	Identity provider sha256 cert fingerprint if saml_provider_metadata_url is not available.
saml_provider_issuer_url string	Identity provider issuer url
saml_provider_metadata_url string	Metadata URL for the SAML identity provider
saml_provider_slo_target_url string	Identity provider SLO endpoint
saml_provider_sso_target_url string	Identity provider SSO endpoint if saml_provider_metadata_url is not available.
scim_authentication_method string	SCIM authentication type. Possible values: `none`, `basic`, `token`
scim_username string	SCIM username.
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?page=1&per_page=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/sso_strategies.xml?page=1&per_page=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::SsoStrategy.list(
  page: 1, 
  per_page: 1
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\SsoStrategy::list(array(
  'page' => 1, 
  'per_page' => 1
));

Example Response

[
  {
    "protocol": "okta",
    "provider": "okta",
    "id": 1,
    "saml_provider_cert_fingerprint": "",
    "saml_provider_issuer_url": "",
    "saml_provider_metadata_url": "",
    "saml_provider_slo_target_url": "",
    "saml_provider_sso_target_url": "",
    "scim_authentication_method": "",
    "scim_username": "",
    "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>
    <protocol>okta</protocol>
    <provider>okta</provider>
    <id type="integer">1</id>
    <saml_provider_cert_fingerprint></saml_provider_cert_fingerprint>
    <saml_provider_issuer_url></saml_provider_issuer_url>
    <saml_provider_metadata_url></saml_provider_metadata_url>
    <saml_provider_slo_target_url></saml_provider_slo_target_url>
    <saml_provider_sso_target_url></saml_provider_sso_target_url>
    <scim_authentication_method></scim_authentication_method>
    <scim_username></scim_username>
    <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

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Request Parameters

Parameter	Description
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Deprecated: If set to `count` returns a count of matching records rather than the records themselves.

Show Sso Strategy

Example Request

curl https://app.files.com/api/rest/v1/sso_strategies/{id}.json \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/sso_strategies/{id}.xml \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::SsoStrategy.find(id)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\SsoStrategy::find($id);

Example Response

{
  "protocol": "okta",
  "provider": "okta",
  "id": 1,
  "saml_provider_cert_fingerprint": "",
  "saml_provider_issuer_url": "",
  "saml_provider_metadata_url": "",
  "saml_provider_slo_target_url": "",
  "saml_provider_sso_target_url": "",
  "scim_authentication_method": "",
  "scim_username": "",
  "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>
  <protocol>okta</protocol>
  <provider>okta</provider>
  <id type="integer">1</id>
  <saml_provider_cert_fingerprint></saml_provider_cert_fingerprint>
  <saml_provider_issuer_url></saml_provider_issuer_url>
  <saml_provider_metadata_url></saml_provider_metadata_url>
  <saml_provider_slo_target_url></saml_provider_slo_target_url>
  <saml_provider_sso_target_url></saml_provider_sso_target_url>
  <scim_authentication_method></scim_authentication_method>
  <scim_username></scim_username>
  <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}

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Request Parameters

Parameter	Description
id int64 Required	Sso Strategy ID.

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

{
  "id": 1,
  "path": "",
  "logo": "",
  "thumbnail": ""
}

<?xml version="1.0" encoding="UTF-8"?>
<style>
  <id type="integer">1</id>
  <path></path>
  <logo></logo>
  <thumbnail></thumbnail>
</style>

Attribute	Description
id int64	Style ID
path string	Folder path This must be slash-delimited, but it must neither start nor end with a slash. Maximum of 5000 characters.
logo	Logo
thumbnail	Logo thumbnail
file file	Logo for custom branding.

Show Style

Example Request

curl https://app.files.com/api/rest/v1/styles/{path} \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/styles/{path} \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::Style.list(path)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\Style::list($path);

Example Response

{
  "id": 1,
  "path": "",
  "logo": "",
  "thumbnail": ""
}

<?xml version="1.0" encoding="UTF-8"?>
<style>
  <id type="integer">1</id>
  <path></path>
  <logo></logo>
  <thumbnail></thumbnail>
</style>

HTTPS Request

GET /styles/?*path

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
path string Required	Style path.

Update Style

Example Request

curl https://app.files.com/api/rest/v1/styles/{path} \
  -X PATCH \
  -H 'Content-Type: application/json' \
  -d '{"file":"file"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/styles/{path} \
  -X PATCH \
  -H 'Content-Type: application/xml' \
  -d '<style>
       <file>file</file>
     </style>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

style = Files::Style.find(path)
style.update(
  file: "file"
)

\Files\Files::setApiKey('YOUR_API_KEY');

$style = \Files\Style->find(1);
$style->update(array(
  'file' => "file"
));

Example Response

{
  "id": 1,
  "path": "",
  "logo": "",
  "thumbnail": ""
}

<?xml version="1.0" encoding="UTF-8"?>
<style>
  <id type="integer">1</id>
  <path></path>
  <logo></logo>
  <thumbnail></thumbnail>
</style>

HTTPS Request

PATCH /styles/?*path

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

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 \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/styles/{path} \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

style = Files::Style.find(path)
style.delete

\Files\Files::setApiKey('YOUR_API_KEY');

$style = \Files\Style->find(1);
$style->delete();

Example Response

No response.

No response.

HTTPS Request

DELETE /styles/?*path

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Request Parameters

Parameter	Description
path string Required	Style path.

Usage Daily Snapshots

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

The UsageDailySnapshot object

Example UsageDailySnapshot Object

{
  "id": 1,
  "date": "2020-11-21",
  "current_storage": "65536",
  "usage_by_top_level_dir": [

  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<usage-daily-snapshot>
  <id type="integer">1</id>
  <date>2020-11-21</date>
  <current_storage>65536</current_storage>
  <usage_by_top_level_dir type="array"/>
</usage-daily-snapshot>

Attribute	Description
id int64	ID of the usage record
date date	The date of this usage record
current_storage int64	The quantity of storage held for this site
usage_by_top_level_dir array	Usage broken down by each top-level folder

List Usage Daily Snapshots

Example Request

curl "https://app.files.com/api/rest/v1/usage_daily_snapshots.json?page=1&per_page=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/usage_daily_snapshots.xml?page=1&per_page=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::UsageDailySnapshot.list(
  page: 1, 
  per_page: 1
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\UsageDailySnapshot::list(array(
  'page' => 1, 
  'per_page' => 1
));

Example Response

[
  {
    "id": 1,
    "date": "2020-11-21",
    "current_storage": "65536",
    "usage_by_top_level_dir": [

    ]
  }
]

<?xml version="1.0" encoding="UTF-8"?>
<usage-daily-snapshots type="array">
  <usage-daily-snapshot>
    <id type="integer">1</id>
    <date>2020-11-21</date>
    <current_storage>65536</current_storage>
    <usage_by_top_level_dir type="array"/>
  </usage-daily-snapshot>
</usage-daily-snapshots>

HTTPS Request

GET /usage_daily_snapshots

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Request Parameters

Parameter	Description
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Deprecated: If set to `count` returns a count of matching records rather than the records themselves.

Usage Snapshots

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

The UsageSnapshot object

Example UsageSnapshot Object

{
  "id": 1,
  "start_at": "2000-01-01T01:00:00Z",
  "end_at": "2000-01-01T01:00:00Z",
  "created_at": "2000-01-01T01:00:00Z",
  "current_storage": "",
  "high_water_storage": "",
  "total_downloads": 1,
  "total_uploads": 1,
  "updated_at": "2000-01-01T01:00:00Z",
  "usage_by_top_level_dir": "",
  "root_storage": "",
  "deleted_files_counted_in_minimum": "",
  "deleted_files_storage": ""
}

<?xml version="1.0" encoding="UTF-8"?>
<usage-snapshot>
  <id type="integer">1</id>
  <start_at>2000-01-01T01:00:00Z</start_at>
  <end_at>2000-01-01T01:00:00Z</end_at>
  <created_at>2000-01-01T01:00:00Z</created_at>
  <current_storage></current_storage>
  <high_water_storage></high_water_storage>
  <total_downloads type="integer">1</total_downloads>
  <total_uploads type="integer">1</total_uploads>
  <updated_at>2000-01-01T01:00:00Z</updated_at>
  <usage_by_top_level_dir></usage_by_top_level_dir>
  <root_storage></root_storage>
  <deleted_files_counted_in_minimum></deleted_files_counted_in_minimum>
  <deleted_files_storage></deleted_files_storage>
</usage-snapshot>

Attribute	Description
id int64	Site usage ID
start_at date-time	Site usage report start date/time
end_at date-time	Site usage report end date/time
created_at date-time	Site usage report created at date/time
current_storage double	Current site usage as of report
high_water_storage double	Site usage report highest usage in time period
total_downloads int64	Number of downloads in report time period
total_uploads int64	Number of uploads in time period
updated_at date-time	The last time this site usage report was updated
usage_by_top_level_dir object	A map of root folders to their total usage
root_storage double	Usage for root folder
deleted_files_counted_in_minimum double	Usage for files that are deleted but uploaded within last 30 days
deleted_files_storage double	Usage for files that are deleted but retained as backups

List Usage Snapshots

Example Request

curl "https://app.files.com/api/rest/v1/usage_snapshots.json?page=1&per_page=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/usage_snapshots.xml?page=1&per_page=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::UsageSnapshot.list(
  page: 1, 
  per_page: 1
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\UsageSnapshot::list(array(
  'page' => 1, 
  'per_page' => 1
));

Example Response

[
  {
    "id": 1,
    "start_at": "2000-01-01T01:00:00Z",
    "end_at": "2000-01-01T01:00:00Z",
    "created_at": "2000-01-01T01:00:00Z",
    "current_storage": "",
    "high_water_storage": "",
    "total_downloads": 1,
    "total_uploads": 1,
    "updated_at": "2000-01-01T01:00:00Z",
    "usage_by_top_level_dir": "",
    "root_storage": "",
    "deleted_files_counted_in_minimum": "",
    "deleted_files_storage": ""
  }
]

<?xml version="1.0" encoding="UTF-8"?>
<usage-snapshots type="array">
  <usage-snapshot>
    <id type="integer">1</id>
    <start_at>2000-01-01T01:00:00Z</start_at>
    <end_at>2000-01-01T01:00:00Z</end_at>
    <created_at>2000-01-01T01:00:00Z</created_at>
    <current_storage></current_storage>
    <high_water_storage></high_water_storage>
    <total_downloads type="integer">1</total_downloads>
    <total_uploads type="integer">1</total_uploads>
    <updated_at>2000-01-01T01:00:00Z</updated_at>
    <usage_by_top_level_dir></usage_by_top_level_dir>
    <root_storage></root_storage>
    <deleted_files_counted_in_minimum></deleted_files_counted_in_minimum>
    <deleted_files_storage></deleted_files_storage>
  </usage-snapshot>
</usage-snapshots>

HTTPS Request

GET /usage_snapshots

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Request Parameters

Parameter	Description
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Deprecated: If set to `count` returns a count of matching records rather than the records themselves.

Get the most recent usage snapshot (usage data for billing purposes) for a Site

Example Request

curl https://app.files.com/api/rest/v1/site/usage.json \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/site/usage.xml \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::Site.get_usage

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\Site::getUsage();

Example Response

{
  "id": 1,
  "start_at": "2000-01-01T01:00:00Z",
  "end_at": "2000-01-01T01:00:00Z",
  "created_at": "2000-01-01T01:00:00Z",
  "current_storage": "",
  "high_water_storage": "",
  "total_downloads": 1,
  "total_uploads": 1,
  "updated_at": "2000-01-01T01:00:00Z",
  "usage_by_top_level_dir": "",
  "root_storage": "",
  "deleted_files_counted_in_minimum": "",
  "deleted_files_storage": ""
}

<?xml version="1.0" encoding="UTF-8"?>
<usage-snapshot>
  <id type="integer">1</id>
  <start_at>2000-01-01T01:00:00Z</start_at>
  <end_at>2000-01-01T01:00:00Z</end_at>
  <created_at>2000-01-01T01:00:00Z</created_at>
  <current_storage></current_storage>
  <high_water_storage></high_water_storage>
  <total_downloads type="integer">1</total_downloads>
  <total_uploads type="integer">1</total_uploads>
  <updated_at>2000-01-01T01:00:00Z</updated_at>
  <usage_by_top_level_dir></usage_by_top_level_dir>
  <root_storage></root_storage>
  <deleted_files_counted_in_minimum></deleted_files_counted_in_minimum>
  <deleted_files_storage></deleted_files_storage>
</usage-snapshot>

HTTPS Request

GET /site/usage

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Users

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

The User object

Example User Object

{
  "id": 1,
  "username": "user",
  "admin_group_ids": [

  ],
  "allowed_ips": "127.0.0.1",
  "attachments_permission": true,
  "api_keys_count": 1,
  "authenticate_until": "2000-01-01T01:00:00Z",
  "authentication_method": "password",
  "avatar_url": "",
  "billing_permission": true,
  "bypass_site_allowed_ips": true,
  "bypass_inactive_disable": true,
  "created_at": "2000-01-01T01:00:00Z",
  "dav_permission": true,
  "disabled": true,
  "email": "john.doe@files.com",
  "ftp_permission": true,
  "group_ids": [

  ],
  "language": "en",
  "last_login_at": "2000-01-01T01:00:00Z",
  "last_protocol_cipher": "",
  "lockout_expires": "2000-01-01T01:00:00Z",
  "name": "John Doe",
  "notes": "Internal notes on this user.",
  "notification_daily_send_time": 18,
  "password_set_at": "2000-01-01T01:00:00Z",
  "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,
  "skip_welcome_screen": 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": ""
}

<?xml version="1.0" encoding="UTF-8"?>
<user>
  <id type="integer">1</id>
  <username>user</username>
  <admin_group_ids type="array"/>
  <allowed_ips>127.0.0.1</allowed_ips>
  <attachments_permission type="boolean">true</attachments_permission>
  <api_keys_count type="integer">1</api_keys_count>
  <authenticate_until>2000-01-01T01:00:00Z</authenticate_until>
  <authentication_method>password</authentication_method>
  <avatar_url></avatar_url>
  <billing_permission type="boolean">true</billing_permission>
  <bypass_site_allowed_ips type="boolean">true</bypass_site_allowed_ips>
  <bypass_inactive_disable type="boolean">true</bypass_inactive_disable>
  <created_at>2000-01-01T01:00:00Z</created_at>
  <dav_permission type="boolean">true</dav_permission>
  <disabled type="boolean">true</disabled>
  <email>john.doe@files.com</email>
  <ftp_permission type="boolean">true</ftp_permission>
  <group_ids type="array"/>
  <language>en</language>
  <last_login_at>2000-01-01T01:00:00Z</last_login_at>
  <last_protocol_cipher></last_protocol_cipher>
  <lockout_expires>2000-01-01T01:00:00Z</lockout_expires>
  <name>John Doe</name>
  <notes>Internal notes on this user.</notes>
  <notification_daily_send_time type="integer">18</notification_daily_send_time>
  <password_set_at>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>
  <skip_welcome_screen type="boolean">true</skip_welcome_screen>
  <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>
</user>

Attribute	Description
id int64	User ID
username string	User's username
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`.
api_keys_count int64	Number of api keys associated with this user
authenticate_until date-time	Scheduled Date/Time at which user will be deactivated
authentication_method string	How is this user authenticated? Possible values: `password`, `ldap`, `sso`, `none`
avatar_url string	URL holding the user's avatar
billing_permission boolean	Allow this user to perform operations on the account, payments, and invoices?
bypass_site_allowed_ips boolean	Allow this user to skip site-wide IP blacklists?
bypass_inactive_disable boolean	Exempt this user from being disabled based on inactivity?
created_at date-time	When this user was created
dav_permission boolean	Can the user connect with WebDAV?
disabled boolean	Is user disabled? Disabled users cannot log in, and do not count for billing purposes. Users can be automatically disabled after an inactivity period via a Site setting.
email email	User email address
ftp_permission boolean	Can the user access with FTP/FTPS?
group_ids array	Comma-separated 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
notification_daily_send_time int64	Hour of the day at which daily notifications should be sent. Can be in range 0 to 23
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?
skip_welcome_screen boolean	Skip Welcome page in the UI?
ssl_required string	SSL required setting Possible values: `use_system_setting`, `always_require`, `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.
avatar_file file	An image file for your user avatar.
avatar_delete boolean	If true, the avatar will be deleted.
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`.
grant_permission string	Permission to grant on the user root. Can be blank or `full`, `read`, `write`, `preview`, or `history`.
group_id int64	Group ID to associate this user with.
password string	User password.
password_confirmation string	Optional, but if provided, we will ensure that it matches the value sent in `password`.
announcements_read boolean	Signifies that the user has read all the announcements in the UI.

List Users

Example Request

curl "https://app.files.com/api/rest/v1/users.json?page=1&per_page=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/users.xml?page=1&per_page=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

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,
    "username": "user",
    "admin_group_ids": [

    ],
    "allowed_ips": "127.0.0.1",
    "attachments_permission": true,
    "api_keys_count": 1,
    "authenticate_until": "2000-01-01T01:00:00Z",
    "authentication_method": "password",
    "avatar_url": "",
    "billing_permission": true,
    "bypass_site_allowed_ips": true,
    "bypass_inactive_disable": true,
    "created_at": "2000-01-01T01:00:00Z",
    "dav_permission": true,
    "disabled": true,
    "email": "john.doe@files.com",
    "ftp_permission": true,
    "group_ids": [

    ],
    "language": "en",
    "last_login_at": "2000-01-01T01:00:00Z",
    "last_protocol_cipher": "",
    "lockout_expires": "2000-01-01T01:00:00Z",
    "name": "John Doe",
    "notes": "Internal notes on this user.",
    "notification_daily_send_time": 18,
    "password_set_at": "2000-01-01T01:00:00Z",
    "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,
    "skip_welcome_screen": 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": ""
  }
]

<?xml version="1.0" encoding="UTF-8"?>
<users type="array">
  <user>
    <id type="integer">1</id>
    <username>user</username>
    <admin_group_ids type="array"/>
    <allowed_ips>127.0.0.1</allowed_ips>
    <attachments_permission type="boolean">true</attachments_permission>
    <api_keys_count type="integer">1</api_keys_count>
    <authenticate_until>2000-01-01T01:00:00Z</authenticate_until>
    <authentication_method>password</authentication_method>
    <avatar_url></avatar_url>
    <billing_permission type="boolean">true</billing_permission>
    <bypass_site_allowed_ips type="boolean">true</bypass_site_allowed_ips>
    <bypass_inactive_disable type="boolean">true</bypass_inactive_disable>
    <created_at>2000-01-01T01:00:00Z</created_at>
    <dav_permission type="boolean">true</dav_permission>
    <disabled type="boolean">true</disabled>
    <email>john.doe@files.com</email>
    <ftp_permission type="boolean">true</ftp_permission>
    <group_ids type="array"/>
    <language>en</language>
    <last_login_at>2000-01-01T01:00:00Z</last_login_at>
    <last_protocol_cipher></last_protocol_cipher>
    <lockout_expires>2000-01-01T01:00:00Z</lockout_expires>
    <name>John Doe</name>
    <notes>Internal notes on this user.</notes>
    <notification_daily_send_time type="integer">18</notification_daily_send_time>
    <password_set_at>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>
    <skip_welcome_screen type="boolean">true</skip_welcome_screen>
    <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>
  </user>
</users>

HTTPS Request

GET /users

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Folder Admin permissions.

Request Parameters

Parameter	Description
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Deprecated: If set to `count` returns a count of matching records rather than the records themselves.
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.

Show User

Example Request

curl https://app.files.com/api/rest/v1/users/{id}.json \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/users/{id}.xml \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::User.find(id)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\User::find($id);

Example Response

{
  "id": 1,
  "username": "user",
  "admin_group_ids": [

  ],
  "allowed_ips": "127.0.0.1",
  "attachments_permission": true,
  "api_keys_count": 1,
  "authenticate_until": "2000-01-01T01:00:00Z",
  "authentication_method": "password",
  "avatar_url": "",
  "billing_permission": true,
  "bypass_site_allowed_ips": true,
  "bypass_inactive_disable": true,
  "created_at": "2000-01-01T01:00:00Z",
  "dav_permission": true,
  "disabled": true,
  "email": "john.doe@files.com",
  "ftp_permission": true,
  "group_ids": [

  ],
  "language": "en",
  "last_login_at": "2000-01-01T01:00:00Z",
  "last_protocol_cipher": "",
  "lockout_expires": "2000-01-01T01:00:00Z",
  "name": "John Doe",
  "notes": "Internal notes on this user.",
  "notification_daily_send_time": 18,
  "password_set_at": "2000-01-01T01:00:00Z",
  "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,
  "skip_welcome_screen": 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": ""
}

<?xml version="1.0" encoding="UTF-8"?>
<user>
  <id type="integer">1</id>
  <username>user</username>
  <admin_group_ids type="array"/>
  <allowed_ips>127.0.0.1</allowed_ips>
  <attachments_permission type="boolean">true</attachments_permission>
  <api_keys_count type="integer">1</api_keys_count>
  <authenticate_until>2000-01-01T01:00:00Z</authenticate_until>
  <authentication_method>password</authentication_method>
  <avatar_url></avatar_url>
  <billing_permission type="boolean">true</billing_permission>
  <bypass_site_allowed_ips type="boolean">true</bypass_site_allowed_ips>
  <bypass_inactive_disable type="boolean">true</bypass_inactive_disable>
  <created_at>2000-01-01T01:00:00Z</created_at>
  <dav_permission type="boolean">true</dav_permission>
  <disabled type="boolean">true</disabled>
  <email>john.doe@files.com</email>
  <ftp_permission type="boolean">true</ftp_permission>
  <group_ids type="array"/>
  <language>en</language>
  <last_login_at>2000-01-01T01:00:00Z</last_login_at>
  <last_protocol_cipher></last_protocol_cipher>
  <lockout_expires>2000-01-01T01:00:00Z</lockout_expires>
  <name>John Doe</name>
  <notes>Internal notes on this user.</notes>
  <notification_daily_send_time type="integer">18</notification_daily_send_time>
  <password_set_at>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>
  <skip_welcome_screen type="boolean">true</skip_welcome_screen>
  <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>
</user>

HTTPS Request

GET /users/{id}

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Folder Admin permissions.

Request Parameters

Parameter	Description
id int64 Required	User ID.

Create User

Example Request

curl https://app.files.com/api/rest/v1/users.json \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"avatar_delete":true,"email":"john.doe@files.com","group_id":1,"announcements_read":true,"allowed_ips":"127.0.0.1","attachments_permission":true,"authenticate_until":"2000-01-01T01:00:00Z","authentication_method":"password","billing_permission":true,"bypass_inactive_disable":true,"bypass_site_allowed_ips":true,"dav_permission":true,"disabled":true,"ftp_permission":true,"language":"en","notification_daily_send_time":18,"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,"skip_welcome_screen":true,"ssl_required":"always_require","sso_strategy_id":1,"subscribe_to_newsletter":true,"time_zone":"Pacific Time (US & Canada)","username":"user"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/users.xml \
  -X POST \
  -H 'Content-Type: application/xml' \
  -d '<user>
       <avatar_delete type="boolean">true</avatar_delete>
       <email>john.doe@files.com</email>
       <group_id type="integer">1</group_id>
       <announcements_read type="boolean">true</announcements_read>
       <allowed_ips>127.0.0.1</allowed_ips>
       <attachments_permission type="boolean">true</attachments_permission>
       <authenticate_until>2000-01-01T01:00:00Z</authenticate_until>
       <authentication_method>password</authentication_method>
       <billing_permission type="boolean">true</billing_permission>
       <bypass_inactive_disable type="boolean">true</bypass_inactive_disable>
       <bypass_site_allowed_ips type="boolean">true</bypass_site_allowed_ips>
       <dav_permission type="boolean">true</dav_permission>
       <disabled type="boolean">true</disabled>
       <ftp_permission type="boolean">true</ftp_permission>
       <language>en</language>
       <notification_daily_send_time type="integer">18</notification_daily_send_time>
       <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>
       <skip_welcome_screen type="boolean">true</skip_welcome_screen>
       <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>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::User.create(
  avatar_delete: true, 
  email: "john.doe@files.com", 
  group_id: 1, 
  announcements_read: true, 
  allowed_ips: "127.0.0.1", 
  attachments_permission: true, 
  authenticate_until: "2000-01-01T01:00:00Z", 
  authentication_method: "password", 
  billing_permission: true, 
  bypass_inactive_disable: true, 
  bypass_site_allowed_ips: true, 
  dav_permission: true, 
  disabled: true, 
  ftp_permission: true, 
  language: "en", 
  notification_daily_send_time: 18, 
  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, 
  skip_welcome_screen: 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(
  'avatar_delete' => true, 
  'email' => "john.doe@files.com", 
  'group_id' => 1, 
  'announcements_read' => true, 
  'allowed_ips' => "127.0.0.1", 
  'attachments_permission' => true, 
  'authenticate_until' => "2000-01-01T01:00:00Z", 
  'authentication_method' => "password", 
  'billing_permission' => true, 
  'bypass_inactive_disable' => true, 
  'bypass_site_allowed_ips' => true, 
  'dav_permission' => true, 
  'disabled' => true, 
  'ftp_permission' => true, 
  'language' => "en", 
  'notification_daily_send_time' => 18, 
  '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, 
  'skip_welcome_screen' => 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,
  "username": "user",
  "admin_group_ids": [

  ],
  "allowed_ips": "127.0.0.1",
  "attachments_permission": true,
  "api_keys_count": 1,
  "authenticate_until": "2000-01-01T01:00:00Z",
  "authentication_method": "password",
  "avatar_url": "",
  "billing_permission": true,
  "bypass_site_allowed_ips": true,
  "bypass_inactive_disable": true,
  "created_at": "2000-01-01T01:00:00Z",
  "dav_permission": true,
  "disabled": true,
  "email": "john.doe@files.com",
  "ftp_permission": true,
  "group_ids": [

  ],
  "language": "en",
  "last_login_at": "2000-01-01T01:00:00Z",
  "last_protocol_cipher": "",
  "lockout_expires": "2000-01-01T01:00:00Z",
  "name": "John Doe",
  "notes": "Internal notes on this user.",
  "notification_daily_send_time": 18,
  "password_set_at": "2000-01-01T01:00:00Z",
  "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,
  "skip_welcome_screen": 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": ""
}

<?xml version="1.0" encoding="UTF-8"?>
<user>
  <id type="integer">1</id>
  <username>user</username>
  <admin_group_ids type="array"/>
  <allowed_ips>127.0.0.1</allowed_ips>
  <attachments_permission type="boolean">true</attachments_permission>
  <api_keys_count type="integer">1</api_keys_count>
  <authenticate_until>2000-01-01T01:00:00Z</authenticate_until>
  <authentication_method>password</authentication_method>
  <avatar_url></avatar_url>
  <billing_permission type="boolean">true</billing_permission>
  <bypass_site_allowed_ips type="boolean">true</bypass_site_allowed_ips>
  <bypass_inactive_disable type="boolean">true</bypass_inactive_disable>
  <created_at>2000-01-01T01:00:00Z</created_at>
  <dav_permission type="boolean">true</dav_permission>
  <disabled type="boolean">true</disabled>
  <email>john.doe@files.com</email>
  <ftp_permission type="boolean">true</ftp_permission>
  <group_ids type="array"/>
  <language>en</language>
  <last_login_at>2000-01-01T01:00:00Z</last_login_at>
  <last_protocol_cipher></last_protocol_cipher>
  <lockout_expires>2000-01-01T01:00:00Z</lockout_expires>
  <name>John Doe</name>
  <notes>Internal notes on this user.</notes>
  <notification_daily_send_time type="integer">18</notification_daily_send_time>
  <password_set_at>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>
  <skip_welcome_screen type="boolean">true</skip_welcome_screen>
  <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>
</user>

HTTPS Request

POST /users

Authentication Required

Available to all authenticated keys or sessions.

Request Parameters

Parameter	Description
avatar_file file	An image file for your user avatar.
avatar_delete boolean	If true, the avatar will be deleted.
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_id int64	Group ID to associate this user with.
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`.
announcements_read boolean	Signifies that the user has read all the announcements in the UI.
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? Possible values: `password`, `ldap`, `sso`, `none`
billing_permission boolean	Allow this user to perform operations on the account, payments, and invoices?
bypass_inactive_disable boolean	Exempt this user from being disabled based on inactivity?
bypass_site_allowed_ips boolean	Allow this user to skip site-wide IP blacklists?
dav_permission boolean	Can the user connect with WebDAV?
disabled boolean	Is user disabled? Disabled users cannot log in, and do not count for billing purposes. Users can be automatically disabled after an inactivity period via a Site setting.
ftp_permission boolean	Can the user access with FTP/FTPS?
language string	Preferred language
notification_daily_send_time int64	Hour of the day at which daily notifications should be sent. Can be in range 0 to 23
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?
skip_welcome_screen boolean	Skip Welcome page in the UI?
ssl_required string	SSL required setting Possible values: `use_system_setting`, `always_require`, `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 \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/users/{id}/unlock.xml \
  -X POST \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

user = Files::User.find(id)
user.unlock

\Files\Files::setApiKey('YOUR_API_KEY');

$user = \Files\User->find(1);
$user->unlock();

Example Response

No response.

No response.

HTTPS Request

POST /users/{id}/unlock

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

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 \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/users/{id}/resend_welcome_email.xml \
  -X POST \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

user = Files::User.find(id)
user.resend_welcome_email

\Files\Files::setApiKey('YOUR_API_KEY');

$user = \Files\User->find(1);
$user->resendWelcomeEmail();

Example Response

No response.

No response.

HTTPS Request

POST /users/{id}/resend_welcome_email

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

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 \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/users/{id}/2fa/reset.xml \
  -X POST \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

user = Files::User.find(id)
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

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

The X-Files-Reauthentication header is required for all requests to this endpoint.

Request Parameters

Parameter	Description
id int64 Required	User ID.

Update User

Example Request

curl https://app.files.com/api/rest/v1/users/{id}.json \
  -X PATCH \
  -H 'Content-Type: application/json' \
  -d '{"avatar_delete":true,"email":"john.doe@files.com","group_id":1,"announcements_read":true,"allowed_ips":"127.0.0.1","attachments_permission":true,"authenticate_until":"2000-01-01T01:00:00Z","authentication_method":"password","billing_permission":true,"bypass_inactive_disable":true,"bypass_site_allowed_ips":true,"dav_permission":true,"disabled":true,"ftp_permission":true,"language":"en","notification_daily_send_time":18,"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,"skip_welcome_screen":true,"ssl_required":"always_require","sso_strategy_id":1,"subscribe_to_newsletter":true,"time_zone":"Pacific Time (US & Canada)","username":"user"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/users/{id}.xml \
  -X PATCH \
  -H 'Content-Type: application/xml' \
  -d '<user>
       <avatar_delete type="boolean">true</avatar_delete>
       <email>john.doe@files.com</email>
       <group_id type="integer">1</group_id>
       <announcements_read type="boolean">true</announcements_read>
       <allowed_ips>127.0.0.1</allowed_ips>
       <attachments_permission type="boolean">true</attachments_permission>
       <authenticate_until>2000-01-01T01:00:00Z</authenticate_until>
       <authentication_method>password</authentication_method>
       <billing_permission type="boolean">true</billing_permission>
       <bypass_inactive_disable type="boolean">true</bypass_inactive_disable>
       <bypass_site_allowed_ips type="boolean">true</bypass_site_allowed_ips>
       <dav_permission type="boolean">true</dav_permission>
       <disabled type="boolean">true</disabled>
       <ftp_permission type="boolean">true</ftp_permission>
       <language>en</language>
       <notification_daily_send_time type="integer">18</notification_daily_send_time>
       <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>
       <skip_welcome_screen type="boolean">true</skip_welcome_screen>
       <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>'
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

user = Files::User.find(id)
user.update(
  avatar_delete: true,
  email: "john.doe@files.com",
  group_id: 1,
  announcements_read: true,
  allowed_ips: "127.0.0.1",
  attachments_permission: true,
  authenticate_until: "2000-01-01T01:00:00Z",
  authentication_method: "password",
  billing_permission: true,
  bypass_inactive_disable: true,
  bypass_site_allowed_ips: true,
  dav_permission: true,
  disabled: true,
  ftp_permission: true,
  language: "en",
  notification_daily_send_time: 18,
  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,
  skip_welcome_screen: 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(
  'avatar_delete' => true, 
  'email' => "john.doe@files.com", 
  'group_id' => 1, 
  'announcements_read' => true, 
  'allowed_ips' => "127.0.0.1", 
  'attachments_permission' => true, 
  'authenticate_until' => "2000-01-01T01:00:00Z", 
  'authentication_method' => "password", 
  'billing_permission' => true, 
  'bypass_inactive_disable' => true, 
  'bypass_site_allowed_ips' => true, 
  'dav_permission' => true, 
  'disabled' => true, 
  'ftp_permission' => true, 
  'language' => "en", 
  'notification_daily_send_time' => 18, 
  '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, 
  'skip_welcome_screen' => 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,
  "username": "user",
  "admin_group_ids": [

  ],
  "allowed_ips": "127.0.0.1",
  "attachments_permission": true,
  "api_keys_count": 1,
  "authenticate_until": "2000-01-01T01:00:00Z",
  "authentication_method": "password",
  "avatar_url": "",
  "billing_permission": true,
  "bypass_site_allowed_ips": true,
  "bypass_inactive_disable": true,
  "created_at": "2000-01-01T01:00:00Z",
  "dav_permission": true,
  "disabled": true,
  "email": "john.doe@files.com",
  "ftp_permission": true,
  "group_ids": [

  ],
  "language": "en",
  "last_login_at": "2000-01-01T01:00:00Z",
  "last_protocol_cipher": "",
  "lockout_expires": "2000-01-01T01:00:00Z",
  "name": "John Doe",
  "notes": "Internal notes on this user.",
  "notification_daily_send_time": 18,
  "password_set_at": "2000-01-01T01:00:00Z",
  "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,
  "skip_welcome_screen": 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": ""
}

<?xml version="1.0" encoding="UTF-8"?>
<user>
  <id type="integer">1</id>
  <username>user</username>
  <admin_group_ids type="array"/>
  <allowed_ips>127.0.0.1</allowed_ips>
  <attachments_permission type="boolean">true</attachments_permission>
  <api_keys_count type="integer">1</api_keys_count>
  <authenticate_until>2000-01-01T01:00:00Z</authenticate_until>
  <authentication_method>password</authentication_method>
  <avatar_url></avatar_url>
  <billing_permission type="boolean">true</billing_permission>
  <bypass_site_allowed_ips type="boolean">true</bypass_site_allowed_ips>
  <bypass_inactive_disable type="boolean">true</bypass_inactive_disable>
  <created_at>2000-01-01T01:00:00Z</created_at>
  <dav_permission type="boolean">true</dav_permission>
  <disabled type="boolean">true</disabled>
  <email>john.doe@files.com</email>
  <ftp_permission type="boolean">true</ftp_permission>
  <group_ids type="array"/>
  <language>en</language>
  <last_login_at>2000-01-01T01:00:00Z</last_login_at>
  <last_protocol_cipher></last_protocol_cipher>
  <lockout_expires>2000-01-01T01:00:00Z</lockout_expires>
  <name>John Doe</name>
  <notes>Internal notes on this user.</notes>
  <notification_daily_send_time type="integer">18</notification_daily_send_time>
  <password_set_at>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>
  <skip_welcome_screen type="boolean">true</skip_welcome_screen>
  <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>
</user>

HTTPS Request

PATCH /users/{id}

Authentication Required

Not available to user API keys or sessions from users that are marked as Shared/Bot users.

The X-Files-Reauthentication header is required for any requests including the following parameters: password, change_password, email, site_admin.

Request Parameters

Parameter	Description
id int64 Required	User ID.
avatar_file file	An image file for your user avatar.
avatar_delete boolean	If true, the avatar will be deleted.
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_id int64	Group ID to associate this user with.
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`.
announcements_read boolean	Signifies that the user has read all the announcements in the UI.
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? Possible values: `password`, `ldap`, `sso`, `none`
billing_permission boolean	Allow this user to perform operations on the account, payments, and invoices?
bypass_inactive_disable boolean	Exempt this user from being disabled based on inactivity?
bypass_site_allowed_ips boolean	Allow this user to skip site-wide IP blacklists?
dav_permission boolean	Can the user connect with WebDAV?
disabled boolean	Is user disabled? Disabled users cannot log in, and do not count for billing purposes. Users can be automatically disabled after an inactivity period via a Site setting.
ftp_permission boolean	Can the user access with FTP/FTPS?
language string	Preferred language
notification_daily_send_time int64	Hour of the day at which daily notifications should be sent. Can be in range 0 to 23
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?
skip_welcome_screen boolean	Skip Welcome page in the UI?
ssl_required string	SSL required setting Possible values: `use_system_setting`, `always_require`, `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

Delete User

Example Request

curl https://app.files.com/api/rest/v1/users/{id}.json \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl https://app.files.com/api/rest/v1/users/{id}.xml \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

user = Files::User.find(id)
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}

Authentication Required

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

The X-Files-Reauthentication header is required for all requests to this endpoint.

Request Parameters

Parameter	Description
id int64 Required	User ID.

User Cipher Uses

This object allows you to see the exact set of encryption ciphers and protocols used by a given user. This is most often used to support migrations from one TLS version to the next. You can query each user and determine who is still using legacy ciphers.

The UserCipherUse object

Example UserCipherUse Object

{
  "id": 1,
  "protocol_cipher": "TLSv1.2; ECDHE-RSA-AES256-GCM-SHA384",
  "created_at": "2000-01-01T01:00:00Z",
  "interface": "restapi",
  "updated_at": "2000-01-01T01:00:00Z",
  "user_id": 1
}

<?xml version="1.0" encoding="UTF-8"?>
<user-cipher-use>
  <id type="integer">1</id>
  <protocol_cipher>TLSv1.2; ECDHE-RSA-AES256-GCM-SHA384</protocol_cipher>
  <created_at>2000-01-01T01:00:00Z</created_at>
  <interface>restapi</interface>
  <updated_at>2000-01-01T01:00:00Z</updated_at>
  <user_id type="integer">1</user_id>
</user-cipher-use>

Attribute	Description
id int64	UserCipherUse ID
protocol_cipher string	The protocol and cipher employed
created_at date-time	The earliest recorded use of this combination of interface and protocol and cipher (for this user)
interface string	The interface accessed Possible values: `web`, `ftp`, `sftp`, `dav`, `desktop`, `restapi`, `robot`, `jsapi`
updated_at date-time	The most recent use of this combination of interface and protocol and cipher (for this user)
user_id int64	ID of the user who performed this access

List User Cipher Uses

Example Request

curl "https://app.files.com/api/rest/v1/user_cipher_uses.json?user_id=1&page=1&per_page=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

curl "https://app.files.com/api/rest/v1/user_cipher_uses.xml?user_id=1&page=1&per_page=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Files.api_key = 'YOUR_API_KEY'

Files::UserCipherUse.list(
  user_id: 1, 
  page: 1, 
  per_page: 1
)

\Files\Files::setApiKey('YOUR_API_KEY');

\Files\UserCipherUse::list(array(
  'user_id' => 1, 
  'page' => 1, 
  'per_page' => 1
));

Example Response

[
  {
    "id": 1,
    "protocol_cipher": "TLSv1.2; ECDHE-RSA-AES256-GCM-SHA384",
    "created_at": "2000-01-01T01:00:00Z",
    "interface": "restapi",
    "updated_at": "2000-01-01T01:00:00Z",
    "user_id": 1
  }
]

<?xml version="1.0" encoding="UTF-8"?>
<user-cipher-uses type="array">
  <user-cipher-use>
    <id type="integer">1</id>
    <protocol_cipher>TLSv1.2; ECDHE-RSA-AES256-GCM-SHA384</protocol_cipher>
    <created_at>2000-01-01T01:00:00Z</created_at>
    <interface>restapi</interface>
    <updated_at>2000-01-01T01:00:00Z</updated_at>
    <user_id type="integer">1</user_id>
  </user-cipher-use>
</user-cipher-uses>

HTTPS Request

GET /user_cipher_uses

Authentication Required

Not available to user API keys or sessions from users that are marked as Shared/Bot users.

Request Parameters

Parameter	Description
user_id int64	User ID. Provide a value of `0` to operate the current session's user.
page int64	Current page number.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).
action string	Deprecated: If set to `count` returns a count of matching records rather than the records themselves.

Introduction

REST API

Per-Language SDKs

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

Authentication with API Key

Authentication with a Session

Logging in

HTTP Request

Using a session

Reauthentication

Logging out

HTTP Request

Errors

HTTP status codes

Account Line Items

The AccountLineItem object

List Invoices

HTTPS Request

Authentication Required

Request Parameters

List Payments

HTTPS Request

Authentication Required

Request Parameters

Show Invoice

HTTPS Request

Authentication Required

Request Parameters

Show Payment

HTTPS Request

Authentication Required

Request Parameters

Actions

The Action object

List history for specific file

HTTPS Request

Authentication Required

Request Parameters

List history for specific folder

HTTPS Request

Authentication Required

Request Parameters

List history for specific user

HTTPS Request

Authentication Required

Request Parameters

List site login history

HTTPS Request

Authentication Required

Request Parameters

List site full action history

HTTPS Request

Authentication Required

Request Parameters

Api Keys

The ApiKey object

List Api Keys

HTTPS Request

Authentication Required

Request Parameters

Show information about current API key. (Requires current API connection to be using an API key.)

HTTPS Request

Authentication Required

Show Api Key

HTTPS Request

Authentication Required

Request Parameters

Create Api Key

HTTPS Request

Authentication Required

Request Parameters

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

HTTPS Request

Authentication Required

Request Parameters

Update Api Key

HTTPS Request

Authentication Required

Request Parameters

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