Authentication Process
1     Access Token.
2     Canto OAuth page.
3     Login and Authorization to Canto.
4     Authorization Code.
5     Obtain an Access Token.
6     Obtain a Refresh Token.
7     Get Canto Account Name using a Refresh Token.

Methods
1     List all API endpoints.
2     Get current user info.
3     Get content details.
4     Download content
5     List the content of specified scheme.
6     Get full library tree view.
7     Get sub tree view.
8     List content of a specified album.
9     Get upload setting.
10       Upload file.
11       Query upload status.
12       Apply tag to content.
13       Remove tag from content.
14       Attach keyword to content.
15       Remove keyword from content.
16       Create folder.
17       Create album.
18       Global search.
19       Filter.
20       Advanced Search.
21       Batch Edit Content Get.
22       Batch Edit Content Apply.
23       Get Preset List
24       Advanced Download Options.
25       Create Share Links.
26       Assign Content to Album.
27       Remove Contents from Album.
28       Create Upload Links.
29       Add keywords.



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.

  • 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:

Currently undocumented request parameters (whether they are actually ignored or not) may be given a specific meaning

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.

  • SSL only

We require that all requests are done over SSL.

  • 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.

  • 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”

  • 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 unaccessible
  • 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.

  • Pagination

For this API call there are 2 scenarios:

  • Always return the complete set;
  • 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”

 


Authorization:


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 respones back to you.
{Canto OAuth domain url}
https://oauth.canto.com/oauth/

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.

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.

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.

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.objectiva.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 have 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.

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.objectiva.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.

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:

https://oauth.canto.com/oauth/api/oauth2/tenant/92d2087662bc432c92dda9ad2668b31cb179c157528d485f9a6a1c4a65cf2f4f

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.




Methods:


List all API endpoints

 

View all endpoints as URI templates.

GET https://{Canto domain url}/api/v1
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": "cantodev@canto.com",
                "firstName": "first name", 
                "lastName": "last name"
            }
        }
    },
    { ... },
    { ... },
    { ... },
]
“url” would be the url path for endpoint.
“method” would be the http method including “GET”, “PUT”, “POST”, etc.
“parameter” describes 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 a 500 http status code.

Get current user info

Get the current user info, which the access token represents.

GET https://{Canto domain url}/api/v1/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": "cantodev@canto.com",
 "name": "Canto Developer",
}
Please refer to general notes above for time format.
Failure
N/A

If other exception occurs, Canto will return a 500 http status code.

Get content details

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 url}/api/v1/{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"
    },
    "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",
            "uri": {
                "preview": "https://obj.canto.com/api_binary/v1/image/abcdefghijklmnopqrstuvwxyz/smallpreviewversionid2abcdefghighijklmnopqrstuvwxyz/preview",
                "download": "https://obj.canto.com/api_binary/v1/image/abcdefghijklmnopqrstuvwxyz/fileversionid2abcdefghighijklmnopqrstuvwxyz"
            }
        },
        {
            "no": "1",
            "ownerName": "first name last name",
            "created": "20150415063836418",
            "time": "20150415063836418",
            "versionId": "fileversionid1abcdefghighijklmnopqrstuvwxyz",
            "uri": {
                "preview": "https://obj.canto.com/api_binary/v1/image/abcdefghijklmnopqrstuvwxyz/smallpreviewversionid1abcdefghighijklmnopqrstuvwxyz/preview",
                "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"
},
    "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 or not.
“keyword” & “tag” labeling conventions within Canto.
“default” & “additional” fields can be set in Canto settings.
“versionHistory” shows the upload history of the file.
“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 an expiration date is set, it will return this value. The format is “yyyyMMddHHmmssSSS”
Failure
Http status code 404 for arbitrary content id.

If other exception occurs, Canto will return a 500 http status code.

Download content

To download the content, firstly retrieve the detail info above (3 Get Content Detail), and then you will get an array named url.  All of them contain an “api_binary”, which refers to the binary files in various format. The detail url will connect to your Canto account you were able to login to.

The “download” url gives the original content file. For image content, there are extra 3 urls, “PNG”, “HighJPG”, “LowJPG”. You can download the corresponding image format as you want.

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 means the longest size of the width and height when zooming out). To specifiy the dimension, you could provide slash “/” and dimension number under the preview url. For example, if the preview url is https://yourdomain.canto.com/api_binary/v1/image/abc/preview, you can 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 will only get 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 for audio and video content. Generally the file would be smaller than original , so it can be played and it represents the original file.

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 url}/api/v1/{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

Response
Description
Success
Http status code 200 and content list returned as below:
{
    "found": 2902,
    "limit": 100,
    "start": 2900,
    "sortBy": "name",
    "sortDirection": "ascending",
    "results": [
        {
            "scheme": "image",
            "id": "abcdefghijklmnopqrstuvwxyz",
            "name": "sample.jpg",
            "size": "123",
            "owner": "cantodev@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": "cantodev@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"
            }
        }
    ]
}
 
 
“found” the total number of assets found.
“results” provides a brief list of information on the content.array maintain all brief info list of the content.
Failure
N/A

