Authentication Process

Methods


Canto API (canto.com) Version 1.23

Updated: 2019-10-18


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

Rate limit: 1000 times/minute

 

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

Rate limit: 1000 times/minute

 

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

 

 

 

Get content details

Rate limit: 500 times/minute

 

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

Rate limit: 1000 times/minute

 

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

Rate limit: 200 times/minute

 

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

Rate limit: 300 times/minute

 

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.

 

“created” means the created time.

 

“time” means the last modified time.

 

 

“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

Rate limit: 300 times/minute

 

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.

 

“created” means the created time.

 

“time” means the last modified time.

 

“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

Rate limit: 200 times/minute

 

List content of a 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

Rate limit: 1000 times/minute

 

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.

Please note: This setting is valid for 5 hours. You will need to retrive settings again after 5 hours to continue use.

Upload file

Rate limit: 1000 times/minute

 

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

Rate limit: 500 times/minute

 

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:

 

n   Initial

File uploads to AWS.

n   Queue

Waiting in queue to process.

n   Processing

Step by step processing.

n   Done

Successfully done. You can find it in your Canto library.

n   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

Rate limit: 500 times/minute

 

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

Rate limit: 500 times/minute

 

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

Rate limit: 500 times/minute

 

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

Rate limit: 500 times/minute

 

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

Rate limit: 500 times/minute

 

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

Rate limit: 500 times/minute

 

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

Rate limit: 200 times/minute

 

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

Rate limit: 200 times/minute

 

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)

createdTime

 

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

Rate limit: 200 times/minute

 

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& searchInField = filename& 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

Rate limit: 500 times/minute

 

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

Rate limit: 200 times/minute

 

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

Rate limit: 500 times/minute

 

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

Rate limit: 500 times/minute

 

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

Rate limit: 500 times/minute

 

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

Rate limit: 200 times/minute

 

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

Rate limit: 200 times/minute

 

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 a 500 http status code.

Create Upload Links

Rate limit: 500 times/minute

 

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@canto.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@canto.com" }]}

 

 

 

 

Response

Description

Success

Upload Link Id

Failure

N/A

 

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

 

Add Keywords

Rate limit: 500 times/minute

 

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.

 

 

Get specified content Usage History report

Rate limit: 500 times/minute

 

Get a specified content’s Usage history report. The detail seen on the asset content detail page.

GET https://{Canto domain prefix}/usagehistory/{scheme}/{id}

Parameter

Required

Description

scheme (provided in url path)

YES

Image, Video, Audio, Document, Presentation, or Other.

Case sensitive.

 

id(provided in url path)

YES

Content id

sortDirection

NO

“ascending” or “descending”. The default is descending

limit

NO

The maximum number of items to be returned. Default is 100.

marker

NO

This API returns results page by page. This value is from the API call response, indicates to get the next page.

 

Below is a sample url:

https://yourdomain.canto.com/api/v1/usagehistory/{scheme}/{id}?limit=4&sortDirection=ascending&marker=MjAxODA3MjUwOTIwMjc0OTE

 

Response

Description

Success

Http status code 200 and json returned as below:

 

{

       "limit": 100,

       "results": [

              {

                     "user": "jim cai newnew",

                     "actionName": "Previewed File",

                     "email": "jcai@canto.com",

                     "actionTime": "20181203023538150"

              },           

              {

                     "user": "jim cai newnew",

                     "actionName": "Downloaded Image",

                     "email": "jcai@canto.com",

                     "actionTime": "20180914010453282"

              },           

              {

                     "user": "jim cai newnew",

                     "actionName": "Shared to Slack",

                     "email": "jcai@canto.com",

                     "actionTime": "20180913193104916"

              },

              {

                     "user": "jim cai newnew",

                     "actionName": "Shared to Facebook",

                     "email": "jcai@canto.com",

                     "actionTime": "20180913193034869"

              },           

              {

                     "user": "jim cai newnew",

                     "actionName": "Uploaded Image",

                     "email": "jcai@canto.com",

                     "actionTime": "20180725021237425"

              }

       ],

       "sortDirection": "descending",

       "sortBy": "time",

       "nextMarker":"MjAxODA3MjUwOTIwMjc0OTE"

}

 

If you specified a limit parameter, and if there are more results than the number specified, then a nextMarker value will be included in the response json.

You can set this “nextMarker” value into the call to obtain the next page.

