Overview

This is the documentation for v1.0 of the SmartFile API.

Authentication

Once you have authorized API access, you must provide your API key and password with each request made to the API. HTTP Basic Authentication (RFC 2617 section 2) must be used.

Response format

By default, JSON is the format used for responses. Different formats are available by including format= with the request.

For example, 'format=xml' included in the URL for a GET request or as part of the data in other HTTP methods will provide the response in XML format for those requests that return data.

Available formats: JSON, XML

HTTPS/Security

Our API fully supports HTTPS with a valid certificate. It is strongly recommended that you take adavange of HTTPS when using the SmartFile API. This will protect your API key and password as well as any other sensitive data on the wire.

API Methods

  1. Path API
    1. read
    2. create
    3. update
    4. delete
  2. Package API
    1. read
  3. Site API
    1. read
    2. create
    3. update
  4. User API
    1. read
    2. create
    3. update
    4. delete
  5. SiteUser API
    1. read
    2. update

Path API

An API to interact with files and directories stored in SmartFile.

Using this API, you can perform the following actions.

  • Create new file or directory.
  • Read a file's or directory's details.
  • Update an existing file or directory.
  • Delete a file or directory.

method read(path=/):

URL: GET /api/1.0/paths/list__PATH__

Return information about the requested path. Additional information is available via special request.

Acceptable Fields:

  • checksum=<algorithm>

    Where <algorithm> is any of the following algorithms. The file's contents will be checksummed and the result returned as hex encoded binary data.

    • MD5
    • SHA1
    • SHA256
    • SHA512
    • CRC-32

  • recurse=<depth>

    Where <depth> is the recursion depth to be obtained. By default only information about the requested path is returned. If you enable recursion then a subtree will be produced. You can control how deeply this subtree is explored by adjusting the <depth> value. For unlimited recursion, pass the special value "all", otherwise provide an integer. For example, a value of 1 will cause only the immediate children of the requested path to be returned.

  • download=<ignored>

This parameter if present will trigger the creation of a URL that can be used to download the file's contents. Only the presence of this key is important, a value is not required. This parameter is valid only for files.

Status codes:

  • 200 - Path information returned
  • 400 - Invalid request
  • 403 - Forbidden to access path
  • 404 - Path is invalid or does not exist

Return Value: object or list of objects consisting of the following fields.

  • path - The location of the path.
  • name - The name of the file (excluding parent paths).
  • extension - The path's extension.
  • size - The size in bytes of the path. For directories, the size refers to the size of the directory's sub-tree.
  • size_pretty - The size in human readable form.
  • mime - Mime type of the path.
  • created - The timestamp of the path's creation.
  • updated - The timestamp of the path's last modification.
  • checksum - The checksum of the file using the requested algorithm (Returned only if requested).
  • children - The children of the requested path returned as a list of objects. These objects may themselves have children if the recursion depth requested allows exploration to that level. (Returned only if requested).
  • download - A URL that can be used to retrieve the file. This URL expires after 2 minutes. (Returned only if requested).

method create(path=/):

URL: POST /api/1.0/paths/add__PATH__

Creates a file or directory at the requested path. By default, items with an extension will be created as blank files. Items lacking an extension will be created as directories. You can override this behavior by passing either file, or directory parameters. Only file OR directory can be present, if both are present, the request will result in an error.

Acceptable Fields:

  • file=<ignored>
If this parameter is present it will trigger the creation of a blank file. A URL will be returned as the upload return field. This URL can be used to POST the file contents to.
  • directory=<ignored>
If this parameter is present it will trigger the creation of a directory.

Status codes:

  • 201 - New path created and information returned
  • 400 - Invalid request
  • 403 - Forbidden to access path
  • 404 - Path is invalid or does not exist

Return Value: object consisting of the following fields.

  • path - The location of the path.
  • name - The name of the file (excluding parent paths).
  • extension - The path's extension.
  • size - The size in bytes of the path. For directories, the size refers to the size of the directory's sub-tree.
  • size_pretty - The size in human readable form.
  • mime - Mime type of the path.
  • created - The timestamp of the path's creation.
  • updated - The timestamp of the path's last modification.
  • upload - The URL to POST the file's contents to. Only returned when a file has been created.

method update(path=/):

URL: PUT /api/1.0/paths/edit__PATH__

Update the requested path. You can edit the path's attributes as well as request a URL to upload new file contents to.

method delete(path=/):

URL: DELETE /api/1.0/paths/delete__PATH__

Delete the requested path. Directories are deleted recursively.

Be careful with this API call, deleted files are immediately removed from storage and they cannot be retrieved!

Package API

An API to manage reseller packages. As a reseller, you are able to define the packages you offer to your customers. If you use a CRM package or other customer management software, you can use this API to retrieve a list of avaialable packages as defined in your SmartFile reseller panel.

Using this API, you can perform the following actions.

  • Read your package information.

method read(package=<optional>):

URL: GET /api/1.0/reseller/packages/list/__PACKAGE__/

Without a package name, this method will return a list of the packages defined within your reseller panel. If given a package name, then the details of that package will be returned.

Status codes:

  • 200 - Package or package list returned
  • 403 - Forbidden to access package or package list
  • 404 - Unknown package name

Return Value: object or list of objects consisting of the following fields.

  • name

Site API

API to interact with a SmartFile reseller account. As a SmartFile reseller, you have the ability to manage your own sites.

Using this API, you can perform the following actions.

method read(site=<optional>):

