/files

Create, modify, and delete files, symbolic links, and directories on a node. Manage filelocks on files.

Requirements
  • Available as of Enterprise Server version 3.6.0.
Access Control
  • HTTP Basic Auth
    Provide an access key ID and secret. Node API credentials are not supported.
  • Bearer token
    Actions are restricted to the tenant space defined by the bearer token and the permissions set on the content.
Headers

All requests to this endpoint use the same 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
X-Aspera-AccessKey Required
(for bearer token authorization)
The access key ID that was used to create the bearer token. Access key ID.
Authorization Required
(for bearer token authorization)
The bearer token. "Bearer token_string"
Status Codes and Errors
Code Description Notes
200 OK Success
204 No Content Success File, symbolic link, or directory successfully modified.
400 Bad Request Error Request contains a formatting or syntax error, or filelocks are disabled.
404 Not Found Error Invalid file ID.
409 Conflict Error File already exists.
500 Internal Server Error Error The server configuration is invalid.
503 Service Unavailable Error The access key is locked for backup.

Endpoint Actions

Create a File, Symbolic Link, or Folder

Create a 0-byte file, symbolic link, or directory in the directory that is specified by ID. Specify the object characteristics in the request body.

Restrictions
  • The user must have write permission (recursively) on the directory to create files or links, and mkdir permission to create directories.
URL
POST https://{domain}:9092/files/{id}/files

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

Where request_body.json contains the following:
{
    "name" : "filename",
    "type" : "file",
    "filelocked" : false
}

Request Body
Element Required Type Description
name Required String The name of the file.
type Required String The file type. Values: file for regular files, link for symbolic links, or folder for a directory.
target_id Optional String The file ID of the symbolic link target.
target_node_id Optional String The node ID of the node on which the symbolic link target is located. Get the node ID by using /info.
mount_point Optional Boolean If the directory should be treated as a mount point.
filelocked Optional Boolean Set the initial file lock on a file.
Sample Response
HTTP/1.1 200 OK
Cache: no-cache
Connection: close
Content-Type: application/json; charset=utf-8
 
{
  "id" : "417",
  "name" : "file.txt.17",
  "size" : 0,
  "type" : "file",
  "modified_time" : "2017-04-05T23:15:32Z",
  "content_type" : "application/octet-stream"
}

Response
Element Type Description
id String The file ID of the created file, symbolic link, or directory.
name String The name of the created file, symbolic link, or directory.
size Unsigned integer The size of the file, symbolic link, or directory, in bytes.
type String The file type.
modified_time String The file creation time in ISO format.
content_type String The file format, such as application/octet-stream and text/plain.

Get the Metadata of a File

List the metatdata of the specified file, symbolic link, or folder.

Restrictions
  • The user must have list permission (recursively) on the directory.
  • The user must have admin permissions to view file paths.
URL
GET https://{domain}:9092/files/{id}

Sample Request
curl -i -u user:secret -X GET https://{domain}:9092/files/{id} \
     -H "Content-Type: application/json" \
     -H "Accept: application/json"

Query Parameters
Parameter Type Description Values
include String Include the specified attributes in the metadata. access_levels, permission_count, recursive_counts, filelocked_file_ids
Sample Response
HTTP/1.1 200 OK
Cache: no-cache
Connection: close
Content-Type: application/json; charset=utf-8

{
    "id" : "33",
    "name" : "aspera",
    "path" : "/Users/aspera",
    "type" : "folder",
    "modified_time" : "2018-02-09T17:15:17Z",
    "mount_point" : false,
    "access_levels" : [
      "list",
      "read",
      "write",
      "delete",
      "mkdir",
      "rename",
      "preview"
    ],
    "access_level" : "edit"
}

Response
Element Type Description
id String File ID.
name String File name.
path String File path.
type String file, link, or folder.
modified_time String Modification time in ISO format.
mount_point Boolean For directories, if the directory is a mount point.
access_levels String JSON array of permissions on the file.
access_level String Deprecated version of access_levels that is retained for backwards compatibility.

