API Reference
The EmbedSpace API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies and, returns JSON-encoded responses, and uses standard HTTP response codes, authorization, and verbs.
Params and Functions
Parameters

Some parameters are common in embedspace-api. This section describes some of those common parameter types and the typical required format. You must know before proceed. EmbedSpace does not supports File/Folder name that contain charecters / * ? " : < > | & #.
folder, type: string
The empty string ("") or, forward slash ("/") or, zero ("0") represents the root folder(Except shared-folder). All other formats should not start with a slash (e.g. "hello/welcome/2021/"), and end with a slash.

Every folder in EmbedSpace also has an ID (e.g. WaA1ck3f,2d5c80a,ba317e,...) that can be obtained from it's details. These IDs are case-sensitive, so they should always be stored with their case preserved, and always compared in a case-sensitive manner. A path of folder relative to its parent folder's ID can be constructed by using a slash (e.g. "d:WaA1ck3f/welcome/"). If you're using paths related to ID's will reduce traversal and responses fastly.
file, type: string
The empty string ("") or, forward slash ("/") or, zero ("0") represents the root folder(Except shared-folder). All other formats should not start with a slash (e.g. "hello/sample.img"), and may not end with a slash or whitespace.

Every file in EmbedSpace also has an ID (e.g. 2kM1j3l,9cH4c6,49Fdfjg,....) that can be obtained from it's details. These IDs are case-sensitive, so they should always be stored with their case preserved, and always compared in a case-sensitive manner. A path of file relative to a folder's ID can be constructed by using a slash (e.g. "d:WaA1ck3f/hello/sample.jpg"). If you're using paths related to ID's will reduce traversal and responses fastly.
Functions

The following section describes the functions used to create requests to communicate with embedspace-api. You need to implement code for these functions.
HEX()
Lowercase base 16 encoding.
SHA256Hash()
Secure Hash Algorithm (SHA) cryptographic hash function.
HMAC_SHA256()
Computes HMAC by using the SHA256 algorithm with the signing key provided. This is the final signature.
Uri-Encode()
URI encode every byte. UriEncode() must enforce the following rules:
  • URI encode every byte except the unreserved characters: 'A'-'Z', 'a'-'z', '0'-'9', '-', '.', '_', and '~'.
  • The space character is a reserved character and must be encoded as %20 (and not as +).
  • Each URI encoded byte is formed by a % and the two-digit hexadecimal value of the byte. eg: '?' as '%3F'.
  • Letters in the hexadecimal value must be uppercase, eg: '%5B'.
BASE64_ENCODE()
Encodes data with MIME base64.
Upload Methods

EmbedSpace supports HTTP POST requests so that users can upload content directly to EmbedSpace. By using POST, end users can authenticate requests without having to pass data through a secure intermediary node that protects your credentials.
The following figure shows EmbedSpace upload using a POST request.
Tus Upload
This section discusses how to upload files directly to EmbedSpace cloud storage from a client application using tus.io open protocol. It also contains information about how to use tus.io protocol to EmbedSpace cloud Storage.
You can upload any file type—images, backups, data, movies, etc. —into EmbedSpace. If your file size is less than 8MB use POST method.

The process for sending tus requests is as follows:
  1. Create authorization headers ES-Authorization, ES-File values to authenticate the request.
  2. ES-Slot name of storage slot.
  3. Append ES-Authorization, ES-File, ES-Slot HTTP header to your tus request.

Creating Authorization Header
We're using Signature Verification to authenticate tus request.
Here is the step's for Create Signature using HMAC-SHA256 signing algorithm.

FileName_Key = HMAC_SHA256(Uri-Encode(<FileName>), <AccessKey>);
FileNameSlot_Key = HMAC_SHA256(<FileName_Key>, <SlotName>);
FileNameSlotSize_Key = HMAC_SHA256(<FileNameSlot_Key>, <FileSizeInBytes>);

FileNameSlotSizeLocation = <FileNameSlotSize_Key> + <SecretKey> + Uri-Encode(<FileLocation>);

FileNameSlotSizeLocation_Key = HMAC_SHA256(<FileNameSlotSizeLocation>, “ES-S4-TUS-V1”);
Signature = HEX(HMAC_SHA256(<FileNameSlotSizeLocation_Key>, <ExpiresInTimestamp>));


Header[‘ES-Authorization’] = v1.0/ES-S4-TUS-V1/<AccessKey>/<Signature>/<ExpiresInTimestamp>
Header[‘ES-Slot’] = <SlotName>
Header[‘ES-File’] = BASE64_ENCODE("{
‘location’ : Uri-Encode(<FileLocation>),
‘name’ : Uri-Encode(<FileName>),
‘size’ : <FileSizeInBytes>
}");


FileName and FileSize are the attributes of file that to be upload, You can use custom name for the file.
AccessKey and SecretKey are the authorization strings those are available at es-api page.
FileLocation location of file to be uploaded at EmbedSpace storage slot, location format.
SlotNameStorage slot name on EmbedSpace, or your EmbedSpace username.
tus-es-authorization header
PHP
$fileName = '2008/Videos/Animated/';
$fileLocation = '';		//keep standard (folder/subfolder/)
$fileSize = '';		//file size in Bytes
$slotName = 'xxxxxx';

$base = '';
$accessKey = 'ACCESSKEY';
$secretKey = 'SECRETKEY';