Failure

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

 

 

 

Get specified content Share Activity report

Rate limit: 500 times/minute

 

Get a specified content’s Share Activity report. The detail seen on the asset content detail page.

GET https://{Canto domain prefix}/shareactivity/{scheme}/{id}

Parameter

Required

Description

scheme (provided in url path)

YES

Image, Video, Audio, Document, Presentation, or Other.

Case sensitive.

 

id(provided in url path)

YES

Content id

sortDirection

NO

“ascending” or “descending”. The default is descending

limit

NO

The maximum number of items to be returned. Default is 100.

marker

NO

This API returns results page by page. This value is from the API call response, indicates to get the next page.

 

Below is a sample url:

https://yourdomain.canto.com/api/v1/shareactivity/{scheme}/{id}?limit=4&sortDirection=ascending&marker=MjAxODA3MjUwOTIwMjc0OTE

 

Response

Description

Success

Http status code 200 and json returned as below:

 

{

       "limit": 100,

       "results": [

              {

                     "user": "jim cai newnew",

                     "actionName": "Shared to Slack",

                     "email": "jcai@canto.com",

                     "actionTime": "20180913193104916"

              },

              {

                     "user": "jim cai newnew",

                     "actionName": "Shared to Facebook",

                     "email": "jcai@canto.com",

                     "actionTime": "20180913193034869"

              }

             

       ],

       "sortDirection": "descending",

       "sortBy": "time",

       "nextMarker":"MjAxODA3MjUwOTIwMjc0OTE"

}

 

If you specified a limit parameter, and if there are more results than the number specified, then a nextMarker value will be included in the response json.

You can set this “nextMarker” value into the call to obtain the next page.

Failure

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

 

 

Get specified content Download Activity report

Rate limit: 500 times/minute

 

Get a specified content’s Download Activity report. The detail seen on the asset content detail page.

GET https://{Canto domain prefix}/downloadactivity/{scheme}/{id}

Parameter

Required

Description

scheme (provided in url path)

YES

Image, Video, Audio, Document, Presentation, or Other.

Case sensitive.

 

id(provided in url path)

YES

Content id

sortDirection

NO

“ascending” or “descending”. The default is descending

limit

NO

The maximum number of items to be returned. Default is 100.

marker

NO

This API returns results page by page. This value is from the API call response, indicates to get the next page.

 

Below is a sample url:

https://yourdomain.canto.com/api/v1/downloadactivity/{scheme}/{id}?limit=4&sortDirection=ascending&marker=MjAxODA3MjUwOTIwMjc0OTE

 

Response

Description

Success

Http status code 200 and json returned as below:

 

{

       "limit": 100,

       "results": [

              {

                     "user": "jim cai newnew",

                     "actionName": "Downloaded Image",

                     "email": "jcai@canto.com",

                     "actionTime": "20180913193104916"

              }

             

       ],

       "sortDirection": "descending",

       "sortBy": "time",

       "nextMarker":"MjAxODA3MjUwOTIwMjc0OTE"

}

 

If you specified a limit parameter, and if there are more results than the number specified, then a nextMarker value will be included in the response json.

You can set this “nextMarker” value into the call to obtain the next page.

Failure

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

 

 

 

Get specified content View Activity report

Rate limit: 500 times/minute

 

Get a specified content’s View Activity report, just like you see that in Canto site content detail page.

GET https://{Canto domain prefix}/viewactivity/{scheme}/{id}

Parameter

Required

Description

scheme (provided in url path)

YES

Image, Video, Audio, Document, Presentation, or Other.

Case sensitive.

 

id(provided in url path)

YES

Content id

sortDirection

NO

“ascending” or “descending”. The default is descending

limit

NO

The maximum number of items to be returned. Default is 100.

marker

NO

This API returns results page by page. This value is from the API call response, indicates to get the next page.

 

Below is a sample url:

https://yourdomain.canto.com/api/v1/viewactivity/{scheme}/{id}?limit=4&sortDirection=ascending&marker=MjAxODA3MjUwOTIwMjc0OTE

 

Response

Description

Success

Http status code 200 and a json returned as below:

 

{

       "limit": 100,

       "results": [

              {

                     "user": "jim cai newnew",

                     "actionName": "Previewed File",

                     "email": "jcai@canto.com",

                     "actionTime": "20180913193104916"

              }

             

       ],

       "sortDirection": "descending",

       "sortBy": "time",

       "nextMarker":"MjAxODA3MjUwOTIwMjc0OTE"

}

 

