Storage

The storage system offers the necessary endpoints to upload, download, list, delete and organize any amount of unstructured data. The services are presented in three sections, namely Files, Folder, and Administration. Notice that the API is designed to be idempotent. Therefore, consecutive calls to the same endpoint with equal parameters will always have the same effect.

Files

These are the available endpoints for file operations, allowing to store and retrieve any kind of data.

POST /storage/file/upload/{folder}

Upload a file to a folder. When the folder variable is missing, it is uploaded to the root directory.

Parameters

FieldSourceMandatoryTypeDescription
folderQueryStringDestination folder
fileFormMultipart fileFile
curl -L -X POST 'https://api.sherpalive.com/v2/storage/file/upload/my-folder' \
-H  "X-Sherpa-apikey: XXXX-SHERPA-DELIVERED-PUBLIC-APIKEY-XXXX" \
-H  "X-Sherpa-timestamp: 1748084514112" \
-H  "X-Sherpa-nonce: XXXX-SHERPA-RAMDOM-UUID-XXXX" \
-H  "X-Sherpa-hmac: xxxxyyyyyyy***signature******" \
-H  'Accept-Language: es-ES' \
-H  'Content-Type: multipart/form-data'
-H  'Time-Zone: Europe/Madrid' \
-F  'file=@/path/to/aFile.txt'

Response

The service will return the file and folder names. It returns a 404 error if the folder does not exist.

CodeName
200OK
401Unauthorized
404Not found
500Internal Server Error
{
  "file": "aFile.txt",
  "folder": "my-folder"
}

GET /storage/file/download/{folder}/{file}

Download a file. The file is downloaded from the root directory when no folder is indicated.

Parameters

FieldSourceMandatoryTypeDescription
folderQueryStringSource folder
fileQueryStringFile
curl -L -X GET 'https://api.sherpalive.com/v2/storage/file/download/my-folder/aFile.txt' \
-H  "X-Sherpa-apikey: XXXX-SHERPA-DELIVERED-PUBLIC-APIKEY-XXXX" \
-H  "X-Sherpa-timestamp: 1748084514112" \
-H  "X-Sherpa-nonce: XXXX-SHERPA-RAMDOM-UUID-XXXX" \
-H  "X-Sherpa-hmac: xxxxyyyyyyy***signature******" \
-H  'Accept-Language: es-ES' \
-H  'Time-Zone: Europe/Madrid'

Response

The service will return the raw file. It returns a 404 error if the file does not exist.

CodeName
200OK
401Unauthorized
404Not found
500Internal Server Error

GET /storage/file/exists/{folder}/{file}

Checks if a file with the requested name exists in the target folder. When the folder variable is missing, it will check for existance in the root directory.

Parameters

FieldSourceMandatoryTypeDescription
folderQueryStringFolder
fileQueryStringFile
curl -L -X GET 'https://api.sherpalive.com/v2/storage/file/exists/my-folder/aFile.txt' \
-H  "X-Sherpa-apikey: XXXX-SHERPA-DELIVERED-PUBLIC-APIKEY-XXXX" \
-H  "X-Sherpa-timestamp: 1748084514112" \
-H  "X-Sherpa-nonce: XXXX-SHERPA-RAMDOM-UUID-XXXX" \
-H  "X-Sherpa-hmac: xxxxyyyyyyy***signature******" \
-H  'Accept-Language: es-ES' \
-H  'Time-Zone: Europe/Madrid'

Response

The file return true or false.

CodeName
200OK
401Unauthorized
500Internal Server Error

DELETE /storage/file/delete/{folder}/{file}

Delete a file. The file will be deleted from the root directory when the folder variable is missing.

Parameters

FieldSourceMandatoryTypeDescription
folderQueryStringFolder
fileQueryStringFile
curl -L -X DELETE 'https://api.sherpalive.com/v2/storage/file/delete/my-folder/aFile.txt' \
-H  "X-Sherpa-apikey: XXXX-SHERPA-DELIVERED-PUBLIC-APIKEY-XXXX" \
-H  "X-Sherpa-timestamp: 1748084514112" \
-H  "X-Sherpa-nonce: XXXX-SHERPA-RAMDOM-UUID-XXXX" \
-H  "X-Sherpa-hmac: xxxxyyyyyyy***signature******" \
-H  'Accept-Language: es-ES' \
-H  'Time-Zone: Europe/Madrid'

Response

The service ensures that the file does not exist. Therefore, the same response is provided whether the file specified in the request was found or not.

CodeName
204No response
401Unauthorized
500Internal Server Error