$fileName = rawurlencode(($fileName);
$fileLocation = rawurlencode($fileLocation);
$expires = strtotime('+1 hour');

$fileNameKey = hash_hmac('sha256', $fileName, $accessKey, true);
$fileNameSlotKey = hash_hmac('sha256', $slotName, $fileNameKey, true);
$fileNameSlotSizeKey = hash_hmac('sha256', $fileSize, $fileNameSlotKey, true);
$fileNameSlotSizeLocation = $fileNameSlotSizeKey . $secretKey . $fileLocation;
$fileNameSlotSizeLocationKey = hash_hmac('sha256', "ES-S4-TUS-V1", $fileNameSlotSizeLocation, true);

$signature= hash_hmac('sha256', $expires, $fileNameSlotSizeLocationKey, false);

$header_es_authorization = 'v1.0/ES-S4-TUS-V1/'.$accessKey.'/'.$signature.'/'.$expires;
$header_es_slot = $slotName;
$header_es_file = base64_encode(json_encode([
'name' => $fileName,
'location' => $fileLocation,
'size' => $fileSize
]));
Append header and Send file
You can use any of tus-client library to send file EmbedSpace cloud storage with endpoint https://tus.myslot.es/files/.
Use the same values used for create authorization header to create metadata on tus request.
If any of the syntax mentioned above is fails. Our end point will responds with standard HTTP Status Codes.


Note: File name or Location can't contain / * ? " ' : < > | & # characters. Location should not starts with `/´ and should end with `/´.

Common error responses from endpoint.
400, Bad Request,
401, Unauthorized (Signature Does Not Match),
402, Payment Required,
403, Forbidden (Unauthorized),
404, Not Found,
405, Method Not Allowed,
406, Not Acceptable,
407, Proxy Authorization Required,
408, Request Timeout,
426, Upgrade Required(Make your Account as Premium)
If you upload a file with name that already exists in selected location, EmbedSpace creates another version of the file instead of replacing the existing file. EmbedSpace will generates a unique version id. You can access all the versions by using version id or, version number version number of file is listed based on created time, When completed the upload the last uploaded version is considered as current version of the file.
tus-js-client file upload
JS
var file = th.files[0];
var file_location = '2008/Videos/Animated/';
var file_type = 'binary/octet-stream';

var authorization_header = getAuth(file.name,file_location,file.size); // Get authorization header
var tus_upload = {
endpoint: 'https://tus.myslot.es/files/',
retryDelays: [0, 1000, 3000, 5000],
overridePatchMethod: true,
chunkSize: 5242880,
metadata: {
	name: file.name,
	location: file_location,
	type: file_type
},
headers : {
	"ES-Authorization": authorization_header,
	"ES-Slot": slotName,
	"ES-File": file_header
},
removeFingerprintOnSuccess:true,
onProgress: function (bytesUploaded, bytesTotal){
	console.log(bytesUploaded,bytesTotal);
},
onSuccess: function () {
	console.log('UPLOAD SUCCESS');
}
};
var new_tus = new tus.Upload(file,tus_upload);
try{
new_tus.start();
}catch (e){
console.log('Tus error ' + e.name + ":" + e.message + "\n" + e.stack);
}
File Version Tus Upload
This section discusses how to upload new version of a file on EmbedSpace cloud storage from a client application using tus.io open protocol. This method is working only for active files, if the file is in trash or permanently deleted return errors.

The process for sending tus requests is as follows:
  1. Create authorization headers ES-Authorization, ES-File values to authenticate the request.
  2. ES-Slot name of storage slot.
  3. Append ES-Authorization, ES-File, ES-Slot HTTP header to your tus request.

Creating Authorization Header
We're using Signature Verification to authenticate tus request.
Here is the step's for Create Signature using HMAC-SHA256 signing algorithm.

FileId_Key = HMAC_SHA256(<FileId>, <AccessKey>);
FileIdSlot_Key = HMAC_SHA256(<FileId_Key>, <SlotName>);
FileIdSlotSize_Key = HMAC_SHA256(<FileIdSlot_Key>, <FileSizeInBytes>);
FileIdSlotSizeFv_Key = HMAC_SHA256(<FileIdSlotSize_Key>, “ES-S4-TUS-V1-FV”);

FileIdSlotSizeFvSc_Key = HMAC_SHA256(<FileIdSlotSizeFv_Key>, <SecretKey>);
Signature = HEX(HMAC_SHA256(<FileIdSlotSizeFvSc_Key>, <ExpiresInTimestamp>)); 

Header[‘ES-Authorization’] = v1.0/ES-S4-TUS-V1-FV/<AccessKey>/<Signature>/<ExpiresInTimestamp>
Header[‘ES-Slot’] = <SlotName>
Header[‘ES-File’] = BASE64_ENCODE("{
‘id’ : <FileId>,
‘size’ : <FileSizeInBytes>
}");


You will get file FileId from file details. FileSize Size of file to be uploaded in bytes.
AccessKey and SecretKey are the authorization strings those are available at es-api page.
tus-fileversion-es-authorization header
PHP
$fileId = '';		//from file details
$fileSize = '';		//file size in Bytes

$slotName = 'xxxxxx';
$accessKey = 'ACCESSKEY';
$secretKey = 'SECRETKEY';

$expires = strtotime('+1 hour');

$fileIdKey = hash_hmac('sha256', $fileId, $accessKey, true);
$fileIdSlotKey = hash_hmac('sha256', $slotName, $fileIdKey, true);
$fileIdSlotSizeKey = hash_hmac('sha256', $fileSize, $fileIdSlotKey, true);
$fileIdSlotSizeFvKey = hash_hmac('sha256', "ES-S4-TUS-V1-FV", $fileIdSlotSizeKey, true);
$fileIdSlotSizeFvScKey = hash_hmac('sha256', $secretKey, $fileIdSlotSizeFvKey, true);

$signature = hash_hmac('sha256', $expires, $fileIdSlotSizeFvScKey, false);

$header_es_authorization = 'v1.0/ES-S4-TUS-V1-FV/'.$accessKey.'/'.$signature.'/'.$expires;
$header_es_slot = $slotName;
$header_es_file = base64_encode(json_encode([
'id' => $fileId,
'size' => $fileSize
]));
Append header and Send file
Use any of tus-client library to send file EmbedSpace cloud storage with endpoint https://tus.myslot.es/files/. If any of the syntax mentioned above is fails. Our end point will responds with standard HTTP Status Codes.
Post Upload
This section discusses how to upload files directly to EmbedSpace cloud storage from a client application using POST method. Maximum uploadable file size is 8MB.

The process for sending POST requests is as follows:
  1. Create authorization headers ES-Authorization, ES-File values to authenticate the request.
  2. ES-Slot name of storage slot.
  3. Append ES-Authorization, ES-File, ES-Slot HTTP header to your tus request.

Creating Authorization Header
We're using Signature Verification to authenticate tus request.
Here is the step's for Create Signature using HMAC-SHA256 signing algorithm.

FileName_Key = HMAC_SHA256(Uri-Encode(<FileName>), <AccessKey>);
FileNameSlot_Key = HMAC_SHA256(<FileName_Key>, <SlotName>);
FileNameSlotSize_Key = HMAC_SHA256(<FileNameSlot_Key>, <FileSizeInBytes>);

FileNameSlotSizeLocation = <FileNameSlotSize_Key> + <SecretKey> + Uri-Encode(<FileLocation>);

FileNameSlotSizeLocation_Key = HMAC_SHA256(<FileNameSlotSizeLocation>, “ES-S4-POST-V1”);
Signature = HEX(HMAC_SHA256(<FileNameSlotSizeLocation_Key>, <ExpiresInTimestamp>));

Header[‘ES-Authorization’] = v1.0/ES-S4-POST-V1/<AccessKey>/<Signature>/<ExpiresInTimestamp>
Header[‘ES-Slot’] = <SlotName>
Header[‘ES-File’] = BASE64_ENCODE("{
‘location’ : Uri-Encode(<FileLocation>),
‘name’ : Uri-Encode(<FileName>),
‘size’ : <FileSizeInBytes>
}");

FileName and FileSize are the attributes of file that to be upload, You can use custom name for the file.
AccessKey and SecretKey are the authorization strings those are available at es-api page.
FileLocation location of file to be uploaded at EmbedSpace storage slot, location format.
SlotNameStorage slot name on EmbedSpace, or your EmbedSpace username.
post-es-authorization header
PHP
$fileName = '2008/Videos/Animated/';
$fileLocation = '';		//keep standard (folder/subfolder/)
$fileSize = '';		//file size in Bytes
$slotName = 'xxxxxx';

$base = '';
$accessKey = 'ACCESSKEY';
$secretKey = 'SECRETKEY';

$fileName = urlencode($fileName);
$fileLocation = urlencode($fileLocation);
$expires = strtotime('+1 hour');

$fileNameKey = hash_hmac('sha256', $fileName, $accessKey, true);
$fileNameSlotKey = hash_hmac('sha256', $slotName, $fileNameKey, true);
$fileNameSlotSizeKey = hash_hmac('sha256', $fileSize, $fileNameSlotKey, true);
$fileNameSlotSizeLocation = $fileNameSlotSizeKey . $secretKey . $fileLocation;
$fileNameSlotSizeLocationKey = hash_hmac('sha256', "ES-S4-POST-V1", $fileNameSlotSizeLocation, true);

$signature= hash_hmac('sha256', $expires, $fileNameSlotSizeLocationKey, false);

$header_es_authorization = 'v1.0/ES-S4-POST-V1/'.$accessKey.'/'.$signature.'/'.$expires;
$header_es_slot = $slotName;
$header_es_file = base64_encode(json_encode([
'name' => $fileName,
'location' => $fileLocation,
'size' => $fileSize
]));
Append header and Send file
You can use any of tus-client library to send file EmbedSpace cloud storage with endpoint https://post.myslot.es/files/.
Use the same values used for create authorization header to create metadata on tus request.
If any of the syntax mentioned above is fails. Our end point will responds with standard HTTP Status Codes.


Note: File name or Location can't contain / * ? " ' : < > | & # characters. Location should not starts with `/´ and should end with `/´.

Common error responses from endpoint.
400, Bad Request,
401, Unauthorized (Signature Does Not Match),
402, Payment Required,
403, Forbidden (Unauthorized),
404, Not Found,
405, Method Not Allowed,
406, Not Acceptable,
407, Proxy Authorization Required,
408, Request Timeout,
426, Upgrade Required(Make your Account as Premium)
If you upload a file with name that already exists in selected location, EmbedSpace creates another version of the file instead of replacing the existing file. EmbedSpace will generates a unique version id. You can access all the versions by using version id or, version number version number of file is listed based on created time, When completed the upload the last uploaded version is considered as current version of the file.
client-js file upload
JS
var file = th.files[0];
var file_location = '2008/Videos/Animated/';
var file_type = 'binary/octet-stream';


var formdata = new FormData();
formdata.append("file",obj.file);
formdata.append("metadata",JSON.stringify({
name: filename,
location: file_location,
type: file_type
}));

var xhr = new XMLHttpRequest();
xhr.upload.addEventListener("progress",function(e){
e = e || event;
console.log(e.total,e.loaded);
document.getElementById('uploadprogress').innerHTML = ((bytesUploaded/bytesTotal)*100).toFixed(2)+'%';
}, false);
xhr.addEventListener("load",function(e){
e = e || event;
console.log(e.target.responseText);
if(this.status===200){
	console.log('UPLOAD SUCCESS');
}
else{
	console.log('UPLOAD FAIL');
}
}, false);
xhr.addEventListener("error",function(e){
e = e || event;
console.log('UPLOAD FAIL');
}, false);

xhr.open("POST",'https://post.myslot.es/files/',true);
xhr.setRequestHeader("ES-Authorization",authorization_header);
xhr.setRequestHeader("ES-Slot",slotName);
xhr.setRequestHeader("ES-File",file_header);
xhr.send(formdata);
File Version Post Upload
This section discusses how to upload new version of a file on EmbedSpace cloud storage from a client application using POST method. This method is working only for active files, if the file is in trash or permanently deleted return errors.

The process for sending tus requests is as follows:
  1. Create authorization headers ES-Authorization, ES-File values to authenticate the request.
  2. ES-Slot name of storage slot.
  3. Append ES-Authorization, ES-File, ES-Slot HTTP header to your tus request.

Creating Authorization Header
We're using Signature Verification to authenticate tus request.
Here is the step's for Create Signature using HMAC-SHA256 signing algorithm.

FileId_Key = HMAC_SHA256(<FileId>, <AccessKey>);
FileIdSlot_Key = HMAC_SHA256(<FileId_Key>, <SlotName>);
FileIdSlotSize_Key = HMAC_SHA256(<FileIdSlot_Key>, <FileSizeInBytes>);
FileIdSlotSizeFv_Key = HMAC_SHA256(<FileIdSlotSize_Key>, “ES-S4-POST-V1-FV”);

FileIdSlotSizeFvSc_Key = HMAC_SHA256(<FileIdSlotSizeFv_Key>, <SecretKey>);
Signature = HEX(HMAC_SHA256(<FileIdSlotSizeFvSc_Key>, <ExpiresInTimestamp>)); 

Header[‘ES-Authorization’] = v1.0/ES-S4-POST-V1-FV/<AccessKey>/<Signature>/<ExpiresInTimestamp>
Header[‘ES-Slot’] = <SlotName>
Header[‘ES-File’] = BASE64_ENCODE("{
‘id’ : <FileId>,
‘size’ : <FileSizeInBytes>
}");

You will get file FileId from file details. FileSize Size of file to be uploaded in bytes.
AccessKey and SecretKey are the authorization strings those are available at es-api page.
post-file-es-authorization header
PHP
$fileId = '';		//from file details
$fileSize = '';		//file size in Bytes

$slotName = 'xxxxxx';
$accessKey = 'ACCESSKEY';
$secretKey = 'SECRETKEY';

$expires = strtotime('+1 hour');

$fileIdKey = hash_hmac('sha256', $fileId, $accessKey, true);
$fileIdSlotKey = hash_hmac('sha256', $slotName, $fileIdKey, true);
$fileIdSlotSizeKey = hash_hmac('sha256', $fileSize, $fileIdSlotKey, true);
$fileIdSlotSizeFvKey = hash_hmac('sha256', "ES-S4-POST-V1-FV", $fileIdSlotSizeKey, true);
$fileIdSlotSizeFvScKey = hash_hmac('sha256', $secretKey, $fileIdSlotSizeFvKey, true);

$signature = hash_hmac('sha256', $expires, $fileIdSlotSizeFvScKey, false);

$header_es_authorization = 'v1.0/ES-S4-POST-V1-FV/'.$accessKey.'/'.$signature.'/'.$expires;
$header_es_slot = $slotName;
$header_es_file = base64_encode(json_encode([
'id' => $fileId,
'size' => $fileSize
]));
Append header and Send file
Use any of tus-client library to send file EmbedSpace cloud storage with endpoint https://post.myslot.es/files/. If any of the syntax mentioned above is fails. Our end point will responds with standard HTTP Status Codes.
Direct Access

Retrieves files from EmbedSpace. To use GET, you must have READ access to the file. If you grant READ access to the anonymous user, you can return the file without using an authorization header.
To get file, specify the full path for the file in the GET operation. For a virtual hosted-style request example, if you have the file building.jpg at location 2008/Images/Animated/, specify the resource as 2008/Images/Animated/building.jpg.
For a path-style request example, if you have a file 2008/Images/Animated/building.jpg and es-drive slot username, if the file is public specify the resource url as https://slot.embedspace.com/username/2008/Images/Animated/building.jpg, else add authorization parameters with resource url. When backwards-incompatible changes are made to the API, a new, dated version is released. The current version is 1.0.

Here is some parameters to change response;
  • download-as, to force download the requested resource.
  • version, By default, the GET operation returns the current version of the file. To return a different version, pass the version number of the file.
  • version-id, Pass the version id of the file. You will version-id from file version details.


Authorization methods for direct-access.
Version 1.0
EmbedSpace provides a powerful token authorization system to strictly control who, where and for how long can access your resource. This section contains the documentation on how to generate authorization strings to securely access your content.

How to sign an URL?

This section contains instructions on how to generate and format the unique signatures and use those to sign an URL. The signing process consists of the following parameters that need to be added to the URL:
  • auth-method, This is required parameter. It helps our servers to identify authorization method to authenticate incoming request.
  • expires, The expires parameter is must always be included. It allows you to control exactly for how long the signed request is valid. It is a UNIX timestamp based time representation. Any request after this timestamp will be rejected.
  • signature, The signature parameter is the main key in signing the URL. It represents a SHA256 hash based on the requested resource.

User_Key = HEX(HMAC_SHA256(<AccessKey>, <SecretKey>));
UserFilePath_Key = HEX(HMAC_SHA256(<User_Key>, Uri-Encode(<FilePath>)));
//URL-encode according to RFC 3986
UserFilePathS4DA_Key = HEX(HMAC_SHA256(<UserFilePath_Key>, “ES-S4-DA-V1”));

UserFilePathS4DA_Key = <UserFilePathS4DA_Key> + <ClientIP>;
//<ClientIP> is optional.

Signature = HEX(HMAC_SHA256(<UserFilePathS4DA_Key>, <ExpiresInTimestamp>));


URL format 1:
https://myslot.es/<slotname>/<FilePath>?access-key=<AccessKey>&auth-method=ES-S4-DA-V1&expires=<ExpiresInTimestamp>&signature=<Signature>
URL format 2:
https://<slotname>.myslot.es/<FilePath>?access-key=<AccessKey>&auth-method=ES-S4-DA-V1&expires=<ExpiresInTimestamp>&signature=<Signature>

Overriding Response Header Values
In a GET response, there are situations when you want to override particular response header values. For example, you might override the Content-Language response header value in your GET request.
 The following query parameters can be used to override values for a set of response headers. These response header values are sent only on a successful request, that is, when status code 200 OK is returned. The response headers that you can override for the GET response are Content-Type, Content-Language, Cache-Control, Content-Disposition, and Content-Encoding. To override these header values in the GET response, you use the following request parameters, and the Uri-Encoded values as parameter-values.

  • response-content-type
  • response-content-language
  • response-cache-control
  • response-content-disposition
  • response-content-encoding

direct-access signature
PHP
$filePath = '2008/Images/Animated/building.jpg';

$expires    = strtotime('+1 hour');

$slot       = "SLOTNAME";
$accessKey  = 'ACCESSKEY';
$secretKey  = 'SECRETKEY';
$path       = 'FILE_PATH(INCLUDING SLOTNAME IF FORMAT IS 1)';


/*--------------------With out IP validation--------------------*/

$userKey = hash_hmac('sha256', $secretKey, $accessKey, false);
$userFilePathKey = hash_hmac('sha256', rawurlencode($path), $userKey, false);
$userFilePathS4DAKey = hash_hmac('sha256', 'ES-S4-DA-V1', $userFilePathKey, false);

$signature = hash_hmac('sha256', $expires, $userFilePathS4DAKey, false);

/*----------------------With IP validation----------------------*/

$clientIP = "xxx.xxx.xxx.xxx";

$userKey = hash_hmac('sha256', $secretKey, $accessKey, false);
$userFilePathKey = hash_hmac('sha256', rawurlencode($path), $userKey, false);
$userFilePathS4DAKey = hash_hmac('sha256', 'ES-S4-DA-V1', $userFilePathKey, false);

$userFilePathS4DAKey_IP = $userFilePathS4DAKey . $clientIP;

$signature = hash_hmac('sha256', $expires, $userFilePathS4DAKey, false);

API-Authorization

In order to interact with the EmbedSpace API, you or your application must authenticate.
To authenticate with the API, create ES-Authorization header with your authorization strings and add it as HTTP header to your request. You can find authorization strings at es-api tab, in the My Account section. All requests must be made over HTTPS to the end point https://api.embedspace.com. This api-authorization is valid only for operations on the storage. API requests without authorization header will fail.

EmbedSpace uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted). Codes in the 5xx range indicate an error with EmbedSpace's servers (these are rare).

