This documentation describes the Cloudsto.re new Core Web Services API

Version 2.0 (Released Jan 2019)

Accessing the API

Make all requests to: https://api.cloudsto.re/core TLS 1.2 (or better) encryption is required for all calls to all the Cloudsto.re Web Services. TLS version 1.1 and earlier are not supported.

Cloudsto.re API

The Cloudsto.re API is designed as RESTful API. All API calls are implemented as httpMethod: POST. The HTTP response codes 200 is success responses, all other response codes are errors. Data will only be returned for HTTP response code 200. Error descriptions can be obtained from the response body. See Error handling section for further information.

Request Data

All request data sent to the Cloudsto.re API must be in JSON objects. See the section for each API call for the full details of the request data format. The content-type header should be set accordingly to application/x-www-form-urlencoded .

Return Data

Return data from the API is in JSON objects by default. See the section for each API call for the full details of the return values within the response object. JSON is the recommended data format for returned data and accept header should be set to either: application/json or */*. (XML format data returns can be requested by setting the accept header to application/xml, This feature is currently experimental and not fully tested)

Authentication

Each API call should contain an API key for authentication. API keys are created when you are registered to use the service (see /APIKey endpoint for further onformation)

Request an API Key for the account to be used with all subsequent API calls for authorisation. API keys should be stored in memory by the calling app for the use within the session, but you are encouraged to make a new call for API Key between sessions and not to store the key locally. The API Key may change periodically for security reasons.

This call also returns some additional information about the business associated with the login.

Request 

{ 
  "Username": "user@example.com",
  "Password" : "mypassword"
}

Parameters

Response

{
   "APIKey": "x-a3A1qLrXStYDgThU3dfA",
   "BusinessID" : "BS-25",
   "BusinessName": "Artsto.re",
   "CurrencyCode" : "GBP",
   "IsPublisher" : false
}

Parameters

JQuery Example

$.ajax({
    url: "https://api.cloudsto.re/core/apikey",
    contentType: 'application/x-www-form-urlencoded',
    dataType: 'json',
    type: 'POST', 
    data: JSON.stringify({“Username”:“user@example.com”,
                          "Password" : "mypassword"}),    
    success: function(response) {
               // process returns
    },
    error: function(err) {
               // handle error
    }
});

cURL Example

$curl -d '{“Username” : “user@example.com”,"Password" : "mypassword"}' \
      -X POST https://api.cloudsto.re/core/apikey

Request a list of all information about this account’s publisher.

Only accounts with publisher privilege are allowed to get paper media information.

Request 

{   
  "APIKey": "x-a3A1qLrXStYDgThU3dfA"
}

Parameters

Response

{  
    "PublisherID":"PB-27", 
    "PublisherName":"imagesto.re",
    "CostValue": 50.0,
    "CostUnit": 5,
    "FixedCostValue": 0,
    "PremiumFactor": 1,
    "PublisherAvailable" : true,
    "FactorP" : 1,
    "CurrencyCode" "GBP",
    "CurrencyExchangeGBP" : 1,
    "CurrencyExchangeUSD" : 1.3,
    "CurrencyExchangeEUR" : 1.2
}

Parameters

JQuery Example

$.ajax({
    url: "https://api.cloudsto.re/core/publisher",
    contentType: 'application/x-www-form-urlencoded',
    dataType: 'json',
    type: 'POST', 
    data: JSON.stringify({“APIKey”:“x-a3A1qLrXStYDgThU3dfA”}),    
    success: function(response) {
          $.each(response.Medias, function(index, value) {
               // process returns
          });
    },
    error: function(err) {
               // handle error
    }
});

cURL Example

$curl -d '{"APIKey" : "x-a3A1qLrXStYDgThU3dfA"}' \
      -X POST https://api.cloudsto.re/core/publisher

Request a specific or list of all business information associated with this account’s publisher.

Only accounts with publisher privilege are allowed to get business information.

Request 

{   
  "APIKey": "x-a3A1qLrXStYDgThU3dfA",
  "BusinessID" : "BS-14"
}

Parameters

Response

{  
   "Count":1,
   "Business":[  
      {  
         "PublisherID" : "PB-15"
         "BusinessID":"BS-27", 
         "BusinessName":"Online Business",
         "CurrencyCode": "GBP",
         "CostFactorB": 1.2,
         "Available" : true
      }
   ]
}

Parameters

JQuery Example

$.ajax({
    url: "https://api.cloudsto.re/core/publisher/business",
    contentType: 'application/x-www-form-urlencoded',
    dataType: 'json',
    type: 'POST', 
    data: JSON.stringify({“APIKey”:“x-a3A1qLrXStYDgThU3dfA”}),    
    success: function(response) {
          $.each(response.Medias, function(index, value) {
               // process returns
          });
    },
    error: function(err) {
               // handle error
    }
});

cURL Example

$curl -d '{"APIKey" : "x-a3A1qLrXStYDgThU3dfA"}' \
      -X POST https://api.cloudsto.re/core/publisher/business

Request a list of all paper media information associated with this account’s publisher.

Only accounts with publisher privilege are allowed to get paper media information.

Request 

{   
  "APIKey": "x-a3A1qLrXStYDgThU3dfA"
}

Parameters

Response

{  
   "Count":1,
   "Medias":[  
      {  
         "MediaID":"MD-27", 
         "MediaName":"Standard Paper",
         "CostValue": 50.0,
         "CostUnit": 5,
         "FixedCostValue": 0,
         "MediaFactor": 1,
         "Premium":false,
         "Available" : true
      }
   ]
}

Parameters

JQuery Example

$.ajax({
    url: "https://api.cloudsto.re/core/publisher/medias",
    contentType: 'application/x-www-form-urlencoded',
    dataType: 'json',
    type: 'POST', 
    data: JSON.stringify({“APIKey”:“x-a3A1qLrXStYDgThU3dfA”}),    
    success: function(response) {
          $.each(response.Medias, function(index, value) {
               // process returns
          });
    },
    error: function(err) {
               // handle error
    }
});

cURL Example

$curl -d '{"APIKey" : "x-a3A1qLrXStYDgThU3dfA"}' \
      -X POST https://api.cloudsto.re/core/publisher/medias

Add a new publisher paper media.

Only accounts with publisher privilege are allowed to update publisher paper media parameters.

Request 

{ 
  "APIKey": "x-a3A1qLrXStYDgThU3dfA",
  "MediaName" : "Standard Paper",
  "MediaFactor" : 1.0,
  "Premium" : false,
  "CostValue" : 40.50
  "CostUnit" : 5,
  "FixedCostValue" : 10,
  "Available" : true
}

Parameters

Response

{
  PaperMediaID: 'PM-100'
}

Parameters

JQuery Example

$.ajax({
    url: "https://api.cloudsto.re/core/publisher/medias/add",
    contentType: 'application/x-www-form-urlencoded',
    dataType: 'json',
    type: 'POST', 
    data: JSON.stringify({“APIKey”:“x-a3A1qLrXStYDgThU3dfA”,"MediaName":"Paper","MediaFactor" : 1.25}),    
    success: function(response) {
               // process returns
    },
    error: function(err) {
               // handle error
    }
});

cURL Example

$curl -d '{“APIKey”:“x-a3A1qLrXStYDgThU3dfA”,"MediaName":"Paper", "MediaFactor" : 1.25}' \
      -X POST https://api.cloudsto.re/core/publisher/medias/add

Remove a publisher paper media.

Only accounts with publisher privilege are allowed to update publisher paper media parameters.

Request 

{ 
  "APIKey": "x-a3A1qLrXStYDgThU3dfA",
  "MediaID": "PM-27"
}

Parameters

Response

{
  Message: 'Success!'
}

Parameters

JQuery Example

$.ajax({
    url: "https://api.cloudsto.re/core/publisher/medias/remove",
    contentType: 'application/x-www-form-urlencoded',
    dataType: 'json',
    type: 'POST', 
    data: JSON.stringify({“APIKey”:“x-a3A1qLrXStYDgThU3dfA”,"MediaID":"PM-27"}),    
    success: function(response) {
               // process returns
    },
    error: function(err) {
               // handle error
    }
});

cURL Example

$curl -d '{“APIKey”:“x-a3A1qLrXStYDgThU3dfA”,"MediaID":"PM-27"}' \
      -X POST https://api.cloudsto.re/core/publisher/medias/remove

Update information about publisher paper media.

Only accounts with publisher privilege are allowed to update publisher paper media parameters.

Request 

{ 
  "APIKey": "x-a3A1qLrXStYDgThU3dfA",
  "MediaID": "PM-27",
  "MediaName" : "Standard Paper",
  "MediaFactor" : 1.0,
  "Premium" : false,
  "CostValue" : 40.50
  "CostUnit" : 5,
  "FixedCostValue" : 10,
  "Available" : true
}

Parameters

Response

{
  Message: 'Success!'
}

Parameters

JQuery Example

$.ajax({
    url: "https://api.cloudsto.re/core/publisher/medias/update",
    contentType: 'application/x-www-form-urlencoded',
    dataType: 'json',
    type: 'POST', 
    data: JSON.stringify({“APIKey”:“x-a3A1qLrXStYDgThU3dfA”,"MediaID":"PM-27","MediaFactor" : 1.25}),    
    success: function(response) {
               // process returns
    },
    error: function(err) {
               // handle error
    }
});

cURL Example

$curl -d '{“APIKey”:“x-a3A1qLrXStYDgThU3dfA”,"MediaID":"PM-27", "MediaFactor" : 1.25}' \
      -X POST https://api.cloudsto.re/core/publisher/medias/update

Update information about publisher.

Only accounts with publisher privilege are allowed to update publisher parameters.

Request 

{ 
  "APIKey": "x-a3A1qLrXStYDgThU3dfA",
  "FactorP" : 1.25,
  "CurrencyExchangeGBP" : 1.0,
  "CurrencyExchangeEUR" : 1.15,
  "CurrencyExchangeUSD" : 1.25,
  "CostValue" : 40.50
  "CostUnit" : 5,
  "FixedCostValue" : 10,
  "PremiumFactor" : 1.2
}

Parameters

Response

{
  Message: 'Success'
}

Parameters

JQuery Example

$.ajax({
    url: "https://api.cloudsto.re/core/publisher/update",
    contentType: 'application/x-www-form-urlencoded',
    dataType: 'json',
    type: 'POST', 
    data: JSON.stringify({“APIKey”:“x-a3A1qLrXStYDgThU3dfA”,"FactorP" : 1.25}),    
    success: function(response) {
               // process returns
    },
    error: function(err) {
               // handle error
    }
});

cURL Example

$curl -d '{“APIKey”:“x-a3A1qLrXStYDgThU3dfA”,"FactorP" : 1.25}' \
      -X POST https://api.cloudsto.re/core/publisher/update

Publisher level users have access to the secure Vault for listing, uploading and image manipulation.

The Vault data model is a flat structure: a publisher has a unique Vault, and the vault stores image objects. There is no hierarchy of sub-vaults or sub-folders. However, you can infer logical hierarchy using key name prefixes. Suppose that your Vault has four objects with the following object keys:

Artist-1/portrait-675.jpg
Artist-2/london-543.tiff
Private/sea-6754.jpg
aeroplane.jpg

The key name prefixes (Artist-1/, Artist-2/, and Private/) and delimiter (‘/’) are used to infer hierarchy and introduce the concept of folders.

Request removal of an uploaded image. this request will delete the image file, thumbnail and associated entry in images database.

Only images that have not been used in jobs or user galleries can be deleted.

Only accounts with Publisher right and the owner of the uploaded image is allowed to delete the image.

Request 

{ 
  "APIKey": "x-a3A1qLrXStYDgThU3dfA",
  "PublisherID" : "15",
  "ImageID" : "IM-22"
}

Parameters

Response

{  
   "Message": "Success"
}

Parameters

JQuery Example

$.ajax({
    url: "https://api.cloudsto.re/core/vault/remove",
    contentType: 'application/x-www-form-urlencoded',
    dataType: 'json',
    type: 'POST', 
    data: JSON.stringify({“APIKey”:“x-a3A1qLrXStYDgThU3dfA”,"PublisherID":"15","ImageID : "IM-22"}),    
    success: function(response) {
               // process returns
    },
    error: function(err) {
               // handle error
    }
});

cURL Example

$curl -d '{“APIKey”:“x-a3A1qLrXStYDgThU3dfA”,"PublisherID":"15","ImageID : "IM-22"}' \
      -X POST https://api.cloudsto.re/core/vault/remove

Update information about an uploaded image.

Request 

{ 
  "APIKey": "x-a3A1qLrXStYDgThU3dfA",
  "PublisherID" : "PB-123",
  "ImageID" : "IM-342",
  "ImageAvailable" : true,
  "Artist" : "Frans Deerek",
  "Category" : "Skyline",
  "ItemName" : "Sky Portrait",
  "Reference" : "XD1234",
  "CostValue" : 40.50
  "CostUnit" : 5,
  "PrintLimit" : 100,
  "MaxPrintSize : 250,
  "Tags_en" : [ "sky", "Sun", "Sea"],
  "Tags_it" : []
}

Parameters

Response

{
  Message: 'Success'
}

Parameters

JQuery Example

$.ajax({
    url: "https://api.cloudsto.re/core/vault/update",
    contentType: 'application/x-www-form-urlencoded',
    dataType: 'json',
    type: 'POST', 
    data: JSON.stringify({“APIKey”:“x-a3A1qLrXStYDgThU3dfA”,"PublisherID" : "PB-123","ImageID" : "IM-342","ImageAvailable" : true}),    
    success: function(response) {
               // process returns
    },
    error: function(err) {
               // handle error
    }
});

cURL Example

$curl -d '{“APIKey”:“x-a3A1qLrXStYDgThU3dfA”,"PublisherID" : "PB-123","ImageID" : "IM-342","ImageAvailable" : true}' \
      -X POST https://api.cloudsto.re/core/vault/update

The process of upload of an image involves a time sequence events starting by requesting an upload of an image. The following time sequence diagram shows the sequence of events involved in the upload of an image.

The upload request call can contain one or more request for upload with the Image Keys specifying the path including the file name. The return from API call will contain a time-limited authorized upload link for each Image Key requested. This link is valid for 60 minutes and gives full access to upload a binary image. Example of uploads are shown below. Once the files have been uploaded, the system will process and add to catalogue. The images are typically available within minutes.

Only accounts with publisher privilege are allowed to upload images.

Image Keys

Each image object has a key. Image key (or key name) uniquely identifies the object in the Vault.

When you upload an image, you specify the key name, which uniquely identifies the image object in the Vault.  These names are the object keys. The name for a key is a sequence of Unicode characters whose UTF-8 encoding should at most be 1024 bytes long.

Image Recognition

AutoTag Image facility is a Deep Learning powered Image Recognition service that detects objects, scenes, and faces;  it also extracts text and recognises celebrities. AutoTag Image service identifies thousands of objects such as vehicles, pets, and furniture. AutoTag service also detects scenes within an image, such as a sunset or beach. The service is continually trained on new data to expand its ability to recognise objects, scenes, and activities to improve its ability to accurately analyse images.

This service makes it easy to generate tags for  large image libraries. The upload call can request the use of AutoTag service to automatically generate tags for the uploaded image. The tags are also automatically translated to all supported languages.

Exif

The upload service can also read the image metadata and extract EXIF tags to populate image information. Currently the following tags are recognised and used in the image information:

Limitations

The following restrictions on uploaded file is currently in place:

Request 

{ 
  "APIKey": "x-a3A1qLrXStYDgThU3dfA",
  "ImageKeys" : [
      {
         "ImageKey" : "Artist-1/portrait-675.jpg",
         "AutoTag" : true, 
         "AutoExif" : false, 
         "ArtistName" : "John Pierre",
         "ItemName" : "Day at sea",
         "Category" : "Pop Art",
         "CostValue" : 40.0,
         "CostUnit"  : 5,
         "PrintLimit" : 30,
         "MaxPrintSize" : 250
        },
      {
         "ImageKey" : "Artist-2/london-543.tiff",
         "Reference" : "XY0987-DE",
         "Tags_en" : ["sea", "sun", "beach", "water"] 
         "Tags_de" : ["sitz", "sonne", "strand", "wasser"]      
      },
      {
         "ImageKey" : "Private/sea-6754.jpg",
         "Tags_es" : ["noche", "cielo", "ciudad"] 
      },
      {
         "ImageKey" : "aeroplane.jpg"
      }
  ]
}

Parameters

Response

{  
   "Count": 4,
   "ImageKeys":[  
      {  
         "ImageKey" : "Artist-1/portrait-675.jpg",
         "Existing": false,
         "URL" : "https://aodupload.s3.eu-west-1.amazonaws.com/Publisher-XY/315d83d3-6a0d-44af-bcfd-c6d9845b2af3?AWSAccessKeyId=ASIA4LJIRF2XWYM4JIOU&Content-Type=image%2Fjpeg&Expires=1564753951&Signature=vqiHebQ82wwXWY2%2BeH6oLrVS2Aw%3D&x-amz-security-token=keaKcVr3KulyUGOQIgVhkXcB%2Fuk%2BVOItNR181%2BoXDH53wD3B5oaV0lRbzefUgqnAII1v",
     }, 
     {           
         "ImageKey" : "Artist-2/london-543.tiff",
         "Existing": false,          
         "URL" : "https://aodupload.s3.eu-west-1.amazonaws.com/Publisher-XY/09865d83d3-6a0d-88af-bcfd-7856fdb2af3?AWSAccessKeyId=ASIA4LJIRF2XWYM4JIOU&Content-Type=image%2Ftiff&Expires=1564753951&Signature=vqiHebQ82wwXWY2%2BeH6oLrVS2Aw%3D&x-amz-security-token=KcVr3KulyUGOQIgVhkXcB%2Fuk%2BVOItNR181%2BoXDH53wD3B5oaV0lRbzefUgqnAII1v",             
     },  
     {                     
         "ImageKey" : "Private/sea-6754.jpg",    
         "Existing": false,      
         "URL" : "https://aodupload.s3.eu-west-1.amazonaws.com/Publisher-XY/456265d83d3-6a0d-893f-bcfd-78098fse2af3?AWSAccessKeyId=ASIA4LJIRF2XWYM4JIOU&Content-Type=image%2Fjpeg&Expires=1564753951&Signature=vqiHebQ82wwXWY2%2BeH6oLrVS2Aw%3D&x-amz-security-token=keaKcVr3KulyUGOQIgVhkXcB%2Fuk%2BVOItNR181%2BoXDH53wD3B5oaV0lRbzefUgqnAII1v",          
     },  
     {                     
         "ImageKey" : "aeroplane.jpg", 
         "Existing": true,         
         "URL" : "https://aodupload.s3.eu-west-1.amazonaws.com/Publisher-XY/456278643d3-6a7g-89f3f-bdfd-783428fse2af3?AWSAccessKeyId=ASIA4LJIRF2XWYM4JIOU&Content-Type=image%2Fjpeg&Expires=1564753951&Signature=vqiHebQ82wwXWY2%2BeH6oLrVS2Aw%3D&x-amz-security-token=keaKcVr3KulyUGOQIgVhkXcB%2Fuk%2BVOItNR181%2BoXDH53wD3B5oaV0lRbzefUgqnAII1v",           
     }  
  ]
}

Parameters

JQuery Example

Request Upload
$.ajax({
    url: "https://api.cloudsto.re/core/vault/upload",
    contentType: 'application/x-www-form-urlencoded',
    dataType: 'json',
    type: 'POST', 
    data: JSON.stringify({“APIKey”:“x-a3A1qLrXStYDgThU3dfA”,"ImageKeys":[{"ImageKey" : "testfile.jpg","Reference" : "XYPCD"}]}),    
    success: function(response) {
          $.each(response.Transactions, function(index, value) {
               // process returns
          });
    },
    error: function(err) {
               // handle error
    }
});

Upload File
$.ajax({
    url: "https://aodupload.s3.eu-west-1.amazonaws.com/Publisher-XY/456265d83d3-6a0d-893f-bcfd-78098fse2af3?AWSAccessKeyId=ASIA4LJIRF2XWYM4JIOU&Content-Type=image%2Fjpeg&Expires=1564753951&Signature=vqiHebQ82wwXWY2%2BeH6oLrVS2Aw%3D&x-amz-security-token=keaKcVr3KulyUGOQIgVhkXcB%2Fuk%2BVOItNR181%2BoXDH53wD3B5oaV0lRbzefUgqnAII1v",
    type: 'PUT',
    data: file,
    processData: false,
    headers: {'Content-Type': 'image/jpeg'},
    success: function (response) {
               // call success
    }
}).done(function (data) {
       // upload done 
}).fail(function (arg1, arg2) {  
        // upload fail
});

cURL Example

Request Upload
$curl -d '{"APIKey" : "x-a3A1qLrXStYDgThU3dfA","ImageKeys":[{"ImageKey" : "testfile.jpg","Reference" : "XYPCD"}]}' \
      -X POST https://api.cloudsto.re/core/vault/upload

Upload File
$curl -H "Content-Type: image/jpeg" --upload-file imagefile.jpg "https://aodupload.s3.eu-west-1.amazonaws.com/Publisher-XY/456265d83d3-6a0d-893f-bcfd-78098fse2af3?AWSAccessKeyId=ASIA4LJIRF2XWYM4JIOU&Content-Type=image%2Fjpeg&Expires=1564753951&Signature=vqiHebQ82wwXWY2%2BeH6oLrVS2Aw%3D&x-amz-security-token=keaKcVr3KulyUGOQIgVhkXcB%2Fuk%2BVOItNR181%2BoXDH53wD3B5oaV0lRbzefUgqnAII1v"

As part of the upload feature we have an online import facility for uploading images from web browser. You are able to fill a template (csv) file with associated data for the images and use that as part of the upload from cloudsto.re console under your own account.

The console provides the facility to export an empty template (csv) file with correct heading and list of selected files. First select the files you wish to upload, use the export facility to create an empty template and then fill the template file with information about images. You can then Upload images with the associated template file which will populate the database with the provided information.

The following table describes the fields and the format of the data required. If you do not want to provide data for a field, leave it blank (the comma separator should exist for each field). The header line describing the fields should exist as first line. Enter data for each image one per line after the header.

A useful tool for working with csv files is Microsoft® Excel™ (remember to save as csv format with UTF-8 encoding).

Sample Template File (csv)

FileName,ImageKey,Reference,ArtistName,ItemName,Category,CostValue,CostUnit,FixedCostValue,PrintLimit,MaxPrintSize,AutoTag,AutoExif,Tags_en,Tags_de,Tags_es,Tags_fr,Tags_it,Tags_nl
li-yang-138248-unsplash.jpg,test/li-yang-138248-unsplash.jpg,138248,Li Yang,Shanghai,Landscape,,,,,,true,,city|sky|night life|skyscraper,,,,
Gullwing.jpg,test/Gullwing.jpg,,,Mercedes,Cars,true,,,,,,

Errors are returned as standard JSON objects using HTTP statusCode. With error status, the error message text can be obtained from the response body. The HTTP response code 200 is success responses, all other response codes are errors. Data will only be returned for HTTP response code 200.

{
    statusCode: 400,
    body: "Invalid Request"
}

HTTP Status Code