If other exception occurs, Canto will return a 500 http status code.

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 url}/api/v1/tree
Parameter
Required
Description
sortBy
NO
Name, Time, Scheme, Owner, Size.  Default sort is time.
sortDirection
NO
“ascending” or “descending”
layer
NO
The maximum depth 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": "cantodev@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": "cantodev@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": "cantodev@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": "cantodev@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": "cantodev@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": "cantodev@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.
 
“children” lists all immediate children of the parent folder.
Failure
N/A

If other exception occurs, Canto will return a 500 http status code.

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 url}/api/v1/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 depth 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": "cantodev@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": "cantodev@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.
 
“children” lists all immediate children of the parent folder.
Failure
Http status code 404 for arbitrary folder id.

If other exception occurs, Canto will return a 500 http status code.

List content of a specified album

List content of an album, page by page. Only brief content info is returned.

GET https://{Canto domain url}/api/v1/album/{album id}
Parameter
Required
Description
Album Id (provided in url path)
YES
Parent album id
sortBy
NO
One of name, time, scheme, owner, size,  default 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": "cantodev@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": "cantodev@canto.com",
            "ownerName": "Canto Developer",
            "time": "20150422181308000"
        }
    ]
}
 
“found” the total number of assets 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 a 500 http status code.

Get upload setting

Before uploading a file, you need to retrive this setting.

GET https://{Canto domain url}/api/v1/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/cantodev@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 required by AWS. The values are Case Sensitive.
Failure
N/A

If other exception occurs, Canto will return a 500 http status code.

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 are 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/cantodev@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

Query upload status

Query upload status for recently uploaded files.

GET https://{Canto domain url}/api/v1/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"
        },
        {
            "id": " oers558mq96ov5djl3mc0sl31g ",
            "name": " horse.jpg ",
            "time": "20150422181308000",
            "status": "done"
        },
    { ... },
    { ... },
    { ... }
    ]
}
“id” means identity of the file.
“name” means file name.
“time” means uploading time.
“status” means the status of the uploading file. There are 4 period list below:
  • Initial
  • File uploads to AWS.
  • Queue
  • Waiting in queue to process.
  • Processing
  • Step by step processing.
  • Done
  • Successfully done. You can find it in your Canto library.
  • Error
  • Ran into issue. (Please try again.)
Failure
N/A

If other exception occurs, Canto will return a 500 http status code.

Apply tag to content

Apply a tag to specific content. (A tag is just a plain text.)

PUT https://{Canto domain url}/api/v1/{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 a 500 http status code.

Remove tag from content

Remove a tag from specify content. (A tag is just a plain text.)

DELETE https://{Canto domain url}/api/v1/{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 a 500 http status code.

Attach keyword to content

Attach a keyword to specify content.

PUT https://{Canto domain url}/api/v1/{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 attached.
Failure
Http status code 404 for arbitrary content id.
Http status code 404 for arbitrary keyword.

If other exception occurs, Canto will return ‘500’ http status code.

Remove keyword from content

Remove a keyword from specified content.

DELETE https://{Canto domain url}/api/v1/{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.

Create folder

