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 file
type - the MIME type of the file
encoded_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.

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.

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/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/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/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

Parameter	Description

Pagination Params

Read more about Paginating List Requests

Parameter	Description
cursor string	Used for pagination. When a list request has more records available, cursors are provided in the response headers `X-Files-Cursor-Next` and `X-Files-Cursor-Prev`. Send one of those cursor value here to resume an existing list from the next available record. Note: many of our SDKs have iterator methods that will automatically handle cursor-based pagination.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).

List Payments

Example Request

curl "https://app.files.com/api/rest/v1/payments.json" \
  -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

Parameter	Description

Pagination Params

Read more about Paginating List Requests

Parameter	Description
cursor string	Used for pagination. When a list request has more records available, cursors are provided in the response headers `X-Files-Cursor-Next` and `X-Files-Cursor-Prev`. Send one of those cursor value here to resume an existing list from the next available record. Note: many of our SDKs have iterator methods that will automatically handle cursor-based pagination.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).

Show Invoice

Example Request

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

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

Files.api_key = 'YOUR_API_KEY'

Files::Invoice.find(id)

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


Invoice.find(, 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

Parameter	Description
cursor string	Used for pagination. When a list request has more records available, cursors are provided in the response headers `X-Files-Cursor-Next` and `X-Files-Cursor-Prev`. Send one of those cursor value here to resume an existing list from the next available record. Note: many of our SDKs have iterator methods that will automatically handle cursor-based pagination.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).

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

Parameter	Description
cursor string	Used for pagination. When a list request has more records available, cursors are provided in the response headers `X-Files-Cursor-Next` and `X-Files-Cursor-Prev`. Send one of those cursor value here to resume an existing list from the next available record. Note: many of our SDKs have iterator methods that will automatically handle cursor-based pagination.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).

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

Parameter	Description
cursor string	Used for pagination. When a list request has more records available, cursors are provided in the response headers `X-Files-Cursor-Next` and `X-Files-Cursor-Prev`. Send one of those cursor value here to resume an existing list from the next available record. Note: many of our SDKs have iterator methods that will automatically handle cursor-based pagination.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).

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`.

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

Parameter	Description
cursor string	Used for pagination. When a list request has more records available, cursors are provided in the response headers `X-Files-Cursor-Next` and `X-Files-Cursor-Prev`. Send one of those cursor value here to resume an existing list from the next available record. Note: many of our SDKs have iterator methods that will automatically handle cursor-based pagination.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).

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

Parameter	Description
cursor string	Used for pagination. When a list request has more records available, cursors are provided in the response headers `X-Files-Cursor-Next` and `X-Files-Cursor-Prev`. Send one of those cursor value here to resume an existing list from the next available record. Note: many of our SDKs have iterator methods that will automatically handle cursor-based pagination.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).

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 the status field until it is ready.
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 the id that you got in step 1 as the action_notification_export_id parameter. Check the X-Files-Cursor-Next header to see if there are more records available, and resubmit the same request with a cursor parameter to fetch the next page of results. Unlike most API Endpoints, this endpoint does not provide X-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

Parameter	Description
cursor string	Used for pagination. When a list request has more records available, cursors are provided in the response headers `X-Files-Cursor-Next` and `X-Files-Cursor-Prev`. Send one of those cursor value here to resume an existing list from the next available record. Note: many of our SDKs have iterator methods that will automatically handle cursor-based pagination.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).

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

Parameter	Description
cursor string	Used for pagination. When a list request has more records available, cursors are provided in the response headers `X-Files-Cursor-Next` and `X-Files-Cursor-Prev`. Send one of those cursor value here to resume an existing list from the next available record. Note: many of our SDKs have iterator methods that will automatically handle cursor-based pagination.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).

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

{
  "name": "example",
  "extended_description": "example",
  "short_description": "example",
  "documentation_links": {
    "Important Info": "http://files.test/learn-more"
  },
  "icon_url": "example",
  "logo_url": "example",
  "screenshot_list_urls": [
    "example"
  ],
  "logo_thumbnail_url": "example",
  "sso_strategy_type": "example",
  "remote_server_type": "example",
  "folder_behavior_type": "example",
  "external_homepage_url": "example",
  "marketing_youtube_url": "example",
  "tutorial_youtube_url": "example",
  "app_type": "example",
  "featured": true
}

<?xml version="1.0" encoding="UTF-8"?>
<app>
  <name>example</name>
  <extended_description>example</extended_description>
  <short_description>example</short_description>
  <documentation_links>
    <Important Info>http://files.test/learn-more</Important Info>
  </documentation_links>
  <icon_url>example</icon_url>
  <logo_url>example</logo_url>
  <screenshot_list_urls type="array">
    <screenshot_list_url>example</screenshot_list_url>
  </screenshot_list_urls>
  <logo_thumbnail_url>example</logo_thumbnail_url>
  <sso_strategy_type>example</sso_strategy_type>
  <remote_server_type>example</remote_server_type>
  <folder_behavior_type>example</folder_behavior_type>
  <external_homepage_url>example</external_homepage_url>
  <marketing_youtube_url>example</marketing_youtube_url>
  <tutorial_youtube_url>example</tutorial_youtube_url>
  <app_type>example</app_type>
  <featured type="boolean">true</featured>
</app>

Attribute	Description
name string	Name of the App
extended_description string	Long form description of the App
short_description string	Short description of the App
documentation_links object	Collection of named links to documentation
icon_url string	App icon
logo_url string	Full size logo for the App
screenshot_list_urls array	Screenshots of the App
logo_thumbnail_url string	Logo thumbnail for the App
sso_strategy_type string	Associated SSO Strategy type, if any Possible values: `google`, `auth0`, `okta`, `atlassian`, `azure`, `box`, `dropbox`, `slack`, `onelogin`, `saml`, `idaptive`, `ldap`, `scim`
remote_server_type string	Associated Remote Server type, if any Possible values: `ftp`, `sftp`, `s3`, `google_cloud_storage`, `webdav`, `wasabi`, `backblaze_b2`, `one_drive`, `rackspace`, `box`, `dropbox`, `google_drive`, `azure`, `sharepoint`, `s3_compatible`, `azure_files`, `files_agent`, `filebase`, `cloudflare`, `linode`
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`
external_homepage_url string	Link to external homepage
marketing_youtube_url string	Marketing video page
tutorial_youtube_url string	Tutorial video page
app_type string	The type of the App Possible values: `sdk`, `sso`, `remote_server`, `folder_behavior`, `client_app`, `app_integration`
featured boolean	Is featured on the App listing?

