Authentication Process
3 Login and Authorization to Canto
7 Get Canto Account Name using a Refresh Token
8 Obtain client_credentials token
Methods
5 List the content of specified scheme
8 List content of a specified album
15 Remove keyword from content
30 Get specified content Usage History report
31 Get specified content Share Activity report
32 Get specified content Download Activity report
33 Get specified content View Activity report
38 Obtain asset preview CloudFront URL
39 Obtain asset donwload’s CloudFront URL
46 Batch permanently delete content
47 Get folder/album detail info
General Notes:
Canto's API uses the OAuth 2.0 protocol for authorization. Every API request must contain an access_token parameter with the OAuth 2.0 access token.
This document covers the methods and techniques required to access, create, and modify content (assets, folders and albums) in Canto through our RESTful API. The API assumes you have a user account for Canto. The document references the http call as https://[your domain].canto.com where your domain is the domain name (Canto account name) you currently use.
Throughout this document we will use https://obj.canto.com as an example.
If you are a global account with URL format https://[your domain].canto.global, please substitute all API calls with https:// [your domain].canto.global.
a) API Compatibilty
Future API versions may add new endpoints or parameters. In order to keep older verisons working, behaviors and return values of APIs with given parameters will not change from the currently documented behavior and return values. That being said, there are two important exceptions:
o Currently undocumented request parameters (whether they are actually ignored or not) may be given a specific meaning
o objects returned in responses may contain additional keys in the future
Thus, if you want to be future-proof, you should avoid passing undocumented parameters (as they may cause a different behavior in the future), and should avoid strict checks on the keys of objects found in responses. The current version is v1. So each path will start with /api/v1. Once we update the API to a newer version, we will maintain /api/v1 as it is, and we will use “/api/v2” as the new version.
b) SSL only
We require that all requests are done over SSL.
c) Date format
All dates in the API are strings in the following format:
20150415063836418
yyyyMMddHHmmssSSS
The sequence refers to the year, month, day, hour, minute, second and millisecond format.
Note: If the date format is not available, the response will be of the same format that’s in the original file.
d) Access Token
By default you need to use an access token or the server will reject your request (401 status code).
For example, the API to retrieve the current user info, you should retrieve it as the following s:
curl -v -H 'Authorization: Bearer ya29.BwH2aP6rApmqH6eNqylimHjX0_iJ8Wah5S8-OM2U7SZreoLibKn-d3j4AVpC-t4fr7NgOdVNNscQcA'
-H 'User-Agent: App Canto Publishing ' “https://yourdomain.canto.com/api/v1/user”
e) HTTP Status Codes
The Canto API uses standard HTTP response codes to indicate errors.
Status Code | Description |
200 | Request processed successfully |
400 |
|
401 |
|
403 | Access Token is invalid or missing |
404 | Results (or page) not found (will also return this in case of arbitrary content/album/folder ID) |
500 | Unexpected Error |
503 | Server inaccessible |
f) General Properties
The following properties are used in Canto:
Scheme: Image, Video, Audio, Document, Presentation, and Other.
Id: Id of the Folder, Album or Asset
Created: Original created time.
Time: Last modified time.
Owner: The User Id of first the uploader.
OwnerName: The Username of the asset owner.
g) Pagination
For this API call there are 2 scenarios:
a. Always return the complete set;
b. Return selected results.
In the first scenario, we provide “sortBy” and “sortDirection” parameters to sort the result.
In the second scenario, we will provide 2 extra parameters including “limit” and “start” to follow pagination. The response will return a ‘found’ field, which states the number of assets found.
For example, if the “found” is 680, and we use the default value for “limit” which is 100, then there would be a total of 7 pages:
To display the 1st page, and display files [0 to 99], you will use the Parameters: “?start=0&limit=100”
To display the 2nd page, and display files [100 to 199], you will use the Parameters: “?start=100&limit=100”
To display the 3rd page, and display files [200 to 299], you will use the Parameters: “?start=200&limit=100”
To display the 4th page, and display files [300 to 399], you will use the Parameters: “?start=300&limit=100”
To display the 5th page, and display files [400 to 499], you will use the Parameters: “?start=400&limit=100”
To display the 6th page, and display files [500 to 599], you will use the Parameters: “?start=500&limit=100”
To display the 7th page, and display files [600 to 679], you will use the Parameters: “?start=600&limit=100”
h) API Rate Limit
Rate limits are how many API calls you can make in a given time frame. If your call exceeds the pre-defined Rate Limit, listed below, you will run into a “429” http error-code. After which, you will need to wait until you can make another API call.
Rate Limit Levels
Customer Rate level | |
level 1: | 1000 times per minutes |
level 2: | 500 times per minutes |
level 3: | 300 times per minutes |
level 4: | 200 times per minutes |
Trial User Rate level | |
level 1: | 500 times per minutes |
level 2: | 300 times per minutes |
level 3: | 200 times per minutes |
level 4: | 100 times per minutes |
API Call Rate Limits Based on Rate Limit Levels
| API name | Rate level | |
1 | List all API endpoints | 1 | |
2 | Get current user info | 1 | |
3 | Get content detail | 2 | |
4 | Download content | 1 | |
5 | List the content of specified scheme | 4 | |
6 | Get whole tree view | 3 | |
7 | Get sub tree view | 3 | |
8 | List content of a specified album | 4 | |
9 | Get upload setting | 1 | |
10 | Upload file to amazon s3 | 1 | |
11 | Query upload status | 2 | |
12 | Attach tag to content | 2 | |
13 | Remove tag from content | 2 | |
14 | Attach keyword to content | 2 | |
15 | Remove keyword from content | 2 | |
16 | Create folder | 2 | |
17 | Create album | 2 | |
18 | Global search | 4 | |
19 | Filter | 4 | |
20 | Advanced search | 4 | |
21 | Batch Edit Content Get | 2 | |
22 | Batch Edit Content Apply | 4 | |
23 | Get preset list | 2 | |
24 | Advance download Image | 2 | |
25 | Share Contents Link | 2 | |
26 | Batch Assign Content to Album | 4 | |
27 | Remove Contents from Album | 4 | |
28 | Create Upload Link | 2 | |
29 | Add a keyword | 2 | |
30 | Get specified content Usage History report | 2 | |
31 | Get specified content Share Activity report | 2 | |
32 | Get specified content Download Activity report | 2 | |
33 | Get specified content View Activity report | 2 | |
34 | Get custom field list | 2 | |
35 | Add new user | 2 | |
36 | Delete a user | 2 | |
37 | Get user list | 2 | |
38 | Obtain preview’s CloudFront URL | 1 | |
39 | Obtain content donwload’s CloudFront URL | 1 | |
40 | Rename content | 2 | |
41 | Create custom field | 2 | |
42 | Update custom field | 2 | |
43 | Delete custom field | 2 | |
44 | Search under a folder | 4 | |
45 | Batch delete content | 4 | |
46 | Batch permanently delete content | 4 |
For example, with “#44 Search under a folder” the rate limit is level 4, meaning that the API call will limit to 200 times per minute. If you exceed 200 times, you will receive a 429 error code.
Authorization:
1 Access Token
All OAuth endpoints use the following basic parameters. Every third party App needs the following values.
Parameter | Description |
{App Id} | This is a string Canto will provide to you. It represents your App identifier. |
{App Secret} | This is a string Canto will provide to you. It represents your App secret. |
{Redirect Uri} | Your web site URL, which is used for redirect when Canto processes a request and returns the response back to you. |
{Canto OAuth domain url} | https://oauth.canto.com/oauth/
|
2 Canto OAuth page
Open a browser, and use the below url in the address bar
GET https://{ Canto OAuth domain url }/api/oauth2/authorize | ||
Parameter | Required | Description |
response_type | Yes | MUST be set to "code" |
app_id | Yes | Your App identifier, the value is {App Id} |
redirect_uri | No | The redirect URL on third party web site. The value is {Redirect Uri}. If this value is not present, Canto will take the value from your App setting. If this value is present, it must be same as your {Redirect Uri} in the App setting. |
state | No | A value which the {Redirect Uri} will receive alongside access tokens. This is for security purposes, to ensure the response is sent back to the right address. |
|
|
|
Here is a sample url:
https://oauth.canto.com/oauth/api/oauth2/authorize?response_type=code&app_id=4024046ce7ff43119208853efd6f76ac
&redirect_uri=https%3A%2F%2Foauth.canto.com%3A8443%2Foauth%2Frest%2Ftwitter%2Fback&state=abcd
Response | Description |
success | Canto will display the login and authorization page |
fail | If parameter is invalid, Canto will return a 400 http status code alongside a json string. Example: {“error”: “invalid_request”, “error_description”:” Wrong app_id value”} |
| If an exception occurs, Canto will return a 500 http status code. |
3 Login and Authorization to Canto
On the first page, enter your Canto Account URL. Example: “developer.canto.com”
Followed by your username (email address), and then the password.
Canto will then verify the validity of the account.
On the second page, Canto will ask you whether you would like to authorize the App and connect to your Canto account.
If you click “Deny”, Canto will redirect to your {Redirect Uri} to tell you that you have denied the authorization.
For example, you will receive {Redirect Uri}?error=access_denied&error_description=The+user+denied+access+to+your+application
If you click “Agree”, Canto will return the authorization code to your {Redirect Uri} web site.
4 Authorization Code
After you agree to authorize your App, Canto will return an authorization code to your {Redirect Uri} web site.
For example: https://yoursite.com/rest/canto/back?code=y78isjkh4c123u2bcq2&state=abcd
Response | Description |
code | A string token you must exchange for your access token. The authorization code has 1-hour expiration time. |
state | The state you provided earlier. You must validate that this matches your original state. If the state does not match, you should not attempt to exchange the authorization code. |
5 Obtain an Access Token
POST https://{ Canto OAuth domain url }/api/oauth2/token | ||
Parameter | Required | Description |
app_id | Yes | Your App identifier, the value is {App Id} |
app_secret | Yes | Your App Secret, the value is {App Secret} |
grant_type | Yes | To gain access token, the value should be “authorization_code” |
redirect_uri | No | The redirect url on third party web site. The value is {Redirect Uri}. If this value is not present, Canto will take the value from your App setting. If this value is present, it must be same as your {Redirect Uri} in the App setting. |
code | Yes | The authorization code you gain in last step. |
|
|
|
Below is a sample POST request:
curl -v -d "app_id=4024046ce7ff43119208853efd6f76ac&redirect_uri=https%3A%2F%2Foauth.dmc.canto.cn%3A8443%2Foauth%2Frest%2Fyoutube%2Fback&app_secret= 04b88b20a1b847a49ea3e36baa53d7e19d770ee927644585adbc98da58763dbe&grant_type=authorization_code&code= f135cd520c074219a5cac1622bd3415e" oauth.canto.com/oauth/api/oauth2/token
Response | Description |
success | http status code = 200 Canto will return the access token & refresh token, in JSON format: {"accessToken":"d0531d8b5247444fa2249f7f575faffe", "expiresIn":"2592000", "tokenType":"Bearer", "refreshToken":"71b8b869e9144c5f9a2000279e55bf8224143a9bbac342648d976bf5650eeffa"} The “expiresIn” unit is seconds. The access token have 1 month expiration time. The refresh token has 1 year expiration time. |
fail | If some parameters are invalid, like app id, grant_type, redirect_uri are not correct, Canto will return a 400 http status code along with a json string. Example: {“error”: “invalid_request”, “error_description”:” Wrong app_id value”} |
| If authorization code has expired or is incorrect, .etc, Canto will return a 401 http status code alongside a JSON string. Example: {“error”: “authentication_expired”, “error_description”:” Authentication code expired”} |
| If an exception occurs, Canto will return a 500 http status code. |
6 Obtain a Refresh Token
POST https://{ Canto OAuth domain url }/api/oauth2/token | ||
Parameter | Required | Description |
app_id | Yes | Your App identifier, the value is {App Id} |
app_secret | Yes | Your App Secret, the value is {App Secret} |
grant_type | Yes | To refresh access token, the value should be “refresh_token” |
redirect_uri | No | The redirect url on third party web site. The value is {Redirect Uri}. If this value is not present, Canto will take the value from your App setting. If this value is present, it must be same as your {Redirect Uri} in the App setting. |
refresh_token | Yes | The refresh token is used in exchange for an access token. |
|
|
|
Below is a sample POST request:
curl -v -d "app_id=4024046ce7ff43119208853efd6f76ac&redirect_uri=https%3A%2F%2Foauth.dmc.canto.cn%3A8443%2Foauth%2Frest%2Fyoutube%2Fback&app_secret= 04b88b20a1b847a49ea3e36baa53d7e19d770ee927644585adbc98da58763dbe&grant_type= refresh_token&refresh_token=71b8b869e9144c5f9a2000279e55bf8224143a9bbac342648d976bf5650eeffa" oauth.canto.com/oauth/api/oauth2/token
Response | Description |
success | http status code = 200 Canto will return a new access token & refresh token, in JSON format: {"accessToken":"2d35fd02eafa45b79fd58e48d6b23bcd", "expiresIn":"2592000", "tokenType":"Bearer", "refreshToken":"bb14553feadf45b4917190a8fc8435ad8522750c8ca04470be3e47f556e1bf27"} The “expiresIn” unit is second. The access token have 1 month expiration time. The refresh token have 1 year expiration time. When an access token is requested, we also publish a new refresh token. |
fail | If some parameters are invalid, like app id, grant_type, redirect_uri are not correct, .etc, Canto will return a 400 http status code with a json string. Example: {“error”: “invalid_request”, “error_description”:”Wrong redirect_uri value”} |
| If the refresh token has expired or is incorrect, .etc, Canto will return a 401 http status code along with a json string. Example: {“error”: “authentication_fail”, “error_description”:”Invalid refresh token”} |
| If other exception occurs, Canto will return a 500 http status code. |
7 Get Canto Account Name using a Refresh Token
In case you want to know which account, you are connecting to
GET https://{ Canto OAuth domain url }/api/oauth2/tenant/{refresh token} | ||
Parameter | Required | Description |
Refresh token | Yes | The refresh token string you obtained in step #5 |
Below is a sample url:
Response | Description |
success | Will return the hostname (Canto Account Name) you are connecting to, example: development.canto.com |
fail | If refresh token is invalid, Canto will return a 401 http status code along with a json string. Example: {“error”: “authentication_fail”, “error_description”:” Invalid refresh token”} |
| If an exception occurs, Canto will return a 500 http status code. |
8 Obtain client_credentials token
POST https://{ Canto OAuth domain url }/api/oauth2/token | ||
Parameter | Required | Description |
app_id | Yes | Your App identifier, the value is {App Id} |
app_secret | Yes | Your App Secret, the value is {App Secret} |
grant_type | Yes | For client_credentials mode, the value should be “client_credentials” |
scope | No | This allows you to obtain a different role access token. The value is “admin”, “contributor” or “consumer”. If not provided, the default is “admin” role. |
|
|
|
Below is a sample POST request:
curl -v -d "app_id=5909b958eac74764914e9cad927d1523&app_secret= bca8d7d4136047fdb58cbdbfd2dc0b5288832db69345434e845418a3a4bd1d00&grant_type= client_credentials&scope=admin" oauth.canto.com/oauth/api/oauth2/token
Response | Description |
success | http status code = 200 Canto will return an access token, in JSON format: {"accessToken":"2d35fd02eafa45b79fd58e48d6b23bcd", "expiresIn":"2592000", "tokenType":"Bearer", "refreshToken": null} The “expiresIn” unit is second. The access token has 1 month expiration time. For client_credentials mode, we do not provide refresh_token |
fail | If some parameters are invalid, like app id, app_secret, grant_type not correct, .etc, Canto will return a 400 http status code. Also return a json string- Sample: {“error”: “invalid_request”, “error_description”:” Wrong app_id value”} |
| If the app_id does not support client_credentials mode, .etc, Canto will return a 401 http status code. Also return you a json string to tell you what happen. Sample: {“error”: “invalid_grant”, “error_description”:” Fail to create access token”} |
| If other exception occurs, Canto will return a 500 http status code. |
Method:
1 List all API endpoints
View all endpoints as URI templates.
GET https://{Canto domain prefix} | ||
Parameter | Required | Description |
N/A |
|
|
Below is a sample url:
https://yourdomain.canto.com/api/v1
Response | Description |
Success | Http status code 200 and all API endpoints returned as below:
[ { "url": "/api[/p/{pname}]/v1/user", "method": "GET", "description": "get user info", "parameters": [ ], "exceptions": [ ], "return": { "type": "user", "description": "user info", "sampleResult": { "userId": "flightdev@canto.com", "firstName": "first name", "lastName": "last name" } } }, { ... }, { ... }, { ... }, ]
“url” would be the url path for endpoint. “method” would be http method including “GET”, “PUT”, “POST”, etc. “parameter” describe the input parameter. “return” describes the return json. For “type” it will be: “user”, “single_result”, “multiple_result” or “binary”. |
Failure | N/A |
| If other exception occurs, Canto will return you 500 http status code. |
2 Get current user info
Get the current user info, which the access token represent.
GET https://{Canto domain prefix}/user | ||
Parameter | Required | Description |
N/A |
|
|
Below is a sample url:
https://yourdomain.canto.com/api/v1/user
Response | Description |
Success | Http status code 200 and current user info returned as below:
{ "userId": "flightdev@canto.com", "name": "Canto Developer",
"firstName": "Canto", "lastName": "Developer", "email": "flightdev@canto.com",
"portalId": "g-4a7bc30647f7414d81492403337c4838", "portalName": "ga",
"permissions": [ "download", "allowAdobeConnector" ] }
Please refer to general notes above for time format. |
Failure | N/A |
| If other exception occurs, Canto will return you 500 http status code. |
3 Get content detail
Get content details including general properties, URLs, default & additional fields (custom fields), version history and metadata. Use the “detail” URL from URL array to get a preview.
GET https://{Canto domain prefix}/{scheme}/{content id} | ||
Parameter | Required | Description |
scheme (provided in url path) | YES | Image, Video, Audio, Document, Presentation, or Other. Case sensitive. |
content Id (provided in url path) | YES | Id of the content |
Below is a sample url:
https://yourdomain.canto.com/api/v1/image/abcdefghijklmnopqrstuvwxyz
Response | Description |
Success | Http status code 200 and given content detail returned as below:
{ "scheme": "image", "id": "abcdefghijklmnopqrstuvwxyz", "name": "sample.png", "owner": "noreply@canto.com", "ownerName": "first name last name", "description": "the description of the content", "size": "123", "created": "20150415063836418", "time": "20150422063836418", "lastUploaded": "20150418063836418", "url": { "detail": "https://obj.canto.com/smartalbum/image?column=image&id=abcdefghijklmnopqrstuvwxyz", "preview": "https://obj.canto.com/api_binary/v1/image/abcdefghijklmnopqrstuvwxyz/preview", "PNG": "https://obj.canto.com/api_binary/v1/image/abcdefghijklmnopqrstuvwxyz/PNG", "HighJPG": "https://obj.canto.com/api_binary/v1/image/abcdefghijklmnopqrstuvwxyz/HighJPG", "download": "https://obj.canto.com/api_binary/v1/image/abcdefghijklmnopqrstuvwxyz", "LowJPG": "https://obj.canto.com/api_binary/v1/image/abcdefghijklmnopqrstuvwxyz/LowJPG", "metadata": "https://obj.canto.com/api_binary/v1/image/abcdefghijklmnopqrstuvwxyz/metadata", "directUrlOriginal": "https://obj.canto.com/download/image/abcdefghijklmnopqrstuvwxyz/original", "directUrlPreview": "https://obj.canto.com/preview/image/abcdefghijklmnopqrstuvwxyz/800" }, "tag": [ "the", "tag", "list" ], "keyword": [ "the", "keyword", "list" ], "default": { "Name": "original.png", "Content Type": "image/png", "Dimensions": "1024*768 Pixels", "Creation Tool": "Adobe Photoshop CS6", "Author": "specified author", "Copyright": null, "Date modified": "20150422063836418", "Date uploaded": "20150415063836418", "Uploaded by": "noreply@canto.com", "Color": "RGB", "Size": "123" }, "additional": { "Product": "my product", "License Expired Date": "20150401234123714", "License Used Number": "135" }, "versionHistory": [ { "no": "2", "ownerName": "first name last name", "created": "20150418063836418", "time": "20150418063836418", "versionId": "fileversionid2abcdefghighijklmnopqrstuvwxyz", "comment": "version2 comment.", "uri": { "download": "https://obj.canto.com/api_binary/v1/image/abcdefghijklmnopqrstuvwxyz/fileversionid2abcdefghighijklmnopqrstuvwxyz" } }, { "no": "1", "ownerName": "first name last name", "created": "20150415063836418", "time": "20150415063836418", "versionId": "fileversionid1abcdefghighijklmnopqrstuvwxyz", "comment": "version1 comment.", "uri": { "download": "https://obj.canto.com/api_binary/v1/image/abcdefghijklmnopqrstuvwxyz/fileversionid1abcdefghighijklmnopqrstuvwxyz" } } ], "metadata": { "File Type": "image", "Orientation": "Landscape File", "Image Height": "768", "File Name": "original.jpg", "Asset Data Size (Long)": "123", "Finfotool version": "1.1", "Color": "RGB", "Compression": "Deflate/Inflate", "Filter": "Adaptive", "MIME Type": "image/png", "File Modification Date/Time": "2015-04-20 08:08:28", "Bit Depth": "8", "Image Size": "1024x768", "File Type Detail": "PNG", "Interlace": "Noninterlaced", "Color Model": "RGB", "Image Width": "1024" }, "relatedFile": [ { "id": "6jogqp4n6509p01n46bpe6ad0d", "scheme": "image", "displayName": "000000000006075120-f.tif" }, { "id": "dgi99u4vk903ddmvkqq2rdlr52", "scheme": "image", "displayName": "00ca7a61a258439fba783c1dacc118f6.100 - Copy - Copy - Copy.jpg" }, { "id": "fchvm858e90jh1dmjm06a6fq2g", "scheme": "image", "displayName": "000000000006075120-f.tif" } ], "copyright": "copyright", "termsAndConditions": "www.canto.com", "approvalStatus": "Approved", "expirationDate": "20170930150000000" }
“scheme”: “image”, “video”, “audio”, “document”, “presentation”, “other” - All content within Canto will belong to one of these schemes. “id”, “name”, “owner”, “ownerName”, “description” - Details regarding the asset.
The point is the array list of the URL. Each content contains the detail, preview, metadata and download URL. Others are scheme special URL. The detail URL points to the file within your Canto account. “size” means file size in bytes here. “created” means original uploaded time. “time” means last modified time. “lastUploaded” means the uploaded time of latest version. From here we could check whether the binary changed.
“keyword” & “tag” are labeling conventions within Canto.
“default” & “additional” fields can be set in Canto settings.
“versionHistory” shows the upload history of the file.
“relatedFile” this asset’s related file information.
“metadata” extracted from the original file.
“copyright” and “termsAndConditions” values will return if you turn on DRM in Canto setting and set values in detail page.
“approvalStatus” the content status: pending, restricted, approved “expirationDate” if the status is approved, and set the expiration date, then this is the value. The format is “yyyyMMddHHmmssSSS” |
Failure | Http status code 404 for arbitrary content id. |
| If other exception occurs, Canto will return you 500 http status code. |
4 Download content
To download the content, first, retrieve the detail info above (3 Get Content Detail), and then you will get an array named URL. All of them will contain “api_binary” which refers to the binary files in various format. The detail URL will connect to your Canto website if you were able to login to.
The “download” URL gives downloading the original content file. For image content, there are extra 3 URLs, “PNG”, “HighJPG”, “ LowJPG”. You can download the corresponding image format.
The “preview” gives an image view of the content. For example, first page view for document content, and a smaller size image for the image content. By default, the image is “240” pixels (dimension image means the longest size of the width and height when zooming out). To specify the dimension, you could provide slash “/” and dimension number under the preview URL. For example the preview URL is https://yourdomain.canto.com/api_binary/v1/image/abc/preview, you could get a 500 dimension preview image by using “https://yourdomain.canto.com/api_binary/v1/image/abc/preview/500”. If the maximum preview size is 400, the URL only present the 400 dimension preview.
The “metadata” URL will give you the xml file which was extracted from the original file. It has more detail than the metadata returned by the detail API. It follows the original data format, not the one in general notes.
The “play” URL is only for audio and video content. Generally, the file would be smaller than original, and it could be played and represent the original file.
5 List the content of specified scheme
List the content of the specified scheme, page by page. Only brief content info supplied.
GET https://{Canto domain prefix}/{scheme} | ||
Parameter | Required | Description |
scheme (provided in URL path) | YES | One of the image, video, audio, document, presentation, other Case sensitive. |
sortBy | NO | Name, Time, Scheme, Owner, Size. Default sort is time. |
sortDirection | NO | “ascending” or “descending” |
limit | NO | The maximum number of items to be returned. Default is 100. |
start | NO | The offset number of items to be returned. Default is 0. |
Below is a sample url:
https://yourdomain.canto.com/api/v1/{scheme}?sortBy=name&sortDirection=ascending&limit=2&start=10
6 Get full library tree view
Get the whole tree. There’s no pagination option, if you don’t specify the layer parameter, you will get the whole tree info including each folder and each album.
GET https://{Canto domain prefix}/tree | ||
Parameter | Required | Description |
sortBy | NO | One of name, time, scheme, owner, size, default is time. |
sortDirection | NO | “ascending” or “descending” |
layer | NO | The maximum deep number of the folder or album items to be returned. Default is -1 which means no limit. |
Below is a sample url:
https://yourdomain.canto.com/api/v1/tree?sortBy=name&sortDirection=ascending
Response | Description |
Success | Http status code 200 and whole tree returned as below:
{ "orderBy": "name", "sortDirection": false, "results": [ { "scheme": "album", "id": "Q32JS", "name": "topLevelAlbum", "idPath": "Q32JS", "namePath": "topLevelAlbum", "size": "5", "url": { "detail": "https://obj.canto.com/album/Q32JS" }, "owner": "flightdev@canto.com", "description": "top level album", "created": "20150422092222748", "time": "20150422092222748" }, { "scheme": "folder", "id": "U6H66", "name": "dev", "idPath": "U6H66", "namePath": "dev", "url": { "detail": "https://obj.canto.com/folder/U6H66" }, "owner": "flightdev@canto.com", "time": "20150422092441072", "children": [ { "scheme": "folder", "id": "LDM3J", "name": "movie", "idPath": "U6H66/LDM3J", "namePath": "dev/movie", "url": { "detail": "https://obj.canto.com/folder/LDM3J" }, "owner": "flightdev@canto.com", "time": "20150422092501097" }, { "scheme": "folder", "id": "H87HD", "name": "book", "idPath": "U6H66/H87HD", "namePath": "dev/book", "url": { "detail": "https://obj.canto.com/folder/H87HD" }, "owner": "flightdev@canto.com", "time": "20150422092451137", "children": [ { "scheme": "folder", "id": "OH4MP", "name": "computer", "idPath": "U6H66/H87HD/OH4MP", "namePath": "dev/book/computer", "url": { "detail": "https://obj.canto.com/folder/OH4MP" }, "size": "3", "owner": "flightdev@canto.com", "created": "20150422092542069", "time": "20150422092542069" }, { "scheme": "album", "id": "SIR13", "name": "art", "idPath": "U6H66/H87HD/SIR13", "namePath": "dev/book/art", "url": { "detail": "https://obj.canto.com/album/SIR13" }, "size": "2", "owner": "flightdev@canto.com", "created": "20150422092551909", "time": "20150422092551909" } ] } ] } ] }
“idPath” means the full id path from the library root.
“namePath” means the full name path from the library root.
“size” of folder means immediate folder and album count under it.
“size” of album means content number assigned with it.
“created” means the created time.
“time” means the last modified time.
“children” lists all immediate children folders of the parent folder. |
Failure | N/A |
| If other exception occurs, Canto will return you 500 http status code. |
7 Get sub tree view
Get the sub tree under specified folder. Folders and albums under the folder will be returned. Only folders can contain folder or album, album can only contain content, so please don’t specify album id.
GET https://{Canto domain prefix}/tree/{folder id} | ||
Parameter | Required | Description |
folder Id (provided in url path) | YES | Parent folder id |
sortBy | NO | Name, Time, Scheme, Owner, Size. Default sort is time. |
sortDirection | NO | “ascending” or “descending” |
layer | NO | The maximum deep number of the folder or album items to be returned. Default is -1 which means no limit. |
Below is a sample url:
https://yourdomain.canto.com/api/v1/tree/H87HD?sortBy=name&sortDirection=ascending
Response | Description |
Success | Http status code 200 and sub tree under the given folder returned as below:
{ "orderBy": "name", "sortDirection": false, "results": [ { "scheme": "folder", "id": "OH4MP", "name": "computer", "idPath": "U6H66/H87HD/OH4MP", "namePath": "dev/book/computer", "url": { "detail": "https://obj.canto.com/folder/OH4MP" }, "size": "3", "owner": "flightdev@canto.com", "created": "20150422092542069", "time": "20150422092542069" }, { "scheme": "album", "id": "SIR13", "name": "art", "idPath": "U6H66/H87HD/SIR13", "namePath": "dev/book/art", "url": { "detail": "https://obj.canto.com/album/SIR13" }, "size": "2", "owner": "flightdev@canto.com", "created": "20150422092551909", "time": "20150422092551909" } ] } “idPath” means the full id path from the library root.
“namePath” means the full name path from the library root.
“size” of folder means immediate folder and album count under it.
“size” of album means content number assigned with it.
“created” means the created time.
“time” means the last modified time.
“children” lists all immediate children folders of the parent folder. |
Failure | Http status code 404 for arbitrary folder id. |
| If other exception occurs, Canto will return you 500 http status code. |
8 List content of a specified album
List content of an album, page by page. Only brief content info returned.
GET https://{Canto domain prefix}/album/{album id} | ||
Parameter | Required | Description |
album Id (provided in url path) | YES | Parent album id |
sortBy | NO | Name, Time, Scheme, Owner, Size. Default sort is time. |
sortDirection | NO | “ascending” or “descending” |
limit | NO | The maximum number of items to be returned. Default is 100. |
start | NO | The offset number of items to be returned. Default is 0. |
Below is a sample url:
https://yourdomain.canto.com/api/v1/album/SIR13?sortBy=name&sortDirection=ascending&limit=2&start=10
Response | Description |
Success | Http status code 200 and content list under the given album returned as below:
{ "found": 20, "limit": 2, "start": 10, "sortBy": "name", "sortDirection": "ascending", "results": [ { "scheme": "image", "id": "ob3mim4rf13dn2kc56lv1eko2p", "name": "China_Shanghai.jpg", "url": { "detail": "https://obj.canto.com/smartalbum/image?column=image&id=ob3mim4rf13dn2kc56lv1eko2p", "preview": "https://obj.canto.com/api_binary/v1/image/ob3mim4rf13dn2kc56lv1eko2p/preview", "PNG": "https://obj.canto.com/api_binary/v1/image/ob3mim4rf13dn2kc56lv1eko2p/PNG", "HighJPG": "https://obj.canto.com/api_binary/v1/image/ob3mim4rf13dn2kc56lv1eko2p/HighJPG", "download": "https://obj.canto.com/api_binary/v1/image/ob3mim4rf13dn2kc56lv1eko2p", "LowJPG": "https://obj.canto.com/api_binary/v1/image/ob3mim4rf13dn2kc56lv1eko2p/LowJPG", "metadata": "https://obj.canto.com/api_binary/v1/image/ob3mim4rf13dn2kc56lv1eko2p/metadata" }, "size": "3549975", "owner": "flightdev@canto.com", "ownerName": "Canto Developer", "time": "20150422150212000", "description": "SHANGHAI - November 21" }, { "scheme": "image", "id": "oers558mq96ov5djl3mc0sl31g", "name": "horse.jpg", "url": { "detail": "https://obj.canto.com/smartalbum/image?column=image&id=oers558mq96ov5djl3mc0sl31g", "preview": "https://obj.canto.com/api_binary/v1/image/oers558mq96ov5djl3mc0sl31g/preview", "PNG": "https://obj.canto.com/api_binary/v1/image/oers558mq96ov5djl3mc0sl31g/PNG", "HighJPG": "https://obj.canto.com/api_binary/v1/image/oers558mq96ov5djl3mc0sl31g/HighJPG", "download": "https://obj.canto.com/api_binary/v1/image/oers558mq96ov5djl3mc0sl31g", "LowJPG": "https://obj.canto.com/api_binary/v1/image/oers558mq96ov5djl3mc0sl31g/LowJPG", "metadata": "https://obj.canto.com/api_binary/v1/image/oers558mq96ov5djl3mc0sl31g/metadata" }, "size": "47551", "owner": "flightdev@canto.com", "ownerName": "Canto Developer", "time": "20150422181308000" } ] }
“found” means the total number of the server found. “results” provides a brief list of information on the content.array maintain all brief info list of the content. |
Failure | Http status code 404 for arbitrary album id. |
| If other exception occurs, Canto will return you 500 http status code. |
9 Get upload setting
Before actual uploading, you need to retrieve the following setting
GET https://{Canto domain prefix}/upload/setting | ||
Parameter | Required | Description |
N/A |
|
|
Response | Description |
Success | Http status code 200 and a properties map returned as below:
{ "url": "https://bucket-name.s3-us-west-2.amazonaws.com/", "AWSAccessKeyId": "ACCESS KEY ID", "Policy": "POLICY STRING", "key": "tenant id/flightdev@canto.com/${filename}", "Signature": " Signature " "acl": "private", "x-amz-meta-tag": "", "x-amz-meta-file_name": "${filename}" "x-amz-meta-scheme": "", "x-amz-meta-id": "", "x-amz-meta-album_id": "", } “url” means post form url, action value actually.
Others fields are all request by amazon service. Please provide them in post form honestly. A friendly remind it’s case sensitive.
|
Failure | N/A |
| If other exception occurs, Canto will return you 500 http status code. |
Note: This setting is valid for 5 hours. You will need to retrive settings again after 5 hours to continue use.
10 Upload file
Upload a file directly into the Canto S3 bucket. Construct a form based on the settings retrieved.
The form and policy must be UTF-8 encoded. You can apply UTF-8 encoding to the form by specifying it in the HTML heading or as a request header.
The enclosure type (enctype) must be specified and must be set to multipart/form-data for both file uploads and text area uploads. For more information, refer to RFC 1867.
POST https://bucket-name.s3-us-west-2.amazonaws.com/ (the url property retrieved from upload setting) | ||
Parameter | Required | Description |
other properties | YES | Provide the value as the setting given. |
x-amz-meta-album_id | YES | Which album the content assigned to. Provide empty string if you want none. |
x-amz-meta-scheme | YES | Provide the original scheme if you want to upload a new version, otherwise just empty string. |
x-amz-meta-id | YES | Provide the original id if you want to upload a new version, otherwise just empty string. |
file | YES | The file or content must be the last field in the form. Any fields below it is ignored. You cannot upload more than one file at a time. |
A sample form like below:
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Post file directly to s3</title>
</head>
<body>
<form action="https://default-public-bucket.s3-us-west-2.amazonaws.com/" method="POST" enctype="multipart/form-data">
Key to upload: <input type="input" name="key" value="bucket-name/flightdev@canto.com/${filename}"/><br />
ACL: <input type="input" name="acl" value="private" /><br />
AWSAccessKeyId:<input type="input" name="AWSAccessKeyId" value="ACCESS KEY ID" /><br />
Policy:<input type="input" name="Policy" value="Policy String" /><br />
Signature:<input type="input" name="Signature" value="Signature" /><br />
File Name: <input type="input" name="x-amz-meta-file_name" value="${filename}" /><br />
Tags for File: <input type="input" name="x-amz-meta-tag" value="" /><br />
scheme for File: <input type="input" name="x-amz-meta-scheme" value="" /><br />
id for File: <input type="input" name="x-amz-meta-id" value="" /><br />
Album for File: <input type="input" name="x-amz-meta-album_id" value="" /><br />
File: <input type="file" name="file" /> <br />
<!-- The elements after this will be ignored -->
<input type="submit" name="submit" value="Upload to Amazon S3" />
</form>
</body>
</html>
Response | Description |
Success | Http status code 200 nothing returned.
|
Failure | N/A |
Please refer to Amazon document for details. http://docs.aws.amazon.com/AmazonS3/latest/dev/HTTPPOSTForms.html
Note: If you upload 2 or more files have the same name in a short period of time, the later upload may override the previous uploaded file.
To avoid this, you will need to modify the “key” value, add a GUID after the “key” value which will return from “Get Upload Setting” API.
For example, if you were to have 2 files named “abc.jpg,” and you uploaded them together.
The “Get Upload Setting” API will return “key” as "tenant id/flightdev@canto.com/${filename}".
Instead, you can upload the first file with “key” as "tenant id/flightdev@canto.com/${filename}-{GUID1}" and the second file with “key” as "tenant id/flightdev@canto.com/${filename}-{GUID2}".
11 Query upload status
Query upload status for recently file uploading or uploaded.
GET https://{Canto domain prefix}/upload/status | ||
Parameter | Required | Description |
hours | No | An integer of 1..24, and the default value is 1. |
Response | Description |
Success | Http status code 200 and a list returned as below:
{ "found": 20, "results": [ { "id": "ob3mim4rf13dn2kc56lv1eko2p", "name": "China_Shanghai.jpg", "time": "20150422150212000", "status": "processing", “scheme”: “image” }, { "id": " oers558mq96ov5djl3mc0sl31g ", "name": " horse.jpg ", "time": "20150422181308000", "status": "done", “scheme”: “image” }, { ... }, { ... }, { ... } ] }
“id” means identify of the file. At very first period, we don’t have this property. “name” means file name of the uploading. “time” means uploading time. “status” means the status of the uploading file. There are 4 period list below:
n Initial File just uploads to amazon storage. n Queue Waiting for process n Processing Step by step processing n Done Successfully done. You could find it in system now. n Error Something unfortunately happened. You might try it again. “scheme” means which this file belong to.
|
Failure | N/A |
| If other exception occurs, Canto will return you 500 http status code. |
12 Attach tag to content
Attach a tag to specify content (a tag is just a plain text).
PUT https://{Canto domain prefix}/{scheme}/{content id}/tag/{tag} | ||
Parameter | Required | Description |
scheme (provided in URL path) | YES | Image, Video, Audio, Document, Presentation, or Other. Case sensitive Scheme refers to the smart albums within your Canto application. |
content Id (provided in URL path) | YES | Id of the content |
Tag | Yes | The plain text of tag |
Response | Description |
Success | Http status code 200 and nothing returned.
The same response is returned for a tag that has been already applied. |
Failure | Http status code 404 for arbitrary content id. |
| If other exception occurs, Canto will return you 500 http status code. |
13 Remove tag from content
Remove a tag from specify content (a tag is just a plain text).
DELETE https://{Canto domain prefix}/{scheme}/{content id}/tag/{tag} | ||
Parameter | Required | Description |
scheme (provided in URL path) | YES | Image, Video, Audio, Document, Presentation, or Other. Case sensitive Scheme refers to the smart albums within your Canto application. |
content Id (provided in URL path) | YES | Id of the content |
Tag | Yes | The plain text of tag |
Response | Description |
Success | Http status code 200 and nothing returned.
The same response is returned for a tag that has been already applied. |
Failure | Http status code 404 for arbitrary content id. |
| If other exception occurs, Canto will return you 500 http status code. |
14 Attach keyword to content
Attach a keyword to specify content.
PUT https://{Canto domain prefix}/{scheme}/{content id}/keyword/{keyword} | ||
Parameter | Required | Description |
scheme (provided in url path) | YES | Image, Video, Audio, Document, Presentation, or Other. Case sensitive Scheme refers to the smart albums within your Canto application. |
content Id (provided in url path) | YES | Id of the content |
keyword | Yes | The plain text of keyword |
Response | Description |
Success | Http status code 200 and nothing returned.
Get same successfully response for the keyword already attached. |
Failure | Http status code 404 for arbitrary content id. Http status code 404 for arbitrary keyword. |
| If other exception occurs, Canto will return a ‘500’ http status code. |
15 Remove keyword from content
Remove a keyword from specified content.
DELETE https://{Canto domain prefix}/{scheme}/{content id}/keyword/{keyword} | ||
Parameter | Required | Description |
scheme (provided in URL path) | YES | Image, Video, Audio, Document, Presentation, or Other. Case sensitive. Scheme refers to the smart albums within your Canto application. |
content Id (provided in URL path) | YES | Id of the content |
keyword | Yes | The plain text of keyword |
Response | Description |
Success | Http status code 200 and nothing returned.
The same successful response when keyword is already removed. |
Failure | Http status code 404 for arbitrary content id. Http status code 404 for arbitrary keyword. |
| If other exception occurs, Canto will return a ‘500’ http status code. |
16 Create folder
Create a folder under specified folder or library.
POST https://{Canto domain prefix}/folder/{folder name} POST https://{Canto domain prefix}/folder/{parent folder id}/{folder name} | ||
Parameter | Required | Description |
parent Folder ID (provided in url path) | NO | The parent folder id. Empty for library. |
folder Name (provided in url path) | YES | Folder Name, The max length is 80. Avoid using \ / : * ? \" < > or | in name. |
description | NO | The Description of the folder. The max length is 400. |
Response | Description |
Success | Http status code 200 and created folder info returned as below:
{ scheme: "folder", id: "J3V5N", name: "newFolderName", url: { detail: "https://hta.dev.canto.com/folder/J3V5N" }, time: "20151210154909104", namePath: "parentFolderName/newFolderName", idPath: "SRRP7/J3V5N" }
|
Failure | Http status code 404 for arbitrary folder id. Http status code 400 for duplicate folder name. |
| If other exception occurs, Canto will return a ‘500’ http status code. |
17 Create album
Create an album under the specified folder or library.
POST https://{Canto domain prefix}/album/{album name} POST https://{Canto domain prefix}/album/{parent folder id}/{album name} | ||
Parameter | Required | Description |
parent Folder ID (provided in url path) | NO | The parent folder id. Empty for library. |
album Name (provided in url path) | YES | Album Name, The max length is 80. Avoid using \ / : * ? \" < > or | in name. |
description | NO | The Description of the album. The max length is 400. |
Response | Description |
Success | Http status code 200 and created album info returned as below:
{ scheme: "album", id: "J3V5N", name: "newAlbumName", url: { detail: "https://hta.dev.canto.com/album/J3V5N" }, time: "20151210154909104", namePath: "parentFolderName/newAlbumName ", idPath: "SRRP7/J3V5N" }
|
Failure | Http status code 404 for arbitrary folder id. Http status code 400 for duplicate album name. |
| If other exception occurs, Canto will return a ‘500’ http status code. |
18 Global search
List the results of the specified keyword, page by page.
GET https://{Canto domain prefix}/search | ||
Parameter | Required | Description |
keyword | YES | The search term(s) |
sortBy | NO | Name, Time, Scheme, Owner, Size. Default sort is time. |
sortDirection | NO | “ascending” or “descending”, default is descending. |
limit | NO | The maximum number of items to be returned. Default is 100. |
start | NO | The offset number of items to be returned. Default is 0. |
Below is a sample url:
Response | Description |
Success | Http status code 200 and content list returned as below:
{ "found": 2902, "limit": 100, "start": 2900, "sortBy": "name", "sortDirection": " descending ", "results": [ { "scheme": "image", "id": "abcdefghijklmnopqrstuvwxyz", "name": "sample.jpg", "size": "123", "owner": "flightdev@canto.com", "ownerName": "Canto Developer", "time": "20150422070212000", "description": "here is the description", "url": { "detail": "https://obj.canto.com/smartalbum/image?column=image&id=abcdefghijklmnopqrstuvwxyz", "preview": "https://obj.canto.com/api_binary/v1/image/abcdefghijklmnopqrstuvwxyz/preview", "PNG": "https://obj.canto.com/api_binary/v1/image/abcdefghijklmnopqrstuvwxyz/PNG", "HighJPG": "https://obj.canto.com/api_binary/v1/image/abcdefghijklmnopqrstuvwxyz/HighJPG", "download": "https://obj.canto.com/api_binary/v1/image/abcdefghijklmnopqrstuvwxyz", "LowJPG": "https://obj.canto.com/api_binary/v1/image/abcdefghijklmnopqrstuvwxyz/LowJPG", "metadata": "https://obj.canto.com/api_binary/v1/image/abcdefghijklmnopqrstuvwxyz/metadata" } }, { "scheme": "image", "id": "ghijklmnopqrstuvwxyzabcdef", "name": "another.jpg", "size": "123", "owner": "flightdev@canto.com", "ownerName": "Canto Developer", "time": "20150422070212000", "description": "here is the description", "url": { "detail": "https://obj.canto.com/smartalbum/image?column=image&id=ghijklmnopqrstuvwxyzabcdef", "preview": "https://obj.canto.com/api_binary/v1/image/ghijklmnopqrstuvwxyzabcdef/preview", "PNG": "https://obj.canto.com/api_binary/v1/image/ghijklmnopqrstuvwxyzabcdef/PNG", "HighJPG": "https://obj.canto.com/api_binary/v1/image/ghijklmnopqrstuvwxyzabcdef/HighJPG", "download": "https://obj.canto.com/api_binary/v1/image/ghijklmnopqrstuvwxyzabcdef", "LowJPG": "https://obj.canto.com/api_binary/v1/image/ghijklmnopqrstuvwxyzabcdef/LowJPG", "metadata": "https://obj.canto.com/api_binary/v1/image/ghijklmnopqrstuvwxyzabcdef/metadata" } } ] "facets": [{"name": "approval","value": ["Approved","Pending","Restricted"]}, {"name": "scheme","value": ["image","video"]}, {"name": "created","max": 1452021772,"min": 1445901667}, {"name": "dimension","max": 2448,"min": 202}, {"name": "duration","max": 10,"min": 10}, {"name": "keywords","value": ["doristest","Unkeyworded"]}, {"name": "orientation","value": ["Portrait","Landscape"]}, {"name": "owner","value": ["dzuo@canto.com"]}, {"name": "pageNumber"}, {"name": "resolution","max": 72,"min": 1}, {"name": "fileSize","max": 4294967293,"min": 4}, {"name": "storageClass","value": ["standard"]}, {"name": "tags","value": ["doris","test","baby","tree","Untagged"]}], }
“found” the total number of assets found. “results” provides a brief list of information on the content. “facets” return the search range value from cloud search. “name” is the facet name. “value” Returns a string type value from search. “min” Minimum value. Int type. “max” Maximum value. Int type. |
Failure | N/A |
| If other exception occurs, Canto will return you 500 http status code. |
19 Filter
To filter the results, firstly retrieve the detail information above (1 Global Search), then you will get the data using for filter.
General rules: if the filter field type is String (e.g. Keyword), you can search one value or multi value. Some multiple values can have both Filter conditions OR and AND. While some multiple values can only have one Filter condition: OR.
Example for OR: standard|freeze. Example for AND: sunset+beach+people
If the filter field type is int, you can search using a data range. Example for: 0..1233
Parameter | Required | Description | Example format |
keyword | NO | The search term(s) |
|
scheme | NO | Image, Video, Audio, Document, Presentation, or Other. Case sensitive. Scheme refers to the smart albums within your Canto application. | One value: image Multi values with OR: image|video|audio |
keywords | NO | File keywords | One value: business Multi values with OR: home|office Multi values with AND: business+office |
tags | NO | File tags | One value: sunset Multi values with OR: sunset|dawn Multi values with AND: sunset+beach |
storageClass | NO | Storage type, standard, freeze | One value: standard Multi values with OR: standard|freeze |
owner | NO | The user ID | One value: midiclear@163.com Multi values with OR: midiclear@163.com|hello@canto.com |
fileSize | NO | File size | 95073..26893954 |
created | NO | Created time | 1444662143..1452182400 |
approval | NO | It works when the approval process is checked in setting page. Approval status: Approved, Pending, Restricted, Expired | One value: approved Multi values with OR: approved|pending
If you select Expired, you cannot select other status. e.g. cannot use Expired |pending, only use Expired |
dimension | NO | Only for image, e.g.202 px | 77..3840 |
resolution | NO | Only for image, e.g. 15 dpi | 5..350 |
orientation | NO | Only for image, landscape, portrait, square | One value: landscape Multi values: landscape|portrait |
duration | NO | Only for video, audio | 9..1205 |
pageNumber | NO | Only for document, presentation | 6..482 |
meta_{type}_{sequence}
Note: It’s for Custom field filter, previously called Additional field. For "choice" and "multichoice" type, the parameter is meta_{type}_{sequence}_key. | NO | Filter by specified custom field with id. The type means custom field type, including "text", "num", "date", "choice", "multichoice" & "url"; the sequence is an immutable integer given by system. You could find the whole part in web page URL when filter by the same custom field in our system.
The custom field id above should be "meta_text_0". See the screenshot below as another example. | You could use the same value as the web page of our system. Basically for "text", "choice", & "URL" types, simply put what you want; for "num", "date", put a range with ".."; for "multichoice", you could combine more choices with "|" or "+" (which means "OR" and "AND", and for encoding reason please put %7C and %2B instead) |
createdTime | NO | File created time | Value is in Unix time. Ex. 1571042449..1571301649 |
lastModified | NO | File last modified time | Value is in Unix time. Ex. 1571042449..1571301649 |
uploadedTime | NO | File uploaded time | Value is in Unix time. Ex. 1571042449..1571301649 |
Below is a sample url:
https://yourdomain.canto.com/api/v1/search? sortBy=name&sortDirection=ascending&limit=100&start=0&keyword=tiger& tags=sunset|1227&storageClass=freeze&pageNumber=6..482
Response | Description |
Success | Http status code 200 and content list returned as below:
{ "found": 2902, "limit": 100, "start": 2900, "sortBy": "name", "sortDirection": " descending ", "results": [ { "scheme": "image", "id": "abcdefghijklmnopqrstuvwxyz", "name": "sample.jpg", "size": "123", "owner": "flightdev@canto.com", "ownerName": "Canto Developer", "time": "20150422070212000", "description": "here is the description", "url": { "detail": "https://obj.canto.com/smartalbum/image?column=image&id=abcdefghijklmnopqrstuvwxyz", "preview": "https://obj.canto.com/api_binary/v1/image/abcdefghijklmnopqrstuvwxyz/preview", "PNG": "https://obj.canto.com/api_binary/v1/image/abcdefghijklmnopqrstuvwxyz/PNG", "HighJPG": "https://obj.canto.com/api_binary/v1/image/abcdefghijklmnopqrstuvwxyz/HighJPG", "download": "https://obj.canto.com/api_binary/v1/image/abcdefghijklmnopqrstuvwxyz", "LowJPG": "https://obj.canto.com/api_binary/v1/image/abcdefghijklmnopqrstuvwxyz/LowJPG", "metadata": "https://obj.canto.com/api_binary/v1/image/abcdefghijklmnopqrstuvwxyz/metadata" } }, { "scheme": "image", "id": "ghijklmnopqrstuvwxyzabcdef", "name": "another.jpg", "size": "123", "owner": "flightdev@canto.com", "ownerName": "Canto Developer", "time": "20150422070212000", "description": "here is the description", "url": { "detail": "https://obj.canto.com/smartalbum/image?column=image&id=ghijklmnopqrstuvwxyzabcdef", "preview": "https://obj.canto.com/api_binary/v1/image/ghijklmnopqrstuvwxyzabcdef/preview", "PNG": "https://obj.canto.com/api_binary/v1/image/ghijklmnopqrstuvwxyzabcdef/PNG", "HighJPG": "https://obj.canto.com/api_binary/v1/image/ghijklmnopqrstuvwxyzabcdef/HighJPG", "download": "https://obj.canto.com/api_binary/v1/image/ghijklmnopqrstuvwxyzabcdef", "LowJPG": "https://obj.canto.com/api_binary/v1/image/ghijklmnopqrstuvwxyzabcdef/LowJPG", "metadata": "https://obj.canto.com/api_binary/v1/image/ghijklmnopqrstuvwxyzabcdef/metadata" } } ] "facets": [{"name": "approval","value": ["Approved","Pending","Restricted"]}, {"name": "scheme","value": ["image","video"]}, {"name": "created","max": 1452021772,"min": 1445901667}, {"name": "dimension","max": 2448,"min": 202}, {"name": "duration","max": 10,"min": 10}, {"name": "keywords","value": ["doristest","Unkeyworded"]}, {"name": "orientation","value": ["Portrait","Landscape"]}, {"name": "owner","value": ["dzuo@canto.com"]}, {"name": "pageNumber"}, {"name": "resolution","max": 72,"min": 1}, {"name": "fileSize","max": 4294967293,"min": 4}, {"name": "storageClass","value": ["standard"]}, {"name": "tags","value": ["doris","test","baby","tree","Untagged"]}], }
“found” the total number of assets found. “results” provides a brief list of information on the content. “facets” return the search range value from cloud search. “name” is the facet name. “value” Returns a string type value from search. “min” Minimum value. Int type. “max” Maximum value. Int type. |
Failure | N/A |
| If other exception occurs, Canto will return you 500 http status code. |
20 Advanced Search
List the results of searching from combination of any 6 fields which include filename, description, comment, keywords, author, and tags using operator “and” “or”.
Parameter | Required | Description |
keyword | YES | The search term(s) |
searchInField | YES | You can search from fields which include filename, description, comment, keywords, author, tags, documenttext, smarttags and customfields. If you input other field name, the results will ignore it. |
operator | YES | Operator, and, or. Default is and. |
Below is a sample url:
https://yourdomain.canto.com /api/v1/search?sortBy=name&sortDirection=ascending&searchInField=filename
Response | Description |
Success | Http status code 200 and content list returned as below:
{ "found": 2902, "limit": 100, "start": 2900, "sortBy": "name", "sortDirection": " descending ", "results": [ { "scheme": "image", "id": "abcdefghijklmnopqrstuvwxyz", "name": "sample.jpg", "size": "123", "owner": "flightdev@canto.com", "ownerName": "Canto Developer", "time": "20150422070212000", "description": "here is the description", "url": { "detail": "https://obj.canto.com/smartalbum/image?column=image&id=abcdefghijklmnopqrstuvwxyz", "preview": "https://obj.canto.com/api_binary/v1/image/abcdefghijklmnopqrstuvwxyz/preview", "PNG": "https://obj.canto.com/api_binary/v1/image/abcdefghijklmnopqrstuvwxyz/PNG", "HighJPG": "https://obj.canto.com/api_binary/v1/image/abcdefghijklmnopqrstuvwxyz/HighJPG", "download": "https://obj.canto.com/api_binary/v1/image/abcdefghijklmnopqrstuvwxyz", "LowJPG": "https://obj.canto.com/api_binary/v1/image/abcdefghijklmnopqrstuvwxyz/LowJPG", "metadata": "https://obj.canto.com/api_binary/v1/image/abcdefghijklmnopqrstuvwxyz/metadata" } }, { "scheme": "image", "id": "ghijklmnopqrstuvwxyzabcdef", "name": "another.jpg", "size": "123", "owner": "flightdev@canto.com", "ownerName": "Canto Developer", "time": "20150422070212000", "description": "here is the description", "url": { "detail": "https://obj.canto.com/smartalbum/image?column=image&id=ghijklmnopqrstuvwxyzabcdef", "preview": "https://obj.canto.com/api_binary/v1/image/ghijklmnopqrstuvwxyzabcdef/preview", "PNG": "https://obj.canto.com/api_binary/v1/image/ghijklmnopqrstuvwxyzabcdef/PNG", "HighJPG": "https://obj.canto.com/api_binary/v1/image/ghijklmnopqrstuvwxyzabcdef/HighJPG", "download": "https://obj.canto.com/api_binary/v1/image/ghijklmnopqrstuvwxyzabcdef", "LowJPG": "https://obj.canto.com/api_binary/v1/image/ghijklmnopqrstuvwxyzabcdef/LowJPG", "metadata": "https://obj.canto.com/api_binary/v1/image/ghijklmnopqrstuvwxyzabcdef/metadata" } } ] "facets": [{"name": "approval","value": ["Approved","Pending","Restricted"]}, {"name": "scheme","value": ["image","video"]}, {"name": "created","max": 1452021772,"min": 1445901667}, {"name": "dimension","max": 2448,"min": 202}, {"name": "duration","max": 10,"min": 10}, {"name": "keywords","value": ["doristest","Unkeyworded"]}, {"name": "orientation","value": ["Portrait","Landscape"]}, {"name": "owner","value": ["dzuo@canto.com"]}, {"name": "pageNumber"}, {"name": "resolution","max": 72,"min": 1}, {"name": "fileSize","max": 4294967293,"min": 4}, {"name": "storageClass","value": ["standard"]}, {"name": "tags","value": ["doris","test","baby","tree","Untagged"]}], }
“found” the total number of assets found. “results” provides a brief list of information on the content. “facets” return the search range value from cloud search. “name” is the facet name. “value” Returns a string type value from search. “min” Minimum value. Int type. “max” Maximum value. Int type. |
Failure | N/A |
| If other exception occurs, Canto will return you 500 http status code. |
21 Batch Edit Content Get
Get Information Field Values of Multi-Content Being Edited.
POST https://{Canto domain prefix}/batch/edit | ||
Parameter | Required | Description |
scheme | YES | One of the image, video, audio, document, presentation, other |
id | YES | Id of the content |
Below is a sample of request parameters:
[{"id":"iim463p68p59t11cijqfchd066","scheme":"presentation"},{"id":"jshc6m631l41n758lj3525tl1i","scheme":"document"},{"id":"dafmf4ma291bf7243s9tg35s2j","scheme":"image"}]
Response | Description |
Success | Http status code 200 and content list returned as below: { " availableKeywords ": ["ASKW_1","Animal","AveryKey","HectorKeyword","Search test keyword","hector test keyword","test keyword"], "approvalStatus": ["Approved"], "expirationDate": ["2016-05-29 00:00"], "autoApproveDate": null, "tag": ["ASKW_1"], "keyword": ["ASKW_1"] , "description": ["000"], "Number": ["30"], "Text": ["test."], "Date": ["2019-02-10"], "SingleChoice": ["A"], "MultiChoice": ["B", "C"], "Url": ["https://www.baidu.com/"], "Label": ["#55AEFF"], "Rating": ["4"] }
availableKeywords: available keywords for select. approvalStatus, expirationDate, autoApproveDate, description:if mutli select document have the same value,return this value,else return null. tag, keyword: return the same tag or keyword from mutli select document.if all different return null. Number, Text, Date, SingleChoice, MultiChoice, Url, Label, Rating is Custom fields. |
Failure | N/A |
| If other exception occurs, Canto will return you 500 http status code. |
22 Batch Edit Content Apply
Save the information fields of the batch edit content.
This API can use to batch edit description, approvalStatus, expirationDate, keyword, tag, author, comment and Custom field.
PUT https://{Canto domain prefix}/batch/edit | ||
Parameter | Required | Description |
contents | YES | Multi select document |
scheme | YES | One of the image, video, audio, document, presentation, other |
id | YES | Id of the content |
properties | YES | Set properties |
propertyId | YES | Properties name. You can edit from properties name which include description, approvalStatus, expirationDate, autoApproveDate, keyword, tag, author, comment and Custom field name. |
propertyValue | YES | Properties value, permit an empty string. When property name is expirationDate/autoApproveDate,value format by YYYY-MM-DD HH:mm. When property name is keyword or tag, the mutli value separates by comma. When property is a DATE Custom field, value format by YYYY-MM-DD. When property is a SINGLECHOICE or MULTICHOICE Custom field, The value should refer to the response of Get Custom Field List API. When property is a LABEL Custom field, value is hexadecimal representation of the color, like #FFFFFF. It can be multiple. When property is a RATING Custom field, values can range from 1 to 5. MULTICHOICE and Label Custom fields may have multiple values, so their property values should be an array. |
action | NO | Permit an empty string. When property name is description, action is one of append or cover. Empty string default cover. When property name is keyword, tag or MULTICHOICE, LABEL Custom field, action is one of add or remove. Empty string default add. |
customField | NO | When the property is a Custom field, the value must be true. |
Below is a sample of request parameter:
{"contents":[{"id":"iim463p68p59t11cijqfchd066","scheme":"presentation"},{"id":"jshc6m631l41n758lj3525tl1i","scheme":"document"},{"id":"dafmf4ma291bf7243s9tg35s2j","scheme":"image"}],"properties":[{"propertyId":"description","propertyValue":"909090","action":"append"},{"propertyId":"approvalStatus","propertyValue":"Approved"},{"propertyId":"expirationDate","propertyValue":"2020-01-01 00:00"},{" propertyId":"keyword","propertyValue":"test keyword","action":"add"},{"propertyId":"keyword","propertyValue":"ASKW_1","action":"remove"},{"propertyId":"tag","propertyValue":"ASKW_1","action":"add"}, {"propertyId":"Number","propertyValue":"20","customField":true},{"propertyId":"Text","propertyValue":"test","customField":true},{"propertyId":"Date","propertyValue":"2019-01-01","customField":true},{"propertyId":"SingleChoice","propertyValue":"A","customField":true},{"propertyId":"MultiChoice","propertyValue": ["a, b, c \" /\\","m1"],"customField":true,"action":"add"},{"propertyId":"Rating","propertyValue":"4","customField":true},{"propertyId":"Label","propertyValue":["#FFFFFF", "#000000"]," customField":true,"action":"add"},{"propertyId": "author", "propertyValue": "Administrator"}, {"propertyId": "comment", "propertyValue": "this is comment"}]}
Response | Description |
Success | Http status code 200 and content list returned as below: success
|
Failure | N/A |
| If other exception occurs, Canto will return you 500 http status code. |
23 Get Preset List
Before preset downloading, firstly you need to retrieve this list.
GET https://{Canto domain prefix}/tenant/download/presets | ||
Parameter | Required | Description |
N/A |
|
|
Below is a sample url:
https://yourdomain.canto.com/api/v1/tenant/download/presets
Response | Description |
Success | Http status code 200 and a list returned as below:
[
“id” is the presetId, it is a param in advance download api. “height” & “width” is the dimension of the result image. “keepAspectRatio” control the result image ratio.
|
Failure | N/A |
| If other exception occurs, Canto will return you 500 http status code. |
24 Advance Download Options
This API support resize, crop, and download a preset image.
GET https://{Canto domain url}/api_binary/v1/advance/image/{content id}/download | ||
Parameter | Required | Description |
resize (provided in url path) | No | Resize param, use ”widthxheight” format. Example: 300x400 |
crop (provided in url path) | No | crop param, use ”widthxheight+top+left” format. Example: 500x400+30+30 |
dpi(provided in url path) | No | Result image dpi |
type(provided in url path) | No | Result image type {“jpg”, “png”} |
version(provided in url path) | No | The content version. It means latest version if it is null. |
preset(provided in url path) | No | Preset id. You can get the preset list by preset list API. |
Below is some sample url:
Response | Description |
Success | Http status code 200 and a download url as below:
https://d15cl5q7pq68a5.cloudfront.net/downloaddata/81e584d8-9700-4ba7-b30b-f1a35824dc53/f3d964e004814b3284a9b33c3778b90a_17c182d0abd844c8afd0729ebb37b4f6?response-content-disposition=attachment%3B filename%2A%3DUTF-8%27%27photos%2520not%2520loading.png&Expires=1532763833&Signature=dcd0cFfciJdCf97tGLG~VAOlFSWc8vzF6gApZNT3AkbgS6hOR27u6oO1uMKQvInz86WXTHYcCUrVf9zt~glQxJ2Vv2mc5YphrAWbGbHBMErb~04zQ4-lEgSqoWJFRuGdVmb3DtXUCDoCNyQiTRUYk-QHhDZ4D6T3eZgnkcOu5taU~KO5BRydn44HNMxrTOrYg3gYCeCpYWelLLxaM2RRHcscTCAOZW52d5tkOqXRK2I4zqq9UBpcrbF1GqjvqdovLP53TsQf6p7JGbA9dajACKvMtry-3KhRKrBi9lxjJ5az8kI8EFkkib3WHWakQdTNOHqerK2A4hk9-LYlP7cPkw__
It will be redirect to s3 download url, and expired after a while.
|
Failure | N/A |
| If other exception occurs, Canto will return you 500 http status code. |
25 Create Share Links
This API support batch share contents.
PUT https://{Canto domain url}/api /v1/share/batch | ||
Parameter | Required | Description |
contents | YES | Mutli select document Example: "contents":[{"id":"go536odumd2oj29r806ohfv75k", "scheme":"image"}, { "id":"he4c8lmtk11kn3d92f5nbf2j47", "scheme":"image"}] |
scheme | YES | One of the image, video, audio, document, presentation, other |
id | YES | Id of the content |
shareDetail | YES | Share Links setting. Example: "shareDetail":{"expires":"2018-11-08", "hideShareBy":true, "allowDownloadOriginal":true, "allowCropAndResize":true, "allowPresets":true,}, |
expires | NO | If null, never expired. |
hideShareBy | YES | If true, the shared by user will be hidden |
allowDownloadOriginal | YES | If true, downloading Original file is available. If false, image can be downloaded as converted content. |
allowCropAndResize | YES | If true, the download page will show crop and resize options. |
allowPresets | YES | If true, can be downloaded as a preset. |
Below is a sample of request paramter:
{"shareDetail":{ "expires":"2018-11-08", "hideShareBy":true, "allowDownloadOriginal":true, " allowCropAndResize":true, "allowPresets":true, }, "contents":[ { "id":"go536odumd2oj29r806ohfv75k", "scheme":"image" }, { "id":"he4c8lmtk11kn3d92f5nbf2j47", "scheme":"image"} ]}
Response | Description |
Success | Share links Url.
https:// yourdomain.canto.com /s/{sharedId} |
Failure | N/A |
| If other exception occurs, Canto will return you 500 http status code. |
26 Assign Content to Album
This API support batch assign contents to an album.
POST https://{Canto domain url}/api /v1/ batch/album | ||
Parameter | Required | Description |
contents | YES | Mutli select document Example: "contents":[{"id":"go536odumd2oj29r806ohfv75k", "scheme":"image"}, { "id":"he4c8lmtk11kn3d92f5nbf2j47", "scheme":"image"}] |
scheme | YES | Image, Video, Audio, Document, Presentation, Other |
id | YES | Id of the content |
displayName | YES | Display name of content |
Below is a sample of request paramter:
{"albumPath":"MRL4P","contents":[{"id": "unkjs3q20p5vhflb21v7f56n5i", "displayName": "eclipse_update_120.jpg", "scheme": "image"}, {"id": "v4m6a7bfut23de6lc07q1flg0q", "displayName": "eclipse_update_121.jpg", "scheme": "image"}]}
Response | Description |
Success | N/A |
Failure | Return fail Result array, e.g. [ {"id": " ackjs3q20p5vhflb21v7f56n5h ", "displayName": "eclipse_update_121.jpg","reason":"exceptionKey"} ] |
| If other exception occurs, Canto will return you 500 http status code. |
27 Remove Contents from Album
This API support batch remove contents of an album.
DELETE https://{Canto domain url}/api /v1/batch/album | ||
Parameter | Required | Description |
contents |