Data API

The Nasuni Data API provides programatic access to the filesystem of an Nasuni Edge Appliance. The API provides endpoints for creating, updating and deleting files and folders.

Prerequisites

You must enable “Mobile Access” for the share that you want to use the Nasuni API with. On the Nasuni Edge Appliance user interface, use the CIFS Shares page. On the Nasuni Management Console use the Shares page and enable “Sync and Mobile Access”.

Getting Started

Creating an API Token

For all APIs listed here, the host is the host name or IP address of the Nasuni Edge Appliance, and the port is usually 443.

The auth/login endpoint is used to generate a x-secret-token (in the response header). The username and password must be valid SMB credentials. The values of device_id and device_type are not validated though device_id is intended to be unique per device or application instance.

curl -k -i -F username=test_user_1 -F password=1234 -F device_id=test1 -F device_type=iphone https://10.100.21.41/mobileapi/1/auth/login
HTTP/1.1 200 OK
Date: Fri, 16 May 2025 19:59:50 GMT
Server: uvicorn
Strict-Transport-Security: max-age=31536000
x-secret-key: EGngFS/6sETWST90Mv72dg==

Using an API Token

The x-secret-token is combined with the device_id which is passed as Basic Auth header (username-device_id, password=token) in subsequent requests.

curl -k -u "test1:EGngFS/6sETWST90Mv72dg==" https://10.100.21.41/mobileapi/1/fs
{"name":"/","items":[{"type":"share","name":"Share1","mod_time":1747352913,"path":"/shareone","share":"Share1"},\
{"type":"share","name":"Another Share","mod_time":1747352913,"path":"/Another Share","share":"Another Share"}]}

Errors

The return codes listed are the most common and should have a specific action associated with them. It is possible that in some cases these APIs will return other return codes, such as codes in the 500s for various server problems and 400s for client errors. For anything unspecified, the app should simply display a general error message and ask the user to try again. Please report any recurrent return codes in the 500s to Nasuni Technical Support.

Examples

Note: Examples are given using curl. Since all the APIs use https, ensure that the version of libcurl that you use supports https. See curl - Download.

When using cURL, it is necessary to handle certificates correctly. If the Nasuni Edge Appliance has only a self-signed certificate, you must disable certificate chain checking. See the description of the –k cURL option.

Entity Tags

The intent of entity tags (“ETags”) is as a mechanism to let the caller know if an item has changed, or to conditionally perform an operation if it has changed or not.

Files

As of version 10.1 Etags are always returned for files.

An ETag is always available for a file and is generated from the modified time of the file and it’s size. Thus, is changes as a file’s contents are changed.

ETag is not affected by things that change metadata such as rename, permissions, and ACLs.

Note: Files can have the same ETag, but are not the same file.

Directories

As of version 10.1 Etags are current not calculated for directories. Ref: Defect WE-873.

Earlier Releases

Prior to 10.1 ETags are returned for directories and files when a header request was passed:

X-NAS-Options: generate_etag

An ETag is returned for directories only when the directory has been fully synchronized with the cloud.

Any changes within a directory (such as new file, file rename, or file create) immediately clears the ETag until that directory is fully synchronized again with the cloud.

When encountering a directory with a missing ETag, you must enumerate or process all contents, comparing the ETag of each item within, and for directories descending, if needed.

The directory ETag is updated before files are updated are done so there are no race conditions.

Authentication (Login) API

Authenticates a user's credentials and logs the user in. After authentication, all client threads must use the x-secret-key token returned for all subsequent API calls.

URL

/mobileapi/1/auth/login

Method

POST

Request Body Parameters

username

Active Directory username. Both <username> and <domain>\<username> formats are allowed.
For native users, enter the username.

password

Password for the username.

Note: Applications should never save the user’s password.

device_id

The field name “device_id” comes from the Mobile Access API, which is the origin of the Nasuni API. This field allows you to enter a unique random string, such as a GUID, that uniquely identifies the client.

Note: This device_id appears on the Mobile License Usage page of the Nasuni Edge Appliance user interface.

device_type

