Embed only

Import rich media into Canva with a content extension.

A content extension can support one of two types of content:

When a content extension supports embeds, it can provide users with embeddable media, such as YouTube videos, Instagram photos, and animated GIFs. This media appears in the side panel and can be dragged into the user's design.

How embeds work

Behind the scenes, Canva uses Iframely to embed media in designs. This means any URL supported by Iframely can be embedded via a content extension.

To check if a URL is supported by Iframely, refer to URLs supported by Iframely.

Enabling embeds

For a content extension to support embeds, it must be configured via the Developer Portal.

To enable support for embeds:

  1. Navigate to an app via the Developer Portal.

  2. From the Extensions page, expand the Content panel.

  3. From the Content type dropdown, select Embed only.

A content extension can't support embeds and images. It can only support one or the other.

What embeds can't do

When working with embeds, there are some limitations:

  • The media is embedded via an iframe. This means the user can only manipulate the size and position of the media. They cannot apply effects to it.

  • Canva only stores a reference to the media. If the original media becomes unavailable, an error will be displayed in place of the media.

  • If a user downloads their design, the media won't be interactive or animated.

  • Unlike images, embeds can't be organized into containers.

Receiving embed requests

When a content extension supports embeds, Canva will retrieve the embeddable media by sending a POST request to the following URL:

<base_url>/content/resources/find

<base_url> is a placeholder that will be replaced by the extension's Base URL. You can configure this URL via the Developer Portal. The /content/resources/find path is not configurable.

The body of this request is a JSON object that contains the following properties:

Name

Type

Description

brand

string

The ID of the user’s brand.

continuation?

string

A token used for pagination.

label

string

The type of extension that triggered the request.

limit

integer

The maximum number of embeds to return in a response.

locale?

string

The user’s locale as an IETF BCP 47 language tag.

query?

string

A search query, provided by the user.

type

string

user

string

The ID of the user.

This is an example of an "EMBED" request:

{
"user": "AUQ2RUzug9pEvgpK9lL2qlpRsIbn1Vy5GoEt1MaKRE=",
"brand": "AUQ2RUxiRj966Wsvp7oGrz33BnaFmtq4ftBeLCSHf8=",
"label": "CONTENT",
"limit": 100,
"type": "EMBED",
"locale": "en-US"
}

Responding to embed requests

After receiving an "EMBED" request, your extension should return a "SUCCESS" response that includes the embeds that will appear in the side panel.

The body of this response must contain the following properties:

Name

Type

Description

continuation?

string

A token used for pagination.

resources

array

The embeds to display in the side panel.

type

string

The type of response.

Each object in the resources array must contain the following properties:

Name

Type

Description

id

string

A unique ID for the embed.

name

string

A human readable name for the embed.

thumbnail

object

A thumbnail for the embed.

type

string

The type of resource.

url

string

The URL of the embeddable media. This URL must be supported by Iframely.

The thumbnail object must contain the following properties:

Name

Type

Description

height?

number

The height of the thumbnail, in pixels.

url

string

The URL of the thumbnail.

width?

number

The width of the thumbnail, in pixels.

For thumbnail images, we recommend a minimum width and height of 150 pixels.

This is an example of a "SUCCESS" response:

{
"type": "SUCCESS",
"resources": [
{
"id": "dQw4w9WgXcQ",
"name": "Rick Astley - Never Gonna Give You Up",
"type": "EMBED",
"thumbnail": {
"url": "https://i.imgur.com/Q2Unw.gif"
},
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}
]
}

When an "EMBED" resource is an animated GIF, the thumbnail should also be animated.

Error handling

If your extension is unable to return the requested embeds, it should return an "ERROR" response:

{
"type": "ERROR",
"errorCode": "INVALID_REQUEST"
}

For a complete list of valid error codes, refer to the API reference.