Managing Files

This describes the web services that manage media, message media and REST log files that reside on the file store for an account on Aculab Cloud.

When specifying directories, use forward slash as the delimiter.

For services that accept a filetype parameter, the options are "media", "msg_media" or "rest". These correspond to Media, Message media and REST log on the Files menu of the Cloud Console. When working with REST application log files, choose "rest". When working with wav or tiff files, for UAS or REST applications, choose "media". When working with image files for messages, choose "msg_media".

Any image file formats can be uploaded for message media and for these files, it is recommended that you set contenttype.

Media files (unencrypted):

Unencrypted media files are uploaded using File Write. Their format is immediately checked for compatibility. Files that are uploaded for the first time (unique name) will then be immediately available in the media store. Files that are uploaded that overwrite existing files may take some time to be updated across the system.

Encrypted media files:

To upload a file that you have encrypted, use File Write with the encrypted flag set to true.

Note that encrypted files cannot be checked for compatibility on upload, as they are encrypted. Instead they will be validated just before use when your application provides the decryption keys. For REST, this will be done automatically when you request an action that uses the encrypted file. For UAS, you request the validation and file use seperately in your application. This allows your application to check that it has a valid file before taking further actions.

Messsage media does not support encrypted files.

This is a low level API. For information on higher level APIs see the High-level Language Wrappers

File List

This lists all the files of a specified type present on the file store of a cloud account. An optional prefix can be specified to determine a subset of files to list.

Authorisation

This API uses basic authentication, using your cloud account username and API Access Key.

Username	:	cloudID/username (e.g. 1-2-0/bob@example.com)
Password	:	API Access key

Request:

Url	:	https://ws.aculabcloud.net/file_list
Methods	:	GET, POST

Parameter	Value	Description
filetype	string	the type of files to list ("media", "msg_media" or "rest").
filename	string (optional)	a filename to match. Matches just one file whose name is this string. An empty string matches all files in all folders (the default). The last character can be a '*' wildcard in which case the preceding filename acts exactly as prefix does and lists all files that start with it. If both filename and prefix are provided, filename takes precedence.
prefix	string (optional)	a prefix to match. Matches any file whose name starts with the string. An empty string matches all files in all folders (the default). If both filename and prefix are provided, filename takes precedence.
maxcount	integer (optional)	the maximum number of files to list. The default is 10,000 which is also the maximum value for this parameter.
startpos	integer (optional)	the zero-based index of the first file to list. This enables files to be listed in batches when more than 10,000 are present on the cloud. The default is 0. (Deprecated. Use startafter instead)
to	string (optional)	indicates a selected range of files to list, in the format YYYY-MM-DD_hh:mm:ss. If specified, will limit return of filenames where the modified date is up to the time (inclusive) given. May be used with from to select ranges of dates.
from	string (optional)	indicates a selected range of files to list, in the format YYYY-MM-DD_hh:mm:ss. If specified, will limit return of filenames where the modified date is after the time (inclusive) given. May be used with to to select ranges of dates.
startafter	string (optional)	A filename to use to start listing files after. Use the last filename from a previous result to page through all available media files.

Returns:

A JSON object containing the files stored on the cloud account together with details of each file represented in a JSON object.

Parameter	Value	Description
modified	string	the last modification time for the file formatted as YYYY-MM-DD_hh:mm:ss.
size	integer	the size of the file in bytes.
encrypted	boolean	true if the file is encrypted, false if the file is unencrypted.
expiry_date	string	the expiry date (UTC) of the file formatted as YYYY-MM-DD_hh:mm:ss. It is empty if time to live has not been set.

Example:

https://ws.aculabcloud.net/file_list?filetype=media&prefix=recordings/voice

Response:

  {
    "recordings/voicemail/recording_1.wav":
    {
      "modified": "2016-09-30_05:54:47", 
      "encrypted": true,
      "size": 254034,
      "expiry_date": "2017-01-20_10:34:00" 
    }, 
    "recordings/voicemail/recording_2.wav":
    {
      "modified": "2016-09-30_10:31:44", 
      "encrypted": false,
      "size": 245634
    } 
  }

Folder List

This shows a folder view of a given folder name on the file store of an account, listing all the files and folders within that folder.

Authorisation

This API uses basic authentication, using your cloud account username and API Access Key.

Username	:	cloudID/username (e.g. 1-2-0/bob@example.com)
Password	:	API Access key

Request:

Url	:	https://ws.aculabcloud.net/folder_list
Methods	:	GET, POST