Create a folder under specified folder or library.

POST https://{Canto domain url}/api/v1/folder/{folder name}
POST https://{Canto domain url}/api/v1/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.

Create album

Create an album under the specified folder or library.

POST https://{Canto domain url}/api/v1/album/{album name}
POST https://{Canto domain url}/api/v1/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.

Global search

List the results of the specified keyword, page by page.

GET https://{Canto domain url}/api/v1/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:

https://yourdomain.canto.com/api/v1/search? sortBy=name&sortDirection=ascending&limit=100&start=0&keyword=tiger

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": "cantodev@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": "cantodev@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 a 500 http status code.

Filter

To filter the results, first retrieve the detail information above (1 global search), and 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 enabled in settings page.
Approval status: Approved, Pending, Restricted,Expired
One value: approved
Multi values with OR: approved|pending
If you select Expired, you cannot select another status.
e.g. cannot use Expired |pending, only use Expired
dimension
NO
Only for image, e.g.202px
77..3840
resolution
NO
Only for image, e.g. 15dpi
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.
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)

Below is a sample url:

https://yourdomain.canto.com/api/v1/search? sortBy=name&sortDirection=ascending&limit=100&start=0&keyword=tiger&amp; tags=sunset|1227&amp; storageClass=freeze&amp; 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": "cantodev@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": "cantodev@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 500 http status code.

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, and tags.  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&limit=100&start=0&keyword=tiger&amp; searchInField = filename&amp; searchInField = tags

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": "cantodev@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": "cantodev@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 500 http status code.

Batch Edit Content Get

Get Information Field Values of Multi-Content Edit

POST https://{Canto domain url}/api/v1/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"],
              "tag": ["ASKW_1"],      
            "keyword": ["ASKW_1"] ,
              "description": ["000"]
}
availableKeywords: Available keywords to use for search.
approvalStatus, expirationDate, description:
When selecting multiple assets, it will return the common values. But if values are different, it will return null.
tag, keyword: Returns the same tag or keyword from the multiple selection. If all the values are different, it will return null.
Failure
N/A

If other exception occurs, Canto will return a 500 http status code.

Batch Edit Content Apply

Save  the information fields of the batch edit content.

PUT https://{Canto domain url}/api/v1/batch/edit
Parameter
Required
Description
contents
YES
Mutli select document

scheme

YES
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, keyword and tag.

propertyValue

YES
Properties value, permit an empty string.
When property name is expirationDate ,value format by YYYY-MM-DD.
When property  name is keyword or tag,the  mutli value separator by comma.

action

NO
Permit an empty string.
When property  name is description,action is one of the append or cover. empty string default cover.
When property name is keyword or tag,action is one of the add or remove.  empty string default add.

Below is a sample of request paramter:

{"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"},{"propertyId":"keyword","propertyValue":"test keyword","action":"add"},{"propertyId":"keyword","propertyValue":"ASKW_1","action":"remove"},{"propertyId":"tag","propertyValue":"ASKW_1","action":"add"}]}

Response
Description
Success
Http status code 200 and content list returned as below:
success
Failure
N/A

If other exception occurs, Canto will return a 500 http status code.

Get Preset List

Before preset downloading, firstly you need to retrieve this list.

GET https://{Canto domain url}/api/v1/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":"adad68e6b17d4f9ab6f0a0300aa9ad3a",
"name":"test",
"description":"small preview",
"height":200,
"width":200,
"keepAspectRatio":false,
"mainLibraryEnabled":true,
"portalEnabled":true
}
]
 “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 a 500 http status code.

Advanced Download Options

This API supports resize, crop, and downloads 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
Example: 72
type (provided in url path)
No
Result image type {“jpg”, “png”}
Example:jpg
version (provided in url path)
No
The content version. If null, the latest version of the content is shown.
preset (provided in url path)
No
Preset ID.  You can get the preset list by preset list API.

Below is a sample url:

Resize: https://yourdomain.canto.com/api_binary/v1/advance/image/ufcm9o04g55j5159mcu3eu5p0a/download?resize=1764x797&type=png&dpi=72

