When a user interacts with a content extension, Canva sends a POST
request to the following endpoint:
<base_url>/content/resources/find
Specifically, Canva sends this request when a user:
Opens an extension.
Opens a container.
Paginates through resources.
Searches for content.
The purpose of this request is to retrieve content that Canva can display in the side panel of the editor, such as images, embeds, or containers.
The type
property in the request body determines the type of resources the extension must provide in the response. For example, when value of the type
property is "IMAGE"
, the endpoint must respond with image resources.
Extensions must respond to this request within 8 seconds.
When sending this request, Canva replaces <base_url>
with the extension's Base URL. You can configure the Base URL via the Developer Portal.
To configure the type of resources that Canva expects the extension to provide, change the extension's Content type via the Developer Portal.
POST <base_url>/content/resources/find
Property | Type | Required | Description |
| string | Yes | A comma-separated list of request signatures. |
| string | Yes | The UNIX timestamp (in seconds) of when Canva sent the request. |
Property | Type | Required | Description |
| string | Yes | The ID of the user. |
| string | Yes | The ID of the user's team. |
| string | Yes | The type of extension that sent the request. |
| number | Yes | The maximum number of resources to provide in a response. |
| string | Yes | The user’s locale as an IETF BCP 47 language tag. |
| string | Yes | The type of resources the extension must provide in the response. Enum: |
| string | No | A token for paginating resources. |
| string | No | The ID of the selected container. |
| string | No | A user-provided search query. |
{"limit": 100,"user": "<user>","brand": "<brand>","label": "<label>","locale": "<locale>","type": "<type>"}
The response an extension must provide when the value of the type
property in the request body is "CONTAINER"
.
Property | Type | Required | Description |
|
| Yes | The type of response. |
| Array<Container> | Yes | The containers to render in the side panel. |
| string | No | A token for paginating resources. |
{"resources": [],"type": "SUCCESS"}
The response an extension must provide when the value of the type
property in the request body is "EMBED"
.
Property | Type | Required | Description |
|
| Yes | The type of response. |
| Array<Embed> | Yes | The embeds to render in the side panel. |
| string | No | A token for paginating resources. |
{"resources": [],"type": "SUCCESS"}
The response an extension must provide when the value of the type
property in the request body is "IMAGE"
.
Property | Type | Required | Description |
|
| Yes | The type of response. |
| Array<Image> | Yes | The images to render in the side panel. |
| string | No | A token for paginating resources. |
{"resources": [],"type": "SUCCESS"}
The response an extension provides when it can't provide the requested resources.
Property | Type | Required | Description |
|
| Yes | The type of response. |
| string | Yes | An error code that describes what went wrong. Enum: |
{"type": "ERROR","errorCode": "<error_code>"}
An extension must verify the request signature and timestamp of all incoming requests. When an extension can't verify either of these values, it must reject the request with a 401
status code.
Represents a container (folder) that Canva renders in the side panel. When a user selects a container, Canva sends a request for resources that belong to the container.
Property | Type | Required | Description |
| ​Thumbnail​ | No | A thumbnail for the container. |
| string | Yes | A unique ID for the container. |
| string | Yes | A human readable name for the container. |
|
| Yes | The type of resource. |
{"id": "<id>","name": "<name>","type": "CONTAINER"}
Represents embeddable media that Canva renders in the side panel, such as a YouTube video or Instagram photo. When a user selects an embed, Canva adds it to their design.
{"id": "<id>","name": "<name>","type": "EMBED","url": "<url>"}
Represents an image file that Canva renders in the side panel, such as a PNG or SVG. When a user selects an image, Canva uploads the image to the user's account and adds it to their design.
Property | Type | Required | Description |
| string | No | The MIME type of the image. If you omit the |
| string | Yes | A unique ID for the image. This ID should always refer to the same image file. |
| string | Yes | A human readable name for the image. |
|
| Yes | The type of resource. |
| string | Yes | The URL of the full-resolution image. The MIME type of the image must match the type specified in the |
| ​Thumbnail​ | Yes | A thumbnail for the image. This thumbnail must have the same aspect ratio as the full-resolution image. |
{"id": "<id>","name": "<name>","type": "IMAGE","url": "<url>"}
A thumbnail image. If you don't provide the dimensions of a thumbnail, Canva sends a HEAD
request to the URL to request its dimensions. This adds a perceptible delay to thumbnail load times and may result in CORS issues. As such, we recommend always providing the dimensions.
Property | Type | Required | Description |
| string | Yes | The URL of the thumbnail. |
| number | No | The height of the thumbnail (in pixels). If you provide a height, you must provide a width. |
| number | No | The width of the thumbnail (in pixels). If you provide a width, you must provide a height. |
{"url": "<url>"}