When backwards-incompatible changes are made to the API, a new, dated version is released. The current version is 1.0.
Version 1.0
This section discusses how to create ES-Authorization header to interact with the EmbedSpace API.

Creating Authorization Header
We're using Signature Verification to authenticate api request.
Here is the step's for Create Signature using HMAC-SHA256 signing algorithm.

Request_Key = HMAC_SHA256(<Request>, <AccessKey>);
RequestVersion_Key = HMAC_SHA256(<Request_Key>, “v1.0”);
RequestVersionEx_Key = HMAC_SHA256(<RequestVersion_Key>, <Expires>);
Signature = HEX(HMAC_SHA256(<RequestVersionEx_Key>, <SecretKey>));

Header[‘ES-Authorization’] = v1.0/<AccessKey>/<Signature>/<Expires>

Request operation on files or,folders stored in EmbedSpace cloud storage eg: file/copy-files, file/get-versioning, folder/create-folder, etc...
AccessKey and SecretKey are the authorization strings those are available at es-api page.
api authorization header
PHP
$request = 'folder/delete';
$accessKey = 'ACCESSKEY';
$secretKey = 'SECRETKEY';

$expires = strtotime('+1 minute');

$requestKey = hash_hmac('sha256', $accessKey, $request, true);
$requestVersionKey = hash_hmac('sha256', "v1.0", $requestKey, true);
$requestVersionExKey = hash_hmac('sha256', $expires, $requestVersionKey, true);

