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.
Attaching Files to API Requests
Certain API endpoints allow you to upload files to configure certain objects on the API. Examples of this include uploading avatars to a user record or custom background image for your login screen.
The process used to upload these sorts of files to the API is separate from the main process of uploading files to your Files.com site as part of an actual business file transfer.
Any time an API endpoint accepts a parameter with type File
, there are two different ways to upload that file.
One way is to upload it as an HTTP POST parameter using the HTTP multipart/form-data
standard. This is the same way that a file that gets uploaded by web browsers when you create a <form method="post" enctype="mulitpart/form-data">
form in HTML that contains an <input type="file" />
field. The upside of this approach is that it uses a completely standard HTTP technique for uploading files. The downside to this approach is that it breaks from the pattern used everywhere else in our API where JSON bodies are preferred for POST/PUT requests.
As a result of that, the preferred way to upload a file to our API uses a non-standard technique of encoding the file as Base64 and including that Base64 representation in the standard JSON body of the POST/PUT request. When using this approach, you will provide a JSON object with 3 elements:
filename
- the file name of the filetype
- the MIME type of the fileencoded_data
- the actual data of the file encoded using Base64
Please see the cURL example code on the right for an example of the exact format.
When using our SDKs and integrations, please be aware that (unfortunately) support for File Attachments to API requests is somewhat inconsistent. We are very interested in adding support to any SDKs where a customer needs this capability, so please reach out to us and we'll be happy to help.
Paginating List Requests
Example Paginating List Requests
curl https://SUBDOMAIN.files.com/api/rest/v1/users.json?cursor=CURSOR \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl https://SUBDOMAIN.files.com/api/rest/v1/users.xml?cursor=CURSOR \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
// List root folder with auto pagination (loads each page into memory)
for (Folder item : Folder.listFor("/", null).listAutoPaging()) {
System.out.println(item.path);
}
// List root folder with manual pagination (loads each page into memory)
ListIterator<Folder> listing = Folder.listFor("/", null);
do {
for (Folder item : listing.loadNextPage()) {
System.out.println(item.path);
}
} while (listing.hasNextPage());
// if auto-pagination executed, we'll see results from all pages
Files.configureNetwork({
autoPaginate: true,
})
const allPageItems = await Folder.listFor('/')
# if auto-paginng executed, we'll see results from all pages
Files::User.list.auto_paging_each { |u| puts u.username }
// true by default
Files::$autoPaginate = true;
\Files\Model\User::list();
// List root folder with auto pagination (loads each page into memory)
foreach (var file in Folder.ListFor("/").ListAutoPaging())
{
Console.WriteLine("- Path: {0}", file.Path);
}
// List root folder with manual pagination (loads each page into memory)
FilesList<RemoteFile> listing = Folder.ListFor("/");
do
{
foreach (var file in await listing.LoadNextPage())
{
Console.WriteLine("- Path: {0}", file.Path);
}
} while (listing.HasNextPage);
list_obj = files_sdk.folder.list_for('/')
# Iterating with with auto_paging_iter
for f in list_obj.auto_paging_iter():
print(f.type, f.path)
# Iterating manually
while list_obj.has_next_page:
list_obj.load_next_page()
for f in list_obj:
print(f.type, f.path)
// To have it auto-paginate set ListParams.MaxPages, default is 1.
user.List(files_sdk.UserListParams{
ListParams: files_sdk.ListParams{
MaxPages: 10,
},
})
Auto-paging is enabled by default. Change --max-pages option to limit the number of pages.
files-cli folders ls --max-pages=2
Certain API list endpoints return lists of objects. For example, the GET /users
endpoint returns a list of User
objects. When the number of objects in the list is large, the API will paginate the results.
All of our APIs provide iterator methods that will automatically paginate through lists that span more than one page of results. Check the documentation for your preferred SDK for additional information.
When using the API directly, there are two GET parameters that control pagination on list requests:
Parameter | Description |
---|---|
cursor string | Cursor representing a point from a previous list request to resume from on this request. |
per_page integer | Number of records to show per page. Default: 1,000. Max: 10,000. 1,000 or less is recommended. |
List requests that have another page of records available will return the HTTP header X-Files-Cursor-Next
. This header will contain a value to be used as the cursor
parameter when you load the next page of the list.
If a cursor was provided to access the page, the API will also return X-Files-Cursor-Prev
which is a cursor that can be used to navigate to the previous page of results.
When using a cursor, you must keep the per_page
value (number of records per page) consistent between pages.
Extracting Information from the Cursor
The cursor is a string which consists of a page number prefix and an encrypted cursor part separated by a colon (:
).
Example: PAGE_NUMBER:encrypted_cursor_part
. You can use the page number to show a page number in a UI, if applicable.
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"})
files_sdk.APIKey = "YOUR_API_KEY"
// Alternatively, you can specify the API key on a per-request basis using the Config struct.
config := files_sdk.Config{APIKey: "XXXX-XXXX..."}
client := folder.Client{Config: config}
client.ListFor(context.Background(), files_sdk.FolderListForParams{})
files-cli folders list-for --api-key=YOUR_API_KEY
Make sure to replace
YOUR_API_KEY
with your API key.
To use the API or SDKs with an API Key, first generate an API key from the web interface or via the API or an SDK.
Note that when using a user-specific API key, if the user is an administrator, you will have full access to the entire API. If the user is not an administrator, you will only be able to access files that user can access, and no access will be granted to site administration functions in the API.
You may provide the key to the API one of two ways. The simplest way is to set the X-FilesAPI-Key
header with the value of the key.
Alternatively, you may use HTTP Basic Authentication. You should pass in the API Key as the Username field in HTTP Basic Authentication. The password field may be left blank, or you may use a dummy value, such as x
.
SDKs can be configured to use a single API key or you can pass the API key to each individual method on the SDK.
Authentication with a Session
You can also authenticate to the REST API or SDKs by creating a user session using the username and password of an active user. If the user is an administrator, the session will have full access to the entire API. Sessions created from regular user accounts will only be able to access files that user can access, and no access will be granted to site administration functions.
API sessions use the exact same session timeout settings as web interface sessions. When an API session times out, simply create a new session and resume where you left off. This process is not automatically handled by SDKs because we do not want to store password information in memory without your explicit consent.
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" })
config := files_sdk.Config{Subdomain: "SUBDOMAIN"}
client := session.Client{Config: config}
session := client.Create(
context.Background(),
files_sdk.SessionCreateParams{
Username: "motor",
Password: "vroom",
}
)
files-cli config-set --subdomain SUBDOMAIN --username motor
files-cli folders list-for
> 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 to be used by default for subsequent requests.
files_sdk.set_session(session)
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})
config := files_sdk.Config{SessionId: session.Id, Subdomain: "SUBDOMAIN"}
userClient := users.Client{Config: config}
userClient.Find(context.Background(), files_sdk.UserFindParams{id: "1"})
files-cli config-set --subdomain SUBDOMAIN --username motor
files-cli folders list-for
> password: vroom
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()
session.Delete(context.Background(), files_sdk.SessionDeleteParams{Session: session})
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",
"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>
<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>
Example Response: Model Save Error
{
"error": "Error saving model.",
"http-code": 422,
"instance": "508503b0-2423-4edc-a46f-77d77ac4a7e3",
"model_errors": {
"username": [
"Username must not contain multiple spaces together",
"Username must not begin or end with a space"
]
},
"model_error_keys": {
"username": [
"multiple_spaces",
"leading_trailing_space"
]
},
"errors": [
"Username must not contain multiple spaces together",
"Username must not begin or end with a space"
],
"title": "Model Save Error",
"type": "processing-failure/model-save-error"
}
<?xml version="1.0" encoding="UTF-8"?>
<error_response>
<error>Error saving model.</error>
<http-code type="integer">422</http-code>
<instance>f94c6af9-b968-44dd-be09-4e5aedfd115c</instance>
<model_errors>
<username type="array">
<username>Username must not contain multiple spaces together</username>
<username>Username must not begin or end with a space</username>
</username>
</model_errors>
<model_error_keys>
<username type="array">
<username type="symbol">multiple_spaces</username>
<username type="symbol">leading_trailing_space</username>
</username>
</model_error_keys>
<errors type="array">
<error>Username must not contain multiple spaces together</error>
<error>Username must not begin or end with a space</error>
</errors>
<title>Model Save Error</title>
<type>processing-failure/model-save-error</type>
</error_response>
{
"detail": "Error saving model.",
"error": "Error saving model.",
"errors": [
"Username must not contain multiple spaces together",
"Username must not begin or end with a space"
],
"http-code": 422,
"instance": "14846924-ee4f-45ae-836e-406cad383adb",
"model_errors": {
"avatar_file": [],
"username": [
"Username must not contain multiple spaces together",
"Username must not begin or end with a space"
]
},
"title": "Model save error",
"type": "model-save-error"
}
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 occurred 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.
When the request encounters an error while creating or updating a record, the response will include three additional JSON objects: errors
, model_errors
, and model_error_keys
. The errors
object contains user friendly error strings translated into your site's default language. The model_errors
object contains the user friendly error strings from the errors
object mapped to the parameter that caused the error. The model_error_keys
object contains the translation keys used to generate the user friendly entries in model_errors
. These keys can be used for language independent error handling logic. For errors which do not have translation keys, the model_error_keys
entries will instead contain the English error string.
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 |
---|---|
bad-request |
Bad Request |
bad-request/agent-upgrade-required |
Agent Upgrade Required |
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-body |
Invalid Body |
bad-request/invalid-cursor |
Invalid Cursor |
bad-request/invalid-cursor-type-for-sort |
Invalid Cursor Type For Sort |
bad-request/invalid-etags |
Invalid Etags |
bad-request/invalid-filter-alias-combination |
Invalid Filter Alias Combination |
bad-request/invalid-filter-combination |
Invalid Filter Combination |
bad-request/invalid-filter-field |
Invalid Filter Field |
bad-request/invalid-filter-param |
Invalid Filter Param |
bad-request/invalid-input-encoding |
Invalid Input Encoding |
bad-request/invalid-interface |
Invalid Interface |
bad-request/invalid-oauth-provider |
Invalid Oauth Provider |
bad-request/invalid-path |
Invalid Path |
bad-request/invalid-return-to-url |
Invalid Return To Url |
bad-request/invalid-upload-offset |
Invalid Upload Offset |
bad-request/invalid-upload-part-gap |
Invalid Upload Part Gap |
bad-request/invalid-upload-part-size |
Invalid Upload Part Size |
bad-request/method-not-allowed |
Method Not Allowed |
bad-request/no-valid-input-params |
No Valid Input Params |
bad-request/operation-on-non-scim-resource |
Operation On Non Scim Resource |
bad-request/part-number-too-large |
Part Number Too Large |
bad-request/reauthentication-needed-fields |
Reauthentication Needed Fields |
bad-request/request-param-path-cannot-have-trailing-whitespace |
Request Param Path Cannot Have Trailing Whitespace |
bad-request/request-params-contain-invalid-character |
Request Params Contain Invalid Character |
bad-request/request-params-invalid |
Request Params Invalid |
bad-request/request-params-required |
Request Params Required |
bad-request/search-all-on-child-path |
Search All On Child Path |
bad-request/unsupported-currency |
Unsupported Currency |
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 |
not-authenticated/authentication-required |
Authentication Required |
not-authenticated/bundle-registration-code-failed |
Bundle Registration Code Failed |
not-authenticated/files-agent-token-failed |
Files Agent Token Failed |
not-authenticated/inbox-registration-code-failed |
Inbox Registration Code Failed |
not-authenticated/invalid-credentials |
Invalid Credentials |
not-authenticated/invalid-oauth |
Invalid Oauth |
not-authenticated/invalid-or-expired-code |
Invalid Or Expired Code |
not-authenticated/invalid-username-or-password |
Invalid Username Or Password |
not-authenticated/locked-out |
Locked Out |
not-authenticated/lockout-region-mismatch |
Lockout Region Mismatch |
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-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-mobile-app |
Api Key Only For Mobile App |
not-authorized/api-key-only-for-office-integration |
Api Key Only For Office Integration |
not-authorized/billing-permission-required |
Billing Permission Required |
not-authorized/bundle-maximum-uses-reached |
Bundle Maximum Uses Reached |
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/files-agent-failed-authorization |
Files Agent Failed Authorization |
not-authorized/folder-admin-or-billing-permission-required |
Folder Admin Or Billing Permission Required |
not-authorized/folder-admin-permission-required |
Folder Admin Permission Required |
not-authorized/full-permission-required |
Full Permission Required |
not-authorized/history-permission-required |
History Permission Required |
not-authorized/insufficient-permission-for-params |
Insufficient Permission For Params |
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/non-admins-must-query-by-folder-or-path |
Non Admins Must Query By Folder Or Path |
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/site-admin-required |
Site Admin Required |
not-authorized/site-files-are-immutable |
Site Files Are Immutable |
not-authorized/two-factor-authentication-required |
Two Factor Authentication Required |
not-authorized/user-id-without-site-admin |
User Id Without Site Admin |
not-authorized/write-and-bundle-permission-required |
Write And Bundle Permission Required |
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/bundle-registration-not-found |
Bundle Registration 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/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/automation-cannot-be-run-manually |
Automation Cannot Be Run Manually |
processing-failure/bundle-only-allows-previews |
Bundle Only Allows Previews |
processing-failure/bundle-operation-requires-subfolder |
Bundle Operation Requires Subfolder |
processing-failure/could-not-create-parent |
Could Not Create Parent |
processing-failure/destination-exists |
Destination Exists |
processing-failure/destination-folder-limited |
Destination Folder Limited |
processing-failure/destination-parent-conflict |
Destination Parent Conflict |
processing-failure/destination-parent-does-not-exist |
Destination Parent Does Not Exist |
processing-failure/expired-private-key |
Expired Private Key |
processing-failure/expired-public-key |
Expired Public Key |
processing-failure/export-failure |
Export Failure |
processing-failure/export-not-ready |
Export Not Ready |
processing-failure/failed-to-change-password |
Failed To Change Password |
processing-failure/file-locked |
File Locked |
processing-failure/file-not-uploaded |
File Not Uploaded |
processing-failure/file-pending-processing |
File Pending Processing |
processing-failure/file-too-big-to-decrypt |
File Too Big To Decrypt |
processing-failure/file-too-big-to-encrypt |
File Too Big To Encrypt |
processing-failure/file-uploaded-to-wrong-region |
File Uploaded To Wrong Region |
processing-failure/folder-locked |
Folder Locked |
processing-failure/folder-not-empty |
Folder Not Empty |
processing-failure/history-unavailable |
History Unavailable |
processing-failure/invalid-bundle-code |
Invalid Bundle Code |
processing-failure/invalid-file-type |
Invalid File Type |
processing-failure/invalid-filename |
Invalid Filename |
processing-failure/invalid-range |
Invalid Range |
processing-failure/model-save-error |
Model Save Error |
processing-failure/multiple-processing-errors |
Multiple Processing Errors |
processing-failure/path-too-long |
Path Too Long |
processing-failure/recipient-already-shared |
Recipient Already Shared |
processing-failure/remote-server-error |
Remote Server Error |
processing-failure/resource-locked |
Resource Locked |
processing-failure/subfolder-locked |
Subfolder Locked |
processing-failure/two-factor-authentication-code-already-sent |
Two Factor Authentication Code Already Sent |
processing-failure/two-factor-authentication-country-blacklisted |
Two Factor Authentication Country Blacklisted |
processing-failure/two-factor-authentication-general-error |
Two Factor Authentication General Error |
processing-failure/updates-not-allowed-for-remotes |
Updates Not Allowed For Remotes |
rate-limited/duplicate-share-recipient |
Duplicate Share Recipient |
rate-limited/reauthentication-rate-limited |
Reauthentication Rate Limited |
rate-limited/too-many-concurrent-requests |
Too Many Concurrent Requests |
rate-limited/too-many-login-attempts |
Too Many Login Attempts |
rate-limited/too-many-requests |
Too Many Requests |
rate-limited/too-many-shares |
Too Many Shares |
service-unavailable/agent-unavailable |
Agent Unavailable |
service-unavailable/automations-unavailable |
Automations Unavailable |
service-unavailable/uploads-unavailable |
Uploads Unavailable |
site-configuration/account-already-exists |
Account Already Exists |
site-configuration/account-overdue |
Account Overdue |
site-configuration/no-account-for-site |
No Account For Site |
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": [
null
],
"method": "paypal",
"payment_line_items": [
null
],
"payment_reversed_at": "2000-01-01T01:00:00Z",
"payment_type": "example",
"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 nil="true"/>
</invoice_line_items>
<method>paypal</method>
<payment_line_items type="array">
<payment_line_item nil="true"/>
</payment_line_items>
<payment_reversed_at>2000-01-01T01:00:00Z</payment_reversed_at>
<payment_type>example</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" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/invoices.xml" \
-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<>();
requestParams.put("per_page", 1);
Invoice.list(parameters).all()
await Invoice.list({
per_page: 1,
})
var parameters = new Dictionary<string, object>();
parameters.Add("per_page", (Int64?) 1);
await Invoice.List(parameters).All();
files_sdk.set_api_key("my-key")
files_sdk.invoice.list({
"per_page": 1
})
files_sdk.APIKey = "YOUR_API_KEY"
invoice.List(context.Background(), files_sdk.InvoiceListParams{
Cursor: "",
PerPage: 1,
})
files-cli invoices list \
--cursor="" \
--per-page=1 \
--api-key=YOUR_API_KEY
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": [
null
],
"method": "paypal",
"payment_line_items": [
null
],
"payment_reversed_at": "2000-01-01T01:00:00Z",
"payment_type": "example",
"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 nil="true"/>
</invoice_line_items>
<method>paypal</method>
<payment_line_items type="array">
<payment_line_item nil="true"/>
</payment_line_items>
<payment_reversed_at>2000-01-01T01:00:00Z</payment_reversed_at>
<payment_type>example</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
No request parameters available for this endpoint.
Pagination Params
Read more about Paginating List Requests.
List Payments
Example Request
curl "https://app.files.com/api/rest/v1/payments.json" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/payments.xml" \
-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<>();
requestParams.put("per_page", 1);
Payment.list(parameters).all()
await Payment.list({
per_page: 1,
})
var parameters = new Dictionary<string, object>();
parameters.Add("per_page", (Int64?) 1);
await Payment.List(parameters).All();
files_sdk.set_api_key("my-key")
files_sdk.payment.list({
"per_page": 1
})
files_sdk.APIKey = "YOUR_API_KEY"
payment.List(context.Background(), files_sdk.PaymentListParams{
Cursor: "",
PerPage: 1,
})
files-cli payments list \
--cursor="" \
--per-page=1 \
--api-key=YOUR_API_KEY
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": [
null
],
"method": "paypal",
"payment_line_items": [
null
],
"payment_reversed_at": "2000-01-01T01:00:00Z",
"payment_type": "example",
"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 nil="true"/>
</invoice_line_items>
<method>paypal</method>
<payment_line_items type="array">
<payment_line_item nil="true"/>
</payment_line_items>
<payment_reversed_at>2000-01-01T01:00:00Z</payment_reversed_at>
<payment_type>example</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
No request parameters available for this endpoint.
Pagination Params
Read more about Paginating List Requests.
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(, parameters
await Invoice.find(id)
await Invoice.Find(id);
files_sdk.set_api_key("my-key")
files_sdk.invoice.find(id)
files_sdk.APIKey = "YOUR_API_KEY"
invoice.Find(context.Background(), files_sdk.InvoiceFindParams{
Id: 1,
})
files-cli invoices find \
--id=1 \
--api-key=YOUR_API_KEY
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": [
null
],
"method": "paypal",
"payment_line_items": [
null
],
"payment_reversed_at": "2000-01-01T01:00:00Z",
"payment_type": "example",
"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 nil="true"/>
</invoice_line_items>
<method>paypal</method>
<payment_line_items type="array">
<payment_line_item nil="true"/>
</payment_line_items>
<payment_reversed_at>2000-01-01T01:00:00Z</payment_reversed_at>
<payment_type>example</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(, parameters
await Payment.find(id)
await Payment.Find(id);
files_sdk.set_api_key("my-key")
files_sdk.payment.find(id)
files_sdk.APIKey = "YOUR_API_KEY"
payment.Find(context.Background(), files_sdk.PaymentFindParams{
Id: 1,
})
files-cli payments find \
--id=1 \
--api-key=YOUR_API_KEY
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": [
null
],
"method": "paypal",
"payment_line_items": [
null
],
"payment_reversed_at": "2000-01-01T01:00:00Z",
"payment_type": "example",
"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 nil="true"/>
</invoice_line_items>
<method>paypal</method>
<payment_line_items type="array">
<payment_line_item nil="true"/>
</payment_line_items>
<payment_reversed_at>2000-01-01T01:00:00Z</payment_reversed_at>
<payment_type>example</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 , mobile , as2 , inbound_email , remote |
List history for specific file
Example Request
curl "https://app.files.com/api/rest/v1/history/files/{path}" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/history/files/{path}" \
-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<>();
requestParams.put("display", Actual text of the action here.);
requestParams.put("per_page", 1);
History.listForFile(parameters).all()
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", (Int64?) 1);
await History.ListForFile(path, parameters).All();
files_sdk.set_api_key("my-key")
files_sdk.history.list_for_file(path, {
"display": "Actual text of the action here.",
"per_page": 1
})
files_sdk.APIKey = "YOUR_API_KEY"
history.ListForFile(context.Background(), files_sdk.HistoryListForFileParams{
StartAt: "",
EndAt: "",
Display: "Actual text of the action here.",
Cursor: "",
PerPage: 1,
SortBy: "",
Path: "path",
})
files-cli histories list-for-file \
--start-at="" \
--end-at="" \
--display="Actual text of the action here." \
--cursor="" \
--per-page=1 \
--path="path" \
--api-key=YOUR_API_KEY
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 . |
path string Required | Path to operate on. |
Pagination Params
Read more about Paginating List Requests.
Available Fields for Sorting
Read more about Sorting List Requests
Parameter | Description |
---|---|
sort_by object | If set, sort records by the specified field in either asc or desc direction (e.g. sort_by[user_id]=desc ). Valid fields are user_id and created_at . |
List history for specific folder
Example Request
curl "https://app.files.com/api/rest/v1/history/folders/{path}" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/history/folders/{path}" \
-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<>();
requestParams.put("display", Actual text of the action here.);
requestParams.put("per_page", 1);
History.listForFolder(parameters).all()
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", (Int64?) 1);
await History.ListForFolder(path, parameters).All();
files_sdk.set_api_key("my-key")
files_sdk.history.list_for_folder(path, {
"display": "Actual text of the action here.",
"per_page": 1
})
files_sdk.APIKey = "YOUR_API_KEY"
history.ListForFolder(context.Background(), files_sdk.HistoryListForFolderParams{
StartAt: "",
EndAt: "",
Display: "Actual text of the action here.",
Cursor: "",
PerPage: 1,
SortBy: "",
Path: "path",
})
files-cli histories list-for-folder \
--start-at="" \
--end-at="" \
--display="Actual text of the action here." \
--cursor="" \
--per-page=1 \
--path="path" \
--api-key=YOUR_API_KEY
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 . |
path string Required | Path to operate on. |
Pagination Params
Read more about Paginating List Requests.
Available Fields for Sorting
Read more about Sorting List Requests
Parameter | Description |
---|---|
sort_by object | If set, sort records by the specified field in either asc or desc direction (e.g. sort_by[user_id]=desc ). Valid fields are user_id and created_at . |
List history for specific user
Example Request
curl "https://app.files.com/api/rest/v1/history/users/{user_id}.json" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/history/users/{user_id}.xml" \
-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<>();
requestParams.put("display", Actual text of the action here.);
requestParams.put("per_page", 1);
History.listForUser(parameters).all()
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", (Int64?) 1);
await History.ListForUser(user_id, parameters).All();
files_sdk.set_api_key("my-key")
files_sdk.history.list_for_user(user_id, {
"display": "Actual text of the action here.",
"per_page": 1
})
files_sdk.APIKey = "YOUR_API_KEY"
history.ListForUser(context.Background(), files_sdk.HistoryListForUserParams{
StartAt: "",
EndAt: "",
Display: "Actual text of the action here.",
Cursor: "",
PerPage: 1,
SortBy: "",
UserId: 1,
})
files-cli histories list-for-user \
--start-at="" \
--end-at="" \
--display="Actual text of the action here." \
--cursor="" \
--per-page=1 \
--user-id=1 \
--api-key=YOUR_API_KEY
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 . |
user_id int64 Required | User ID. |
Pagination Params
Read more about Paginating List Requests.
Available Fields for Sorting
Read more about Sorting List Requests
Parameter | Description |
---|---|
sort_by object | If set, sort records by the specified field in either asc or desc direction (e.g. sort_by[user_id]=desc ). Valid fields are user_id and created_at . |
List site login history
Example Request
curl "https://app.files.com/api/rest/v1/history/login.json" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/history/login.xml" \
-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<>();
requestParams.put("display", Actual text of the action here.);
requestParams.put("per_page", 1);
History.listLogins(parameters).all()
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", (Int64?) 1);
await History.ListLogins(parameters).All();
files_sdk.set_api_key("my-key")
files_sdk.history.list_logins({
"display": "Actual text of the action here.",
"per_page": 1
})
files_sdk.APIKey = "YOUR_API_KEY"
history.ListLogins(context.Background(), files_sdk.HistoryListLoginsParams{
StartAt: "",
EndAt: "",
Display: "Actual text of the action here.",
Cursor: "",
PerPage: 1,
SortBy: "",
})
files-cli histories list-logins \
--start-at="" \
--end-at="" \
--display="Actual text of the action here." \
--cursor="" \
--per-page=1 \
--api-key=YOUR_API_KEY
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 . |
Pagination Params
Read more about Paginating List Requests.
Available Fields for Sorting
Read more about Sorting List Requests
Parameter | Description |
---|---|
sort_by object | If set, sort records by the specified field in either asc or desc direction (e.g. sort_by[user_id]=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" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/history.xml" \
-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<>();
requestParams.put("display", Actual text of the action here.);
requestParams.put("per_page", 1);
History.list(parameters).all()
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", (Int64?) 1);
await History.List(parameters).All();
files_sdk.set_api_key("my-key")
files_sdk.history.list({
"display": "Actual text of the action here.",
"per_page": 1
})
files_sdk.APIKey = "YOUR_API_KEY"
history.List(context.Background(), files_sdk.HistoryListParams{
StartAt: "",
EndAt: "",
Display: "Actual text of the action here.",
Cursor: "",
PerPage: 1,
SortBy: "",
Filter: "",
FilterPrefix: "",
})
files-cli histories list \
--start-at="" \
--end-at="" \
--display="Actual text of the action here." \
--cursor="" \
--per-page=1 \
--api-key=YOUR_API_KEY
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 . |
Pagination Params
Read more about Paginating List Requests.
Available Fields for Sorting
Read more about Sorting List Requests
Parameter | Description |
---|---|
sort_by object | If set, sort records by the specified field in either asc or desc direction (e.g. sort_by[path]=desc ). Valid fields are path , folder , user_id or created_at . |
Available Filters
Read more about Filtering List Requests
Parameter | Description |
---|---|
filter object | If set, return records where the specified field is equal to the supplied value. Valid fields are user_id , folder or path . |
filter_prefix object | If set, return records where the specified field is prefixed by the supplied value. Valid fields are path . |
Action Notification Exports
The Action Notification Export API provides access to outgoing webhook logs. Querying webhook logs is a little different than other APIs.
All queries against the archive must be submitted as Exports. (Even our Web UI creates an Export behind the scenes.)
In any query field in this API, you may specify multiple values separated by commas. That means that commas cannot be searched for themselves, and neither can single quotation marks.
Use the following steps to complete an export:
- Initiate the export by using the Create Action Notification Export endpoint. Non Site Admins must query by folder or path.
- Using the
id
from the response to step 1, poll the Show Action Notification Export endpoint. Check thestatus
field until it isready
. - You can download the results of the export as a CSV file using the
results_url
field in the response from step 2. If you want to page through the records in JSON format, use the List Action Notification Export Results endpoint, passing theid
that you got in step 1 as theaction_notification_export_id
parameter. Check theX-Files-Cursor-Next
header to see if there are more records available, and resubmit the same request with acursor
parameter to fetch the next page of results. Unlike most API Endpoints, this endpoint does not provideX-Files-Cursor-Prev
cursors allowing reverse pagination through the results. This is due to limitations in Amazon Athena, the underlying data lake for these records.
If you intend to use this API for high volume or automated use, please contact us with more information about your use case.
Example Queries
- History for a folder:
{ "query_folder": "path/to/folder" }
- History for a range of time:
{ "start_at": "2021-03-18 12:00:00", "end_at": "2021-03-19 12:00:00" }
- History of all notifications that used GET or POST:
{ "query_request_method": "GET,POST" }
The ActionNotificationExport object
Example ActionNotificationExport Object
{
"id": 1,
"export_version": "example",
"start_at": "2000-01-01T01:00:00Z",
"end_at": "2000-01-01T01:00:00Z",
"status": "ready",
"query_path": "MyFile.txt",
"query_folder": "MyFolder",
"query_message": "Connection Refused",
"query_request_method": "GET",
"query_request_url": "http://example.com/webhook",
"query_status": "200",
"query_success": true,
"results_url": "https://files.com/action_notification_results.csv"
}
<?xml version="1.0" encoding="UTF-8"?>
<action-notification-export>
<id type="integer">1</id>
<export_version>example</export_version>
<start_at>2000-01-01T01:00:00Z</start_at>
<end_at>2000-01-01T01:00:00Z</end_at>
<status>ready</status>
<query_path>MyFile.txt</query_path>
<query_folder>MyFolder</query_folder>
<query_message>Connection Refused</query_message>
<query_request_method>GET</query_request_method>
<query_request_url>http://example.com/webhook</query_request_url>
<query_status>200</query_status>
<query_success type="boolean">true</query_success>
<results_url>https://files.com/action_notification_results.csv</results_url>
</action-notification-export>
Attribute | Description |
---|---|
id int64 | History Export ID |
export_version string | Version of the underlying records for the export. |
start_at date-time | Start date/time of export range. |
end_at date-time | End date/time of export range. |
status string | Status of export. Valid values: building , ready , or failed |
query_path string | Return notifications that were triggered by actions on this specific path. |
query_folder string | Return notifications that were triggered by actions in this folder. |
query_message string | Error message associated with the request, if any. |
query_request_method string | The HTTP request method used by the webhook. |
query_request_url string | The target webhook URL. |
query_status string | The HTTP status returned from the server in response to the webhook request. |
query_success boolean | true if the webhook request succeeded (i.e. returned a 200 or 204 response status). false otherwise. |
results_url string | If status is ready , this will be a URL where all the results can be downloaded at once as a CSV. |
user_id int64 | User ID. Provide a value of 0 to operate the current session's user. |
Show Action Notification Export
Example Request
curl https://app.files.com/api/rest/v1/action_notification_exports/{id}.json \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl https://app.files.com/api/rest/v1/action_notification_exports/{id}.xml \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::ActionNotificationExport.find(id)
\Files\Model\ActionNotificationExport::find($id);
ActionNotificationExport.find(, parameters
await ActionNotificationExport.find(id)
await ActionNotificationExport.Find(id);
files_sdk.set_api_key("my-key")
files_sdk.action_notification_export.find(id)
files_sdk.APIKey = "YOUR_API_KEY"
actionnotificationexport.Find(context.Background(), files_sdk.ActionNotificationExportFindParams{
Id: 1,
})
files-cli action-notification-exports find \
--id=1 \
--api-key=YOUR_API_KEY
Example Response
{
"id": 1,
"export_version": "example",
"start_at": "2000-01-01T01:00:00Z",
"end_at": "2000-01-01T01:00:00Z",
"status": "ready",
"query_path": "MyFile.txt",
"query_folder": "MyFolder",
"query_message": "Connection Refused",
"query_request_method": "GET",
"query_request_url": "http://example.com/webhook",
"query_status": "200",
"query_success": true,
"results_url": "https://files.com/action_notification_results.csv"
}
<?xml version="1.0" encoding="UTF-8"?>
<action-notification-export>
<id type="integer">1</id>
<export_version>example</export_version>
<start_at>2000-01-01T01:00:00Z</start_at>
<end_at>2000-01-01T01:00:00Z</end_at>
<status>ready</status>
<query_path>MyFile.txt</query_path>
<query_folder>MyFolder</query_folder>
<query_message>Connection Refused</query_message>
<query_request_method>GET</query_request_method>
<query_request_url>http://example.com/webhook</query_request_url>
<query_status>200</query_status>
<query_success type="boolean">true</query_success>
<results_url>https://files.com/action_notification_results.csv</results_url>
</action-notification-export>
HTTPS Request
GET /action_notification_exports/{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 | Action Notification Export ID. |
Create Action Notification Export
Example Request
curl https://app.files.com/api/rest/v1/action_notification_exports.json \
-X POST \
-H 'Content-Type: application/json' \
-d '{"user_id":1,"start_at":"2000-01-01T01:00:00Z","end_at":"2000-01-01T01:00:00Z","query_message":"Connection Refused","query_request_method":"GET","query_request_url":"http://example.com/webhook","query_status":"200","query_success":true,"query_path":"MyFile.txt","query_folder":"MyFolder"}' \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl https://app.files.com/api/rest/v1/action_notification_exports.xml \
-X POST \
-H 'Content-Type: application/xml' \
-d '<action-notification-export>
<user_id type="integer">1</user_id>
<start_at>2000-01-01T01:00:00Z</start_at>
<end_at>2000-01-01T01:00:00Z</end_at>
<query_message>Connection Refused</query_message>
<query_request_method>GET</query_request_method>
<query_request_url>http://example.com/webhook</query_request_url>
<query_status>200</query_status>
<query_success type="boolean">true</query_success>
<query_path>MyFile.txt</query_path>
<query_folder>MyFolder</query_folder>
</action-notification-export>'
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::ActionNotificationExport.create(
user_id: 1,
start_at: "2000-01-01T01:00:00Z",
end_at: "2000-01-01T01:00:00Z",
query_message: "Connection Refused",
query_request_method: "GET",
query_request_url: "http://example.com/webhook",
query_status: "200",
query_success: true,
query_path: "MyFile.txt",
query_folder: "MyFolder"
)
\Files\Model\ActionNotificationExport::create(array(
'user_id' => 1,
'start_at' => "2000-01-01T01:00:00Z",
'end_at' => "2000-01-01T01:00:00Z",
'query_message' => "Connection Refused",
'query_request_method' => "GET",
'query_request_url' => "http://example.com/webhook",
'query_status' => "200",
'query_success' => true,
'query_path' => "MyFile.txt",
'query_folder' => "MyFolder"
));
HashMap<Object, String> requestParams = new HashMap<>();
requestParams.put("user_id", 1);
requestParams.put("start_at", 2000-01-01T01:00:00Z);
requestParams.put("end_at", 2000-01-01T01:00:00Z);
requestParams.put("query_message", Connection Refused);
requestParams.put("query_request_method", GET);
requestParams.put("query_request_url", http://example.com/webhook);
requestParams.put("query_status", 200);
requestParams.put("query_success", true);
requestParams.put("query_path", MyFile.txt);
requestParams.put("query_folder", MyFolder);
ActionNotificationExport.create(parameters)
await ActionNotificationExport.create({
user_id: 1,
start_at: "2000-01-01T01:00:00Z",
end_at: "2000-01-01T01:00:00Z",
query_message: "Connection Refused",
query_request_method: "GET",
query_request_url: "http://example.com/webhook",
query_status: "200",
query_success: true,
query_path: "MyFile.txt",
query_folder: "MyFolder",
})
var parameters = new Dictionary<string, object>();
parameters.Add("user_id", (Int64?) 1);
parameters.Add("start_at", "2000-01-01T01:00:00Z");
parameters.Add("end_at", "2000-01-01T01:00:00Z");
parameters.Add("query_message", "Connection Refused");
parameters.Add("query_request_method", "GET");
parameters.Add("query_request_url", "http://example.com/webhook");
parameters.Add("query_status", "200");
parameters.Add("query_success", true);
parameters.Add("query_path", "MyFile.txt");
parameters.Add("query_folder", "MyFolder");
await ActionNotificationExport.Create(parameters);
files_sdk.set_api_key("my-key")
files_sdk.action_notification_export.create({
"user_id": 1,
"start_at": "2000-01-01T01:00:00Z",
"end_at": "2000-01-01T01:00:00Z",
"query_message": "Connection Refused",
"query_request_method": "GET",
"query_request_url": "http://example.com/webhook",
"query_status": "200",
"query_success": True,
"query_path": "MyFile.txt",
"query_folder": "MyFolder"
})
files_sdk.APIKey = "YOUR_API_KEY"
actionnotificationexport.Create(context.Background(), files_sdk.ActionNotificationExportCreateParams{
UserId: 1,
StartAt: "2000-01-01T01:00:00Z",
EndAt: "2000-01-01T01:00:00Z",
QueryMessage: "Connection Refused",
QueryRequestMethod: "GET",
QueryRequestUrl: "http://example.com/webhook",
QueryStatus: []string{"200"},
QuerySuccess: lib.Bool(true),
QueryPath: "MyFile.txt",
QueryFolder: "MyFolder",
})
files-cli action-notification-exports create \
--user-id=1 \
--start-at="2000-01-01T01:00:00Z" \
--end-at="2000-01-01T01:00:00Z" \
--query-message="Connection Refused" \
--query-request-method="GET" \
--query-request-url="http://example.com/webhook" \
--query-status="200" \
--query-path="MyFile.txt" \
--query-folder="MyFolder" \
--api-key=YOUR_API_KEY
Example Response
{
"id": 1,
"export_version": "example",
"start_at": "2000-01-01T01:00:00Z",
"end_at": "2000-01-01T01:00:00Z",
"status": "ready",
"query_path": "MyFile.txt",
"query_folder": "MyFolder",
"query_message": "Connection Refused",
"query_request_method": "GET",
"query_request_url": "http://example.com/webhook",
"query_status": "200",
"query_success": true,
"results_url": "https://files.com/action_notification_results.csv"
}
<?xml version="1.0" encoding="UTF-8"?>
<action-notification-export>
<id type="integer">1</id>
<export_version>example</export_version>
<start_at>2000-01-01T01:00:00Z</start_at>
<end_at>2000-01-01T01:00:00Z</end_at>
<status>ready</status>
<query_path>MyFile.txt</query_path>
<query_folder>MyFolder</query_folder>
<query_message>Connection Refused</query_message>
<query_request_method>GET</query_request_method>
<query_request_url>http://example.com/webhook</query_request_url>
<query_status>200</query_status>
<query_success type="boolean">true</query_success>
<results_url>https://files.com/action_notification_results.csv</results_url>
</action-notification-export>
HTTPS Request
POST /action_notification_exports
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 |
---|---|
user_id int64 | User ID. Provide a value of 0 to operate the current session's user. |
start_at string | Start date/time of export range. |
end_at string | End date/time of export range. |
query_message string | Error message associated with the request, if any. |
query_request_method string | The HTTP request method used by the webhook. |
query_request_url string | The target webhook URL. |
query_status string | The HTTP status returned from the server in response to the webhook request. |
query_success boolean | true if the webhook request succeeded (i.e. returned a 200 or 204 response status). false otherwise. |
query_path string | Return notifications that were triggered by actions on this specific path. |
query_folder string | Return notifications that were triggered by actions in this folder. |
Action Notification Export Results
The ActionNotificationExportResults resource in the REST API allows you to operate on ActionNotificationExportResults.
The ActionNotificationExportResult object
Example ActionNotificationExportResult Object
{
"id": 1,
"created_at": 1,
"status": 200,
"message": "Success",
"success": true,
"request_headers": "{\"User-Agent\":\"Files.com Webhook\"}",
"request_method": "GET",
"request_url": "www.example.com/webhook_receiver",
"path": "MyFolder/MyFile.txt",
"folder": "MyFolder"
}
<?xml version="1.0" encoding="UTF-8"?>
<action-notification-export-result>
<id type="integer">1</id>
<created_at type="integer">1</created_at>
<status type="integer">200</status>
<message>Success</message>
<success type="boolean">true</success>
<request_headers>{"User-Agent":"Files.com Webhook"}</request_headers>
<request_method>GET</request_method>
<request_url>www.example.com/webhook_receiver</request_url>
<path>MyFolder/MyFile.txt</path>
<folder>MyFolder</folder>
</action-notification-export-result>
Attribute | Description |
---|---|
id int64 | Notification ID |
created_at int64 | When the notification was sent. |
status int64 | HTTP status code returned in the webhook response. |
message string | A message indicating the overall status of the webhook notification. |
success boolean | true if the webhook succeeded by receiving a 200 or 204 response. |
request_headers string | A JSON-encoded string with headers that were sent with the webhook. |
request_method string | The HTTP verb used to perform the webhook. |
request_url string | The webhook request URL. |
path string | The path to the actual file that triggered this notification. This must be slash-delimited, but it must neither start nor end with a slash. Maximum of 5000 characters. |
folder string | The folder associated with the triggering action for this notification. |
List Action Notification Export Results
Example Request
curl "https://app.files.com/api/rest/v1/action_notification_export_results.json?user_id=1&action_notification_export_id=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/action_notification_export_results.xml?user_id=1&action_notification_export_id=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::ActionNotificationExportResult.list(
user_id: 1,
per_page: 1,
action_notification_export_id: 1
)
\Files\Model\ActionNotificationExportResult::list(array(
'user_id' => 1,
'per_page' => 1,
'action_notification_export_id' => 1
));
HashMap<Object, String> requestParams = new HashMap<>();
requestParams.put("user_id", 1);
requestParams.put("per_page", 1);
requestParams.put("action_notification_export_id", 1);
ActionNotificationExportResult.list(parameters).all()
await ActionNotificationExportResult.list({
user_id: 1,
per_page: 1,
action_notification_export_id: 1,
})
var parameters = new Dictionary<string, object>();
parameters.Add("user_id", (Int64?) 1);
parameters.Add("per_page", (Int64?) 1);
parameters.Add("action_notification_export_id", (Int64?) 1);
await ActionNotificationExportResult.List(parameters).All();
files_sdk.set_api_key("my-key")
files_sdk.action_notification_export_result.list({
"user_id": 1,
"per_page": 1,
"action_notification_export_id": 1
})
files_sdk.APIKey = "YOUR_API_KEY"
actionnotificationexportresult.List(context.Background(), files_sdk.ActionNotificationExportResultListParams{
UserId: 1,
Cursor: "",
PerPage: 1,
ActionNotificationExportId: 1,
})
files-cli action-notification-export-results list \
--user-id=1 \
--cursor="" \
--per-page=1 \
--action-notification-export-id=1 \
--api-key=YOUR_API_KEY
Example Response
[
{
"id": 1,
"created_at": 1,
"status": 200,
"message": "Success",
"success": true,
"request_headers": "{\"User-Agent\":\"Files.com Webhook\"}",
"request_method": "GET",
"request_url": "www.example.com/webhook_receiver",
"path": "MyFolder/MyFile.txt",
"folder": "MyFolder"
}
]
<?xml version="1.0" encoding="UTF-8"?>
<action-notification-export-results type="array">
<action-notification-export-result>
<id type="integer">1</id>
<created_at type="integer">1</created_at>
<status type="integer">200</status>
<message>Success</message>
<success type="boolean">true</success>
<request_headers>{"User-Agent":"Files.com Webhook"}</request_headers>
<request_method>GET</request_method>
<request_url>www.example.com/webhook_receiver</request_url>
<path>MyFolder/MyFile.txt</path>
<folder>MyFolder</folder>
</action-notification-export-result>
</action-notification-export-results>
HTTPS Request
GET /action_notification_export_results
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 |
---|---|
user_id int64 | User ID. Provide a value of 0 to operate the current session's user. |
action_notification_export_id int64 Required | ID of the associated action notification export. |
Pagination Params
Read more about Paginating List Requests.
Action Webhook Failures
The ActionWebhookFailures resource in the REST API allows you to operate on ActionWebhookFailures.
retry Action Webhook Failure
Example Request
curl https://app.files.com/api/rest/v1/action_webhook_failures/{id}/retry.json \
-X POST \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl https://app.files.com/api/rest/v1/action_webhook_failures/{id}/retry.xml \
-X POST \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
action_webhook_failure = Files::ActionWebhookFailure.new
action_webhook_failure.retry
$action_webhook_failure = new \Files\Model\ActionWebhookFailure();
$action_webhook_failure->retry();
HashMap<Object, String> attributes = new HashMap<>();
ActionWebhookFailure actionWebhookFailure = new ActionWebhookFailure(attributes);
actionWebhookFailure.retry();
const actionWebhookFailure = new ActionWebhookFailure()
await actionWebhookFailure.retry()
await actionWebhookFailure.Retry();
files_sdk.set_api_key("my-key")
action_webhook_failure = files_sdk.action_webhook_failure()
action_webhook_failure.retry()
files_sdk.APIKey = "YOUR_API_KEY"
actionwebhookfailure.Retry(context.Background(), files_sdk.ActionWebhookFailureRetryParams{
Id: 1,
})
files-cli action-webhook-failures retry \
--id=1 \
--api-key=YOUR_API_KEY
Example Response
No response.
No response.
HTTPS Request
POST /action_webhook_failures/{id}/retry
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 | Action Webhook Failure ID. |
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)",
"description": "example",
"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",
"url": "example",
"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>
<description>example</description>
<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>
<url>example</url>
<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. |
description string | User-supplied description of API 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 , mobile_app |
platform string | If this API key represents a Desktop app, what platform was it created on? |
url string | URL for API host. |
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" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/api_keys.xml?user_id=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<>();
requestParams.put("user_id", 1);
requestParams.put("per_page", 1);
ApiKey.list(parameters).all()
await ApiKey.list({
user_id: 1,
per_page: 1,
})
var parameters = new Dictionary<string, object>();
parameters.Add("user_id", (Int64?) 1);
parameters.Add("per_page", (Int64?) 1);
await ApiKey.List(parameters).All();
files_sdk.set_api_key("my-key")
files_sdk.api_key.list({
"user_id": 1,
"per_page": 1
})
files_sdk.APIKey = "YOUR_API_KEY"
apikey.List(context.Background(), files_sdk.ApiKeyListParams{
UserId: 1,
Cursor: "",
PerPage: 1,
SortBy: "",
Filter: "",
FilterGt: "",
FilterGteq: "",
FilterLt: "",
FilterLteq: "",
})
files-cli api-keys list \
--user-id=1 \
--cursor="" \
--per-page=1 \
--api-key=YOUR_API_KEY
Example Response
[
{
"id": 1,
"descriptive_label": "Site-wide API key for https://site.files.com/ (key ID #1)",
"description": "example",
"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",
"url": "example",
"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>
<description>example</description>
<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>
<url>example</url>
<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. |
Pagination Params
Read more about Paginating List Requests.
Available Fields for Sorting
Read more about Sorting List Requests
Parameter | Description |
---|---|
sort_by object | If set, sort records by the specified field in either asc or desc direction (e.g. sort_by[expires_at]=desc ). Valid fields are expires_at . |
Available Filters
Read more about Filtering List Requests
Parameter | Description |
---|---|
filter object | If set, return records where the specified field is equal to the supplied value. Valid fields are expires_at . |
filter_gt object | If set, return records where the specified field is greater than the supplied value. Valid fields are expires_at . |
filter_gteq object | If set, return records where the specified field is greater than or equal the supplied value. Valid fields are expires_at . |
filter_lt object | If set, return records where the specified field is less than the supplied value. Valid fields are expires_at . |
filter_lteq object | If set, return records where the specified field is less than or equal 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 \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl https://app.files.com/api/rest/v1/api_key.xml \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::ApiKey.find_current
\Files\Model\ApiKey::findCurrent();
ApiKey.findCurrent(, parameters
await ApiKey.findCurrent()
await ApiKey.FindCurrent();
files_sdk.set_api_key("my-key")
files_sdk.api_key.find_current()
files_sdk.APIKey = "YOUR_API_KEY"
apikey.FindCurrent
files-cli api-keys find-current \
--api-key=YOUR_API_KEY
Example Response
{
"id": 1,
"descriptive_label": "Site-wide API key for https://site.files.com/ (key ID #1)",
"description": "example",
"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",
"url": "example",
"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>
<description>example</description>
<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>
<url>example</url>
<user_id type="integer">1</user_id>
</api-key>
HTTPS Request
GET /api_key
Authentication Required
Available to all authenticated keys or sessions.
Show Api Key
Example Request
curl https://app.files.com/api/rest/v1/api_keys/{id}.json \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl https://app.files.com/api/rest/v1/api_keys/{id}.xml \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::ApiKey.find(id)
\Files\Model\ApiKey::find($id);
ApiKey.find(, parameters
await ApiKey.find(id)
await ApiKey.Find(id);
files_sdk.set_api_key("my-key")
files_sdk.api_key.find(id)
files_sdk.APIKey = "YOUR_API_KEY"
apikey.Find(context.Background(), files_sdk.ApiKeyFindParams{
Id: 1,
})
files-cli api-keys find \
--id=1 \
--api-key=YOUR_API_KEY
Example Response
{
"id": 1,
"descriptive_label": "Site-wide API key for https://site.files.com/ (key ID #1)",
"description": "example",
"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",
"url": "example",
"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>
<description>example</description>
<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>
<url>example</url>
<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","description":"example","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>
<description>example</description>
<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",
description: "example",
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",
'description' => "example",
'expires_at' => "2000-01-01T01:00:00Z",
'permission_set' => "full",
'path' => "shared/docs"
));
HashMap<Object, String> requestParams = new HashMap<>();
requestParams.put("user_id", 1);
requestParams.put("name", My Main API Key);
requestParams.put("description", example);
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",
description: "example",
expires_at: "2000-01-01T01:00:00Z",
permission_set: "full",
path: "shared/docs",
})
var parameters = new Dictionary<string, object>();
parameters.Add("user_id", (Int64?) 1);
parameters.Add("name", "My Main API Key");
parameters.Add("description", "example");
parameters.Add("expires_at", "2000-01-01T01:00:00Z");
parameters.Add("permission_set", "full");
parameters.Add("path", "shared/docs");
await ApiKey.Create(parameters);
files_sdk.set_api_key("my-key")
files_sdk.api_key.create({
"user_id": 1,
"name": "My Main API Key",
"description": "example",
"expires_at": "2000-01-01T01:00:00Z",
"permission_set": "full",
"path": "shared/docs"
})
files_sdk.APIKey = "YOUR_API_KEY"
apikey.Create(context.Background(), files_sdk.ApiKeyCreateParams{
UserId: 1,
Name: "My Main API Key",
Description: "example",
ExpiresAt: "2000-01-01T01:00:00Z",
PermissionSet: "full",
Path: "shared/docs",
})
files-cli api-keys create \
--user-id=1 \
--name="My Main API Key" \
--description="example" \
--expires-at="2000-01-01T01:00:00Z" \
--permission-set="full" \
--path="shared/docs" \
--api-key=YOUR_API_KEY
Example Response
{
"id": 1,
"descriptive_label": "Site-wide API key for https://site.files.com/ (key ID #1)",
"description": "example",
"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",
"url": "example",
"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>
<description>example</description>
<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>
<url>example</url>
<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. |
description string | User-supplied description of API key. |
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 , mobile_app |
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<>();
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");
await ApiKey.UpdateCurrent(parameters);
files_sdk.set_api_key("my-key")
files_sdk.api_key.update_current({
"expires_at": "2000-01-01T01:00:00Z",
"name": "My Main API Key",
"permission_set": "full"
})
files_sdk.APIKey = "YOUR_API_KEY"
apikey.UpdateCurrent(context.Background(), files_sdk.ApiKeyUpdateCurrentParams{
ExpiresAt: "2000-01-01T01:00:00Z",
Name: "My Main API Key",
PermissionSet: "full",
})
files-cli api-keys update-current \
--expires-at="2000-01-01T01:00:00Z" \
--name="My Main API Key" \
--permission-set="full" \
--api-key=YOUR_API_KEY
Example Response
{
"id": 1,
"descriptive_label": "Site-wide API key for https://site.files.com/ (key ID #1)",
"description": "example",
"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",
"url": "example",
"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>
<description>example</description>
<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>
<url>example</url>
<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 , mobile_app |
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","description":"example","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>
<description>example</description>
<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.first
api_key.update(
name: "My Main API Key",
description: "example",
expires_at: "2000-01-01T01:00:00Z",
permission_set: "full"
)
$api_key = \Files\Model\ApiKey::list()[0];
$api_key->update(array(
'name' => "My Main API Key",
'description' => "example",
'expires_at' => "2000-01-01T01:00:00Z",
'permission_set' => "full"
));
ApiKey apiKey = ApiKey.list()[0];
apiKey.setName("My Main API Key");
apiKey.setDescription("example");
apiKey.setExpiresAt("2000-01-01T01:00:00Z");
apiKey.setPermissionSet("full");
apiKey.update();
const apiKey = (await ApiKey.list())[0]
await apiKey.update({
name: "My Main API Key",
description: "example",
expires_at: "2000-01-01T01:00:00Z",
permission_set: "full",
})
var apiKey = (await ApiKey.List())[0];
var parameters = new Dictionary<string, object>();
parameters.Add("name", "My Main API Key");
parameters.Add("description", "example");
parameters.Add("expires_at", "2000-01-01T01:00:00Z");
parameters.Add("permission_set", "full");
await apiKey.Update(parameters);
files_sdk.set_api_key("my-key")
api_key = files_sdk.api_key.find(id)
api_key.update({
"name": "My Main API Key",
"description": "example",
"expires_at": "2000-01-01T01:00:00Z",
"permission_set": "full"
})
files_sdk.APIKey = "YOUR_API_KEY"
apikey.Update(context.Background(), files_sdk.ApiKeyUpdateParams{
Id: 1,
Name: "My Main API Key",
Description: "example",
ExpiresAt: "2000-01-01T01:00:00Z",
PermissionSet: "full",
})
files-cli api-keys update \
--id=1 \
--name="My Main API Key" \
--description="example" \
--expires-at="2000-01-01T01:00:00Z" \
--permission-set="full" \
--api-key=YOUR_API_KEY
Example Response
{
"id": 1,
"descriptive_label": "Site-wide API key for https://site.files.com/ (key ID #1)",
"description": "example",
"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",
"url": "example",
"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>
<description>example</description>
<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>
<url>example</url>
<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. |
description string | User-supplied description of API key. |
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 , mobile_app |
Delete current API key. (Requires current API connection to be using an API key.)
Example Request
curl https://app.files.com/api/rest/v1/api_key.json \
-X DELETE \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl https://app.files.com/api/rest/v1/api_key.xml \
-X DELETE \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::ApiKey.delete_current
\Files\Model\ApiKey::deleteCurrent();
ApiKey.deleteCurrent(, parameters
await ApiKey.deleteCurrent()
await ApiKey.DeleteCurrent();
files_sdk.set_api_key("my-key")
files_sdk.api_key.delete_current()
files_sdk.APIKey = "YOUR_API_KEY"
apikey.DeleteCurrent
files-cli api-keys delete-current \
--api-key=YOUR_API_KEY
Example Response
No response.
No response.
HTTPS Request
DELETE /api_key
Authentication Required
Available to all authenticated keys or sessions.
Delete Api Key
Example Request
curl https://app.files.com/api/rest/v1/api_keys/{id}.json \
-X DELETE \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl https://app.files.com/api/rest/v1/api_keys/{id}.xml \
-X DELETE \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
api_key = Files::ApiKey.list.first
api_key.delete
$api_key = \Files\Model\ApiKey::list()[0];
$api_key->delete();
ApiKey apiKey = ApiKey.list()[0];
apiKey.delete();
const apiKey = (await ApiKey.list())[0]
await apiKey.delete()
var apiKey = (await ApiKey.List())[0];
await apiKey.Delete();
files_sdk.set_api_key("my-key")
api_key = files_sdk.api_key.find(id)
api_key.delete()
files_sdk.APIKey = "YOUR_API_KEY"
apikey.Delete(context.Background(), files_sdk.ApiKeyDeleteParams{
Id: 1,
})
files-cli api-keys delete \
--id=1 \
--api-key=YOUR_API_KEY
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
{
"app_type": "example",
"documentation_links": {
"Important Info": "http://files.test/learn-more"
},
"extended_description": "example",
"extended_description_for_marketing_site": "example",
"external_homepage_url": "example",
"featured": true,
"folder_behavior_type": "example",
"icon_url": "example",
"logo_thumbnail_url": "example",
"logo_url": "example",
"marketing_intro": "example",
"marketing_youtube_url": "example",
"name": "example",
"package_manager_install_command": "example",
"remote_server_type": "example",
"screenshot_list_urls": [
"example"
],
"sdk_installation_instructions_link": "example",
"short_description": "example",
"sso_strategy_type": "example",
"tutorial_youtube_url": "example"
}
<?xml version="1.0" encoding="UTF-8"?>
<app>
<app_type>example</app_type>
<documentation_links>
<Important Info>http://files.test/learn-more</Important Info>
</documentation_links>
<extended_description>example</extended_description>
<extended_description_for_marketing_site>example</extended_description_for_marketing_site>
<external_homepage_url>example</external_homepage_url>
<featured type="boolean">true</featured>
<folder_behavior_type>example</folder_behavior_type>
<icon_url>example</icon_url>
<logo_thumbnail_url>example</logo_thumbnail_url>
<logo_url>example</logo_url>
<marketing_intro>example</marketing_intro>
<marketing_youtube_url>example</marketing_youtube_url>
<name>example</name>
<package_manager_install_command>example</package_manager_install_command>
<remote_server_type>example</remote_server_type>
<screenshot_list_urls type="array">
<screenshot_list_url>example</screenshot_list_url>
</screenshot_list_urls>
<sdk_installation_instructions_link>example</sdk_installation_instructions_link>
<short_description>example</short_description>
<sso_strategy_type>example</sso_strategy_type>
<tutorial_youtube_url>example</tutorial_youtube_url>
</app>
Attribute | Description |
---|---|
app_type string | The type of the App Possible values: sdk , sso , remote_server , folder_behavior , client_app , app_integration |
documentation_links object | Collection of named links to documentation |
extended_description string | Long description for the in-App landing page |
extended_description_for_marketing_site string | Long form description of the App |
external_homepage_url string | Link to external homepage |
featured boolean | Is featured on the App listing? |
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 , auto_decrypt , override_upload_filename , permission_fence |
icon_url string | App icon |
logo_thumbnail_url string | Logo thumbnail for the App |
logo_url string | Full size logo for the App |
marketing_intro string | Marketing introdution of the App |
marketing_youtube_url string | Marketing video page |
name string | Name of the App |
package_manager_install_command string | Package manager install command |
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 , sharepoint , s3_compatible , azure_files , files_agent , filebase , cloudflare , linode |
screenshot_list_urls array | Screenshots of the App |
sdk_installation_instructions_link string | Link to SDK installation instructions |
short_description string | Short description of the App |
sso_strategy_type string | Associated SSO Strategy type, if any Possible values: google , auth0 , okta , atlassian , azure , box , dropbox , slack , onelogin , saml , idaptive , ldap , scim |
tutorial_youtube_url string | Tutorial video page |
List Apps
Example Request
curl "https://app.files.com/api/rest/v1/apps.json" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/apps.xml" \
-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<>();
requestParams.put("per_page", 1);
App.list(parameters).all()
await App.list({
per_page: 1,
})
var parameters = new Dictionary<string, object>();
parameters.Add("per_page", (Int64?) 1);
await App.List(parameters).All();
files_sdk.set_api_key("my-key")
files_sdk.app.list({
"per_page": 1
})
files_sdk.APIKey = "YOUR_API_KEY"
app.List(context.Background(), files_sdk.AppListParams{
Cursor: "",
PerPage: 1,
SortBy: "",
Filter: "",
FilterPrefix: "",
})
files-cli apps list \
--cursor="" \
--per-page=1 \
--api-key=YOUR_API_KEY
Example Response
[
{
"app_type": "example",
"documentation_links": {
"Important Info": "http://files.test/learn-more"
},
"extended_description": "example",
"extended_description_for_marketing_site": "example",
"external_homepage_url": "example",
"featured": true,
"folder_behavior_type": "example",
"icon_url": "example",
"logo_thumbnail_url": "example",
"logo_url": "example",
"marketing_intro": "example",
"marketing_youtube_url": "example",
"name": "example",
"package_manager_install_command": "example",
"remote_server_type": "example",
"screenshot_list_urls": [
"example"
],
"sdk_installation_instructions_link": "example",
"short_description": "example",
"sso_strategy_type": "example",
"tutorial_youtube_url": "example"
}
]
<?xml version="1.0" encoding="UTF-8"?>
<apps type="array">
<app>
<app_type>example</app_type>
<documentation_links>
<Important Info>http://files.test/learn-more</Important Info>
</documentation_links>
<extended_description>example</extended_description>
<extended_description_for_marketing_site>example</extended_description_for_marketing_site>
<external_homepage_url>example</external_homepage_url>
<featured type="boolean">true</featured>
<folder_behavior_type>example</folder_behavior_type>
<icon_url>example</icon_url>
<logo_thumbnail_url>example</logo_thumbnail_url>
<logo_url>example</logo_url>
<marketing_intro>example</marketing_intro>
<marketing_youtube_url>example</marketing_youtube_url>
<name>example</name>
<package_manager_install_command>example</package_manager_install_command>
<remote_server_type>example</remote_server_type>
<screenshot_list_urls type="array">
<screenshot_list_url>example</screenshot_list_url>
</screenshot_list_urls>
<sdk_installation_instructions_link>example</sdk_installation_instructions_link>
<short_description>example</short_description>
<sso_strategy_type>example</sso_strategy_type>
<tutorial_youtube_url>example</tutorial_youtube_url>
</app>
</apps>
HTTPS Request
GET /apps
Authentication Required
No authentication required; you may call this endpoint without a key or session.
Request Parameters
No request parameters available for this endpoint.
Pagination Params
Read more about Paginating List Requests.
Available Fields for Sorting
Read more about Sorting List Requests
Parameter | Description |
---|---|
sort_by object | If set, sort records by the specified field in either asc or desc direction (e.g. sort_by[name]=desc ). Valid fields are name and app_type . |
Available Filters
Read more about Filtering List Requests
Parameter | Description |
---|---|
filter object | If set, return records where the specified field is equal to the supplied value. Valid fields are name and app_type . Valid field combinations are [ name, app_type ] and [ app_type, name ] . |
filter_prefix object | If set, return records where the specified field is prefixed by the supplied value. Valid fields are name . |
As2 Incoming Messages
An As2 Incoming Message is created for each individual AS2 file transfer incoming from a Partner. It contains the message details and tracks the lifecycle status with milestones of the transfer.
The As2IncomingMessage object
Example As2IncomingMessage Object
{
"id": 1,
"as2_partner_id": 1,
"as2_station_id": 1,
"uuid": "example",
"content_type": "example",
"http_headers": {
"key": "example value"
},
"activity_log": "example",
"processing_result": "example",
"processing_result_description": "example",
"mic": "example",
"mic_algo": "example",
"as2_to": "example",
"as2_from": "example",
"message_id": "example",
"subject": "example",
"date": "example",
"body_size": "example",
"attachment_filename": "example",
"ip": "example",
"created_at": "2000-01-01T01:00:00Z",
"http_response_code": "example",
"http_response_headers": {
"key": "example value"
},
"recipient_serial": "example",
"hex_recipient_serial": "A5:EB:C1:95:DC:D8:2B:E7",
"recipient_issuer": "example",
"message_received": true,
"message_decrypted": true,
"message_signature_verified": true,
"message_processing_success": true,
"message_mdn_returned": true,
"encrypted_uri": "example",
"smime_signed_uri": "example",
"smime_uri": "example",
"raw_uri": "example",
"mdn_response_uri": "example"
}
<?xml version="1.0" encoding="UTF-8"?>
<as2-incoming-message>
<id type="integer">1</id>
<as2_partner_id type="integer">1</as2_partner_id>
<as2_station_id type="integer">1</as2_station_id>
<uuid>example</uuid>
<content_type>example</content_type>
<http_headers>
<key>example value</key>
</http_headers>
<activity_log>example</activity_log>
<processing_result>example</processing_result>
<processing_result_description>example</processing_result_description>
<mic>example</mic>
<mic_algo>example</mic_algo>
<as2_to>example</as2_to>
<as2_from>example</as2_from>
<message_id>example</message_id>
<subject>example</subject>
<date>example</date>
<body_size>example</body_size>
<attachment_filename>example</attachment_filename>
<ip>example</ip>
<created_at>2000-01-01T01:00:00Z</created_at>
<http_response_code>example</http_response_code>
<http_response_headers>
<key>example value</key>
</http_response_headers>
<recipient_serial>example</recipient_serial>
<hex_recipient_serial>A5:EB:C1:95:DC:D8:2B:E7</hex_recipient_serial>
<recipient_issuer>example</recipient_issuer>
<message_received type="boolean">true</message_received>
<message_decrypted type="boolean">true</message_decrypted>
<message_signature_verified type="boolean">true</message_signature_verified>
<message_processing_success type="boolean">true</message_processing_success>
<message_mdn_returned type="boolean">true</message_mdn_returned>
<encrypted_uri>example</encrypted_uri>
<smime_signed_uri>example</smime_signed_uri>
<smime_uri>example</smime_uri>
<raw_uri>example</raw_uri>
<mdn_response_uri>example</mdn_response_uri>
</as2-incoming-message>
Attribute | Description |
---|---|
id int64 | Id of the AS2 Partner. |
as2_partner_id int64 | Id of the AS2 Partner associated with this message. |
as2_station_id int64 | Id of the AS2 Station associated with this message. |
uuid string | UUID assigned to this message. |
content_type string | Content Type header of the incoming message. |
http_headers object | HTTP Headers sent with this message. |
activity_log string | JSON Structure of the activity log. |
processing_result string | Result of processing. Possible values: not_started , unable_to_find_station , unable_to_find_partner , unable_to_validate_signature , decrypt_fail , file_save_fail , success |
processing_result_description string | Result of processing description. |
mic string | AS2 Message Integrity Check |
mic_algo string | AS2 Message Integrity Check Algorithm Used |
as2_to string | AS2 TO header of message |
as2_from string | AS2 FROM header of message |
message_id string | AS2 Message Id |
subject string | AS2 Subject Header |
date string | Date Header |
body_size string | Encrypted Payload Body Size |
attachment_filename string | Filename of the file being received. |
ip string | IP Address of the Sender |
created_at date-time | Message creation date/time |
http_response_code string | HTTP Response Code sent for this message |
http_response_headers object | HTTP Headers sent for this message. |
recipient_serial string | Incoming Message Recipient(the Client Cert used to encrypt this message)'s serial |
hex_recipient_serial string | Incoming Message Recipient(the Client Cert used to encrypt this message)'s serial in hex format. |
recipient_issuer string | Incoming Message Recipient(the Client Cert used to encrypt this message)'s issuer |
message_received boolean | Message body received? |
message_decrypted boolean | Message decrypted successfully? |
message_signature_verified boolean | Message signature verified? |
message_processing_success boolean | Message processed successfully? |
message_mdn_returned boolean | MDN returned? |
encrypted_uri string | URL to download the encrypted signed smime that is to sent as AS2 body |
smime_signed_uri string | URL to download the file contents as smime with signature |
smime_uri string | URL to download the file contents encoded as smime |
raw_uri string | URL to download the original file contents |
mdn_response_uri string | URL to download the http response body |
List As2 Incoming Messages
Example Request
curl "https://app.files.com/api/rest/v1/as2_incoming_messages.json?as2_partner_id=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/as2_incoming_messages.xml?as2_partner_id=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::As2IncomingMessage.list(
per_page: 1,
as2_partner_id: 1
)
\Files\Model\As2IncomingMessage::list(array(
'per_page' => 1,
'as2_partner_id' => 1
));
HashMap<Object, String> requestParams = new HashMap<>();
requestParams.put("per_page", 1);
requestParams.put("as2_partner_id", 1);
As2IncomingMessage.list(parameters).all()
await As2IncomingMessage.list({
per_page: 1,
as2_partner_id: 1,
})
var parameters = new Dictionary<string, object>();
parameters.Add("per_page", (Int64?) 1);
parameters.Add("as2_partner_id", (Int64?) 1);
await As2IncomingMessage.List(parameters).All();
files_sdk.set_api_key("my-key")
files_sdk.as2_incoming_message.list({
"per_page": 1,
"as2_partner_id": 1
})
files_sdk.APIKey = "YOUR_API_KEY"
as2incomingmessage.List(context.Background(), files_sdk.As2IncomingMessageListParams{
Cursor: "",
PerPage: 1,
SortBy: "",
Filter: "",
FilterGt: "",
FilterGteq: "",
FilterLt: "",
FilterLteq: "",
As2PartnerId: 1,
})
files-cli as2-incoming-messages list \
--cursor="" \
--per-page=1 \
--as2-partner-id=1 \
--api-key=YOUR_API_KEY
Example Response
[
{
"id": 1,
"as2_partner_id": 1,
"as2_station_id": 1,
"uuid": "example",
"content_type": "example",
"http_headers": {
"key": "example value"
},
"activity_log": "example",
"processing_result": "example",
"processing_result_description": "example",
"mic": "example",
"mic_algo": "example",
"as2_to": "example",
"as2_from": "example",
"message_id": "example",
"subject": "example",
"date": "example",
"body_size": "example",
"attachment_filename": "example",
"ip": "example",
"created_at": "2000-01-01T01:00:00Z",
"http_response_code": "example",
"http_response_headers": {
"key": "example value"
},
"recipient_serial": "example",
"hex_recipient_serial": "A5:EB:C1:95:DC:D8:2B:E7",
"recipient_issuer": "example",
"message_received": true,
"message_decrypted": true,
"message_signature_verified": true,
"message_processing_success": true,
"message_mdn_returned": true,
"encrypted_uri": "example",
"smime_signed_uri": "example",
"smime_uri": "example",
"raw_uri": "example",
"mdn_response_uri": "example"
}
]
<?xml version="1.0" encoding="UTF-8"?>
<as2-incoming-messages type="array">
<as2-incoming-message>
<id type="integer">1</id>
<as2_partner_id type="integer">1</as2_partner_id>
<as2_station_id type="integer">1</as2_station_id>
<uuid>example</uuid>
<content_type>example</content_type>
<http_headers>
<key>example value</key>
</http_headers>
<activity_log>example</activity_log>
<processing_result>example</processing_result>
<processing_result_description>example</processing_result_description>
<mic>example</mic>
<mic_algo>example</mic_algo>
<as2_to>example</as2_to>
<as2_from>example</as2_from>
<message_id>example</message_id>
<subject>example</subject>
<date>example</date>
<body_size>example</body_size>
<attachment_filename>example</attachment_filename>
<ip>example</ip>
<created_at>2000-01-01T01:00:00Z</created_at>
<http_response_code>example</http_response_code>
<http_response_headers>
<key>example value</key>
</http_response_headers>
<recipient_serial>example</recipient_serial>
<hex_recipient_serial>A5:EB:C1:95:DC:D8:2B:E7</hex_recipient_serial>
<recipient_issuer>example</recipient_issuer>
<message_received type="boolean">true</message_received>
<message_decrypted type="boolean">true</message_decrypted>
<message_signature_verified type="boolean">true</message_signature_verified>
<message_processing_success type="boolean">true</message_processing_success>
<message_mdn_returned type="boolean">true</message_mdn_returned>
<encrypted_uri>example</encrypted_uri>
<smime_signed_uri>example</smime_signed_uri>
<smime_uri>example</smime_uri>
<raw_uri>example</raw_uri>
<mdn_response_uri>example</mdn_response_uri>
</as2-incoming-message>
</as2-incoming-messages>
HTTPS Request
GET /as2_incoming_messages
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 |
---|---|
as2_partner_id int64 | As2 Partner ID. If provided, will return message specific to that partner. |
Pagination Params
Read more about Paginating List Requests.
Available Fields for Sorting
Read more about Sorting List Requests
Parameter | Description |
---|---|
sort_by object | If set, sort records by the specified field in either asc or desc direction (e.g. sort_by[created_at]=desc ). Valid fields are created_at and as2_partner_id . |
Available Filters
Read more about Filtering List Requests
Parameter | Description |
---|---|
filter object | If set, return records where the specified field is equal to the supplied value. Valid fields are created_at . |
filter_gt object | If set, return records where the specified field is greater than the supplied value. Valid fields are created_at . |
filter_gteq object | If set, return records where the specified field is greater than or equal the supplied value. Valid fields are created_at . |
filter_lt object | If set, return records where the specified field is less than the supplied value. Valid fields are created_at . |
filter_lteq object | If set, return records where the specified field is less than or equal the supplied value. Valid fields are created_at . |
As2 Outgoing Messages
An As2 Outgoing Message is created for each individual AS2 file transfer out to a Partner. It contains the message details and tracks the lifecycle status with milestones of the transfer.
The As2OutgoingMessage object
Example As2OutgoingMessage Object
{
"id": 1,
"as2_partner_id": 1,
"as2_station_id": 1,
"uuid": "example",
"http_headers": {
"key": "example value"
},
"activity_log": "example",
"processing_result": "example",
"processing_result_description": "example",
"mic": "example",
"mic_sha_256": "example",
"as2_to": "example",
"as2_from": "example",
"date": "example",
"message_id": "example",
"body_size": "example",
"attachment_filename": "example",
"created_at": "2000-01-01T01:00:00Z",
"http_response_code": "example",
"http_response_headers": {
"key": "example value"
},
"http_transmission_duration": 1.0,
"mdn_received": true,
"mdn_valid": true,
"mdn_signature_verified": true,
"mdn_message_id_matched": true,
"mdn_mic_matched": true,
"mdn_processing_success": true,
"raw_uri": "example",
"smime_uri": "example",
"smime_signed_uri": "example",
"encrypted_uri": "example",
"mdn_response_uri": "example"
}
<?xml version="1.0" encoding="UTF-8"?>
<as2-outgoing-message>
<id type="integer">1</id>
<as2_partner_id type="integer">1</as2_partner_id>
<as2_station_id type="integer">1</as2_station_id>
<uuid>example</uuid>
<http_headers>
<key>example value</key>
</http_headers>
<activity_log>example</activity_log>
<processing_result>example</processing_result>
<processing_result_description>example</processing_result_description>
<mic>example</mic>
<mic_sha_256>example</mic_sha_256>
<as2_to>example</as2_to>
<as2_from>example</as2_from>
<date>example</date>
<message_id>example</message_id>
<body_size>example</body_size>
<attachment_filename>example</attachment_filename>
<created_at>2000-01-01T01:00:00Z</created_at>
<http_response_code>example</http_response_code>
<http_response_headers>
<key>example value</key>
</http_response_headers>
<http_transmission_duration type="float">1.0</http_transmission_duration>
<mdn_received type="boolean">true</mdn_received>
<mdn_valid type="boolean">true</mdn_valid>
<mdn_signature_verified type="boolean">true</mdn_signature_verified>
<mdn_message_id_matched type="boolean">true</mdn_message_id_matched>
<mdn_mic_matched type="boolean">true</mdn_mic_matched>
<mdn_processing_success type="boolean">true</mdn_processing_success>
<raw_uri>example</raw_uri>
<smime_uri>example</smime_uri>
<smime_signed_uri>example</smime_signed_uri>
<encrypted_uri>example</encrypted_uri>
<mdn_response_uri>example</mdn_response_uri>
</as2-outgoing-message>
Attribute | Description |
---|---|
id int64 | Id of the AS2 Partner. |
as2_partner_id int64 | Id of the AS2 Partner associated with this message. |
as2_station_id int64 | Id of the AS2 Station associated with this message. |
uuid string | UUID assigned to this message. |
http_headers object | HTTP Headers sent with this message. |
activity_log string | JSON Structure of the activity log. |
processing_result string | Result of processing. Possible values: not_started , send_failed , send_success , send_success_mdn_invalid , send_success_mic_mismatch , send_success_message_id_mismatch , send_success_signature_mismatch , send_success_processing_failure , send_failed_unknown_host , send_failed_bad_http_response_code , send_failed_ssl_error , send_failed_connection_refused |
processing_result_description string | Result of processing description. |
mic string | AS2 Message Integrity Check SHA1 |
mic_sha_256 string | AS2 Message Integrity Check SHA256 |
as2_to string | AS2 TO |
as2_from string | AS2 FROM |
date string | Date Header |
message_id string | AS2 Message Id |
body_size string | Encrypted Payload Body Size |
attachment_filename string | Filename of the file being sent. |
created_at date-time | Message creation date/time |
http_response_code string | HTTP Response Code received for this message |
http_response_headers object | HTTP Headers received for this message. |
http_transmission_duration double | HTTP transmission duration in seceonds |
mdn_received boolean | Did the partner give a response body? |
mdn_valid boolean | Is the response in MDN format? |
mdn_signature_verified boolean | MDN signature verified? |
mdn_message_id_matched boolean | MDN message id matched? |
mdn_mic_matched boolean | MDN MIC matched? |
mdn_processing_success boolean | MDN disposition indicate a successful processing? |
raw_uri string | URL to download the original file contents |
smime_uri string | URL to download the file contents encoded as smime |
smime_signed_uri string | URL to download the file contents as smime with signature |
encrypted_uri string | URL to download the encrypted signed smime that is to sent as AS2 body |
mdn_response_uri string | URL to download the http response body |
List As2 Outgoing Messages
Example Request
curl "https://app.files.com/api/rest/v1/as2_outgoing_messages.json?as2_partner_id=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/as2_outgoing_messages.xml?as2_partner_id=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::As2OutgoingMessage.list(
per_page: 1,
as2_partner_id: 1
)
\Files\Model\As2OutgoingMessage::list(array(
'per_page' => 1,
'as2_partner_id' => 1
));
HashMap<Object, String> requestParams = new HashMap<>();
requestParams.put("per_page", 1);
requestParams.put("as2_partner_id", 1);
As2OutgoingMessage.list(parameters).all()
await As2OutgoingMessage.list({
per_page: 1,
as2_partner_id: 1,
})
var parameters = new Dictionary<string, object>();
parameters.Add("per_page", (Int64?) 1);
parameters.Add("as2_partner_id", (Int64?) 1);
await As2OutgoingMessage.List(parameters).All();
files_sdk.set_api_key("my-key")
files_sdk.as2_outgoing_message.list({
"per_page": 1,
"as2_partner_id": 1
})
files_sdk.APIKey = "YOUR_API_KEY"
as2outgoingmessage.List(context.Background(), files_sdk.As2OutgoingMessageListParams{
Cursor: "",
PerPage: 1,
SortBy: "",
Filter: "",
FilterGt: "",
FilterGteq: "",
FilterLt: "",
FilterLteq: "",
As2PartnerId: 1,
})
files-cli as2-outgoing-messages list \
--cursor="" \
--per-page=1 \
--as2-partner-id=1 \
--api-key=YOUR_API_KEY
Example Response
[
{
"id": 1,
"as2_partner_id": 1,
"as2_station_id": 1,
"uuid": "example",
"http_headers": {
"key": "example value"
},
"activity_log": "example",
"processing_result": "example",
"processing_result_description": "example",
"mic": "example",
"mic_sha_256": "example",
"as2_to": "example",
"as2_from": "example",
"date": "example",
"message_id": "example",
"body_size": "example",
"attachment_filename": "example",
"created_at": "2000-01-01T01:00:00Z",
"http_response_code": "example",
"http_response_headers": {
"key": "example value"
},
"http_transmission_duration": 1.0,
"mdn_received": true,
"mdn_valid": true,
"mdn_signature_verified": true,
"mdn_message_id_matched": true,
"mdn_mic_matched": true,
"mdn_processing_success": true,
"raw_uri": "example",
"smime_uri": "example",
"smime_signed_uri": "example",
"encrypted_uri": "example",
"mdn_response_uri": "example"
}
]
<?xml version="1.0" encoding="UTF-8"?>
<as2-outgoing-messages type="array">
<as2-outgoing-message>
<id type="integer">1</id>
<as2_partner_id type="integer">1</as2_partner_id>
<as2_station_id type="integer">1</as2_station_id>
<uuid>example</uuid>
<http_headers>
<key>example value</key>
</http_headers>
<activity_log>example</activity_log>
<processing_result>example</processing_result>
<processing_result_description>example</processing_result_description>
<mic>example</mic>
<mic_sha_256>example</mic_sha_256>
<as2_to>example</as2_to>
<as2_from>example</as2_from>
<date>example</date>
<message_id>example</message_id>
<body_size>example</body_size>
<attachment_filename>example</attachment_filename>
<created_at>2000-01-01T01:00:00Z</created_at>
<http_response_code>example</http_response_code>
<http_response_headers>
<key>example value</key>
</http_response_headers>
<http_transmission_duration type="float">1.0</http_transmission_duration>
<mdn_received type="boolean">true</mdn_received>
<mdn_valid type="boolean">true</mdn_valid>
<mdn_signature_verified type="boolean">true</mdn_signature_verified>
<mdn_message_id_matched type="boolean">true</mdn_message_id_matched>
<mdn_mic_matched type="boolean">true</mdn_mic_matched>
<mdn_processing_success type="boolean">true</mdn_processing_success>
<raw_uri>example</raw_uri>
<smime_uri>example</smime_uri>
<smime_signed_uri>example</smime_signed_uri>
<encrypted_uri>example</encrypted_uri>
<mdn_response_uri>example</mdn_response_uri>
</as2-outgoing-message>
</as2-outgoing-messages>
HTTPS Request
GET /as2_outgoing_messages
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 |
---|---|
as2_partner_id int64 | As2 Partner ID. If provided, will return message specific to that partner. |
Pagination Params
Read more about Paginating List Requests.
Available Fields for Sorting
Read more about Sorting List Requests
Parameter | Description |
---|---|
sort_by object | If set, sort records by the specified field in either asc or desc direction (e.g. sort_by[created_at]=desc ). Valid fields are created_at and as2_partner_id . |
Available Filters
Read more about Filtering List Requests
Parameter | Description |
---|---|
filter object | If set, return records where the specified field is equal to the supplied value. Valid fields are created_at . |
filter_gt object | If set, return records where the specified field is greater than the supplied value. Valid fields are created_at . |
filter_gteq object | If set, return records where the specified field is greater than or equal the supplied value. Valid fields are created_at . |
filter_lt object | If set, return records where the specified field is less than the supplied value. Valid fields are created_at . |
filter_lteq object | If set, return records where the specified field is less than or equal the supplied value. Valid fields are created_at . |
As2 Partners
As2 Partner defines a Files.com hosted AS2 server that can receive data into Files.com and send data from Files.com
The As2Partner object
Example As2Partner Object
{
"id": 1,
"as2_station_id": 1,
"name": "AS2 Partner Name",
"uri": "example",
"server_certificate": "require_match",
"enable_dedicated_ips": true,
"hex_public_certificate_serial": "A5:EB:C1:95:DC:D8:2B:E7",
"public_certificate_md5": "example",
"public_certificate_subject": "example",
"public_certificate_issuer": "example",
"public_certificate_serial": "example",
"public_certificate_not_before": "example",
"public_certificate_not_after": "example"
}
<?xml version="1.0" encoding="UTF-8"?>
<as2-partner>
<id type="integer">1</id>
<as2_station_id type="integer">1</as2_station_id>
<name>AS2 Partner Name</name>
<uri>example</uri>
<server_certificate>require_match</server_certificate>
<enable_dedicated_ips type="boolean">true</enable_dedicated_ips>
<hex_public_certificate_serial>A5:EB:C1:95:DC:D8:2B:E7</hex_public_certificate_serial>
<public_certificate_md5>example</public_certificate_md5>
<public_certificate_subject>example</public_certificate_subject>
<public_certificate_issuer>example</public_certificate_issuer>
<public_certificate_serial>example</public_certificate_serial>
<public_certificate_not_before>example</public_certificate_not_before>
<public_certificate_not_after>example</public_certificate_not_after>
</as2-partner>
Attribute | Description |
---|---|
id int64 | Id of the AS2 Partner. |
as2_station_id int64 | Id of the AS2 Station associated with this partner. |
name string | The partner's formal AS2 name. |
uri string | Public URI for sending AS2 message to. |
server_certificate string | Remote server certificate security setting Possible values: require_match , allow_any |
enable_dedicated_ips boolean | true if remote server only accepts connections from dedicated IPs |
hex_public_certificate_serial string | Serial of public certificate used for message security in hex format. |
public_certificate_md5 string | MD5 hash of public certificate used for message security. |
public_certificate_subject string | Subject of public certificate used for message security. |
public_certificate_issuer string | Issuer of public certificate used for message security. |
public_certificate_serial string | Serial of public certificate used for message security. |
public_certificate_not_before string | Not before value of public certificate used for message security. |
public_certificate_not_after string | Not after value of public certificate used for message security. |
public_certificate string |
List As2 Partners
Example Request
curl "https://app.files.com/api/rest/v1/as2_partners.json" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/as2_partners.xml" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::As2Partner.list(
per_page: 1
)
\Files\Model\As2Partner::list(array(
'per_page' => 1
));
HashMap<Object, String> requestParams = new HashMap<>();
requestParams.put("per_page", 1);
As2Partner.list(parameters).all()
await As2Partner.list({
per_page: 1,
})
var parameters = new Dictionary<string, object>();
parameters.Add("per_page", (Int64?) 1);
await As2Partner.List(parameters).All();
files_sdk.set_api_key("my-key")
files_sdk.as2_partner.list({
"per_page": 1
})
files_sdk.APIKey = "YOUR_API_KEY"
as2partner.List(context.Background(), files_sdk.As2PartnerListParams{
Cursor: "",
PerPage: 1,
})
files-cli as2-partners list \
--cursor="" \
--per-page=1 \
--api-key=YOUR_API_KEY
Example Response
[
{
"id": 1,
"as2_station_id": 1,
"name": "AS2 Partner Name",
"uri": "example",
"server_certificate": "require_match",
"enable_dedicated_ips": true,
"hex_public_certificate_serial": "A5:EB:C1:95:DC:D8:2B:E7",
"public_certificate_md5": "example",
"public_certificate_subject": "example",
"public_certificate_issuer": "example",
"public_certificate_serial": "example",
"public_certificate_not_before": "example",
"public_certificate_not_after": "example"
}
]
<?xml version="1.0" encoding="UTF-8"?>
<as2-partners type="array">
<as2-partner>
<id type="integer">1</id>
<as2_station_id type="integer">1</as2_station_id>
<name>AS2 Partner Name</name>
<uri>example</uri>
<server_certificate>require_match</server_certificate>
<enable_dedicated_ips type="boolean">true</enable_dedicated_ips>
<hex_public_certificate_serial>A5:EB:C1:95:DC:D8:2B:E7</hex_public_certificate_serial>
<public_certificate_md5>example</public_certificate_md5>
<public_certificate_subject>example</public_certificate_subject>
<public_certificate_issuer>example</public_certificate_issuer>
<public_certificate_serial>example</public_certificate_serial>
<public_certificate_not_before>example</public_certificate_not_before>
<public_certificate_not_after>example</public_certificate_not_after>
</as2-partner>
</as2-partners>
HTTPS Request
GET /as2_partners
Authentication Required
Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.
Request Parameters
No request parameters available for this endpoint.
Pagination Params
Read more about Paginating List Requests.
Show As2 Partner
Example Request
curl https://app.files.com/api/rest/v1/as2_partners/{id}.json \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl https://app.files.com/api/rest/v1/as2_partners/{id}.xml \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::As2Partner.find(id)
\Files\Model\As2Partner::find($id);
As2Partner.find(, parameters
await As2Partner.find(id)
await As2Partner.Find(id);
files_sdk.set_api_key("my-key")
files_sdk.as2_partner.find(id)
files_sdk.APIKey = "YOUR_API_KEY"
as2partner.Find(context.Background(), files_sdk.As2PartnerFindParams{
Id: 1,
})
files-cli as2-partners find \
--id=1 \
--api-key=YOUR_API_KEY
Example Response
{
"id": 1,
"as2_station_id": 1,
"name": "AS2 Partner Name",
"uri": "example",
"server_certificate": "require_match",
"enable_dedicated_ips": true,
"hex_public_certificate_serial": "A5:EB:C1:95:DC:D8:2B:E7",
"public_certificate_md5": "example",
"public_certificate_subject": "example",
"public_certificate_issuer": "example",
"public_certificate_serial": "example",
"public_certificate_not_before": "example",
"public_certificate_not_after": "example"
}
<?xml version="1.0" encoding="UTF-8"?>
<as2-partner>
<id type="integer">1</id>
<as2_station_id type="integer">1</as2_station_id>
<name>AS2 Partner Name</name>
<uri>example</uri>
<server_certificate>require_match</server_certificate>
<enable_dedicated_ips type="boolean">true</enable_dedicated_ips>
<hex_public_certificate_serial>A5:EB:C1:95:DC:D8:2B:E7</hex_public_certificate_serial>
<public_certificate_md5>example</public_certificate_md5>
<public_certificate_subject>example</public_certificate_subject>
<public_certificate_issuer>example</public_certificate_issuer>
<public_certificate_serial>example</public_certificate_serial>
<public_certificate_not_before>example</public_certificate_not_before>
<public_certificate_not_after>example</public_certificate_not_after>
</as2-partner>
HTTPS Request
GET /as2_partners/{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 | As2 Partner ID. |
Create As2 Partner
Example Request
curl https://app.files.com/api/rest/v1/as2_partners.json \
-X POST \
-H 'Content-Type: application/json' \
-d '{"name":"name","uri":"uri","public_certificate":"public_certificate","as2_station_id":1,"server_certificate":"require_match","enable_dedicated_ips":true}' \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl https://app.files.com/api/rest/v1/as2_partners.xml \
-X POST \
-H 'Content-Type: application/xml' \
-d '<as2-partner>
<name>name</name>
<uri>uri</uri>
<public_certificate>public_certificate</public_certificate>
<as2_station_id type="integer">1</as2_station_id>
<server_certificate>require_match</server_certificate>
<enable_dedicated_ips type="boolean">true</enable_dedicated_ips>
</as2-partner>'
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::As2Partner.create(
name: "name",
uri: "uri",
public_certificate: "public_certificate",
as2_station_id: 1,
server_certificate: "require_match",
enable_dedicated_ips: true
)
\Files\Model\As2Partner::create(array(
'name' => "name",
'uri' => "uri",
'public_certificate' => "public_certificate",
'as2_station_id' => 1,
'server_certificate' => "require_match",
'enable_dedicated_ips' => true
));
HashMap<Object, String> requestParams = new HashMap<>();
requestParams.put("name", name);
requestParams.put("uri", uri);
requestParams.put("public_certificate", public_certificate);
requestParams.put("as2_station_id", 1);
requestParams.put("server_certificate", require_match);
requestParams.put("enable_dedicated_ips", true);
As2Partner.create(parameters)
await As2Partner.create({
name: "name",
uri: "uri",
public_certificate: "public_certificate",
as2_station_id: 1,
server_certificate: "require_match",
enable_dedicated_ips: true,
})
var parameters = new Dictionary<string, object>();
parameters.Add("name", "name");
parameters.Add("uri", "uri");
parameters.Add("public_certificate", "public_certificate");
parameters.Add("as2_station_id", (Int64?) 1);
parameters.Add("server_certificate", "require_match");
parameters.Add("enable_dedicated_ips", true);
await As2Partner.Create(parameters);
files_sdk.set_api_key("my-key")
files_sdk.as2_partner.create({
"name": "name",
"uri": "uri",
"public_certificate": "public_certificate",
"as2_station_id": 1,
"server_certificate": "require_match",
"enable_dedicated_ips": True
})
files_sdk.APIKey = "YOUR_API_KEY"
as2partner.Create(context.Background(), files_sdk.As2PartnerCreateParams{
Name: "name",
Uri: "uri",
PublicCertificate: "public_certificate",
As2StationId: 1,
ServerCertificate: "require_match",
EnableDedicatedIps: lib.Bool(true),
})
files-cli as2-partners create \
--name="name" \
--uri="uri" \
--public-certificate="public_certificate" \
--as2-station-id=1 \
--server-certificate="require_match" \
--api-key=YOUR_API_KEY
Example Response
{
"id": 1,
"as2_station_id": 1,
"name": "AS2 Partner Name",
"uri": "example",
"server_certificate": "require_match",
"enable_dedicated_ips": true,
"hex_public_certificate_serial": "A5:EB:C1:95:DC:D8:2B:E7",
"public_certificate_md5": "example",
"public_certificate_subject": "example",
"public_certificate_issuer": "example",
"public_certificate_serial": "example",
"public_certificate_not_before": "example",
"public_certificate_not_after": "example"
}
<?xml version="1.0" encoding="UTF-8"?>
<as2-partner>
<id type="integer">1</id>
<as2_station_id type="integer">1</as2_station_id>
<name>AS2 Partner Name</name>
<uri>example</uri>
<server_certificate>require_match</server_certificate>
<enable_dedicated_ips type="boolean">true</enable_dedicated_ips>
<hex_public_certificate_serial>A5:EB:C1:95:DC:D8:2B:E7</hex_public_certificate_serial>
<public_certificate_md5>example</public_certificate_md5>
<public_certificate_subject>example</public_certificate_subject>
<public_certificate_issuer>example</public_certificate_issuer>
<public_certificate_serial>example</public_certificate_serial>
<public_certificate_not_before>example</public_certificate_not_before>
<public_certificate_not_after>example</public_certificate_not_after>
</as2-partner>
HTTPS Request
POST /as2_partners
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 Required | AS2 Name |
uri string Required | URL base for AS2 responses |
public_certificate string Required | |
as2_station_id int64 Required | Id of As2Station for this partner |
server_certificate string | Remote server certificate security setting |
enable_dedicated_ips boolean |
Update As2 Partner
Example Request
curl https://app.files.com/api/rest/v1/as2_partners/{id}.json \
-X PATCH \
-H 'Content-Type: application/json' \
-d '{"name":"AS2 Partner Name","uri":"example","server_certificate":"require_match","enable_dedicated_ips":true}' \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl https://app.files.com/api/rest/v1/as2_partners/{id}.xml \
-X PATCH \
-H 'Content-Type: application/xml' \
-d '<as2-partner>
<name>AS2 Partner Name</name>
<uri>example</uri>
<server_certificate>require_match</server_certificate>
<enable_dedicated_ips type="boolean">true</enable_dedicated_ips>
</as2-partner>'
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
as2_partner = Files::As2Partner.list.first
as2_partner.update(
name: "AS2 Partner Name",
uri: "example",
server_certificate: "require_match",
enable_dedicated_ips: true
)
$as2_partner = \Files\Model\As2Partner::list()[0];
$as2_partner->update(array(
'name' => "AS2 Partner Name",
'uri' => "example",
'server_certificate' => "require_match",
'enable_dedicated_ips' => true
));
As2Partner as2Partner = As2Partner.list()[0];
as2Partner.setName("AS2 Partner Name");
as2Partner.setUri("example");
as2Partner.setServerCertificate("require_match");
as2Partner.setEnableDedicatedIps(true);
as2Partner.update();
const as2Partner = (await As2Partner.list())[0]
await as2Partner.update({
name: "AS2 Partner Name",
uri: "example",
server_certificate: "require_match",
enable_dedicated_ips: true,
})
var as2Partner = (await As2Partner.List())[0];
var parameters = new Dictionary<string, object>();
parameters.Add("name", "AS2 Partner Name");
parameters.Add("uri", "example");
parameters.Add("server_certificate", "require_match");
parameters.Add("enable_dedicated_ips", true);
await as2Partner.Update(parameters);
files_sdk.set_api_key("my-key")
as2_partner = files_sdk.as2_partner.find(id)
as2_partner.update({
"name": "AS2 Partner Name",
"uri": "example",
"server_certificate": "require_match",
"enable_dedicated_ips": True
})
files_sdk.APIKey = "YOUR_API_KEY"
as2partner.Update(context.Background(), files_sdk.As2PartnerUpdateParams{
Id: 1,
Name: "AS2 Partner Name",
Uri: "example",
ServerCertificate: "require_match",
PublicCertificate: "",
EnableDedicatedIps: lib.Bool(true),
})
files-cli as2-partners update \
--id=1 \
--name="AS2 Partner Name" \
--uri="example" \
--server-certificate="require_match" \
--public-certificate="" \
--api-key=YOUR_API_KEY
Example Response
{
"id": 1,
"as2_station_id": 1,
"name": "AS2 Partner Name",
"uri": "example",
"server_certificate": "require_match",
"enable_dedicated_ips": true,
"hex_public_certificate_serial": "A5:EB:C1:95:DC:D8:2B:E7",
"public_certificate_md5": "example",
"public_certificate_subject": "example",
"public_certificate_issuer": "example",
"public_certificate_serial": "example",
"public_certificate_not_before": "example",
"public_certificate_not_after": "example"
}
<?xml version="1.0" encoding="UTF-8"?>
<as2-partner>
<id type="integer">1</id>
<as2_station_id type="integer">1</as2_station_id>
<name>AS2 Partner Name</name>
<uri>example</uri>
<server_certificate>require_match</server_certificate>
<enable_dedicated_ips type="boolean">true</enable_dedicated_ips>
<hex_public_certificate_serial>A5:EB:C1:95:DC:D8:2B:E7</hex_public_certificate_serial>
<public_certificate_md5>example</public_certificate_md5>
<public_certificate_subject>example</public_certificate_subject>
<public_certificate_issuer>example</public_certificate_issuer>
<public_certificate_serial>example</public_certificate_serial>
<public_certificate_not_before>example</public_certificate_not_before>
<public_certificate_not_after>example</public_certificate_not_after>
</as2-partner>
HTTPS Request
PATCH /as2_partners/{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 | As2 Partner ID. |
name string | AS2 Name |
uri string | URL base for AS2 responses |
server_certificate string | Remote server certificate security setting |
public_certificate string | |
enable_dedicated_ips boolean |
Delete As2 Partner
Example Request
curl https://app.files.com/api/rest/v1/as2_partners/{id}.json \
-X DELETE \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl https://app.files.com/api/rest/v1/as2_partners/{id}.xml \
-X DELETE \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
as2_partner = Files::As2Partner.list.first
as2_partner.delete
$as2_partner = \Files\Model\As2Partner::list()[0];
$as2_partner->delete();
As2Partner as2Partner = As2Partner.list()[0];
as2Partner.delete();
const as2Partner = (await As2Partner.list())[0]
await as2Partner.delete()
var as2Partner = (await As2Partner.List())[0];
await as2Partner.Delete();
files_sdk.set_api_key("my-key")
as2_partner = files_sdk.as2_partner.find(id)
as2_partner.delete()
files_sdk.APIKey = "YOUR_API_KEY"
as2partner.Delete(context.Background(), files_sdk.As2PartnerDeleteParams{
Id: 1,
})
files-cli as2-partners delete \
--id=1 \
--api-key=YOUR_API_KEY
Example Response
No response.
No response.
HTTPS Request
DELETE /as2_partners/{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 | As2 Partner ID. |
As2 Stations
As2 Station defines a remote AS2 server that can send data into Files.com and received data from Files.com
The As2Station object
Example As2Station Object
{
"id": 1,
"name": "AS2 Station Name",
"uri": "example",
"domain": "domain.test",
"hex_public_certificate_serial": "A5:EB:C1:95:DC:D8:2B:E7",
"public_certificate_md5": "example",
"private_key_md5": "example",
"public_certificate_subject": "example",
"public_certificate_issuer": "example",
"public_certificate_serial": "example",
"public_certificate_not_before": "example",
"public_certificate_not_after": "example",
"private_key_password_md5": "example"
}
<?xml version="1.0" encoding="UTF-8"?>
<as2-station>
<id type="integer">1</id>
<name>AS2 Station Name</name>
<uri>example</uri>
<domain>domain.test</domain>
<hex_public_certificate_serial>A5:EB:C1:95:DC:D8:2B:E7</hex_public_certificate_serial>
<public_certificate_md5>example</public_certificate_md5>
<private_key_md5>example</private_key_md5>
<public_certificate_subject>example</public_certificate_subject>
<public_certificate_issuer>example</public_certificate_issuer>
<public_certificate_serial>example</public_certificate_serial>
<public_certificate_not_before>example</public_certificate_not_before>
<public_certificate_not_after>example</public_certificate_not_after>
<private_key_password_md5>example</private_key_password_md5>
</as2-station>
Attribute | Description |
---|---|
id int64 | Id of the AS2 Station. |
name string | The station's formal AS2 name. |
uri string | Public URI for sending AS2 message to. |
domain string | The station's AS2 domain name. |
hex_public_certificate_serial string | Serial of public certificate used for message security in hex format. |
public_certificate_md5 string | MD5 hash of public certificate used for message security. |
private_key_md5 string | MD5 hash of private key used for message security. |
public_certificate_subject string | Subject of public certificate used for message security. |
public_certificate_issuer string | Issuer of public certificate used for message security. |
public_certificate_serial string | Serial of public certificate used for message security. |
public_certificate_not_before string | Not before value of public certificate used for message security. |
public_certificate_not_after string | Not after value of public certificate used for message security. |
private_key_password_md5 string | MD5 hash of private key password used for message security. |
public_certificate string | |
private_key string | |
private_key_password string |
List As2 Stations
Example Request
curl "https://app.files.com/api/rest/v1/as2_stations.json" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/as2_stations.xml" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::As2Station.list(
per_page: 1
)
\Files\Model\As2Station::list(array(
'per_page' => 1
));
HashMap<Object, String> requestParams = new HashMap<>();
requestParams.put("per_page", 1);
As2Station.list(parameters).all()
await As2Station.list({
per_page: 1,
})
var parameters = new Dictionary<string, object>();
parameters.Add("per_page", (Int64?) 1);
await As2Station.List(parameters).All();
files_sdk.set_api_key("my-key")
files_sdk.as2_station.list({
"per_page": 1
})
files_sdk.APIKey = "YOUR_API_KEY"
as2station.List(context.Background(), files_sdk.As2StationListParams{
Cursor: "",
PerPage: 1,
})
files-cli as2-stations list \
--cursor="" \
--per-page=1 \
--api-key=YOUR_API_KEY
Example Response
[
{
"id": 1,
"name": "AS2 Station Name",
"uri": "example",
"domain": "domain.test",
"hex_public_certificate_serial": "A5:EB:C1:95:DC:D8:2B:E7",
"public_certificate_md5": "example",
"private_key_md5": "example",
"public_certificate_subject": "example",
"public_certificate_issuer": "example",
"public_certificate_serial": "example",
"public_certificate_not_before": "example",
"public_certificate_not_after": "example",
"private_key_password_md5": "example"
}
]
<?xml version="1.0" encoding="UTF-8"?>
<as2-stations type="array">
<as2-station>
<id type="integer">1</id>
<name>AS2 Station Name</name>
<uri>example</uri>
<domain>domain.test</domain>
<hex_public_certificate_serial>A5:EB:C1:95:DC:D8:2B:E7</hex_public_certificate_serial>
<public_certificate_md5>example</public_certificate_md5>
<private_key_md5>example</private_key_md5>
<public_certificate_subject>example</public_certificate_subject>
<public_certificate_issuer>example</public_certificate_issuer>
<public_certificate_serial>example</public_certificate_serial>
<public_certificate_not_before>example</public_certificate_not_before>
<public_certificate_not_after>example</public_certificate_not_after>
<private_key_password_md5>example</private_key_password_md5>
</as2-station>
</as2-stations>
HTTPS Request
GET /as2_stations
Authentication Required
Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.
Request Parameters
No request parameters available for this endpoint.
Pagination Params
Read more about Paginating List Requests.
Show As2 Station
Example Request
curl https://app.files.com/api/rest/v1/as2_stations/{id}.json \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl https://app.files.com/api/rest/v1/as2_stations/{id}.xml \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::As2Station.find(id)
\Files\Model\As2Station::find($id);
As2Station.find(, parameters
await As2Station.find(id)
await As2Station.Find(id);
files_sdk.set_api_key("my-key")
files_sdk.as2_station.find(id)
files_sdk.APIKey = "YOUR_API_KEY"
as2station.Find(context.Background(), files_sdk.As2StationFindParams{
Id: 1,
})
files-cli as2-stations find \
--id=1 \
--api-key=YOUR_API_KEY
Example Response
{
"id": 1,
"name": "AS2 Station Name",
"uri": "example",
"domain": "domain.test",
"hex_public_certificate_serial": "A5:EB:C1:95:DC:D8:2B:E7",
"public_certificate_md5": "example",
"private_key_md5": "example",
"public_certificate_subject": "example",
"public_certificate_issuer": "example",
"public_certificate_serial": "example",
"public_certificate_not_before": "example",
"public_certificate_not_after": "example",
"private_key_password_md5": "example"
}
<?xml version="1.0" encoding="UTF-8"?>
<as2-station>
<id type="integer">1</id>
<name>AS2 Station Name</name>
<uri>example</uri>
<domain>domain.test</domain>
<hex_public_certificate_serial>A5:EB:C1:95:DC:D8:2B:E7</hex_public_certificate_serial>
<public_certificate_md5>example</public_certificate_md5>
<private_key_md5>example</private_key_md5>
<public_certificate_subject>example</public_certificate_subject>
<public_certificate_issuer>example</public_certificate_issuer>
<public_certificate_serial>example</public_certificate_serial>
<public_certificate_not_before>example</public_certificate_not_before>
<public_certificate_not_after>example</public_certificate_not_after>
<private_key_password_md5>example</private_key_password_md5>
</as2-station>
HTTPS Request
GET /as2_stations/{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 | As2 Station ID. |
Create As2 Station
Example Request
curl https://app.files.com/api/rest/v1/as2_stations.json \
-X POST \
-H 'Content-Type: application/json' \
-d '{"name":"name","public_certificate":"public_certificate","private_key":"private_key"}' \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl https://app.files.com/api/rest/v1/as2_stations.xml \
-X POST \
-H 'Content-Type: application/xml' \
-d '<as2-station>
<name>name</name>
<public_certificate>public_certificate</public_certificate>
<private_key>private_key</private_key>
</as2-station>'
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::As2Station.create(
name: "name",
public_certificate: "public_certificate",
private_key: "private_key"
)
\Files\Model\As2Station::create(array(
'name' => "name",
'public_certificate' => "public_certificate",
'private_key' => "private_key"
));
HashMap<Object, String> requestParams = new HashMap<>();
requestParams.put("name", name);
requestParams.put("public_certificate", public_certificate);
requestParams.put("private_key", private_key);
As2Station.create(parameters)
await As2Station.create({
name: "name",
public_certificate: "public_certificate",
private_key: "private_key",
})
var parameters = new Dictionary<string, object>();
parameters.Add("name", "name");
parameters.Add("public_certificate", "public_certificate");
parameters.Add("private_key", "private_key");
await As2Station.Create(parameters);
files_sdk.set_api_key("my-key")
files_sdk.as2_station.create({
"name": "name",
"public_certificate": "public_certificate",
"private_key": "private_key"
})
files_sdk.APIKey = "YOUR_API_KEY"
as2station.Create(context.Background(), files_sdk.As2StationCreateParams{
Name: "name",
PublicCertificate: "public_certificate",
PrivateKey: "private_key",
PrivateKeyPassword: "",
})
files-cli as2-stations create \
--name="name" \
--public-certificate="public_certificate" \
--private-key="private_key" \
--private-key-password="" \
--api-key=YOUR_API_KEY
Example Response
{
"id": 1,
"name": "AS2 Station Name",
"uri": "example",
"domain": "domain.test",
"hex_public_certificate_serial": "A5:EB:C1:95:DC:D8:2B:E7",
"public_certificate_md5": "example",
"private_key_md5": "example",
"public_certificate_subject": "example",
"public_certificate_issuer": "example",
"public_certificate_serial": "example",
"public_certificate_not_before": "example",
"public_certificate_not_after": "example",
"private_key_password_md5": "example"
}
<?xml version="1.0" encoding="UTF-8"?>
<as2-station>
<id type="integer">1</id>
<name>AS2 Station Name</name>
<uri>example</uri>
<domain>domain.test</domain>
<hex_public_certificate_serial>A5:EB:C1:95:DC:D8:2B:E7</hex_public_certificate_serial>
<public_certificate_md5>example</public_certificate_md5>
<private_key_md5>example</private_key_md5>
<public_certificate_subject>example</public_certificate_subject>
<public_certificate_issuer>example</public_certificate_issuer>
<public_certificate_serial>example</public_certificate_serial>
<public_certificate_not_before>example</public_certificate_not_before>
<public_certificate_not_after>example</public_certificate_not_after>
<private_key_password_md5>example</private_key_password_md5>
</as2-station>
HTTPS Request
POST /as2_stations
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 Required | AS2 Name |
public_certificate string Required | |
private_key string Required | |
private_key_password string |
Update As2 Station
Example Request
curl https://app.files.com/api/rest/v1/as2_stations/{id}.json \
-X PATCH \
-H 'Content-Type: application/json' \
-d '{"name":"AS2 Station Name"}' \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl https://app.files.com/api/rest/v1/as2_stations/{id}.xml \
-X PATCH \
-H 'Content-Type: application/xml' \
-d '<as2-station>
<name>AS2 Station Name</name>
</as2-station>'
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
as2_station = Files::As2Station.list.first
as2_station.update(
name: "AS2 Station Name"
)
$as2_station = \Files\Model\As2Station::list()[0];
$as2_station->update(array(
'name' => "AS2 Station Name"
));
As2Station as2Station = As2Station.list()[0];
as2Station.setName("AS2 Station Name");
as2Station.update();
const as2Station = (await As2Station.list())[0]
await as2Station.update({
name: "AS2 Station Name",
})
var as2Station = (await As2Station.List())[0];
var parameters = new Dictionary<string, object>();
parameters.Add("name", "AS2 Station Name");
await as2Station.Update(parameters);
files_sdk.set_api_key("my-key")
as2_station = files_sdk.as2_station.find(id)
as2_station.update({
"name": "AS2 Station Name"
})
files_sdk.APIKey = "YOUR_API_KEY"
as2station.Update(context.Background(), files_sdk.As2StationUpdateParams{
Id: 1,
Name: "AS2 Station Name",
PublicCertificate: "",
PrivateKey: "",
PrivateKeyPassword: "",
})
files-cli as2-stations update \
--id=1 \
--name="AS2 Station Name" \
--public-certificate="" \
--private-key="" \
--private-key-password="" \
--api-key=YOUR_API_KEY
Example Response
{
"id": 1,
"name": "AS2 Station Name",
"uri": "example",
"domain": "domain.test",
"hex_public_certificate_serial": "A5:EB:C1:95:DC:D8:2B:E7",
"public_certificate_md5": "example",
"private_key_md5": "example",
"public_certificate_subject": "example",
"public_certificate_issuer": "example",
"public_certificate_serial": "example",
"public_certificate_not_before": "example",
"public_certificate_not_after": "example",
"private_key_password_md5": "example"
}
<?xml version="1.0" encoding="UTF-8"?>
<as2-station>
<id type="integer">1</id>
<name>AS2 Station Name</name>
<uri>example</uri>
<domain>domain.test</domain>
<hex_public_certificate_serial>A5:EB:C1:95:DC:D8:2B:E7</hex_public_certificate_serial>
<public_certificate_md5>example</public_certificate_md5>
<private_key_md5>example</private_key_md5>
<public_certificate_subject>example</public_certificate_subject>
<public_certificate_issuer>example</public_certificate_issuer>
<public_certificate_serial>example</public_certificate_serial>
<public_certificate_not_before>example</public_certificate_not_before>
<public_certificate_not_after>example</public_certificate_not_after>
<private_key_password_md5>example</private_key_password_md5>
</as2-station>
HTTPS Request
PATCH /as2_stations/{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 | As2 Station ID. |
name string | AS2 Name |
public_certificate string | |
private_key string | |
private_key_password string |
Delete As2 Station
Example Request
curl https://app.files.com/api/rest/v1/as2_stations/{id}.json \
-X DELETE \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl https://app.files.com/api/rest/v1/as2_stations/{id}.xml \
-X DELETE \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
as2_station = Files::As2Station.list.first
as2_station.delete
$as2_station = \Files\Model\As2Station::list()[0];
$as2_station->delete();
As2Station as2Station = As2Station.list()[0];
as2Station.delete();
const as2Station = (await As2Station.list())[0]
await as2Station.delete()
var as2Station = (await As2Station.List())[0];
await as2Station.Delete();
files_sdk.set_api_key("my-key")
as2_station = files_sdk.as2_station.find(id)
as2_station.delete()
files_sdk.APIKey = "YOUR_API_KEY"
as2station.Delete(context.Background(), files_sdk.As2StationDeleteParams{
Id: 1,
})
files-cli as2-stations delete \
--id=1 \
--api-key=YOUR_API_KEY
Example Response
No response.
No response.
HTTPS Request
DELETE /as2_stations/{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 | As2 Station 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.
Automations are never removed when folders are removed, while Behaviors are removed when the associated folder is removed.
Path Matching
The path
attribute specifies which folders this automation applies to.
It gets combined with the source
attribute to determine which files are actually affected by the automation.
Note that the path
attribute supports globs, and only refers to folders.
It's the source
attribute combined with the path
attribute that determines which files are affected, and automations only operate on the files themselves.
Additionally, paths in Automations can refer to folders which don't yet exist.
Path Globs
Although Automations may have a path
specified, it can be a glob (which includes wildcards), which affects multiple folders.
*
matches any folder at that level of the path, but not subfolders. For example, path/to/*
matches path/to/folder1
and path/to/folder2
, but not path/to/folder1/subfolder
.
**
matches subfolders recursively. For example, path/to/**
matches path/to/folder1
, path/to/folder1/subfolder
, path/to/folder2
, path/to/folder2/subfolder
, etc.
?
matches any one character.
Use square brackets []
to match any character from a set. This works like a regular expression, including negation using ^
.
Globs are not supported on remote paths of any kind.
Automation Triggers
Automations can be triggered in the following ways:
custom_schedule
: The automation will run according to the custom schedule parameters fordays_of_week
(0-based) andtimes_of_day
. A time zone may be specified viatime_zone
in Rails TimeZone name format.daily
: The automation will run once in a pickedinterval
. You can specifyrecurring_day
to select day number inside a pickedinterval
it should be run on.webhook
: the automation will run when a request is sent to the corresponding webhook URL.action
: The automation will run when a specific action happens, e.g. a file is created or downloaded.
Future enhancements will allow Automations to be triggered by an incoming email, or by other services.
Currently, all Automation types support all triggers, with the following exceptions: Create Folder
and Run Remote Server Sync
are not supported by the action
trigger.
Automations can be triggered manually if trigger is not set to action
.
Destinations
The destinations
parameter is a list of paths where files will be copied, moved, or created. It may include formatting parameters to dynamically determine the destination at runtime.
Relative vs. Absolute Paths
In order to specify a relative path, it must start with either ./
or ../
. All other paths are considered absolute. In general, leading slashes should never be used on Files.com paths, including here. Paths are interpreted as absolute in all contexts, even without a leading slash.
Files vs. Folders
If the destination path ends with a /
, the filename from the source path will be preserved and put into the folder of this name. If the destination path does not end with a /
, it will be interpreted as a filename and will override the source file's filename entirely.
Formatting Parameters
Action-Triggered Automations
%tf
: The name of the file that triggered the automation.%tp
: The path of the file that triggered the automation.%td
: The directory of the file that triggered the automation.
For example, if the triggering file is at path/to/file.txt
, then the automation destination path/to/dest/incoming-%tf
will result in the actual destination being path/to/dest/incoming-file.txt
.
Parent Folders
To reference the parent folder of a source file, use %p1
, %p2
, %p3
, etc. for the first, second, third, etc. parent folder, respectively.
For example, if the source file is at accounts/file.txt
, then the automation destination path/to/dest/%p1/some_file_name.txt
will result in the actual destination being path/to/dest/accounts/some_file_name.txt
.
Dates and Times
%Y
: The current year (4 digits)%m
: The current month (2 digits)%B
: The current month (full name)%d
: The current day (2 digits)%H
: The current hour (2 digits, 24-hour clock)%M
: The current minute (2 digits)%S
: The current second (2 digits)%z
: UTC Time Zone (e.g. -0900)
For example, if the current date is June 23, 2023 and the source file is named daily_sales.csv
, then the following automation destination path/to/dest/%Y/%m/%d/
will result in the actual destination being path/to/dest/2023/06/23/daily_sales.csv
.
Replacing Text
To replace text in the source filename, use the destination_replace_from
and destination_replace_to
parameters. This will perform a simple text replacement on the source filename before inserting it into the destination path.
For example, if the destination_replace_from
is incoming
and the destination_replace_to
is outgoing
, then path/to/incoming.txt
will translate to path/to/outgoing.txt
.
Automation Types
There are several types of automations: Create Folder, Copy File, Move File, Delete File and, Run Remote Server Sync.
Create Folder
Creates the folder with named by destinations
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/*/
- Destinations:
%Y/Quarter-ending-%m-%d
Note this assumes you have folders in AccountingAndTax/SalesTax/State/
already created for each state, e.g. AccountingAndTax/SalesTax/State/CA/
.
Delete File
Deletes the file with path matching source
(wildcards allowed) in the path named by path
.
Copy File
Copies files in the folder named by path
to the path specified in destinations
.
The automation will only fire on files matching the source
(wildcards allowed). In the case of an action-triggered automation, it will only operate on the actual file that triggered the automation.
If the parameter limit
exists, the automation will only copy the newest limit
files.
Move File
Moves files in the folder named by path
to the path specified in destinations
.
The automation will only fire on files matching the source
(wildcards allowed). In the case of an action-triggered automation, it will only operate on the actual file that triggered the automation.
If the parameter limit
exists, the automation will only move the newest limit
files.
Note that for a move with multiple destinations, all but one destination is treated as a copy.
Run Remote Server Sync
The Run Remote Server Sync automation runs the remote server syncs specified by the sync_ids
.
Typically when this automation is used, the remote server syncs in question are set to the manual
scheduling mode (manual
to true
via the API) to disable the built in sync scheduler.
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",
"deleted": true,
"disabled": true,
"trigger": "daily",
"interval": "week",
"last_modified_at": "2000-01-01T01:00:00Z",
"name": "example",
"schedule": "example",
"source": "example",
"destinations": [
"destination"
],
"destination_replace_from": "example",
"destination_replace_to": "example",
"description": "example",
"recurring_day": 25,
"path": "example",
"user_id": 1,
"sync_ids": [
1,
2
],
"user_ids": [
1,
2
],
"group_ids": [
1,
2
],
"webhook_url": "https://app.files.com/api/webhooks/abc123",
"trigger_actions": [
"create"
],
"value": {
"limit": "1"
}
}
<?xml version="1.0" encoding="UTF-8"?>
<automation>
<id type="integer">1</id>
<automation>create_folder</automation>
<deleted type="boolean">true</deleted>
<disabled type="boolean">true</disabled>
<trigger>daily</trigger>
<interval>week</interval>
<last_modified_at>2000-01-01T01:00:00Z</last_modified_at>
<name>example</name>
<schedule>example</schedule>
<source>example</source>
<destinations type="array">
<destination>destination</destination>
</destinations>
<destination_replace_from>example</destination_replace_from>
<destination_replace_to>example</destination_replace_to>
<description>example</description>
<recurring_day type="integer">25</recurring_day>
<path>example</path>
<user_id type="integer">1</user_id>
<sync_ids type="array">
<sync_id type="integer">1</sync_id>
<sync_id type="integer">2</sync_id>
</sync_ids>
<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 type="array">
<trigger_action>create</trigger_action>
</trigger_actions>
<value>
<limit>1</limit>
</value>
</automation>
Attribute | Description |
---|---|
id int64 | Automation ID |
automation string | Automation type Possible values: create_folder , delete_file , copy_file , move_file , as2_send , run_sync |
deleted boolean | Indicates if the automation has been deleted. |
disabled boolean | If true, this automation will not run. |
trigger string | How this automation is triggered to run. Possible values: 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 |
last_modified_at date-time | Time when automation was last modified. Does not change for name or description updates. |
name string | Name for this automation. |
schedule object | If trigger is custom_schedule , Custom schedule description for when the automation should be run. |
source string | Source Path |
destinations array | Destination Paths |
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. |
description string | Description for the this Automation. |
recurring_day int64 | If trigger type is daily , this specifies a day number to run in one of the supported intervals: week , month , quarter , year . |
path string | Path on which this Automation runs. Supports globs, except on remote mounts. 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. |
sync_ids array | IDs of remote sync folder behaviors to run by this Automation |
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 array | 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 |
value object | A Hash of attributes specific to the automation type. |
destination string | DEPRECATED: Destination Path. Use destinations instead. |
List Automations
Example Request
curl "https://app.files.com/api/rest/v1/automations.json" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/automations.xml" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::Automation.list(
per_page: 1,
with_deleted: true
)
\Files\Model\Automation::list(array(
'per_page' => 1,
'with_deleted' => true
));
HashMap<Object, String> requestParams = new HashMap<>();
requestParams.put("per_page", 1);
requestParams.put("with_deleted", true);
Automation.list(parameters).all()
await Automation.list({
per_page: 1,
with_deleted: true,
})
var parameters = new Dictionary<string, object>();
parameters.Add("per_page", (Int64?) 1);
parameters.Add("with_deleted", true);
await Automation.List(parameters).All();
files_sdk.set_api_key("my-key")
files_sdk.automation.list({
"per_page": 1,
"with_deleted": True
})
files_sdk.APIKey = "YOUR_API_KEY"
automation.List(context.Background(), files_sdk.AutomationListParams{
Cursor: "",
PerPage: 1,
SortBy: "",
Filter: "",
FilterGt: "",
FilterGteq: "",
FilterLt: "",
FilterLteq: "",
WithDeleted: lib.Bool(true),
})
files-cli automations list \
--cursor="" \
--per-page=1 \
--api-key=YOUR_API_KEY
Example Response
[
{
"id": 1,
"automation": "create_folder",
"deleted": true,
"disabled": true,
"trigger": "daily",
"interval": "week",
"last_modified_at": "2000-01-01T01:00:00Z",
"name": "example",
"schedule": "example",
"source": "example",
"destinations": [
"destination"
],
"destination_replace_from": "example",
"destination_replace_to": "example",
"description": "example",
"recurring_day": 25,
"path": "example",
"user_id": 1,
"sync_ids": [
1,
2
],
"user_ids": [
1,
2
],
"group_ids": [
1,
2
],
"webhook_url": "https://app.files.com/api/webhooks/abc123",
"trigger_actions": [
"create"
],
"value": {
"limit": "1"
}
}
]
<?xml version="1.0" encoding="UTF-8"?>
<automations type="array">
<automation>
<id type="integer">1</id>
<automation>create_folder</automation>
<deleted type="boolean">true</deleted>
<disabled type="boolean">true</disabled>
<trigger>daily</trigger>
<interval>week</interval>
<last_modified_at>2000-01-01T01:00:00Z</last_modified_at>
<name>example</name>
<schedule>example</schedule>
<source>example</source>
<destinations type="array">
<destination>destination</destination>
</destinations>
<destination_replace_from>example</destination_replace_from>
<destination_replace_to>example</destination_replace_to>
<description>example</description>
<recurring_day type="integer">25</recurring_day>
<path>example</path>
<user_id type="integer">1</user_id>
<sync_ids type="array">
<sync_id type="integer">1</sync_id>
<sync_id type="integer">2</sync_id>
</sync_ids>
<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 type="array">
<trigger_action>create</trigger_action>
</trigger_actions>
<value>
<limit>1</limit>
</value>
</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 |
---|---|
with_deleted boolean | Set to true to include deleted automations in the results. |
Pagination Params
Read more about Paginating List Requests.
Available Fields for Sorting
Read more about Sorting List Requests
Parameter | Description |
---|---|
sort_by object | If set, sort records by the specified field in either asc or desc direction (e.g. sort_by[automation]=desc ). Valid fields are automation , disabled , last_modified_at or name . |
Available Filters
Read more about Filtering List Requests
Parameter | Description |
---|---|
filter object | If set, return records where the specified field is equal to the supplied value. Valid fields are disabled , last_modified_at or automation . Valid field combinations are [ automation, disabled ] and [ disabled, automation ] . |
filter_gt object | If set, return records where the specified field is greater than the supplied value. Valid fields are last_modified_at . |
filter_gteq object | If set, return records where the specified field is greater than or equal the supplied value. Valid fields are last_modified_at . |
filter_lt object | If set, return records where the specified field is less than the supplied value. Valid fields are last_modified_at . |
filter_lteq object | If set, return records where the specified field is less than or equal the supplied value. Valid fields are last_modified_at . |
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(, parameters
await Automation.find(id)
await Automation.Find(id);
files_sdk.set_api_key("my-key")
files_sdk.automation.find(id)
files_sdk.APIKey = "YOUR_API_KEY"
automation.Find(context.Background(), files_sdk.AutomationFindParams{
Id: 1,
})
files-cli automations find \
--id=1 \
--api-key=YOUR_API_KEY
Example Response
{
"id": 1,
"automation": "create_folder",
"deleted": true,
"disabled": true,
"trigger": "daily",
"interval": "week",
"last_modified_at": "2000-01-01T01:00:00Z",
"name": "example",
"schedule": "example",
"source": "example",
"destinations": [
"destination"
],
"destination_replace_from": "example",
"destination_replace_to": "example",
"description": "example",
"recurring_day": 25,
"path": "example",
"user_id": 1,
"sync_ids": [
1,
2
],
"user_ids": [
1,
2
],
"group_ids": [
1,
2
],
"webhook_url": "https://app.files.com/api/webhooks/abc123",
"trigger_actions": [
"create"
],
"value": {
"limit": "1"
}
}
<?xml version="1.0" encoding="UTF-8"?>
<automation>
<id type="integer">1</id>
<automation>create_folder</automation>
<deleted type="boolean">true</deleted>
<disabled type="boolean">true</disabled>
<trigger>daily</trigger>
<interval>week</interval>
<last_modified_at>2000-01-01T01:00:00Z</last_modified_at>
<name>example</name>
<schedule>example</schedule>
<source>example</source>
<destinations type="array">
<destination>destination</destination>
</destinations>
<destination_replace_from>example</destination_replace_from>
<destination_replace_to>example</destination_replace_to>
<description>example</description>
<recurring_day type="integer">25</recurring_day>
<path>example</path>
<user_id type="integer">1</user_id>
<sync_ids type="array">
<sync_id type="integer">1</sync_id>
<sync_id type="integer">2</sync_id>
</sync_ids>
<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 type="array">
<trigger_action>create</trigger_action>
</trigger_actions>
<value>
<limit>1</limit>
</value>
</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 '{"source":"source","destinations":["folder_a/file_a.txt",{"folder_path":"folder_b","file_path":"file_b.txt"},{"folder_path":"folder_c"}],"destination_replace_from":"example","destination_replace_to":"example","interval":"year","path":"example","sync_ids":[1,2],"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)"},"description":"example","disabled":true,"name":"example","trigger":"daily","trigger_actions":["create"],"value":{"limit":"1"},"recurring_day":25,"automation":"create_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>
<source>source</source>
<destinations type="array">
<destination>folder_a/file_a.txt</destination>
<destination>
<folder_path>folder_b</folder_path>
<file_path>file_b.txt</file_path>
</destination>
<destination>
<folder_path>folder_c</folder_path>
</destination>
</destinations>
<destination_replace_from>example</destination_replace_from>
<destination_replace_to>example</destination_replace_to>
<interval>year</interval>
<path>example</path>
<sync_ids type="array">
<sync_id type="integer">1</sync_id>
<sync_id type="integer">2</sync_id>
</sync_ids>
<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 type="array">
<days_of_week type="integer">0</days_of_week>
<days_of_week type="integer">1</days_of_week>
<days_of_week type="integer">3</days_of_week>
</days_of_week>
<times_of_day type="array">
<times_of_day>7:30</times_of_day>
<times_of_day>11:30</times_of_day>
</times_of_day>
<time_zone>Eastern Time (US & Canada)</time_zone>
</schedule>
<description>example</description>
<disabled type="boolean">true</disabled>
<name>example</name>
<trigger>daily</trigger>
<trigger_actions type="array">
<trigger_action>create</trigger_action>
</trigger_actions>
<value>
<limit>1</limit>
</value>
<recurring_day type="integer">25</recurring_day>
<automation>create_folder</automation>
</automation>'
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::Automation.create(
source: "source",
destinations: ["folder_a/file_a.txt",{"folder_path":"folder_b","file_path":"file_b.txt"},{"folder_path":"folder_c"}],
destination_replace_from: "example",
destination_replace_to: "example",
interval: "year",
path: "example",
sync_ids: [1,2],
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)"},
description: "example",
disabled: true,
name: "example",
trigger: "daily",
trigger_actions: ["create"],
value: {"limit":"1"},
recurring_day: 25,
automation: "create_folder"
)
\Files\Model\Automation::create(array(
'source' => "source",
'destinations' => ["folder_a/file_a.txt",{"folder_path":"folder_b","file_path":"file_b.txt"},{"folder_path":"folder_c"}],
'destination_replace_from' => "example",
'destination_replace_to' => "example",
'interval' => "year",
'path' => "example",
'sync_ids' => [1,2],
'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)"},
'description' => "example",
'disabled' => true,
'name' => "example",
'trigger' => "daily",
'trigger_actions' => ["create"],
'value' => {"limit":"1"},
'recurring_day' => 25,
'automation' => "create_folder"
));
HashMap<Object, String> requestParams = new HashMap<>();
requestParams.put("source", source);
requestParams.put("destinations", ["folder_a/file_a.txt", {"folder_path"=>"folder_b", "file_path"=>"file_b.txt"}, {"folder_path"=>"folder_c"}]);
requestParams.put("destination_replace_from", example);
requestParams.put("destination_replace_to", example);
requestParams.put("interval", year);
requestParams.put("path", example);
requestParams.put("sync_ids", [1, 2]);
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("description", example);
requestParams.put("disabled", true);
requestParams.put("name", example);
requestParams.put("trigger", daily);
requestParams.put("trigger_actions", ["create"]);
requestParams.put("value", {"limit"=>"1"});
requestParams.put("recurring_day", 25);
requestParams.put("automation", create_folder);
Automation.create(parameters)
await Automation.create({
source: "source",
destinations: ["folder_a/file_a.txt",{"folder_path":"folder_b","file_path":"file_b.txt"},{"folder_path":"folder_c"}],
destination_replace_from: "example",
destination_replace_to: "example",
interval: "year",
path: "example",
sync_ids: [1,2],
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)"},
description: "example",
disabled: true,
name: "example",
trigger: "daily",
trigger_actions: ["create"],
value: {"limit":"1"},
recurring_day: 25,
automation: "create_folder",
})
var parameters = new Dictionary<string, object>();
parameters.Add("source", "source");
parameters.Add("destinations", (string[]) ["folder_a/file_a.txt",{"folder_path":"folder_b","file_path":"file_b.txt"},{"folder_path":"folder_c"}]);
parameters.Add("destination_replace_from", "example");
parameters.Add("destination_replace_to", "example");
parameters.Add("interval", "year");
parameters.Add("path", "example");
parameters.Add("sync_ids", [1,2]);
parameters.Add("user_ids", [1,2]);
parameters.Add("group_ids", [1,2]);
parameters.Add("schedule", (object) {"days_of_week":[0,1,3],"times_of_day":["7:30","11:30"],"time_zone":"Eastern Time (US & Canada)"});
parameters.Add("description", "example");
parameters.Add("disabled", true);
parameters.Add("name", "example");
parameters.Add("trigger", "daily");
parameters.Add("trigger_actions", (string[]) ["create"]);
parameters.Add("value", (object) {"limit":"1"});
parameters.Add("recurring_day", (Int64?) 25);
parameters.Add("automation", "create_folder");
await Automation.Create(parameters);
files_sdk.set_api_key("my-key")
files_sdk.automation.create({
"source": "source",
"destinations": ["folder_a/file_a.txt",{"folder_path":"folder_b","file_path":"file_b.txt"},{"folder_path":"folder_c"}],
"destination_replace_from": "example",
"destination_replace_to": "example",
"interval": "year",
"path": "example",
"sync_ids": [1,2],
"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)"},
"description": "example",
"disabled": True,
"name": "example",
"trigger": "daily",
"trigger_actions": ["create"],
"value": {"limit":"1"},
"recurring_day": 25,
"automation": "create_folder"
})
files_sdk.APIKey = "YOUR_API_KEY"
automation.Create(context.Background(), files_sdk.AutomationCreateParams{
Source: "source",
Destination: "",
Destinations: []string{"folder_a/file_a.txt", "{\"folder_path\"=>\"folder_b\", \"file_path\"=>\"file_b.txt\"}", "{\"folder_path\"=>\"folder_c\"}"},
DestinationReplaceFrom: "example",
DestinationReplaceTo: "example",
Interval: "year",
Path: "example",
SyncIds: []string{"1", "2"},
UserIds: []string{"1", "2"},
GroupIds: []string{"1", "2"},
Schedule: `{"days_of_week":[0,1,3],"times_of_day":["7:30","11:30"],"time_zone":"Eastern Time (US & Canada)"}`,
Description: "example",
Disabled: lib.Bool(true),
Name: "example",
Trigger: "daily",
TriggerActions: []string{"create"},
Value: `{"limit":"1"}`,
RecurringDay: 25,
Automation: "create_folder",
})
files-cli automations create \
--source="source" \
--destination="" \
--destinations="["folder_a/file_a.txt",{"folder_path":"folder_b","file_path":"file_b.txt"},{"folder_path":"folder_c"}]" \
--destination-replace-from="example" \
--destination-replace-to="example" \
--interval="year" \
--path="example" \
--sync-ids="[1,2]" \
--user-ids="[1,2]" \
--group-ids="[1,2]" \
--description="example" \
--name="example" \
--trigger="daily" \
--trigger-actions="["create"]" \
--recurring-day=25 \
--automation="create_folder" \
--api-key=YOUR_API_KEY
Example Response
{
"id": 1,
"automation": "create_folder",
"deleted": true,
"disabled": true,
"trigger": "daily",
"interval": "week",
"last_modified_at": "2000-01-01T01:00:00Z",
"name": "example",
"schedule": "example",
"source": "example",
"destinations": [
"destination"
],
"destination_replace_from": "example",
"destination_replace_to": "example",
"description": "example",
"recurring_day": 25,
"path": "example",
"user_id": 1,
"sync_ids": [
1,
2
],
"user_ids": [
1,
2
],
"group_ids": [
1,
2
],
"webhook_url": "https://app.files.com/api/webhooks/abc123",
"trigger_actions": [
"create"
],
"value": {
"limit": "1"
}
}
<?xml version="1.0" encoding="UTF-8"?>
<automation>
<id type="integer">1</id>
<automation>create_folder</automation>
<deleted type="boolean">true</deleted>
<disabled type="boolean">true</disabled>
<trigger>daily</trigger>
<interval>week</interval>
<last_modified_at>2000-01-01T01:00:00Z</last_modified_at>
<name>example</name>
<schedule>example</schedule>
<source>example</source>
<destinations type="array">
<destination>destination</destination>
</destinations>
<destination_replace_from>example</destination_replace_from>
<destination_replace_to>example</destination_replace_to>
<description>example</description>
<recurring_day type="integer">25</recurring_day>
<path>example</path>
<user_id type="integer">1</user_id>
<sync_ids type="array">
<sync_id type="integer">1</sync_id>
<sync_id type="integer">2</sync_id>
</sync_ids>
<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 type="array">
<trigger_action>create</trigger_action>
</trigger_actions>
<value>
<limit>1</limit>
</value>
</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 |
---|---|
source string | Source Path |
destination string | DEPRECATED: Destination Path. Use destinations instead. |
destinations array(string) | A list of String destination paths or Hash of folder_path and optional file_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. |
sync_ids string | A list of sync IDs the automation is associated with. If sent as a string, it should be comma-delimited. |
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. |
description string | Description for the this Automation. |
disabled boolean | If true, this automation will not run. |
name string | Name for this automation. |
trigger string | How this automation is triggered to run. Possible values: 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 |
value object | A Hash of attributes specific to the automation type. |
recurring_day int64 | If trigger type is daily , this specifies a day number to run in one of the supported intervals: week , month , quarter , year . |
automation string Required | Automation type Possible values: create_folder , delete_file , copy_file , move_file , as2_send , run_sync |
Manually run automation
Example Request
curl https://app.files.com/api/rest/v1/automations/{id}/manual_run.json \
-X POST \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl https://app.files.com/api/rest/v1/automations/{id}/manual_run.xml \
-X POST \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
automation = Files::Automation.list.first
automation.manual_run
$automation = \Files\Model\Automation::list()[0];
$automation->manualRun();
Automation automation = Automation.list()[0];
automation.manualRun();
const automation = (await Automation.list())[0]
await automation.manualRun()
var automation = (await Automation.List())[0];
await automation.ManualRun();
files_sdk.set_api_key("my-key")
automation = files_sdk.automation.find(id)
automation.manual_run()
files_sdk.APIKey = "YOUR_API_KEY"
automation.ManualRun(context.Background(), files_sdk.AutomationManualRunParams{
Id: 1,
})
files-cli automations manual-run \
--id=1 \
--api-key=YOUR_API_KEY
Example Response
No response.
No response.
HTTPS Request
POST /automations/{id}/manual_run
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. |
Update Automation
Example Request
curl https://app.files.com/api/rest/v1/automations/{id}.json \
-X PATCH \
-H 'Content-Type: application/json' \
-d '{"source":"source","destinations":["folder_a/file_a.txt",{"folder_path":"folder_b","file_path":"file_b.txt"},{"folder_path":"folder_c"}],"destination_replace_from":"example","destination_replace_to":"example","interval":"year","path":"example","sync_ids":[1,2],"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)"},"description":"example","disabled":true,"name":"example","trigger":"daily","trigger_actions":["create"],"value":{"limit":"1"},"recurring_day":25,"automation":"create_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>
<source>source</source>
<destinations type="array">
<destination>folder_a/file_a.txt</destination>
<destination>
<folder_path>folder_b</folder_path>
<file_path>file_b.txt</file_path>
</destination>
<destination>
<folder_path>folder_c</folder_path>
</destination>
</destinations>
<destination_replace_from>example</destination_replace_from>
<destination_replace_to>example</destination_replace_to>
<interval>year</interval>
<path>example</path>
<sync_ids type="array">
<sync_id type="integer">1</sync_id>
<sync_id type="integer">2</sync_id>
</sync_ids>
<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 type="array">
<days_of_week type="integer">0</days_of_week>
<days_of_week type="integer">1</days_of_week>
<days_of_week type="integer">3</days_of_week>
</days_of_week>
<times_of_day type="array">
<times_of_day>7:30</times_of_day>
<times_of_day>11:30</times_of_day>
</times_of_day>
<time_zone>Eastern Time (US & Canada)</time_zone>
</schedule>
<description>example</description>
<disabled type="boolean">true</disabled>
<name>example</name>
<trigger>daily</trigger>
<trigger_actions type="array">
<trigger_action>create</trigger_action>
</trigger_actions>
<value>
<limit>1</limit>
</value>
<recurring_day type="integer">25</recurring_day>
<automation>create_folder</automation>
</automation>'
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
automation = Files::Automation.list.first
automation.update(
source: "source",
destinations: ["folder_a/file_a.txt",{"folder_path":"folder_b","file_path":"file_b.txt"},{"folder_path":"folder_c"}],
destination_replace_from: "example",
destination_replace_to: "example",
interval: "year",
path: "example",
sync_ids: [1,2],
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)"},
description: "example",
disabled: true,
name: "example",
trigger: "daily",
trigger_actions: ["create"],
value: {"limit":"1"},
recurring_day: 25,
automation: "create_folder"
)
$automation = \Files\Model\Automation::list()[0];
$automation->update(array(
'source' => "source",
'destinations' => ["folder_a/file_a.txt",{"folder_path":"folder_b","file_path":"file_b.txt"},{"folder_path":"folder_c"}],
'destination_replace_from' => "example",
'destination_replace_to' => "example",
'interval' => "year",
'path' => "example",
'sync_ids' => [1,2],
'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)"},
'description' => "example",
'disabled' => true,
'name' => "example",
'trigger' => "daily",
'trigger_actions' => ["create"],
'value' => {"limit":"1"},
'recurring_day' => 25,
'automation' => "create_folder"
));
Automation automation = Automation.list()[0];
automation.setSource("source");
automation.setDestinations(["folder_a/file_a.txt", {"folder_path"=>"folder_b", "file_path"=>"file_b.txt"}, {"folder_path"=>"folder_c"}]);
automation.setDestinationReplaceFrom("example");
automation.setDestinationReplaceTo("example");
automation.setInterval("year");
automation.setPath("example");
automation.setSyncIds("[1, 2]");
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.setDescription("example");
automation.setDisabled(true);
automation.setName("example");
automation.setTrigger("daily");
automation.setTriggerActions(["create"]);
automation.setValue({"limit"=>"1"});
automation.setRecurringDay(25);
automation.setAutomation("create_folder");
automation.update();
const automation = (await Automation.list())[0]
await automation.update({
source: "source",
destinations: ["folder_a/file_a.txt",{"folder_path":"folder_b","file_path":"file_b.txt"},{"folder_path":"folder_c"}],
destination_replace_from: "example",
destination_replace_to: "example",
interval: "year",
path: "example",
sync_ids: [1,2],
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)"},
description: "example",
disabled: true,
name: "example",
trigger: "daily",
trigger_actions: ["create"],
value: {"limit":"1"},
recurring_day: 25,
automation: "create_folder",
})
var automation = (await Automation.List())[0];
var parameters = new Dictionary<string, object>();
parameters.Add("source", "source");
parameters.Add("destinations", (string[]), shorthand: true) ["folder_a/file_a.txt",{"folder_path":"folder_b","file_path":"file_b.txt"},{"folder_path":"folder_c"}]);
parameters.Add("destination_replace_from", "example");
parameters.Add("destination_replace_to", "example");
parameters.Add("interval", "year");
parameters.Add("path", "example");
parameters.Add("sync_ids", [1,2]);
parameters.Add("user_ids", [1,2]);
parameters.Add("group_ids", [1,2]);
parameters.Add("schedule", (object), shorthand: true) {"days_of_week":[0,1,3],"times_of_day":["7:30","11:30"],"time_zone":"Eastern Time (US & Canada)"});
parameters.Add("description", "example");
parameters.Add("disabled", true);
parameters.Add("name", "example");
parameters.Add("trigger", "daily");
parameters.Add("trigger_actions", (string[]), shorthand: true) ["create"]);
parameters.Add("value", (object), shorthand: true) {"limit":"1"});
parameters.Add("recurring_day", (Nullable<Int64>), shorthand: true) 25);
parameters.Add("automation", "create_folder");
await automation.Update(parameters);
files_sdk.set_api_key("my-key")
automation = files_sdk.automation.find(id)
automation.update({
"source": "source",
"destinations": ["folder_a/file_a.txt",{"folder_path":"folder_b","file_path":"file_b.txt"},{"folder_path":"folder_c"}],
"destination_replace_from": "example",
"destination_replace_to": "example",
"interval": "year",
"path": "example",
"sync_ids": [1,2],
"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)"},
"description": "example",
"disabled": True,
"name": "example",
"trigger": "daily",
"trigger_actions": ["create"],
"value": {"limit":"1"},
"recurring_day": 25,
"automation": "create_folder"
})
files_sdk.APIKey = "YOUR_API_KEY"
automation.Update(context.Background(), files_sdk.AutomationUpdateParams{
Id: 1,
Source: "source",
Destination: "",
Destinations: []string{"folder_a/file_a.txt", "{\"folder_path\"=>\"folder_b\", \"file_path\"=>\"file_b.txt\"}", "{\"folder_path\"=>\"folder_c\"}"},
DestinationReplaceFrom: "example",
DestinationReplaceTo: "example",
Interval: "year",
Path: "example",
SyncIds: []string{"1", "2"},
UserIds: []string{"1", "2"},
GroupIds: []string{"1", "2"},
Schedule: `{"days_of_week":[0,1,3],"times_of_day":["7:30","11:30"],"time_zone":"Eastern Time (US & Canada)"}`,
Description: "example",
Disabled: lib.Bool(true),
Name: "example",
Trigger: "daily",
TriggerActions: []string{"create"},
Value: `{"limit":"1"}`,
RecurringDay: 25,
Automation: "create_folder",
})
files-cli automations update \
--id=1 \
--source="source" \
--destination="" \
--destinations="["folder_a/file_a.txt",{"folder_path":"folder_b","file_path":"file_b.txt"},{"folder_path":"folder_c"}]" \
--destination-replace-from="example" \
--destination-replace-to="example" \
--interval="year" \
--path="example" \
--sync-ids="[1,2]" \
--user-ids="[1,2]" \
--group-ids="[1,2]" \
--description="example" \
--name="example" \
--trigger="daily" \
--trigger-actions="["create"]" \
--recurring-day=25 \
--automation="create_folder" \
--api-key=YOUR_API_KEY
Example Response
{
"id": 1,
"automation": "create_folder",
"deleted": true,
"disabled": true,
"trigger": "daily",
"interval": "week",
"last_modified_at": "2000-01-01T01:00:00Z",
"name": "example",
"schedule": "example",
"source": "example",
"destinations": [
"destination"
],
"destination_replace_from": "example",
"destination_replace_to": "example",
"description": "example",
"recurring_day": 25,
"path": "example",
"user_id": 1,
"sync_ids": [
1,
2
],
"user_ids": [
1,
2
],
"group_ids": [
1,
2
],
"webhook_url": "https://app.files.com/api/webhooks/abc123",
"trigger_actions": [
"create"
],
"value": {
"limit": "1"
}
}
<?xml version="1.0" encoding="UTF-8"?>
<automation>
<id type="integer">1</id>
<automation>create_folder</automation>
<deleted type="boolean">true</deleted>
<disabled type="boolean">true</disabled>
<trigger>daily</trigger>
<interval>week</interval>
<last_modified_at>2000-01-01T01:00:00Z</last_modified_at>
<name>example</name>
<schedule>example</schedule>
<source>example</source>
<destinations type="array">
<destination>destination</destination>
</destinations>
<destination_replace_from>example</destination_replace_from>
<destination_replace_to>example</destination_replace_to>
<description>example</description>
<recurring_day type="integer">25</recurring_day>
<path>example</path>
<user_id type="integer">1</user_id>
<sync_ids type="array">
<sync_id type="integer">1</sync_id>
<sync_id type="integer">2</sync_id>
</sync_ids>
<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 type="array">
<trigger_action>create</trigger_action>
</trigger_actions>
<value>
<limit>1</limit>
</value>
</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. |
source string | Source Path |
destination string | DEPRECATED: Destination Path. Use destinations instead. |
destinations array(string) | A list of String destination paths or Hash of folder_path and optional file_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. |
sync_ids string | A list of sync IDs the automation is associated with. If sent as a string, it should be comma-delimited. |
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. |
description string | Description for the this Automation. |
disabled boolean | If true, this automation will not run. |
name string | Name for this automation. |
trigger string | How this automation is triggered to run. Possible values: 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 |
value object | A Hash of attributes specific to the automation type. |
recurring_day int64 | If trigger type is daily , this specifies a day number to run in one of the supported intervals: week , month , quarter , year . |
automation string | Automation type Possible values: create_folder , delete_file , copy_file , move_file , as2_send , run_sync |
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.first
automation.delete
$automation = \Files\Model\Automation::list()[0];
$automation->delete();
Automation automation = Automation.list()[0];
automation.delete();
const automation = (await Automation.list())[0]
await automation.delete()
var automation = (await Automation.List())[0];
await automation.Delete();
files_sdk.set_api_key("my-key")
automation = files_sdk.automation.find(id)
automation.delete()
files_sdk.APIKey = "YOUR_API_KEY"
automation.Delete(context.Background(), files_sdk.AutomationDeleteParams{
Id: 1,
})
files-cli automations delete \
--id=1 \
--api-key=YOUR_API_KEY
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. |
Automation Runs
AutomationRuns represent a single execution of a given Automation.
The AutomationRun object
Example AutomationRun Object
{
"id": 1,
"automation_id": 1,
"completed_at": "2000-01-01T01:00:00Z",
"created_at": "2000-01-01T01:00:00Z",
"status": "success",
"status_messages_url": "https://www.example.com/log_file.txt"
}
<?xml version="1.0" encoding="UTF-8"?>
<automation-run>
<id type="integer">1</id>
<automation_id type="integer">1</automation_id>
<completed_at>2000-01-01T01:00:00Z</completed_at>
<created_at>2000-01-01T01:00:00Z</created_at>
<status>success</status>
<status_messages_url>https://www.example.com/log_file.txt</status_messages_url>
</automation-run>
Attribute | Description |
---|---|
id int64 | ID. |
automation_id int64 | ID of the associated Automation. |
completed_at date-time | Automation run completion/failure date/time. |
created_at date-time | Automation run start date/time. |
status string | The success status of the AutomationRun. One of running , success , partial_failure , or failure . Possible values: running , success , partial_failure , failure , skipped , queued |
status_messages_url string | Link to status messages log file. |
List Automation Runs
Example Request
curl "https://app.files.com/api/rest/v1/automation_runs.json?automation_id=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/automation_runs.xml?automation_id=1" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::AutomationRun.list(
per_page: 1,
automation_id: 1
)
\Files\Model\AutomationRun::list(array(
'per_page' => 1,
'automation_id' => 1
));
HashMap<Object, String> requestParams = new HashMap<>();
requestParams.put("per_page", 1);
requestParams.put("automation_id", 1);
AutomationRun.list(parameters).all()
await AutomationRun.list({
per_page: 1,
automation_id: 1,
})
var parameters = new Dictionary<string, object>();
parameters.Add("per_page", (Int64?) 1);
parameters.Add("automation_id", (Int64?) 1);
await AutomationRun.List(parameters).All();
files_sdk.set_api_key("my-key")
files_sdk.automation_run.list({
"per_page": 1,
"automation_id": 1
})
files_sdk.APIKey = "YOUR_API_KEY"
automationrun.List(context.Background(), files_sdk.AutomationRunListParams{
Cursor: "",
PerPage: 1,
SortBy: "",
Filter: "",
AutomationId: 1,
})
files-cli automation-runs list \
--cursor="" \
--per-page=1 \
--automation-id=1 \
--api-key=YOUR_API_KEY
Example Response
[
{
"id": 1,
"automation_id": 1,
"completed_at": "2000-01-01T01:00:00Z",
"created_at": "2000-01-01T01:00:00Z",
"status": "success",
"status_messages_url": "https://www.example.com/log_file.txt"
}
]
<?xml version="1.0" encoding="UTF-8"?>
<automation-runs type="array">
<automation-run>
<id type="integer">1</id>
<automation_id type="integer">1</automation_id>
<completed_at>2000-01-01T01:00:00Z</completed_at>
<created_at>2000-01-01T01:00:00Z</created_at>
<status>success</status>
<status_messages_url>https://www.example.com/log_file.txt</status_messages_url>
</automation-run>
</automation-runs>
HTTPS Request
GET /automation_runs
Authentication Required
Available to all authenticated keys or sessions.
Request Parameters
Parameter | Description |
---|---|
automation_id int64 Required | ID of the associated Automation. |
Pagination Params
Read more about Paginating List Requests.
Available Fields for Sorting
Read more about Sorting List Requests
Parameter | Description |
---|---|
sort_by object | If set, sort records by the specified field in either asc or desc direction (e.g. sort_by[automation_id]=desc ). Valid fields are automation_id , created_at or status . |
Available Filters
Read more about Filtering List Requests
Parameter | Description |
---|---|
filter object | If set, return records where the specified field is equal to the supplied value. Valid fields are status and automation_id . Valid field combinations are [ automation_id, status ] . |
Show Automation Run
Example Request
curl https://app.files.com/api/rest/v1/automation_runs/{id}.json \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl https://app.files.com/api/rest/v1/automation_runs/{id}.xml \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::AutomationRun.find(id)
\Files\Model\AutomationRun::find($id);
AutomationRun.find(, parameters
await AutomationRun.find(id)
await AutomationRun.Find(id);
files_sdk.set_api_key("my-key")
files_sdk.automation_run.find(id)
files_sdk.APIKey = "YOUR_API_KEY"
automationrun.Find(context.Background(), files_sdk.AutomationRunFindParams{
Id: 1,
})
files-cli automation-runs find \
--id=1 \
--api-key=YOUR_API_KEY
Example Response
{
"id": 1,
"automation_id": 1,
"completed_at": "2000-01-01T01:00:00Z",
"created_at": "2000-01-01T01:00:00Z",
"status": "success",
"status_messages_url": "https://www.example.com/log_file.txt"
}
<?xml version="1.0" encoding="UTF-8"?>
<automation-run>
<id type="integer">1</id>
<automation_id type="integer">1</automation_id>
<completed_at>2000-01-01T01:00:00Z</completed_at>
<created_at>2000-01-01T01:00:00Z</created_at>
<status>success</status>
<status_messages_url>https://www.example.com/log_file.txt</status_messages_url>
</automation-run>
HTTPS Request
GET /automation_runs/{id}
Authentication Required
Available to all authenticated keys or sessions.
Request Parameters
Parameter | Description |
---|---|
id int64 Required | Automation Run 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"
}
<?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>
</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 |
List Bandwidth Snapshots
Example Request
curl "https://app.files.com/api/rest/v1/bandwidth_snapshots.json" \
-H 'X-FilesAPI-Key: YOUR_API_KEY'
curl "https://app.files.com/api/rest/v1/bandwidth_snapshots.xml" \
-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<>();
requestParams.put("per_page", 1);
BandwidthSnapshot.list(parameters).all()
await BandwidthSnapshot.list({
per_page: 1,
})
var parameters = new Dictionary<string, object>();
parameters.Add("per_page", (Int64?) 1);
await BandwidthSnapshot.List(parameters).All();
files_sdk.set_api_key("my-key")
files_sdk.bandwidth_snapshot.list({
"per_page": 1
})
files_sdk.APIKey = "YOUR_API_KEY"
bandwidthsnapshot.List(context.Background(), files_sdk.BandwidthSnapshotListParams{
Cursor: "",
PerPage: 1,
SortBy: "",
Filter: "",
FilterGt: "",
FilterGteq: "",
FilterLt: "",
FilterLteq: "",
})
files-cli bandwidth-snapshots list \
--cursor="" \
--per-page=1 \
--api-key=YOUR_API_KEY
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"
}
]
<?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>
</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
No request parameters available for this endpoint.
Pagination Params
Read more about Paginating List Requests.
Available Fields for Sorting
Read more about Sorting List Requests
Parameter | Description |
---|---|
sort_by object | If set, sort records by the specified field in either asc or desc direction (e.g. sort_by[logged_at]=desc ). Valid fields are logged_at . |
Available Filters
Read more about Filtering List Requests
Parameter | Description |
---|---|
filter object | If set, return records where the specified field is equal to the supplied value. Valid fields are logged_at . |
filter_gt object | If set, return records where the specified field is greater than the supplied value. Valid fields are logged_at . |
filter_gteq object | If set, return records where the specified field is greater than or equal the supplied value. Valid fields are logged_at . |
filter_lt object | If set, return records where the specified field is less than the supplied value. Valid fields are logged_at . |
filter_lteq object | If set, return records where the specified field is less than or equal 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 Behaviors
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. |
Value Hash Parameter | Description |
---|---|
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 . |
triggering_filenames | Leave blank to trigger webhooks on any file in this folder. Or you may specify an array of filenames (possibly with wildcards) to match for action path. |
encoding | May be JSON , XML , RAW , EV1 , or EV2 . 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. If set to EV1, we will encode the payload to emulate ExaVault's version 1 webhook format. If set to EV2, we will encode the payload to emulate ExaVault's version 2.0 webhook format. |
headers | Hash of HTTP Headers to send. |
body | Hash of Body Params to send |
verification_token | If provided, this token will be used to sign webhook messages cryptographically to allow you to verify the webhook authenticity. |
file_form_field | A string specifying the name of a form field containing the contents of the file that triggered this webhook send. If this value is present, the webhook will submit a multipart/form-data POST with no request body encoding. |
file_as_body | When sending webhook requests, submit the contents of the file that triggered this webhook send as the request body. |
use_dedicated_ips | If set to true, we will send webhooks from dedicated IPs. This is useful if you need to whitelist IPs for your webhook endpoint. |
curl https://app.files.com/api/rest/v1/behaviors.json -X POST -H 'Content-Type: application/json' -d '{"value": "{\"urls\":[\"https://mysite.com/url...\"],\"method\":\"POST\",\"triggers\":[\"create\",\"read\",\"update\",\"destroy\",\"move\",\"copy\"],\"triggering_filenames\":[\"*.pdf\",\"*so*.jpg\"],\"encoding\":\"RAW\",\"headers\":{\"MY-HEADER\":\"foo\"},\"body\":{\"MY_BODY_PARAM\":\"bar\"},\"verification_token\":\"tok12345\",\"file_form_field\":\"my_form_field\",\"file_as_body\":\"my_file_body\",\"use_dedicated_ips\":false}", "behavior": "webhook", "path": "/foo/bar" }' -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>
<behavior>
webhook
</behavior>
<path>/foo/bar</path>
<value>
{"urls":["https://mysite.com/url..."],"method":"POST","triggers":["create","read","update","destroy","move","copy"],"triggering_filenames":["*.pdf","*so*.jpg"],"encoding":"RAW","headers":{"MY-HEADER":"foo"},"body":{"MY_BODY_PARAM":"bar"},"verification_token":"tok12345","file_form_field":"my_form_field","file_as_body":"my_file_body","use_dedicated_ips":false}
</value>
</behavior>'
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::Behavior.create(
value: "{\"urls\":[\"https://mysite.com/url...\"],\"method\":\"POST\",\"triggers\":[\"create\",\"read\",\"update\",\"destroy\",\"move\",\"copy\"],\"triggering_filenames\":[\"*.pdf\",\"*so*.jpg\"],\"encoding\":\"RAW\",\"headers\":{\"MY-HEADER\":\"foo\"},\"body\":{\"MY_BODY_PARAM\":\"bar\"},\"verification_token\":\"tok12345\",\"file_form_field\":\"my_form_field\",\"file_as_body\":\"my_file_body\",\"use_dedicated_ips\":false}",
path: "path",
behavior: "webhook"
)
\Files\Model\Behavior::create(array(
'value' => "{\"urls\":[\"https://mysite.com/url...\"],\"method\":\"POST\",\"triggers\":[\"create\",\"read\",\"update\",\"destroy\",\"move\",\"copy\"],\"triggering_filenames\":[\"*.pdf\",\"*so*.jpg\"],\"encoding\":\"RAW\",\"headers\":{\"MY-HEADER\":\"foo\"},\"body\":{\"MY_BODY_PARAM\":\"bar\"},\"verification_token\":\"tok12345\",\"file_form_field\":\"my_form_field\",\"file_as_body\":\"my_file_body\",\"use_dedicated_ips\":false}",
'path' => "path",
'behavior' => "webhook"
));
HashMap<Object, String> requestParams = new HashMap<>();
requestParams.put("path", path);
requestParams.put("behavior", "webhook");
requestParams.put("value", {"urls":["https://mysite.com/url..."],"method":"POST","triggers":["create","read","update","destroy","move","copy"],"triggering_filenames":["*.pdf","*so*.jpg"],"encoding":"RAW","headers":{"MY-HEADER":"foo"},"body":{"MY_BODY_PARAM":"bar"},"verification_token":"tok12345","file_form_field":"my_form_field","file_as_body":"my_file_body","use_dedicated_ips":false});
Behavior.create(requestParams);
await Behavior.create({
value: "{\"urls\":[\"https://mysite.com/url...\"],\"method\":\"POST\",\"triggers\":[\"create\",\"read\",\"update\",\"destroy\",\"move\",\"copy\"],\"triggering_filenames\":[\"*.pdf\",\"*so*.jpg\"],\"encoding\":\"RAW\",\"headers\":{\"MY-HEADER\":\"foo\"},\"body\":{\"MY_BODY_PARAM\":\"bar\"},\"verification_token\":\"tok12345\",\"file_form_field\":\"my_form_field\",\"file_as_body\":\"my_file_body\",\"use_dedicated_ips\":false}",
path: "path",
behavior: "webhook",
})
var parameters = new Dictionary<string, object>();
parameters.Add("value", "{\"urls\":[\"https://mysite.com/url...\"],\"method\":\"POST\",\"triggers\":[\"create\",\"read\",\"update\",\"destroy\",\"move\",\"copy\"],\"triggering_filenames\":[\"*.pdf\",\"*so*.jpg\"],\"encoding\":\"RAW\",\"headers\":{\"MY-HEADER\":\"foo\"},\"body\":{\"MY_BODY_PARAM\":\"bar\"},\"verification_token\":\"tok12345\",\"file_form_field\":\"my_form_field\",\"file_as_body\":\"my_file_body\",\"use_dedicated_ips\":false}");
parameters.Add("path", "path");
parameters.Add("behavior", "webhook");
Behavior.Create(parameters);
files_sdk.set_api_key("my-key")
files_sdk.behavior.create({
"value": "{\"urls\":[\"https://mysite.com/url...\"],\"method\":\"POST\",\"triggers\":[\"create\",\"read\",\"update\",\"destroy\",\"move\",\"copy\"],\"triggering_filenames\":[\"*.pdf\",\"*so*.jpg\"],\"encoding\":\"RAW\",\"headers\":{\"MY-HEADER\":\"foo\"},\"body\":{\"MY_BODY_PARAM\":\"bar\"},\"verification_token\":\"tok12345\",\"file_form_field\":\"my_form_field\",\"file_as_body\":\"my_file_body\",\"use_dedicated_ips\":false}",
"path": "path",
"behavior": "webhook"
})
files_sdk.APIKey = "YOUR_API_KEY"
behavior.Create(context.Background(), files_sdk.BehaviorCreateParams{
Value: []string{`{"urls":["https://mysite.com/url..."],"method":"POST","triggers":["create","read","update","destroy","move","copy"],"triggering_filenames":["*.pdf","*so*.jpg"],"encoding":"RAW","headers":{"MY-HEADER":"foo"},"body":{"MY_BODY_PARAM":"bar"},"verification_token":"tok12345","file_form_field":"my_form_field","file_as_body":"my_file_body","use_dedicated_ips":false}`},
Path: "path",
Behavior: "webhook",
})
files-cli behaviors create \
--value='{\"urls\":[\"https://mysite.com/url...\"],\"method\":\"POST\",\"triggers\":[\"create\",\"read\",\"update\",\"destroy\",\"move\",\"copy\"],\"triggering_filenames\":[\"*.pdf\",\"*so*.jpg\"],\"encoding\":\"RAW\",\"headers\":{\"MY-HEADER\":\"foo\"},\"body\":{\"MY_BODY_PARAM\":\"bar\"},\"verification_token\":\"tok12345\",\"file_form_field\":\"my_form_field\",\"file_as_body\":\"my_file_body\",\"use_dedicated_ips\":false}' \
--path="path" \
--behavior="webhook" \
--api-key=YOUR_API_KEY
File Expiration Behaviors
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. |
This behavior type takes a single unnamed argument.
curl https://app.files.com/api/rest/v1/behaviors.json -X POST -H 'Content-Type: application/json' -d '{"value": "30", "behavior": "file_expiration", "path": "/foo/bar" }' -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>
<behavior>
file_expiration
</behavior>
<path>/foo/bar</path>
<value>
30
</value>
</behavior>'
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::Behavior.create(
value: "30",
path: "path",
behavior: "file_expiration"
)
\Files\Model\Behavior::create(array(
'value' => "30",
'path' => "path",
'behavior' => "file_expiration"
));
HashMap<Object, String> requestParams = new HashMap<>();
requestParams.put("path", path);
requestParams.put("behavior", "file_expiration");
requestParams.put("value", 30);
Behavior.create(requestParams);
await Behavior.create({
value: "30",
path: "path",
behavior: "file_expiration",
})
var parameters = new Dictionary<string, object>();
parameters.Add("value", "30");
parameters.Add("path", "path");
parameters.Add("behavior", "file_expiration");
Behavior.Create(parameters);
files_sdk.set_api_key("my-key")
files_sdk.behavior.create({
"value": "30",
"path": "path",
"behavior": "file_expiration"
})
files_sdk.APIKey = "YOUR_API_KEY"
behavior.Create(context.Background(), files_sdk.BehaviorCreateParams{
Value: []string{`30`},
Path: "path",
Behavior: "file_expiration",
})
files-cli behaviors create \
--value='30' \
--path="path" \
--behavior="file_expiration" \
--api-key=YOUR_API_KEY
Auto Encrypt Behaviors
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. |
Value Hash Parameter | Description |
---|---|
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. |
gpg_key_id | Your GPG Key ID object to use for this encrypt |
curl https://app.files.com/api/rest/v1/behaviors.json -X POST -H 'Content-Type: application/json' -d '{"value": "{\"algorithm\":\"PGP/GPG\",\"suffix\":\".gpg\",\"key\":\"[your GPG public key]\",\"armor\":false,\"gpg_key_id\":1}", "behavior": "auto_encrypt", "path": "/foo/bar" }' -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>
<behavior>
auto_encrypt
</behavior>
<path>/foo/bar</path>
<value>
{"algorithm":"PGP/GPG","suffix":".gpg","key":"[your GPG public key]","armor":false,"gpg_key_id":1}
</value>
</behavior>'
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::Behavior.create(
value: "{\"algorithm\":\"PGP/GPG\",\"suffix\":\".gpg\",\"key\":\"[your GPG public key]\",\"armor\":false,\"gpg_key_id\":1}",
path: "path",
behavior: "auto_encrypt"
)
\Files\Model\Behavior::create(array(
'value' => "{\"algorithm\":\"PGP/GPG\",\"suffix\":\".gpg\",\"key\":\"[your GPG public key]\",\"armor\":false,\"gpg_key_id\":1}",
'path' => "path",
'behavior' => "auto_encrypt"
));
HashMap<Object, String> requestParams = new HashMap<>();
requestParams.put("path", path);
requestParams.put("behavior", "auto_encrypt");
requestParams.put("value", {"algorithm":"PGP/GPG","suffix":".gpg","key":"[your GPG public key]","armor":false,"gpg_key_id":1});
Behavior.create(requestParams);
await Behavior.create({
value: "{\"algorithm\":\"PGP/GPG\",\"suffix\":\".gpg\",\"key\":\"[your GPG public key]\",\"armor\":false,\"gpg_key_id\":1}",
path: "path",
behavior: "auto_encrypt",
})
var parameters = new Dictionary<string, object>();
parameters.Add("value", "{\"algorithm\":\"PGP/GPG\",\"suffix\":\".gpg\",\"key\":\"[your GPG public key]\",\"armor\":false,\"gpg_key_id\":1}");
parameters.Add("path", "path");
parameters.Add("behavior", "auto_encrypt");
Behavior.Create(parameters);
files_sdk.set_api_key("my-key")
files_sdk.behavior.create({
"value": "{\"algorithm\":\"PGP/GPG\",\"suffix\":\".gpg\",\"key\":\"[your GPG public key]\",\"armor\":false,\"gpg_key_id\":1}",
"path": "path",
"behavior": "auto_encrypt"
})
files_sdk.APIKey = "YOUR_API_KEY"
behavior.Create(context.Background(), files_sdk.BehaviorCreateParams{
Value: []string{`{"algorithm":"PGP/GPG","suffix":".gpg","key":"[your GPG public key]","armor":false,"gpg_key_id":1}`},
Path: "path",
Behavior: "auto_encrypt",
})
files-cli behaviors create \
--value='{\"algorithm\":\"PGP/GPG\",\"suffix\":\".gpg\",\"key\":\"[your GPG public key]\",\"armor\":false,\"gpg_key_id\":1}' \
--path="path" \
--behavior="auto_encrypt" \
--api-key=YOUR_API_KEY
Lock Subfolders Behaviors
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. |
Value Hash Parameter | Description |
---|---|
level | URL key used for the inbox. Can be children_recursive (default), children , self , or none . |
curl https://app.files.com/api/rest/v1/behaviors.json -X POST -H 'Content-Type: application/json' -d '{"value": "{\"level\":\"children_recursive\"}", "behavior": "lock_subfolders", "path": "/foo/bar" }' -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>
<behavior>
lock_subfolders
</behavior>
<path>/foo/bar</path>
<value>
{"level":"children_recursive"}
</value>
</behavior>'
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::Behavior.create(
value: "{\"level\":\"children_recursive\"}",
path: "path",
behavior: "lock_subfolders"
)
\Files\Model\Behavior::create(array(
'value' => "{\"level\":\"children_recursive\"}",
'path' => "path",
'behavior' => "lock_subfolders"
));
HashMap<Object, String> requestParams = new HashMap<>();
requestParams.put("path", path);
requestParams.put("behavior", "lock_subfolders");
requestParams.put("value", {"level":"children_recursive"});
Behavior.create(requestParams);
await Behavior.create({
value: "{\"level\":\"children_recursive\"}",
path: "path",
behavior: "lock_subfolders",
})
var parameters = new Dictionary<string, object>();
parameters.Add("value", "{\"level\":\"children_recursive\"}");
parameters.Add("path", "path");
parameters.Add("behavior", "lock_subfolders");
Behavior.Create(parameters);
files_sdk.set_api_key("my-key")
files_sdk.behavior.create({
"value": "{\"level\":\"children_recursive\"}",
"path": "path",
"behavior": "lock_subfolders"
})
files_sdk.APIKey = "YOUR_API_KEY"
behavior.Create(context.Background(), files_sdk.BehaviorCreateParams{
Value: []string{`{"level":"children_recursive"}`},
Path: "path",
Behavior: "lock_subfolders",
})
files-cli behaviors create \
--value='{\"level\":\"children_recursive\"}' \
--path="path" \
--behavior="lock_subfolders" \
--api-key=YOUR_API_KEY
Storage Region Behaviors
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. |
This behavior type takes a single unnamed argument.
curl https://app.files.com/api/rest/v1/behaviors.json -X POST -H 'Content-Type: application/json' -d '{"value": "\"us-east-1\"", "behavior": "storage_region", "path": "/foo/bar" }' -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>
<behavior>
storage_region
</behavior>
<path>/foo/bar</path>
<value>
"us-east-1"
</value>
</behavior>'
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::Behavior.create(
value: "\"us-east-1\"",
path: "path",
behavior: "storage_region"
)
\Files\Model\Behavior::create(array(
'value' => "\"us-east-1\"",
'path' => "path",
'behavior' => "storage_region"
));
HashMap<Object, String> requestParams = new HashMap<>();
requestParams.put("path", path);
requestParams.put("behavior", "storage_region");
requestParams.put("value", "us-east-1");
Behavior.create(requestParams);
await Behavior.create({
value: "\"us-east-1\"",
path: "path",
behavior: "storage_region",
})
var parameters = new Dictionary<string, object>();
parameters.Add("value", "\"us-east-1\"");
parameters.Add("path", "path");
parameters.Add("behavior", "storage_region");
Behavior.Create(parameters);
files_sdk.set_api_key("my-key")
files_sdk.behavior.create({
"value": "\"us-east-1\"",
"path": "path",
"behavior": "storage_region"
})
files_sdk.APIKey = "YOUR_API_KEY"
behavior.Create(context.Background(), files_sdk.BehaviorCreateParams{
Value: []string{`"us-east-1"`},
Path: "path",
Behavior: "storage_region",
})
files-cli behaviors create \
--value='\"us-east-1\"' \
--path="path" \
--behavior="storage_region" \
--api-key=YOUR_API_KEY
Serve Publicly Behaviors
Behavior Details | |
---|---|
Behavior type | serve_publicly |
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. |
Value Hash Parameter | Description |
---|---|
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? |
curl https://app.files.com/api/rest/v1/behaviors.json -X POST -H 'Content-Type: application/json' -d '{"value": "{\"key\":\"public-photos\",\"show_index\":true}", "behavior": "serve_publicly", "path": "/foo/bar" }' -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>
<behavior>
serve_publicly
</behavior>
<path>/foo/bar</path>
<value>
{"key":"public-photos","show_index":true}
</value>
</behavior>'
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::Behavior.create(
value: "{\"key\":\"public-photos\",\"show_index\":true}",
path: "path",
behavior: "serve_publicly"
)
\Files\Model\Behavior::create(array(
'value' => "{\"key\":\"public-photos\",\"show_index\":true}",
'path' => "path",
'behavior' => "serve_publicly"
));
HashMap<Object, String> requestParams = new HashMap<>();
requestParams.put("path", path);
requestParams.put("behavior", "serve_publicly");
requestParams.put("value", {"key":"public-photos","show_index":true});
Behavior.create(requestParams);
await Behavior.create({
value: "{\"key\":\"public-photos\",\"show_index\":true}",
path: "path",
behavior: "serve_publicly",
})
var parameters = new Dictionary<string, object>();
parameters.Add("value", "{\"key\":\"public-photos\",\"show_index\":true}");
parameters.Add("path", "path");
parameters.Add("behavior", "serve_publicly");
Behavior.Create(parameters);
files_sdk.set_api_key("my-key")
files_sdk.behavior.create({
"value": "{\"key\":\"public-photos\",\"show_index\":true}",
"path": "path",
"behavior": "serve_publicly"
})
files_sdk.APIKey = "YOUR_API_KEY"
behavior.Create(context.Background(), files_sdk.BehaviorCreateParams{
Value: []string{`{"key":"public-photos","show_index":true}`},
Path: "path",
Behavior: "serve_publicly",
})
files-cli behaviors create \
--value='{\"key\":\"public-photos\",\"show_index\":true}' \
--path="path" \
--behavior="serve_publicly" \
--api-key=YOUR_API_KEY
Create User Folders Behaviors
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. |
Value Hash Parameter | Description |
---|---|
permission | What permission level to give the user on his or her new folder? Takes the same options as the Permissions endpoint. |
additional_permission | Additional permission level to give the user on his or her new folder. Used to apply a second permission. 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' |
subfolders | Subfolders to create within the new folder |
curl https://app.files.com/api/rest/v1/behaviors.json -X POST -H 'Content-Type: application/json' -d '{"value": "{\"permission\":\"full\",\"additional_permission\":\"bundle\",\"existing_users\":true,\"group_id\":1,\"new_folder_name\":\"username\",\"subfolders\":[\"in\",\"out\"]}", "behavior": "create_user_folders", "path": "/foo/bar" }' -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>
<behavior>
create_user_folders
</behavior>
<path>/foo/bar</path>
<value>
{"permission":"full","additional_permission":"bundle","existing_users":true,"group_id":1,"new_folder_name":"username","subfolders":["in","out"]}
</value>
</behavior>'
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::Behavior.create(
value: "{\"permission\":\"full\",\"additional_permission\":\"bundle\",\"existing_users\":true,\"group_id\":1,\"new_folder_name\":\"username\",\"subfolders\":[\"in\",\"out\"]}",
path: "path",
behavior: "create_user_folders"
)
\Files\Model\Behavior::create(array(
'value' => "{\"permission\":\"full\",\"additional_permission\":\"bundle\",\"existing_users\":true,\"group_id\":1,\"new_folder_name\":\"username\",\"subfolders\":[\"in\",\"out\"]}",
'path' => "path",
'behavior' => "create_user_folders"
));
HashMap<Object, String> requestParams = new HashMap<>();
requestParams.put("path", path);
requestParams.put("behavior", "create_user_folders");
requestParams.put("value", {"permission":"full","additional_permission":"bundle","existing_users":true,"group_id":1,"new_folder_name":"username","subfolders":["in","out"]});
Behavior.create(requestParams);
await Behavior.create({
value: "{\"permission\":\"full\",\"additional_permission\":\"bundle\",\"existing_users\":true,\"group_id\":1,\"new_folder_name\":\"username\",\"subfolders\":[\"in\",\"out\"]}",
path: "path",
behavior: "create_user_folders",
})
var parameters = new Dictionary<string, object>();
parameters.Add("value", "{\"permission\":\"full\",\"additional_permission\":\"bundle\",\"existing_users\":true,\"group_id\":1,\"new_folder_name\":\"username\",\"subfolders\":[\"in\",\"out\"]}");
parameters.Add("path", "path");
parameters.Add("behavior", "create_user_folders");
Behavior.Create(parameters);
files_sdk.set_api_key("my-key")
files_sdk.behavior.create({
"value": "{\"permission\":\"full\",\"additional_permission\":\"bundle\",\"existing_users\":true,\"group_id\":1,\"new_folder_name\":\"username\",\"subfolders\":[\"in\",\"out\"]}",
"path": "path",
"behavior": "create_user_folders"
})
files_sdk.APIKey = "YOUR_API_KEY"
behavior.Create(context.Background(), files_sdk.BehaviorCreateParams{
Value: []string{`{"permission":"full","additional_permission":"bundle","existing_users":true,"group_id":1,"new_folder_name":"username","subfolders":["in","out"]}`},
Path: "path",
Behavior: "create_user_folders",
})
files-cli behaviors create \
--value='{\"permission\":\"full\",\"additional_permission\":\"bundle\",\"existing_users\":true,\"group_id\":1,\"new_folder_name\":\"username\",\"subfolders\":[\"in\",\"out\"]}' \
--path="path" \
--behavior="create_user_folders" \
--api-key=YOUR_API_KEY
Remote Server Sync Behaviors
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. |
Value Hash Parameter | Description |
---|---|
direction | One way or two way sync? Valid values: push_to_server , pull_from_server , two_way |
disabled | If true, this sync will not be run automatically. Useful for disabling syncs during testing. |
keep_after_copy | If one-way syncing, should we delete or keep files after sync? |
manual | If false , this sync will run automatically via the built in scheduler for syncs (default). If true , this sync will not run automatically. A common reason to set this to true is if you intend to use a different scheduling mechanism such as a Webhook or email via an Automation. |
remote_path | Path on remote server to sync with. This should be an absolute path on the remote server. This must be slash-delimited, but it must neither start nor end with a slash. |
remote_server_id | ID of the remote server to sync with. See the Remote Servers API resource for managing these. |
trigger | How this remote sync is scheduled to run. One of: `(empty), daily, or custom_schedule. If left empty remote sync will be run on every remote_sync_interval` minutes. |
interval | If trigger type is recurring , this specifies how often to run this behavior. One of: day , week , week_end , month , month_end , quarter , quarter_end , year , year_end |
recurring_day | If trigger type is daily , this specifies the day of the month. |
schedule | If trigger type is custom_schedule , Custom schedule description for when the behavior should be run. |
delete_empty_folders | Applies only to one-way syncs. If true, we will remove empty folders on the source. This is a good way to clean up empty folders left by this sync or other automated processes. Note that the removal will occur on the subsequent sync run if the folder was non-empty at any point during the sync run. |
curl https://app.files.com/api/rest/v1/behaviors.json -X POST -H 'Content-Type: application/json' -d '{"value": "{\"direction\":\"two_way\",\"disabled\":false,\"keep_after_copy\":\"keep\",\"manual\":false,\"remote_path\":\"\",\"remote_server_id\":\"1\",\"trigger\":\"daily\",\"interval\":\"month\",\"recurring_day\":25,\"schedule\":{\"days_of_week\":[0,2,4],\"times_of_day\":[\"6:30\",\"14:30\"],\"time_zone\":\"Eastern Time (US & Canada)\"},\"delete_empty_folders\":false}", "behavior": "remote_server_sync", "path": "/foo/bar" }' -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>
<behavior>
remote_server_sync
</behavior>
<path>/foo/bar</path>
<value>
{"direction":"two_way","disabled":false,"keep_after_copy":"keep","manual":false,"remote_path":"","remote_server_id":"1","trigger":"daily","interval":"month","recurring_day":25,"schedule":{"days_of_week":[0,2,4],"times_of_day":["6:30","14:30"],"time_zone":"Eastern Time (US & Canada)"},"delete_empty_folders":false}
</value>
</behavior>'
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::Behavior.create(
value: "{\"direction\":\"two_way\",\"disabled\":false,\"keep_after_copy\":\"keep\",\"manual\":false,\"remote_path\":\"\",\"remote_server_id\":\"1\",\"trigger\":\"daily\",\"interval\":\"month\",\"recurring_day\":25,\"schedule\":{\"days_of_week\":[0,2,4],\"times_of_day\":[\"6:30\",\"14:30\"],\"time_zone\":\"Eastern Time (US & Canada)\"},\"delete_empty_folders\":false}",
path: "path",
behavior: "remote_server_sync"
)
\Files\Model\Behavior::create(array(
'value' => "{\"direction\":\"two_way\",\"disabled\":false,\"keep_after_copy\":\"keep\",\"manual\":false,\"remote_path\":\"\",\"remote_server_id\":\"1\",\"trigger\":\"daily\",\"interval\":\"month\",\"recurring_day\":25,\"schedule\":{\"days_of_week\":[0,2,4],\"times_of_day\":[\"6:30\",\"14:30\"],\"time_zone\":\"Eastern Time (US & Canada)\"},\"delete_empty_folders\":false}",
'path' => "path",
'behavior' => "remote_server_sync"
));
HashMap<Object, String> requestParams = new HashMap<>();
requestParams.put("path", path);
requestParams.put("behavior", "remote_server_sync");
requestParams.put("value", {"direction":"two_way","disabled":false,"keep_after_copy":"keep","manual":false,"remote_path":"","remote_server_id":"1","trigger":"daily","interval":"month","recurring_day":25,"schedule":{"days_of_week":[0,2,4],"times_of_day":["6:30","14:30"],"time_zone":"Eastern Time (US & Canada)"},"delete_empty_folders":false});
Behavior.create(requestParams);
await Behavior.create({
value: "{\"direction\":\"two_way\",\"disabled\":false,\"keep_after_copy\":\"keep\",\"manual\":false,\"remote_path\":\"\",\"remote_server_id\":\"1\",\"trigger\":\"daily\",\"interval\":\"month\",\"recurring_day\":25,\"schedule\":{\"days_of_week\":[0,2,4],\"times_of_day\":[\"6:30\",\"14:30\"],\"time_zone\":\"Eastern Time (US & Canada)\"},\"delete_empty_folders\":false}",
path: "path",
behavior: "remote_server_sync",
})
var parameters = new Dictionary<string, object>();
parameters.Add("value", "{\"direction\":\"two_way\",\"disabled\":false,\"keep_after_copy\":\"keep\",\"manual\":false,\"remote_path\":\"\",\"remote_server_id\":\"1\",\"trigger\":\"daily\",\"interval\":\"month\",\"recurring_day\":25,\"schedule\":{\"days_of_week\":[0,2,4],\"times_of_day\":[\"6:30\",\"14:30\"],\"time_zone\":\"Eastern Time (US & Canada)\"},\"delete_empty_folders\":false}");
parameters.Add("path", "path");
parameters.Add("behavior", "remote_server_sync");
Behavior.Create(parameters);
files_sdk.set_api_key("my-key")
files_sdk.behavior.create({
"value": "{\"direction\":\"two_way\",\"disabled\":false,\"keep_after_copy\":\"keep\",\"manual\":false,\"remote_path\":\"\",\"remote_server_id\":\"1\",\"trigger\":\"daily\",\"interval\":\"month\",\"recurring_day\":25,\"schedule\":{\"days_of_week\":[0,2,4],\"times_of_day\":[\"6:30\",\"14:30\"],\"time_zone\":\"Eastern Time (US & Canada)\"},\"delete_empty_folders\":false}",
"path": "path",
"behavior": "remote_server_sync"
})
files_sdk.APIKey = "YOUR_API_KEY"
behavior.Create(context.Background(), files_sdk.BehaviorCreateParams{
Value: []string{`{"direction":"two_way","disabled":false,"keep_after_copy":"keep","manual":false,"remote_path":"","remote_server_id":"1","trigger":"daily","interval":"month","recurring_day":25,"schedule":{"days_of_week":[0,2,4],"times_of_day":["6:30","14:30"],"time_zone":"Eastern Time (US & Canada)"},"delete_empty_folders":false}`},
Path: "path",
Behavior: "remote_server_sync",
})
files-cli behaviors create \
--value='{\"direction\":\"two_way\",\"disabled\":false,\"keep_after_copy\":\"keep\",\"manual\":false,\"remote_path\":\"\",\"remote_server_id\":\"1\",\"trigger\":\"daily\",\"interval\":\"month\",\"recurring_day\":25,\"schedule\":{\"days_of_week\":[0,2,4],\"times_of_day\":[\"6:30\",\"14:30\"],\"time_zone\":\"Eastern Time (US & Canada)\"},\"delete_empty_folders\":false}' \
--path="path" \
--behavior="remote_server_sync" \
--api-key=YOUR_API_KEY
Inbox Behaviors
Behavior Details | |
---|---|
Behavior type | inbox |
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. |
Value Hash Parameter | Description |
---|---|
key | URL key used for the inbox. May only contain lowercase alphabetic characters, numbers, and dashes. |
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. |
dont_allow_folders_in_uploads | If set to true , will prevent folders from being created inside an inbox submission. Useful for certain automation use cases where nested folders don't work well. |
require_inbox_recipient | If set to true , requires that the inbox be shared with specific recipients rather than being accessed via a URL directly. |
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. |
path_template | Template for creating submission subfolders. Can use the uploader's name, email address, ip, company, and any custom form data. |
enable_inbound_email_address | This is only used when creating/updating a behavior. If set to true , will generate inbound_email_address to this folder. If set to false , will remove inbound_email_address to this folder. Please note that the uploads via email doesn't work if require_registration or password options are set to true. |
notify_senders_on_successful_uploads_via_email | Notify senders on successful uploads via email |
allow_whitelisting | allow/disallow whitelist |
whitelist | Comma-separated string of whitelisted email addresses and domains |
curl https://app.files.com/api/rest/v1/behaviors.json -X POST -H 'Content-Type: application/json' -d '{"value": "{\"key\":\"application-forms\",\"dont_separate_submissions_by_folder\":true,\"dont_allow_folders_in_uploads\":false,\"require_inbox_recipient\":false,\"show_on_login_page\":true,\"title\":\"Submit Your Job Applications Here\",\"description\":\"Thanks for coming to the Files.com Job Application Page\",\"help_text\":\"If you have trouble here, please contact your recruiter.\",\"require_registration\":true,\"password\":\"foobar\",\"path_template\":\"{{name}}_{{ip}}\",\"enable_inbound_email_address\":true,\"notify_senders_on_successful_uploads_via_email\":true,\"allow_whitelisting\":true,\"whitelist\":[\"john@test.com\",\"mydomain.com\"]}", "behavior": "inbox", "path": "/foo/bar" }' -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>
<behavior>
inbox
</behavior>
<path>/foo/bar</path>
<value>
{"key":"application-forms","dont_separate_submissions_by_folder":true,"dont_allow_folders_in_uploads":false,"require_inbox_recipient":false,"show_on_login_page":true,"title":"Submit Your Job Applications Here","description":"Thanks for coming to the Files.com Job Application Page","help_text":"If you have trouble here, please contact your recruiter.","require_registration":true,"password":"foobar","path_template":"{{name}}_{{ip}}","enable_inbound_email_address":true,"notify_senders_on_successful_uploads_via_email":true,"allow_whitelisting":true,"whitelist":["john@test.com","mydomain.com"]}
</value>
</behavior>'
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::Behavior.create(
value: "{\"key\":\"application-forms\",\"dont_separate_submissions_by_folder\":true,\"dont_allow_folders_in_uploads\":false,\"require_inbox_recipient\":false,\"show_on_login_page\":true,\"title\":\"Submit Your Job Applications Here\",\"description\":\"Thanks for coming to the Files.com Job Application Page\",\"help_text\":\"If you have trouble here, please contact your recruiter.\",\"require_registration\":true,\"password\":\"foobar\",\"path_template\":\"{{name}}_{{ip}}\",\"enable_inbound_email_address\":true,\"notify_senders_on_successful_uploads_via_email\":true,\"allow_whitelisting\":true,\"whitelist\":[\"john@test.com\",\"mydomain.com\"]}",
path: "path",
behavior: "inbox"
)
\Files\Model\Behavior::create(array(
'value' => "{\"key\":\"application-forms\",\"dont_separate_submissions_by_folder\":true,\"dont_allow_folders_in_uploads\":false,\"require_inbox_recipient\":false,\"show_on_login_page\":true,\"title\":\"Submit Your Job Applications Here\",\"description\":\"Thanks for coming to the Files.com Job Application Page\",\"help_text\":\"If you have trouble here, please contact your recruiter.\",\"require_registration\":true,\"password\":\"foobar\",\"path_template\":\"{{name}}_{{ip}}\",\"enable_inbound_email_address\":true,\"notify_senders_on_successful_uploads_via_email\":true,\"allow_whitelisting\":true,\"whitelist\":[\"john@test.com\",\"mydomain.com\"]}",
'path' => "path",
'behavior' => "inbox"
));
HashMap<Object, String> requestParams = new HashMap<>();
requestParams.put("path", path);
requestParams.put("behavior", "inbox");
requestParams.put("value", {"key":"application-forms","dont_separate_submissions_by_folder":true,"dont_allow_folders_in_uploads":false,"require_inbox_recipient":false,"show_on_login_page":true,"title":"Submit Your Job Applications Here","description":"Thanks for coming to the Files.com Job Application Page","help_text":"If you have trouble here, please contact your recruiter.","require_registration":true,"password":"foobar","path_template":"{{name}}_{{ip}}","enable_inbound_email_address":true,"notify_senders_on_successful_uploads_via_email":true,"allow_whitelisting":true,"whitelist":["john@test.com","mydomain.com"]});
Behavior.create(requestParams);
await Behavior.create({
value: "{\"key\":\"application-forms\",\"dont_separate_submissions_by_folder\":true,\"dont_allow_folders_in_uploads\":false,\"require_inbox_recipient\":false,\"show_on_login_page\":true,\"title\":\"Submit Your Job Applications Here\",\"description\":\"Thanks for coming to the Files.com Job Application Page\",\"help_text\":\"If you have trouble here, please contact your recruiter.\",\"require_registration\":true,\"password\":\"foobar\",\"path_template\":\"{{name}}_{{ip}}\",\"enable_inbound_email_address\":true,\"notify_senders_on_successful_uploads_via_email\":true,\"allow_whitelisting\":true,\"whitelist\":[\"john@test.com\",\"mydomain.com\"]}",
path: "path",
behavior: "inbox",
})
var parameters = new Dictionary<string, object>();
parameters.Add("value", "{\"key\":\"application-forms\",\"dont_separate_submissions_by_folder\":true,\"dont_allow_folders_in_uploads\":false,\"require_inbox_recipient\":false,\"show_on_login_page\":true,\"title\":\"Submit Your Job Applications Here\",\"description\":\"Thanks for coming to the Files.com Job Application Page\",\"help_text\":\"If you have trouble here, please contact your recruiter.\",\"require_registration\":true,\"password\":\"foobar\",\"path_template\":\"{{name}}_{{ip}}\",\"enable_inbound_email_address\":true,\"notify_senders_on_successful_uploads_via_email\":true,\"allow_whitelisting\":true,\"whitelist\":[\"john@test.com\",\"mydomain.com\"]}");
parameters.Add("path", "path");
parameters.Add("behavior", "inbox");
Behavior.Create(parameters);
files_sdk.set_api_key("my-key")
files_sdk.behavior.create({
"value": "{\"key\":\"application-forms\",\"dont_separate_submissions_by_folder\":true,\"dont_allow_folders_in_uploads\":false,\"require_inbox_recipient\":false,\"show_on_login_page\":true,\"title\":\"Submit Your Job Applications Here\",\"description\":\"Thanks for coming to the Files.com Job Application Page\",\"help_text\":\"If you have trouble here, please contact your recruiter.\",\"require_registration\":true,\"password\":\"foobar\",\"path_template\":\"{{name}}_{{ip}}\",\"enable_inbound_email_address\":true,\"notify_senders_on_successful_uploads_via_email\":true,\"allow_whitelisting\":true,\"whitelist\":[\"john@test.com\",\"mydomain.com\"]}",
"path": "path",
"behavior": "inbox"
})
files_sdk.APIKey = "YOUR_API_KEY"
behavior.Create(context.Background(), files_sdk.BehaviorCreateParams{
Value: []string{`{"key":"application-forms","dont_separate_submissions_by_folder":true,"dont_allow_folders_in_uploads":false,"require_inbox_recipient":false,"show_on_login_page":true,"title":"Submit Your Job Applications Here","description":"Thanks for coming to the Files.com Job Application Page","help_text":"If you have trouble here, please contact your recruiter.","require_registration":true,"password":"foobar","path_template":"{{name}}_{{ip}}","enable_inbound_email_address":true,"notify_senders_on_successful_uploads_via_email":true,"allow_whitelisting":true,"whitelist":["john@test.com","mydomain.com"]}`},
Path: "path",
Behavior: "inbox",
})
files-cli behaviors create \
--value='{\"key\":\"application-forms\",\"dont_separate_submissions_by_folder\":true,\"dont_allow_folders_in_uploads\":false,\"require_inbox_recipient\":false,\"show_on_login_page\":true,\"title\":\"Submit Your Job Applications Here\",\"description\":\"Thanks for coming to the Files.com Job Application Page\",\"help_text\":\"If you have trouble here, please contact your recruiter.\",\"require_registration\":true,\"password\":\"foobar\",\"path_template\":\"{{name}}_{{ip}}\",\"enable_inbound_email_address\":true,\"notify_senders_on_successful_uploads_via_email\":true,\"allow_whitelisting\":true,\"whitelist\":[\"john@test.com\",\"mydomain.com\"]}' \
--path="path" \
--behavior="inbox" \
--api-key=YOUR_API_KEY
Append Timestamp Behaviors
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. |
Value Hash Parameter | Description |
---|---|
format | Format for the timestamp. You may use anything accepted by the standard UNIX date command or strftime . |
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. |
curl https://app.files.com/api/rest/v1/behaviors.json -X POST -H 'Content-Type: application/json' -d '{"value": "{\"format\":\"-YYYY-MM-DDThh:mm:ssZ\",\"time_zone\":\"Eastern Time (US & Canada)\"}", "behavior": "append_timestamp", "path": "/foo/bar" }' -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>
<behavior>
append_timestamp
</behavior>
<path>/foo/bar</path>
<value>
{"format":"-YYYY-MM-DDThh:mm:ssZ","time_zone":"Eastern Time (US & Canada)"}
</value>
</behavior>'
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::Behavior.create(
value: "{\"format\":\"-YYYY-MM-DDThh:mm:ssZ\",\"time_zone\":\"Eastern Time (US & Canada)\"}",
path: "path",
behavior: "append_timestamp"
)
\Files\Model\Behavior::create(array(
'value' => "{\"format\":\"-YYYY-MM-DDThh:mm:ssZ\",\"time_zone\":\"Eastern Time (US & Canada)\"}",
'path' => "path",
'behavior' => "append_timestamp"
));
HashMap<Object, String> requestParams = new HashMap<>();
requestParams.put("path", path);
requestParams.put("behavior", "append_timestamp");
requestParams.put("value", {"format":"-YYYY-MM-DDThh:mm:ssZ","time_zone":"Eastern Time (US & Canada)"});
Behavior.create(requestParams);
await Behavior.create({
value: "{\"format\":\"-YYYY-MM-DDThh:mm:ssZ\",\"time_zone\":\"Eastern Time (US & Canada)\"}",
path: "path",
behavior: "append_timestamp",
})
var parameters = new Dictionary<string, object>();
parameters.Add("value", "{\"format\":\"-YYYY-MM-DDThh:mm:ssZ\",\"time_zone\":\"Eastern Time (US & Canada)\"}");
parameters.Add("path", "path");
parameters.Add("behavior", "append_timestamp");
Behavior.Create(parameters);
files_sdk.set_api_key("my-key")
files_sdk.behavior.create({
"value": "{\"format\":\"-YYYY-MM-DDThh:mm:ssZ\",\"time_zone\":\"Eastern Time (US & Canada)\"}",
"path": "path",
"behavior": "append_timestamp"
})
files_sdk.APIKey = "YOUR_API_KEY"
behavior.Create(context.Background(), files_sdk.BehaviorCreateParams{
Value: []string{`{"format":"-YYYY-MM-DDThh:mm:ssZ","time_zone":"Eastern Time (US & Canada)"}`},
Path: "path",
Behavior: "append_timestamp",
})
files-cli behaviors create \
--value='{\"format\":\"-YYYY-MM-DDThh:mm:ssZ\",\"time_zone\":\"Eastern Time (US & Canada)\"}' \
--path="path" \
--behavior="append_timestamp" \
--api-key=YOUR_API_KEY
Limit File Extensions Behaviors
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. Can be overridden by adding a behavior to the child. |
Value Hash Parameter | Description |
---|---|
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 . |
curl https://app.files.com/api/rest/v1/behaviors.json -X POST -H 'Content-Type: application/json' -d '{"value": "{\"extensions\":[\"xls\",\"csv\"],\"mode\":\"whitelist\"}", "behavior": "limit_file_extensions", "path": "/foo/bar" }' -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>
<behavior>
limit_file_extensions
</behavior>
<path>/foo/bar</path>
<value>
{"extensions":["xls","csv"],"mode":"whitelist"}
</value>
</behavior>'
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::Behavior.create(
value: "{\"extensions\":[\"xls\",\"csv\"],\"mode\":\"whitelist\"}",
path: "path",
behavior: "limit_file_extensions"
)
\Files\Model\Behavior::create(array(
'value' => "{\"extensions\":[\"xls\",\"csv\"],\"mode\":\"whitelist\"}",
'path' => "path",
'behavior' => "limit_file_extensions"
));
HashMap<Object, String> requestParams = new HashMap<>();
requestParams.put("path", path);
requestParams.put("behavior", "limit_file_extensions");
requestParams.put("value", {"extensions":["xls","csv"],"mode":"whitelist"});
Behavior.create(requestParams);
await Behavior.create({
value: "{\"extensions\":[\"xls\",\"csv\"],\"mode\":\"whitelist\"}",
path: "path",
behavior: "limit_file_extensions",
})
var parameters = new Dictionary<string, object>();
parameters.Add("value", "{\"extensions\":[\"xls\",\"csv\"],\"mode\":\"whitelist\"}");
parameters.Add("path", "path");
parameters.Add("behavior", "limit_file_extensions");
Behavior.Create(parameters);
files_sdk.set_api_key("my-key")
files_sdk.behavior.create({
"value": "{\"extensions\":[\"xls\",\"csv\"],\"mode\":\"whitelist\"}",
"path": "path",
"behavior": "limit_file_extensions"
})
files_sdk.APIKey = "YOUR_API_KEY"
behavior.Create(context.Background(), files_sdk.BehaviorCreateParams{
Value: []string{`{"extensions":["xls","csv"],"mode":"whitelist"}`},
Path: "path",
Behavior: "limit_file_extensions",
})
files-cli behaviors create \
--value='{\"extensions\":[\"xls\",\"csv\"],\"mode\":\"whitelist\"}' \
--path="path" \
--behavior="limit_file_extensions" \
--api-key=YOUR_API_KEY
Limit File Regex Behaviors
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. Can be overridden by adding a behavior to the child. |
This behavior type takes a single unnamed argument.
curl https://app.files.com/api/rest/v1/behaviors.json -X POST -H 'Content-Type: application/json' -d '{"value": "[\"/Document-.*/\"]", "behavior": "limit_file_regex", "path": "/foo/bar" }' -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>
<behavior>
limit_file_regex
</behavior>
<path>/foo/bar</path>
<value>
["/Document-.*/"]
</value>
</behavior>'
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::Behavior.create(
value: "[\"/Document-.*/\"]",
path: "path",
behavior: "limit_file_regex"
)
\Files\Model\Behavior::create(array(
'value' => "[\"/Document-.*/\"]",
'path' => "path",
'behavior' => "limit_file_regex"
));
HashMap<Object, String> requestParams = new HashMap<>();
requestParams.put("path", path);
requestParams.put("behavior", "limit_file_regex");
requestParams.put("value", ["/Document-.*/"]);
Behavior.create(requestParams);
await Behavior.create({
value: "[\"/Document-.*/\"]",
path: "path",
behavior: "limit_file_regex",
})
var parameters = new Dictionary<string, object>();
parameters.Add("value", "[\"/Document-.*/\"]");
parameters.Add("path", "path");
parameters.Add("behavior", "limit_file_regex");
Behavior.Create(parameters);
files_sdk.set_api_key("my-key")
files_sdk.behavior.create({
"value": "[\"/Document-.*/\"]",
"path": "path",
"behavior": "limit_file_regex"
})
files_sdk.APIKey = "YOUR_API_KEY"
behavior.Create(context.Background(), files_sdk.BehaviorCreateParams{
Value: []string{`["/Document-.*/"]`},
Path: "path",
Behavior: "limit_file_regex",
})
files-cli behaviors create \
--value='[\"/Document-.*/\"]' \
--path="path" \
--behavior="limit_file_regex" \
--api-key=YOUR_API_KEY
Amazon Sns Behaviors
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. |
Value Hash Parameter | Description |
---|---|
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 . |
curl https://app.files.com/api/rest/v1/behaviors.json -X POST -H 'Content-Type: application/json' -d '{"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\"}}", "behavior": "amazon_sns", "path": "/foo/bar" }' -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>
<behavior>
amazon_sns
</behavior>
<path>/foo/bar</path>
<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>
</behavior>'
-H 'X-FilesAPI-Key: YOUR_API_KEY'
Files.api_key = 'YOUR_API_KEY'
Files::Behavior.create(
value: "{\"arns\":[\"ARN\"],\"triggers\"