Skip navigation
Skip to main content
Reference

POST /content/resources/find

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

When a user interacts with a content extension, Canva sends POST requests to the following endpoint:

<base_url>/content/resources/find
bash

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 types property in the request body determines the type of resources the extension can provide in the response. For example, when value of the types includes "IMAGE", the endpoint can 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.
  • Extensions should meet the UX guidelines.

Request

Endpoint

POST <base_url>/content/resources/find
bash

Headers

PropertyTypeRequiredDescription
X-Canva-SignaturesstringYesA comma-separated list of request signatures. The name of this header is sometimes lowercase (e.g. x-canva-signatures).
X-Canva-TimestampstringYesThe 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

PropertyTypeRequiredDescription
userstringYesThe ID of the user.
brandstringYesThe ID of the user's team.
labelstringYesThe type of extension that sent the request.
limitnumberYesThe maximum number of resources to provide in a response.
localestringYesThe user's locale as an IETF BCP 47 language tag.
type (deprecated)stringYesThe type of resources the extension must provide in the response. Enum: "CONTAINER", "EMBED", "IMAGE", "VIDEO"
typesArray<string>YesThe types of resources the extension can provide in the response. Enum: "CONTAINER", "EMBED", "IMAGE", "VIDEO"
continuationstringNoA token for paginating resources.
containerIdstringNoThe ID of the selected container.
querystringNoA user-provided search query.

Example

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

Responses

200 - Success (containers)

The response an extension must provide when the types property in the request body includes "CONTAINER".

Properties

PropertyTypeRequiredDescription
type"SUCCESS"YesThe type of response.
resourcesArray<Container>YesThe containers to render in the side panel.
continuationstringNoA token for paginating resources.

Example

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

200 - Success (embeds)

The response an extension must provide when the types property in the request body includes "EMBED".

Properties

PropertyTypeRequiredDescription
type"SUCCESS"YesThe type of response.
resourcesArray<Embed>YesThe embeds to render in the side panel.
continuationstringNoA token for paginating resources.

Example

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

200 - Success (images)

The response an extension must provide when the types property in the request body includes "IMAGE".

Properties

PropertyTypeRequiredDescription
type"SUCCESS"YesThe type of response.
resourcesArray<Image>YesThe images to render in the side panel.
continuationstringNoA token for paginating resources.

Example

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

200 - Success (videos)

The response an extension must provide when the types property in the request body includes "VIDEO".

Properties

PropertyTypeRequiredDescription
type"SUCCESS"YesThe type of response.
resourcesArray<Video>YesThe videos to render in the side panel.
continuationstringNoA token for paginating resources.

Example

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

200 - Error

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

Properties

PropertyTypeRequiredDescription
type"ERROR"YesThe type of response.
errorCodestringYesAn error code that describes what went wrong. Enum: "CONFIGURATION_REQUIRED", "FORBIDDEN", "INTERNAL_ERROR", "INVALID_REQUEST", "NOT_FOUND", "TIMEOUT"

Example

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

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

PropertyTypeRequiredDescription
thumbnailThumbnailNoA thumbnail for the container.
idstringYesA unique ID for the container. The ID must be less than 100 characters.
namestringYesA human readable name for the container. The name must be equal to or less than 200 characters.
type"CONTAINER"YesThe type of resource.

Example

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

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

PropertyTypeRequiredDescription
idstringYesA unique ID for the embed. The ID must be less than 100 characters.
namestringYesA human readable name for the embed. The name must be equal to or less than 200 characters.
type"EMBED"YesThe type of resource.
urlstringYesThe URL of the embeddable media. This URL must be HTTPS-enabled, supported by Iframely, and less than 2048 characters.
thumbnailThumbnailYesA thumbnail for the embed.

Example

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

Image

Represents an image file that Canva renders in the side panel, such as a PNG or SVG.

Properties

PropertyTypeRequiredDescription
idstringYesA unique ID for the image. This ID must always refer to the same image file and be less than 100 characters. If the image file is modified, assign it a new ID.
namestringYesA human readable name for the image. The name must be equal to or less than 200 characters.
type"IMAGE"YesThe type of resource.
urlstringYesThe URL of the full-resolution image. This URL must be HTTPS-enabled, not redirect to a different URL, and be less than 2048 characters. The MIME type of the image must match the type specified in the contentType property. The image must meet Canva's file upload requirements.
contentTypestringYesThe MIME type of the image. Enum: "image/jpeg", "image/png", "image/svg+xml", "image/heic"
thumbnailThumbnailYesA 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>",
  "contentType": "<content_type>",
  "thumbnail": {
    "url": "<url>"
  }
}
json

Video

Represents a video file that Canva renders in the side panel, such as an MP4 or MOV file.

Properties

PropertyTypeRequiredDescription
idstringYesA unique ID for the video. This ID must always refer to the same video file and be less than 100 characters. If the video file is modified, assign it a new ID.
namestringYesA human readable name for the video. The name must be less than 100 characters.
type"VIDEO"YesThe type of resource.
urlstringYesThe URL of the full-resolution video. This URL must be HTTPS-enabled, not redirect to a different URL, and be less than 2048 characters. The MIME type of the video must match the type specified in the contentType property. The video must meet Canva's file upload requirements.
contentTypestringYesThe MIME type of the video. Enum: "video/mov", "image/gif", "video/mpeg", "video/x-matroska", "video/webm", "video/mp4"
widthnumberYesThe width of the full-resolution video, in pixels.
heightnumberYesThe height of the full-resolution video, in pixels.
durationMsnumberYesThe duration of the video, in milliseconds.
thumbnailThumbnailYesA thumbnail for the video. This thumbnail must have the same aspect ratio as the full-resolution video.

Example

{
  "width": 0,
  "height": 0,
  "durationMs": 0,
  "id": "<id>",
  "name": "<name>",
  "type": "VIDEO",
  "url": "<url>",
  "contentType": "<content_type>",
  "thumbnail": {
    "url": "<url>"
  }
}
json

Thumbnail

A thumbnail image.

Properties

PropertyTypeRequiredDescription
urlstringYesThe URL of the thumbnail. This URL must be HTTPS-enabled and less than 2048 characters.
heightnumberNoThe height of the thumbnail, in pixels. If you provide a height, you must provide a width.
widthnumberNoThe width of the thumbnail, in pixels. If you provide a width, you must provide a height.

Example

{
  "url": "<url>"
}
json