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

Field	Source	Mandatory	Type	Description
folder	Query		String	Destination folder
file	Form	✓	Multipart file	File

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.

Code	Name
200	OK
401	Unauthorized
404	Not found
500	Internal 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

Field	Source	Mandatory	Type	Description
folder	Query		String	Source folder
file	Query	✓	String	File

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.

Code	Name
200	OK
401	Unauthorized
404	Not found
500	Internal 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

Field	Source	Mandatory	Type	Description
folder	Query		String	Folder
file	Query	✓	String	File

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.

Code	Name
200	OK
401	Unauthorized
500	Internal 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

Field	Source	Mandatory	Type	Description
folder	Query		String	Folder
file	Query	✓	String	File

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.

Code	Name
204	No response
401	Unauthorized
500	Internal 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

Field	Source	Mandatory	Type	Description
folder	Query		String	Folder
files	Form	✓	List of strings	Names 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.

Code	Name
204	No response
401	Unauthorized
500	Internal 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

Field	Source	Type	Description
folder	Query	String	Folder name
prefix	Query	String	Prefix
suffix	Query	String	Suffix
from	Query	Long	Timestamp in UNIX time milliseconds
to	Query	Long	Timestamp in UNIX time milliseconds
minSize	Query	Long	Minimum size in bytes
maxSize	Query	Long	Maximum 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.

Code	Name
200	OK
401	Unauthorized
500	Internal 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

Field	Source	Mandatory	Type	Description
folder	Query	✓	String	Folder 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.

Code	Name
200	OK
401	Unauthorized
500	Internal Server Error

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

Parameters

Field	Source	Mandatory	Type	Description
folder	Query	✓	String	Folder

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.

Code	Name
200	OK
401	Unauthorized
500	Internal Server Error

DELETE /storage/folder/delete/{folder}

Delete a folder and all its contents.

Parameters

Field	Source	Mandatory	Type	Description
folder	Query	✓	String	Folder

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.

Code	Name
204	No response
401	Unauthorized
500	Internal 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.

Code	Name
200	OK
401	Unauthorized
500	Internal 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

Code	Name
200	OK
401	Unauthorized
500	Internal 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

Field	Source	Mandatory	Type	Description
token	Query		String	Confirmation token

Response

Code	Name
200	OK
401	Unauthorized
500	Internal 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.