The field name “device_type” comes from the Mobile Access API.

Note: As of version 10.1 the device_type is required but it’s value is no longer restricted.

Return codes

200: Success.

401: Unauthorized. Authentication failure. Ensure that the username and password are correct. Verify that Mobile Access is enabled.

403: Forbidden: Authentication failure. (version 10.1 only)

410: device_id is disabled on the Nasuni Edge Appliance for this particular device. Authorization using a different device_id is necessary.

Response headers

x-secret-key

In the case of a 200 success, this response header contains a secret key, which the app is responsible for saving and using on all subsequent API calls. This key can be used concurrently by any number of client threads. If the secret key is lost for any reason, you can just re-authenticate to get a new one.

As of version 10.1 most header parameters are now returned with lowercase names. Earlier versions returned X-Secret-Key.

This response header is of the form:

x-secret-key: gWTklSZs9EpuAo3yM3TymvdbscaKeQ6H37EnLK6spUs=

cURL example

curl -k -i -F username=TESTUSER -F password=TESTPASSWORD -F device_id=apple001 -F device_type=iphone https://hostname/mobileapi/1/auth/login

Note: In this example, the cURL switches include the following:

-k

This option explicitly allows curl to perform "insecure" SSL connections and transfers. All SSL connections are attempted to be made secure by using the CA certificate bundle installed by default. This makes all connections considered "insecure" fail unless –k or --insecure is used.

-i

Include the HTTP-header in the output. The HTTP-header includes information like server-name, date of the document, HTTP-version and more.

-F

This lets curl emulate a filled-in form in which a user has pressed the Submit button.

Output:

HTTP/1.1 100 Continue

HTTP/1.1 200 OK Date: Tue, 01 May 2012 20:38:00 GMT Server: uvicorn x-secret-key: gWTklSZs9EpuAo3yM3TymvdbscaKeQ6H37EnLK6spUs= content-length: 0 connection: Keep-Alive content-type: text/plain; charset=UTF-8

Logout

De-authenticates the user from the interface. After use of this API, the caller should forget the secret key, but can still retain and re-use the device ID.

URL

/mobileapi/1/auth/logout

Method

POST

Request Headers

Authorization: Basic <device_id>:<x-secret-key> - mandatory Basic Auth Header.

Return codes

200: Success.

401: Unauthorized. Authentication failure. Authentication failures on non-authenticated APIs can be due to expired secret keys. On logout, this error can be ignored, and the logout can be considered successful.

cURL example

curl –X POST -k -i-u "apple001:gWTklSZs9EpuAo3yM3TymvdbscaKeQ6H37=" https://hostname/mobileapi/1/auth/logout

Note: In this example, the cURL switches include the following:

-X

Specifies a custom request method to use when communicating with the HTTP server. The specified request is used instead of the method otherwise used (which defaults to GET).

-k

-i

Include the HTTP-header in the output. The HTTP-header includes information like server-name, date of the document, HTTP-version and more.

-u

Use <device_id>:<x-secret-key>.

Note: In this example, the following fields are used:

device_id

The same device_id used for login.

x-secret-key

The secret key obtained after running login.

Output:

HTTP/1.1 200 OK Date: Tue, 01 May 2012 20:38:00 GMT Server: uvicorn content-length: 0 connection: Keep-Alive content-type: text/plain; charset=UTF-8

Get items

Get the contents of an item, either a directory listing, the previous version listing of a file or directory, or the contents of a file.

URL

/mobileapi/1/fs/<path>

Note: “fs” stands for “file system”.

Method

GET

Request Headers

Authorization: Basic <device_id>:<x-secret-key>

Range

HTTP Range header. Optional. Only meaningful if the path is to a file.

If-None-Match: ETag

ETag from a previous GET request. (Can also be a list of ETags). A return code of 304 is returned if this directory or file has not changed per the ETag.

Parameters

path

(Optional.) Path to the item. If omitted, the result is a list of shares.

previous

(Optional.) True or false. Instead of getting a file or directory's contents, get its list of previous versions.

version_time

(Optional.) Specifies which version of the file or directory to retrieve.

Return codes