URL: GET /api/1.0/reseller/sites/list/__SITE__/

Return the requested site or if no specific site is requested, then provide a list of sites. All sites returned are in association with the reseller.

Status codes:

  • 200 - Site or site list returned
  • 404 - Site(s) not found in assocation with the reseller

method create():

URL: POST /api/1.0/reseller/sites/add/

Create a seller, using a unique name, associated with the authenticated reseller. Upon success, the response will contain a Location header of the newly created site.

Acceptable fields:

  • site_name - required
  • industry - required.
    Accepted choices for industry:
    • Personal Use
    • Software
    • Marketing/Design
    • Print/Publishing
    • Construction
    • Accounting
    • Law
    • Medical
    • Professional Services
    • Other
  • package - required
  • username - required
  • fullname - required
  • password - required
  • email - optional (required if send_email is True)
  • send_email (True or False; default True) - optional

Status codes:

  • 201 - Created
  • 400 - Bad request that did not pass form validation
  • 403 - Forbidden (reseller site is over disk quota)
  • 409 - Existing site found

method update(site):

URL: PUT /api/1.0/reseller/sites/edit/__SITE__/

Update a site associated with the reseller. Upon success, the response will contain the edited site.

Acceptable fields:

  • package - optional
  • active (True or False) - optional

Status codes:

  • 200 - Update successful
  • 400 - Bad request that did not pass form validation
  • 403 - Forbidden to access user
  • 404 - Site not found in assocation with the reseller

User API

An API to interact with users in the SmartFile system.

Using this API, you can perform the following actions.

  • Create new users.
  • Read a user's details, or retrieve a list of users.
  • Update an existing user.
  • Delete a user.

method read(username=<optional>):

URL: GET /api/1.0/users/list/__USERNAME__/

Return the requested user or if no specific user is requested, then provide a list of users related to the authenticated user.

Status codes:

  • 200 - User or user list returned
  • 403 - Forbidden to access user
  • 404 - User not found within realm

Return Value: object, or list of objects consisting of the following fields.

  • username - The user's unique identifier.
  • root - The user's home directory.
  • name - The user's full name.
  • email - The user's email address.
  • ftp_active - Whether or not the user has FTP access; True or False.
  • active - Whether or not the user is activated (can login).
  • groups - List of group(s) the user belongs. Present only if the user belongs to at least one group.
  • role - The permissions the user has within SmartFile.

method create():

URL: POST /api/1.0/users/add/

Create a user, using a unique username, associated with the authenticated user. Upon success, the response will contain a Location header of the newly created user.

Acceptable fields:

  • username - required
  • root (path for user; default is '/') - optional
  • name (full name) - required
  • email - optional (required if send_email is True)
  • send_email (True or False; default True) - optional
  • password - required
  • ftp_active (True or False; default True) - optional
  • active (True or False; default True) - optional
  • groups (multiple times for more than one group) - optional
  • role (User, Manager, Administrator; default is User) - optional

Status codes:

  • 201 - Created
  • 400 - Bad request that did not pass form validation
  • 409 - Existing user found

Return Value: None

method update(username):

URL: PUT /api/1.0/users/edit/__USERNAME__/

Update a user associated with the authenticated user. Upon success, the response will contain the edited user.

Acceptable fields:

  • username - optional
  • root (path for user; default is '/') - optional
  • name (full name) - optional
  • email - optional
  • password - optional
  • ftp_active (True or False) - optional
  • active (True or False) - optional
  • groups (multiple times for more than one group. To remove a user from all groups, send a single empty group) - optional
  • role (User, Manager, Administrator) - optional

Status codes:

  • 200 - Update successful
  • 400 - Bad request that did not pass form validation
  • 403 - Forbidden to access user
  • 404 - User not found within realm

Return Value: None

method delete(username):

URL: DELETE /api/1.0/users/delete/__USERNAME__/

Delete a user associated with the authenticated user.

Status codes:

  • 204 - Deleted
  • 400 - Unable to delete oneself
  • 404 - User not found within realm
  • 500 - Server error

Return value: None

SiteUser API

API to interact with the Users of a Site. This API is meant for resellers to manage the Users of the Sites.

Using this API, you can perform the following actions.

  • Read a site's user information.
  • Update a site's user information.

method read(site, username=<optional>):

URL: GET /api/1.0/reseller/sites/edit/__SITE__/users/list/__USERNAME__/

From a specific site associated with a reseller, return the requested user or if no specific user is requested, then provide a list of users related to the site.

Status codes:

  • 200 - User or user list returned
  • 403 - Forbidden to access site
  • 404 - Site or user not found in association with the reseller

Return Value: object, or list of objects consisting of the following fields.

  • username - The user's unique identifier.
  • name - The user's full name.
  • email - The user's email address.
  • active - Whether or not the user is activated (can login).

method update(site, username):

URL: PUT /api/1.0/reseller/sites/edit/__SITE__/users/edit/__USERNAME__/

Update a user from a specific site associated with the reseller. Upon success, the response will contain the edited user.

Acceptable fields:

  • password - optional
  • active (True or False) - optional

Status codes:

  • 200 - Update successful
  • 400 - Bad request that did not pass form validation
  • 403 - Forbidden to access site
  • 404 - Site or user not found in association with the reseller

Return Value: object consisting of the following fields.

  • username - The user's unique identifier.
  • name - The user's full name.
  • email - The user's email address.
  • active - Whether or not the user is activated (can login).