Parameter	Value	Description
filetype	string	the type of files to list ("media", "msg_media" or "rest").
foldername	string (optional)	a folder name to list. Matches the folder whose name equals the string. A trailing '/' is allowed, but not required. An empty string matches the root folder (the default).
prefix	string (optional)	a prefix to match. Matches any file whose name within the folder starts with the string. An empty string matches all the files (the default).
maxcount	integer (optional)	the maximum number of files to list. The default is 10,000 which is also the maximum value for this parameter.
startafter	string (optional)	A filename to use to start listing files after. Use the last filename from a previous result to page through all available media files.
to	string (optional)	indicates a selected range of folders and files to list, in the format YYYY-MM-DD_hh:mm:ss. If specified, will limit return of folders and filenames where the modified date is up to the time (inclusive) given. May be used with from to select ranges of dates.
from	string (optional)	indicates a selected range of folders and files to list, in the format YYYY-MM-DD_hh:mm:ss. If specified, will limit return of folders and filenames where the modified date is after the time (inclusive) given. May be used with to to select ranges of dates.

Returns on success:

A JSON object containing the following parameters:

Parameter	Type	Availability	Description
folders	array	always	an array of folder objects each representing a folder within the specified folder path.
files	array	always	an array of file objects each representing a file within the specified folder path.
startafter	string	present if additional files are available from a further folder_list call	the name of a file within the specified folder path that can be used to obtain the next available folders and files.

Folder object

Parameter	Type	Availability	Description
name	string	always	the name of the folder including the trailing /.

File object

Parameter	Type	Availability	Description
name	string	always	the name of the file.
size	integer	always	the size of the file in bytes.
modified	string	always	the last modification time for the file formatted as YYYY-MM-DD_hh:mm:ss.
encrypted	bool	always	true if the file is encrypted, false if the file is unencrypted.
expiry_date	string	always	the expiry date (UTC) of the file formatted as YYYY-MM-DD_hh:mm:ss. It is empty if time to live has not been set.

Example:

https://ws.aculabcloud.net/folder_list?filetype=media&foldername=test&prefix=record

Response:

{
    "folders": [
        {
            "name": "test/recording_archive/"
        }
    ],
    "files": [
          {
            "name": "test/recording1.wav",
            "modified": "2022-02-01_12:01:32",
            "encrypted": false,
            "expiry_date": "",
            "size": 188490
        }
    ]
}

File Write

This uploads a local media or msg_media file onto the cloud file store for a cloud account.

Only .wav audio and .tif image media files can be uploaded when filetype paramater is set to media. The .tif files are constrained to fax format images.

For msg_media filetypes any file type is allowed, though .gif, .jpg and .png files are checked for correct formatting.

See the Media File Names and Extensions guide regarding file name character and extension restrictions when uploading to the cloud file store.

For a PUT, the file data to upload is the body of the request. For a POST, the body must contain an HTML form, the file data being the value of one of its fields.

Files that are uploaded for the first time (unique name) will then be immediately available in the media store. Files that are uploaded that overwrite existing files may take some time to be updated across the system.

Unencrypted media files

Unencrypted media file formats are checked for compatibility during upload.

Encrypted media files:

To upload a file that you have encrypted, set the encrypted flag to true.

The format of an encrypted file cannot be checked for compatibility on upload, as it is encrypted. Instead it will be validated just before use when your application provides the decryption keys. For REST, this will be done automatically when you request an action that uses the encrypted file. For UAS, you request the validation and file use seperately in your application. This allows your application to check that it has a valid file before taking further actions.

Authorisation

This API uses basic authentication, using your cloud account username and API Access Key.

Username	:	cloudID/username (e.g. 1-2-0/bob@example.com)
Password	:	API Access key

Request:

Url	:	https://ws.aculabcloud.net/file_write
Methods	:	POST, PUT

Parameter	Value	Description
filetype	string	the type of files to write ("media" or "msg_media").
filename	string	the target filename on the cloud file store, including path.
encrypted	string (optional)	whether the file is encrypted ("true", "false"). The default is "false"
time_to_live	string (optional)	the time to live (TTL) of the file, expressed as Xm (X minutes), Xh (X hours), or Xd (X days). By default a file's time to live is unlimited.
contenttype	string (optional)	The media type (also called the MIME type) is derived from the filename extension by default. If the mediatype cannot be guessed, or the default needs to be overridden, then it can be set here. (For example, "image/jpeg".)

Returns:

Nothing.

Example:

https://ws.aculabcloud.net/file_write?filetype=media&filename=mediafiles/message_1.wav

File Move

This renames a file that is present on the file store of a cloud account.

See the Media File Names and Extensions guide regarding file name character and extension restrictions when moving existing files on the cloud file store.

Authorisation

This API uses basic authentication, using your cloud account username and API Access Key.

Username	:	cloudID/username (e.g. 1-2-0/bob@example.com)
Password	:	API Access key

Request:

Url	:	https://ws.aculabcloud.net/file_move
Methods	:	GET, POST, HEAD

Parameter	Value	Description
filetype	string	the type of file to rename ("media" or "msg_media").
from	string	the filename of the file to rename, including path.
to	string	the target filename, including path.