$signature = hash_hmac('sha256', $secretKey, $requestVersionExKey, false);

$header_es_authorization = 'v1.0/'.$accessKey.'/'.$signature.'/'.$expires;
Operations on Files

There are various operations which can be done on a file in EmbedSpace. The operation request format is file/operation. Send JSON arguments through a POST request with ES-Authorization header for every operation. Returns JSON-encoded responses, and uses standard HTTP response codes.
Copy Files
Creates a copy of file(s) to a different location that is already stored in EmbedSpace slot. It will copy only current version of the file. All copy requests must be authenticated. Additionally, you must have read section Authorization.
A copy request might return an error when EmbedSpace receives the copy request or while EmbedSpace is copying the files. If the error occurs before the copy operation starts, you receive a standard HTTP error. Design your application to parse the contents of the response and handle it appropriately.
If the copy is successful, you receive a response with information about the copied file in data object from response.

file/copy-files
Url: https://api.embedspace.com/v1.0/file/copy-files

Parameters
  • slot, type: string, required EmbedSpace storage slot name (username).
  • files, type: array, required Specifies the source file(s) for the copy operation. You specify the values in mentioned formats.
  • copy_to, type: string, required Path in the user's slot that is the destination.
  • create_folder, type: boolean, default: true Create new folder or folders if the destination does not exists. If it is false return error.

Request Sample:
copy-files request
JSON
{
"slot": "myslot",
"files": [
	"d:e8fc19d1153eb/Images/Animated/Copy of sample1.png",
	"d:e8fc19d1153eb/Images/Films/sample.jpg",
	"d:1a131c5a888c9/Copy of sample2.png",
	"2008/Images/Animated/Copy of Untitled22.jpg",
	"f:2a131c5a888c3"
],
"copy_to": "2008/Images/Copied2/",
"create_folder": true
}

Response:
copy-files response
JSON
{
"status": 200,
"response": "OK",
"request": "file/copy-files",
"data": {
	"new_files": [
		{
			"id": "6585f603905703",
			"name": "Copy of sample1.png"
		},
		{
			"id": "b81d7a32ddf8ea",
			"name": "sample.jpg"
		},
		...
	]
}
}
Response data Elements
  • new_files,New file info type: array Name and Id of each file newly created by this request.
    • id, type: string A unique identifier for the file.
    • name, type: string The last component of the path (including extension). This never contains a slash.
  • message, type: string Message related to the request. eg: Storage limit, etc.
List Versions
Returns metadata about all versions(up to 100 for single request) of a file. You can also use request parameters as selection criteria to return metadata about a subset of all the file versions. The versions listed base on creation time in descending order

file/list-versions
Url: https://api.embedspace.com/v1.0/file/list-versions

Parameters
  • slot, type: string, required EmbedSpace storage slot name (username).
  • file, type: string, required Specifies the source file which you want to list versions.
  • start_from, type: integer, default: 0 Where you want to start listing from. EmbedSpace starts listing after this specified value in the order of created time. If it is 0 start listing from beginning.
  • max_results, type: integer, default: 100, max: 100 Sets the maximum number of version-details returned in the response. The operation returns up to 100 versions by default.

Request Sample:
file-list-versions request
JSON
{
"slot": "myslot",
"file": "2008/Images/Animated/Copy of Untitled22.jpg",
"start_from": 30,
"max_results": 50
}

Response:
file-list-versions response
JSON
{
"status": 200,
"response": "OK",
"request": "file/list-versions",
"data": {
	"file_id": "f81d7a32ddf8ea",
	"versions": [
		{
			"id": "723c407fb23df61094b5278c1570e78d",
			"created_by": "105984344",
			"created_at": 405984548,
			"current_version": true,
			"size": 5899459,
			"type": "application/octet-stream"
		},
		{
			"id": "78e5b55202cbb0916154e8d65c21f70d",
			...
		}
		...
	],
	"list_end": false
}
}
Response data Elements
  • file_id, type: string A unique identifier for the file.
  • versions,Version Info type: array Information about version.
    • id, type: string A unique identifier for the version.
    • created_by, type: string The account ID of the user.
    • created_at, type: integer The Unix timestamp of when the user created this version.
    • current_version, type: boolean This is the current version of the file.
    • size, type: integer The file size in bytes.
    • type, type: string A standard MIME type describing the format of the file data.
  • list_end, type: boolean Represent list is ended.
Public Access
Sets direct access permission on files. If you set public-access as true the files visible to public(read) with out authorization.

file/public-access
Url: https://api.embedspace.com/v1.0/file/public-access

Parameters
  • slot, type: string, required EmbedSpace storage slot name (username).
  • files, type: array, required Specifies the file(s) to set public-access permission. You specify the values in mentioned formats.
  • public_access, type: boolean, required setting public-access permission of file(s).

Request Sample:
file-public-access request
JSON
{
"slot": "myslot",
"files": [
	"d:e8fc19d1153eb4/Images/Animated/Copy of sample1.png",
	"d:e8fc19d1153eb4/Images/Films/sample.jpg",
	"d:1a131c5a888c9/Copy of sample2.png",
	"2008/Images/Animated/Copy of Untitled22.jpg",
	"f:2a131c5a888c3"
],
"public_access": true
}

Response:
file-public-access response
JSON
{
"status": 200,
"response": "OK",
"request": "file/public-access",
"data": {}
}
Delete
Delete the file or files, either permanently or by moving it to the trash. This request will delete all the versions of requested file(s).

file/delete
Url: https://api.embedspace.com/v1.0/file/delete

Parameters
  • slot, type: string, required EmbedSpace storage slot name (username).
  • files, type: array, required Specifies the file(s) for delete. You specify the values in mentioned formats.
  • permanent, type: boolean, required If it is true file(including all versions) will be deleted permanently, else go to trash.

