Actions

An Action is a single record in our history log. File and Login actions on Files.com are recorded and can be queried via 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.

Note: Failed Logins are no longer logged in this logging mechanism. The failedlogin value is still listed in the action documentation for legacy reasons. Use API or other protocol logs (SFTP, FTP, etc.) for detailed and better information about login failures.

List history for specific file

SDK Method

History.ListForFile();

Return Object

FilesList<Action>

Authorization Requirement

Available to all authenticated keys or sessions.

Method Arguments

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

Additional Arguments

Example Request

using FilesCom.Models;

var parameters = new Dictionary<string, object>();
parameters.Add("display", "Actual text of the action here.");

try
{
    var actionIterator = History.ListForFile(path, parameters);
    foreach (Action action in actionIterator.ListAutoPaging()) {
        // Operate on action
    }
}
catch (FilesCom.NotAuthenticatedException e)
{
    Console.WriteLine($"Authentication Error Occurred ({e.GetType().Name}): " + e.Message);
}
catch (FilesCom.SdkException e)
{
    Console.WriteLine($"Unknown Error Occurred ({e.GetType().Name}): " + e.Message);
}

List history for specific folder

SDK Method

History.ListForFolder();

Return Object

FilesList<Action>

Authorization Requirement

Available to all authenticated keys or sessions.

Method Arguments

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

Additional Arguments

Example Request

using FilesCom.Models;

var parameters = new Dictionary<string, object>();
parameters.Add("display", "Actual text of the action here.");

try
{
    var actionIterator = History.ListForFolder(path, parameters);
    foreach (Action action in actionIterator.ListAutoPaging()) {
        // Operate on action
    }
}
catch (FilesCom.NotAuthenticatedException e)
{
    Console.WriteLine($"Authentication Error Occurred ({e.GetType().Name}): " + e.Message);
}
catch (FilesCom.SdkException e)
{
    Console.WriteLine($"Unknown Error Occurred ({e.GetType().Name}): " + e.Message);
}

List history for specific user

SDK Method

History.ListForUser();

Return Object

FilesList<Action>

Authorization Requirement

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

Method Arguments

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

Additional Arguments

Example Request

using FilesCom.Models;

var parameters = new Dictionary<string, object>();
parameters.Add("display", "Actual text of the action here.");

try
{
    var actionIterator = History.ListForUser(user_id, parameters);
    foreach (Action action in actionIterator.ListAutoPaging()) {
        // Operate on action
    }
}
catch (FilesCom.NotAuthenticatedException e)
{
    Console.WriteLine($"Authentication Error Occurred ({e.GetType().Name}): " + e.Message);
}
catch (FilesCom.SdkException e)
{
    Console.WriteLine($"Unknown Error Occurred ({e.GetType().Name}): " + e.Message);
}

List site login history

SDK Method

History.ListLogins();

Return Object

FilesList<Action>

Authorization Requirement

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

Method Arguments

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

Additional Arguments

Example Request

using FilesCom.Models;

var parameters = new Dictionary<string, object>();
parameters.Add("display", "Actual text of the action here.");

try
{
    var actionIterator = History.ListLogins(parameters);
    foreach (Action action in actionIterator.ListAutoPaging()) {
        // Operate on action
    }
}
catch (FilesCom.NotAuthenticatedException e)
{
    Console.WriteLine($"Authentication Error Occurred ({e.GetType().Name}): " + e.Message);
}
catch (FilesCom.SdkException e)
{
    Console.WriteLine($"Unknown Error Occurred ({e.GetType().Name}): " + e.Message);
}

List site full action history

SDK Method

History.List();

Return Object

FilesList<Action>

Authorization Requirement

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

Method Arguments

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

Additional Arguments

Example Request

using FilesCom.Models;

var parameters = new Dictionary<string, object>();
parameters.Add("display", "Actual text of the action here.");

try
{
    var actionIterator = History.List(parameters);
    foreach (Action action in actionIterator.ListAutoPaging()) {
        // Operate on action
    }
}
catch (FilesCom.NotAuthenticatedException e)
{
    Console.WriteLine($"Authentication Error Occurred ({e.GetType().Name}): " + e.Message);
}
catch (FilesCom.SdkException e)
{
    Console.WriteLine($"Unknown Error Occurred ({e.GetType().Name}): " + e.Message);
}

The Action Object

Some of the methods above return a Action object. The attributes of this object are listed below.

AttributeDescription
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
object		Targets
user_id
int64		User ID
username
string		Username
user_is_from_parent_site
boolean		true if this change was performed by a user on a parent site.
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, archived_delete
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, insecure_ftp, insecure_cipher, rate_limited
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, inbound_s3