List Apps

Example Request

curl "https://app.files.com/api/rest/v1/apps.json" \
  -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

[
  {
    "name": "example",
    "extended_description": "example",
    "short_description": "example",
    "documentation_links": {
      "Important Info": "http://files.test/learn-more"
    },
    "icon_url": "example",
    "logo_url": "example",
    "screenshot_list_urls": [
      "example"
    ],
    "logo_thumbnail_url": "example",
    "sso_strategy_type": "example",
    "remote_server_type": "example",
    "folder_behavior_type": "example",
    "external_homepage_url": "example",
    "marketing_youtube_url": "example",
    "tutorial_youtube_url": "example",
    "app_type": "example",
    "featured": true
  }
]

<?xml version="1.0" encoding="UTF-8"?>
<apps type="array">
  <app>
    <name>example</name>
    <extended_description>example</extended_description>
    <short_description>example</short_description>
    <documentation_links>
      <Important Info>http://files.test/learn-more</Important Info>
    </documentation_links>
    <icon_url>example</icon_url>
    <logo_url>example</logo_url>
    <screenshot_list_urls type="array">
      <screenshot_list_url>example</screenshot_list_url>
    </screenshot_list_urls>
    <logo_thumbnail_url>example</logo_thumbnail_url>
    <sso_strategy_type>example</sso_strategy_type>
    <remote_server_type>example</remote_server_type>
    <folder_behavior_type>example</folder_behavior_type>
    <external_homepage_url>example</external_homepage_url>
    <marketing_youtube_url>example</marketing_youtube_url>
    <tutorial_youtube_url>example</tutorial_youtube_url>
    <app_type>example</app_type>
    <featured type="boolean">true</featured>
  </app>
</apps>

HTTPS Request

GET /apps

Authentication Required

No authentication required; you may call this endpoint without a key or session.

Request Parameters

Parameter	Description

Pagination Params

Read more about Paginating List Requests

Parameter	Description
cursor string	Used for pagination. When a list request has more records available, cursors are provided in the response headers `X-Files-Cursor-Next` and `X-Files-Cursor-Prev`. Send one of those cursor value here to resume an existing list from the next available record. Note: many of our SDKs have iterator methods that will automatically handle cursor-based pagination.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).

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

Parameter	Description
cursor string	Used for pagination. When a list request has more records available, cursors are provided in the response headers `X-Files-Cursor-Next` and `X-Files-Cursor-Prev`. Send one of those cursor value here to resume an existing list from the next available record. Note: many of our SDKs have iterator methods that will automatically handle cursor-based pagination.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).

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

Parameter	Description
cursor string	Used for pagination. When a list request has more records available, cursors are provided in the response headers `X-Files-Cursor-Next` and `X-Files-Cursor-Prev`. Send one of those cursor value here to resume an existing list from the next available record. Note: many of our SDKs have iterator methods that will automatically handle cursor-based pagination.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).

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

Parameter	Description

Pagination Params

Read more about Paginating List Requests

Parameter	Description
cursor string	Used for pagination. When a list request has more records available, cursors are provided in the response headers `X-Files-Cursor-Next` and `X-Files-Cursor-Prev`. Send one of those cursor value here to resume an existing list from the next available record. Note: many of our SDKs have iterator methods that will automatically handle cursor-based pagination.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).

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