Returns:

Nothing.

Example:

https://ws.aculabcloud.net/file_move?filetype=media&from=rec_1.wav&to=rec_2.wav

File Get

This downloads a file present on the file store of a cloud account.

Authorisation

This API uses basic authentication, using your cloud account username and API Access Key.

Username	:	cloudID/username (e.g. 1-2-0/bob@example.com)
Password	:	API Access key

Request:

Url	:	https://ws.aculabcloud.net/file_get
Methods	:	GET, POST, HEAD

Parameter	Value	Description
filetype	string	the type of file to get ("media", "msg_media" or "rest").
filename	string	the filename of a file on the file store on the cloud to download. This must be an exact match of the file that is to be downloaded. Only one file can be downloaded at a time.

Returns:

The file data.

Example:

https://ws.aculabcloud.net/file_get?filetype=rest&filename=/2013/11/07/rest_16_39_23_058d242936dcc5f9.47610.log

File Delete

This deletes one or more files from the file store of a cloud account. Call file_delete_progress to monitor the progress of the deletion of multiple files.

Authorisation

This API uses basic authentication, using your cloud account username and API Access Key.

Username	:	cloudID/username (e.g. 1-2-0/bob@example.com)
Password	:	API Access key

Request:

Url	:	https://ws.aculabcloud.net/file_delete
Methods	:	DELETE, GET, POST

Parameter	Value	Description
filetype	string	the type of file to delete ("media", "msg_media" or "rest").
filename	string	a filename specifying the file to delete. This can be a prefix followed by a '' to match all files and directories starting with the prefix. Setting to '' will delete all files.
to	string (optional)	indicates a selected range of files to delete, in the format YYYY-MM-DD_hh:mm:ss. If specified, will limit deletion of files where the modified date is up to the time (inclusive) given. May be used with from to select ranges of dates.
from	string (optional)	indicates a selected range of files to delete, in the format YYYY-MM-DD_hh:mm:ss. If specified, will limit deletion of files where the modified date is after the time (inclusive) given. May be used with to to select ranges of dates.

Returns:

A JSON object that contains the following properties:

Parameter	Value	Description
token	string	a token that identifies the deletion requested. This token can be used with the file_delete_progress web service to monitor the progress of a deletion.

Example:

https://ws.aculabcloud.net/file_delete?filetype=media&filename=voicemail*

Response:

  {
    token: "2e8903c1_2.1367569618.101"
  }

File Delete Progress

This retrieves the progress of a file deletion from a cloud account initiated by file_delete.

Authorisation

This API uses basic authentication, using your cloud account username and API Access Key.

Username	:	cloudID/username (e.g. 1-2-0/bob@example.com)
Password	:	API Access key

Request:

Url	:	https://ws.aculabcloud.net/file_delete_progress
Methods	:	GET, POST

Parameter	Value	Description
token	string	a token returned by a call to the file_delete web service.

Returns:

A JSON object describing the status of the deletion.

Parameter	Value	Description
status	string	the status of the deletion. Either "in progress" or "completed".
files_deleted	integer	the number of files deleted. This value will be updated in chunks of up to 10k files while status is 'in progress'. Once the status is 'deleted' then it will contain the total number of files deleted.

Example:

https://ws.aculabcloud.net/file_delete_progress?token=2e8903c1_2.1367569618.101

Response:

200

  {
    "status": "in progress",
    "files_deleted": 10000
  }

400

{
    "error": {
        "code": "0001",
        "text": "'token' is not specified.",
        "datetime": "2022-12-12_11:28:49",
        "link": "https://www.aculab.com/cloud/other-apis/web-services/web-service-errors?error=0900"
    },
    "request": {
        "datetime": "2022-12-12_11:28:49",
        "url": "/file_delete_progress"
    }
}

404

{
    "error": {
        "code": "0405",
        "text": "Invalid token; token is either invalid, lapsed, or otherwise unidentified.",
        "datetime": "2022-12-12_11:32:41",
        "link": "https://www.aculab.com/cloud/other-apis/web-services/web-service-errors?error=0405"
    },
    "request": {
        "datetime": "2022-12-12_11:32:41",
        "url": "/file_delete_progress"
    }
}

Cloud documentation

Managing Files

Media files (unencrypted):

Encrypted media files:

File List

Authorisation

Request:

Returns:

Example:

Response:

Folder List

Authorisation

Request:

Returns on success:

Folder object

File object

Example:

Response:

File Write

Unencrypted media files

Encrypted media files:

Authorisation

Request:

Returns:

Example:

File Move

Authorisation

Request:

Returns:

Example:

File Get

Authorisation

Request:

Returns:

Example:

File Delete

Authorisation

Request:

Returns:

Example:

Response:

File Delete Progress

Authorisation

Request:

Returns:

Example:

Response:

200

400

404

Contact Aculab