Request Sample:
file-delete request
JSON
{
"slot": "myslot",
"files": [
	"d:e8fc19d1153eb4/Images/Animated/Copy of sample1.png",
	"d:e8fc19d1153eb4/Images/Films/sample.jpg",
	"d:1a131c5a888c9/Copy of sample2.png",
	"2008/Images/Animated/Copy of Untitled22.jpg",
	"f:2a131c5a888c3"
],
"permanent": true
}

Response:
file-delete response
JSON
{
"status": 200,
"response": "OK",
"request": "file/delete",
"data": {
	"deleted_at": 45426889
}
}
Delete Version
You can Delete all the versions of a file except current version. You can use version_id or version_number as a reference for delete specific versions. version_number is just a number based only on creation time, We'll not set number for file-version. If you delete 100th version of a file, then 101st version will become 100th version. Once deleted it can't be undone.

file/delete-version
Url: https://api.embedspace.com/v1.0/file/delete-version

Parameters
  • slot, type: string, required EmbedSpace storage slot name (username).
  • file, type: array, required Specifies the file(s) for delete. You specify the values in mentioned formats.
  • version_id, type: string,array, required, if version_number is empty Used to reference specific version or versions of the file.
  • version_number, type: integer, required, if version_id is empty Used to reference a specific version of the file. The numbering is based on creation time.

Request Sample:
file-version-delete request
JSON
{
"slot": "myslot",
"file": "f:af08245bfe0f9b6",
"version_id": [
	"40ff6097d6e57f5785bf0b8b3c0d9c97",
	"420c2a180ba010b2b0af3cf1b5d0f97e"
]
}

Response:
file-version-delete response
JSON
{
"status": 200,
"response": "OK",
"request": "file/delete-version",
"data": {
	"deleted_versions": [
		{
			"version_id": "420c2a180ba010b2b0af3cf1b5d0f97e",
			"deleted_at": 1615476187
		},
		{
			"version_id": "40ff6097d6e57f5785bf0b8b3c0d9c97",
			"deleted_at": 1615476187
		}
	]
}
}
Response data Elements
  • deleted_versions,Version info type: array List of deleted version.
    • version_id, type: string A unique identifier for the version.
    • deleted_at, type: integer The Unix timestamp of when the user deleted the version.
Get Versioning
In EmbedSpace file versioning is Default, supports unlimited file versioning with flexible versioning control. User can control file versioning through our Api. get-versioning Returns the versioning properties of file(s).

file/get-versioning
Url: https://api.embedspace.com/v1.0/file/get-versioning

Parameters
  • slot, type: string, required EmbedSpace storage slot name (username).
  • files, type: array, required Specifies the file(s) to get versioning properties. You specify the values in mentioned formats.

Request Sample:
file-get-versioning request
JSON
{
"slot": "myslot",
"files": [
	"d:e8fc19d1153eb4/Images/Animated/Copy of sample1.png",
	"d:e8fc19d1153eb4/Images/Films/sample.jpg",
	"d:1a131c5a888c9/Copy of sample2.png",
	"2008/Images/Animated/Copy of Untitled22.jpg",
	"f:2a131c5a888c3"
],
}

Response:
file-get-versioning response
JSON
{
"status": 200,
"response": "OK",
"request": "file/get-versioning",
"data": {
	"versions_control": [
		{
			"file_id": "fab57723c9ddb",
			"min_versions_keep_forever": 15,
			"delete_previous_versions_after": 35
		},
		{
			"file_id": "2a131c5a888c3",
			"min_versions_keep_forever": 15,
			"delete_previous_versions_after": 35
		},
		...
	]
}
}
Response data Elements
  • versions_control,Version control info type: array List of versioning properties of files.
    • file_id, type: string A unique identifier for the file.
    • min_versions_keep_forever, type: integer Zero(0) means unlimted versions. If you want to set limit then 9999 is maximum. EmebdSpace will keep the versions forever until you delete or minimizing the limits.
    • delete_previous_versions_after, type: integer Zero(0) means if new version of the file is created then older version(s) instantly deleted with keeping minimum versions you set.
Set Versioning
In EmbedSpace file versioning is Default, supports unlimited file versioning with flexible versioning control. User can control file versioning through our Api. set-versioning Sets the versioning properties of file(s).

file/set-versioning
Url: https://api.embedspace.com/v1.0/file/set-versioning

Parameters
  • slot, type: string, required EmbedSpace storage slot name (username).
  • files, type: array, required Specifies the file(s) to set versioning. You specify the values in mentioned formats.
  • min_versions_keep_forever, type: integer Zero(0) means unlimted versions. If you want to set limit then 9999 is maximum. EmebdSpace will keep the versions forever until you delete or minimizing the limits.
  • delete_previous_versions_after, type: integer In days (max: 999), Zero(0) means if new version of the file is created then older version(s) instantly deleted with keeping minimum versions you set.

Request Sample:
file-set-versioning request
JSON
{
"slot": "myslot",
"files": [
	"d:e8fc19d1153eb4/Images/Animated/Copy of sample1.png",
	"d:e8fc19d1153eb4/Images/Films/sample.jpg",
	"d:1a131c5a888c9/Copy of sample2.png",
	"2008/Images/Animated/Copy of Untitled22.jpg",
	"f:2a131c5a888c3"
],
"min_versions_keep_forever": 35
"delete_previous_versions_after": 45
}

Response:
file-set-versioning response
JSON
{
"status": 200,
"response": "OK",
"request": "file/set-versioning",
"data": {}
}
List Shared with
Returns the members who have been shared with a file. in ascending order of Email address associated with the member

file/list-shared-members
Url: https://api.embedspace.com/v1.0/file/list-shared-members

Parameters
  • slot, type: string, required EmbedSpace storage slot name (username).
  • file, type: string, required Specifies the file for which you want to see members. You specify the values in mentioned formats.
  • users_start_from, type: integer, default: 0 Where you want to start listing from. Starts users listing after this specified value. If it is 0 start listing from beginning.
  • users_max_results, type: integer, default: 100, max: 100 Sets the maximum number of users returned in the response. By default the action returns up to 100.
  • invitees_start_from, type: integer, default: 0 Where you want to start listing from. Starts invitees listing after this specified value. If it is 0 start listing from beginning.
  • invitees_max_results, type: integer, default: 100, max: 100 Sets the maximum number of invitees returned in the response. By default the action returns up to 100.

Request Sample:
file-list-shared-members request
JSON
{
"slot": "myslot",
"file": "f:af08245bfe0f9b6",
"users_start_from": 30,
"users_max_results": 50,
"invitees_start_from": 30,
"invitees_max_results": 50,
}

Response:
file-list-shared-members response
JSON
{
"status": 200,
"response": "OK",
"request": "file/list-shared-members",
"data": {
	"users": [
		{
			"account_id": "48866815",
			"display_name": "Muhammad Iqbal",
			"email": "[email protected]",
			"permission": "rw"
		},
		...
	],
	"invitees": [
		{
			"email": "[email protected]",
			"permission": "r"
		},
		...
	]
}
}
Response data Elements
  • users,File users info type: array The list of users of the shared file.
    • account_id, type: string The account ID of the user.
    • display_name, type: string The display name of the user.
    • email, type: string Email address of user.
    • permission, type: string The (read/write) permission given to the user.
  • invitees,Invitees info type: array The list of invited members of a file, but have not logged in and claimed this.
    • email, type: string Email address of user.
    • permission, type: string The (read/write) permission given to the member.
Share with
To share file(s) with member(s), using the email address, the path of the file(s), and the permission the user should have when accessing the file.

file/share-with
Url: https://api.embedspace.com/v1.0/file/share-with

Parameters
  • slot, type: string, required EmbedSpace storage slot name (username).
  • files, type: array, required Specifies the file(s) to which to add members. You specify the values in mentioned formats.
  • members,File members info type: array The intended list of members to add.
    • email, type: string Email address of user.
    • permission, type: string The (read/write) permission given to the user.

Request Sample:
file-share-with request
JSON
{
"slot": "myslot",
"files": [
	"d:e8fc19d1153eb4/Images/Animated/Copy of sample1.png",
	"d:e8fc19d1153eb4/Images/Films/sample.jpg",
	"d:1a131c5a888c9/Copy of sample2.png",
	"2008/Images/Animated/Copy of Untitled22.jpg",
	"f:2a131c5a888c3"
],
"members": [
	{
		"email": "[email protected]",
		"permission": "r"
	},
	{
		"email": "[email protected]",
		"permission": "w"
	}
	...
]
}