Parameter	Description

Pagination Params

Read more about Paginating List Requests

Parameter	Description
cursor string	Used for pagination. When a list request has more records available, cursors are provided in the response headers `X-Files-Cursor-Next` and `X-Files-Cursor-Prev`. Send one of those cursor value here to resume an existing list from the next available record. Note: many of our SDKs have iterator methods that will automatically handle cursor-based pagination.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).

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 for days_of_week (0-based) and times_of_day. A time zone may be specified via time_zone in Rails TimeZone name format.
daily : The automation will run once in a picked interval. You can specify recurring_day to select day number inside a picked interval 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

Parameter	Description
cursor string	Used for pagination. When a list request has more records available, cursors are provided in the response headers `X-Files-Cursor-Next` and `X-Files-Cursor-Prev`. Send one of those cursor value here to resume an existing list from the next available record. Note: many of our SDKs have iterator methods that will automatically handle cursor-based pagination.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).

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 &amp; 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 &amp; 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?user_id=1&automation_id=1" \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

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

Files.api_key = 'YOUR_API_KEY'

Files::AutomationRun.list(
  user_id: 1, 
  per_page: 1, 
  automation_id: 1
)

\Files\Model\AutomationRun::list(array(
  'user_id' => 1, 
  'per_page' => 1, 
  'automation_id' => 1
));

HashMap<Object, String> requestParams = new HashMap<>();
requestParams.put("user_id", 1);
requestParams.put("per_page", 1);
requestParams.put("automation_id", 1);
AutomationRun.list(parameters).all()

await AutomationRun.list({
  user_id: 1, 
  per_page: 1, 
  automation_id: 1,
})


var parameters = new Dictionary<string, object>();
parameters.Add("user_id", (Int64?) 1);
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({
  "user_id": 1,
  "per_page": 1,
  "automation_id": 1
})

files_sdk.APIKey = "YOUR_API_KEY"
automationrun.List(context.Background(), files_sdk.AutomationRunListParams{
  UserId: 1,
  Cursor: "",
  PerPage: 1,
  SortBy: "",
  Filter: "",
  AutomationId: 1,
})

files-cli automation-runs list \
  --user-id=1 \
  --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
user_id int64	User ID. Provide a value of `0` to operate the current session's user.
automation_id int64 Required	ID of the associated Automation.

Pagination Params

Read more about Paginating List Requests

Parameter	Description
cursor string	Used for pagination. When a list request has more records available, cursors are provided in the response headers `X-Files-Cursor-Next` and `X-Files-Cursor-Prev`. Send one of those cursor value here to resume an existing list from the next available record. Note: many of our SDKs have iterator methods that will automatically handle cursor-based pagination.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).

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

Parameter	Description

Pagination Params

Read more about Paginating List Requests

Parameter	Description
cursor string	Used for pagination. When a list request has more records available, cursors are provided in the response headers `X-Files-Cursor-Next` and `X-Files-Cursor-Prev`. Send one of those cursor value here to resume an existing list from the next available record. Note: many of our SDKs have iterator methods that will automatically handle cursor-based pagination.
per_page int64	Number of records to show per page. (Max: 10,000, 1,000 or less is recommended).

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, cannot be overridden.

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, cannot be overridden.

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</

Introduction

SDKs

JavaScript SDK

Ruby SDK

PHP SDK

Microsoft .NET SDK

Python SDK

Java SDK

Go SDK

REST API

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

Command Line Interface (CLI) App

Mock Server For Your Integration Tests

Attaching Files to API Requests

Authentication with API Key

Authentication with a Session

Logging in

HTTP Request

Using a session

Reauthentication

Logging out

HTTP Request

Response Codes / Errors

Error Types

Account Line Items

The AccountLineItem object

List Invoices

HTTPS Request

Authentication Required

Request Parameters

Pagination Params

List Payments

HTTPS Request

Authentication Required

Request Parameters

Pagination Params

Show Invoice

HTTPS Request

Authentication Required

Request Parameters

Show Payment

HTTPS Request

Authentication Required

Request Parameters

Actions

The Action object

List history for specific file

HTTPS Request

Authentication Required

Request Parameters

Pagination Params

Available Fields for Sorting

List history for specific folder

HTTPS Request

Authentication Required

Request Parameters

Pagination Params

Available Fields for Sorting

List history for specific user

HTTPS Request

Authentication Required

Request Parameters

Pagination Params

Available Fields for Sorting

List site login history

HTTPS Request

Authentication Required

Request Parameters

Pagination Params

Available Fields for Sorting

List site full action history

HTTPS Request

Authentication Required

Request Parameters

Pagination Params

Available Fields for Sorting

Available Filters

Action Notification Exports

Example Queries

The ActionNotificationExport object