POST /content/resources/find

API reference for the "/content/resources/find" endpoint.

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.

Notes

  • 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.

Request

Endpoint

POST <base_url>/content/resources/find

Headers

Property

Type

Required

Description

X-Canva-Signatures

string

Yes

A comma-separated list of request signatures. The name of this header is sometimes lowercase (e.g. x-canva-signatures).

X-Canva-Timestamp

string

Yes

The UNIX timestamp (in seconds) of when Canva sent the request. The name of this header is sometimes lowercase (e.g. x-canva-timestamp).

Body

Properties

Property

Type

Required

Description

user

string

Yes

The ID of the user.

brand

string

Yes

The ID of the user's team.

label

string

Yes

The type of extension that sent the request.

limit

number

Yes

The maximum number of resources to provide in a response.

locale

string

Yes

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

type (deprecated)

string

Yes

The type of resources the extension must provide in the response. Enum: "CONTAINER", "EMBED", "IMAGE"

types

Array<string>

Yes

The types of resources the extension can provide in the response. Enum: "CONTAINER", "EMBED", "IMAGE"

continuation

string

No

A token for paginating resources.

containerId

string

No

The ID of the selected container.

query

string

No

A user-provided search query.

Example

{
"limit": 100,
"user": "<user>",
"brand": "<brand>",
"label": "<label>",
"locale": "<locale>",
"type": "<type>"
}

Responses

200 - Success (containers)

The response an extension must provide when the value of the type property in the request body is "CONTAINER".

Properties

Property

Type

Required

Description

type

"SUCCESS"

Yes

The type of response.

resources

Array<Container>

Yes

The containers to render in the side panel.

continuation

string

No

A token for paginating resources.

Example

{
"resources": [],
"type": "SUCCESS"
}

200 - Success (embeds)

The response an extension must provide when the value of the type property in the request body is "EMBED".

Properties

Property

Type

Required

Description

type

"SUCCESS"

Yes

The type of response.

resources

Array<Embed>

Yes

The embeds to render in the side panel.

continuation

string

No

A token for paginating resources.

Example

{
"resources": [],
"type": "SUCCESS"
}

200 - Success (images)

The response an extension must provide when the value of the type property in the request body is "IMAGE".

Properties

Property

Type

Required

Description

type

"SUCCESS"

Yes

The type of response.

resources

Array<Image>

Yes

The images to render in the side panel.

continuation

string

No

A token for paginating resources.

Example

{
"resources": [],
"type": "SUCCESS"
}

200 - Error

The response an extension provides when it can't provide the requested resources.

Properties

Property

Type

Required

Description

type

"ERROR"

Yes

The type of response.

errorCode

string

Yes

An error code that describes what went wrong. Enum: "CONFIGURATION_REQUIRED", "FORBIDDEN", "INTERNAL_ERROR", "INVALID_REQUEST", "NOT_FOUND", "TIMEOUT"

Example

{
"type": "ERROR",
"errorCode": "<error_code>"
}

401 - Invalid request signature or timestamp

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.

Schemas

Container

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.

Properties

Property

Type

Required

Description

thumbnail

Thumbnail

No

A thumbnail for the container.

id

string

Yes

A unique ID for the container.

name

string

Yes

A human readable name for the container.

type

"CONTAINER"

Yes

The type of resource.

Example

{
"id": "<id>",
"name": "<name>",
"type": "CONTAINER"
}

Embed

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.

Properties

Property

Type

Required

Description

id

string

Yes

A unique ID for the embed.

name

string

Yes

A human readable name for the embed.

type

"EMBED"

Yes

The type of resource.

url

string

Yes

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

thumbnail

Thumbnail

Yes

A thumbnail for the embed.

Example

{
"id": "<id>",
"name": "<name>",
"type": "EMBED",
"url": "<url>"
}

Image

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.

Properties

Property

Type

Required

Description

contentType

string

No

The MIME type of the image. If you omit the contentType, Canva must send a HEAD request to each image, which decreases the performance of the extension. Enum: "image/jpeg", "image/png", "image/svg+xml", "image/heic"

id

string

Yes

A unique ID for the image. This ID should always refer to the same image file.

name

string

Yes

A human readable name for the image.

type

"IMAGE"

Yes

The type of resource.

url

string

Yes

The URL of the full-resolution image. The MIME type of the image must match the type specified in the contentType property. The image must also meet Canva's Upload format and requirements. For security reasons, the URL must not redirect to a different URL.

thumbnail

Thumbnail

Yes

A thumbnail for the image. This thumbnail must have the same aspect ratio as the full-resolution image.

Example

{
"id": "<id>",
"name": "<name>",
"type": "IMAGE",
"url": "<url>"
}

Thumbnail

A thumbnail image.

Properties

Property

Type

Required

Description

url

string

Yes

The URL of the thumbnail.

height

number

No

The height of the thumbnail (in pixels). If you provide a height, you must provide a width.

width

number

No

The width of the thumbnail (in pixels). If you provide a width, you must provide a height.

Example

{
"url": "<url>"
}