200: Success.

206: Partial range satisfied.

304: Not modified.

401: Authentication failure.

403: Permission denied.

404: Object not found.

410: device_id is disabled on the Nasuni Edge Appliance for this particular device. Authorization using a different device_id is necessary.

416: Range requested but cannot be satisfied.

Response headers:

x-object-type

One of shares, share, directory, versions, or file.

ETag

If client requested generation of an ETag.

Response body:

If shares, the list of shares available to navigate into.

If directory or share, the list of files and directories within this directory.

If versions, a listing of the previous versions of a file or directory.

If file, the (possibly partial) contents of the file.

Example: obtaining top-level directory

curl -k -u "apple001:gWTklSZs9EpuAo3yM3TymvdbscaKeQ6H37=" https://hostname/mobileapi/1/fs

Note: The path is omitted to get the top directory.

Note: In this example, the cURL switches include the following:

-k

-u

Use “device_id:x-secret-key”

Note: In this example, the following fields are used:

device_id

The same device_id used for login.

x-secret-key

The secret key obtained after running login.

The result, in JSON format, is of the form:

{
  "name": "/",
  "items": [
    {"type": "share", "name": "share1", "mod_time": 1334857842},
    {"type": "share", "name": "share2", "mod_time": 1334857347},
    {"type": "share", "name": "share3", "mod_time": 1334857436}
  ]
}

Example: obtaining arbitrary directory

curl -k -u "apple001:gWTklSZs9EpuAo3yM3TymvdbscaKeQ6H37=" https://hostname/mobileapi/1/fs/full/path/to/dir

Note: In this example, the cURL switches include the following:

-k

-u

Use “device_id:x-secret-key”

Note: In this example, the following fields are used:

device_id

The same device_id used for login.

x-secret-key

The secret key obtained after running login.

The result, in JSON format, is of the form:

{
  "name": "/full/path/to/dir",
  "items": [
    {"mod_time": 1334857842, "type": "file", "name": "file2", "size": 10240000, "ETag": "1-1334857842-10240000"},
    {"mod_time": 1234567890, "type": "file", "name": "file4", "size": 324, "ETag": "1-1234567890-324"},
    {"mod_time": 1234567890, "type": "directory", "name": "dir2"}
  ]
}

Example: obtaining previous versions of a file

curl -k -u "apple001:gWTklSZs9EpuAo3yM3TymvdbscaKeQ6H37=" https://hostname/mobileapi/1/fs/full/path/to/file?previous=true

Note: In this example, the cURL switches include the following:

-k

-u: Use “device_id:x-secret-key”

Note: In this example, the following fields are used:

previous

(Optional.) True or false. Instead of getting a file or directory's contents, get its list of previous versions.

device_id: The same device_id used for login.

x-secret-key: The secret key obtained after running login.

The result, in JSON format, is of the form:

{
  "type": "file",
  "name": "/full/path/to/filename",
  "versions": [
    {"version_time":1336049867, "mod_time": 1336049977, size: 84576, "ETag": "1-1336049867-84576"},
    {"version_time":1336049977, "mod_time": 1336049537, size: 74537, "ETag": "1-1336049977-74537"},
    {"version_time":1336050987, "mod_time": 1335996049, size: 63452, "ETag": "1-1336050987-63452"}
  ]
}

Example: obtaining previous versions of a directory

curl -k -u "apple001:gWTklSZs9EpuAo3yM3TymvdbscaKeQ6H37=" https://hostname/mobileapi/1/fs/full/path/to/dir ?previous=true

Note: In this example, the cURL switches include the following:

-k

-u

Use “device_id:x-secret-key”

Note: In this example, the following fields are used:

previous

(Optional.) True or false. Instead of getting a file or directory's contents, get its list of previous versions.

device_id

The same device_id used for login.

x-secret-key

The secret key obtained after running login.

The result, in JSON format, is of the form:

{
  "type": "directory",
  "name": "/full/path/to/dirname",
  "versions": [
    {"version_time":1336049867, "mod_time": 1336049977},
    {"version_time":1336049977, "mod_time": 1336049537},
    {"version_time":1336050987, "mod_time": 1335986914}
  ]
}