Response:
file-share-with response
JSON
{
"status": 200,
"response": "OK",
"request": "file/share-with",
"data": {}
}
Remove Shared members
Removes access permission for file(s) from specific user(s).

file/remove-shared-members
Url: https://api.embedspace.com/v1.0/file/remove-shared-members

Parameters
  • slot, type: string, required EmbedSpace storage slot name (username).
  • files, type: array, required Specifies the file(s) from which to remove members. You specify the values in mentioned formats.
  • members,File members info type: array The members to remove from the file(s).
    • email, type: string Email address of user.

Request Sample:
file-remove-shared-members request
JSON
{
"slot": "myslot",
"files": [
	"d:e8fc19d1153eb4/Images/Animated/Copy of sample1.png",
	"d:e8fc19d1153eb4/Images/Films/sample.jpg",
	"d:1a131c5a888c9/Copy of sample2.png",
	"2008/Images/Animated/Copy of Untitled22.jpg",
	"f:2a131c5a888c3"
],
"members": [
	{
		"email": "[email protected]"
	},
	{
		"email": "[email protected]"
	}
	...
]
}

Response:
file-remove-shared-members response
JSON
{
"status": 200,
"response": "OK",
"request": "file/remove-shared-members",
"data": {}
}
List Tags
File tags are text values attach to files for classifying files. list-tags Returns all the tags attached to the file in ascending order.

file/list-tags
Url: https://api.embedspace.com/v1.0/file/list-tags

Parameters
  • slot, type: string, required EmbedSpace storage slot name (username).
  • file, type: string, required Specifies the file to list tags. You specify the values in mentioned formats.
  • start_from, type: integer, default: 0 Where you want to start listing from. Starts listing after this specified value the list begins in ascending order of tag name. If it's 0, start at the beginning of the list.
  • max_results, type: integer, default: 100, max: 100 The maximum number of tags that will be returned in a response. The action returns up to 100 key names by default.

Request Sample:
file-list-tags request
JSON
{
"slot": "myslot",
"file": "f:af08245bfe0f9b6"
}

Response:
file-list-tags response
JSON
{
"status": 200,
"response": "OK",
"request": "file/list-tags",
"data": {
	"tags": [
		{
			"name": "india",
			"attached_by": "47544096"
		},
		{
			"name": "kerala",
			"attached_by": "47544096"
		},
		{
			"name": "munnar",
			"attached_by": "47544096"
		}
	]
}
}
Response data Elements
  • tags,Tag info type: array The list of file tags.
    • name, type: string name of the tag.
    • attached_by, type: string The account ID of the user.
Add Tags
New tags attached to the file.

file/add-tags
Url: https://api.embedspace.com/v1.0/file/add-tags

Parameters
  • slot, type: string, required EmbedSpace storage slot name (username).
  • files, type: array, required Specifies the file(s) to add tags. You specify the values in mentioned formats.

Request Sample:
file-add-tags request
JSON
{
"slot": "myslot",
"files": [
	"d:e8fc19d1153eb4/Images/Animated/Copy of sample1.png",
	"d:e8fc19d1153eb4/Images/Films/sample.jpg",
	"d:1a131c5a888c9/Copy of sample2.png",
	"2008/Images/Animated/Copy of Untitled22.jpg",
	"f:2a131c5a888c3"
],
"tags": [
	{
		"name": "sample tag1"
	},
	{
		"name": "sample tag2"
	},
	{
		"name": "sample tag3"
	}
]
}

Response:
file-add-tags response
JSON
{
"status": 200,
"response": "OK",
"request": "file/add-tags",
"data": {}
}
Remove Tags
Removes tags attached to the file.

file/remove-tags
Url: https://api.embedspace.com/v1.0/file/remove-tags

Parameters
  • slot, type: string, required EmbedSpace storage slot name (username).
  • files, type: array, required Specifies the file(s) to remove tags. You specify the values in mentioned formats.

Request Sample:
file-remove-tags request
JSON
{
"slot": "myslot",
"files": [
	"d:e8fc19d1153eb4/Images/Animated/Copy of sample1.png",
	"d:e8fc19d1153eb4/Images/Films/sample.jpg",
	"d:1a131c5a888c9/Copy of sample2.png",
	"2008/Images/Animated/Copy of Untitled22.jpg",
	"f:2a131c5a888c3"
],
"tags": [
	{
		"name": "sample tag1"
	},
	{
		"name": "sample tag2"
	},
	{
		"name": "sample tag3"
	}
]
}

Response:
file-remove-tags response
JSON
{
"status": 200,
"response": "OK",
"request": "file/remove-tags",
"data": {}
}
Rename
To rename a file in EmbedSpace. If there's a conflict with any file EmbedSpace will return error.

file/rename
Url: https://api.embedspace.com/v1.0/file/rename

Parameters
  • slot, type: string, required EmbedSpace storage slot name (username).
  • file, type: string, required Specifies the file which you intend to rename. You specify the values in mentioned formats.
  • new_name, type: string, required New name of the file. File name does not contain / * ? " ' : < > | & #

Request Sample:
file-rename request
JSON
{
"slot": "myslot",
"file": "f:af08245bfe0f9b6",
"new_name": "New File Name.txt"
}

Response:
file-rename response
JSON
{
"status": 200,
"response": "OK",
"request": "file/rename",
"data": {
	"last_modified": 154789236,
	"modified_by": 457516645
}
}
Response data Elements
  • last_modified, type: integer The Unix timestamp of when the user deleted the version.
  • modified_by, type: string The account ID of the modifier.
Move Files
Move file(s) to a different location.

file/move-files
Url: https://api.embedspace.com/v1.0/file/move-files

Parameters
  • slot, type: string, required EmbedSpace storage slot name (username).
  • files, type: array, required Specifies the source file(s) to be moved. You specify the values in mentioned formats.
  • move_to, type: string, required Path in the user's slot that is the destination.
  • create_folder, type: boolean, default: true Create new folder or folders if the destination does not exists. If it is false return error.

Request Sample:
move-files request
JSON
{
"slot": "myslot",
"files": [
	"d:e8fc19d1153eb4/Images/Animated/Copy of sample1.png",
	"d:e8fc19d1153eb4/Images/Films/sample.jpg",
	"d:1a131c5a888c9/Copy of sample2.png",
	"2008/Images/Animated/Copy of Untitled22.jpg",
	"f:2a131c5a888c3"
],
"move_to": "2008/Images/Destination/",
"create_folder": true
}

Response:
move-files response
JSON
{
"status": 200,
"response": "OK",
"request": "file/move-files",
"data": {
	"moved": 3,
	"failed": 0
}
}
Response data Elements
  • moved, type: integer Number of files moved successfully.
  • failed, type: integer Number of files failed the operation.
Get Details
Returns the details for a file.

file/get-details
Url: https://api.embedspace.com/v1.0/file/get-details

Parameters
  • slot, type: string, required EmbedSpace storage slot name (username).
  • file, type: string, required The path of a file on EmbedSpace. You specify the values in mentioned formats.

Request Sample:
file-get-details request
JSON
{
"slot": "myslot",
"file": "f:af08245bfe0f9b6"
}

Response:
file-get-details response
JSON
{
"status": 200,
"response": "OK",
"request": "file/get-details",
"data": {
	"details": {
		"id": "af08245bfe0f9b6",
		"name": "New Open.docx",
		"created_at": 1614523732,
		"created_by": {
			"account_id": "548412522",
			"display_name": "Peter John"
		},
		"last_modified": 1616082295,
		"last_modified_by": {
			"account_id": "548412522",
			"display_name": "Peter John"
		},
		"versions": 1,
		"storage_used": 1336461,
		"size": 1336461,
		"type": "binary/octet-stream",
		"owner": {
			"account_id": "478412522",
			"display_name": "Sony Singh"
		},
		"slot": "alameenlr",
		"parent_folder": {
			"id": "df08245bfe0f8f7",
			"name": "Building_5"
		},
		"location": "Site/Images/Building_5/"
	}
}
}
Response data Elements
  • details, File details Details of requested file.
    • id, type: string A unique identifier for the file.
    • name, type: string Name of the file.
    • created_at, type: integer The Unix timestamp, when the user deleted the version.
    • created_by, User Info Which user created the file.
      • account_id, type: string The account ID of the user.
      • display_name, type: string The display name of the user.
    • last_modified, type: integer The Unix timestamp indicating when the user modified the file.
    • last_modified_by, User Info User info who is modified the file last.
      • account_id, type: string The account ID of the user.
      • display_name, type: string The display name of the user.
    • versions, type: integer How many versions of the file still active.
    • storage_used, type: integer The total file size(sum of all version) in bytes.
    • size, type: integer The file size(current version) in bytes.
    • type, type: string A standard MIME type describing the format of the file data.
    • owner, User Info File owner information.
      • account_id, type: string The account ID of the user.
      • display_name, type: string The display name of the user.
    • slot, type: string Which EmbedSpace storage slot holds the file.
    • parent_folder, Parent folder info Folder information.
      • id, type: string A unique identifier for the folder.
      • name, type: string Name of the folder.
    • path, type: string Path to the file realated to slot.
