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

[]*Action

Authorization Requirement

Available to all authenticated keys or sessions.

HistoryListForFileParams Fields

FieldDescription
StartAt
string		Leave blank or set to a date/time to filter earlier entries.
EndAt
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

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    "github.com/Files-com/files-sdk-go/v3/history"
)

actionIterator, err := history.ListForFile(files_sdk.HistoryListForFileParams{Path: "path"})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

for actionIterator.Next() {
    action := actionIterator.action()
}
err = actionIterator.Err()
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

List history for specific folder

SDK Method

history.ListForFolder()

Return Object

[]*Action

Authorization Requirement

Available to all authenticated keys or sessions.

HistoryListForFolderParams Fields

FieldDescription
StartAt
string		Leave blank or set to a date/time to filter earlier entries.
EndAt
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

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    "github.com/Files-com/files-sdk-go/v3/history"
)

actionIterator, err := history.ListForFolder(files_sdk.HistoryListForFolderParams{Path: "path"})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

for actionIterator.Next() {
    action := actionIterator.action()
}
err = actionIterator.Err()
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

List history for specific user

SDK Method

history.ListForUser()

Return Object

[]*Action

Authorization Requirement

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

HistoryListForUserParams Fields

FieldDescription
StartAt
string		Leave blank or set to a date/time to filter earlier entries.
EndAt
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.
UserId
int64
Required		User ID.

Additional Arguments

Example Request

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    "github.com/Files-com/files-sdk-go/v3/history"
)

actionIterator, err := history.ListForUser(files_sdk.HistoryListForUserParams{UserId: 1})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

for actionIterator.Next() {
    action := actionIterator.action()
}
err = actionIterator.Err()
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

List site login history

SDK Method

history.ListLogins()

Return Object

[]*Action

Authorization Requirement

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

HistoryListLoginsParams Fields

FieldDescription
StartAt
string		Leave blank or set to a date/time to filter earlier entries.
EndAt
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

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    "github.com/Files-com/files-sdk-go/v3/history"
)

actionIterator, err := history.ListLogins(files_sdk.HistoryListLoginsParams{Display: "Actual text of the action here."})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

for actionIterator.Next() {
    action := actionIterator.action()
}
err = actionIterator.Err()
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

List site full action history

SDK Method

history.List()

Return Object

[]*Action

Authorization Requirement

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

HistoryListParams Fields

FieldDescription
StartAt
string		Leave blank or set to a date/time to filter earlier entries.
EndAt
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

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    "github.com/Files-com/files-sdk-go/v3/history"
)

actionIterator, err := history.List(files_sdk.HistoryListParams{Display: "Actual text of the action here."})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

for actionIterator.Next() {
    action := actionIterator.action()
}
err = actionIterator.Err()
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

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
UserId
int64		User ID
Username
string		Username
UserIsFromParentSite
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
FailureType
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