Example: downloading a single file

curl -k -u "apple001:gWTklSZs9EpuAo3yM3TymvdbscaKeQ6H37=" -o <local-path-to- file> https://hostname/mobileapi/1/fs/full/path/to/file

Note: In this example, the cURL switches include the following:

-k

-o <local-path-to- file>

Output file format.

-u

Use “device_id:x-secret-key”

Note: In this example, the following fields are used:

device_id

The same device_id used for login.

x-secret-key

The secret key obtained after running login.

Notes for fs

This field is also available:

version_time

(Optional.) Specifies which version of the file or directory to retrieve.

It is possible to continue traversing the previous version of a directory to deeper directories and files. For example, suppose you are looking at version 1336050987 of directory /A/B/C, which contains a directory D. You can get the contents of D by issuing a GET request to /A/B/C/D?version_time=1336050987.

Furthermore, if D contains a file F, you can retrieve that file by issuing a GET request to /A/B/C/D/F?version_time=1336050987.

However, you cannot see the previous versions of F (or D). That is, this request is invalid: /A/B/C/D/F?version_time=1336050987&previous=true.

Calling GET on the root directory / results in a list of shares.

Note: There are no previous versions of /.

Upload file

Upload a file to the Nasuni Edge Appliance.

Note: You cannot upload a file to the root level, since that is a list of CIFS (SMB) shares.

URL

/mobileapi/1/fs/<path_including_new_filename>

Method

PUT

Request Headers

Authorization: Basic <device_id>:<x-secret-key>

content-length: the size of the file to upload.

~~X-NAS-Options: generate_etag. Use entity tags (ETag)~~ ~~ETag Specification~~ ~~to allow client caching of results. See ETag Behavior on page 31.~~

Request Body

The raw bytes to be stored.

Parameters

path_including_new_filename

Path to the new file in the Nasuni Edge Appliance, including the new filename.

Return codes

200: Success.

401: Authentication failure.

403: Permission denied.

404: Parent directory not found.

409: File or directory already exists.

410: device_id is disabled on the Nasuni Edge Appliance for this particular device. Authorization using a different device_id is necessary.

Response headers:

ETag: If client requested generation of an ETag.

cURL example

curl –X PUT -k -T file.txt -u "apple001:gWTklSZs9EpuAo3yM3TymvdbscaKeQ6H37=" https://hostname/mobileapi/1/fs/full/path/to/ newfilename.txt

Note: In this example, the cURL switches include the following:

-X

Specifies a custom request method to use when communicating with the HTTP server. The specified request is used instead of the method otherwise used (which defaults to GET).

-k

-u

Use “device_id:x-secret-key”

-T <file>

This transfers the specified local file to the remote URL.

You can specify one -T for each URL on the command line. Each
-T + URL pair specifies what to upload and to where.

Note: In this example, the following fields are used:

device_id

The same device_id used for login.

x-secret-key

The secret key obtained after running login.

Notes for fs

These fields are also available:

mod_time

(Optional.) Integer. The last modification time of the file on upload, in seconds since 1970.

overwrite

(Optional.) True or false. Overwrite destination file if it exists.

createparents

(Optional.) True or false. Create parent directories if they do not exist.

Download files

Download multiple files as a zip archive.

URL

/mobileapi/1/fs/<path>?action=MULTIDL

Method

POST

Request Headers

Authorization: Basic <device_id>:<x-secret-key>

Parameters

action

multidl

paths

Multiple entries containing the relative paths to include in the archive. Path names do not include the path provided in the URL. See examples:

paths = /1920x1200
paths = /models
paths = /1280x1024/raver_1280x1024.jpg

Return codes

200: Success.

400: Invalid input, such as a directory name that ends in a dot, which is illegal on Windows.

401: Authentication failure.

403: Permission denied.

404: Parent directory not found.

409: Conflict. Reach max-size or max-files constraint when building zip archive.

411: No paths specified.

cURL example