Operations on Folders

There are various operations which can be done on a folder in EmbedSpace. The operation request format is folder/operation. Send JSON arguments through a POST request with ES-Authorization header for every operation. Returns JSON-encoded responses, and uses standard HTTP response codes.
Path formats
The empty string ("") or, forward slash ("/") or, zero ("0") represents the root folder. All other paths should not start with a slash (e.g. "hello/welcome/"). Paths end with a slash.

Every folder in EmbedSpace also has an ID (e.g. for folder "d:WaA1ck3f") that can be obtained from it's details. These IDs are case-sensitive, so they should always be stored with their case preserved, and always compared in a case-sensitive manner. A path relative to a folder's ID can be constructed by using a slash (e.g. "d:WaA1ck3f/samplefolder/"). If you're using paths related to ID's will reduce traversal and responses fastly.
Create Folder
Creates a new empty folder within the specified parent folder.

folder/create-folder
Url: https://api.embedspace.com/v1.0/folder/create-folder

Parameters
  • slot, type: string, required EmbedSpace storage slot name (username).
  • path, type: string, Where the folder to be created, in the user's storage slot.
  • new_folder, type: string, required Name of new folder. Folder name does not contain / * ? " ' : < > | & #

Request Sample:
create-folder request
JSON
{
"slot": "myslot",
"path":"2008/Images/Animated/",
"new_folder": "New Folder"
}

Response:
create-folder response
JSON
{
"status": 200,
"response": "OK",
"request": "file/create-folder",
"data": {
	"folder": {
		"name": "New Folder",
		"id": "a4d24cde7b2a9",
		"created_at": 1616264311
	}
}
}
Response data Elements
  • folder,New folder info Details about newly created folder.
    • id, type: string A unique identifier for the folder.
    • name, type: string Name of the folder.
    • created_at, type: integer The Unix timestamp, when the user created the folder.
List Items
Returns items in a folder or storage slot.

folder/list-items
Url: https://api.embedspace.com/v1.0/folder/list-items

Parameters
  • slot, type: string, required EmbedSpace storage slot name (username).
  • path, type: string, Where the folder to be created, in the user's storage slot.
  • only_folders, type: boolean, default: false, List folders only.
  • only_files, type: boolean, default: false, List files only.
  • sort, Sort by, Sort the List. By default sorted by File/Folder Name in ascending order.
    • by, type: string Items are always sorted by their name first, with folders listed before files. Value is one of name, last_modified, created_at, size
    • direction, type: string The direction to sort results in. This can be either in alphabetical ascending ASC or descending DESC order.
  • start_from, type: integer, default: 0 Where you want to start listing from. EmbedSpace begins listing after this defined value, in ascending order of name. If it's 0, start at the beginning of the list.
  • max_results, type: integer, default: 100, max: 100 Sets the maximum number of items in the response that will be returned. The action returns up to 100 key names by default.

Request Sample:
list-items request
JSON
{
"slot": "myslot",
"path":"2008/Images/Animated/",
"only_folders": false,
"only_files": false,
"sort":{	
	"by":"name",
	"direction": "ASC"
},
"start_from": 30,
"max_results": 50
}

Response:
list-items response
JSON
{
"status": 200,
"response": "OK",
"request": "folder/list-items",
"data": {
	"folders": [
		{
			"name": "New Folder",
			"id": "a40bff82ee32f",
			"created_at": 1616264311,
			"created_by": "4516264313",
			"last_modified_at": "4516264313",
			"last_modified_by": 1616264311,
		},
		{
			"name": "New Folder2",
			"id": "2a9903fc9d70b",
			...
		},
		...
	],
	"files": [
		{
			"name": "sample1.jpg",
			"id": "fc9d70bff8e32f",
			"created_at": 1616264311,
			"created_by": "4516264313",
			"last_modified_at": "4516264313",
			"last_modified_by": 1616264311,
			"size": 46454311,
			"versions": 142
		},
		{
			"name": "sample2.jpg",
			"id": "GTf4eDYwNTYzYzc3",
			...
		},
		...
	]
}
}
Response data Elements
  • folders, folder infotype: array Details about folders.
    • name, type: string Name of the folder.
    • id, type: string A unique identifier for the folder.
    • created_at, type: integer The Unix timestamp, when the user created the folder.
    • created_by, type: string The account ID of the user, who created the file.
    • last_modified_at, type: integer The Unix timestamp, when the user modified the folder.
    • last_modified_by, type: string The account ID of the user, who created the file.
  • files, file infotype: array Details about files.
    • name, type: string Name of the folder.
    • id, type: string A unique identifier for the folder.
    • created_at, type: integer The Unix timestamp, when the user created the folder.
    • created_by, type: string The account ID of the user, who created the file.
    • last_modified_at, type: integer The Unix timestamp, when the user modified the folder.
    • last_modified_by, type: string The account ID of the user, who created the file.
    • size, type: integer The file size(current version) in bytes.
    • versions, type: integer How many versions of the file still active.
Public Access
Sets direct access permission on folders.

folder/public-access
Url: https://api.embedspace.com/v1.0/folder/public-access

Parameters
  • slot, type: string, required EmbedSpace storage slot name (username).
  • folders, type: array, required Specifies the folder(s) for set public-access permission. You specify the values in mentioned formats.
  • public_access, type: boolean, required setting public-access permission of folder(s).

Request Sample:
folder-public-access request
JSON
{
"slot": "myslot",
"folders": [
	"d:e8fc19d1153eb4/Images/Animated/",
	"d:e8fc19d1153eb4/Images/Films/",
	"d:1a131c5a888c9"
],
"public_access": true
}

Response:
folder-public-access response
JSON
{
"status": 200,
"response": "OK",
"request": "folder/public-access",
"data": {}
}
Delete
Delete the folder or folders, either permanently or by moving it to the trash. This request will delete all the contents in the folder(s).

folders/delete
Url: https://api.embedspace.com/v1.0/folder/delete

Parameters
  • slot, type: string, required EmbedSpace storage slot name (username).
  • folders, type: array, required Specifies the folder(s) for delete. You specify the values in mentioned formats.
  • permanent, type: boolean, required If it is true folder(s) will be deleted permanently, else go to trash.

Request Sample:
folder-delete request
JSON
{
"slot": "myslot",
"folders": [
	"d:e8fc19d1153eb4/Images/Animated/",
	"d:e8fc19d1153eb4/Images/Films/",
	"f:2a131c5a888c3"
],
"permanent": true
}

Response:
file-delete response
JSON
{
"status": 200,
"response": "OK",
"request": "folder/delete",
"data": {
	"deleted_at": 45426889
}
}
List Shared with
Returns the members who have been shared with a folder, in ascending order of Email address associated with the member.

folder/list-shared-members
Url: https://api.embedspace.com/v1.0/folder/list-shared-members

Parameters
  • slot, type: string, required EmbedSpace storage slot name (username).
  • folder, type: string, required Specifies the folder for which you want to see members. You specify the values in mentioned formats.
  • users_start_from, type: integer, default: 0 Where you want to start listing from. Starts users listing after this specified value. If it is 0 start listing from beginning.
  • users_max_results, type: integer, default: 100, max: 100 Sets the maximum number of users returned in the response. By default the action returns up to 100.
  • invitees_start_from, type: integer, default: 0 Where you want to start listing from. Starts invitees listing after this specified value. If it is 0 start listing from beginning.
  • invitees_max_results, type: integer, default: 100, max: 100 Sets the maximum number of invitees returned in the response. By default the action returns up to 100.