Crop: https://yourdomain.canto.com/api_binary/v1/advance/image/ufcm9o04g55j5159mcu3eu5p0a/download?resize=&crop=1229x789%2B855%2B378&version=&type=jpeg&dpi=72

Preset: https://yourdomain.canto.com/api_binary/v1/advance/image/ufcm9o04g55j5159mcu3eu5p0a/download?resize=&crop=&version=&type=jpeg&dpi=72&preset=adad68e6b17d4f9ab6f0a0300aa9ad3a

Response
Description
Success
Http status code 200 and a download url as shown 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 you redirect to the s3 download url, and is temporarily available.
Failure
N/A

If other exception occurs, Canto will return a 500 http status code.

Create Share Links

This supports batch sharing of content.

PUT https://{Canto domain url}/api /v1/share/batch
Parameter
Required
Description
contents
YES
Select multiple documents.
Example:
"contents":[{"id":"go536odumd2oj29r806ohfv75k",
            "scheme":"image"},
        {  "id":"he4c8lmtk11kn3d92f5nbf2j47",
            "scheme":"image"}]

scheme

YES
Image, Video, Audio, Document, Presentation, Other

id

YES
Id of the content
shareDetail
YES
Settings for the share link:
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 availalable. 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 request:

{"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 link URL:
https:// yourdomain.canto.com /s/{sharedId}
Failure
N/A

If other exception occurs, Canto will return a 500 http status code.

Assign Content to Album

This supports batch assigning contents to an album.

POST https://{Canto domain url}/api /v1/ batch/album
Parameter
Required
Description
contents
YES
Select multiple documents.
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 the content

Below is a sample request:

{"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
Returns a failed result array, e.g.{[ "id": " ackjs3q20p5vhflb21v7f56n5h ", "displayName": "eclipse_update_121.jpg","reason":"exceptionKey"]}

If other exception occurs, Canto will return a 500 http status code.

Remove Contents from Album

This supports batch removal of contents in an album.

DELETE 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
One of the image, video, audio, document, presentation, other

id

YES
Id of the content

displayName

YES
Display name of content

Below is a sample request parameter:

{"albumPath":"MRL4P","contents":[{"id": "unkjs3q20p5vhflb21v7f56n5i", "displayName": "eclipse_update.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.

Create Upload Links

This supports creation of an Upload Link.

POST https://{Canto domain url}/api /v1/uploadlink
Parameter
Required
Description
portalName
YES
Upload link name
description
NO
Upload link description
emailSubject
YES
Email subject of the receiver
emailBody
YES
Email body of the receiver
isNeverExpired
YES
true – upload link will not expire, false – upload link will expire
displayExpireDate
NO
If isNeverExpired == false, date value must be added here
If isNeverExpired == true, no need to set a date value here
recipients
YES
Recipient details

firstName

YES
First Name of recipient

lastName

YES
Last Name of recipient

email

YES
Email address of recipient

Below are two sample requests:

{"portalName":"CantoTest","description":"CantoTest","emailSubject":"Canto Test sent you a request to upload content","emailBody":"To upload files, please click on the button below or copy the URL to a browser:","editable":false,"isNeverExpired":true,"recipients":[{"firstName":"CantoTest","lastName":"CantoTest","email":"CantoTest@objectivasoftware.com" }]}

{"portalName":"CantoTest","description":"CantoTest","emailSubject":"Canto Test sent you a request to upload content","emailBody":"To upload files, please click on the button below or copy the URL to a browser:","editable":false,"isNeverExpired":false, "displayExpireDate":"2019-02-20","recipients":[{"firstName":"CantoTest","lastName":"CantoTest","email":"CantoTest@objectivasoftware.com" }]}

Response
Description
Success
Upload Link Id
Failure
N/A

If other exception occurs, Canto will return a 500 http status code.

Add Keywords

This supports adding a keyword.

POST https://{Canto domain url}/api /v1 /keyword
Parameter
Required
Description
name
YES
Name of keyword
description
YES
Description of keyword

Below is a sample request:

{name: "Canto", description: "Canto Test"}

Response
Description
Success
success
Failure
N/A

If other exception occurs, Canto will return a 500 http status code.