List Metadata for Files in a Directory

List the metadata of files in the specified directory (IDs of links and folders are not supported).

Restrictions
  • The user must have list permission (recursively) on the directory.
  • The user must have admin permissions to view file paths.
URL
GET https://{domain}:9092/files/{id}/files

Sample Request
curl -i -u user:secret -X GET https://{domain}:9092/files/{id}/files?page=1&per_page=25 \
     -H "Content-Type: application/json" \
     -H "Accept: application/json"

Query Parameters
Parameter Type Description Values
page Unsigned integer Return the metadata of files in the directory as pages and for the specified page number. Number
per_page Unsigned integer Return the metatdata for the specified number of files on each page. Number
include String Include the specified attributes in the metadata. access_levels, recursive_counts, filelocked_file_ids
sort String Sort the files by the specified attribute. Sortable attributes are name, size, type, modified_time, recursive_folder_count, recursive_link_count, recursive_file_count, recursive_size
name String Filter files by name. Use this option to return metadata for a specific file. The file name.
name_glob String Filter files by name using glob patterns that are case sensitive. A glob pattern, such as *.TXT.
name_iglob String Filter files by name using glob patterns that are case insensitive. A glob pattern, such as *.txt.
min_size Unsigned integer Filter files by size, returning metadata only for files that are larger than the specified value. File size threshold in bytes.
max_size Unsigned integer Filter files by size, returning metadata only for files that are smaller than the specified value. File size threshold in bytes.
type String Filter files by type. file, link, or folder.
min_modified_time String Filter files by modified time, returning metadata only for files that were modfied after the specified time. Time in ISO format
max_modified_time String Filter files by modified time, returning metadata only for files that were modfied before the specified time. Time in ISO format
target_id String Filter files by target ID. Target ID.
target_node_id String Filter files by the ID of the node on which the symbolic link target is located. The node ID.
Sample Response
HTTP/1.1 200 OK
Cache: no-cache
Connection: close
Content-Type: application/json; charset=utf-8
Access-Control-Expose-Headers: X-Aspera-Node-Cache, X-Total-Count
X-Aspera-Node-Cache: id=MTpmaWxlOmNhY2hlOnpzZXQ6e2N9OjI0Oi06dDI= ct=1518201221 age=89 ttl=211
X-Total-Count: 2

[
  {
    "id" : "32",
    "name" : "Shared",
    "path" : "/Users/Shared",
    "type" : "folder",
    "modified_time" : "2018-01-26T17:28:56Z",
    "mount_point" : false,
    "access_levels" : [
      "list",
      "read",
      "write",
      "delete",
      "mkdir",
      "rename",
      "preview"
    ],
    "access_level" : "edit"
  },
  {
    "id" : "33",
    "name" : "aspera",
    "path" : "/Users/aspera",
    "type" : "folder",
    "modified_time" : "2018-02-09T17:15:17Z",
    "mount_point" : false,
    "access_levels" : [
      "list",
      "read",
      "write",
      "delete",
      "mkdir",
      "rename",
      "preview"
    ],
    "access_level" : "edit"
  }
]

Response
Element Type Description
id String File ID.
name String File name.
path String File path.
type String file, link, or folder.
modified_time String Modification time in ISO format.
mount_point Boolean For directories, if the directory is a mount point.
access_levels String JSON array of permissions on the file.
access_level String Deprecated version of access_levels that is retained for backwards compatibility.

Get File Contents

List the contents of the specified file.

Restrictions
  • The user must have read permission (recursively) on the file.
  • Content cannot be returned for files that are larger than the configured maximum requested file creation size (max_request_file_create_size_kb).
  • Content cannot be returned for symbolic links or directories.
URL
GET https://{domain}:9092/files/{id}/content

