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

    ParameterValueDescription
    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.

    ParameterValueDescription
    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

    ParameterValueDescription
    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:

    ParameterTypeAvailabilityDescription
    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

    ParameterTypeAvailabilityDescription
    name string always the name of the folder including the trailing /.

    File object

    ParameterTypeAvailabilityDescription
    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

    ParameterValueDescription
    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

    ParameterValueDescription
    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

    ParameterValueDescription
    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

    ParameterValueDescription
    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:

    ParameterValueDescription
    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

    ParameterValueDescription
    token string a token returned by a call to the file_delete web service.

    Returns:

    A JSON object describing the status of the deletion.

    ParameterValueDescription
    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"
        }
    }
    
  • File Convert

    Converts a file received in the request body to a specified file type. The converted file is then uploaded to the cloud file store of the requester's account. The name of the output file will be a combination of the optional prefix and the job token.

    Currently this service only allows for conversion of PDF documents to TIFF images.

    File Convert is an asynchronous service.

    Call File Convert Progress to monitor the progress of the conversion.

    Maximum page count is 150. Supported document formats A4, B4, and A3 (for more information see Supported Fax Formats).

    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_convert
    Methods : PUT

    ParameterValueDescription
    callback_url string (uri) (optional) URL where the response object will be posted
    file_prefix string (optional) prefix to the randomly generated name of the converted file
    page_range string (optional) range of pages in the PDF to convert (inclusive). Takes a single digit or two digits separated with a dash (see example)

    Callback message:

    Example message sent to the callback URL, if provided.

    {
        "token": "ib6cc8716-64fe-11ed-9304-0a68e3f23e2b",
        "status": "done",
        "converted_file_name": "prefixib6cc8716-64fe-11ed-9304-0a68e3f23e2b.tiff,
    }

    Returns:

    A JSON object that contains the following properties:

    ParameterValueDescription
    token string a token that identifies the conversion request. This token can be used with file_convert_progress web service to monitor the progress of a conversion.

    Example:

    https://ws.aculabcloud.net/file_convert?callback_url=https://my-callback.com&file_prefix=fax&page_range=1-5

    Response:

    200

    {
        "token": "ib6cc8716-64fe-11ed-9304-0a68e3f23e2b"
    }

    400

    {
        "error": {
            "code": "0902",
            "text": "No file found in request body.",
            "datetime": "2023-03-13_11:06:48",
            "link": "https://www.aculab.com/cloud/other-apis/web-services/web-service-errors?error=0902"
        },
        "request": {
            "datetime": "2023-03-13_11:06:48",
            "url": "/file_convert"
        }
    }

    415

    {
        "error": {
            "code": "0901",
            "text": "Unsupported Content-Type.",
            "datetime": "2022-12-15_09:58:24",
            "link": "https://www.aculab.com/cloud/other-apis/web-services/web-service-errors?error=0901"
        },
        "request": {
            "datetime": "2022-12-15_09:58:24",
            "url": "/file_convert"
        }
    }
  • File Convert Progress

    Uses the token returned by File Convert to retrieve the status of an existing converion.

    Job status can be accessed for up to one hour after the initial request was made.

    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_convert_status
    Methods : GET

    ParameterValueDescription
    token string a token returned by a call to the file_convert service.

    Returns on success:

    A JSON object that contains the following properties:

    ParameterValueDescription
    token string a token that identies the conversion request. This token can be used with file_convert_progress web service to monitor the progress of a conversion.
    status string the status of the conversion. Either "queued", "processing", or "done".
    converted_file_name string the name of the converted file. Consists of the optional prefix, job token, and file extension.
    last_update_ts string date and time of the last time the job status was updated.

    Example:

    https://ws.aculabcloud.net/file_convert_progress?token=3f68ed4b-43d8-11ed-a430-ac74b1c63779

    Responses:

    200

    {
        "token": "ib6cc8716-64fe-11ed-9304-0a68e3f23e2b",
        "status": "done",
        "converted_file_name": "fax_3f68ed4b-43d8-11ed-a430-ac74b1c63779.tiff",
        "last_update_ts": "2022-11-14 13:44:02 UTC"
    }

    400

    {
        "error": {
            "code": "0001",
            "text": "'token' is not specified.",
            "datetime": "2023-03-13_11:09:11",
            "link": "https://www.aculab.com/cloud/other-apis/web-services/web-service-errors?error=0001"
        },
        "request": {
            "datetime": "2023-03-13_11:09:11",
            "url": "/file_convert_progress"
        }
    }

    404

    {
        "error": {
            "code": "0900",
            "text": "Convert job not found. Token is invalid, lapsed, or otherwise or otherwise unidentified.",
            "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_convert_progress"
        }
    }