DELETE /storage/file/deletes/{folder}

Delete several files. The files will be deleted from the root directory when the folder variable is missing.

Parameters

FieldSourceMandatoryTypeDescription
folderQueryStringFolder
filesFormList of stringsNames of the files to be deleted
curl -L -X DELETE 'https://api.sherpalive.com/v2/storage/file/delete/my-folder/' \
-H  "X-Sherpa-apikey: XXXX-SHERPA-DELIVERED-PUBLIC-APIKEY-XXXX" \
-H  "X-Sherpa-timestamp: 1748084514112" \
-H  "X-Sherpa-nonce: XXXX-SHERPA-RAMDOM-UUID-XXXX" \
-H  "X-Sherpa-hmac: xxxxyyyyyyy***signature******" \
-H  'Accept-Language: es-ES' \
-H  'Time-Zone: Europe/Madrid' \
-F  'files=a-file.txt,otherFile,another_file.mp3'

Response

The service ensures that the files do not exist. Therefore, the same response is provided whether the files were found or not.

CodeName
204No response
401Unauthorized
500Internal Server Error

GET /storage/file/list/{folder}?prefix={prefix}&suffix={suffix}&from={from}&to={to}&minSize={minSize}&maxSize={maxSize}

List the files located in the requested folder. If the folder variable is missing, list the files in the root directory. The request allows to filter the results using the following additive criteria: returning only files with names that start with a prefix and/or end with a suffix, files last modified later that a from timestamp and/or earlier than a to timestamp, and files bigger than and/or smaller than the provided minSize and maxSize parameters. All the filtering parameters are optional.

Parameters

FieldSourceMandatoryTypeDescription
folderQueryStringFolder name
prefixQueryStringPrefix
suffixQueryStringSuffix
fromQueryLongTimestamp in UNIX time milliseconds
toQueryLongTimestamp in UNIX time milliseconds
minSizeQueryLongMinimum size in bytes
maxSizeQueryLongMaximum size in bytes
curl -L -X GET 'https://api.sherpalive.com/v2/storage/file/list/my-folder?prefix=API&'\
               'suffix=json&from=0&to=5000000000000&minSize=150000&maxSize=1000000' \
-H  "X-Sherpa-apikey: XXXX-SHERPA-DELIVERED-PUBLIC-APIKEY-XXXX" \
-H  "X-Sherpa-timestamp: 1748084514112" \
-H  "X-Sherpa-nonce: XXXX-SHERPA-RAMDOM-UUID-XXXX" \
-H  "X-Sherpa-hmac: xxxxyyyyyyy***signature******" \
-H  'Accept-Language: es-ES' \
-H  'Time-Zone: Europe/Madrid'

Response

The response is a JSON array of objects. For each file, the following information is provided: The file name, the size (in bytes) and the last modification UTC Unix timestamp (the number of milliseconds from the epoch of 1970-01-01T00:00:00Z). The service does not check if the request folder exists; it returns an empty array when the folder is empty or when it does not exist.

CodeName
200OK
401Unauthorized
500Internal Server Error
[
    {
        "name": "aFile.txt",
        "size": 194426,
        "lastModified": 1604911035000
    }
]

Folders

These are the available endpoints for folder operations, allowing to create, list or delete folders. The API allows one level of depth, i.e. all created folders will be located in the root directory.

PUT /storage/folder/create/{folder}

Create a folder.

Parameters

FieldSourceMandatoryTypeDescription
folderQueryStringFolder name
curl -L -X PUT 'https://api.sherpalive.com/v2/storage/folder/my-folder' \
-H  "X-Sherpa-apikey: XXXX-SHERPA-DELIVERED-PUBLIC-APIKEY-XXXX" \
-H  "X-Sherpa-timestamp: 1748084514112" \
-H  "X-Sherpa-nonce: XXXX-SHERPA-RAMDOM-UUID-XXXX" \
-H  "X-Sherpa-hmac: xxxxyyyyyyy***signature******" \
-H  'Accept-Language: es-ES' \
-H  'Time-Zone: Europe/Madrid'

Response

The service ensures that the folder exists. It will not return an error code if the folder already exists.

CodeName
200OK
401Unauthorized
500Internal Server Error

GET /storage/folder/exists/{folder}
Checks if a folder with the requested name exists.

Parameters

