API requests and responses

API requests (submitted to an API endpoint) tell the endpoint to do something. Once the request is processed, the API endpoint sends a response.

To make API requests, you must know the HTTP method, URL path, and parameters for the endpoint that you want to use.

Hence, an API request consists of the combination of the following:

HTTP method + URL path of the endpoint + request parameters

An HTTP method is the operation that you want the endpoint to execute. REST HTTP methods⁠(opens in a new tab or window) can be:

• POST (create)
• GET (read)
• PUT (update/replace)
• PATCH (update/modify)
• DELETE (delete).

The URL path is the HTTP URL where the endpoint can be accessed.

Use the --request flag followed by the HTTP method and the URL path.

For example, the HTTP method for generating an access token is POST and the URL path for the endpoint is https://api.canva.com/rest/v1/oauth/token. The curl request for generating an access token looks like the following:

curl --request POST 'https://api.canva.com/rest/v1/oauth/token'

Request parameters are the options that you can pass to the endpoints to influence the response. Parameters help single out the data that you want to receive from the endpoint. Most requests need you to pass parameters and their values.

Parameters can be of the following types:

• required (the request cannot go through without the parameter)
• optional (the parameter value is supplemented with the default value)

We use the following parameters in Canva Connect API:

Path parameters are a part of the endpoint itself. They are usually formatted with curly braces and are not optional.

For example, the path parameter for getting folder information from the folder endpoint is {folderID}.

The curl request is:

curl --request GET 'https://api.canva.com/rest/v1/folders/{folderId}' \
--header 'Authorization: Bearer {token}'

Query parameters are included in the query string of the endpoint. A query string starts with ? and lists parameters one after another separated by &.

For example, the required query parameters for the /authorize endpoint are code_challenge, code_challenge_method, etc. Hence, the URL path becomes:

https://www.canva.com/api/oauth/authorize?code_challenge=<code challenge string>&code_challenge_method=s256...

Header parameters are included in the HTTP request headers. They carry information such as the authorization, connection type, proxies, and content type of the request.

When using curl, use the --header flag followed by the header in key:value format.

For example, the header parameter for the /token endpoint is Content-Type with the value application/x-www-form-urlencoded.

The curl request becomes:

curl --request POST 'https://api.canva.com/rest/v1/oauth/token' \
--header 'Content-Type:application/x-www-form-urlencoded'

Body parameters are included in the request body, and are used to send data to the API endpoints. These parameters are usually sent as JSON objects in POST, PUT, or PATCH requests.

When using curl, use the --data-<type> flag followed by the parameter in the parameter=value format.

For example, the body parameters for the /token endpoint are grant_type, code_verifier, code, etc.

The curl request becomes:

curl --request POST 'https://api.canva.com/rest/v1/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code_verifier=<code verifier>' \
...

API responses indicate whether an API request was successful. A response consists of an HTTP response status code and a response body that includes either a successful response or an error response.

As a result, an API response consists of the combination of the following:

HTTP response status code + response body (success response or error response)

HTTP response status codes⁠(opens in a new tab or window) indicate whether your request was successful. They include the following types:

Many requests return a response body in JSON format. The responses can include the following types:

If your API request has completed successfully, you'll receive a success response that includes the required parameters, usually in JSON format.

For example, the success response for the /token endpoint is:

{
  "access_token": "...",
  "token_type": "bearer",
  "expires_in": "...",
  "scope": "...",
  "refresh_token": "..."
}

If your API request doesn't complete successfully, you'll get an error response that consists of the following:

• Error HTTP status code
• Error code (usually includes different information to the status code)
• Error message

For example, an error response can look like this:

HTTP 404

{
  "code": "design_not_found",
  "message": "Design with id 'ABCD' not found"
}

Some Connect APIs are asynchronous. This means that the endpoint doesn't return the response immediately. Instead, it creates a job to process the request and returns a job ID that you can use to check the status of the job.

Asynchronous job APIs are usually those that might require additional server-side processing to complete, such as the design import and autofill APIs.

The typical flow for using an asynchronous job API is as follows:

1. Submit a request to the 'Create [API name] job' API.

2. If the request was valid, the API returns a response that includes a job with an id, and a status of in_progress.

   For example:

   {
     "job": {
       "id": "450a76e7-f96f-43ae-9c37-0e1ce492ac72",
       "status": "in_progress"
     }
   }

   JSON

   Copy

3. Use the job ID to poll the 'Get [API name] job' API until the job status changes from in_progress to either success or failed. For more information on polling, see Job polling strategies.

   For successful jobs, the response also includes the result of the job. For example:

   {
     "job": {
       "id": "450a76e7-f96f-43ae-9c37-0e1ce492ac72",
       "status": "success",
       ...
     }
   }

   JSON

   Copy

4. Use the result of the finished job to do the next steps in your integration. For example, if you used the design import API, you can use the returned design ID to show the design thumbnail in your integration.

You should poll a 'Get [API name] job' API at an interval that's short enough to provide a good user experience, but not too short to hit rate limits for the particular API.

We recommend that you use an exponential backoff⁠(opens in a new tab or window) strategy to poll the job status. This means that you should start with a short poll interval, then exponentially increase the time between each poll, up to a maximum interval. For an example implementation, see the Canva Connect API Starter Kit⁠(opens in a new tab or window).