curl -k -u "device_id:x-secret-key" -o <local-path-to-zip-file> https://hostname/mobileapi/1/fs/full/path/to/filename.extension?action=MULTIDL

Note: In this example, the cURL switches include the following:

-k

-u

Use “device_id:x-secret-key”

-o <local-path-to-zip-file>

Output file in .zip format.

Note: In this example, the following fields are used:

device_id

The same device_id used for login.

x-secret-key

The secret key obtained after running login.

Create directory

Create a directory in the Nasuni Edge Appliance.

Note: You cannot create a directory at the root level, since that is a list of CIFS (SMB) shares.

URL

/mobileapi/1/fs/<path_including_dir_name>?action=MKDIR

Method

POST

Request Headers

Authorization: Basic <device_id>:<x-secret-key>

Parameters

path_including_dir_name

Path to the new directory in the Nasuni Edge Appliance, including the new directory name.

action=MKDIR

Required.

mod_time

(Optional.) Integer. The last modification time of the directory on creation, in seconds since 1970.

Return codes

200: Success.

204: No content (success).

400: Invalid input, such as a directory name that ends in a dot, which is illegal on Windows.

401: Authentication failure.

403: Permission denied.

404: Parent directory not found.

409: File or directory already exists.

410: device_id is disabled on the Nasuni Edge Appliance for this particular device. Authorization using a different device_id is necessary.

cURL example

curl –X POST -k -u "apple001:gWTklSZs9EpuAo3yM3TymvdbscaKeQ6H37=" https://hostname/mobileapi/1/fs/full/path/to/dir/ ?action=MKDIR

Note: In this example, the cURL switches include the following:

-X

Specifies a custom request method to use when communicating with the HTTP server. The specified request is used instead of the method otherwise used (which defaults to GET).

-k

-u

Use “device_id:x-secret-key”

Note: In this example, the following fields are used:

action=MKDIR

Action to make a new directory.

device_id

The same device_id used for login.

x-secret-key

The secret key obtained after running login.

Rename or move file or directory

Rename a file or directory, or move a file or directory within a share.

URL

mobileapi/1/fs/full/path/to/item?action=RENAME&to_path=<full_path_within_share_to_destination>

Method

POST

Request Headers

Authorization: Basic <device_id>:<x-secret-key>

Parameters

action

"RENAME", if renaming or moving a file or directory.

to_path

If this is a move, the full path within the share to move the file or directory to. If this is a move, this path and the source path must include the name of the source directory.
If this is a rename, the full path within the share of the new name of the file or directory. Unlike the full path used for the source, DO NOT include the share name in this path.
For example, if this were the source:

https://file.company.com/mobileapi/1/fs/SHR/top/mid/file.jpg

The associated to_path would be:

/top/mid/file.jpg

If-Match

(Optional.) ETag string: if set, the operation only proceeds if the source file ETag matches.

Return codes

204: Renamed or moved successfully.

400: Invalid input: either missing a leading “/” or contains a trailing “/”.

401: Authentication failure, such as bad device ID, username, or password.

403: Permission denied.

404: Target directory not found.

409: File or directory already exists. Or ETag does not match when If-Match is specified.

410: device_id is disabled on the Nasuni Edge Appliance for this particular device. Authorization using a different device_id is necessary. Wipe cache and favorites.

cURL examples

Moving a file:

curl -X POST -k -u "apple001:gWTklSZs9EpuAo3yM3TymvdbscaKeQ6H37=" https://file.company.com/1/fs/SHR/Top/mid/file.jpg ?action=RENAME &to_path=/top/mid/New%20destination/file.jpg

When moving a file, the to_path would include the desired path for the move within the share, including the file name.

Moving a directory:

curl -X POST -k -u "apple001:gWTklSZs9EpuAo3yM3TymvdbscaKeQ6H37=" https://file.company.com/1/fs/SHR/top/mid &action=RENAME &to_path=/top/NewDirectory/mid

In this example, we're moving the "mid" directory to another directory named "NewDirectory", specified in the to_path. The “mid” directory must appear in both the source path and the destination path.

Renaming a file:

curl -X POST -k
-u "apple001:gWTklSZs9EpuAo3yM3TymvdbscaKeQ6H37=" https://file.company.com/1/fs/SHR/top/mid/file.jpg ?action=RENAME &to_path=/top/mid/file-new.jpg

By specifying a new file name for a file as part of the to_path, a rename operation occurs.

Note: In this example, the cURL switches include the following:

-X

Specifies a custom request method to use when communicating with the HTTP server. The specified request is used instead of the method otherwise used (which defaults to GET).

-k

-u

Use “device_id:x-secret-key”

Note: In this example, the following fields are used:

action=RENAME

Action to rename a file or directory.

to_path

For example, if this were the source:

https://file.company.com/mobileapi/1/fs/SHR/top/mid/file.jpg

The associated to_path would be:

/top/mid/file.jpg

device_id

The same device_id used for login.

x-secret-key

The secret key obtained after running login.

Delete file or directory

Delete a file or directory.

You cannot delete a non-empty directory. You also cannot delete a directory at the root level, since they are shares.

URL

/mobileapi/1/fs/<full_path_to_file_or_dir>

Method

DELETE

Request Headers

Authorization: Basic <device_id>:<x-secret-key>

Parameters

full_path_to_file_or_dir

Return codes

204: Deleted successfully.

401: Authentication failure, such as bad device ID, username, or password.

403: Permission denied.

404: File or directory not found.

409: Directory not empty.

410: device_id is disabled on the Nasuni Edge Appliance for this particular device. Authorization using a different device_id is necessary.

cURL example

curl –X DELETE -k -u "apple001:gWTklSZs9EpuAo3yM3TymvdbscaKeQ6H37=" https://hostname/mobileapi/1/fs/full/path/to/ file_or_dir

Note: In this example, the cURL switches include the following:

-X

Specifies a custom request method to use when communicating with the HTTP server. The specified request is used instead of the method otherwise used (which defaults to GET).

-k

-u

Use “device_id:x-secret-key”

Note: In this example, the following fields are used:

device_id

The same device_id used for login.

x-secret-key

The secret key obtained after running login.

Exists query

Check if a file or directory exists.

URL

/mobileapi/1/fs/<path>

Method

HEAD

Request Headers

Authorization: Basic <device_id>:<x-secret-key>

Response headers:

x-size: Size of file.

x-modtime: Modification date of file or directory.

x-object-type: One of shares, share, directory, versions, or file.

Parameters

Return codes

200: Success.

401: Authentication failure, such as bad device ID, username, or password.

403: Permission denied.

404: File or directory not found.

410: device_id is disabled on the Nasuni Edge Appliance for this particular device. Authorization using a different device_id is necessary.

cURL example

curl –i –X HEAD -k -u "apple001:gWTklSZs9EpuAo3yM3TymvdbscaKeQ6H37=" https://hostname/mobileapi/1/fs/full/path/to/file_or_dir

Note: In this example, the cURL switches include the following:

-i

Include the HTTP-header in the output. The HTTP-header includes information like server-name, date of the document, HTTP-version and more.

-X

Specifies a custom request method to use when communicating with the HTTP server. The specified request is used instead of the method otherwise used (which defaults to GET).

-k

-u

Use “device_id:x-secret-key”

Note: In this example, the following fields are used:

device_id

The same device_id used for login.

x-secret-key

The secret key obtained after running login.

Output:

HTTP/1.1 200 OK date: Fri, 04 May 2012 20:22:21 GMT Server: uvicorn x-size: 0 x-modtime: 1336162154 x-object-type: directory connection: Keep-Alive content-type: text/plain; charset=UTF-8

List of return codes

200: Success.

204: Deleted successfully.

206: Partial range satisfied.

304: Not modified.

400: Invalid input, such as a directory name that ends in a dot, which is illegal on Windows.

401: Authentication failure, such as bad device ID, username, or password.

403: Permission denied.

404: Object not found.

409: File or directory already exists. Or directory not empty.

410: device_id is disabled on the Nasuni Edge Appliance for this particular device. Authorization using a different device_id is necessary.

416: Range requested but cannot be satisfied.