Sample Request
curl -i -u user:secret -X GET https://{domain}:9092/files/{id}/content \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" 

Sample Response
HTTP/1.1 200 OK
Cache: no-cache
Connection: close
Content-Type: text/plain
Content-Length: 445

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
ncididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostru
d exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aut
e irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat n
ulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui
 officia deserunt mollit anim id est laborum.

Modify a File or Directory

Rename the specified file, directory, or symbolic link. Change the mount point status of a directory.

Restrictions
  • The user must have rename permission (recursively) on the file.
  • Mount point status is only visible to master access keys.
  • Modification fails if the file is filelocked by a different user.
URL
PUT https://{domain}:9092/files/{id}

Sample Request
curl -i -u user:secret -X PUT https://{domain}:9092/files/{id} \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d '{"name" : "new_file_name", "mount_point" : false}'

Request Body
Element Required Type Description
name Optional String The new name for the file, symbolic link, or directory.
mount_point Optional Boolean If the directory is a mount point. Does not apply to files or symbolic links.
Sample Response
Success:
HTTP/1.1 204 No Content
Cache: no-cache
Connection: close
Content-Type: application/json; charset=utf-8
Content-Length: 0

Error:
HTTP/1.1 404 Not Found
Cache: no-cache
Connection: close
Content-Type: text/plain
Content-Length: 445

{
    "error" : { 
        "code" : 404, 
        "reason" : "Not Found", 
        "user_message" : "File_id='52' does not exist" 
    }
}
Response
Element Type Description
error JSON object Error response.
code Double HTTP error code.
reason String HTTP error message.
user_message String Error description.

Delete a File, Link, or Directory

Delete the specified file, symbolic link, or directory.

Restrictions
  • The user must have delete permission (recursively) on the file.
  • Deletion fails if the file is filelocked by a different user.
URL
DELETE https://{domain}:9092/files/{id}

Sample Request
curl -i -u user:secret -X DELETE https://{domain}:9092/files/{id}

Sample Response
Success:
HTTP/1.1 204 No Content
Cache: no-cache
Connection: close
Content-Type: application/json; charset=utf-8
Content-Length: 0

Error:
HTTP/1.1 404 Not Found
Cache: no-cache
Connection: close
Content-Type: text/plain
Content-Length: 445

{
    "error" : { 
        "code" : 404, 
        "reason" : "Not Found", 
        "user_message" : "File_id='52' does not exist" 
    }
}
Response
Element Type Description
error JSON object Error response.
code Double HTTP error code.
reason String HTTP error message.
user_message String Error description.

Filelock a File

Apply a filelock to a file that prevents other users from modifying the file, unless they are admins, in which case they can override the filelock. The filelock creates a backup of the original file as .file.asp-bak and a metadata file, .file.asp-lck, that contains the name of the user who locked the file.

Restrictions
  • The user must have recursive read, write, and delete permissions on the file.
  • Does not support non-files (folders or links).
URL
POST https://{domain}:9092/files/{id}/filelock

Sample Request
curl -i -u user:secret -X POST https://{domain}:9092/files/{id}/filelock \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d '{"tags":{"tag1":"tag_string"}}'

Request Body
Element Required Type Description
tags Optional String JSON object that contains user-defined tags.
Sample Response
HTTP/1.1 200 OK
Cache: no-cache
Connection: close
Content-Type: application/json; charset=utf-8
 
{
  "file_id" : "2",
  "created_by_type" : "node",
  "created_by_id" : "ak123",
  "created_at" : "2017-11-08T01:22:05Z",
  "tags" : {"tag1":"tag_string"}
}

Response
Success:
Element Type Description
file_id String File ID.
created_by_type String How the filelock was created.
created_by_id String The access key ID that authorized the request.
created_at String Time the filelock was applied, in ISO format.
tags String Any user-defined tags.
Error:
Element Type Description
error JSON object Error response.
code Double HTTP error code.
reason String HTTP error message.
user_message String Error description.

