/files/search

Search for objects in a specified path that match user-specified conditions and terms. To search by using bearer token authentication and file IDs, use the /files endpoint.

Requirements
  • Available as of Enterprise Server version 3.0.0.
  • Search requests can timeout if the path includes a large directory tree with many files or if the server is slow. The default timeout is 10 seconds. To increase the timeout:
    1. Change the default timeout by running the following command (this example increases the timeout to 5 minutes):
      asconfigurator -x "set_server_data;max_response_time_sec,300"
    2. Restart asperanoded to activate the update.
      # service asperanoded restart
Access Control
  • HTTP Basic Auth
    Users who authenticate with Node API credentials can search paths that are within their docroot. Access key users can search paths that are within the path set in the access key.
URL
POST https://{domain}:9092/files/search

Sample Request
curl -i -u user:secret -X POST https://{domain}:9092/files/search \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d @request_body.json

Where request_body.json contains the following:
{
    "path" : "/",
    "skip" : 5,
    "count" : 100,
    "sort" : "path",
    "filters" : {
        "types" : [
            "file",
            "directory"
        ],
        "depth_min" : 0,
        "depth_max" : 10
    }
}

Headers
Header Name Required Description Values
Content-Type Optional The format of the request data. application/json
Accept Optional The format of the response data. application/json
Request Body
Element Required Type Description
path Required String Absolute path to file or directory.
skip Optional Unsigned integer Skip the first "skip" results. Default 0
count Optional Unsigned integer Return no more than "count" results.  It is the client’s responsibility to keep track of number of results returned. Default 100.
case_sensistive Optional Boolean Set to true to make sort and basename case sensitive. Default: false. Search on Solaris, Windows, and Isilon nodes is always case sensitive.
sort Optional String Sort results by the specified value. Values:
  • path (pathname)
  • type (directory/file)
  • size_a (bytes, ascending)
  • size_d (bytes, descending)
  • mtime_a (modification date, ascending)
  • mtime_d (modification date, descending)
filters Optional JSON Array of filters to apply to the results.
types Optional String Return data only for the specified content types: file, symbolic_link, or directory.
paths Optional String Return data only for path names that match the specified path.
basenames Optional String Return data only for files with basenames that match the specified basenames.
size_min Optional Unsigned integer Include files that are greater than or equal to size_min (in bytes). NOTE: This setting automatically restricts the results to files, equivalent to setting "types":"file".
size_max Optional Unsigned integer Include files that are less than size_max (in bytes). NOTE: This setting automatically restricts the results to files, equivalent to setting "types":"file".
mtime_min Optional String Include files that were updated after mtime_min, in the format "2011-01-31T12:59:59Z", T or space in the middle; Z optional at the end.
mtime_max Optional String Include files that were updated before mtime_max, in ISO format "2011-01-31T12:59:59Z", T or space in the middle; Z optional at the end.
depth_min Optional Unsigned integer The minimum directory depth to search.
depth_max Optional Unsigned integer The maximum directory depth to search.
Sample Response
HTTP/1.1 200 OK
Cache: no-cache
Connection: close
Content-Type: application/json; charset=utf-8

{
    "items" : [
        {
            "path" : "/Users/aspera/Documents/.sample.txt.asp-lck/1519688692:n:ak123",
            "basename" : "1519688692:n:ak123",
            "type" : "file",
            "size" : 0,
            "mtime" : "2018-02-26T23:44:52Z",
            "permissions" : [
                { "name" : "view" },
                { "name" : "edit" },
                { "name" : "delete" }
            ],
            "filelock" : null
        },
        {
            "path" : "/Users/aspera/Documents/sample.txt",
            "basename" : "sample.txt",
            "type" : "file",
            "size" : 445,
            "mtime" : "2018-02-09T23:08:46Z",
            "permissions" : [
                { "name" : "view" },
                { "name" : "edit" },
                { "name" : "delete" }
            ],
            "filelock" : {
                "created_by_type" : "node",
                "created_by_id" : "ak123",
                "created_at" : "2018-02-26T23:44:52Z",
                "tags" : null
            }
        },
        {
            "path" : "/Users/aspera/Documents/symlink1",
            "basename" : "symlink1",
            "type" : "file",
            "size" : 445,
            "mtime" : "2018-02-09T23:08:46Z",
            "permissions" : [
                { "name" : "view" },
                { "name" : "edit" },
                { "name" : "delete" }
            ],
            "filelock" : null
        },
        {    
            "path" : "/Users/aspera/Documents/test_folder",
            "basename" : "test_folder",
            "type" : "directory",
            "size" : 0,
            "mtime" : "2018-02-19T17:43:59Z",
            "permissions" : [
                { "name" : "view" },
                { "name" : "edit" },
                { "name" : "delete" }
            ]
        }
    ],
    "item_count" : 4,
    "total_count" : 5,
    "parameters" : {
        "path" : "/Users/aspera/Documents",
        "skip" : 1,
        "count" : 100,
        "depth_min" : 0,
        "depth_max" : 2
    }
}

Status Codes and Errors
Code Description Notes
200 OK Success
400 Bad Request Error Request contains a formatting or syntax error.
404 Not Found Error Invalid pathname.
500 Internal Server Error Error The server configuration is invalid.
Response
Element Type Description
items JSON Array of file and directory metadata that match the search request.
path String The pathname of the file, symbolic link, or directory.
basename String The item's basename.
type String The item type.
size Unsigned integer The size of the item in bytes.
mtime String The modification time of the item, in ISO format.
permissions JSON Array of permissions that the user has on the file.
name String The permission. Values: view, edit, and delete.
filelock JSON If a file is filelocked, a JSON object with the filelock metadata.
created_by_type String The filelock source.
created_by_id String The username of the user who applied the filelock.
created_at String The time the filelock was applied, in ISO format.
tags JSON Tags associated with the filelock.
item_count Unsigned integer The number of items returned by the request, calculated as the total number of items in the path minus the number of items that are skipped and filtered.
total_count Unsigned integer The total number of items in the request path, minus the number of items that are filtered.
parameters JSON JSON object containing the search parameters from the request body.
Video player

Video

×