Canto API

The Canto API allows you to connect to your Canto Account via RESTful Web Service. You have the possibility to access, create and modify the content of your Canto Account. # 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 {{SITE_BASEURL}} where your domain is the domain name (Canto account name) you currently use. ## API Compatibilty Future API versions may add new endpoints or parameters. In order to keep older versions 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: `yyyyMMddHHmmssSSS` **Example:** `20150415063836418` 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). _Example:_ To retrieve the current user info, you should retrieve it as the following ``` curl -v -H 'Authorization: Bearer ' -H 'User-Agent: App Canto Publishing ' “{{SITE_BASEURL}}/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 | Parameters are invalid | | 401 | Access Token is invalid or missing | | 403 | Access Token represent account has no permission to process the request | | 404 | Results (or page) not found. (will also return this in case of arbitrary content/album/folder ID) | | 429 | Rate limit exceeded | | 500 | Unexpected Error | | 503 | Server unaccessible | ## General Properties The following properties are used in Canto: | Property name | Description | | --- | --- | | 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: 1. Always return the complete set. 2. 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. **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” ## API Rate Limit Rate limits are how many API calls you can make in a given time frame. If your call exceeds the pre-defined rate limit, you will run into a “429” http error-code. After which, you will need to wait until you can make another API call. ### Rate Limit Level #### Customer Rate Level | Level | Description | | --- | --- | | level 1 | 1000 times per minute | | level 2 | 500 times per minute | | level 3 | 300 times per minute | | level 4 | 200 times per minute | | level 5 | 50 times per minute | #### Trial User Rate Level | Level | Description | | --- | --- | | level 1 | 500 times per minute | | level 2 | 300 times per minute | | level 3 | 200 times per minute | | level 4 | 100 times per minute | | level 5 | 50 times per minute | ### API Call Rate Limits Based on Rate Limit Levels | Level | Description | | --- | --- | For example, with “#44 Search under a folder” the rate limit is level 4, meaning that the API call will limit to 200 times per minute. If you exceed 200 times, you will receive a 429 error code.