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.
SDKs
Files.com publishes SDKs for all popular programming languages. We strongly recommend using our SDKs over directly implementing our REST API, especially if working with files. Our SDKs include developer-friendly features such as support for automatic pagination and tight integration with the File APIs in your language of choice.
Plus we have invested time into optimizing file operations, including parallelization of uploads and downloads in some SDKs. As we add support for more remote server backends via our Sync and Mount features, we will always update our SDKs with any optimizations that are available.
JavaScript SDK
The JavaScript SDK can be installed via NPM or it can be retrieved directly at GitHub.
Ruby SDK
The Ruby SDK can be installed via Rubygems/Bundler or it can be retrieved directly at GitHub.
PHP SDK
The PHP SDK can be installed via Packagist or it can be retrieved directly at GitHub.
Microsoft .NET SDK
The .NET SDK can be installed via NuGet or it can be retrieved directly at GitHub.
Python SDK
The Python SDK can be installed via PyPI or it can be retrieved directly at GitHub.
Java SDK
The Java SDK can be installed via at GitHub.
Go SDK
The Go SDK can be installed via at GitHub.
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.
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.
Command Line Interface (CLI) App
A Command Line Interface (CLI) app for Windows, macOS, and Linux can be found here.
Mock Server For Your Integration Tests
Files.com publishes a Files.com API server, which is useful for testing your use of the Files.com SDKs and other direct integrations against the Files.com API in an integration test environment.
It is a Ruby app that operates as a minimal server for the purpose of testing basic network operations and JSON encoding for your SDK or API client. It does not maintain state and it does not deeply inspect your submissions for correctness.
Eventually we will add more features intended for integration testing, such as the ability to intentionally provoke errors.
Download the server as a Docker image via Docker Hub.
The Source Code is also available on GitHub.
A README is available on the GitHub link.
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\Files::setApiKey('YOUR_API_KEY');
\Files\Files::setBaseUrl('https://SUBDOMAIN.files.com');
# Alternatively, you can specify the API key on a per-object basis in the second parameter to a model constructor.
$user = new \Files\Model\User($params, array('api_key' => 'YOUR_API_KEY'));
# You may also specify the API key on a per-request basis in the final parameter to static methods.
\Files\Model\User::find($id, $params, array('api_key' => 'YOUR_API_KEY'));
FilesClient.apiKey = "YOUR_API_KEY";
// Alternatively, you can specify the API key on a per-object
// basis in options HashMap to a model constructor.
HashMap<String, Object> requestOptions = new HashMap()<>;
requestOptions.put("api_key", "my-key");
User user = new User(params, requestParameters);
// You may also specify the API key on a per-request basis in
// in the final parameter to static methods.
HashMap<String, Object> requestOptions = new HashMap()<>;
requestOptions.put("api_key", "my-key");
User.find(id, params, requestOptions);
Files.setApiKey('YOUR_API_KEY')
Files.setBaseUrl('https://SUBDOMAIN.files.com')
// Alternatively, you can specify the API key on a per-object basis in the second parameter to a model constructor.
const user = new User(params, { apiKey: 'YOUR_API_KEY' })
// You may also specify the API key on a per-request basis in the final parameter to static methods.
await User.find(id, params, { apiKey: 'YOUR_API_KEY' })
// Using manual configuration
var config = new FilesConfiguration();
config.ApiKey = 'YOUR_API_KEY'
new FilesClient(config);
// In app.config
<configSections>
<sectionGroup name="files.com">
<section
name="filesConfiguration"
type="Files.FilesConfiguration, Files.com"
/>
</sectionGroup>
</configSections>
<files.com>
<filesConfiguration ApiKey="YOUR_API_KEY" />
</files.com>
new FilesClient();
// You may also specify the API key on a per-request basis in the final parameter to static methods.
var options = Dictionary<string, object>();
options.Add("api_key", "YOUR_API_KEY");
User.Find(id, params, options);
files_sdk.set_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_sdk.user.list(params, {"api_key": "YOUR_API_KEY"})
Make sure to replace
YOUR_API_KEYwith 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>'
$session = \Files\Model\Session::create(['username' => 'motor', 'password' => 'vroom']);
HashMap<String, Object> sessionParameters = new HashMap<>()
sessionParameters.put("username", "username");
sessionParameters.put("password", "password");
Session session = Session.create(parameters)
const session = await Session.create({ username: 'motor', password: 'vroom' })
session = files_sdk.session.create({ "username": "motor", "password": "vroom" })
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'
# You may set the returned session ID to be used by default for subsequent requests.
\Files\Files::setSessionId($session->id);
\Files\Files::setBaseUrl('https://SUBDOMAIN.files.com');
# Alternatively, you can specify the session ID on a per-object basis in the second parameter to a model constructor.
$user = new \Files\Model\User($params, array('session_id' => $session->id));
# You may also specify the session ID on a per-request basis in the final parameter to static methods.
\Files\Model\User::find($id, $params, array('session_id' => $session->id));
// You may set the returned session to be used by default for subsequent requests.
FilesClient.session = session;
// Alternatively, you can specify the session ID on a per-object basis
// in the second parameter to a model constructor.
HashMap<String, Object> requestParameters = new HashMap<>();
requestParameters.put("session_id", session.getId());
User.find(id, params, requestParameters);
// You may set the returned session ID to be used by default for subsequent requests.
Files.setSessionId(session.id)
Files.setBaseUrl('https://SUBDOMAIN.files.com')
// Alternatively, you can specify the session ID on a per-object basis in the second parameter to a model constructor.
const user = new User(params, { session_id: session.id })
// You may also specify the session ID on a per-request basis in the final parameter to static methods.
await User.find(id, params, { session_id: session.id })
# You may set the returned session ID to be used by default for subsequent requests.
files_sdk.session_id = session.id
files_sdk.base_url = "https://SUBDOMAIN.files.com"
# Alternatively, you can specify the session ID on a per-object basis in the second parameter to a model constructor.
user = files_sdk.user.User(params, {"session_id": session.id})
# You may also specify the session ID on a per-request basis in the final parameter to static methods.
files_sdk.user.find(id, params, {"session_id": session.id})
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
Session::destroy();
session.destroy()
await Session.destroy()
session.destroy()
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)
Response Codes / Errors
Example Response: Invalid API key
{
"error":"Unauthorized. The API key or Session token is either missing or invalid.",
"http-code":401,
"instance":"a69f6b06-6ba9-4e71-8542-60d2ff3d96f2",
"title":"Authentication Required",
"type":"not-authorized/authentication-required"
}
<?xml version="1.0" encoding="UTF-8"?>
<error_response>
<error>Unauthorized. The API key or Session token is either missing or invalid.</error>
<http-code type="integer">401</http-code>
<instance>df517ee8-91ec-4120-bf54-642db67e483d</instance>
<title>Authentication Required</title>
<type>not-authorized/authentication-required</type>
</error_response>
Example Response: Invalid username or password
{
"error":"Invalid username or password",
"http-code":401,
"instance":"d895ebaa-7e7e-4ced-87c9-2acf743a19c3",
"errors":[
{
"error":"Invalid username or password",
"http-code":401,
"instance":"d895ebaa-7e7e-4ced-87c9-2acf743a19c3",
"title":"Invalid Username Or Password",
"type":"401-invalid-username-or-password"
}
],
"title":"Invalid Username Or Password",
"type":"bad-request/invalid-username-or-password"
}
<?xml version="1.0" encoding="UTF-8"?>
<error_response>
<error>Invalid username or password</error>
<http-code type="integer">401</http-code>
<instance>8bbd89f7-f0eb-4295-8b23-4ab4bec17546</instance>
<errors type="array">
<error>
<error>Invalid username or password</error>
<http-code type="integer">401</http-code>
<instance>8bbd89f7-f0eb-4295-8b23-4ab4bec17546</instance>
<title>Invalid Username Or Password</title>
<type>401-invalid-username-or-password</type>
</error>
</errors>
<title>Invalid Username Or Password</title>
<type>bad-request/invalid-username-or-password</type>
</error_response>
Example Response: No read permission for path
{
"error":"You do not have read permission for this path, file.txt",
"http-code":403,
"instance":"37ffdbfb-8faa-4af9-8091-29162f0be67c",
"title":"Read Permission Required",
"type":"not-authorized/read-permission-required"
}
<?xml version="1.0" encoding="UTF-8"?>
<error_response>
<error>You do not have read permission for this path, file.txt</error>
<http-code type="integer">403</http-code>
<instance>03df05f8-9a1b-4d25-83cc-01278cb43682</instance>
<title>Read Permission Required</title>
<type>not-authorized/read-permission-required</type>
</error_response>
The Files.com API returns standard HTTP success (2xx) or error (4xx, 5xx) status codes. Status codes in the 5xx range are unexpected and indicate 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.
Note that success codes can include 200, 201, and 204.
The Files.com API returns errors in a standard structure for both JSON and XML API requests as well as our SDKs. Because different types of errors will share the same HTTP response code, it is strongly recommended to use the type attribute of the returned error object and not the HTTP response code when handling errors.
Each SDK implements exception handling in a native way using these error types. You can catch/rescue individual error types as well as error type families.
Error Types
| Type | Description |
|---|---|
account-in-bad-standing/account-overdue |
Account Overdue |
bad-request |
Bad Request |
bad-request/attachment-too-large |
Attachment Too Large |
bad-request/cannot-download-directory |
Cannot Download Directory |
bad-request/cant-move-with-multiple-locations |
Cant Move With Multiple Locations |
bad-request/datetime-parse |
Datetime Parse |
bad-request/destination-same |
Destination Same |
bad-request/folder-must-not-be-a-file |
Folder Must Not Be A File |
bad-request/invalid-filter-combination |
Invalid Filter Combination |
bad-request/invalid-filter-field |
Invalid Filter Field |
bad-request/invalid-input-encoding |
Invalid Input Encoding |
bad-request/invalid-interface |
Invalid Interface |
bad-request/invalid-oauth |
Invalid Oauth |
bad-request/invalid-oauth-provider |
Invalid Oauth Provider |
bad-request/invalid-return-to-url |
Invalid Return To Url |
bad-request/invalid-upload-offset |
Invalid Upload Offset |
bad-request/invalid-username-or-password |
Invalid Username Or Password |
bad-request/operation-on-non-scim-resource |
Operation On Non Scim Resource |
bad-request/unsupported-http-response-format |
Unsupported Http Response Format |
bad-request/unsupported-media-type |
Unsupported Media Type |
bad-request/user-id-invalid |
User Id Invalid |
bad-request/user-id-on-user-endpoint |
User Id On User Endpoint |
bad-request/user-required |
User Required |
invalid-params/no-valid-input-params |
No Valid Input Params |
invalid-params/reauthentication-needed-fields |
Reauthentication Needed Fields |
invalid-params/request-param-path-cannot-have-trailing-whitespace |
Request Param Path Cannot Have Trailing Whitespace |
invalid-params/request-params-contain-invalid-character |
Request Params Contain Invalid Character |
invalid-params/request-params-invalid |
Request Params Invalid |
invalid-params/request-params-required |
Request Params Required |
invalid-params/unsupported-currency |
Unsupported Currency |
locked/file-locked |
File Locked |
locked/folder-locked |
Folder Locked |
locked/resource-locked |
Resource Locked |
locked/subfolder-locked |
Subfolder Locked |
not-authenticated/one-time-password-incorrect |
One Time Password Incorrect |
not-authenticated/two-factor-authentication-error |
Two Factor Authentication Error |
not-authenticated/two-factor-authentication-required |
Two Factor Authentication Required |
not-authenticated/two-factor-authentication-setup-expired |
Two Factor Authentication Setup Expired |
not-authorized/api-key-is-disabled |
Api Key Is Disabled |
not-authorized/api-key-is-path-restricted |
Api Key Is Path Restricted |
not-authorized/api-key-only-for-desktop-app |
Api Key Only For Desktop App |
not-authorized/api-key-only-for-office-integration |
Api Key Only For Office Integration |
not-authorized/authentication-required |
Authentication Required |
not-authorized/cannot-login-while-using-key |
Cannot Login While Using Key |
not-authorized/cant-act-for-other-user |
Cant Act For Other User |
not-authorized/contact-admin-for-password-change-help |
Contact Admin For Password Change Help |
not-authorized/folder-admin-or-billing-permission |
Folder Admin Or Billing Permission |
not-authorized/folder-admin-permission-required |
Folder Admin Permission Required |
not-authorized/history-export-non-admins-must-query-by-folder-or-path |
History Export Non Admins Must Query By Folder Or Path |
not-authorized/history-permission-required |
History Permission Required |
not-authorized/insufficient-permission-for-params |
Insufficient Permission For Params |
not-authorized/locked-out |
Locked Out |
not-authorized/lockout-ip-failures |
Lockout Ip Failures |
not-authorized/lockout-region-mismatch |
Lockout Region Mismatch |
not-authorized/must-authenticate-with-api-key |
Must Authenticate With Api Key |
not-authorized/need-admin-permission-for-inbox |
Need Admin Permission For Inbox |
not-authorized/no-billing-permission |
No Billing Permission |
not-authorized/not-allowed-to-create-bundle |
Not Allowed To Create Bundle |
not-authorized/password-change-not-required |
Password Change Not Required |
not-authorized/password-change-required |
Password Change Required |
not-authorized/read-only-session |
Read Only Session |
not-authorized/read-permission-required |
Read Permission Required |
not-authorized/reauthentication-failed |
Reauthentication Failed |
not-authorized/reauthentication-failed-final |
Reauthentication Failed Final |
not-authorized/reauthentication-needed-action |
Reauthentication Needed Action |
not-authorized/self-managed-required |
Self Managed Required |
not-authorized/unauthorized |
Unauthorized |
not-authorized/user-id-without-site-admin |
User Id Without Site Admin |
not-authorized/write-permission-required |
Write Permission Required |
not-authorized/zip-download-ip-mismatch |
Zip Download Ip Mismatch |
not-found |
Not Found |
not-found/api-key-not-found |
Api Key Not Found |
not-found/bundle-path-not-found |
Bundle Path Not Found |
not-found/code-not-found |
Code Not Found |
not-found/file-not-found |
File Not Found |
not-found/file-upload-not-found |
File Upload Not Found |
not-found/folder-not-found |
Folder Not Found |
not-found/group-not-found |
Group Not Found |
not-found/history-export-not-ready |
History Export Not Ready |
not-found/inbox-not-found |
Inbox Not Found |
not-found/nested-not-found |
Nested Not Found |
not-found/plan-not-found |
Plan Not Found |
not-found/site-not-found |
Site Not Found |
not-found/user-not-found |
User Not Found |
processing-failure/bundle-registration-code-failed |
Bundle Registration Code Failed |
processing-failure/destination-exists |
Destination Exists |
processing-failure/destination-parent-conflict |
Destination Parent Conflict |
processing-failure/destination-parent-does-not-exist |
Destination Parent Does Not Exist |
processing-failure/failed-to-change-password |
Failed To Change Password |
processing-failure/file-not-uploaded |
File Not Uploaded |
processing-failure/folder-not-empty |
Folder Not Empty |
processing-failure/history-export-failure |
History Export Failure |
processing-failure/history-unavailable |
History Unavailable |
processing-failure/inbox-registration-code-failed |
Inbox Registration Code Failed |
processing-failure/invalid-bundle-code |
Invalid Bundle Code |
processing-failure/invalid-or-expired-code |
Invalid Or Expired Code |
processing-failure/model-save-error |
Model Save Error |
processing-failure/remote-server-error |
Remote Server Error |
processing-failure/two-factor-authentication-code-already-sent |
Two Factor Authentication Code Already Sent |
processing-failure/unprocessable-entity |
Unprocessable Entity |
processing-pending |
Processing Pending |
rate-limited/reauthentication-rate-limited |
Reauthentication Rate Limited |
rate-limited/too-many-requests |
Too Many Requests |
site-configuration/account-already-exists |
Account Already Exists |
site-configuration/no-account-for-site |
No Account For Site |
site-configuration/site-admin-required |
Site Admin Required |
site-configuration/site-was-removed |
Site Was Removed |
site-configuration/trial-expired |
Trial Expired |
site-configuration/trial-locked |
Trial Locked |
site-configuration/user-requests-enabled-required |
User Requests Enabled Required |
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": 1.0,
"balance": 1.0,
"created_at": "2000-01-01T01:00:00Z",
"currency": "USD",
"download_uri": "https://url...",
"invoice_line_items": [
{
"amount": 1.0,
"created_at": "2000-01-01T01:00:00Z",
"description": "Service from 2019-01-01 through 2019-12-31",
"type": "invoice",
"service_end_at": "2000-01-01T01:00:00Z",
"service_start_at": "2000-01-01T01:00:00Z",
"updated_at": "2000-01-01T01:00:00Z",
"plan": "Enterprise",
"site": "My site"
}
],
"method": "paypal",
"payment_line_items": [
{
"amount": 1.0,
"created_at": "2000-01-01T01:00:00Z",
"invoice_id": 1,
"payment_id": 1,
"updated_at": "2000-01-01T01:00:00Z"
}
],
"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 type="float">1.0</amount>
<balance type="float">1.0</balance>
<created_at>2000-01-01T01:00:00Z</created_at>
<currency>USD</currency>
<download_uri>https://url...</download_uri>
<invoice_line_items type="array">
<invoice_line_item>
<amount type="float">1.0</amount>
<created_at>2000-01-01T01:00:00Z</created_at>
<description>Service from 2019-01-01 through 2019-12-31</description>
<type>invoice</type>
<service_end_at>2000-01-01T01:00:00Z</service_end_at>
<service_start_at>2000-01-01T01:00:00Z</service_start_at>
<updated_at>2000-01-01T01:00:00Z</updated_at>
<plan>Enterprise</plan>
<site>My site</site>
</invoice_line_item>
</invoice_line_items>
<method>paypal</method>
<payment_line_items type="array">
<payment_line_item>
<amount type="float">1.0</amount>
<created_at>2000-01-01T01:00:00Z</created_at>
<invoice_id type="integer">1</invoice_id>
<payment_id type="integer">1</payment_id>
<updated_at>2000-01-01T01:00:00Z</updated_at>
</payment_line_item>
</payment_line_items>
<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?per_page=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/invoices.xml?per_page=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::Invoice.list(
per_page: 1
)
\Files\Model\Invoice::list(array(
'per_page' => 1
));
["HashMap<Object, String> requestParams = new HashMap<>();\n"]requestParams.put("per_page", 1);
Invoice.list(parameters)
await Invoice.list({
per_page: 1,
})
var parameters = new Dictionary<string, object>();
parameters.Add("per_page", 1);
Invoice.List(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.invoice.list({
"per_page": 1
})
Example Response
[
{
"id": 1,
"amount": 1.0,
"balance": 1.0,
"created_at": "2000-01-01T01:00:00Z",
"currency": "USD",
"download_uri": "https://url...",
"invoice_line_items": [
{
"amount": 1.0,
"created_at": "2000-01-01T01:00:00Z",
"description": "Service from 2019-01-01 through 2019-12-31",
"type": "invoice",
"service_end_at": "2000-01-01T01:00:00Z",
"service_start_at": "2000-01-01T01:00:00Z",
"updated_at": "2000-01-01T01:00:00Z",
"plan": "Enterprise",
"site": "My site"
}
],
"method": "paypal",
"payment_line_items": [
{
"amount": 1.0,
"created_at": "2000-01-01T01:00:00Z",
"invoice_id": 1,
"payment_id": 1,
"updated_at": "2000-01-01T01:00:00Z"
}
],
"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 type="float">1.0</amount>
<balance type="float">1.0</balance>
<created_at>2000-01-01T01:00:00Z</created_at>
<currency>USD</currency>
<download_uri>https://url...</download_uri>
<invoice_line_items type="array">
<invoice_line_item>
<amount type="float">1.0</amount>
<created_at>2000-01-01T01:00:00Z</created_at>
<description>Service from 2019-01-01 through 2019-12-31</description>
<type>invoice</type>
<service_end_at>2000-01-01T01:00:00Z</service_end_at>
<service_start_at>2000-01-01T01:00:00Z</service_start_at>
<updated_at>2000-01-01T01:00:00Z</updated_at>
<plan>Enterprise</plan>
<site>My site</site>
</invoice_line_item>
</invoice_line_items>
<method>paypal</method>
<payment_line_items type="array">
<payment_line_item>
<amount type="float">1.0</amount>
<created_at>2000-01-01T01:00:00Z</created_at>
<invoice_id type="integer">1</invoice_id>
<payment_id type="integer">1</payment_id>
<updated_at>2000-01-01T01:00:00Z</updated_at>
</payment_line_item>
</payment_line_items>
<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 |
|---|---|
| cursor string | Used for pagination. Send a cursor value 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-Next header. |
| per_page int64 | Number of records to show per page. (Max: 10,000, 1,000 or less is recommended). |
List Payments
Example Request
curl "https://app.files.com/api/rest/v1/payments.json?per_page=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/payments.xml?per_page=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::Payment.list(
per_page: 1
)
\Files\Model\Payment::list(array(
'per_page' => 1
));
["HashMap<Object, String> requestParams = new HashMap<>();\n"]requestParams.put("per_page", 1);
Payment.list(parameters)
await Payment.list({
per_page: 1,
})
var parameters = new Dictionary<string, object>();
parameters.Add("per_page", 1);
Payment.List(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.payment.list({
"per_page": 1
})
Example Response
[
{
"id": 1,
"amount": 1.0,
"balance": 1.0,
"created_at": "2000-01-01T01:00:00Z",
"currency": "USD",
"download_uri": "https://url...",
"invoice_line_items": [
{
"amount": 1.0,
"created_at": "2000-01-01T01:00:00Z",
"description": "Service from 2019-01-01 through 2019-12-31",
"type": "invoice",
"service_end_at": "2000-01-01T01:00:00Z",
"service_start_at": "2000-01-01T01:00:00Z",
"updated_at": "2000-01-01T01:00:00Z",
"plan": "Enterprise",
"site": "My site"
}
],
"method": "paypal",
"payment_line_items": [
{
"amount": 1.0,
"created_at": "2000-01-01T01:00:00Z",
"invoice_id": 1,
"payment_id": 1,
"updated_at": "2000-01-01T01:00:00Z"
}
],
"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 type="float">1.0</amount>
<balance type="float">1.0</balance>
<created_at>2000-01-01T01:00:00Z</created_at>
<currency>USD</currency>
<download_uri>https://url...</download_uri>
<invoice_line_items type="array">
<invoice_line_item>
<amount type="float">1.0</amount>
<created_at>2000-01-01T01:00:00Z</created_at>
<description>Service from 2019-01-01 through 2019-12-31</description>
<type>invoice</type>
<service_end_at>2000-01-01T01:00:00Z</service_end_at>
<service_start_at>2000-01-01T01:00:00Z</service_start_at>
<updated_at>2000-01-01T01:00:00Z</updated_at>
<plan>Enterprise</plan>
<site>My site</site>
</invoice_line_item>
</invoice_line_items>
<method>paypal</method>
<payment_line_items type="array">
<payment_line_item>
<amount type="float">1.0</amount>
<created_at>2000-01-01T01:00:00Z</created_at>
<invoice_id type="integer">1</invoice_id>
<payment_id type="integer">1</payment_id>
<updated_at>2000-01-01T01:00:00Z</updated_at>
</payment_line_item>
</payment_line_items>
<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 |
|---|---|
| cursor string | Used for pagination. Send a cursor value 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-Next header. |
| per_page int64 | Number of records to show per page. (Max: 10,000, 1,000 or less is recommended). |
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\Model\Invoice::find($id);
[]
Invoice.find(, parametersasdf
await Invoice.find(id)
Invoice.Find(id);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.invoice.find(id)
Example Response
{
"id": 1,
"amount": 1.0,
"balance": 1.0,
"created_at": "2000-01-01T01:00:00Z",
"currency": "USD",
"download_uri": "https://url...",
"invoice_line_items": [
{
"amount": 1.0,
"created_at": "2000-01-01T01:00:00Z",
"description": "Service from 2019-01-01 through 2019-12-31",
"type": "invoice",
"service_end_at": "2000-01-01T01:00:00Z",
"service_start_at": "2000-01-01T01:00:00Z",
"updated_at": "2000-01-01T01:00:00Z",
"plan": "Enterprise",
"site": "My site"
}
],
"method": "paypal",
"payment_line_items": [
{
"amount": 1.0,
"created_at": "2000-01-01T01:00:00Z",
"invoice_id": 1,
"payment_id": 1,
"updated_at": "2000-01-01T01:00:00Z"
}
],
"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 type="float">1.0</amount>
<balance type="float">1.0</balance>
<created_at>2000-01-01T01:00:00Z</created_at>
<currency>USD</currency>
<download_uri>https://url...</download_uri>
<invoice_line_items type="array">
<invoice_line_item>
<amount type="float">1.0</amount>
<created_at>2000-01-01T01:00:00Z</created_at>
<description>Service from 2019-01-01 through 2019-12-31</description>
<type>invoice</type>
<service_end_at>2000-01-01T01:00:00Z</service_end_at>
<service_start_at>2000-01-01T01:00:00Z</service_start_at>
<updated_at>2000-01-01T01:00:00Z</updated_at>
<plan>Enterprise</plan>
<site>My site</site>
</invoice_line_item>
</invoice_line_items>
<method>paypal</method>
<payment_line_items type="array">
<payment_line_item>
<amount type="float">1.0</amount>
<created_at>2000-01-01T01:00:00Z</created_at>
<invoice_id type="integer">1</invoice_id>
<payment_id type="integer">1</payment_id>
<updated_at>2000-01-01T01:00:00Z</updated_at>
</payment_line_item>
</payment_line_items>
<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\Model\Payment::find($id);
[]
Payment.find(, parametersasdf
await Payment.find(id)
Payment.Find(id);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.payment.find(id)
Example Response
{
"id": 1,
"amount": 1.0,
"balance": 1.0,
"created_at": "2000-01-01T01:00:00Z",
"currency": "USD",
"download_uri": "https://url...",
"invoice_line_items": [
{
"amount": 1.0,
"created_at": "2000-01-01T01:00:00Z",
"description": "Service from 2019-01-01 through 2019-12-31",
"type": "invoice",
"service_end_at": "2000-01-01T01:00:00Z",
"service_start_at": "2000-01-01T01:00:00Z",
"updated_at": "2000-01-01T01:00:00Z",
"plan": "Enterprise",
"site": "My site"
}
],
"method": "paypal",
"payment_line_items": [
{
"amount": 1.0,
"created_at": "2000-01-01T01:00:00Z",
"invoice_id": 1,
"payment_id": 1,
"updated_at": "2000-01-01T01:00:00Z"
}
],
"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 type="float">1.0</amount>
<balance type="float">1.0</balance>
<created_at>2000-01-01T01:00:00Z</created_at>
<currency>USD</currency>
<download_uri>https://url...</download_uri>
<invoice_line_items type="array">
<invoice_line_item>
<amount type="float">1.0</amount>
<created_at>2000-01-01T01:00:00Z</created_at>
<description>Service from 2019-01-01 through 2019-12-31</description>
<type>invoice</type>
<service_end_at>2000-01-01T01:00:00Z</service_end_at>
<service_start_at>2000-01-01T01:00:00Z</service_start_at>
<updated_at>2000-01-01T01:00:00Z</updated_at>
<plan>Enterprise</plan>
<site>My site</site>
</invoice_line_item>
</invoice_line_items>
<method>paypal</method>
<payment_line_items type="array">
<payment_line_item>
<amount type="float">1.0</amount>
<created_at>2000-01-01T01:00:00Z</created_at>
<invoice_id type="integer">1</invoice_id>
<payment_id type="integer">1</payment_id>
<updated_at>2000-01-01T01:00:00Z</updated_at>
</payment_line_item>
</payment_line_items>
<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.
This set of endpoints only provides access to recent actions (actions created within 24 hours). In most cases, you would be better served to create a Webhook, which sends actions to your server, rather than poll this endpoint.
The HistoryExport set of endpoints provides a richer ability to query and filter, as well as search the entire lifetime of your history log.
The Action object
Example Action Object
{
"id": 1,
"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>
<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, country_mismatch |
| interface string | Interface on which this action occurred. Possible values: web, ftp, robot, jsapi, webdesktopapi, sftp, dav, desktop, restapi, scim, office |
List history for specific file
Example Request
curl "https://app.files.com/api/rest/v1/history/files/{path}?display=Actual text of the action here.&per_page=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/history/files/{path}?display=Actual text of the action here.&per_page=1" \
-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.",
per_page: 1
)
\Files\Model\History::listForFile($path, array(
'display' => "Actual text of the action here.",
'per_page' => 1
));
["HashMap<Object, String> requestParams = new HashMap<>();\n"]requestParams.put("display", Actual text of the action here.);
requestParams.put("per_page", 1);
History.listForFile(parameters)
await History.listForFile(path, {
display: "Actual text of the action here.",
per_page: 1,
})
var parameters = new Dictionary<string, object>();
parameters.Add("display", "Actual text of the action here.");
parameters.Add("per_page", 1);
History.ListForFile(path, parameters);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.history.list_for_file(path, {
"display": "Actual text of the action here.",
"per_page": 1
})
Example Response
[
{
"id": 1,
"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>
<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. |
| cursor string | Used for pagination. Send a cursor value 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-Next header. |
| per_page int64 | Number of records to show per page. (Max: 10,000, 1,000 or less is recommended). |
| sort_by object | If set, sort records by the specified field in either 'asc' or 'desc' direction (e.g. sort_by[last_login_at]=desc). Valid fields are user_id and created_at. |
| 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}?display=Actual text of the action here.&per_page=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/history/folders/{path}?display=Actual text of the action here.&per_page=1" \
-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.",
per_page: 1
)
\Files\Model\History::listForFolder($path, array(
'display' => "Actual text of the action here.",
'per_page' => 1
));
["HashMap<Object, String> requestParams = new HashMap<>();\n"]requestParams.put("display", Actual text of the action here.);
requestParams.put("per_page", 1);
History.listForFolder(parameters)
await History.listForFolder(path, {
display: "Actual text of the action here.",
per_page: 1,
})
var parameters = new Dictionary<string, object>();
parameters.Add("display", "Actual text of the action here.");
parameters.Add("per_page", 1);
History.ListForFolder(path, parameters);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.history.list_for_folder(path, {
"display": "Actual text of the action here.",
"per_page": 1
})
Example Response
[
{
"id": 1,
"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>
<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. |
| cursor string | Used for pagination. Send a cursor value 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-Next header. |
| per_page int64 | Number of records to show per page. (Max: 10,000, 1,000 or less is recommended). |
| sort_by object | If set, sort records by the specified field in either 'asc' or 'desc' direction (e.g. sort_by[last_login_at]=desc). Valid fields are user_id and created_at. |
| 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.&per_page=1" \
-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.&per_page=1" \
-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.",
per_page: 1
)
\Files\Model\History::listForUser($user_id, array(
'display' => "Actual text of the action here.",
'per_page' => 1
));
["HashMap<Object, String> requestParams = new HashMap<>();\n"]requestParams.put("display", Actual text of the action here.);
requestParams.put("per_page", 1);
History.listForUser(parameters)
await History.listForUser(user_id, {
display: "Actual text of the action here.",
per_page: 1,
})
var parameters = new Dictionary<string, object>();
parameters.Add("display", "Actual text of the action here.");
parameters.Add("per_page", 1);
History.ListForUser(user_id, parameters);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.history.list_for_user(user_id, {
"display": "Actual text of the action here.",
"per_page": 1
})
Example Response
[
{
"id": 1,
"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>
<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. |
| cursor string | Used for pagination. Send a cursor value 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-Next header. |
| per_page int64 | Number of records to show per page. (Max: 10,000, 1,000 or less is recommended). |
| sort_by object | If set, sort records by the specified field in either 'asc' or 'desc' direction (e.g. sort_by[last_login_at]=desc). Valid fields are user_id and created_at. |
| user_id int64 Required | User ID. |
List site login history
Example Request
curl "https://app.files.com/api/rest/v1/history/login.json?display=Actual text of the action here.&per_page=1" \
-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.&per_page=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::History.list_logins(
display: "Actual text of the action here.",
per_page: 1
)
\Files\Model\History::listLogins(array(
'display' => "Actual text of the action here.",
'per_page' => 1
));
["HashMap<Object, String> requestParams = new HashMap<>();\n"]requestParams.put("display", Actual text of the action here.);
requestParams.put("per_page", 1);
History.listLogins(parameters)
await History.listLogins({
display: "Actual text of the action here.",
per_page: 1,
})
var parameters = new Dictionary<string, object>();
parameters.Add("display", "Actual text of the action here.");
parameters.Add("per_page", 1);
History.ListLogins(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.history.list_logins({
"display": "Actual text of the action here.",
"per_page": 1
})
Example Response
[
{
"id": 1,
"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>
<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. |
| cursor string | Used for pagination. Send a cursor value 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-Next header. |
| per_page int64 | Number of records to show per page. (Max: 10,000, 1,000 or less is recommended). |
| sort_by object | If set, sort records by the specified field in either 'asc' or 'desc' direction (e.g. sort_by[last_login_at]=desc). Valid fields are user_id and created_at. |
List site full action history
Example Request
curl "https://app.files.com/api/rest/v1/history.json?display=Actual text of the action here.&per_page=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/history.xml?display=Actual text of the action here.&per_page=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::History.list(
display: "Actual text of the action here.",
per_page: 1
)
\Files\Model\History::list(array(
'display' => "Actual text of the action here.",
'per_page' => 1
));
["HashMap<Object, String> requestParams = new HashMap<>();\n"]requestParams.put("display", Actual text of the action here.);
requestParams.put("per_page", 1);
History.list(parameters)
await History.list({
display: "Actual text of the action here.",
per_page: 1,
})
var parameters = new Dictionary<string, object>();
parameters.Add("display", "Actual text of the action here.");
parameters.Add("per_page", 1);
History.List(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.history.list({
"display": "Actual text of the action here.",
"per_page": 1
})
Example Response
[
{
"id": 1,
"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>
<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. |
| cursor string | Used for pagination. Send a cursor value 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-Next header. |
| per_page int64 | Number of records to show per page. (Max: 10,000, 1,000 or less is recommended). |
| sort_by object | If set, sort records by the specified field in either 'asc' or 'desc' direction (e.g. sort_by[last_login_at]=desc). Valid fields are path, folder, user_id or created_at. |
| filter object | If set, return records where the specifiied field is equal to the supplied value. Valid fields are user_id, folder or path. |
| filter_gt object | If set, return records where the specifiied field is greater than the supplied value. Valid fields are user_id, folder or path. |
| filter_gteq object | If set, return records where the specifiied field is greater than or equal to the supplied value. Valid fields are user_id, folder or path. |
| filter_like object | If set, return records where the specifiied field is equal to the supplied value. Valid fields are user_id, folder or path. |
| filter_lt object | If set, return records where the specifiied field is less than the supplied value. Valid fields are user_id, folder or path. |
| filter_lteq object | If set, return records where the specifiied field is less than or equal to the supplied value. Valid fields are user_id, folder or path. |
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",
"path": "shared/docs",
"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>
<path>shared/docs</path>
<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. |
| path string | Folder path restriction for this api key. This must be slash-delimited, but it must neither start nor end with a slash. Maximum of 5000 characters. |
| 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). Additional permission sets may become available 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, office_integration |
| 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&per_page=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/api_keys.xml?user_id=1&per_page=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::ApiKey.list(
user_id: 1,
per_page: 1
)
\Files\Model\ApiKey::list(array(
'user_id' => 1,
'per_page' => 1
));
["HashMap<Object, String> requestParams = new HashMap<>();\n"]requestParams.put("user_id", 1);
requestParams.put("per_page", 1);
ApiKey.list(parameters)
await ApiKey.list({
user_id: 1,
per_page: 1,
})
var parameters = new Dictionary<string, object>();
parameters.Add("user_id", 1);
parameters.Add("per_page", 1);
ApiKey.List(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.api_key.list({
"user_id": 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",
"path": "shared/docs",
"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>
<path>shared/docs</path>
<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. |
| cursor string | Used for pagination. Send a cursor value 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-Next header. |
| per_page int64 | Number of records to show per page. (Max: 10,000, 1,000 or less is recommended). |
| sort_by object | If set, sort records by the specified field in either 'asc' or 'desc' direction (e.g. sort_by[last_login_at]=desc). Valid fields are expires_at. |
| filter object | If set, return records where the specifiied field is equal to the supplied value. Valid fields are expires_at. |
| filter_gt object | If set, return records where the specifiied field is greater than the supplied value. Valid fields are expires_at. |
| filter_gteq object | If set, return records where the specifiied field is greater than or equal to the supplied value. Valid fields are expires_at. |
| filter_like object | If set, return records where the specifiied field is equal to the supplied value. Valid fields are expires_at. |
| filter_lt object | If set, return records where the specifiied field is less than the supplied value. Valid fields are expires_at. |
| filter_lteq object | If set, return records where the specifiied field is less than or equal to the supplied value. Valid fields are expires_at. |
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?format=&api_key=" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/api_key.xml?format=&api_key=" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::ApiKey.find_current(
format: "",
api_key: ""
)
\Files\Model\ApiKey::findCurrent(array(
'format' => "",
'api_key' => ""
));
["HashMap<Object, String> requestParams = new HashMap<>();\n"]requestParams.put("format", );
requestParams.put("api_key", );
ApiKey.findCurrent(parameters)
await ApiKey.findCurrent({
format: "",
api_key: "",
})
var parameters = new Dictionary<string, object>();
parameters.Add("format", "");
parameters.Add("api_key", "");
ApiKey.FindCurrent(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.api_key.find_current({
"format": "",
"api_key": ""
})
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",
"path": "shared/docs",
"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>
<path>shared/docs</path>
<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.
Request Parameters
| Parameter | Description |
|---|---|
| format string | |
| api_key object |
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\Model\ApiKey::find($id);
[]
ApiKey.find(, parametersasdf
await ApiKey.find(id)
ApiKey.Find(id);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.api_key.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",
"path": "shared/docs",
"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>
<path>shared/docs</path>
<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 Main API Key","expires_at":"2000-01-01T01:00:00Z","permission_set":"full","path":"shared/docs"}' \
-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 Main API Key</name>
<expires_at>2000-01-01T01:00:00Z</expires_at>
<permission_set>full</permission_set>
<path>shared/docs</path>
</api-key>'
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::ApiKey.create(
user_id: 1,
name: "My Main API Key",
expires_at: "2000-01-01T01:00:00Z",
permission_set: "full",
path: "shared/docs"
)
\Files\Model\ApiKey::create(array(
'user_id' => 1,
'name' => "My Main API Key",
'expires_at' => "2000-01-01T01:00:00Z",
'permission_set' => "full",
'path' => "shared/docs"
));
["HashMap<Object, String> requestParams = new HashMap<>();\n"]requestParams.put("user_id", 1);
requestParams.put("name", My Main API Key);
requestParams.put("expires_at", 2000-01-01T01:00:00Z);
requestParams.put("permission_set", full);
requestParams.put("path", shared/docs);
ApiKey.create(parameters)
await ApiKey.create({
user_id: 1,
name: "My Main API Key",
expires_at: "2000-01-01T01:00:00Z",
permission_set: "full",
path: "shared/docs",
})
var parameters = new Dictionary<string, object>();
parameters.Add("user_id", 1);
parameters.Add("name", "My Main API Key");
parameters.Add("expires_at", "2000-01-01T01:00:00Z");
parameters.Add("permission_set", "full");
parameters.Add("path", "shared/docs");
ApiKey.Create(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.api_key.create({
"user_id": 1,
"name": "My Main API Key",
"expires_at": "2000-01-01T01:00:00Z",
"permission_set": "full",
"path": "shared/docs"
})
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",
"path": "shared/docs",
"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>
<path>shared/docs</path>
<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 the API Key. For your use. |
| expires_at string | API Key expiration date |
| 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). Additional permission sets may become available 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, office_integration |
| path string | Folder path restriction for this api key. |
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 '{"expires_at":"2000-01-01T01:00:00Z","name":"My Main API Key","permission_set":"full"}' \
-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>
<expires_at>2000-01-01T01:00:00Z</expires_at>
<name>My Main API Key</name>
<permission_set>full</permission_set>
</api-key>'
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::ApiKey.update_current(
expires_at: "2000-01-01T01:00:00Z",
name: "My Main API Key",
permission_set: "full"
)
\Files\Model\ApiKey::updateCurrent(array(
'expires_at' => "2000-01-01T01:00:00Z",
'name' => "My Main API Key",
'permission_set' => "full"
));
["HashMap<Object, String> requestParams = new HashMap<>();\n"]requestParams.put("expires_at", 2000-01-01T01:00:00Z);
requestParams.put("name", My Main API Key);
requestParams.put("permission_set", full);
ApiKey.updateCurrent(parameters)
await ApiKey.updateCurrent({
expires_at: "2000-01-01T01:00:00Z",
name: "My Main API Key",
permission_set: "full",
})
var parameters = new Dictionary<string, object>();
parameters.Add("expires_at", "2000-01-01T01:00:00Z");
parameters.Add("name", "My Main API Key");
parameters.Add("permission_set", "full");
ApiKey.UpdateCurrent(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.api_key.update_current({
"expires_at": "2000-01-01T01:00:00Z",
"name": "My Main API Key",
"permission_set": "full"
})
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",
"path": "shared/docs",
"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>
<path>shared/docs</path>
<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 |
|---|---|
| expires_at string | API Key expiration date |
| 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). Additional permission sets may become available 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, office_integration |
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 Main API Key","expires_at":"2000-01-01T01:00:00Z","permission_set":"full"}' \
-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 Main API Key</name>
<expires_at>2000-01-01T01:00:00Z</expires_at>
<permission_set>full</permission_set>
</api-key>'
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
api_key = Files::ApiKey.list_for(path).first
api_key.update(
name: "My Main API Key",
expires_at: "2000-01-01T01:00:00Z",
permission_set: "full"
)
$api_key = \Files\Model\ApiKey::listFor($path)[0];
$api_key->update(array(
'name' => "My Main API Key",
'expires_at' => "2000-01-01T01:00:00Z",
'permission_set' => "full"
));
ApiKey apiKey = ApiKey.listFor(path);
apiKey.setName("My Main API Key");
apiKey.setExpiresAt("2000-01-01T01:00:00Z");
apiKey.setPermissionSet("full");
apiKey.update();
const apiKey = (await ApiKey.listFor(path))[0]
await apiKey.update({
name: "My Main API Key",
expires_at: "2000-01-01T01:00:00Z",
permission_set: "full",
})
var ApiKey = ApiKey.ListFor(path)[0];
var parameters = new Dictionary<string, object>();
parameters.Add("name", "My Main API Key");
parameters.Add("expires_at", "2000-01-01T01:00:00Z");
parameters.Add("permission_set", "full");
ApiKey.Update(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
api_key = files_sdk.api_key.find(id)
api_key.update({
name: "My Main API Key",
expires_at: "2000-01-01T01:00:00Z",
permission_set: "full"
})
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",
"path": "shared/docs",
"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>
<path>shared/docs</path>
<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 the API Key. For your use. |
| expires_at string | API Key expiration date |
| 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). Additional permission sets may become available 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, office_integration |
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?format=&api_key=" \
-X DELETE \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/api_key.xml?format=&api_key=" \
-X DELETE \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::ApiKey.delete_current(
format: "",
api_key: ""
)
\Files\Model\ApiKey::deleteCurrent(array(
'format' => "",
'api_key' => ""
));
["HashMap<Object, String> requestParams = new HashMap<>();\n"]requestParams.put("format", );
requestParams.put("api_key", );
ApiKey.deleteCurrent(parameters)
await ApiKey.deleteCurrent({
format: "",
api_key: "",
})
var parameters = new Dictionary<string, object>();
parameters.Add("format", "");
parameters.Add("api_key", "");
ApiKey.DeleteCurrent(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.api_key.delete_current({
"format": "",
"api_key": ""
})
Example Response
No response.
No response.
HTTPS Request
DELETE /api_key
Authentication Required
Available to all authenticated keys or sessions.
Request Parameters
| Parameter | Description |
|---|---|
| format string | |
| api_key object |
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.list_for(path).first
api_key.delete
$api_key = \Files\Model\ApiKey::listFor($path)[0];
$api_key->delete();
ApiKey apiKey = ApiKey.listFor(path);
apiKey.delete();
const apiKey = (await ApiKey.listFor(path))[0]
await apiKey.delete()
var ApiKey = ApiKey.ListFor(path)[0];
ApiKey.Delete();
files_sdk.set_api_key("YOUR_API_KEY")
api_key = files_sdk.api_key.find(id)
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. |
Apps
Apps are the API/SDK term for the various integrations provided by Files.com.
If you have an idea for a new integration, please let us know as we are continuously adding to this list.
The App object
Example App Object
{
"name": "",
"extended_description": "",
"documentation_links": "Important Info => http://files.test/learn-more",
"icon_url": "",
"logo_url": "",
"screenshot_list_urls": [
""
],
"logo_thumbnail_url": "",
"sso_strategy_type": "",
"remote_server_type": "",
"folder_behavior_type": "",
"external_homepage_url": "",
"app_type": "",
"featured": true
}
<?xml version="1.0" encoding="UTF-8"?>
<app>
<name></name>
<extended_description></extended_description>
<documentation_links>Important Info => http://files.test/learn-more</documentation_links>
<icon_url></icon_url>
<logo_url></logo_url>
<screenshot_list_urls type="array">
<screenshot_list_url></screenshot_list_url>
</screenshot_list_urls>
<logo_thumbnail_url></logo_thumbnail_url>
<sso_strategy_type></sso_strategy_type>
<remote_server_type></remote_server_type>
<folder_behavior_type></folder_behavior_type>
<external_homepage_url></external_homepage_url>
<app_type></app_type>
<featured type="boolean">true</featured>
</app>
| Attribute | Description |
|---|---|
| name string | Name of the App |
| extended_description string | Long form description of the App |
| documentation_links string | Collection of named links to documentation |
| icon_url string | App icon |
| logo_url string | Full size logo for the App |
| screenshot_list_urls string | Screenshots of the App |
| logo_thumbnail_url string | Logo thumbnail for the App |
| sso_strategy_type string | Associated SSO Strategy type, if any Possible values: google, auth0, okta, atlassian, azure, box, dropbox, slack, ubuntu, onelogin, saml, idaptive, ldap, scim |
| remote_server_type string | Associated Remote Server type, if any Possible values: ftp, sftp, s3, google_cloud_storage, webdav, wasabi, backblaze_b2, one_drive, rackspace, box, dropbox, google_drive, azure |
| folder_behavior_type string | Associated Folder Behavior type, if any Possible values: webhook, file_expiration, auto_encrypt, lock_subfolders, storage_region, serve_publicly, create_user_folders, remote_server_sync, inbox, append_timestamp, limit_file_extensions, limit_file_regex, amazon_sns, watermark, remote_server_mount, slack_webhook |
| external_homepage_url string | Link to external homepage |
| app_type string | The type of the App Possible values: sdk, sso, remote_server, folder_behavior, client_app, app_integration |
| featured boolean | Is featured on the App listing? |
List Apps
Example Request
curl "https://app.files.com/api/rest/v1/apps.json?per_page=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/apps.xml?per_page=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::App.list(
per_page: 1
)
\Files\Model\App::list(array(
'per_page' => 1
));
["HashMap<Object, String> requestParams = new HashMap<>();\n"]requestParams.put("per_page", 1);
App.list(parameters)
await App.list({
per_page: 1,
})
var parameters = new Dictionary<string, object>();
parameters.Add("per_page", 1);
App.List(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.app.list({
"per_page": 1
})
Example Response
[
{
"name": "",
"extended_description": "",
"documentation_links": "Important Info => http://files.test/learn-more",
"icon_url": "",
"logo_url": "",
"screenshot_list_urls": [
""
],
"logo_thumbnail_url": "",
"sso_strategy_type": "",
"remote_server_type": "",
"folder_behavior_type": "",
"external_homepage_url": "",
"app_type": "",
"featured": true
}
]
<?xml version="1.0" encoding="UTF-8"?>
<apps type="array">
<app>
<name></name>
<extended_description></extended_description>
<documentation_links>Important Info => http://files.test/learn-more</documentation_links>
<icon_url></icon_url>
<logo_url></logo_url>
<screenshot_list_urls type="array">
<screenshot_list_url></screenshot_list_url>
</screenshot_list_urls>
<logo_thumbnail_url></logo_thumbnail_url>
<sso_strategy_type></sso_strategy_type>
<remote_server_type></remote_server_type>
<folder_behavior_type></folder_behavior_type>
<external_homepage_url></external_homepage_url>
<app_type></app_type>
<featured type="boolean">true</featured>
</app>
</apps>
HTTPS Request
GET /apps
Authentication Required
Available to all authenticated keys or sessions.
Request Parameters
| Parameter | Description |
|---|---|
| cursor string | Used for pagination. Send a cursor value 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-Next header. |
| per_page int64 | Number of records to show per page. (Max: 10,000, 1,000 or less is recommended). |
| sort_by object | If set, sort records by the specified field in either 'asc' or 'desc' direction (e.g. sort_by[last_login_at]=desc). Valid fields are name and app_type. |
| filter object | If set, return records where the specifiied field is equal to the supplied value. Valid fields are name and app_type. |
| filter_gt object | If set, return records where the specifiied field is greater than the supplied value. Valid fields are name and app_type. |
| filter_gteq object | If set, return records where the specifiied field is greater than or equal to the supplied value. Valid fields are name and app_type. |
| filter_like object | If set, return records where the specifiied field is equal to the supplied value. Valid fields are name and app_type. |
| filter_lt object | If set, return records where the specifiied field is less than the supplied value. Valid fields are name and app_type. |
| filter_lteq object | If set, return records where the specifiied field is less than or equal to the supplied value. Valid fields are name and app_type. |
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&per_page=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/as2_keys.xml?user_id=1&per_page=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::As2Key.list(
user_id: 1,
per_page: 1
)
\Files\Model\As2Key::list(array(
'user_id' => 1,
'per_page' => 1
));
["HashMap<Object, String> requestParams = new HashMap<>();\n"]requestParams.put("user_id", 1);
requestParams.put("per_page", 1);
As2Key.list(parameters)
await As2Key.list({
user_id: 1,
per_page: 1,
})
var parameters = new Dictionary<string, object>();
parameters.Add("user_id", 1);
parameters.Add("per_page", 1);
As2Key.List(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.as2_key.list({
"user_id": 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. |
| cursor string | Used for pagination. Send a cursor value 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-Next header. |
| per_page int64 | Number of records to show per page. (Max: 10,000, 1,000 or less is recommended). |
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\Model\As2Key::find($id);
[]
As2Key.find(, parametersasdf
await As2Key.find(id)
As2Key.Find(id);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.as2_key.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\Model\As2Key::create(array(
'user_id' => 1,
'as2_partnership_name' => "Test",
'public_key' => "public_key"
));
["HashMap<Object, String> requestParams = new HashMap<>();\n"]requestParams.put("user_id", 1);
requestParams.put("as2_partnership_name", Test);
requestParams.put("public_key", public_key);
As2Key.create(parameters)
await As2Key.create({
user_id: 1,
as2_partnership_name: "Test",
public_key: "public_key",
})
var parameters = new Dictionary<string, object>();
parameters.Add("user_id", 1);
parameters.Add("as2_partnership_name", "Test");
parameters.Add("public_key", "public_key");
As2Key.Create(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.as2_key.create({
"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.list_for(path).first
as2_key.update(
as2_partnership_name: "Test"
)
$as2_key = \Files\Model\As2Key::listFor($path)[0];
$as2_key->update(array(
'as2_partnership_name' => "Test"
));
As2Key as2Key = As2Key.listFor(path);
as2Key.setAs2PartnershipName("Test");
as2Key.update();
const as2Key = (await As2Key.listFor(path))[0]
await as2Key.update({
as2_partnership_name: "Test",
})
var As2Key = As2Key.ListFor(path)[0];
var parameters = new Dictionary<string, object>();
parameters.Add("as2_partnership_name", "Test");
As2Key.Update(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
as2_key = files_sdk.as2_key.find(id)
as2_key.update({
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.list_for(path).first
as2_key.delete
$as2_key = \Files\Model\As2Key::listFor($path)[0];
$as2_key->delete();
As2Key as2Key = As2Key.listFor(path);
as2Key.delete();
const as2Key = (await As2Key.listFor(path))[0]
await as2Key.delete()
var As2Key = As2Key.ListFor(path)[0];
As2Key.Delete();
files_sdk.set_api_key("YOUR_API_KEY")
as2_key = files_sdk.as2_key.find(id)
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.
Automations can be triggered in realtime (i.e. they would run as soon as something else happens that creates the circumstance for a path to match the Automation), or they can be triggered via a schedule. Future enhancements will allow Automations to be triggered by an incoming Webhook or E-Mail.
Automation Types
There are currently five types of automations: Create Folder, Copy Newest File, Delete File, Request File, and Request Move.
Create Folder
Creates the folder with named by destination in the path named by path.
Destination may include formatting parameters to insert the date/time into the destination name.
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:
- Trigger:
daily - Interval:
quarter_end - Path:
/AccountingAndTax/SalesTax/State/*/ - Destination:
%Y/Quarter-ending-%m-%d
Delete File
Deletes the file with path matching source (wildcards allowed) in the path named by path.
This automation does not currently support Realtime triggering, as this would delete the file immediately when the file was uploaded. If you have a legitimate use case for needing Realtime triggering on this automation, please let us know.
Copy Newest File
Copies the newest file in the folder named by path to the path specified in destination.
If the parameter source exists, the automation will only fire on files matching the source (wildcards allowed).
This automation does not currently support Realtime triggering, but we intend to add this functionality in the future.
Request File
The Request File automation requests a file (optionally from a specific user) if it does not exist.
It requests the file named in the parameter destination in the path named by the parameter path.
If the parameter source exists, the automation will only fire if a file in that path exists.
Destination may include formatting parameters that are backreferences to the path.
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:
- Trigger:
realtime - 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:
- Trigger:
realtime - 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:
- Trigger:
realtime - 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
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:
- Trigger:
realtime - 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",
"trigger": "realtime",
"interval": "week",
"next_process_on": "2020-01-01",
"schedule": {
"days_of_week": [
0,
2,
4
],
"times_of_day": [
"6:30",
"14:30"
],
"time_zone": "Eastern Time (US & Canada)"
},
"source": "",
"destination": "",
"destination_replace_from": "",
"destination_replace_to": "",
"path": "",
"user_id": 1,
"user_ids": [
1,
2
],
"group_ids": [
1,
2
],
"webhook_url": "https://app.files.com/api/webhooks/abc123",
"trigger_actions": "[ \"create\" ]",
"trigger_action_path": "path/to/file/or/folder"
}
<?xml version="1.0" encoding="UTF-8"?>
<automation>
<id type="integer">1</id>
<automation>create_folder</automation>
<trigger>realtime</trigger>
<interval>week</interval>
<next_process_on>2020-01-01</next_process_on>
<schedule>
<days_of_week type="array">
<days_of_week type="integer">0</days_of_week>
<days_of_week type="integer">2</days_of_week>
<days_of_week type="integer">4</days_of_week>
</days_of_week>
<times_of_day type="array">
<times_of_day>6:30</times_of_day>
<times_of_day>14:30</times_of_day>
</times_of_day>
<time_zone>Eastern Time (US & Canada)</time_zone>
</schedule>
<source></source>
<destination></destination>
<destination_replace_from></destination_replace_from>
<destination_replace_to></destination_replace_to>
<path></path>
<user_id type="integer">1</user_id>
<user_ids type="array">
<user_id type="integer">1</user_id>
<user_id type="integer">2</user_id>
</user_ids>
<group_ids type="array">
<group_id type="integer">1</group_id>
<group_id type="integer">2</group_id>
</group_ids>
<webhook_url>https://app.files.com/api/webhooks/abc123</webhook_url>
<trigger_actions>[ "create" ]</trigger_actions>
<trigger_action_path>path/to/file/or/folder</trigger_action_path>
</automation>
| Attribute | Description |
|---|---|
| id int64 | Automation ID |
| automation string | Automation type Possible values: create_folder, request_file, request_move, copy_newest_file, delete_file, copy_file |
| trigger string | How this automation is triggered to run. One of: realtime, daily, custom_schedule, webhook, email, or action. Possible values: realtime, daily, custom_schedule, webhook, email, action |
| interval string | If trigger is daily, this specifies 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 | If trigger is daily, date this automation will next run. |
| schedule object | If trigger is custom_schedule, Custom schedule description for when the automation should be run. |
| 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. |
| 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. |
| 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) |
| webhook_url string | If trigger is webhook, this is the URL of the webhook to trigger the Automation. |
| trigger_actions string | If trigger is action, this is the list of action types on which to trigger the automation. Valid actions are create, read, update, destroy, move, copy |
| trigger_action_path string | If trigger is action, this is the path to watch for the specified trigger actions. |
List Automations
Example Request
curl "https://app.files.com/api/rest/v1/automations.json?per_page=1&automation=create_folder" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/automations.xml?per_page=1&automation=create_folder" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::Automation.list(
per_page: 1,
automation: "create_folder"
)
\Files\Model\Automation::list(array(
'per_page' => 1,
'automation' => "create_folder"
));
["HashMap<Object, String> requestParams = new HashMap<>();\n"]requestParams.put("per_page", 1);
requestParams.put("automation", create_folder);
Automation.list(parameters)
await Automation.list({
per_page: 1,
automation: "create_folder",
})
var parameters = new Dictionary<string, object>();
parameters.Add("per_page", 1);
parameters.Add("automation", "create_folder");
Automation.List(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.automation.list({
"per_page": 1,
"automation": "create_folder"
})
Example Response
[
{
"id": 1,
"automation": "create_folder",
"trigger": "realtime",
"interval": "week",
"next_process_on": "2020-01-01",
"schedule": {
"days_of_week": [
0,
2,
4
],
"times_of_day": [
"6:30",
"14:30"
],
"time_zone": "Eastern Time (US & Canada)"
},
"source": "",
"destination": "",
"destination_replace_from": "",
"destination_replace_to": "",
"path": "",
"user_id": 1,
"user_ids": [
1,
2
],
"group_ids": [
1,
2
],
"webhook_url": "https://app.files.com/api/webhooks/abc123",
"trigger_actions": "[ \"create\" ]",
"trigger_action_path": "path/to/file/or/folder"
}
]
<?xml version="1.0" encoding="UTF-8"?>
<automations type="array">
<automation>
<id type="integer">1</id>
<automation>create_folder</automation>
<trigger>realtime</trigger>
<interval>week</interval>
<next_process_on>2020-01-01</next_process_on>
<schedule>
<days_of_week type="array">
<days_of_week type="integer">0</days_of_week>
<days_of_week type="integer">2</days_of_week>
<days_of_week type="integer">4</days_of_week>
</days_of_week>
<times_of_day type="array">
<times_of_day>6:30</times_of_day>
<times_of_day>14:30</times_of_day>
</times_of_day>
<time_zone>Eastern Time (US & Canada)</time_zone>
</schedule>
<source></source>
<destination></destination>
<destination_replace_from></destination_replace_from>
<destination_replace_to></destination_replace_to>
<path></path>
<user_id type="integer">1</user_id>
<user_ids type="array">
<user_id type="integer">1</user_id>
<user_id type="integer">2</user_id>
</user_ids>
<group_ids type="array">
<group_id type="integer">1</group_id>
<group_id type="integer">2</group_id>
</group_ids>
<webhook_url>https://app.files.com/api/webhooks/abc123</webhook_url>
<trigger_actions>[ "create" ]</trigger_actions>
<trigger_action_path>path/to/file/or/folder</trigger_action_path>
</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 Folder Admin permissions.
Request Parameters
| Parameter | Description |
|---|---|
| cursor string | Used for pagination. Send a cursor value 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-Next header. |
| per_page int64 | Number of records to show per page. (Max: 10,000, 1,000 or less is recommended). |
| sort_by object | If set, sort records by the specified field in either 'asc' or 'desc' direction (e.g. sort_by[last_login_at]=desc). Valid fields are automation. |
| filter object | If set, return records where the specifiied field is equal to the supplied value. Valid fields are automation. |
| filter_gt object | If set, return records where the specifiied field is greater than the supplied value. Valid fields are automation. |
| filter_gteq object | If set, return records where the specifiied field is greater than or equal to the supplied value. Valid fields are automation. |
| filter_like object | If set, return records where the specifiied field is equal to the supplied value. Valid fields are automation. |
| filter_lt object | If set, return records where the specifiied field is less than the supplied value. Valid fields are automation. |
| filter_lteq object | If set, return records where the specifiied field is less than or equal to the supplied value. Valid fields are automation. |
| automation string | DEPRECATED: Type of automation to filter by. Use filter[automation] instead. |
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\Model\Automation::find($id);
[]
Automation.find(, parametersasdf
await Automation.find(id)
Automation.Find(id);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.automation.find(id)
Example Response
{
"id": 1,
"automation": "create_folder",
"trigger": "realtime",
"interval": "week",
"next_process_on": "2020-01-01",
"schedule": {
"days_of_week": [
0,
2,
4
],
"times_of_day": [
"6:30",
"14:30"
],
"time_zone": "Eastern Time (US & Canada)"
},
"source": "",
"destination": "",
"destination_replace_from": "",
"destination_replace_to": "",
"path": "",
"user_id": 1,
"user_ids": [
1,
2
],
"group_ids": [
1,
2
],
"webhook_url": "https://app.files.com/api/webhooks/abc123",
"trigger_actions": "[ \"create\" ]",
"trigger_action_path": "path/to/file/or/folder"
}
<?xml version="1.0" encoding="UTF-8"?>
<automation>
<id type="integer">1</id>
<automation>create_folder</automation>
<trigger>realtime</trigger>
<interval>week</interval>
<next_process_on>2020-01-01</next_process_on>
<schedule>
<days_of_week type="array">
<days_of_week type="integer">0</days_of_week>
<days_of_week type="integer">2</days_of_week>
<days_of_week type="integer">4</days_of_week>
</days_of_week>
<times_of_day type="array">
<times_of_day>6:30</times_of_day>
<times_of_day>14:30</times_of_day>
</times_of_day>
<time_zone>Eastern Time (US & Canada)</time_zone>
</schedule>
<source></source>
<destination></destination>
<destination_replace_from></destination_replace_from>
<destination_replace_to></destination_replace_to>
<path></path>
<user_id type="integer">1</user_id>
<user_ids type="array">
<user_id type="integer">1</user_id>
<user_id type="integer">2</user_id>
</user_ids>
<group_ids type="array">
<group_id type="integer">1</group_id>
<group_id type="integer">2</group_id>
</group_ids>
<webhook_url>https://app.files.com/api/webhooks/abc123</webhook_url>
<trigger_actions>[ "create" ]</trigger_actions>
<trigger_action_path>path/to/file/or/folder</trigger_action_path>
</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 Folder 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","user_ids":[1,2],"group_ids":[1,2],"schedule":"{\"days_of_week\": [ 0, 1, 3 ], \"times_of_day\": [ \"7:30\", \"11:30\" ], \"time_zone\": \"Eastern Time (US & Canada)\"}","trigger":"realtime","trigger_actions":"[ \"create\" ]","trigger_action_path":"path/to/file/or/folder"}' \
-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>
<user_ids type="array">
<user_id type="integer">1</user_id>
<user_id type="integer">2</user_id>
</user_ids>
<group_ids type="array">
<group_id type="integer">1</group_id>
<group_id type="integer">2</group_id>
</group_ids>
<schedule>{"days_of_week": [ 0, 1, 3 ], "times_of_day": [ "7:30", "11:30" ], "time_zone": "Eastern Time (US & Canada)"}</schedule>
<trigger>realtime</trigger>
<trigger_actions>[ "create" ]</trigger_actions>
<trigger_action_path>path/to/file/or/folder</trigger_action_path>
</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",
user_ids: [1,2],
group_ids: [1,2],
schedule: "{\"days_of_week\": [ 0, 1, 3 ], \"times_of_day\": [ \"7:30\", \"11:30\" ], \"time_zone\": \"Eastern Time (US & Canada)\"}",
trigger: "realtime",
trigger_actions: "[ \"create\" ]",
trigger_action_path: "path/to/file/or/folder"
)
\Files\Model\Automation::create(array(
'automation' => "create_folder",
'source' => "source",
'destination' => "destination",
'interval' => "year",
'user_ids' => [1,2],
'group_ids' => [1,2],
'schedule' => "{\"days_of_week\": [ 0, 1, 3 ], \"times_of_day\": [ \"7:30\", \"11:30\" ], \"time_zone\": \"Eastern Time (US & Canada)\"}",
'trigger' => "realtime",
'trigger_actions' => "[ \"create\" ]",
'trigger_action_path' => "path/to/file/or/folder"
));
["HashMap<Object, String> requestParams = new HashMap<>();\n"]requestParams.put("automation", create_folder);
requestParams.put("source", source);
requestParams.put("destination", destination);
requestParams.put("interval", year);
requestParams.put("user_ids", [1, 2]);
requestParams.put("group_ids", [1, 2]);
requestParams.put("schedule", {"days_of_week": [ 0, 1, 3 ], "times_of_day": [ "7:30", "11:30" ], "time_zone": "Eastern Time (US & Canada)"});
requestParams.put("trigger", realtime);
requestParams.put("trigger_actions", [ "create" ]);
requestParams.put("trigger_action_path", path/to/file/or/folder);
Automation.create(parameters)
await Automation.create({
automation: "create_folder",
source: "source",
destination: "destination",
interval: "year",
user_ids: [1,2],
group_ids: [1,2],
schedule: "{\"days_of_week\": [ 0, 1, 3 ], \"times_of_day\": [ \"7:30\", \"11:30\" ], \"time_zone\": \"Eastern Time (US & Canada)\"}",
trigger: "realtime",
trigger_actions: "[ \"create\" ]",
trigger_action_path: "path/to/file/or/folder",
})
var parameters = new Dictionary<string, object>();
parameters.Add("automation", "create_folder");
parameters.Add("source", "source");
parameters.Add("destination", "destination");
parameters.Add("interval", "year");
parameters.Add("user_ids", [1,2]);
parameters.Add("group_ids", [1,2]);
parameters.Add("schedule", "{\"days_of_week\": [ 0, 1, 3 ], \"times_of_day\": [ \"7:30\", \"11:30\" ], \"time_zone\": \"Eastern Time (US & Canada)\"}");
parameters.Add("trigger", "realtime");
parameters.Add("trigger_actions", "[ \"create\" ]");
parameters.Add("trigger_action_path", "path/to/file/or/folder");
Automation.Create(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.automation.create({
"automation": "create_folder",
"source": "source",
"destination": "destination",
"interval": "year",
"user_ids": [1,2],
"group_ids": [1,2],
"schedule": "{\"days_of_week\": [ 0, 1, 3 ], \"times_of_day\": [ \"7:30\", \"11:30\" ], \"time_zone\": \"Eastern Time (US & Canada)\"}",
"trigger": "realtime",
"trigger_actions": "[ \"create\" ]",
"trigger_action_path": "path/to/file/or/folder"
})
Example Response
{
"id": 1,
"automation": "create_folder",
"trigger": "realtime",
"interval": "week",
"next_process_on": "2020-01-01",
"schedule": {
"days_of_week": [
0,
2,
4
],
"times_of_day": [
"6:30",
"14:30"
],
"time_zone": "Eastern Time (US & Canada)"
},
"source": "",
"destination": "",
"destination_replace_from": "",
"destination_replace_to": "",
"path": "",
"user_id": 1,
"user_ids": [
1,
2
],
"group_ids": [
1,
2
],
"webhook_url": "https://app.files.com/api/webhooks/abc123",
"trigger_actions": "[ \"create\" ]",
"trigger_action_path": "path/to/file/or/folder"
}
<?xml version="1.0" encoding="UTF-8"?>
<automation>
<id type="integer">1</id>
<automation>create_folder</automation>
<trigger>realtime</trigger>
<interval>week</interval>
<next_process_on>2020-01-01</next_process_on>
<schedule>
<days_of_week type="array">
<days_of_week type="integer">0</days_of_week>
<days_of_week type="integer">2</days_of_week>
<days_of_week type="integer">4</days_of_week>
</days_of_week>
<times_of_day type="array">
<times_of_day>6:30</times_of_day>
<times_of_day>14:30</times_of_day>
</times_of_day>
<time_zone>Eastern Time (US & Canada)</time_zone>
</schedule>
<source></source>
<destination></destination>
<destination_replace_from></destination_replace_from>
<destination_replace_to></destination_replace_to>
<path></path>
<user_id type="integer">1</user_id>
<user_ids type="array">
<user_id type="integer">1</user_id>
<user_id type="integer">2</user_id>
</user_ids>
<group_ids type="array">
<group_id type="integer">1</group_id>
<group_id type="integer">2</group_id>
</group_ids>
<webhook_url>https://app.files.com/api/webhooks/abc123</webhook_url>
<trigger_actions>[ "create" ]</trigger_actions>
<trigger_action_path>path/to/file/or/folder</trigger_action_path>
</automation>
HTTPS Request
POST /automations
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 |
|---|---|
| automation string Required | Automation type Possible values: create_folder, request_file, request_move, copy_newest_file, delete_file, copy_file |
| 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. |
| schedule object | Custom schedule for running this automation. |
| trigger string | How this automation is triggered to run. One of: realtime, daily, custom_schedule, webhook, email, or action. Possible values: realtime, daily, custom_schedule, webhook, email, action |
| trigger_actions array(string) | If trigger is action, this is the list of action types on which to trigger the automation. Valid actions are create, read, update, destroy, move, copy |
| trigger_action_path string | If trigger is action, this is the path to watch for the specified trigger actions. |
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","user_ids":[1,2],"group_ids":[1,2],"schedule":"{\"days_of_week\": [ 0, 1, 3 ], \"times_of_day\": [ \"7:30\", \"11:30\" ], \"time_zone\": \"Eastern Time (US & Canada)\"}","trigger":"realtime","trigger_actions":"[ \"create\" ]","trigger_action_path":"path/to/file/or/folder"}' \
-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>
<user_ids type="array">
<user_id type="integer">1</user_id>
<user_id type="integer">2</user_id>
</user_ids>
<group_ids type="array">
<group_id type="integer">1</group_id>
<group_id type="integer">2</group_id>
</group_ids>
<schedule>{"days_of_week": [ 0, 1, 3 ], "times_of_day": [ "7:30", "11:30" ], "time_zone": "Eastern Time (US & Canada)"}</schedule>
<trigger>realtime</trigger>
<trigger_actions>[ "create" ]</trigger_actions>
<trigger_action_path>path/to/file/or/folder</trigger_action_path>
</automation>'
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
automation = Files::Automation.list_for(path).first
automation.update(
automation: "create_folder",
source: "source",
destination: "destination",
interval: "year",
user_ids: [1,2],
group_ids: [1,2],
schedule: "{\"days_of_week\": [ 0, 1, 3 ], \"times_of_day\": [ \"7:30\", \"11:30\" ], \"time_zone\": \"Eastern Time (US & Canada)\"}",
trigger: "realtime",
trigger_actions: "[ \"create\" ]",
trigger_action_path: "path/to/file/or/folder"
)
$automation = \Files\Model\Automation::listFor($path)[0];
$automation->update(array(
'automation' => "create_folder",
'source' => "source",
'destination' => "destination",
'interval' => "year",
'user_ids' => [1,2],
'group_ids' => [1,2],
'schedule' => "{\"days_of_week\": [ 0, 1, 3 ], \"times_of_day\": [ \"7:30\", \"11:30\" ], \"time_zone\": \"Eastern Time (US & Canada)\"}",
'trigger' => "realtime",
'trigger_actions' => "[ \"create\" ]",
'trigger_action_path' => "path/to/file/or/folder"
));
Automation automation = Automation.listFor(path);
automation.setAutomation("create_folder");
automation.setSource("source");
automation.setDestination("destination");
automation.setInterval("year");
automation.setUserIds("[1, 2]");
automation.setGroupIds("[1, 2]");
automation.setSchedule({"days_of_week": [ 0, 1, 3 ], "times_of_day": [ "7:30", "11:30" ], "time_zone": "Eastern Time (US & Canada)"});
automation.setTrigger("realtime");
automation.setTriggerActions([ "create" ]);
automation.setTriggerActionPath("path/to/file/or/folder");
automation.update();
const automation = (await Automation.listFor(path))[0]
await automation.update({
automation: "create_folder",
source: "source",
destination: "destination",
interval: "year",
user_ids: [1,2],
group_ids: [1,2],
schedule: "{\"days_of_week\": [ 0, 1, 3 ], \"times_of_day\": [ \"7:30\", \"11:30\" ], \"time_zone\": \"Eastern Time (US & Canada)\"}",
trigger: "realtime",
trigger_actions: "[ \"create\" ]",
trigger_action_path: "path/to/file/or/folder",
})
var Automation = Automation.ListFor(path)[0];
var parameters = new Dictionary<string, object>();
parameters.Add("automation", "create_folder");
parameters.Add("source", "source");
parameters.Add("destination", "destination");
parameters.Add("interval", "year");
parameters.Add("user_ids", [1,2]);
parameters.Add("group_ids", [1,2]);
parameters.Add("schedule", "{\"days_of_week\": [ 0, 1, 3 ], \"times_of_day\": [ \"7:30\", \"11:30\" ], \"time_zone\": \"Eastern Time (US & Canada)\"}");
parameters.Add("trigger", "realtime");
parameters.Add("trigger_actions", "[ \"create\" ]");
parameters.Add("trigger_action_path", "path/to/file/or/folder");
Automation.Update(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
automation = files_sdk.automation.find(id)
automation.update({
automation: "create_folder",
source: "source",
destination: "destination",
interval: "year",
user_ids: [1,2],
group_ids: [1,2],
schedule: "{\"days_of_week\": [ 0, 1, 3 ], \"times_of_day\": [ \"7:30\", \"11:30\" ], \"time_zone\": \"Eastern Time (US & Canada)\"}",
trigger: "realtime",
trigger_actions: "[ \"create\" ]",
trigger_action_path: "path/to/file/or/folder"
})
Example Response
{
"id": 1,
"automation": "create_folder",
"trigger": "realtime",
"interval": "week",
"next_process_on": "2020-01-01",
"schedule": {
"days_of_week": [
0,
2,
4
],
"times_of_day": [
"6:30",
"14:30"
],
"time_zone": "Eastern Time (US & Canada)"
},
"source": "",
"destination": "",
"destination_replace_from": "",
"destination_replace_to": "",
"path": "",
"user_id": 1,
"user_ids": [
1,
2
],
"group_ids": [
1,
2
],
"webhook_url": "https://app.files.com/api/webhooks/abc123",
"trigger_actions": "[ \"create\" ]",
"trigger_action_path": "path/to/file/or/folder"
}
<?xml version="1.0" encoding="UTF-8"?>
<automation>
<id type="integer">1</id>
<automation>create_folder</automation>
<trigger>realtime</trigger>
<interval>week</interval>
<next_process_on>2020-01-01</next_process_on>
<schedule>
<days_of_week type="array">
<days_of_week type="integer">0</days_of_week>
<days_of_week type="integer">2</days_of_week>
<days_of_week type="integer">4</days_of_week>
</days_of_week>
<times_of_day type="array">
<times_of_day>6:30</times_of_day>
<times_of_day>14:30</times_of_day>
</times_of_day>
<time_zone>Eastern Time (US & Canada)</time_zone>
</schedule>
<source></source>
<destination></destination>
<destination_replace_from></destination_replace_from>
<destination_replace_to></destination_replace_to>
<path></path>
<user_id type="integer">1</user_id>
<user_ids type="array">
<user_id type="integer">1</user_id>
<user_id type="integer">2</user_id>
</user_ids>
<group_ids type="array">
<group_id type="integer">1</group_id>
<group_id type="integer">2</group_id>
</group_ids>
<webhook_url>https://app.files.com/api/webhooks/abc123</webhook_url>
<trigger_actions>[ "create" ]</trigger_actions>
<trigger_action_path>path/to/file/or/folder</trigger_action_path>
</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 Folder Admin permissions.
Request Parameters
| Parameter | Description |
|---|---|
| id int64 Required | Automation ID. |
| automation string Required | Automation type Possible values: create_folder, request_file, request_move, copy_newest_file, delete_file, copy_file |
| 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. |
| schedule object | Custom schedule for running this automation. |
| trigger string | How this automation is triggered to run. One of: realtime, daily, custom_schedule, webhook, email, or action. Possible values: realtime, daily, custom_schedule, webhook, email, action |
| trigger_actions array(string) | If trigger is action, this is the list of action types on which to trigger the automation. Valid actions are create, read, update, destroy, move, copy |
| trigger_action_path string | If trigger is action, this is the path to watch for the specified trigger actions. |
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.list_for(path).first
automation.delete
$automation = \Files\Model\Automation::listFor($path)[0];
$automation->delete();
Automation automation = Automation.listFor(path);
automation.delete();
const automation = (await Automation.listFor(path))[0]
await automation.delete()
var Automation = Automation.ListFor(path)[0];
Automation.Delete();
files_sdk.set_api_key("YOUR_API_KEY")
automation = files_sdk.automation.find(id)
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 Folder Admin permissions.
Request Parameters
| Parameter | Description |
|---|---|
| id int64 Required | Automation ID. |
Bandwidth Snapshots
The BandwidthSnapshots resource in the REST API allows you to operate on BandwidthSnapshots.
The BandwidthSnapshot object
Example BandwidthSnapshot Object
{
"id": 1,
"bytes_received": 1.0,
"bytes_sent": 1.0,
"sync_bytes_received": 1.0,
"sync_bytes_sent": 1.0,
"requests_get": 1.0,
"requests_put": 1.0,
"requests_other": 1.0,
"logged_at": "2000-01-01T01:00:00Z",
"created_at": "2000-01-01T01:00:00Z",
"updated_at": "2000-01-01T01:00:00Z"
}
<?xml version="1.0" encoding="UTF-8"?>
<bandwidth-snapshot>
<id type="integer">1</id>
<bytes_received type="float">1.0</bytes_received>
<bytes_sent type="float">1.0</bytes_sent>
<sync_bytes_received type="float">1.0</sync_bytes_received>
<sync_bytes_sent type="float">1.0</sync_bytes_sent>
<requests_get type="float">1.0</requests_get>
<requests_put type="float">1.0</requests_put>
<requests_other type="float">1.0</requests_other>
<logged_at>2000-01-01T01:00:00Z</logged_at>
<created_at>2000-01-01T01:00:00Z</created_at>
<updated_at>2000-01-01T01:00:00Z</updated_at>
</bandwidth-snapshot>
| Attribute | Description |
|---|---|
| id int64 | Site bandwidth ID |
| bytes_received double | Site bandwidth report bytes received |
| bytes_sent double | Site bandwidth report bytes sent |
| sync_bytes_received double | Site sync bandwidth report bytes received |
| sync_bytes_sent double | Site sync bandwidth report bytes sent |
| requests_get double | Site bandwidth report get requests |
| requests_put double | Site bandwidth report put requests |
| requests_other double | Site bandwidth report other requests |
| logged_at date-time | Time the site bandwidth report was logged |
| created_at date-time | Site bandwidth report created at date/time |
| updated_at date-time | The last time this site bandwidth report was updated |
List Bandwidth Snapshots
Example Request
curl "https://app.files.com/api/rest/v1/bandwidth_snapshots.json?per_page=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/bandwidth_snapshots.xml?per_page=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::BandwidthSnapshot.list(
per_page: 1
)
\Files\Model\BandwidthSnapshot::list(array(
'per_page' => 1
));
["HashMap<Object, String> requestParams = new HashMap<>();\n"]requestParams.put("per_page", 1);
BandwidthSnapshot.list(parameters)
await BandwidthSnapshot.list({
per_page: 1,
})
var parameters = new Dictionary<string, object>();
parameters.Add("per_page", 1);
BandwidthSnapshot.List(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.bandwidth_snapshot.list({
"per_page": 1
})
Example Response
[
{
"id": 1,
"bytes_received": 1.0,
"bytes_sent": 1.0,
"sync_bytes_received": 1.0,
"sync_bytes_sent": 1.0,
"requests_get": 1.0,
"requests_put": 1.0,
"requests_other": 1.0,
"logged_at": "2000-01-01T01:00:00Z",
"created_at": "2000-01-01T01:00:00Z",
"updated_at": "2000-01-01T01:00:00Z"
}
]
<?xml version="1.0" encoding="UTF-8"?>
<bandwidth-snapshots type="array">
<bandwidth-snapshot>
<id type="integer">1</id>
<bytes_received type="float">1.0</bytes_received>
<bytes_sent type="float">1.0</bytes_sent>
<sync_bytes_received type="float">1.0</sync_bytes_received>
<sync_bytes_sent type="float">1.0</sync_bytes_sent>
<requests_get type="float">1.0</requests_get>
<requests_put type="float">1.0</requests_put>
<requests_other type="float">1.0</requests_other>
<logged_at>2000-01-01T01:00:00Z</logged_at>
<created_at>2000-01-01T01:00:00Z</created_at>
<updated_at>2000-01-01T01:00:00Z</updated_at>
</bandwidth-snapshot>
</bandwidth-snapshots>
HTTPS Request
GET /bandwidth_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 |
|---|---|
| cursor string | Used for pagination. Send a cursor value 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-Next header. |
| per_page int64 | Number of records to show per page. (Max: 10,000, 1,000 or less is recommended). |
| sort_by object | If set, sort records by the specified field in either 'asc' or 'desc' direction (e.g. sort_by[last_login_at]=desc). Valid fields are logged_at. |
| filter object | If set, return records where the specifiied field is equal to the supplied value. Valid fields are logged_at. |
| filter_gt object | If set, return records where the specifiied field is greater than the supplied value. Valid fields are logged_at. |
| filter_gteq object | If set, return records where the specifiied field is greater than or equal to the supplied value. Valid fields are logged_at. |
| filter_like object | If set, return records where the specifiied field is equal to the supplied value. Valid fields are logged_at. |
| filter_lt object | If set, return records where the specifiied field is less than the supplied value. Valid fields are logged_at. |
| filter_lteq object | If set, return records where the specifiied field is less than or equal to the supplied value. Valid fields are logged_at. |
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 |
| Only one may be set per folder? | No |
| 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
30
| Behavior Details | |
|---|---|
| Behavior type | file_expiration |
| Only one may be set per folder? | Yes |
| 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]",
"armor": "false"
}
| 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. |
armor |
If true, encrypted files are written as ascii text. |
| Behavior Details | |
|---|---|
| Behavior type | auto_encrypt |
| Only one may be set per folder? | Yes |
| 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.
Children Recursive: Do not allow Create/Move/Delete on parent folder, child folders and any descendant folders. Children: Do not allow Create/Move/Delete on parent folder or child folders but do allow on any descendant folders. Self: Do not allow Delete or Rename of this(parent) folder. Do allow Create/Move/Delete on child folders and any descendant folders.
Example Value
{
"level": "children_recursive"
}
| Value Hash Parameters | |
|---|---|
level |
URL key used for the inbox. Can be children_recursive (default), children, self, or none. |
| Behavior Details | |
|---|---|
| Behavior type | lock_subfolders |
| Only one may be set per folder? | Yes |
| Visible to non-admins? | Yes |
| Requires attachment? | No |
| Effect on Child Folders | In effect. Can be overridden by adding a behavior to the child. |
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 |
| Only one may be set per folder? | Yes |
| 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 |
| Only one may be set per folder? | Yes |
| 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,
"new_folder_name": "username"
}
| 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. |
new_folder_name |
What to name the new folder, currently we support 'name' and 'username', name will fall back to username if not present, default value is 'name' |
| Behavior Details | |
|---|---|
| Behavior type | create_user_folders |
| Only one may be set per folder? | No |
| 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 server on a regular basis. Remote servers can be FTP/SFTP servers, Amazon S3/GCP/Azure Blob/Wasabi/Backblaze B2 Buckets, and more. See the RemoteServer object for a full list of the Remote Servers supported.
One-way and two-way sync options are supported.
With this behavior, the Sync between Files.com and the RemoteServer occurs on a schedule. Your plan level determines the frequency of the Sync schedule. Higher plans offer faster sync intervals.
If you want to instead "mount" your RemoteServer for real-time operations within Files.com, please see the RemoteServerMount behavior instead.
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 |
| Only one may be set per folder? | No |
| 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 |
| Only one may be set per folder? | No |
| 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",
"time_zone": "Eastern Time (US & Canada)"
}
| Value Hash Parameters | |
|---|---|
format |
Format for the timestamp. You may use anything accepted by the standard UNIX date command. |
time_zone |
Accepts any valid timezone value from the web interface (e.g. "Eastern Time (US & Canada)") or a UTC offset ("-05:00"). Omit parameter for UTC time. |
| Behavior Details | |
|---|---|
| Behavior type | append_timestamp |
| Only one may be set per folder? | Yes |
| 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
{
"extensions": [
"xls",
"csv"
],
"mode": "whitelist"
}
| Value Hash Parameters | |
|---|---|
extensions |
Array of whitelisted/blacklisted file extensions, depending on mode |
mode |
controls whether the behavior acts as a whitelist or as a blacklist. Default is whitelist. |
| Behavior Details | |
|---|---|
| Behavior type | limit_file_extensions |
| Only one may be set per folder? | Yes |
| 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 |
| Only one may be set per folder? | Yes |
| 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 |
| Only one may be set per folder? | No |
| 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 |
| Only one may be set per folder? | Yes |
| Visible to non-admins? | Yes |
| Requires attachment? | Yes |
| Effect on Child Folders | In effect, cannot be overridden. |
Remote Server Mount
Mount a remote server within this folder. Remote servers can be FTP/SFTP servers, Amazon S3/GCP/Azure Blob/Wasabi/Backblaze B2 Buckets, and more.
See the RemoteServer object for a full list of the Remote Servers supported.
When this behavior is enabled, files in this folder will never actually be stored on Files.com. Rather, Files.com will mount the remote server and act as a mere conduit from your clients to the remote server.
Files.com workflow elements such as Permissions, Automations, Webhooks, Notifications, etc., will apply only to transfer activities that occur through Files.com. We won't send Webhooks or Notifications based on activity that occurs via a direct connetion to the Remote Server other than through Files.com.
Example Value
{
"remote_server_id": "1",
"remote_path": ""
}
| Value Hash Parameters | |
|---|---|
remote_server_id |
ID of the remote server to sync with. See the Remote Servers API resource for managing these. |
remote_path |
Path on remote server to treat as the root of this mount |
| Behavior Details | |
|---|---|
| Behavior type | remote_server_mount |
| Only one may be set per folder? | Yes |
| Visible to non-admins? | Yes |
| Requires attachment? | No |
| Effect on Child Folders | In effect, cannot be overridden. |
Slack Webhook
Sends a Webhook call to Slack whenever certain actions occur on a folder. You will need to add the "Incoming WebHooks" App to your Slack workspace.
Example Value
{
"url": "https://mysite.com/url...",
"username": "Files.com",
"channel": "alerts",
"icon_emoji": ":robot_face:",
"triggers": [
"create",
"read",
"update",
"destroy",
"move",
"copy"
]
}
| Value Hash Parameters | Required | |
|---|---|---|
url |
Slack issued URL to send the webhook to. | Yes |
username |
Username to display in Slack. | No |
channel |
Channel is send the webhook to. | No |
icon_emoji |
Slack emoji to display in Slack, e.g. :robot_face: | No |
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. |
No |
| Behavior Details | |
|---|---|
| Behavior type | slack_webhook |
| Only one may be set per folder? | No |
| 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. |
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?per_page=1&behavior=webhook" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/behaviors.xml?per_page=1&behavior=webhook" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::Behavior.list(
per_page: 1,
behavior: "webhook"
)
\Files\Model\Behavior::list(array(
'per_page' => 1,
'behavior' => "webhook"
));
["HashMap<Object, String> requestParams = new HashMap<>();\n"]requestParams.put("per_page", 1);
requestParams.put("behavior", webhook);
Behavior.list(parameters)
await Behavior.list({
per_page: 1,
behavior: "webhook",
})
var parameters = new Dictionary<string, object>();
parameters.Add("per_page", 1);
parameters.Add("behavior", "webhook");
Behavior.List(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.behavior.list({
"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 |
|---|---|
| cursor string | Used for pagination. Send a cursor value 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-Next header. |
| per_page int64 | Number of records to show per page. (Max: 10,000, 1,000 or less is recommended). |
| sort_by object | If set, sort records by the specified field in either 'asc' or 'desc' direction (e.g. sort_by[last_login_at]=desc). Valid fields are behavior. |
| filter object | If set, return records where the specifiied field is equal to the supplied value. Valid fields are behavior. |
| filter_gt object | If set, return records where the specifiied field is greater than the supplied value. Valid fields are behavior. |
| filter_gteq object | If set, return records where the specifiied field is greater than or equal to the supplied value. Valid fields are behavior. |
| filter_like object | If set, return records where the specifiied field is equal to the supplied value. Valid fields are behavior. |
| filter_lt object | If set, return records where the specifiied field is less than the supplied value. Valid fields are behavior. |
| filter_lteq object | If set, return records where the specifiied field is less than or equal to the supplied value. Valid fields are behavior. |
| 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\Model\Behavior::find($id);
[]
Behavior.find(, parametersasdf
await Behavior.find(id)
Behavior.Find(id);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.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. |
List Behaviors by path
Example Request
curl "https://app.files.com/api/rest/v1/behaviors/folders/{path}?per_page=1&behavior=webhook" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/behaviors/folders/{path}?per_page=1&behavior=webhook" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::Behavior.list_for(path,
per_page: 1,
behavior: "webhook"
)
\Files\Model\Behavior::listFor($path, array(
'per_page' => 1,
'behavior' => "webhook"
));
["HashMap<Object, String> requestParams = new HashMap<>();\n"]requestParams.put("per_page", 1);
requestParams.put("behavior", webhook);
Behavior.listFor(parameters)
await Behavior.listFor(path, {
per_page: 1,
behavior: "webhook",
})
var parameters = new Dictionary<string, object>();
parameters.Add("per_page", 1);
parameters.Add("behavior", "webhook");
Behavior.ListFor(path, parameters);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.behavior.list_for(path, {
"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 |
|---|---|
| cursor string | Used for pagination. Send a cursor value 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-Next header. |
| per_page int64 | Number of records to show per page. (Max: 10,000, 1,000 or less is recommended). |
| sort_by object | If set, sort records by the specified field in either 'asc' or 'desc' direction (e.g. sort_by[last_login_at]=desc). Valid fields are behavior. |
| filter object | If set, return records where the specifiied field is equal to the supplied value. Valid fields are behavior. |
| filter_gt object | If set, return records where the specifiied field is greater than the supplied value. Valid fields are behavior. |
| filter_gteq object | If set, return records where the specifiied field is greater than or equal to the supplied value. Valid fields are behavior. |
| filter_like object | If set, return records where the specifiied field is equal to the supplied value. Valid fields are behavior. |
| filter_lt object | If set, return records where the specifiied field is less than the supplied value. Valid fields are behavior. |
| filter_lteq object | If set, return records where the specifiied field is less than or equal to the supplied value. Valid fields are behavior. |
| path string Required | Path to operate on. |
| recursive string | Show behaviors above this path? |
| behavior string | DEPRECATED: If set only shows folder behaviors matching this behavior type. Use filter[behavior] instead. |
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\Model\Behavior::create(array(
'value' => "{\"method\": \"GET\"}",
'path' => "path",
'behavior' => "webhook"
));
["HashMap<Object, String> requestParams = new HashMap<>();\n"]requestParams.put("value", {"method": "GET"});
requestParams.put("path", path);
requestParams.put("behavior", webhook);
Behavior.create(parameters)
await Behavior.create({
value: "{\"method\": \"GET\"}",
path: "path",
behavior: "webhook",
})
var parameters = new Dictionary<string, object>();
parameters.Add("value", "{\"method\": \"GET\"}");
parameters.Add("path", "path");
parameters.Add("behavior", "webhook");
Behavior.Create(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.behavior.create({
"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","headers":"x-test-header => testvalue","body":"test-param => testvalue","action":"test"}' \
-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>
<headers>x-test-header => testvalue</headers>
<body>test-param => testvalue</body>
<action>test</action>
</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",
headers: "x-test-header => testvalue",
body: "test-param => testvalue",
action: "test"
)
\Files\Model\Behavior::webhookTest(array(
'url' => "https://www.site.com/...",
'method' => "GET",
'encoding' => "RAW",
'headers' => "x-test-header => testvalue",
'body' => "test-param => testvalue",
'action' => "test"
));
["HashMap<Object, String> requestParams = new HashMap<>();\n"]requestParams.put("url", https://www.site.com/...);
requestParams.put("method", GET);
requestParams.put("encoding", RAW);
requestParams.put("headers", x-test-header => testvalue);
requestParams.put("body", test-param => testvalue);
requestParams.put("action", test);
Behavior.webhookTest(parameters)
await Behavior.webhookTest({
url: "https://www.site.com/...",
method: "GET",
encoding: "RAW",
headers: "x-test-header => testvalue",
body: "test-param => testvalue",
action: "test",
})
var parameters = new Dictionary<string, object>();
parameters.Add("url", "https://www.site.com/...");
parameters.Add("method", "GET");
parameters.Add("encoding", "RAW");
parameters.Add("headers", "x-test-header => testvalue");
parameters.Add("body", "test-param => testvalue");
parameters.Add("action", "test");
Behavior.WebhookTest(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.behavior.webhook_test({
"url": "https://www.site.com/...",
"method": "GET",
"encoding": "RAW",
"headers": "x-test-header => testvalue",
"body": "test-param => testvalue",
"action": "test"
})
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). |
| headers object | Additional request headers. |
| body object | Additional body parameters. |
| action string | action for test body |
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\"}","behavior":"webhook"}' \
-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>webhook</behavior>
</behavior>'
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
behavior = Files::Behavior.list_for(path).first
behavior.update(
value: "{\"method\": \"GET\"}",
behavior: "webhook"
)
$behavior = \Files\Model\Behavior::listFor($path)[0];
$behavior->update(array(
'value' => "{\"method\": \"GET\"}",
'behavior' => "webhook"
));
Behavior behavior = Behavior.listFor(path);
behavior.setValue("{"method": "GET"}");
behavior.setBehavior("webhook");
behavior.update();
const behavior = (await Behavior.listFor(path))[0]
await behavior.update({
value: "{\"method\": \"GET\"}",
behavior: "webhook",
})
var Behavior = Behavior.ListFor(path)[0];
var parameters = new Dictionary<string, object>();
parameters.Add("value", "{\"method\": \"GET\"}");
parameters.Add("behavior", "webhook");
Behavior.Update(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
behavior = files_sdk.behavior.find(id)
behavior.update({
value: "{\"method\": \"GET\"}",
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
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 |
| behavior string | Behavior type. |
| path string | Folder behaviors path. |
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.list_for(path).first
behavior.delete
$behavior = \Files\Model\Behavior::listFor($path)[0];
$behavior->delete();
Behavior behavior = Behavior.listFor(path);
behavior.delete();
const behavior = (await Behavior.listFor(path))[0]
await behavior.delete()
var Behavior = Behavior.ListFor(path)[0];
Behavior.Delete();
files_sdk.set_api_key("YOUR_API_KEY")
behavior = files_sdk.behavior.find(id)
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
{
"code": "abc123",
"url": "https://subdomain.files.com/f/12345678",
"description": "The public description of the bundle.",
"password_protected": true,
"require_registration": true,
"require_share_recipient": true,
"clickwrap_body": "[Legal text]",
"form_field_set": {
"id": 1,
"title": "Sample Form Title",
"form_layout": [
1,
2,
3,
4
],
"form_fields": [
{
"id": 1,
"label": "Sample Label",
"required": true,
"help_text": "Help Text",
"field_type": "text",
"options_for_select": [
"red",
"green",
"blue"
],
"default_option": "red",
"form_field_set_id": 1
}
]
},
"id": 1,
"created_at": "2000-01-01T01:00:00Z",
"expires_at": "2000-01-01T01:00:00Z",
"max_uses": 1,
"note": "The internal note on the bundle.",
"user_id": 1,
"username": "user",
"clickwrap_id": 1,
"inbox_id": 1,
"has_inbox": true,
"paths": [
"file.txt"
]
}
<?xml version="1.0" encoding="UTF-8"?>
<bundle>
<code>abc123</code>
<url>https://subdomain.files.com/f/12345678</url>
<description>The public description of the bundle.</description>
<password_protected type="boolean">true</password_protected>
<require_registration type="boolean">true</require_registration>
<require_share_recipient type="boolean">true</require_share_recipient>
<clickwrap_body>[Legal text]</clickwrap_body>
<form_field_set>
<id type="integer">1</id>
<title>Sample Form Title</title>
<form_layout type="array">
<form_layout type="integer">1</form_layout>
<form_layout type="integer">2</form_layout>
<form_layout type="integer">3</form_layout>
<form_layout type="integer">4</form_layout>
</form_layout>
<form_fields type="array">
<form_field>
<id type="integer">1</id>
<label>Sample Label</label>
<required type="boolean">true</required>
<help_text>Help Text</help_text>
<field_type>text</field_type>
<options_for_select type="array">
<options_for_select>red</options_for_select>
<options_for_select>green</options_for_select>
<options_for_select>blue</options_for_select>
</options_for_select>
<default_option>red</default_option>
<form_field_set_id type="integer">1</form_field_set_id>
</form_field>
</form_fields>
</form_field_set>
<id type="integer">1</id>
<created_at>2000-01-01T01:00:00Z</created_at>
<expires_at>2000-01-01T01:00:00Z</expires_at>
<max_uses type="integer">1</max_uses>
<note>The internal note on the bundle.</note>
<user_id type="integer">1</user_id>
<username>user</username>
<clickwrap_id type="integer">1</clickwrap_id>
<inbox_id type="integer">1</inbox_id>
<has_inbox type="boolean">true</has_inbox>
<paths type="array">
<path>file.txt</path>
</paths>
</bundle>
| Attribute | Description |
|---|---|
| code string | Bundle code. This code forms the end part of the Public URL. |
| url string | Public URL of Share Link |
| description string | Public description |
| password_protected boolean | Is this bundle password protected? |
| require_registration boolean | Show a registration page that captures the downloader's name and email address? |
| require_share_recipient boolean | Only allow access to recipients who have explicitly received the share via an email sent through the Files.com UI? |
| clickwrap_body string | Legal text that must be agreed to prior to accessing Bundle. |
| form_field_set | Custom Form to use |
| id int64 | Bundle ID |
| created_at date-time | Bundle created at date/time |
| expires_at date-time | Bundle expiration date/time |
| max_uses int64 | Maximum number of times bundle can be accessed |
| note string | Bundle internal note |
| user_id int64 | Bundle creator user ID |
| username string | Bundle creator username |
| clickwrap_id int64 | ID of the clickwrap to use with this bundle. |
| inbox_id int64 | ID of the associated inbox, if available. |
| has_inbox boolean | Does this bundle have an associated inbox? |
| paths array | A list of paths in this bundle |
| password string | Password for this bundle. |
| form_field_set_id int64 | Id of Form Field Set to use with this bundle |
List Bundles
Example Request
curl "https://app.files.com/api/rest/v1/bundles.json?user_id=1&per_page=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/bundles.xml?user_id=1&per_page=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::Bundle.list(
user_id: 1,
per_page: 1
)
\Files\Model\Bundle::list(array(
'user_id' => 1,
'per_page' => 1
));
["HashMap<Object, String> requestParams = new HashMap<>();\n"]requestParams.put("user_id", 1);
requestParams.put("per_page", 1);
Bundle.list(parameters)
await Bundle.list({
user_id: 1,
per_page: 1,
})
var parameters = new Dictionary<string, object>();
parameters.Add("user_id", 1);
parameters.Add("per_page", 1);
Bundle.List(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.bundle.list({
"user_id": 1,
"per_page": 1
})
Example Response
[
{
"code": "abc123",
"url": "https://subdomain.files.com/f/12345678",
"description": "The public description of the bundle.",
"password_protected": true,
"require_registration": true,
"require_share_recipient": true,
"clickwrap_body": "[Legal text]",
"form_field_set": {
"id": 1,
"title": "Sample Form Title",
"form_layout": [
1,
2,
3,
4
],
"form_fields": [
{
"id": 1,
"label": "Sample Label",
"required": true,
"help_text": "Help Text",
"field_type": "text",
"options_for_select": [
"red",
"green",
"blue"
],
"default_option": "red",
"form_field_set_id": 1
}
]
},
"id": 1,
"created_at": "2000-01-01T01:00:00Z",
"expires_at": "2000-01-01T01:00:00Z",
"max_uses": 1,
"note": "The internal note on the bundle.",
"user_id": 1,
"username": "user",
"clickwrap_id": 1,
"inbox_id": 1,
"has_inbox": true,
"paths": [
"file.txt"
]
}
]
<?xml version="1.0" encoding="UTF-8"?>
<bundles type="array">
<bundle>
<code>abc123</code>
<url>https://subdomain.files.com/f/12345678</url>
<description>The public description of the bundle.</description>
<password_protected type="boolean">true</password_protected>
<require_registration type="boolean">true</require_registration>
<require_share_recipient type="boolean">true</require_share_recipient>
<clickwrap_body>[Legal text]</clickwrap_body>
<form_field_set>
<id type="integer">1</id>
<title>Sample Form Title</title>
<form_layout type="array">
<form_layout type="integer">1</form_layout>
<form_layout type="integer">2</form_layout>
<form_layout type="integer">3</form_layout>
<form_layout type="integer">4</form_layout>
</form_layout>
<form_fields type="array">
<form_field>
<id type="integer">1</id>
<label>Sample Label</label>
<required type="boolean">true</required>
<help_text>Help Text</help_text>
<field_type>text</field_type>
<options_for_select type="array">
<options_for_select>red</options_for_select>
<options_for_select>green</options_for_select>
<options_for_select>blue</options_for_select>
</options_for_select>
<default_option>red</default_option>
<form_field_set_id type="integer">1</form_field_set_id>
</form_field>
</form_fields>
</form_field_set>
<id type="integer">1</id>
<created_at>2000-01-01T01:00:00Z</created_at>
<expires_at>2000-01-01T01:00:00Z</expires_at>
<max_uses type="integer">1</max_uses>
<note>The internal note on the bundle.</note>
<user_id type="integer">1</user_id>
<username>user</username>
<clickwrap_id type="integer">1</clickwrap_id>
<inbox_id type="integer">1</inbox_id>
<has_inbox type="boolean">true</has_inbox>
<paths type="array">
<path>file.txt</path>
</paths>
</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. |
| cursor string | Used for pagination. Send a cursor value 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-Next header. |
| per_page int64 | Number of records to show per page. (Max: 10,000, 1,000 or less is recommended). |
| sort_by object | If set, sort records by the specified field in either 'asc' or 'desc' direction (e.g. sort_by[last_login_at]=desc). Valid fields are created_at and code. |
| filter object | If set, return records where the specifiied field is equal to the supplied value. Valid fields are created_at. |
| filter_gt object | If set, return records where the specifiied field is greater than the supplied value. Valid fields are created_at. |
| filter_gteq object | If set, return records where the specifiied field is greater than or equal to the supplied value. Valid fields are created_at. |
| filter_like object | If set, return records where the specifiied field is equal to the supplied value. Valid fields are created_at. |
| filter_lt object | If set, return records where the specifiied field is less than the supplied value. Valid fields are created_at. |
| filter_lteq object | If set, return records where the specifiied field is less than or equal to the supplied value. Valid fields are created_at. |
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\Model\Bundle::find($id);
[]
Bundle.find(, parametersasdf
await Bundle.find(id)
Bundle.Find(id);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.bundle.find(id)
Example Response
{
"code": "abc123",
"url": "https://subdomain.files.com/f/12345678",
"description": "The public description of the bundle.",
"password_protected": true,
"require_registration": true,
"require_share_recipient": true,
"clickwrap_body": "[Legal text]",
"form_field_set": {
"id": 1,
"title": "Sample Form Title",
"form_layout": [
1,
2,
3,
4
],
"form_fields": [
{
"id": 1,
"label": "Sample Label",
"required": true,
"help_text": "Help Text",
"field_type": "text",
"options_for_select": [
"red",
"green",
"blue"
],
"default_option": "red",
"form_field_set_id": 1
}
]
},
"id": 1,
"created_at": "2000-01-01T01:00:00Z",
"expires_at": "2000-01-01T01:00:00Z",
"max_uses": 1,
"note": "The internal note on the bundle.",
"user_id": 1,
"username": "user",
"clickwrap_id": 1,
"inbox_id": 1,
"has_inbox": true,
"paths": [
"file.txt"
]
}
<?xml version="1.0" encoding="UTF-8"?>
<bundle>
<code>abc123</code>
<url>https://subdomain.files.com/f/12345678</url>
<description>The public description of the bundle.</description>
<password_protected type="boolean">true</password_protected>
<require_registration type="boolean">true</require_registration>
<require_share_recipient type="boolean">true</require_share_recipient>
<clickwrap_body>[Legal text]</clickwrap_body>
<form_field_set>
<id type="integer">1</id>
<title>Sample Form Title</title>
<form_layout type="array">
<form_layout type="integer">1</form_layout>
<form_layout type="integer">2</form_layout>
<form_layout type="integer">3</form_layout>
<form_layout type="integer">4</form_layout>
</form_layout>
<form_fields type="array">
<form_field>
<id type="integer">1</id>
<label>Sample Label</label>
<required type="boolean">true</required>
<help_text>Help Text</help_text>
<field_type>text</field_type>
<options_for_select type="array">
<options_for_select>red</options_for_select>
<options_for_select>green</options_for_select>
<options_for_select>blue</options_for_select>
</options_for_select>
<default_option>red</default_option>
<form_field_set_id type="integer">1</form_field_set_id>
</form_field>
</form_fields>
</form_field_set>
<id type="integer">1</id>
<created_at>2000-01-01T01:00:00Z</created_at>
<expires_at>2000-01-01T01:00:00Z</expires_at>
<max_uses type="integer">1</max_uses>
<note>The internal note on the bundle.</note>
<user_id type="integer">1</user_id>
<username>user</username>
<clickwrap_id type="integer">1</clickwrap_id>
<inbox_id type="integer">1</inbox_id>
<has_inbox type="boolean">true</has_inbox>
<paths type="array">
<path>file.txt</path>
</paths>
</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","form_field_set_id":1,"expires_at":"2000-01-01T01:00:00Z","max_uses":1,"description":"The public description of the bundle.","note":"The internal note on the bundle.","code":"abc123","require_registration":true,"clickwrap_id":1,"inbox_id":1,"require_share_recipient":true}' \
-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>
<form_field_set_id type="integer">1</form_field_set_id>
<expires_at>2000-01-01T01:00:00Z</expires_at>
<max_uses type="integer">1</max_uses>
<description>The public description of the bundle.</description>
<note>The internal note on the bundle.</note>
<code>abc123</code>
<require_registration type="boolean">true</require_registration>
<clickwrap_id type="integer">1</clickwrap_id>
<inbox_id type="integer">1</inbox_id>
<require_share_recipient type="boolean">true</require_share_recipient>
</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",
form_field_set_id: 1,
expires_at: "2000-01-01T01:00:00Z",
max_uses: 1,
description: "The public description of the bundle.",
note: "The internal note on the bundle.",
code: "abc123",
require_registration: true,
clickwrap_id: 1,
inbox_id: 1,
require_share_recipient: true
)
\Files\Model\Bundle::create(array(
'user_id' => 1,
'paths' => ["file.txt"],
'password' => "Password",
'form_field_set_id' => 1,
'expires_at' => "2000-01-01T01:00:00Z",
'max_uses' => 1,
'description' => "The public description of the bundle.",
'note' => "The internal note on the bundle.",
'code' => "abc123",
'require_registration' => true,
'clickwrap_id' => 1,
'inbox_id' => 1,
'require_share_recipient' => true
));
["HashMap<Object, String> requestParams = new HashMap<>();\n"]requestParams.put("user_id", 1);
requestParams.put("paths", ["file.txt"]);
requestParams.put("password", Password);
requestParams.put("form_field_set_id", 1);
requestParams.put("expires_at", 2000-01-01T01:00:00Z);
requestParams.put("max_uses", 1);
requestParams.put("description", The public description of the bundle.);
requestParams.put("note", The internal note on the bundle.);
requestParams.put("code", abc123);
requestParams.put("require_registration", true);
requestParams.put("clickwrap_id", 1);
requestParams.put("inbox_id", 1);
requestParams.put("require_share_recipient", true);
Bundle.create(parameters)
await Bundle.create({
user_id: 1,
paths: ["file.txt"],
password: "Password",
form_field_set_id: 1,
expires_at: "2000-01-01T01:00:00Z",
max_uses: 1,
description: "The public description of the bundle.",
note: "The internal note on the bundle.",
code: "abc123",
require_registration: true,
clickwrap_id: 1,
inbox_id: 1,
require_share_recipient: true,
})
var parameters = new Dictionary<string, object>();
parameters.Add("user_id", 1);
parameters.Add("paths", ["file.txt"]);
parameters.Add("password", "Password");
parameters.Add("form_field_set_id", 1);
parameters.Add("expires_at", "2000-01-01T01:00:00Z");
parameters.Add("max_uses", 1);
parameters.Add("description", "The public description of the bundle.");
parameters.Add("note", "The internal note on the bundle.");
parameters.Add("code", "abc123");
parameters.Add("require_registration", true);
parameters.Add("clickwrap_id", 1);
parameters.Add("inbox_id", 1);
parameters.Add("require_share_recipient", true);
Bundle.Create(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.bundle.create({
"user_id": 1,
"paths": ["file.txt"],
"password": "Password",
"form_field_set_id": 1,
"expires_at": "2000-01-01T01:00:00Z",
"max_uses": 1,
"description": "The public description of the bundle.",
"note": "The internal note on the bundle.",
"code": "abc123",
"require_registration": True,
"clickwrap_id": 1,
"inbox_id": 1,
"require_share_recipient": True
})
Example Response
{
"code": "abc123",
"url": "https://subdomain.files.com/f/12345678",
"description": "The public description of the bundle.",
"password_protected": true,
"require_registration": true,
"require_share_recipient": true,
"clickwrap_body": "[Legal text]",
"form_field_set": {
"id": 1,
"title": "Sample Form Title",
"form_layout": [
1,
2,
3,
4
],
"form_fields": [
{
"id": 1,
"label": "Sample Label",
"required": true,
"help_text": "Help Text",
"field_type": "text",
"options_for_select": [
"red",
"green",
"blue"
],
"default_option": "red",
"form_field_set_id": 1
}
]
},
"id": 1,
"created_at": "2000-01-01T01:00:00Z",
"expires_at": "2000-01-01T01:00:00Z",
"max_uses": 1,
"note": "The internal note on the bundle.",
"user_id": 1,
"username": "user",
"clickwrap_id": 1,
"inbox_id": 1,
"has_inbox": true,
"paths": [
"file.txt"
]
}
<?xml version="1.0" encoding="UTF-8"?>
<bundle>
<code>abc123</code>
<url>https://subdomain.files.com/f/12345678</url>
<description>The public description of the bundle.</description>
<password_protected type="boolean">true</password_protected>
<require_registration type="boolean">true</require_registration>
<require_share_recipient type="boolean">true</require_share_recipient>
<clickwrap_body>[Legal text]</clickwrap_body>
<form_field_set>
<id type="integer">1</id>
<title>Sample Form Title</title>
<form_layout type="array">
<form_layout type="integer">1</form_layout>
<form_layout type="integer">2</form_layout>
<form_layout type="integer">3</form_layout>
<form_layout type="integer">4</form_layout>
</form_layout>
<form_fields type="array">
<form_field>
<id type="integer">1</id>
<label>Sample Label</label>
<required type="boolean">true</required>
<help_text>Help Text</help_text>
<field_type>text</field_type>
<options_for_select type="array">
<options_for_select>red</options_for_select>
<options_for_select>green</options_for_select>
<options_for_select>blue</options_for_select>
</options_for_select>
<default_option>red</default_option>
<form_field_set_id type="integer">1</form_field_set_id>
</form_field>
</form_fields>
</form_field_set>
<id type="integer">1</id>
<created_at>2000-01-01T01:00:00Z</created_at>
<expires_at>2000-01-01T01:00:00Z</expires_at>
<max_uses type="integer">1</max_uses>
<note>The internal note on the bundle.</note>
<user_id type="integer">1</user_id>
<username>user</username>
<clickwrap_id type="integer">1</clickwrap_id>
<inbox_id type="integer">1</inbox_id>
<has_inbox type="boolean">true</has_inbox>
<paths type="array">
<path>file.txt</path>
</paths>
</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. |
| form_field_set_id int64 | Id of Form Field Set to use with this bundle |
| expires_at string | Bundle expiration date/time |
| max_uses int64 | Maximum number of times bundle can be accessed |
| description string | Public description |
| note string | Bundle internal note |
| code string | Bundle code. This code forms the end part of the Public URL. |
| require_registration boolean | Show a registration page that captures the downloader's name and email address? |
| clickwrap_id int64 | ID of the clickwrap to use with this bundle. |
| inbox_id int64 | ID of the associated inbox, if available. |
| require_share_recipient boolean | Only allow access to recipients who have explicitly received the share via an email sent through the Files.com UI? |
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.","recipients":[{"name":"John Doe","company":"Acme Ltd","recipient":"johndoe@gmail.com"}]}' \
-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>
<recipients type="array">
<recipient>
<name>John Doe</name>
<company>Acme Ltd</company>
<recipient>johndoe@gmail.com</recipient>
</recipient>
</recipients>
</bundle>'
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
bundle = Files::Bundle.list_for(path).first
bundle.share(
to: ["johndoe@gmail.com"],
note: "Just a note.",
recipients: [{"name":"John Doe","company":"Acme Ltd","recipient":"johndoe@gmail.com"}]
)
$bundle = \Files\Model\Bundle::listFor($path)[0];
$bundle->share(array(
'to' => ["johndoe@gmail.com"],
'note' => "Just a note.",
'recipients' => [{"name":"John Doe","company":"Acme Ltd","recipient":"johndoe@gmail.com"}]
));
Bundle bundle = Bundle.listFor(path);
bundle.setTo(["johndoe@gmail.com"]);
bundle.setNote("Just a note.");
bundle.setRecipients([{"name"=>"John Doe", "company"=>"Acme Ltd", "recipient"=>"johndoe@gmail.com"}]);
bundle.share();
const bundle = (await Bundle.listFor(path))[0]
await bundle.share({
to: ["johndoe@gmail.com"],
note: "Just a note.",
recipients: [{"name":"John Doe","company":"Acme Ltd","recipient":"johndoe@gmail.com"}],
})
var Bundle = Bundle.ListFor(path)[0];
var parameters = new Dictionary<string, object>();
parameters.Add("to", ["johndoe@gmail.com"]);
parameters.Add("note", "Just a note.");
parameters.Add("recipients", [{"name":"John Doe","company":"Acme Ltd","recipient":"johndoe@gmail.com"}]);
Bundle.Share(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
bundle = files_sdk.bundle.find(id)
bundle.share({
to: ["johndoe@gmail.com"],
note: "Just a note.",
recipients: [{"name":"John Doe","company":"Acme Ltd","recipient":"johndoe@gmail.com"}]
})
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. |
| recipients array(object) | A list of recipients to share this bundle with. |
Update Bundle
Example Request
curl https://app.files.com/api/rest/v1/bundles/{id}.json \
-X PATCH \
-H 'Content-Type: application/json' \
-d '{"paths":["file.txt"],"password":"Password","form_field_set_id":1,"clickwrap_id":1,"code":"abc123","description":"The public description of the bundle.","expires_at":"2000-01-01T01:00:00Z","inbox_id":1,"max_uses":1,"note":"The internal note on the bundle.","require_registration":true,"require_share_recipient":true}' \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl https://app.files.com/api/rest/v1/bundles/{id}.xml \
-X PATCH \
-H 'Content-Type: application/xml' \
-d '<bundle>
<paths type="array">
<path>file.txt</path>
</paths>
<password>Password</password>
<form_field_set_id type="integer">1</form_field_set_id>
<clickwrap_id type="integer">1</clickwrap_id>
<code>abc123</code>
<description>The public description of the bundle.</description>
<expires_at>2000-01-01T01:00:00Z</expires_at>
<inbox_id type="integer">1</inbox_id>
<max_uses type="integer">1</max_uses>
<note>The internal note on the bundle.</note>
<require_registration type="boolean">true</require_registration>
<require_share_recipient type="boolean">true</require_share_recipient>
</bundle>'
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
bundle = Files::Bundle.list_for(path).first
bundle.update(
paths: ["file.txt"],
password: "Password",
form_field_set_id: 1,
clickwrap_id: 1,
code: "abc123",
description: "The public description of the bundle.",
expires_at: "2000-01-01T01:00:00Z",
inbox_id: 1,
max_uses: 1,
note: "The internal note on the bundle.",
require_registration: true,
require_share_recipient: true
)
$bundle = \Files\Model\Bundle::listFor($path)[0];
$bundle->update(array(
'paths' => ["file.txt"],
'password' => "Password",
'form_field_set_id' => 1,
'clickwrap_id' => 1,
'code' => "abc123",
'description' => "The public description of the bundle.",
'expires_at' => "2000-01-01T01:00:00Z",
'inbox_id' => 1,
'max_uses' => 1,
'note' => "The internal note on the bundle.",
'require_registration' => true,
'require_share_recipient' => true
));
Bundle bundle = Bundle.listFor(path);
bundle.setPaths(["file.txt"]);
bundle.setPassword("Password");
bundle.setFormFieldSetId(1);
bundle.setClickwrapId(1);
bundle.setCode("abc123");
bundle.setDescription("The public description of the bundle.");
bundle.setExpiresAt("2000-01-01T01:00:00Z");
bundle.setInboxId(1);
bundle.setMaxUses(1);
bundle.setNote("The internal note on the bundle.");
bundle.setRequireRegistration(true);
bundle.setRequireShareRecipient(true);
bundle.update();
const bundle = (await Bundle.listFor(path))[0]
await bundle.update({
paths: ["file.txt"],
password: "Password",
form_field_set_id: 1,
clickwrap_id: 1,
code: "abc123",
description: "The public description of the bundle.",
expires_at: "2000-01-01T01:00:00Z",
inbox_id: 1,
max_uses: 1,
note: "The internal note on the bundle.",
require_registration: true,
require_share_recipient: true,
})
var Bundle = Bundle.ListFor(path)[0];
var parameters = new Dictionary<string, object>();
parameters.Add("paths", ["file.txt"]);
parameters.Add("password", "Password");
parameters.Add("form_field_set_id", 1);
parameters.Add("clickwrap_id", 1);
parameters.Add("code", "abc123");
parameters.Add("description", "The public description of the bundle.");
parameters.Add("expires_at", "2000-01-01T01:00:00Z");
parameters.Add("inbox_id", 1);
parameters.Add("max_uses", 1);
parameters.Add("note", "The internal note on the bundle.");
parameters.Add("require_registration", true);
parameters.Add("require_share_recipient", true);
Bundle.Update(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
bundle = files_sdk.bundle.find(id)
bundle.update({
paths: ["file.txt"],
password: "Password",
form_field_set_id: 1,
clickwrap_id: 1,
code: "abc123",
description: "The public description of the bundle.",
expires_at: "2000-01-01T01:00:00Z",
inbox_id: 1,
max_uses: 1,
note: "The internal note on the bundle.",
require_registration: True,
require_share_recipient: True
})
Example Response
{
"code": "abc123",
"url": "https://subdomain.files.com/f/12345678",
"description": "The public description of the bundle.",
"password_protected": true,
"require_registration": true,
"require_share_recipient": true,
"clickwrap_body": "[Legal text]",
"form_field_set": {
"id": 1,
"title": "Sample Form Title",
"form_layout": [
1,
2,
3,
4
],
"form_fields": [
{
"id": 1,
"label": "Sample Label",
"required": true,
"help_text": "Help Text",
"field_type": "text",
"options_for_select": [
"red",
"green",
"blue"
],
"default_option": "red",
"form_field_set_id": 1
}
]
},
"id": 1,
"created_at": "2000-01-01T01:00:00Z",
"expires_at": "2000-01-01T01:00:00Z",
"max_uses": 1,
"note": "The internal note on the bundle.",
"user_id": 1,
"username": "user",
"clickwrap_id": 1,
"inbox_id": 1,
"has_inbox": true,
"paths": [
"file.txt"
]
}
<?xml version="1.0" encoding="UTF-8"?>
<bundle>
<code>abc123</code>
<url>https://subdomain.files.com/f/12345678</url>
<description>The public description of the bundle.</description>
<password_protected type="boolean">true</password_protected>
<require_registration type="boolean">true</require_registration>
<require_share_recipient type="boolean">true</require_share_recipient>
<clickwrap_body>[Legal text]</clickwrap_body>
<form_field_set>
<id type="integer">1</id>
<title>Sample Form Title</title>
<form_layout type="array">
<form_layout type="integer">1</form_layout>
<form_layout type="integer">2</form_layout>
<form_layout type="integer">3</form_layout>
<form_layout type="integer">4</form_layout>
</form_layout>
<form_fields type="array">
<form_field>
<id type="integer">1</id>
<label>Sample Label</label>
<required type="boolean">true</required>
<help_text>Help Text</help_text>
<field_type>text</field_type>
<options_for_select type="array">
<options_for_select>red</options_for_select>
<options_for_select>green</options_for_select>
<options_for_select>blue</options_for_select>
</options_for_select>
<default_option>red</default_option>
<form_field_set_id type="integer">1</form_field_set_id>
</form_field>
</form_fields>
</form_field_set>
<id type="integer">1</id>
<created_at>2000-01-01T01:00:00Z</created_at>
<expires_at>2000-01-01T01:00:00Z</expires_at>
<max_uses type="integer">1</max_uses>
<note>The internal note on the bundle.</note>
<user_id type="integer">1</user_id>
<username>user</username>
<clickwrap_id type="integer">1</clickwrap_id>
<inbox_id type="integer">1</inbox_id>
<has_inbox type="boolean">true</has_inbox>
<paths type="array">
<path>file.txt</path>
</paths>
</bundle>
HTTPS Request
PATCH /bundles/{id}
Authentication Required
Available to all authenticated keys or sessions.
Request Parameters
| Parameter | Description |
|---|---|
| id int64 Required | Bundle ID. |
| paths array(string) | A list of paths to include in this bundle. |
| password string | Password for this bundle. |
| form_field_set_id int64 | Id of Form Field Set to use with this bundle |
| clickwrap_id int64 | ID of the clickwrap to use with this bundle. |
| code string | Bundle code. This code forms the end part of the Public URL. |
| description string | Public description |
| expires_at string | Bundle expiration date/time |
| inbox_id int64 | ID of the associated inbox, if available. |
| max_uses int64 | Maximum number of times bundle can be accessed |
| note string | Bundle internal note |
| require_registration boolean | Show a registration page that captures the downloader's name and email address? |
| require_share_recipient boolean | Only allow access to recipients who have explicitly received the share via an email sent through the Files.com UI? |
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.list_for(path).first
bundle.delete
$bundle = \Files\Model\Bundle::listFor($path)[0];
$bundle->delete();
Bundle bundle = Bundle.listFor(path);
bundle.delete();
const bundle = (await Bundle.listFor(path))[0]
await bundle.delete()
var Bundle = Bundle.ListFor(path)[0];
Bundle.Delete();
files_sdk.set_api_key("YOUR_API_KEY")
bundle = files_sdk.bundle.find(id)
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. |
Bundle Downloads
The BundleDownloads resource in the REST API allows you to operate on BundleDownloads.
The BundleDownload object
Example BundleDownload Object
{
"bundle_registration": "",
"download_method": "file",
"path": "a/b/test.txt",
"created_at": "2020-01-01 00:00:00"
}
<?xml version="1.0" encoding="UTF-8"?>
<bundle-download>
<bundle_registration></bundle_registration>
<download_method>file</download_method>
<path>a/b/test.txt</path>
<created_at>2020-01-01 00:00:00</created_at>
</bundle-download>
| Attribute | Description |
|---|---|
| bundle_registration | |
| download_method string | Download method (file or full_zip) Possible values: file, full_zip |
| path string | Download path This must be slash-delimited, but it must neither start nor end with a slash. Maximum of 5000 characters. |
| created_at date-time | Download date/time |
List Bundle Downloads
Example Request
curl "https://app.files.com/api/rest/v1/bundle_downloads.json?per_page=1&bundle_id=1&bundle_registration_id=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/bundle_downloads.xml?per_page=1&bundle_id=1&bundle_registration_id=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::BundleDownload.list(
per_page: 1,
bundle_id: 1,
bundle_registration_id: 1
)
\Files\Model\BundleDownload::list(array(
'per_page' => 1,
'bundle_id' => 1,
'bundle_registration_id' => 1
));
["HashMap<Object, String> requestParams = new HashMap<>();\n"]requestParams.put("per_page", 1);
requestParams.put("bundle_id", 1);
requestParams.put("bundle_registration_id", 1);
BundleDownload.list(parameters)
await BundleDownload.list({
per_page: 1,
bundle_id: 1,
bundle_registration_id: 1,
})
var parameters = new Dictionary<string, object>();
parameters.Add("per_page", 1);
parameters.Add("bundle_id", 1);
parameters.Add("bundle_registration_id", 1);
BundleDownload.List(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.bundle_download.list({
"per_page": 1,
"bundle_id": 1,
"bundle_registration_id": 1
})
Example Response
[
{
"bundle_registration": "",
"download_method": "file",
"path": "a/b/test.txt",
"created_at": "2020-01-01 00:00:00"
}
]
<?xml version="1.0" encoding="UTF-8"?>
<bundle-downloads type="array">
<bundle-download>
<bundle_registration></bundle_registration>
<download_method>file</download_method>
<path>a/b/test.txt</path>
<created_at>2020-01-01 00:00:00</created_at>
</bundle-download>
</bundle-downloads>
HTTPS Request
GET /bundle_downloads
Authentication Required
Available to all authenticated keys or sessions.
Request Parameters
| Parameter | Description |
|---|---|
| cursor string | Used for pagination. Send a cursor value 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-Next header. |
| per_page int64 | Number of records to show per page. (Max: 10,000, 1,000 or less is recommended). |
| bundle_id int64 | Bundle ID |
| bundle_registration_id int64 | BundleRegistration ID |
Bundle Recipients
Bundle recipients are people who have had a bundle shared with them.
The BundleRecipient object
Example BundleRecipient Object
{
"company": "Acme Inc.",
"name": "John Doe",
"note": "Some note.",
"recipient": "john.doe@example.com",
"sent_at": "2000-01-01T01:00:00Z"
}
<?xml version="1.0" encoding="UTF-8"?>
<bundle-recipient>
<company>Acme Inc.</company>
<name>John Doe</name>
<note>Some note.</note>
<recipient>john.doe@example.com</recipient>
<sent_at>2000-01-01T01:00:00Z</sent_at>
</bundle-recipient>
| Attribute | Description |
|---|---|
| company string | The recipient's company. |
| name string | The recipient's name. |
| note string | A note sent to the recipient with the bundle. |
| recipient string | The recipient's email address. |
| sent_at date-time | When the Bundle was shared with this recipient. |
| user_id int64 | User ID. Provide a value of 0 to operate the current session's user. |
| bundle_id int64 | Bundle to share. |
| share_after_create boolean | Set to true to share the link with the recipient upon creation. |
List Bundle Recipients
Example Request
curl "https://app.files.com/api/rest/v1/bundle_recipients.json?user_id=1&per_page=1&bundle_id=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/bundle_recipients.xml?user_id=1&per_page=1&bundle_id=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::BundleRecipient.list(
user_id: 1,
per_page: 1,
bundle_id: 1
)
\Files\Model\BundleRecipient::list(array(
'user_id' => 1,
'per_page' => 1,
'bundle_id' => 1
));
["HashMap<Object, String> requestParams = new HashMap<>();\n"]requestParams.put("user_id", 1);
requestParams.put("per_page", 1);
requestParams.put("bundle_id", 1);
BundleRecipient.list(parameters)
await BundleRecipient.list({
user_id: 1,
per_page: 1,
bundle_id: 1,
})
var parameters = new Dictionary<string, object>();
parameters.Add("user_id", 1);
parameters.Add("per_page", 1);
parameters.Add("bundle_id", 1);
BundleRecipient.List(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.bundle_recipient.list({
"user_id": 1,
"per_page": 1,
"bundle_id": 1
})
Example Response
[
{
"company": "Acme Inc.",
"name": "John Doe",
"note": "Some note.",
"recipient": "john.doe@example.com",
"sent_at": "2000-01-01T01:00:00Z"
}
]
<?xml version="1.0" encoding="UTF-8"?>
<bundle-recipients type="array">
<bundle-recipient>
<company>Acme Inc.</company>
<name>John Doe</name>
<note>Some note.</note>
<recipient>john.doe@example.com</recipient>
<sent_at>2000-01-01T01:00:00Z</sent_at>
</bundle-recipient>
</bundle-recipients>
HTTPS Request
GET /bundle_recipients
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. |
| cursor string | Used for pagination. Send a cursor value 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-Next header. |
| per_page int64 | Number of records to show per page. (Max: 10,000, 1,000 or less is recommended). |
| sort_by object | If set, sort records by the specified field in either 'asc' or 'desc' direction (e.g. sort_by[last_login_at]=desc). Valid fields are has_registrations. |
| filter object | If set, return records where the specifiied field is equal to the supplied value. Valid fields are has_registrations. |
| filter_gt object | If set, return records where the specifiied field is greater than the supplied value. Valid fields are has_registrations. |
| filter_gteq object | If set, return records where the specifiied field is greater than or equal to the supplied value. Valid fields are has_registrations. |
| filter_like object | If set, return records where the specifiied field is equal to the supplied value. Valid fields are has_registrations. |
| filter_lt object | If set, return records where the specifiied field is less than the supplied value. Valid fields are has_registrations. |
| filter_lteq object | If set, return records where the specifiied field is less than or equal to the supplied value. Valid fields are has_registrations. |
| bundle_id int64 Required | List recipients for the bundle with this ID. |
Create Bundle Recipient
Example Request
curl https://app.files.com/api/rest/v1/bundle_recipients.json \
-X POST \
-H 'Content-Type: application/json' \
-d '{"user_id":1,"bundle_id":1,"recipient":"johndoe@gmail.com","name":"John Smith","company":"Acme Ltd","note":"Just a note.","share_after_create":true}' \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl https://app.files.com/api/rest/v1/bundle_recipients.xml \
-X POST \
-H 'Content-Type: application/xml' \
-d '<bundle-recipient>
<user_id type="integer">1</user_id>
<bundle_id type="integer">1</bundle_id>
<recipient>johndoe@gmail.com</recipient>
<name>John Smith</name>
<company>Acme Ltd</company>
<note>Just a note.</note>
<share_after_create type="boolean">true</share_after_create>
</bundle-recipient>'
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::BundleRecipient.create(
user_id: 1,
bundle_id: 1,
recipient: "johndoe@gmail.com",
name: "John Smith",
company: "Acme Ltd",
note: "Just a note.",
share_after_create: true
)
\Files\Model\BundleRecipient::create(array(
'user_id' => 1,
'bundle_id' => 1,
'recipient' => "johndoe@gmail.com",
'name' => "John Smith",
'company' => "Acme Ltd",
'note' => "Just a note.",
'share_after_create' => true
));
["HashMap<Object, String> requestParams = new HashMap<>();\n"]requestParams.put("user_id", 1);
requestParams.put("bundle_id", 1);
requestParams.put("recipient", johndoe@gmail.com);
requestParams.put("name", John Smith);
requestParams.put("company", Acme Ltd);
requestParams.put("note", Just a note.);
requestParams.put("share_after_create", true);
BundleRecipient.create(parameters)
await BundleRecipient.create({
user_id: 1,
bundle_id: 1,
recipient: "johndoe@gmail.com",
name: "John Smith",
company: "Acme Ltd",
note: "Just a note.",
share_after_create: true,
})
var parameters = new Dictionary<string, object>();
parameters.Add("user_id", 1);
parameters.Add("bundle_id", 1);
parameters.Add("recipient", "johndoe@gmail.com");
parameters.Add("name", "John Smith");
parameters.Add("company", "Acme Ltd");
parameters.Add("note", "Just a note.");
parameters.Add("share_after_create", true);
BundleRecipient.Create(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.bundle_recipient.create({
"user_id": 1,
"bundle_id": 1,
"recipient": "johndoe@gmail.com",
"name": "John Smith",
"company": "Acme Ltd",
"note": "Just a note.",
"share_after_create": True
})
Example Response
{
"company": "Acme Inc.",
"name": "John Doe",
"note": "Some note.",
"recipient": "john.doe@example.com",
"sent_at": "2000-01-01T01:00:00Z"
}
<?xml version="1.0" encoding="UTF-8"?>
<bundle-recipient>
<company>Acme Inc.</company>
<name>John Doe</name>
<note>Some note.</note>
<recipient>john.doe@example.com</recipient>
<sent_at>2000-01-01T01:00:00Z</sent_at>
</bundle-recipient>
HTTPS Request
POST /bundle_recipients
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. |
| bundle_id int64 Required | Bundle to share. |
| recipient string Required | Email addresses to share this bundle with. |
| name string | Name of recipient. |
| company string | Company of recipient. |
| note string | Note to include in email. |
| share_after_create boolean | Set to true to share the link with the recipient upon creation. |
Clickwraps
A Clickwrap is a legal agreement (such as an NDA or Terms of Use) that your Users and/or Bundle/Inbox participants will need to agree to via a "Clickwrap" UI before accessing the site, bundle, or inbox.
The Clickwrap object
Example Clickwrap Object
{
"id": 1,
"name": "Example Site NDA for Files.com Use",
"body": "[Legal body text]",
"use_with_users": "",
"use_with_bundles": "",
"use_with_inboxes": ""
}
<?xml version="1.0" encoding="UTF-8"?>
<clickwrap>
<id type="integer">1</id>
<name>Example Site NDA for Files.com Use</name>
<body>[Legal body text]</body>
<use_with_users></use_with_users>
<use_with_bundles></use_with_bundles>
<use_with_inboxes></use_with_inboxes>
</clickwrap>
| Attribute | Description |
|---|---|
| id int64 | Clickwrap ID |
| name string | Name of the Clickwrap agreement (used when selecting from multiple Clickwrap agreements.) |
| body string | Body text of Clickwrap (supports Markdown formatting). |
| use_with_users string | Use this Clickwrap for User Registrations? Note: This only applies to User Registrations where the User is invited to your Files.com site using an E-Mail invitation process where they then set their own password. Possible values: none, require |
| use_with_bundles string | Use this Clickwrap for Bundles? Possible values: none, available, require |
| use_with_inboxes string | Use this Clickwrap for Inboxes? Possible values: none, available, require |
List Clickwraps
Example Request
curl "https://app.files.com/api/rest/v1/clickwraps.json?per_page=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/clickwraps.xml?per_page=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::Clickwrap.list(
per_page: 1
)
\Files\Model\Clickwrap::list(array(
'per_page' => 1
));
["HashMap<Object, String> requestParams = new HashMap<>();\n"]requestParams.put("per_page", 1);
Clickwrap.list(parameters)
await Clickwrap.list({
per_page: 1,
})
var parameters = new Dictionary<string, object>();
parameters.Add("per_page", 1);
Clickwrap.List(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.clickwrap.list({
"per_page": 1
})
Example Response
[
{
"id": 1,
"name": "Example Site NDA for Files.com Use",
"body": "[Legal body text]",
"use_with_users": "",
"use_with_bundles": "",
"use_with_inboxes": ""
}
]
<?xml version="1.0" encoding="UTF-8"?>
<clickwraps type="array">
<clickwrap>
<id type="integer">1</id>
<name>Example Site NDA for Files.com Use</name>
<body>[Legal body text]</body>
<use_with_users></use_with_users>
<use_with_bundles></use_with_bundles>
<use_with_inboxes></use_with_inboxes>
</clickwrap>
</clickwraps>
HTTPS Request
GET /clickwraps
Authentication Required
Available to all authenticated keys or sessions.
Request Parameters
| Parameter | Description |
|---|---|
| cursor string | Used for pagination. Send a cursor value 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-Next header. |
| per_page int64 | Number of records to show per page. (Max: 10,000, 1,000 or less is recommended). |
Show Clickwrap
Example Request
curl https://app.files.com/api/rest/v1/clickwraps/{id}.json \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl https://app.files.com/api/rest/v1/clickwraps/{id}.xml \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::Clickwrap.find(id)
\Files\Model\Clickwrap::find($id);
[]
Clickwrap.find(, parametersasdf
await Clickwrap.find(id)
Clickwrap.Find(id);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.clickwrap.find(id)
Example Response
{
"id": 1,
"name": "Example Site NDA for Files.com Use",
"body": "[Legal body text]",
"use_with_users": "",
"use_with_bundles": "",
"use_with_inboxes": ""
}
<?xml version="1.0" encoding="UTF-8"?>
<clickwrap>
<id type="integer">1</id>
<name>Example Site NDA for Files.com Use</name>
<body>[Legal body text]</body>
<use_with_users></use_with_users>
<use_with_bundles></use_with_bundles>
<use_with_inboxes></use_with_inboxes>
</clickwrap>
HTTPS Request
GET /clickwraps/{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 | Clickwrap ID. |
Create Clickwrap
Example Request
curl https://app.files.com/api/rest/v1/clickwraps.json \
-X POST \
-H 'Content-Type: application/json' \
-d '{"name":"Example Site NDA for Files.com Use","body":"[Legal body text]"}' \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl https://app.files.com/api/rest/v1/clickwraps.xml \
-X POST \
-H 'Content-Type: application/xml' \
-d '<clickwrap>
<name>Example Site NDA for Files.com Use</name>
<body>[Legal body text]</body>
</clickwrap>'
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::Clickwrap.create(
name: "Example Site NDA for Files.com Use",
body: "[Legal body text]"
)
\Files\Model\Clickwrap::create(array(
'name' => "Example Site NDA for Files.com Use",
'body' => "[Legal body text]"
));
["HashMap<Object, String> requestParams = new HashMap<>();\n"]requestParams.put("name", Example Site NDA for Files.com Use);
requestParams.put("body", [Legal body text]);
Clickwrap.create(parameters)
await Clickwrap.create({
name: "Example Site NDA for Files.com Use",
body: "[Legal body text]",
})
var parameters = new Dictionary<string, object>();
parameters.Add("name", "Example Site NDA for Files.com Use");
parameters.Add("body", "[Legal body text]");
Clickwrap.Create(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.clickwrap.create({
"name": "Example Site NDA for Files.com Use",
"body": "[Legal body text]"
})
Example Response
{
"id": 1,
"name": "Example Site NDA for Files.com Use",
"body": "[Legal body text]",
"use_with_users": "",
"use_with_bundles": "",
"use_with_inboxes": ""
}
<?xml version="1.0" encoding="UTF-8"?>
<clickwrap>
<id type="integer">1</id>
<name>Example Site NDA for Files.com Use</name>
<body>[Legal body text]</body>
<use_with_users></use_with_users>
<use_with_bundles></use_with_bundles>
<use_with_inboxes></use_with_inboxes>
</clickwrap>
HTTPS Request
POST /clickwraps
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 | Name of the Clickwrap agreement (used when selecting from multiple Clickwrap agreements.) |
| body string | Body text of Clickwrap (supports Markdown formatting). |
| use_with_bundles string | Use this Clickwrap for Bundles? Possible values: none, available, require |
| use_with_inboxes string | Use this Clickwrap for Inboxes? Possible values: none, available, require |
| use_with_users string | Use this Clickwrap for User Registrations? Note: This only applies to User Registrations where the User is invited to your Files.com site using an E-Mail invitation process where they then set their own password. Possible values: none, require |
Update Clickwrap
Example Request
curl https://app.files.com/api/rest/v1/clickwraps/{id}.json \
-X PATCH \
-H 'Content-Type: application/json' \
-d '{"name":"Example Site NDA for Files.com Use","body":"[Legal body text]"}' \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl https://app.files.com/api/rest/v1/clickwraps/{id}.xml \
-X PATCH \
-H 'Content-Type: application/xml' \
-d '<clickwrap>
<name>Example Site NDA for Files.com Use</name>
<body>[Legal body text]</body>
</clickwrap>'
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
clickwrap = Files::Clickwrap.list_for(path).first
clickwrap.update(
name: "Example Site NDA for Files.com Use",
body: "[Legal body text]"
)
$clickwrap = \Files\Model\Clickwrap::listFor($path)[0];
$clickwrap->update(array(
'name' => "Example Site NDA for Files.com Use",
'body' => "[Legal body text]"
));
Clickwrap clickwrap = Clickwrap.listFor(path);
clickwrap.setName("Example Site NDA for Files.com Use");
clickwrap.setBody("[Legal body text]");
clickwrap.update();
const clickwrap = (await Clickwrap.listFor(path))[0]
await clickwrap.update({
name: "Example Site NDA for Files.com Use",
body: "[Legal body text]",
})
var Clickwrap = Clickwrap.ListFor(path)[0];
var parameters = new Dictionary<string, object>();
parameters.Add("name", "Example Site NDA for Files.com Use");
parameters.Add("body", "[Legal body text]");
Clickwrap.Update(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
clickwrap = files_sdk.clickwrap.find(id)
clickwrap.update({
name: "Example Site NDA for Files.com Use",
body: "[Legal body text]"
})
Example Response
{
"id": 1,
"name": "Example Site NDA for Files.com Use",
"body": "[Legal body text]",
"use_with_users": "",
"use_with_bundles": "",
"use_with_inboxes": ""
}
<?xml version="1.0" encoding="UTF-8"?>
<clickwrap>
<id type="integer">1</id>
<name>Example Site NDA for Files.com Use</name>
<body>[Legal body text]</body>
<use_with_users></use_with_users>
<use_with_bundles></use_with_bundles>
<use_with_inboxes></use_with_inboxes>
</clickwrap>
HTTPS Request
PATCH /clickwraps/{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 | Clickwrap ID. |
| name string | Name of the Clickwrap agreement (used when selecting from multiple Clickwrap agreements.) |
| body string | Body text of Clickwrap (supports Markdown formatting). |
| use_with_bundles string | Use this Clickwrap for Bundles? Possible values: none, available, require |
| use_with_inboxes string | Use this Clickwrap for Inboxes? Possible values: none, available, require |
| use_with_users string | Use this Clickwrap for User Registrations? Note: This only applies to User Registrations where the User is invited to your Files.com site using an E-Mail invitation process where they then set their own password. Possible values: none, require |
Delete Clickwrap
Example Request
curl https://app.files.com/api/rest/v1/clickwraps/{id}.json \
-X DELETE \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl https://app.files.com/api/rest/v1/clickwraps/{id}.xml \
-X DELETE \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
clickwrap = Files::Clickwrap.list_for(path).first
clickwrap.delete
$clickwrap = \Files\Model\Clickwrap::listFor($path)[0];
$clickwrap->delete();
Clickwrap clickwrap = Clickwrap.listFor(path);
clickwrap.delete();
const clickwrap = (await Clickwrap.listFor(path))[0]
await clickwrap.delete()
var Clickwrap = Clickwrap.ListFor(path)[0];
Clickwrap.Delete();
files_sdk.set_api_key("YOUR_API_KEY")
clickwrap = files_sdk.clickwrap.find(id)
clickwrap.delete()
Example Response
No response.
No response.
HTTPS Request
DELETE /clickwraps/{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 | Clickwrap 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?per_page=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/dns_records.xml?per_page=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::DnsRecord.list(
per_page: 1
)
\Files\Model\DnsRecord::list(array(
'per_page' => 1
));
["HashMap<Object, String> requestParams = new HashMap<>();\n"]requestParams.put("per_page", 1);
DnsRecord.list(parameters)
await DnsRecord.list({
per_page: 1,
})
var parameters = new Dictionary<string, object>();
parameters.Add("per_page", 1);
DnsRecord.List(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.dns_record.list({
"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 |
|---|---|
| cursor string | Used for pagination. Send a cursor value 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-Next header. |
| per_page int64 | Number of records to show per page. (Max: 10,000, 1,000 or less is recommended). |
External Events
ExternalEvents record activity such as logins, credential syncs, and lockouts.
The ExternalEvent object
Example ExternalEvent Object
{
"event_type": "",
"status": "",
"body": "",
"created_at": "2000-01-01T01:00:00Z"
}
<?xml version="1.0" encoding="UTF-8"?>
<external-event>
<event_type></event_type>
<status></status>
<body></body>
<created_at>2000-01-01T01:00:00Z</created_at>
</external-event>
| Attribute | Description |
|---|---|
| event_type string | Type of event being recorded. Valid values: remote_server_sync, lockout, ldap_login, saml_login Possible values: ldap_sync, remote_server_sync, lockout, ldap_login, saml_login |
| status string | Status of event. Valid values: error Possible values: success, error |
| body string | Event body |
| created_at date-time | External event create date/time |
List External Events
Example Request
curl "https://app.files.com/api/rest/v1/external_events.json?per_page=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/external_events.xml?per_page=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::ExternalEvent.list(
per_page: 1
)
\Files\Model\ExternalEvent::list(array(
'per_page' => 1
));
["HashMap<Object, String> requestParams = new HashMap<>();\n"]requestParams.put("per_page", 1);
ExternalEvent.list(parameters)
await ExternalEvent.list({
per_page: 1,
})
var parameters = new Dictionary<string, object>();
parameters.Add("per_page", 1);
ExternalEvent.List(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.external_event.list({
"per_page": 1
})
Example Response
[
{
"event_type": "",
"status": "",
"body": "",
"created_at": "2000-01-01T01:00:00Z"
}
]
<?xml version="1.0" encoding="UTF-8"?>
<external-events type="array">
<external-event>
<event_type></event_type>
<status></status>
<body></body>
<created_at>2000-01-01T01:00:00Z</created_at>
</external-event>
</external-events>
HTTPS Request
GET /external_events
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 |
|---|---|
| cursor string | Used for pagination. Send a cursor value 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-Next header. |
| per_page int64 | Number of records to show per page. (Max: 10,000, 1,000 or less is recommended). |
| sort_by object | If set, sort records by the specified field in either 'asc' or 'desc' direction (e.g. sort_by[last_login_at]=desc). Valid fields are remote_server_type, event_type, created_at or status. |
| filter object | If set, return records where the specifiied field is equal to the supplied value. Valid fields are created_at, event_type, remote_server_type or status. |
| filter_gt object | If set, return records where the specifiied field is greater than the supplied value. Valid fields are created_at, event_type, remote_server_type or status. |
| filter_gteq object | If set, return records where the specifiied field is greater than or equal to the supplied value. Valid fields are created_at, event_type, remote_server_type or status. |
| filter_like object | If set, return records where the specifiied field is equal to the supplied value. Valid fields are created_at, event_type, remote_server_type or status. |
| filter_lt object | If set, return records where the specifiied field is less than the supplied value. Valid fields are created_at, event_type, remote_server_type or status. |
| filter_lteq object | If set, return records where the specifiied field is less than or equal to the supplied value. Valid fields are created_at, event_type, remote_server_type or status. |
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
{
"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": {
"id": 1,
"status": "complete",
"download_uri": "https://mysite.files.com/...",
"type": "complete",
"size": 1024
}
}
<?xml version="1.0" encoding="UTF-8"?>
<file>
<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>
<id type="integer">1</id>
<status>complete</status>
<download_uri>https://mysite.files.com/...</download_uri>
<type>complete</type>
<size type="integer">1024</size>
</preview>
</file>
| Attribute | Description |
|---|---|
| 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 Download
// Download to file on disk.
file.saveAsLocalFile("/tmp/");
// Download to writable stream.
file.getInputStream();
// Download to file on disk. (Not available in browser.)
await file.downloadToFile(localFilePath)
// Download to writable stream. (Not available in browser.)
await file.downloadToStream(writableStream)
Example Request
curl "https://app.files.com/api/rest/v1/files/{path}?with_previews=true&with_priority_color=true" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/files/{path}?with_previews=true&with_priority_color=true" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
file = Files::File.list_for(path).first
file.download(
with_previews: true,
with_priority_color: true
)
$file = \Files\Model\File::listFor($path)[0];
$file->download(array(
'with_previews' => true,
'with_priority_color' => true
));
File file = File.listFor(path);
file.setWithPreviews(true);
file.setWithPriorityColor(true);
file.download();
const file = (await File.listFor(path))[0]
await file.download({
with_previews: true,
with_priority_color: true,
})
var File = File.ListFor(path)[0];
var parameters = new Dictionary<string, object>();
parameters.Add("with_previews", true);
parameters.Add("with_priority_color", true);
File.Download(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
file = files_sdk.file.list_for(path).first
file.download({
with_previews: True,
with_priority_color: True
})
Example Response
{
"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": {
"id": 1,
"status": "complete",
"download_uri": "https://mysite.files.com/...",
"type": "complete",
"size": 1024
}
}
<?xml version="1.0" encoding="UTF-8"?>
<file>
<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>
<id type="integer">1</id>
<status>complete</status>
<download_uri>https://mysite.files.com/...</download_uri>
<type>complete</type>
<size type="integer">1024</size>
</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. |
| preview_size string | Request a preview size. Can be small (default), large, xlarge, or pdf. |
| 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}?per_page=1&search_all=true&with_previews=true&with_priority_color=true" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/folders/{path}?per_page=1&search_all=true&with_previews=true&with_priority_color=true" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::Folder.list_for(path,
per_page: 1,
search_all: true,
with_previews: true,
with_priority_color: true
)
\Files\Model\Folder::listFor($path, array(
'per_page' => 1,
'search_all' => true,
'with_previews' => true,
'with_priority_color' => true
));
["HashMap<Object, String> requestParams = new HashMap<>();\n"]requestParams.put("per_page", 1);
requestParams.put("search_all", true);
requestParams.put("with_previews", true);
requestParams.put("with_priority_color", true);
Folder.listFor(parameters)
await Folder.listFor(path, {
per_page: 1,
search_all: true,
with_previews: true,
with_priority_color: true,
})
var parameters = new Dictionary<string, object>();
parameters.Add("per_page", 1);
parameters.Add("search_all", true);
parameters.Add("with_previews", true);
parameters.Add("with_priority_color", true);
Folder.ListFor(path, parameters);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.folder.list_for(path, {
"per_page": 1,
"search_all": True,
"with_previews": True,
"with_priority_color": True
})
Example Response
[
{
"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": {
"id": 1,
"status": "complete",
"download_uri": "https://mysite.files.com/...",
"type": "complete",
"size": 1024
}
}
]
<?xml version="1.0" encoding="UTF-8"?>
<files type="array">
<file>
<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>
<id type="integer">1</id>
<status>complete</status>
<download_uri>https://mysite.files.com/...</download_uri>
<type>complete</type>
<size type="integer">1024</size>
</preview>
</file>
</files>
HTTPS Request
GET /folders/{path}
Authentication Required
Available to all authenticated keys or sessions.
Request Parameters
| Parameter | Description |
|---|---|
| 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. |
| per_page int64 | Number of records to show per page. (Max: 10,000, 1,000 or less is recommended). |
| path string Required | Path to operate on. |
| filter string | If specified, will 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_previews boolean | Include file previews? |
| 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.
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\Model\Folder::create($path);
[]
Folder.create(, parametersasdf
await Folder.create(path)
Folder.Create(path);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.folder.create(path)
Example Response
{
"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": {
"id": 1,
"status": "complete",
"download_uri": "https://mysite.files.com/...",
"type": "complete",
"size": 1024
}
}
<?xml version="1.0" encoding="UTF-8"?>
<file>
<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>
<id type="integer">1</id>
<status>complete</status>
<download_uri>https://mysite.files.com/...</download_uri>
<type>complete</type>
<size type="integer">1024</size>
</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.list_for(path).first
file.update(
provided_mtime: "2000-01-01T01:00:00Z",
priority_color: "red"
)
$file = \Files\Model\File::listFor($path)[0];
$file->update(array(
'provided_mtime' => "2000-01-01T01:00:00Z",
'priority_color' => "red"
));
File file = File.listFor(path);
file.setProvidedMtime("2000-01-01T01:00:00Z");
file.setPriorityColor("red");
file.update();
const file = (await File.listFor(path))[0]
await file.update({
provided_mtime: "2000-01-01T01:00:00Z",
priority_color: "red",
})
var File = File.ListFor(path)[0];
var parameters = new Dictionary<string, object>();
parameters.Add("provided_mtime", "2000-01-01T01:00:00Z");
parameters.Add("priority_color", "red");
File.Update(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
file = files_sdk.file.list_for(path).first
file.update({
provided_mtime: "2000-01-01T01:00:00Z",
priority_color: "red"
})
Example Response
{
"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": {
"id": 1,
"status": "complete",
"download_uri": "https://mysite.files.com/...",
"type": "complete",
"size": 1024
}
}
<?xml version="1.0" encoding="UTF-8"?>
<file>
<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>
<id type="integer">1</id>
<status>complete</status>
<download_uri>https://mysite.files.com/...</download_uri>
<type>complete</type>
<size type="integer">1024</size>
</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.list_for(path).first
file.delete(
recursive: true
)
$file = \Files\Model\File::listFor($path)[0];
$file->delete(array(
'recursive' => true
));
File file = File.listFor(path);
file.delete();
const file = (await File.listFor(path))[0]
await file.delete({
recursive: true,
})
var File = File.ListFor(path)[0];
var parameters = new Dictionary<string, object>();
parameters.Add("recursive", true);
File.Delete(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
file = files_sdk.file.list_for(path).first
file.delete({
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. |
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:
|
| 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>'
# Upload a file on disk.
\Files\Model\File::uploadFile($destinationFileName, $sourceFilePath);
# Upload raw file data.
\Files\Model\File::uploadData($destinationFileName, $fileData);
// Upload a file on disk. (Not available in browser.)
const file = await File.uploadFile(destinationFileName, sourceFilePath)
// Upload raw file data.
const file = await File.uploadData(destinationFileName, fileData)
// Upload from readable stream.
const file = await File.uploadStream(destinationFileName, readableStream)
// Upload a file from disk.
RemoteFile.UploadFile(LocalPath, Path);
# Upload a file on disk.
files_sdk.upload_file(local_path, path)
# Upload raw file data (string)
with files_sdk.open(path, 'w') as f:
f.write(string_data)
# Upload raw file data (binary)
with files_sdk.open(path, 'wb') as f:
f.write(bytes_data)
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&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_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 Actions
The FileActions resource in the REST API allows you to operate on FileActions.
The FileAction object
Example FileAction Object
{
"status": "enqueued",
"file_migration_id": "123"
}
<?xml version="1.0" encoding="UTF-8"?>
<file-action>
<status>enqueued</status>
<file_migration_id>123</file_migration_id>
</file-action>
| Attribute | Description |
|---|---|
| status string | Status of file operation. Possible values: completed, enqueued. |
| file_migration_id int64 | If status is enqueued, this is the id of the FileMigration to check for status updates. |
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","structure":true}' \
-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-action>
<destination>destination</destination>
<structure type="boolean">true</structure>
</file-action>'
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
file_action = Files::FileAction.list_for(path).first
file_action.copy(
destination: "destination",
structure: true
)
$file_action = \Files\Model\FileAction::listFor($path)[0];
$file_action->copy(array(
'destination' => "destination",
'structure' => true
));
FileAction fileAction = FileAction.listFor(path);
fileAction.setDestination("destination");
fileAction.setStructure(true);
fileAction.copy();
const fileAction = (await FileAction.listFor(path))[0]
await fileAction.copy({
destination: "destination",
structure: true,
})
var FileAction = FileAction.ListFor(path)[0];
var parameters = new Dictionary<string, object>();
parameters.Add("destination", "destination");
parameters.Add("structure", true);
FileAction.Copy(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
file_action = files_sdk.file_action.list_for(path).first
file_action.copy({
destination: "destination",
structure: True
})
Example Response
{
"status": "enqueued",
"file_migration_id": "123"
}
<?xml version="1.0" encoding="UTF-8"?>
<file-action>
<status>enqueued</status>
<file_migration_id>123</file_migration_id>
</file-action>
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. |
| structure boolean | Copy structure only? |
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-action>
<destination>destination</destination>
</file-action>'
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
file_action = Files::FileAction.list_for(path).first
file_action.move(
destination: "destination"
)
$file_action = \Files\Model\FileAction::listFor($path)[0];
$file_action->move(array(
'destination' => "destination"
));
FileAction fileAction = FileAction.listFor(path);
fileAction.setDestination("destination");
fileAction.move();
const fileAction = (await FileAction.listFor(path))[0]
await fileAction.move({
destination: "destination",
})
var FileAction = FileAction.ListFor(path)[0];
var parameters = new Dictionary<string, object>();
parameters.Add("destination", "destination");
FileAction.Move(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
file_action = files_sdk.file_action.list_for(path).first
file_action.move({
destination: "destination"
})
Example Response
{
"status": "enqueued",
"file_migration_id": "123"
}
<?xml version="1.0" encoding="UTF-8"?>
<file-action>
<status>enqueued</status>
<file_migration_id>123</file_migration_id>
</file-action>
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. |
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": [
{
"id": 1,
"emoji": "👍"
}
]
}
<?xml version="1.0" encoding="UTF-8"?>
<file-comment>
<id type="integer">1</id>
<body>What a great file!</body>
<reactions type="array">
<reaction>
<id type="integer">1</id>
<emoji>👍</emoji>
</reaction>
</reactions>
</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}?per_page=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/file_comments/files/{path}?per_page=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::FileComment.list_for(path,
per_page: 1
)
\Files\Model\FileComment::listFor($path, array(
'per_page' => 1
));
["HashMap<Object, String> requestParams = new HashMap<>();\n"]requestParams.put("per_page", 1);
FileComment.listFor(parameters)
await FileComment.listFor(path, {
per_page: 1,
})
var parameters = new Dictionary<string, object>();
parameters.Add("per_page", 1);
FileComment.ListFor(path, parameters);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.file_comment.list_for(path, {
"per_page": 1
})
Example Response
[
{
"id": 1,
"body": "What a great file!",
"reactions": [
{
"id": 1,
"emoji": "👍"
}
]
}
]
<?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">
<reaction>
<id type="integer">1</id>
<emoji>👍</emoji>
</reaction>
</reactions>
</file-comment>
</file-comments>
HTTPS Request
GET /file_comments/files/{path}
Authentication Required
Available to all authenticated keys or sessions.
Request Parameters
| Parameter | Description |
|---|---|
| cursor string | Used for pagination. Send a cursor value 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-Next header. |
| per_page int64 | Number of records to show per page. (Max: 10,000, 1,000 or less is recommended). |
| 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\Model\FileComment::create(array(
'body' => "body",
'path' => "path"
));
["HashMap<Object, String> requestParams = new HashMap<>();\n"]requestParams.put("body", body);
requestParams.put("path", path);
FileComment.create(parameters)
await FileComment.create({
body: "body",
path: "path",
})
var parameters = new Dictionary<string, object>();
parameters.Add("body", "body");
parameters.Add("path", "path");
FileComment.Create(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.file_comment.create({
"body": "body",
"path": "path"
})
Example Response
{
"id": 1,
"body": "What a great file!",
"reactions": [
{
"id": 1,
"emoji": "👍"
}
]
}
<?xml version="1.0" encoding="UTF-8"?>
<file-comment>
<id type="integer">1</id>
<body>What a great file!</body>
<reactions type="array">
<reaction>
<id type="integer">1</id>
<emoji>👍</emoji>
</reaction>
</reactions>
</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.list_for(path).first
file_comment.update(
body: "body"
)
$file_comment = \Files\Model\FileComment::listFor($path)[0];
$file_comment->update(array(
'body' => "body"
));
FileComment fileComment = FileComment.listFor(path);
fileComment.setBody("body");
fileComment.update();
const fileComment = (await FileComment.listFor(path))[0]
await fileComment.update({
body: "body",
})
var FileComment = FileComment.ListFor(path)[0];
var parameters = new Dictionary<string, object>();
parameters.Add("body", "body");
FileComment.Update(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
file_comment = files_sdk.file_comment.list_for(path).first
file_comment.update({
body: "body"
})
Example Response
{
"id": 1,
"body": "What a great file!",
"reactions": [
{
"id": 1,
"emoji": "👍"
}
]
}
<?xml version="1.0" encoding="UTF-8"?>
<file-comment>
<id type="integer">1</id>
<body>What a great file!</body>
<reactions type="array">
<reaction>
<id type="integer">1</id>
<emoji>👍</emoji>
</reaction>
</reactions>
</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.list_for(path).first
file_comment.delete
$file_comment = \Files\Model\FileComment::listFor($path)[0];
$file_comment->delete();
FileComment fileComment = FileComment.listFor(path);
fileComment.delete();
const fileComment = (await FileComment.listFor(path))[0]
await fileComment.delete()
var FileComment = FileComment.ListFor(path)[0];
FileComment.Delete();
files_sdk.set_api_key("YOUR_API_KEY")
file_comment = files_sdk.file_comment.list_for(path).first
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\Model\FileCommentReaction::create(array(
'user_id' => 1,
'file_comment_id' => 1,
'emoji' => "emoji"
));
["HashMap<Object, String> requestParams = new HashMap<>();\n"]requestParams.put("user_id", 1);
requestParams.put("file_comment_id", 1);
requestParams.put("emoji", emoji);
FileCommentReaction.create(parameters)
await FileCommentReaction.create({
user_id: 1,
file_comment_id: 1,
emoji: "emoji",
})
var parameters = new Dictionary<string, object>();
parameters.Add("user_id", 1);
parameters.Add("file_comment_id", 1);
parameters.Add("emoji", "emoji");
FileCommentReaction.Create(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.file_comment_reaction.create({
"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.list_for(path).first
file_comment_reaction.delete
$file_comment_reaction = \Files\Model\FileCommentReaction::listFor($path)[0];
$file_comment_reaction->delete();
FileCommentReaction fileCommentReaction = FileCommentReaction.listFor(path);
fileCommentReaction.delete();
const fileCommentReaction = (await FileCommentReaction.listFor(path))[0]
await fileCommentReaction.delete()
var FileCommentReaction = FileCommentReaction.ListFor(path)[0];
FileCommentReaction.Delete();
files_sdk.set_api_key("YOUR_API_KEY")
file_comment_reaction = files_sdk.file_comment_reaction.list_for(path).first
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 Upload Parts
The FileUploadParts resource in the REST API allows you to operate on FileUploadParts.
The FileUploadPart object
Example FileUploadPart Object
{
"send": "",
"action": "multipart",
"ask_about_overwrites": true,
"available_parts": 1,
"expires": "",
"headers": "",
"http_method": "PUT",
"next_partsize": 1,
"parallel_parts": true,
"parameters": "{}",
"part_number": 1,
"partsize": 1,
"path": "",
"ref": "upload-1",
"upload_uri": ""
}
<?xml version="1.0" encoding="UTF-8"?>
<file-upload-part>
<send></send>
<action>multipart</action>
<ask_about_overwrites type="boolean">true</ask_about_overwrites>
<available_parts type="integer">1</available_parts>
<expires></expires>
<headers></headers>
<http_method>PUT</http_method>
<next_partsize type="integer">1</next_partsize>
<parallel_parts type="boolean">true</parallel_parts>
<parameters>{}</parameters>
<part_number type="integer">1</part_number>
<partsize type="integer">1</partsize>
<path></path>
<ref>upload-1</ref>
<upload_uri></upload_uri>
</file-upload-part>
| Attribute | Description |
|---|---|
| send object | Content-Type and File to send |
| action string | Type of upload |
| ask_about_overwrites boolean | If true, this file exists and you may wish to ask the user for overwrite confirmation |
| available_parts int64 | Number of parts in the upload |
| expires string | Date/time of when this Upload part expires and the URL cannot be used any more |
| headers object | Additional upload headers to provide as part of the upload |
| http_method string | HTTP Method to use for uploading the part, usually PUT |
| next_partsize int64 | Size in bytes for this part |
| parallel_parts boolean | If true, multiple parts may be uploaded in parallel. If false, be sure to only upload one part at a time, in order. |
| parameters object | Additional HTTP parameters to send with the upload |
| part_number int64 | Number of this upload part |
| partsize int64 | Size in bytes for the next upload part |
| path string | New file 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-upload-parts>
<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-upload-parts>'
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
file_action = Files::FileAction.list_for(path).first
file_action.begin_upload(
mkdir_parents: true,
part: 1,
parts: 1,
ref: "upload-1",
restart: 1,
with_rename: true
)
$file_action = \Files\Model\FileAction::listFor($path)[0];
$file_action->beginUpload(array(
'mkdir_parents' => true,
'part' => 1,
'parts' => 1,
'ref' => "upload-1",
'restart' => 1,
'with_rename' => true
));
FileAction fileAction = FileAction.listFor(path);
fileAction.setMkdirParents(true);
fileAction.setPart(1);
fileAction.setParts(1);
fileAction.setRef("upload-1");
fileAction.setRestart(1);
fileAction.setWithRename(true);
fileAction.beginUpload();
const fileAction = (await FileAction.listFor(path))[0]
await fileAction.beginUpload({
mkdir_parents: true,
part: 1,
parts: 1,
ref: "upload-1",
restart: 1,
with_rename: true,
})
var FileAction = FileAction.ListFor(path)[0];
var parameters = new Dictionary<string, object>();
parameters.Add("mkdir_parents", true);
parameters.Add("part", 1);
parameters.Add("parts", 1);
parameters.Add("ref", "upload-1");
parameters.Add("restart", 1);
parameters.Add("with_rename", true);
FileAction.BeginUpload(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
file_action = files_sdk.file_action.list_for(path).first
file_action.begin_upload({
mkdir_parents: True,
part: 1,
parts: 1,
ref: "upload-1",
restart: 1,
with_rename: True
})
Example Response
[
{
"send": "",
"action": "multipart",
"ask_about_overwrites": true,
"available_parts": 1,
"expires": "",
"headers": "",
"http_method": "PUT",
"next_partsize": 1,
"parallel_parts": true,
"parameters": "{}",
"part_number": 1,
"partsize": 1,
"path": "",
"ref": "upload-1",
"upload_uri": ""
}
]
<?xml version="1.0" encoding="UTF-8"?>
<file-upload-parts type="array">
<file-upload-part>
<send></send>
<action>multipart</action>
<ask_about_overwrites type="boolean">true</ask_about_overwrites>
<available_parts type="integer">1</available_parts>
<expires></expires>
<headers></headers>
<http_method>PUT</http_method>
<next_partsize type="integer">1</next_partsize>
<parallel_parts type="boolean">true</parallel_parts>
<parameters>{}</parameters>
<part_number type="integer">1</part_number>
<partsize type="integer">1</partsize>
<path></path>
<ref>upload-1</ref>
<upload_uri></upload_uri>
</file-upload-part>
</file-upload-parts>
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? |
Form Field Sets
Form Field Sets define a custom forms to be used for bundle and inbox registrations.
Each Form Field Set contains one or more Form Fields. A form and all of its form fields are submitted in a single create request. The order of form fields in the array is the order they will be displayed.
Once created, a form field set can then be associated with one or more bundle(s) and/or inbox(s). Once associated, you will be required to submit well-formatted form-data when creating a bundle-registration or inbox registration.
The FormFieldSet object
Example FormFieldSet Object
{
"id": 1,
"title": "Sample Form Title",
"form_layout": [
1,
2,
3,
4
],
"form_fields": [
{
"id": 1,
"label": "Sample Label",
"required": true,
"help_text": "Help Text",
"field_type": "text",
"options_for_select": [
"red",
"green",
"blue"
],
"default_option": "red",
"form_field_set_id": 1
}
]
}
<?xml version="1.0" encoding="UTF-8"?>
<form-field-set>
<id type="integer">1</id>
<title>Sample Form Title</title>
<form_layout type="array">
<form_layout type="integer">1</form_layout>
<form_layout type="integer">2</form_layout>
<form_layout type="integer">3</form_layout>
<form_layout type="integer">4</form_layout>
</form_layout>
<form_fields type="array">
<form_field>
<id type="integer">1</id>
<label>Sample Label</label>
<required type="boolean">true</required>
<help_text>Help Text</help_text>
<field_type>text</field_type>
<options_for_select type="array">
<options_for_select>red</options_for_select>
<options_for_select>green</options_for_select>
<options_for_select>blue</options_for_select>
</options_for_select>
<default_option>red</default_option>
<form_field_set_id type="integer">1</form_field_set_id>
</form_field>
</form_fields>
</form-field-set>
| Attribute | Description |
|---|---|
| id int64 | Form field set id |
| title string | Title to be displayed |
| form_layout int64 | Layout of the form |
| form_fields array | Associated form fields |
| user_id int64 | User ID. Provide a value of 0 to operate the current session's user. |
List Form Field Sets
Example Request
curl "https://app.files.com/api/rest/v1/form_field_sets.json?user_id=1&per_page=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/form_field_sets.xml?user_id=1&per_page=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::FormFieldSet.list(
user_id: 1,
per_page: 1
)
\Files\Model\FormFieldSet::list(array(
'user_id' => 1,
'per_page' => 1
));
["HashMap<Object, String> requestParams = new HashMap<>();\n"]requestParams.put("user_id", 1);
requestParams.put("per_page", 1);
FormFieldSet.list(parameters)
await FormFieldSet.list({
user_id: 1,
per_page: 1,
})
var parameters = new Dictionary<string, object>();
parameters.Add("user_id", 1);
parameters.Add("per_page", 1);
FormFieldSet.List(parameters);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.form_field_set.list({
"user_id": 1,
"per_page": 1
})
Example Response
[
{
"id": 1,
"title": "Sample Form Title",
"form_layout": [
1,
2,
3,
4
],
"form_fields": [
{
"id": 1,
"label": "Sample Label",
"required": true,
"help_text": "Help Text",
"field_type": "text",
"options_for_select": [
"red",
"green",
"blue"
],
"default_option": "red",
"form_field_set_id": 1
}
]
}
]
<?xml version="1.0" encoding="UTF-8"?>
<form-field-sets type="array">
<form-field-set>
<id type="integer">1</id>
<title>Sample Form Title</title>
<form_layout type="array">
<form_layout type="integer">1</form_layout>
<form_layout type="integer">2</form_layout>
<form_layout type="integer">3</form_layout>
<form_layout type="integer">4</form_layout>
</form_layout>
<form_fields type="array">
<form_field>
<id type="integer">1</id>
<label>Sample Label</label>
<required type="boolean">true</required>
<help_text>Help Text</help_text>
<field_type>text</field_type>
<options_for_select type="array">
<options_for_select>red</options_for_select>
<options_for_select>green</options_for_select>
<options_for_select>blue</options_for_select>
</options_for_select>
<default_option>red</default_option>
<form_field_set_id type="integer">1</form_field_set_id>
</form_field>
</form_fields>
</form-field-set>
</form-field-sets>
HTTPS Request
GET /form_field_sets
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. |
| cursor string | Used for pagination. Send a cursor value 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-Next header. |
| per_page int64 | Number of records to show per page. (Max: 10,000, 1,000 or less is recommended). |
Show Form Field Set
Example Request
curl https://app.files.com/api/rest/v1/form_field_sets/{id}.json \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl https://app.files.com/api/rest/v1/form_field_sets/{id}.xml \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::FormFieldSet.find(id)
\Files\Model\FormFieldSet::find($id);
[]
FormFieldSet.find(, parametersasdf
await FormFieldSet.find(id)
FormFieldSet.Find(id);
files_sdk.set_api_key("YOUR_API_KEY")
files_sdk.form_field_set.find(id)
Example Response
{
"id": 1,
"title": "Sample Form Title",
"form_layout": [
1,
2,
3,
4
],
"form_fields": [
{
"id": 1,
"label": "Sample Label",
"required": true,
"help_text": "Help Text",
"field_type": "text",
"options_for_select": [
"red",
"green",
"blue"
],
"default_option": "red",
"form_field_set_id": 1
}
]
}
<?xml version="1.0" encoding="UTF-8"?>
<form-field-set>
<id type="integer">1</id>
<title>Sample Form Title</title>
<form_layout type="array">