FieldSourceMandatoryTypeDescription
folderQueryStringFolder
curl -L -X GET 'https://api.sherpalive.com/v2/storage/folder/exists/my-folder' \
-H  "X-Sherpa-apikey: XXXX-SHERPA-DELIVERED-PUBLIC-APIKEY-XXXX" \
-H  "X-Sherpa-timestamp: 1748084514112" \
-H  "X-Sherpa-nonce: XXXX-SHERPA-RAMDOM-UUID-XXXX" \
-H  "X-Sherpa-hmac: xxxxyyyyyyy***signature******" \
-H  'Accept-Language: es-ES' \
-H  'Time-Zone: Europe/Madrid'

Response

The file return true or false.

CodeName
200OK
401Unauthorized
500Internal Server Error

DELETE /storage/folder/delete/{folder}

Delete a folder and all its contents.

Parameters

FieldSourceMandatoryTypeDescription
folderQueryStringFolder
curl -L -X DELETE 'https://api.sherpalive.com/v2/storage/folder/delete/my-folder' \
-H  "X-Sherpa-apikey: XXXX-SHERPA-DELIVERED-PUBLIC-APIKEY-XXXX" \
-H  "X-Sherpa-timestamp: 1748084514112" \
-H  "X-Sherpa-nonce: XXXX-SHERPA-RAMDOM-UUID-XXXX" \
-H  "X-Sherpa-hmac: xxxxyyyyyyy***signature******" \
-H  'Accept-Language: es-ES' \
-H  'Time-Zone: Europe/Madrid'

Response

The service ensures that the folder does not exist. Therefore, the same response is provided whether the folder specified in the request was found or not.

CodeName
204No response
401Unauthorized
500Internal Server Error

GET /storage/folder/list

List the folders in the user's workspace.

Parameters
This request does not require any parameters

curl -L -X GET 'https://api.sherpalive.com/v2/storage/file/list' \
-H  "X-Sherpa-apikey: XXXX-SHERPA-DELIVERED-PUBLIC-APIKEY-XXXX" \
-H  "X-Sherpa-timestamp: 1748084514112" \
-H  "X-Sherpa-nonce: XXXX-SHERPA-RAMDOM-UUID-XXXX" \
-H  "X-Sherpa-hmac: xxxxyyyyyyy***signature******" \
-H  'Accept-Language: es-ES' \
-H  'Time-Zone: Europe/Madrid'

Response

The response is an array of folder names, empty if there are not any folders.

CodeName
200OK
401Unauthorized
500Internal Server Error
["test-folder", "another-folder"]

Administration

These endpoints perform management tasks in the workspace.

GET /storage/total-size

Gets the total size of the used storage space in the workspace. This quantity is calculated by adding the sizes (in bytes) of all the files contained in the client's workspace.

Response

CodeName
200OK
401Unauthorized
500Internal Server Error

The response is a numeric value, the total amount of storage space (in bytes) used.

DELETE /storage/clear/{token}

Deletes all the files and folders in the user's workspace. When the token variable is not included, this service creates a hash token that has a short expiration date. The token is returned to the user, so he or she may use it in a subsequent call in order to confirm the total erasure of the workspace storage contents.

Parameters

FieldSourceMandatoryTypeDescription
tokenQueryStringConfirmation token

Response

CodeName
200OK
401Unauthorized
500Internal Server Error

Usage example

curl -L -X GET 'https://api.sherpalive.com/v2/storage/clear' \
-H  "X-Sherpa-apikey: XXXX-SHERPA-DELIVERED-PUBLIC-APIKEY-XXXX" \
-H  "X-Sherpa-timestamp: 1748084514112" \
-H  "X-Sherpa-nonce: XXXX-SHERPA-RAMDOM-UUID-XXXX" \
-H  "X-Sherpa-hmac: xxxxyyyyyyy***signature******" \
-H  'Accept-Language: es-ES' \
-H  'Time-Zone: Europe/Madrid'

The endpoint returns a temporary token:

cb0c4826-d119-42d5-9a4a-373437d66e1d
curl -L -X GET 'https://api.sherpalive.com/v2/storage/clear/cb0c4826-d119-42d5-9a4a-373437d66e1d' \
-H  "X-Sherpa-apikey: XXXX-SHERPA-DELIVERED-PUBLIC-APIKEY-XXXX" \
-H  "X-Sherpa-timestamp: 1748084514112" \
-H  "X-Sherpa-nonce: XXXX-SHERPA-RAMDOM-UUID-XXXX" \
-H  "X-Sherpa-hmac: xxxxyyyyyyy***signature******" \
-H  'Accept-Language: es-ES' \
-H  'Time-Zone: Europe/Madrid'

All the user workspace storage is deleted.