If you specified a limit parameter, and if there are more results than the number specified, then a nextMarker value will be included in the response json.

You can set this “nextMarker” value into the call to obtain the next page.

Failure

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

 

 

 

 

 

Get custom field list

Rate limit: 500 times/minute

 

Get custom field list (including type and values if any).

GET https://{Canto domain prefix}/tenant/download/presets

Parameter

Required

Description

N/A

 

 

 

Below is a sample url:

https://yourdomain.canto.com/api/v1/custom/field

 

 

Response

Description

Success

Http status code 200 and a list returned as below:

 

[

    {

        "name":"Number",

        "type":"NUMBER"

},

    {

        "name":"Text",

        "type":"TEXT"

},

    {

        "name":"Date",

        "type":"DATE"

    },

    {

        "name":"SingleChoice",

        "type":"SINGLECHOICE",

        "values":[

            "A",

            "B"

        ]

    },

    {

        "name":"MultChoice",

        "type":"MULTICHOICE",

        "values":[

            "A",

            "B",

            "C"

        ]

    },

    {

        "name":"Url",

        "type":"URL"

    },

    {

        "name":"Label",

        "type":"LABEL"

},

    {

        "name":"Rating",

        "type":"RATING"

    }   

]

 "name" is a unique custom field name.

 "type" : NUMBER, TEXT, DATE, SINGLECHOICE, MULTICHOICE, URL, LABEL, RATING.

 "values" the select options for SINGLECHOICE and MULTICHOICE.

 

 

Failure

N/A

 

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

 

Add new user

Rate limit: 500 times/minute

 

Admin adds a new user

POST https://{Canto domain prefix}/user

Parameter

Required

Description

N/A

 

 

 

Below is a sample url and request body:

 

https://yourdomain.canto.com/api/v1/user

 

