API-Reference | EmbedSpace

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:

Create authorization headers ES-Authorization, ES-File values to authenticate the request.
ES-Slot name of storage slot.
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

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:

Create authorization headers ES-Authorization, ES-File values to authenticate the request.
ES-Slot name of storage slot.
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:

Create authorization headers ES-Authorization, ES-File values to authenticate the request.
ES-Slot name of storage slot.
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>
}");

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)

client-js file upload

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:

Create authorization headers ES-Authorization, ES-File values to authenticate the request.
ES-Slot name of storage slot.
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 100^th version of a file, then 101^st version will become 100^th 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": "user1@example.com",
			"permission": "rw"
		},
		...
	],
	"invitees": [
		{
			"email": "invite2@example.com",
			"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": "user1@example.com",
		"permission": "r"
	},
	{
		"email": "user2@example.com",
		"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": "user1@example.com"
	},
	{
		"email": "user2@example.com"
	}
	...
]
}

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": "user1@example.com",
			"permission": "rw"
		},
		...
	],
	"invitees": [
		{
			"email": "invite2@example.com",
			"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": "user1@example.com",
		"permission": "r"
	},
	{
		"email": "user2@example.com",
		"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": "user1@example.com"
	},
	{
		"email": "user2@example.com"
	}
	...
]
}

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.