Get Filelock Information for a File

Retrieve filelock information for a file, including the access key associated with the user who applied the file lock and when the file lock was applied. If the filelock was applied by using Node API credentials and /files/filelock, the user information is not available.

Restrictions
  • The user must have recursive read, write, and delete permissions on the file.
URL
GET https://{domain}:9092/files/{id}/filelock

Sample Request
curl -i -u user:secret -X GET https://{domain}:9092/files/{id}/filelock \
     -H "Content-Type: application/json" \
     -H "Accept: application/json"

Sample Responses
File has a filelock:
HTTP/1.1 200 OK
Cache: no-cache
Connection: close
Content-Type: application/json; charset=utf-8
 
{
  "file_id" : "2",
  "created_by_type" : "node",
  "created_by_id" : "ak123",
  "created_at" : "2017-11-08T01:22:05Z",
  "tags" : {"tag1":"tag_string"}
}

No filelock:
HTTP/1.1 404 Not Found
Cache: no-cache
Connection: close
Content-Type: text/plain
Content-Length: 445

{
    "error" : { 
        "code" : 404, 
        "reason" : "Not Found", 
        "user_message" : "File_id='52' is not filelocked" 
    }
}
Response
Element Type Description
file_id String File ID.
created_by_type String How the filelock was created.
created_by_id String The access key ID that authorized the request.
created_at String Time the filelock was applied, in ISO format.
tags String Any user-defined tags.
error JSON object Error response.
code Double HTTP error code.
reason String HTTP error message.
user_message String Error description.

Modify the Filelock on a File

Modify a filelock on a file by changing the tags or the status.

Restrictions
  • The user must have created the filelock or have recursive read, write, and delete permissions on the file.
URL
PUT https://{domain}:9092/files/{id}/filelock

Sample Request
curl -i -u user:secret -X PUT https://{domain}:9092/files/{id}/filelock \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d '{"tags":{"tag1":"tag_string"}}'

Request Body
Element Required Type Description
tags Optional String JSON object that contains user-defined tags.
status Optional String Update the status to deleted (equivalent to DELETE) or reverted (equivalent to REVERT).
Sample Responses
HTTP/1.1 204 No Content
Cache: no-cache
Connection: close
Content-Type: application/json; charset=utf-8

Response
Error:
Element Type Description
error JSON object Error response.
code Double HTTP error code.
reason String HTTP error message.
user_message String Error description.

Delete a Filelock

Delete the filelock on a file, including the file backup and metadata files.

Restrictions
  • The user must have created the filelock or have recursive read, write, and delete permissions on the file.
  • Once a filelock is deleted, the file cannot be reverted to the original file before the filelock was applied.
URL
DELETE https://{domain}:9092/files/{id}/filelock

Sample Request
curl -i -u user:secret -X DELETE https://{domain}:9092/files/{id}/filelock

Sample Response
HTTP/1.1 204 No Content
Cache: no-cache
Connection: close
Content-Type: application/json; charset=utf-8

Response
Error:
Element Type Description
error JSON object Error response.
code Double HTTP error code.
reason String HTTP error message.
user_message String Error description.

Revert a Filelock

Revert the filelock on a file. This reverts the file to its original state at the time the filelock was applied and deletes the file backup and metadata files.

Restrictions
  • The user must have created the filelock or have recursive read, write, and delete permissions on the file.
URL
REVERT https://{domain}:9092/files/{id}/filelock

Sample Request
curl -i -u user:secret -X REVERT https://{domain}:9092/files/{id}/filelock

Sample Response
Success:
HTTP/1.1 204 No Content
Cache: no-cache
Connection: close
Content-Type: application/json; charset=utf-8

Response
Error:
Element Type Description
error JSON object Error response.
code Double HTTP error code.
reason String HTTP error message.
user_message String Error description.
Video player

Video

×