Request Sample:
folder-list-shared-members request
JSON
{
"slot": "myslot",
"file": "d:af08245bfe0f9b6",
"users_start_from": 30,
"users_max_results": 50,
"invitees_start_from": 30,
"invitees_max_results": 50,
}

Response:
folder-list-shared-members response
JSON
{
"status": 200,
"response": "OK",
"request": "folder/list-shared-members",
"data": {
	"users": [
		{
			"account_id": "48866815",
			"display_name": "Muhammad Iqbal",
			"email": "[email protected]",
			"permission": "rw"
		},
		...
	],
	"invitees": [
		{
			"email": "[email protected]",
			"permission": "r"
		},
		...
	]
}
}
Response data Elements
  • users,File users info type: array The list of users of the shared file.
    • account_id, type: string The account ID of the user.
    • display_name, type: string The display name of the user.
    • email, type: string Email address of user.
    • permission, type: string The (read/write) permission given to the user.
  • invitees,Invitees info type: array The list of invited members of a file, but have not logged in and claimed this.
    • email, type: string Email address of user.
    • permission, type: string The (read/write) permission given to the member.
Share with
To share folder(s) with member(s), using the email address, the path of the folder(s), and the permission the user should have when accessing the folder.

folder/share-with
Url: https://api.embedspace.com/v1.0/folder/share-with

Parameters
  • slot, type: string, required EmbedSpace storage slot name (username).
  • folders, type: array, required Specifies the folder(s) to which to add members. You specify the values in mentioned formats.
  • members,Folder members info type: array The intended list of members to add.
    • email, type: string Email address of user.
    • permission, type: string The (read/write) permission given to the user.

Request Sample:
folder-share-with request
JSON
{
"slot": "myslot",
"folders": [
	"d:e8fc19d1153eb4/Images/Animated/",
	"d:e8fc19d1153eb4/Images/Films/",
	"d:1a131c5a888c9"
],
"members": [
	{
		"email": "[email protected]",
		"permission": "r"
	},
	{
		"email": "[email protected]",
		"permission": "w"
	}
	...
]
}

Response:
folder-share-with response
JSON
{
"status": 200,
"response": "OK",
"request": "folder/share-with",
"data": {}
}
Remove Shared members
Removes access permission for folder(s) from specific user(s).

folder/remove-shared-members
Url: https://api.embedspace.com/v1.0/folder/remove-shared-members

Parameters
  • slot, type: string, required EmbedSpace storage slot name (username).
  • folders, type: array, required Specifies the folders(s) from which to remove members. You specify the values in mentioned formats.
  • members,Folder members info type: array The members to remove from the folder(s).
    • email, type: string Email address of user.

Request Sample:
folder-remove-shared-members request
JSON
{
"slot": "myslot",
"folders": [
	"d:e8fc19d1153eb4/Images/Animated/",
	"d:e8fc19d1153eb4/Images/Films/",
	"d:1a131c5a888c9"
],
"members": [
	{
		"email": "[email protected]"
	},
	{
		"email": "[email protected]"
	}
	...
]
}

Response:
folder-remove-shared-members response
JSON
{
"status": 200,
"response": "OK",
"request": "folder/remove-shared-members",
"data": {}
}
Rename
To rename a folder in EmbedSpace. If there's a conflict with any folder EmbedSpace will return error.

folder/rename
Url: https://api.embedspace.com/v1.0/folder/rename

Parameters
  • slot, type: string, required EmbedSpace storage slot name (username).
  • folder, type: string, required Specifies the folder which you intend to rename. You specify the values in mentioned formats.
  • new_name, type: string, required New name of the folder. file name does not contain / * ? " ' : < > | & #

Request Sample:
folder-rename request
JSON
{
"slot": "myslot",
"file": "d:ff0824345e0f9b6",
"new_name": "New Folder Name"
}

Response:
folder-rename response
JSON
{
"status": 200,
"response": "OK",
"request": "folder/rename",
"data": {
	"last_modified": 154789236,
	"modified_by": 457516645
}
}
Response data Elements
  • last_modified, type: integer The Unix timestamp of when the user deleted the version.
  • modified_by, type: string The account ID of the modifier.
Move Folders
Move folder(s) to a different location.

folder/move-folders
Url: https://api.embedspace.com/v1.0/folder/move-folders

Parameters
  • slot, type: string, required EmbedSpace storage slot name (username).
  • folders, type: array, required Specifies the source folders(s) to be moved. You specify the values in mentioned formats.
  • move_to, type: string, required Path in the user's slot that is the destination.
  • create_folder, type: boolean, default: true Create new folder or folders if the destination does not exists. If it is false return error.

Request Sample:
move-folders request
JSON
{
"slot": "myslot",
"folders": [
	"d:e8fc19d1153eb4/Images/Animated/",
	"d:e8fc19d1153eb4/Images/Films/",
	"d:1a131c5a888c9"
],
"move_to": "2008/Images/Destination/",
"create_folder": true
}

Response:
move-folders response
JSON
{
"status": 200,
"response": "OK",
"request": "folder/move-folders",
"data": {
	"moved": 3,
	"failed": 0
}
}
Response data Elements
  • moved, type: integer Number of folders moved successfully.
  • failed, type: integer Number of folders failed the operation.
Get Details
Returns the details for a folder.

folder/get-details
Url: https://api.embedspace.com/v1.0/folder/get-details

Parameters
  • slot, type: string, required EmbedSpace storage slot name (username).
  • folder, type: string, requiredThe path of a folder on EmbedSpace. You specify the values in mentioned formats.

Request Sample:
folder-get-details request
JSON
{
"slot": "myslot",
"folder": "d:af08245bfe0f9b6/Images/Net/"
}

Response:
folder-get-details response
JSON
{
"status": 200,
"response": "OK",
"request": "folder/get-details",
"data": {
	"details": {
		"id": "af08245bfe0f9b6",
		"name": "March",
		"created_at": 1614523732,
		"created_by": {
			"account_id": "3",
			"display_name": "Al Ameen"
		},
		"contains": {
			"folders": 5,
			"files": 124
		},
		"last_modified": 1616082295,
		"last_modified_by": {
			"account_id": "3",
			"display_name": "Al Ameen"
		},
		"storage_used": 1336461,
		"size": 1336461,
		"owner": {
			"account_id": "3",
			"display_name": "Al Ameen"
		},
		"slot": "alameenlr",
		"parent_folder": {
			"id": "2f08245bfe0f8b6",
			"name": "2020"
		},
		"location": "Reports/Financial/2020/"
	}
}
}
Response data Elements
  • details, Folder details Details of requested folder.
    • id, type: string A unique identifier for the file.
    • name, type: string Name of the file.
    • created_at, type: integer The Unix timestamp, when the user deleted the version.
    • created_by, User Info Which user created the file.
      • account_id, type: string The account ID of the user.
      • display_name, type: string The display name of the user.
    • items_count, Items count Number of items inside a folder.
      • folders, type: integer Count folders and its subfolders in requested folder.
      • files, type: integer Count the files in the requested folder and its subfolders.
    • last_modified, type: integer The Unix timestamp indicating when the user modified the file.
    • last_modified_by, User Info User info who is modified the file last.
      • account_id, type: string The account ID of the user.
      • display_name, type: string The display name of the user.
    • storage_used, type: integer The total file size(sum of all version) in bytes.
    • size, type: integer The file size(current version) in bytes.
    • type, type: string A standard MIME type describing the format of the file data.
    • owner, User Info File owner information.
      • account_id, type: string The account ID of the user.
      • display_name, type: string The display name of the user.
    • slot, type: string Which EmbedSpace storage slot holds the file.
    • parent_folder, Parent folder info Folder information.
      • id, type: string A unique identifier for the folder.
      • name, type: string Name of the folder.
    • path, type: string Path to the file realated to slot.
EmbedSpace provides High Performance,
Cost Effective and Scalable Cloud Storage.
Get in touch If you have any questions or just want to say hi, please feel free to send us an email to:


[email protected]
© 2023 EmbedSpace All Rights Reserved