{"userId": "user@canto.com", “firstName": "Jim", "lastName": "Cai", "roles": ["consumer"], "allowAccessMainTenant": true}

 

Note: The role options: admin, contributor or consumer.   

 

Response

Description

Success

Http status code 200

 

Failure

 

 

If the token is not Admin, Canto will return HTTP 403.

 

If there are no seats left, Canto will return HTTP 500 and the response below,

 

{"code":3203,"message":"It looks like you are trying to add another user but the total number of purchased Consumer seats is {num}. Send us an email at hello@canto.com to purchase additional seats."}

Or

{“code”: 3201,”message”:”It looks like you are trying to add another user but the total number of purchased Admin and Contributor seats is {num}. Send us an email at hello@canto.com to purchase additional seats.”}

 

 

If the email already exists, Canto will return HTTP 500 and the response below,

   {  "code":2152,

      "message":"The user ID already exists."

   }

 

Delete a user

Rate limit: 500 times/minute

 

Admin deletes an existing user

DELETE https://{Canto domain prefix}/user/{user_id}

Parameter

Required

Description

N/A

 

 

 

Below is a sample url

 

https://yourdomain.canto.com/api/v1/user/user@canto.com

 

Response

Description

Success

Http status code 200

 

Failure

If the token user is not Admin, Canto will return HTTP 403.

 

If the token user deletes oneself, Canto will return HTTP 400.

 

 

 

Get user list

Rate limit: 500 times/minute

 

Obtain a list of users within your Canto account with pagination

 

GET https://{Canto domain prefix}/users

Parameter

Required

Description

role

No

1- Admin

2- Contributor

3- Consumer

4- Admin and Contributor

5- Contributor and Consumer

Default to 0 (all roles)

name

No

Find the users name starting with given value. Name means first name, last name or email.

include-group

No

true means the result should include user’s groups.  Default is set to false.

include-portal

No

true means the result should include user’s granted portal/workspace/style guide info. Default is set to false.

page-size

No

Specifies the number of results returned (default is 100)

page

No

Specifies current page number (default is 1)

 

Below are some sample calls:

List all users,

https://yourdomain.canto.com/api/v1/users

 

List all Consumers with assigned group and portal info

https://yourdomain.canto.com/api/v1/users?role=3&include-group=true&include-portal=true

 

Find the user name starting with ‘Tom’

https://yourdomain.canto.com/api/v1/users?name=Tom

 

 

Response

Description

Success

Http status code 200, and a list returned as below,

/api/v1/users?include-group=true&include-portal=true

 

{

                "data": [

                                {

                                                "role": "Admin",

                                                "userId": "bradqiu@canto.com",

                                                "firstName": "Brad",

                                                "lastName": "Q",

                                                "email": "bradqiu@canto.com",

                                                "allowAccessMainLibrary": true

                                },

                                {

                                                "role": "Admin",

                                                "userId": "glin@canto.com",

                                                "firstName": "Gerard",

                                                "lastName": "Lin",

                                                "email": "glin@canto.com",

                                                "allowAccessMainLibrary": true

                                },

                                {

                                                "groups": [

                                                                "Reviewer"

                                                ],

                                                "role": "Contributor",

                                                "userId": "jchai@canto.com",

                                                "grantedPortals": [

                                                                "PortalSample"

                                                ],

                                                "grantedStyleGuides": [

                                                                "GreatOutdoorsGo"

                                                ],

                                                "firstName": "Jeff",

                                                "lastName": "Chai",

                                                "email": "jchai@canto.com",

                                                "allowAccessMainLibrary": false

                                }

                ],

                "currentPage": 1,

                "pageSize": 100,

                "totalCount": 3

}

Failure

If the token user is invalid, Canto will return HTTP 403.

 

Obtain asset preview Cloudfront URL

Rate limit: 1000 times/minute

 

In a situation where the embedded browser does not support redirect URLs, this call can be used to obtain the Cloudfront URL directly.

GET https://{Canto domain prefix}/api_binary/v1/{scheme}/{content id}/previewURI

Parameter

Required

Description

Scheme (provided in url path)

YES

Image, video, audio, document, presentation, other.

Case sensitive

Content Id (provided in url path)

YES

Id of the content

Dimension

No

Indicate the dimension

 

Below is a sample url

 

https://yourdomain.canto.com/api_binary /v1/image/hqiduuc6l96fldlgqh49eb032e/previewURI

https://yourdomain.canto.com/api_binary /v1/image/hqiduuc6l96fldlgqh49eb032e/previewURI/500

https://yourdomain.canto.com/api_binary /v1/image/hqiduuc6l96fldlgqh49eb032e/previewURI/800

 

Response

Description

Success

Http status code 200 and Cloudfront url returned as shown below:

 

https://d15cl5q7pq68a5.cloudfront.net/90dfc36a-4eeb-4e90-8b16-b64f72cd6a7c/8ea4df7986aa4cfab6b0d448972c034e.240.jpg?response-content-disposition=inline%3B%20filename%2A%3DUTF-8%27%271544856627000.jpg&response-content-type=image%2Fjpeg&Expires=1560311429&Signature=SlHxYFn34iKG6~10Yl-MarJ2ED8ES9XzgYgHEeceI07~FBUMCMp8xIdHXD~4hYdHoaYoczJ42VHF0bCxFeduwYfV-2xQ6U8Yii0EeyjXazURyYHoT8BbpR1XqKjAaiC9Er2FTaD5lT5QLrxIKzvND69b6rvULECnRLjffB55heWcYRCwJLc5~NByhhLqKMWC8X5jnHzu4Hhf8I7Q7TUgtkg9SvZKxM~3FdCP8IF4QxGWE1g6f6TSMBRqijR6TT2V6fEDmMC6fJqGr4iDB2X-K8t2aY-L5-JJuH5mFmdglzS~A7FociWFw0jwI20KRJCtTjxPwqhMBiaoVZxRjavUTA__&Key-Pair-Id=APKAJYAUIW7DJ6V23KKQ

 

Failure

Http status code 404 for arbitrary content id.

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

 

Obtain asset download Cloudfront URL

Rate limit: 1000 times/minute

 

In some case, like some embedded browser which is not support redirect url, developer cannot download picture by redirect behavior, he want obtain a cloudfront url.

GET https://{Canto domain prefix}/api_binary/v1/{scheme}/{content id}/directuri

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_binary /v1/image/hqiduuc6l96fldlgqh49eb032e/directuri

 

Response

Description

Success

Http status code 200 and cloudfront url returned as below:

 

https://d15cl5q7pq68a5.cloudfront.net/90dfc36a-4eeb-4e90-8b16-b64f72cd6a7c/8ea4df7986aa4cfab6b0d448972c034e.keywords_tags.0d35d32b16db304ffd6d84a080c85d99?response-content-disposition=attachment%3B%20filename%2A%3DUTF-8%27%27C02-19-0688.jpg&Expires=1560398415&Signature=LUkMcdJqtPH~EbFWFTWgCkYtJjD-F~qbc2TJY2vzK6d~2uKkQQLL7r6~a463~zxgfZH5~Qgxzhmm06a3vk~ar0NMtw1MUJmaHatSRQlA5fVSQja2HBnDK-bZoypkdw5eM3dNJYZix0wydXKd6LEOSi5Fe3qu-ICCMo7T2XEBZtM60fJkP80yumUnZmVJDnoyp0w4KfMjbEb4BqZ5D8frfbrPiYDOwyHmvGnnycPh4U3sPdrdSBP9-~paeJ6P26-pkJxk4Hgn7SglUVyyrmiRefKYFApXKAbCNRT6b2fIKkhSR960coE86VglEluLgMDj~IhgdVcczbsbtjEV1jY6dw__&Key-Pair-Id=APKAJYAUIW7DJ6V23KKQ

Failure

Http status code 404 for arbitrary content id.

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

 

 

 

Batch load Cloudfront URLs

POST https://{Canto domain prefix}/api_binary/v1/batch/directuri

Parameter

Required

Description

A JSON array, contain below elements:

 

The POST body format is: contentType: "application/json; charset=utf-8"

scheme

YES

One of the image, video, audio, document, presentation, other.

Case sensitive

id

YES

Id of the content

 

Below is a sample parameter, it is JSON array format:

[

{"id": "hqiduuc6l96fldlgqh49eb032e", "scheme": "image"},

{"id": "mpi1022fo17ed4hu3jgad1h35i", "scheme": "image"}

]

 

Response

Description

Success

Http status code 200, and JSON array returned as below:

 

[

       {

              "preview": "https://jimcai.flightbycanto.com/api_binary/v1/image/hqiduuc6l96fldlgqh49eb032e/preview",

              "scheme": "image",

              "displayName": "C02-19-0688.jpg",

              "id": "hqiduuc6l96fldlgqh49eb032e",

              "directUri": "https://d15cl5q7pq68a5.cloudfront.net/90dfc36a-4eeb-4e90-8b16-b64f72cd6a7c/8ea4df7986aa4cfab6b0d448972c034e.keywords_tags.0d35d32b16db304ffd6d84a080c85d99?response-content-disposition=attachment%3B%20filename%2A%3DUTF-8%27%27C02-19-0688.jpg&Expires=1546049758&Signature=FiKlxEoPSIRt10AWm0fv9-hy2aMJ3CRQ-2QCcI3MSz2oPJHtMPbUFhDo-J-wEkJXqZ2o~KROKcC6s-9df24DCw1j8VfL2fSw64sXxsgQRzXscfSOokMkSjfmm5xVCaVvQhTtGCw5HWUTNJYDLDmFK4SW9k9gPvHbc8ckxyEdpfOBfR55KarGqjnzRbp5e3HHCUFm1IK9ETxWmfj5K1b8ttDoKpQmfZHq4ywgtQdYvX7e81ERB-RoydraD4p2tf76ZNtgF-LkuV5aL7ARWlKHyj6c7m7cexm~T~Wgylj63owhmzlNX~MZht6muKfv-M15HMw-i64JxKvOZubl0Khmug__&Key-Pair-Id=APKAJYAUIW7DJ6V23KKQ"

       },

       {

              "preview": "https://jimcai.flightbycanto.com/api_binary/v1/image/mpi1022fo17ed4hu3jgad1h35i/preview",

              "scheme": "image",

              "displayName": "._canto-logoMark-orange-512.jpg",

              "id": "mpi1022fo17ed4hu3jgad1h35i",

              "directUri": "https://d15cl5q7pq68a5.cloudfront.net/90dfc36a-4eeb-4e90-8b16-b64f72cd6a7c/b66410084fc04ee6923e1ce0a68623b2.keywords_tags.26adbd8ae6c27216a79859240f014a31?response-content-disposition=attachment%3B%20filename%2A%3DUTF-8%27%27._canto-logoMark-orange-512.jpg&Expires=1546049765&Signature=KnrVZxclJi~0jlsDyrf4i-OeimmtQwSn5dzLVRrD8CHPhlCMQue8gvjvboddKCxz4LSyqUaObHWycVJ9acW4JQSW8CN0SDYe~yoOtOPJM0U-AIUxkxkVDRxGuWnSDy~7brITRFGHlQ7F-pVBfPlaHoOTmkkT905qNxkR9oueM-6UMhCR~U5loeQwyGi5qxyC5l9Djq1B-RRvf00ByBkhhrNvobaPaXHYnrBxAkbizJdPG~bGN13y3HiSnXiki1-bda-HtukoDofJ1NIdbnvS~G5e2PlR8wLzMLmvQq~dH4LIdhcgB4qUJlFwgB9LoAq8sjlPHYk7juKHa~fbrWheew__&Key-Pair-Id=APKAJYAUIW7DJ6V23KKQ"

       }      

]

 

Failure

Http status code !=200

 

 

 

 

 

Rename content

Rate limit: 500 times/minute

 

PUT https://{Canto domain prefix}/{scheme}/{content id}/rename

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

name

YES

Content name.

The max length is 200. Avoid using \ / : * ? \" < > or | in name.

 

Below is a sample of request parameter:

{name: "Canto.jpg"}

 

Response

Description

Success

Http status code 200 with nothing returned.

 

Get same successfully response for the name already updated.

Failure

Http status code 404 for arbitrary content id.

Http status code 400 for arbitrary name.

 

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

 

Create a custom field

Rate limit: 500 times/minute

 

POST https://{Canto domain prefix}/custom/field

Parameter

Required

Description

name

YES

Unique value. The max length is 80.

description

YES

The max length is 800.

type

YES

Types include: NUMBER, TEXT, DATE, SINGLECHOICE, MULTICHOICE, URL, LABEL, RATING.

values

No

Options for SINGLECHOICE and MULTICHOICE type fields.

 

Below is a sample request parameter:

{name:"test",description:"test",type:"SINGLECHOICE",values:["A","B","C"]}

 

Response

Description

Success

Http status code 200 with nothing returned.

Failure

Http status code 400 for duplicate custom field name.

 

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

 

Update a custom field

Rate limit: 500 times/minute

 

PUT https://{Canto domain prefix}/custom/field

Parameter

Required

Description

id

YES

Custom field id.

name

YES

Unique value. The max length is 80.

description

YES

The max length is 800.

values

No

Options for SINGLECHOICE and MULTICHOICE type fields.

 

Below is a sample of request parameter:

{id:" meta_choice_0",name:"test1",description:"test1",values:["A1","B1","C1"]}

 

Response

Description

Success

Http status code 200 with nothing returned.

Failure

Http status code 400 for duplicate custom field name.

 

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

 

Delete a custom field

Rate limit: 500 times/minute

 

DELETE https://{Canto domain prefix}/custom/field/{id}

Parameter

Required

Description

id (provided in url path)

YES

Custom field id.

 

Response

Description

Success

Http status code 200 with nothing returned.

Failure

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

 

 

Search under a folder

Rate limit: 500 times/minute

 

List everything under a specified folder, page by page. This will return all matched sub-folder/album and all its contents.

GET https://{Canto domain prefix}/folder/{folder id}

Parameter

Required

Description

Folder id (provided in url path)

YES

Id of folder to search.

sortBy

NO

Options: name, time, scheme, owner, size. Default 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.

All other parameters

NO

All other parameters are usable from #19 Filter section. Ex. scheme, tags, keywords, lastModified, .etc.

 

 

 

 

Below is a sample url:

https://yourdomain.canto.com/api/v1/folder/{folder id}?sortBy=name&sortDirection=ascending&limit=2&start=10&scheme=image&lastModified=1571109473..1571368673

 

Response

Description

Success

Http status code 200 and all sub-folders, albums and all contents.

The returned JSON the same format as #18 Global search.

 

Failure

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

 

 

 

 

 

 

 

 

 

 

 

 

 


API Change Log

V1.19

7/30/2019

Addition of file rename

V1.20

8/12/2019

Create/update/delete custom fields

V1.21

8/21/2019

For #9, the ‘Get upload setting’ call, settings are valid for 5 hours

V1.22

8/27/2019

For #38, Obtain asset preview Cloudfront URL, dimension parameter added.

V1.23

10/18/2019

For #19, 3 new filtering parameters added.

Added #44, Search within a folder