POST /publish/resources/find

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

If a publish extension uses the Flat list or Nested list layout, Canva sends POST requests to the following endpoint:

<base_url>/publish/resources/find

Specifically, Canva sends these requests when a user:

  • Opens an extension that uses the Flat list or Nested list layout.

  • Opens a container in an extension that uses the Nested list layout.

The purpose of these requests is to retrieve a list of resources from the extension and then render those resources in the Publish menu as files or folders.

When a resource is rendered as a folder, a user can select it and publish their design to a specific location on the destination platform (such as a specific folder in Dropbox).

When a resource is rendered as a file, a user can't interact with it.

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.

  • The API refers to files as "IMAGE" resources and folders as "CONTAINER" resources.

Request

Endpoint

POST <base_url>/publish/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.

preferredThumbnailHeight

integer

Yes

The recommended height (in pixels) of any thumbnails in the response.

preferredThumbnailWidth

integer

Yes

The recommended width (in pixels) of any thumbnails in the response.

designId

string

Yes

The ID of the user's design. This ID does not change if the user republishes their design.

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,
"preferredThumbnailHeight": 500,
"preferredThumbnailWidth": 500,
"user": "<user>",
"brand": "<brand>",
"label": "<label>",
"designId": "<design_id>"
}

Responses

200 - Success

The response an extension provides when it can return a list of resources to render in the Publish menu.

Properties

Property

Type

Required

Description

type

"SUCCESS"

Yes

The type of response.

resources

Array<Resource>

Yes

continuation

string

No

A token for paginating resources.

Example

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

200 - Error

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

Resource

Properties

Property

Type

Required

Description

thumbnail

Thumbnail

No

A thumbnail image.

id

string

Yes

A unique ID for the resource.

name

string

Yes

A human readable name for the resource.

type

string

Yes

The type of resource. Canva renders "CONTAINER" resources as folders and "IMAGE" resources as files. Enum: "CONTAINER", "IMAGE"

isOwner

boolean

Yes

A value of true indicates that the user is the owner of the resource.

readOnly

boolean

Yes

A value of true indicates that the user has read-only access to the resource.

Example

{
"isOwner": true,
"readOnly": true,
"id": "<id>",
"name": "<name>",
"type": "<type>"
}