openapi: 3.0.0
info:
contact:
name: Canva Developer Community
url: https://community.canva.dev/
description: API for building apps with Canva via a REST api
license:
name: ©2023 All Rights Reserved
termsOfService: https://www.canva.com/trust/legal/
title: Canva REST APIs
version: 2024-06-18
servers:
- description: Canva REST APIs
url: https://api.canva.com/rest
tags:
- description: Allow management of brands
name: brands
- name: analytics
- name: app
- name: asset
- name: autofill
- name: brand_template
- name: comment
- name: connect
- name: design
- name: design_generation
- name: design_import
- name: export
- name: folder
- name: image_generation
- name: image_transformation
- name: merge
- name: oauth
- name: oidc
- name: resize
- name: user
paths:
/v1/designs/{designId}/analytics:
get:
description: |-
This API is currently provided as a preview. Be aware of the following:
- There might be unannounced breaking changes.
- Any breaking changes to preview APIs won't produce a new [API version](https://www.canva.dev/docs/apps/rest-apis/versions/).
- Public apps that use preview APIs will not pass the review process, and can't be made available to all Canva users.
To use this API, your app must act on behalf of a user who is a member of a [Canva Enterprise](https://www.canva.com/enterprise/) organization.
Gets the aggregated analytics for a design.
The response includes total views, unique viewers, and view duration metrics.
operationId: getDesignAnalytics
parameters:
- description: The design ID.
explode: false
in: path
name: designId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/GetDesignAnalyticsResponse'
description: OK
"400":
content:
application/json:
examples:
analytics_invalid_design_id:
$ref: '#/components/examples/AnalyticsInvalidDesignIdError'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
"401":
content:
application/json:
examples:
invalid_access_token:
$ref: '#/components/examples/InvalidAccessToken'
schema:
$ref: '#/components/schemas/Error'
description: Unauthorized
"403":
content:
application/json:
examples:
analytics_permission_denied:
$ref: '#/components/examples/AnalyticsPermissionDeniedError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
analytics_design_not_found:
$ref: '#/components/examples/AnalyticsDesignNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
"429":
content:
application/json:
examples:
too_many_requests:
$ref: '#/components/examples/TooManyRequestsError'
schema:
$ref: '#/components/schemas/Error'
description: Too Many Requests
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthAuthCode:
- design:content:read
tags:
- analytics
x-required-capabilities:
- analytics
x-rate-limit-per-client-user: 100
/v1/designs/{designId}/analytics/viewers:
get:
description: |-
This API is currently provided as a preview. Be aware of the following:
- There might be unannounced breaking changes.
- Any breaking changes to preview APIs won't produce a new [API version](https://www.canva.dev/docs/apps/rest-apis/versions/).
- Public apps that use preview APIs will not pass the review process, and can't be made available to all Canva users.
To use this API, your app must act on behalf of a user who is a member of a [Canva Enterprise](https://www.canva.com/enterprise/) organization.
Lists viewers for a design, ordered by most recent view first.
operationId: getDesignAnalyticsViewers
parameters:
- description: The design ID.
explode: false
in: path
name: designId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
- description: "Filters viewers by a specific trackable link. If omitted, only\
\ viewers who visited the design without using a trackable link are returned."
explode: true
in: query
name: link_id
required: false
schema:
example: hddb98a3716
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: form
- description: "Only returns viewers whose first view happened after this time,\
\ as a Unix timestamp (in seconds since the Unix Epoch)."
explode: true
in: query
name: first_viewed_after
required: false
schema:
example: 1745452800
format: int64
type: integer
style: form
- description: The maximum number of viewers to return per page.
explode: true
in: query
name: limit
required: false
schema:
default: 50
example: 50
format: int32
maximum: 100
minimum: 1
type: integer
style: form
- description: |-
If the success response contains a continuation token, there are more viewers you can list. You can use this token as a query parameter and retrieve more viewers from the list, for example `/v1/designs/{designId}/analytics/viewers?continuation={continuation}`.
To retrieve all viewers, you might need to make multiple requests.
explode: true
in: query
name: continuation
required: false
schema:
example: RkFGMgXlsVTDbMd:MR3L0QjiaUzycIAjx0yMyuNiV0OildoiOwL0x32G4NjNu4FwtAQNxowUQNMMYN
type: string
style: form
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/GetDesignAnalyticsViewersResponse'
description: OK
"400":
content:
application/json:
examples:
analytics_invalid_query_parameter:
$ref: '#/components/examples/ExpectedLongQueryParam'
analytics_invalid_continuation_token:
$ref: '#/components/examples/AnalyticsInvalidContinuationError'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
"401":
content:
application/json:
examples:
invalid_access_token:
$ref: '#/components/examples/InvalidAccessToken'
schema:
$ref: '#/components/schemas/Error'
description: Unauthorized
"403":
content:
application/json:
examples:
analytics_permission_denied:
$ref: '#/components/examples/AnalyticsPermissionDeniedError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
analytics_design_not_found:
$ref: '#/components/examples/AnalyticsDesignNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
"429":
content:
application/json:
examples:
too_many_requests:
$ref: '#/components/examples/TooManyRequestsError'
schema:
$ref: '#/components/schemas/Error'
description: Too Many Requests
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthAuthCode:
- design:content:read
tags:
- analytics
x-required-capabilities:
- analytics
x-rate-limit-per-client-user: 100
/v1/designs/{designId}/analytics/views-over-time:
get:
description: |-
This API is currently provided as a preview. Be aware of the following:
- There might be unannounced breaking changes.
- Any breaking changes to preview APIs won't produce a new [API version](https://www.canva.dev/docs/apps/rest-apis/versions/).
- Public apps that use preview APIs will not pass the review process, and can't be made available to all Canva users.
To use this API, your app must act on behalf of a user who is a member of a [Canva Enterprise](https://www.canva.com/enterprise/) organization.
Lists the view counts over time for a design.
Each response item represents one time bucket.
operationId: getDesignAnalyticsViewsOverTime
parameters:
- description: The design ID.
explode: false
in: path
name: designId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
- description: "The inclusive start of the requested time range, as a Unix timestamp\
\ (in seconds since the Unix Epoch)."
explode: true
in: query
name: start_time
required: false
schema:
example: 1745452800
format: int64
type: integer
style: form
- description: "The inclusive end of the requested time range, as a Unix timestamp\
\ (in seconds since the Unix Epoch)."
explode: true
in: query
name: end_time
required: false
schema:
example: 1748044800
format: int64
type: integer
style: form
- description: "The timezone to use for bucketing, as a UTC offset in the form\
\ `+HH:MM` (for example, `+10:00`)."
explode: true
in: query
name: timezone
required: false
schema:
default: +00:00
example: "600"
type: string
style: form
- description: The maximum number of time buckets to return per page.
explode: true
in: query
name: limit
required: false
schema:
default: 50
example: 50
format: int32
maximum: 100
minimum: 1
type: integer
style: form
- description: |-
If the success response contains a continuation token, there are more time buckets you can list. You can use this token as a query parameter and retrieve more time buckets from the list, for example `/v1/designs/{designId}/analytics/views-over-time?continuation={continuation}`.
To retrieve all time buckets, you might need to make multiple requests.
explode: true
in: query
name: continuation
required: false
schema:
example: RkFGMgXlsVTDbMd:MR3L0QjiaUzycIAjx0yMyuNiV0OildoiOwL0x32G4NjNu4FwtAQNxowUQNMMYN
type: string
style: form
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/GetDesignAnalyticsViewsOverTimeResponse'
description: OK
"400":
content:
application/json:
examples:
analytics_invalid_query_parameter:
$ref: '#/components/examples/ExpectedLongQueryParam'
analytics_invalid_time_range:
$ref: '#/components/examples/AnalyticsInvalidTimeRangeError'
analytics_invalid_timezone:
$ref: '#/components/examples/AnalyticsInvalidTimezoneError'
analytics_invalid_continuation_token:
$ref: '#/components/examples/AnalyticsInvalidContinuationError'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
"401":
content:
application/json:
examples:
invalid_access_token:
$ref: '#/components/examples/InvalidAccessToken'
schema:
$ref: '#/components/schemas/Error'
description: Unauthorized
"403":
content:
application/json:
examples:
analytics_permission_denied:
$ref: '#/components/examples/AnalyticsPermissionDeniedError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
analytics_design_not_found:
$ref: '#/components/examples/AnalyticsDesignNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
"429":
content:
application/json:
examples:
too_many_requests:
$ref: '#/components/examples/TooManyRequestsError'
schema:
$ref: '#/components/schemas/Error'
description: Too Many Requests
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthAuthCode:
- design:content:read
tags:
- analytics
x-required-capabilities:
- analytics
x-rate-limit-per-client-user: 100
/v1/designs/{designId}/analytics/page-views:
post:
description: |-
This API is currently provided as a preview. Be aware of the following:
- There might be unannounced breaking changes.
- Any breaking changes to preview APIs won't produce a new [API version](https://www.canva.dev/docs/apps/rest-apis/versions/).
- Public apps that use preview APIs will not pass the review process, and can't be made available to all Canva users.
To use this API, your app must act on behalf of a user who is a member of a [Canva Enterprise](https://www.canva.com/enterprise/) organization.
Lists the page-level view duration data for a design.
The request body can include page filters and pagination controls.
operationId: getDesignAnalyticsPageViews
parameters:
- description: The design ID.
explode: false
in: path
name: designId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/GetDesignAnalyticsPageViewsRequest'
required: true
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/GetDesignAnalyticsPageViewsResponse'
description: OK
"400":
content:
application/json:
examples:
analytics_invalid_request_body:
$ref: '#/components/examples/FailedToReadRequestBody'
analytics_invalid_page_views_filter:
$ref: '#/components/examples/AnalyticsInvalidPageViewsFilterError'
analytics_invalid_continuation_token:
$ref: '#/components/examples/AnalyticsInvalidContinuationError'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
"401":
content:
application/json:
examples:
invalid_access_token:
$ref: '#/components/examples/InvalidAccessToken'
schema:
$ref: '#/components/schemas/Error'
description: Unauthorized
"403":
content:
application/json:
examples:
analytics_permission_denied:
$ref: '#/components/examples/AnalyticsPermissionDeniedError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
analytics_design_not_found:
$ref: '#/components/examples/AnalyticsDesignNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
"429":
content:
application/json:
examples:
too_many_requests:
$ref: '#/components/examples/TooManyRequestsError'
schema:
$ref: '#/components/schemas/Error'
description: Too Many Requests
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthAuthCode:
- design:content:read
tags:
- analytics
x-required-capabilities:
- analytics
x-rate-limit-per-client-user: 100
/v1/designs/{designId}/analytics/links:
get:
description: |-
This API is currently provided as a preview. Be aware of the following:
- There might be unannounced breaking changes.
- Any breaking changes to preview APIs won't produce a new [API version](https://www.canva.dev/docs/apps/rest-apis/versions/).
- Public apps that use preview APIs will not pass the review process, and can't be made available to all Canva users.
To use this API, your app must act on behalf of a user who is a member of a [Canva Enterprise](https://www.canva.com/enterprise/) organization.
Lists trackable links and their metrics for a design.
operationId: getDesignAnalyticsLinks
parameters:
- description: The design ID.
explode: false
in: path
name: designId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
- description: The maximum number of links to return per page.
explode: true
in: query
name: limit
required: false
schema:
default: 50
example: 50
format: int32
maximum: 100
minimum: 1
type: integer
style: form
- description: |-
If the success response contains a continuation token, there are more links you can list. You can use this token as a query parameter and retrieve more links from the list, for example `/v1/designs/{designId}/analytics/links?continuation={continuation}`.
To retrieve all links, you might need to make multiple requests.
explode: true
in: query
name: continuation
required: false
schema:
example: RkFGMgXlsVTDbMd:MR3L0QjiaUzycIAjx0yMyuNiV0OildoiOwL0x32G4NjNu4FwtAQNxowUQNMMYN
type: string
style: form
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/GetDesignAnalyticsLinksResponse'
description: OK
"400":
content:
application/json:
examples:
analytics_invalid_query_parameter:
$ref: '#/components/examples/ExpectedLongQueryParam'
analytics_invalid_continuation_token:
$ref: '#/components/examples/AnalyticsInvalidContinuationError'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
"401":
content:
application/json:
examples:
invalid_access_token:
$ref: '#/components/examples/InvalidAccessToken'
schema:
$ref: '#/components/schemas/Error'
description: Unauthorized
"403":
content:
application/json:
examples:
analytics_permission_denied:
$ref: '#/components/examples/AnalyticsPermissionDeniedError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
analytics_design_not_found:
$ref: '#/components/examples/AnalyticsDesignNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
"429":
content:
application/json:
examples:
too_many_requests:
$ref: '#/components/examples/TooManyRequestsError'
schema:
$ref: '#/components/schemas/Error'
description: Too Many Requests
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthAuthCode:
- design:content:read
tags:
- analytics
x-required-capabilities:
- analytics
x-rate-limit-per-client-user: 100
/v1/apps/{appId}/jwks:
get:
description: |-
Returns the Json Web Key Set (public keys) of an app. These keys are used to
verify JWTs sent to app backends.
operationId: getAppJwks
parameters:
- description: The app ID.
explode: false
in: path
name: appId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/GetAppJwksResponse'
description: OK
"404":
content:
application/json:
examples:
auth_keys_not_found:
$ref: '#/components/examples/AuthKeysNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
tags:
- app
/v1/assets/{assetId}:
delete:
description: |-
You can delete an asset by specifying its `assetId`. This operation mirrors the behavior
in the Canva UI. Deleting an item moves it to the trash.
Deleting an asset doesn't remove it from designs that already use it.
operationId: deleteAsset
parameters:
- description: The ID of the asset.
explode: false
in: path
name: assetId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
responses:
"204":
description: OK
"403":
content:
application/json:
examples:
asset_delete_not_allowed:
$ref: '#/components/examples/AssetDeleteNotAllowedError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
asset_not_found:
$ref: '#/components/examples/AssetNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthAuthCode:
- asset:write
tags:
- asset
x-rate-limit-per-client-user: 30
get:
description: You can retrieve the metadata of an asset by specifying its `assetId`.
operationId: getAsset
parameters:
- description: The ID of the asset.
explode: false
in: path
name: assetId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/GetAssetResponse'
description: OK
"403":
content:
application/json:
examples:
asset_access_not_allowed:
$ref: '#/components/examples/AssetAccessNotAllowedError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
asset_not_found:
$ref: '#/components/examples/AssetNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthAuthCode:
- asset:read
tags:
- asset
x-rate-limit-per-client-user: 100
patch:
description: |-
You can update the name and tags of an asset by specifying its `assetId`. Updating the tags
replaces all existing tags of the asset.
operationId: updateAsset
parameters:
- description: The ID of the asset.
explode: false
in: path
name: assetId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateAssetRequest'
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateAssetResponse'
description: OK
"403":
content:
application/json:
examples:
asset_update_not_allowed:
$ref: '#/components/examples/AssetUpdateNotAllowedError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
asset_not_found:
$ref: '#/components/examples/AssetNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthAuthCode:
- asset:write
tags:
- asset
x-rate-limit-per-client-user: 30
/v1/asset-uploads:
post:
description: |-
Starts a new [asynchronous job](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints) to upload an asset to the user's content library. Supported file types for assets are listed in the [Assets API overview](https://www.canva.dev/docs/apps/rest-apis/reference/assets/).
The request format for this endpoint is an `application/octet-stream` body of bytes. Attach
information about the upload using an `Asset-Upload-Metadata` header.
For more information on the workflow for using asynchronous jobs, see [API requests and responses](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints). You can check the status and get the results of asset upload jobs created with this API using the [Get asset upload job API](https://www.canva.dev/docs/apps/rest-apis/reference/assets/get-asset-upload-job/).
operationId: CreateAssetUploadJob
parameters:
- content:
application/json:
schema:
$ref: '#/components/schemas/AssetUploadMetadata'
in: header
name: Asset-Upload-Metadata
required: true
requestBody:
content:
application/octet-stream:
schema:
format: binary
type: string
description: Binary of the asset to upload.
required: true
responses:
"200":
content:
application/json:
examples:
in_progress:
$ref: '#/components/examples/InProgressAssetUploadJobExample'
success:
$ref: '#/components/examples/SuccessAssetUploadJobExample'
failed:
$ref: '#/components/examples/FailedAssetUploadJobExample'
schema:
$ref: '#/components/schemas/CreateAssetUploadJobResponse'
description: OK
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthClientCredentials:
- service:asset:write
- oauthAuthCode:
- asset:write
tags:
- asset
x-rate-limit-per-client-user: 30
x-rate-limit-per-client-credential: 100
/v1/asset-uploads/{jobId}:
get:
description: |-
Get the result of an asset upload job that was created using the [Create asset upload job API](https://www.canva.dev/docs/apps/rest-apis/reference/assets/create-asset-upload-job/).
You might need to make multiple requests to this endpoint until you get a `success` or `failed` status. For more information on the workflow for using asynchronous jobs, see [API requests and responses](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints).
operationId: GetAssetUploadJob
parameters:
- description: The asset upload job ID.
explode: false
in: path
name: jobId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
responses:
"200":
content:
application/json:
examples:
in_progress:
$ref: '#/components/examples/InProgressAssetUploadJobExample'
success:
$ref: '#/components/examples/SuccessAssetUploadJobExample'
failed:
$ref: '#/components/examples/FailedAssetUploadJobExample'
schema:
$ref: '#/components/schemas/GetAssetUploadJobResponse'
description: OK
"403":
content:
application/json:
examples:
asset_access_not_allowed:
$ref: '#/components/examples/AssetAccessNotAllowedError'
asset_upload_job_not_creator:
$ref: '#/components/examples/AssetUploadJobNotCreatorError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
asset_not_found:
$ref: '#/components/examples/AssetNotFoundError'
asset_upload_job_not_found:
$ref: '#/components/examples/AssetUploadJobNotFoundError'
job_id_not_found:
$ref: '#/components/examples/AssetJobIdNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthClientCredentials:
- service:asset:read
- oauthAuthCode:
- asset:read
tags:
- asset
x-rate-limit-per-client-user: 180
x-rate-limit-per-client-credential: 100
/v1/url-asset-uploads:
post:
description: |-
Starts a new [asynchronous job](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints) to upload an asset from a URL to the user's content library. Supported file types for assets are listed in the [Assets API overview](https://www.canva.dev/docs/apps/rest-apis/reference/assets/).
Uploading a video asset from a URL is limited to a maximum 100MB file size. For importing larger video files, use the [Create asset upload job API](https://www.canva.dev/docs/apps/rest-apis/reference/assets/create-asset-upload-job/).
For more information on the workflow for using asynchronous jobs, see [API requests and responses](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints). You can check the status and get the results of asset upload jobs created with this API using the [Get asset upload job via URL API](https://www.canva.dev/docs/apps/rest-apis/reference/assets/get-url-asset-upload-job/).
operationId: createUrlAssetUploadJob
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUrlAssetUploadJobRequest'
required: true
responses:
"200":
content:
application/json:
examples:
in_progress:
$ref: '#/components/examples/InProgressAssetUploadJobExample'
success:
$ref: '#/components/examples/SuccessAssetUploadJobExample'
failed:
$ref: '#/components/examples/FailedAssetUploadJobExample'
schema:
$ref: '#/components/schemas/CreateUrlAssetUploadJobResponse'
description: OK
"400":
content:
application/json:
examples:
url_invalid:
$ref: '#/components/examples/AssetUrlInvalidError'
asset_upload_already_exists:
$ref: '#/components/examples/AssetUploadAlreadyExistsError'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
"404":
content:
application/json:
examples:
job_with_id_not_found:
$ref: '#/components/examples/AssetJobWithIdNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthClientCredentials:
- service:asset:write
- oauthAuthCode:
- asset:write
tags:
- asset
x-rate-limit-per-client-user: 30
x-rate-limit-per-client-credential: 100
/v1/url-asset-uploads/{jobId}:
get:
description: |-
Get the result of an asset upload job that was created using the [Create asset upload job via URL API](https://www.canva.dev/docs/apps/rest-apis/reference/assets/create-url-asset-upload-job/).
You might need to make multiple requests to this endpoint until you get a `success` or `failed` status. For more information on the workflow for using asynchronous jobs, see [API requests and responses](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints).
operationId: getUrlAssetUploadJob
parameters:
- description: The asset upload job ID.
explode: false
in: path
name: jobId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
responses:
"200":
content:
application/json:
examples:
in_progress:
$ref: '#/components/examples/InProgressAssetUploadJobExample'
success:
$ref: '#/components/examples/SuccessAssetUploadJobExample'
failed:
$ref: '#/components/examples/FailedAssetUploadJobExample'
schema:
$ref: '#/components/schemas/GetUrlAssetUploadJobResponse'
description: OK
"403":
content:
application/json:
examples:
get_this_job_status_not_allowed:
$ref: '#/components/examples/GetThisJobStatusNotAllowedError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
job_not_found:
$ref: '#/components/examples/AssetJobNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthClientCredentials:
- service:asset:read
- oauthAuthCode:
- asset:read
tags:
- asset
x-rate-limit-per-client-user: 180
x-rate-limit-per-client-credential: 100
/v1/autofills:
post:
description: |-
Autofill for designs and brand templates is available when your app acts on behalf of a user on Canva Pro (including Canva Education and Canva for Nonprofits), Canva Teams, or Canva Enterprise. Usage limits will be introduced in the future.
Starts a new [asynchronous job](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints) to autofill a Canva design using input data. Use the `type` field to choose the source of the design:
- `create_from_brand_template`: autofill a new design from a brand template. If `type` isn't specified in the request, the request type is assumed to be `create_from_brand_template`. To get a list of input data fields for a brand template, use the [Get brand template dataset API](https://www.canva.dev/docs/apps/rest-apis/reference/brand-templates/get-brand-template-dataset/).
- `create_from_design`: autofill a new design from an existing design that contains autofill data fields. To get the input data fields for an existing design, use the [Get design dataset
API](https://www.canva.dev/docs/apps/rest-apis/reference/designs/get-design-dataset/).
- `update_design`: autofill an existing design in place, rather than creating a new design. To get the input data fields for the design, use the [Get design dataset API](https://www.canva.dev/docs/apps/rest-apis/reference/designs/get-design-dataset/).
Data fields in brand templates or designs might change (for example, they might be renamed or removed). If you provide data for a field name that doesn't exist, it's silently skipped. Use the Get dataset APIs to confirm the current fields before creating an autofill job.
Available data field types to autofill include:
- Images (which you can autofill with an image or a video asset)
- Text
- Charts
- Sheets
NOTE: For more information on the workflow for using asynchronous jobs, see [API requests and responses](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints). You can check the status and get the results of autofill jobs created with this API using the [Get design autofill job API](https://www.canva.dev/docs/apps/rest-apis/reference/autofills/get-design-autofill-job/).
operationId: createDesignAutofillJob
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDesignAutofillJobRequest'
responses:
"200":
content:
application/json:
examples:
in_progress:
$ref: '#/components/examples/InProgressAutofillJobExample'
success:
$ref: '#/components/examples/SuccessAutofillJobExample'
failed:
$ref: '#/components/examples/FailedAutofillJobExample'
schema:
$ref: '#/components/schemas/CreateDesignAutofillJobResponse'
description: OK
"400":
content:
application/json:
examples:
design_title_invalid:
$ref: '#/components/examples/DesignTitleInvalidError'
chart_data_processing_unsupported:
$ref: '#/components/examples/ChartDataProcessingUnsupportedError'
invalid_brand_template_id:
$ref: '#/components/examples/InvalidBrandTemplateIdError'
design_not_fillable:
$ref: '#/components/examples/DesignNotFillableError'
autofill_data_invalid:
$ref: '#/components/examples/AutofillDataInvalidError'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
"403":
content:
application/json:
examples:
brand_template_forbidden:
$ref: '#/components/examples/BrandTemplateForbiddenError'
autofill_design_forbidden:
$ref: '#/components/examples/AutofillDesignForbiddenError'
autofill_feature_forbidden:
$ref: '#/components/examples/AutofillFeatureForbiddenError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
brand_template_not_found:
$ref: '#/components/examples/BrandTemplateNotFoundError'
autofill_design_not_found:
$ref: '#/components/examples/AutofillDesignNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
"429":
content:
application/json:
examples:
autofill_feature_quota_exceeded:
$ref: '#/components/examples/AutofillFeatureQuotaExceededError'
schema:
$ref: '#/components/schemas/FeatureQuotaExceededError'
description: Too Many Requests
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthClientCredentials:
- service:design:content:write
- oauthAuthCode:
- design:content:write
tags:
- autofill
x-rate-limit-per-client-user: 60
x-rate-limit-per-client-credential: 100
/v1/autofills/{jobId}:
get:
description: |-
Autofill for designs and brand templates is available when your app acts on behalf of a user on Canva Pro (including Canva Education and Canva for Nonprofits), Canva Teams, or Canva Enterprise. Usage limits will be introduced in the future.
Get the result of a design autofill job that was created using the [Create design autofill job
API](https://www.canva.dev/docs/apps/rest-apis/reference/autofills/create-design-autofill-job/).
You might need to make multiple requests to this endpoint until you get a `success` or `failed` status. For more information on the workflow for using asynchronous jobs, see [API requests and responses](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints).
operationId: getDesignAutofillJob
parameters:
- description: The design autofill job ID.
explode: false
in: path
name: jobId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
responses:
"200":
content:
application/json:
examples:
in_progress:
$ref: '#/components/examples/InProgressAutofillJobExample'
success:
$ref: '#/components/examples/SuccessAutofillJobExample'
failed:
$ref: '#/components/examples/FailedAutofillJobExample'
schema:
$ref: '#/components/schemas/GetDesignAutofillJobResponse'
description: OK
"403":
content:
application/json:
examples:
design_autofill_job_forbidden:
$ref: '#/components/examples/DesignAutofillJobForbiddenError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
design_autofill_job_not_found:
$ref: '#/components/examples/DesignAutofillJobNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthClientCredentials:
- service:design:meta:read
- oauthAuthCode:
- design:meta:read
tags:
- autofill
x-rate-limit-per-client-user: 120
x-rate-limit-per-client-credential: 100
/v1/brand-templates:
get:
description: |-
AVAILABILITY: To use this API, your app must act on behalf of a user that's on a Canva plan with access to brand templates (such as Canva Pro, Canva Teams, or Canva Enterprise).
Get a list of the [brand templates](https://www.canva.com/help/publish-team-template/) the user has access to.
operationId: listBrandTemplates
parameters:
- description: Lets you search the brand templates available to the user using
a search term or terms.
explode: true
in: query
name: query
required: false
schema:
type: string
style: form
- description: |-
If the success response contains a continuation token, the user has access to more
brand templates you can list. You can use this token as a query parameter and retrieve
more templates from the list, for example
`/v1/brand-templates?continuation={continuation}`.
To retrieve all the brand templates available to the user, you might need to make
multiple requests.
explode: true
in: query
name: continuation
required: false
schema:
type: string
style: form
- description: The number of brand templates to return.
explode: true
in: query
name: limit
required: false
schema:
default: 25
format: int32
maximum: 100
minimum: 1
type: integer
style: form
- description: Filter the list of brand templates based on the user's ownership
of the brand templates.
explode: true
in: query
name: ownership
required: false
schema:
$ref: '#/components/schemas/OwnershipType'
style: form
- description: Sort the list of brand templates.
explode: true
in: query
name: sort_by
required: false
schema:
$ref: '#/components/schemas/SortByType'
style: form
- description: |-
Filter the list of brand templates based on the brand templates' dataset definitions.
Brand templates with dataset definitions are mainly used with the [Autofill APIs](https://www.canva.dev/docs/apps/rest-apis/reference/autofills/).
explode: true
in: query
name: dataset
required: false
schema:
$ref: '#/components/schemas/DatasetFilter'
style: form
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/ListBrandTemplatesResponse'
description: OK
"400":
content:
application/json:
examples:
invalid_continuation:
$ref: '#/components/examples/InvalidContinuationError'
design_type_not_available:
$ref: '#/components/examples/DesignTypeNotAvailableError'
unable_to_fetch_designs:
$ref: '#/components/examples/UnableToFetchDesignsError'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
"403":
content:
application/json:
examples:
find_brand_templates_forbidden:
$ref: '#/components/examples/FindBrandTemplatesForbiddenError'
not_allowed_to_access_design_list:
$ref: '#/components/examples/ListDesignsForbiddenError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthClientCredentials:
- service:brandtemplate:meta:read
- oauthAuthCode:
- brandtemplate:meta:read
tags:
- brand_template
x-rate-limit-per-client-user: 100
x-rate-limit-per-client-credential: 100
post:
description: |-
This API is currently provided as a preview. Be aware of the following:
- There might be unannounced breaking changes.
- Any breaking changes to preview APIs won't produce a new [API version](https://www.canva.dev/docs/apps/rest-apis/versions/).
- Public apps that use preview APIs will not pass the review process, and can't be made available to all Canva users.
AVAILABILITY: To use this API, your app must act on behalf of a user that's on a Canva plan with access to brand templates (such as Canva Pro, Canva Teams, or Canva Enterprise). Additionally, the user must have one of the following [roles](https://www.canva.com/help/roles-and-permissions/): Team admin, Brand designer, Organization admin, or Organization designer.
Publishes a design as a [brand template](https://www.canva.com/help/publish-team-template/). Brand templates are design templates that can be shared across a team for consistent content creation.
This API supports two workflows:
- **Initial publish**: If the design is not linked to an existing brand template, a new brand template is created.
- **Republish**: If the design is a draft of an existing brand template (created by editing an existing template), the existing template is updated with the changes.
The API returns the published brand template immediately.
The `thumbnail` field might be `null` immediately after publishing, as thumbnails are generated asynchronously. You can use the [Get brand template API](https://www.canva.dev/docs/apps/rest-apis/reference/brand-templates/get-brand-template/) to retrieve the thumbnail once it's ready. The brand template's `view_url` and `create_url` are available immediately.
operationId: publishBrandTemplate
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PublishBrandTemplateRequest'
required: true
responses:
"200":
content:
application/json:
examples:
success:
$ref: '#/components/examples/PublishBrandTemplateSuccessExample'
schema:
$ref: '#/components/schemas/PublishBrandTemplateResponse'
description: OK
"400":
content:
application/json:
examples:
invalid_design_id:
$ref: '#/components/examples/InvalidDesignIdError'
resource_limit_exceeded:
$ref: '#/components/examples/ResourceLimitExceededError'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request - includes validation errors and other bad request
errors
"403":
content:
application/json:
examples:
publish_permission_denied:
$ref: '#/components/examples/PublishPermissionDeniedError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
publish_brand_template_design_not_found:
$ref: '#/components/examples/PublishBrandTemplateDesignNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthAuthCode:
- brandtemplate:content:write
tags:
- brand_template
x-rate-limit-per-client-user: 20
/v1/brand-templates/{brandTemplateId}:
get:
description: |-
AVAILABILITY: To use this API, your app must act on behalf of a user that's on a Canva plan with access to brand templates (such as Canva Pro, Canva Teams, or Canva Enterprise).
Retrieves the metadata for a brand template.
operationId: getBrandTemplate
parameters:
- description: The brand template ID.
explode: false
in: path
name: brandTemplateId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/GetBrandTemplateResponse'
description: OK
"403":
content:
application/json:
examples:
get_brand_template_permission_denied:
$ref: '#/components/examples/GetBrandTemplatePermissionDeniedError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
get_brand_template_not_found:
$ref: '#/components/examples/GetBrandTemplateNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthClientCredentials:
- service:brandtemplate:meta:read
- oauthAuthCode:
- brandtemplate:meta:read
tags:
- brand_template
x-rate-limit-per-client-user: 100
x-rate-limit-per-client-credential: 100
/v1/brand-templates/{brandTemplateId}/dataset:
get:
description: |-
AVAILABILITY: To use this API, your app must act on behalf of a user that's on a Canva plan with access to brand templates (such as Canva Pro, Canva Teams, or Canva Enterprise).
Gets the dataset definition of a brand template. If the brand
template contains autofill data fields, this API returns an object with the data field
names and the type of data they accept.
To get the dataset definition of a design, use the
[Get design dataset API](https://www.canva.dev/docs/apps/rest-apis/reference/designs/get-design-dataset/).
Available data field types include:
- Images (which you can autofill with an image or a video asset)
- Text
- Charts
- Sheets
You can autofill a brand template using the [Create a design autofill job
API](https://www.canva.dev/docs/apps/rest-apis/reference/autofills/create-design-autofill-job/).
operationId: getBrandTemplateDataset
parameters:
- description: The brand template ID.
explode: false
in: path
name: brandTemplateId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/GetBrandTemplateDatasetResponse'
description: OK
"403":
content:
application/json:
examples:
get_brand_template_dataset_permission_denied:
$ref: '#/components/examples/GetBrandTemplateDatasetPermissionDeniedError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
get_brand_template_dataset_not_found:
$ref: '#/components/examples/GetBrandTemplateDatasetNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthClientCredentials:
- service:brandtemplate:content:read
- oauthAuthCode:
- brandtemplate:content:read
tags:
- brand_template
x-rate-limit-per-client-user: 100
x-rate-limit-per-client-credential: 100
/v1/comments:
post:
deprecated: true
description: |-
This preview API is deprecated. You should use the [Create thread](https://www.canva.dev/docs/apps/rest-apis/reference/comments/create-thread/) API instead.
Create a new top-level comment on a design.
For information on comments and how they're used in the Canva UI, see the
[Canva Help Center](https://www.canva.com/help/comments/). A design can have a maximum
of 1000 comments.
operationId: createComment
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCommentRequest'
required: true
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCommentResponse'
description: OK
"400":
content:
application/json:
examples:
assignee_not_mentioned:
$ref: '#/components/examples/AssigneeNotMentionedError'
message_too_long:
$ref: '#/components/examples/MessageTooLongError'
invalid_mention_ids:
$ref: '#/components/examples/InvalidMentionIdsError'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
"403":
content:
application/json:
examples:
too_many_comments:
$ref: '#/components/examples/TooManyCommentsError'
not_allowed_to_comment:
$ref: '#/components/examples/NotAllowedToCommentError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
design_not_found:
$ref: '#/components/examples/DesignNotFoundError'
mentioned_user_not_found:
$ref: '#/components/examples/MentionedUserNotFoundError'
mentioned_team_not_found:
$ref: '#/components/examples/MentionedTeamNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthAuthCode:
- comment:write
tags:
- comment
x-rate-limit-per-client-user: 20
/v1/designs/{designId}/comments/{threadId}/replies:
get:
description: |-
This API is currently provided as a preview. Be aware of the following:
- There might be unannounced breaking changes.
- Any breaking changes to preview APIs won't produce a new [API version](https://www.canva.dev/docs/apps/rest-apis/versions/).
- Public apps that use preview APIs will not pass the review process, and can't be made available to all Canva users.
Retrieves a list of replies for a comment or suggestion thread on a design.
For information on comments and how they're used in the Canva UI, see the
[Canva Help Center](https://www.canva.com/help/comments/).
operationId: listReplies
parameters:
- description: The design ID.
explode: false
in: path
name: designId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
- description: The ID of the thread.
example: KeAbiEAjZEj
explode: false
in: path
name: threadId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
- explode: true
in: query
name: limit
required: false
schema:
default: 50
description: The number of replies to return.
format: int32
maximum: 100
minimum: 1
type: integer
style: form
- description: |-
If the success response contains a continuation token, the list contains more items you can list. You can use this token as a query parameter and retrieve more items from the list, for example `?continuation={continuation}`.
To retrieve all items, you might need to make multiple requests.
explode: true
in: query
name: continuation
required: false
schema:
type: string
style: form
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/ListRepliesResponse'
description: OK
"403":
content:
application/json:
examples:
not_allowed_to_fetch_replies:
$ref: '#/components/examples/NotAllowedToFetchRepliesError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
design_or_thread_not_found:
$ref: '#/components/examples/DesignOrThreadNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthAuthCode:
- comment:read
tags:
- comment
x-rate-limit-per-client-user: 100
post:
description: |-
This API is currently provided as a preview. Be aware of the following:
- There might be unannounced breaking changes.
- Any breaking changes to preview APIs won't produce a new [API version](https://www.canva.dev/docs/apps/rest-apis/versions/).
- Public apps that use preview APIs will not pass the review process, and can't be made available to all Canva users.
Creates a reply to a comment or suggestion thread on a design.
To reply to an existing thread, you must provide the ID of the thread
which is returned when a thread is created, or from the `thread_id` value
of an existing reply in the thread. Each thread can
have a maximum of 100 replies created for it.
For information on comments and how they're used in the Canva UI, see the
[Canva Help Center](https://www.canva.com/help/comments/).
operationId: createReply
parameters:
- description: The design ID.
explode: false
in: path
name: designId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
- description: The ID of the thread.
example: KeAbiEAjZEj
explode: false
in: path
name: threadId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateReplyV2Request'
required: true
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/CreateReplyV2Response'
description: OK
"400":
content:
application/json:
examples:
message_too_long:
$ref: '#/components/examples/MessageTooLongError'
invalid_mention_ids:
$ref: '#/components/examples/InvalidMentionIdsError'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
"403":
content:
application/json:
examples:
too_many_replies:
$ref: '#/components/examples/TooManyRepliesError'
not_allowed_to_reply:
$ref: '#/components/examples/NotAllowedToReplyError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
design_or_comment_not_found:
$ref: '#/components/examples/DesignOrCommentNotFoundForReplyError'
mentioned_user_not_found:
$ref: '#/components/examples/MentionedUserNotFoundError'
mentioned_team_not_found:
$ref: '#/components/examples/MentionedTeamNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthAuthCode:
- comment:write
tags:
- comment
x-rate-limit-per-client-user: 20
/v1/designs/{designId}/comments/{threadId}:
get:
description: |-
This API is currently provided as a preview. Be aware of the following:
- There might be unannounced breaking changes.
- Any breaking changes to preview APIs won't produce a new [API version](https://www.canva.dev/docs/apps/rest-apis/versions/).
- Public apps that use preview APIs will not pass the review process, and can't be made available to all Canva users.
Gets a comment or suggestion thread on a design.
To retrieve a reply to a comment thread, use the [Get reply](https://www.canva.dev/docs/apps/rest-apis/reference/comments/get-reply/) API.
For information on comments and how they're used in the Canva UI, see the
[Canva Help Center](https://www.canva.com/help/comments/).
operationId: getThread
parameters:
- description: The design ID.
explode: false
in: path
name: designId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
- description: The ID of the thread.
example: KeAbiEAjZEj
explode: false
in: path
name: threadId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/GetThreadResponse'
description: OK
"403":
content:
application/json:
examples:
not_allowed_to_fetch_comment:
$ref: '#/components/examples/NotAllowedToFetchCommentError'
not_allowed_to_fetch_suggestion:
$ref: '#/components/examples/NotAllowedToFetchSuggestionError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
thread_not_found:
$ref: '#/components/examples/ThreadNotFoundError'
thread_not_attached_to_design:
$ref: '#/components/examples/ThreadNotAttachedToDesignError'
suggestion_not_found:
$ref: '#/components/examples/SuggestionNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthAuthCode:
- comment:read
tags:
- comment
x-rate-limit-per-client-user: 100
/v1/designs/{designId}/comments/{threadId}/replies/{replyId}:
get:
description: |-
This API is currently provided as a preview. Be aware of the following:
- There might be unannounced breaking changes.
- Any breaking changes to preview APIs won't produce a new [API version](https://www.canva.dev/docs/apps/rest-apis/versions/).
- Public apps that use preview APIs will not pass the review process, and can't be made available to all Canva users.
Gets a reply to a comment or suggestion thread on a design.
For information on comments and how they're used in the Canva UI, see the
[Canva Help Center](https://www.canva.com/help/comments/).
operationId: getReply
parameters:
- description: The design ID.
explode: false
in: path
name: designId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
- description: The ID of the thread.
example: KeAbiEAjZEj
explode: false
in: path
name: threadId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
- description: The ID of the reply.
example: KeAZEAjijEb
explode: false
in: path
name: replyId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/GetReplyResponse'
description: OK
"403":
content:
application/json:
examples:
not_allowed_to_fetch_reply:
$ref: '#/components/examples/NotAllowedToFetchReplyError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
reply_not_found:
$ref: '#/components/examples/ReplyNotFoundError'
suggestion_reply_not_found:
$ref: '#/components/examples/SuggestionReplyNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthAuthCode:
- comment:read
tags:
- comment
x-rate-limit-per-client-user: 100
/v1/designs/{designId}/comments:
post:
description: |-
This API is currently provided as a preview. Be aware of the following:
- There might be unannounced breaking changes.
- Any breaking changes to preview APIs won't produce a new [API version](https://www.canva.dev/docs/apps/rest-apis/versions/).
- Public apps that use preview APIs will not pass the review process, and can't be made available to all Canva users.
Creates a new comment thread on a design.
For information on comments and how they're used in the Canva UI, see the
[Canva Help Center](https://www.canva.com/help/comments/).
operationId: createThread
parameters:
- description: The design ID.
explode: false
in: path
name: designId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateThreadRequest'
required: true
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/CreateThreadResponse'
description: OK
"400":
content:
application/json:
examples:
assignee_not_mentioned:
$ref: '#/components/examples/AssigneeNotMentionedError'
message_too_long:
$ref: '#/components/examples/MessageTooLongError'
invalid_mention_ids:
$ref: '#/components/examples/InvalidMentionIdsError'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
"403":
content:
application/json:
examples:
too_many_comments:
$ref: '#/components/examples/TooManyCommentsError'
not_allowed_to_comment:
$ref: '#/components/examples/NotAllowedToCommentError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
design_not_found:
$ref: '#/components/examples/DesignNotFoundError'
mentioned_user_not_found:
$ref: '#/components/examples/MentionedUserNotFoundError'
mentioned_team_not_found:
$ref: '#/components/examples/MentionedTeamNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthAuthCode:
- comment:write
tags:
- comment
x-rate-limit-per-client-user: 100
/v1/connect/keys:
get:
description: |-
This API is currently provided as a preview. Be aware of the following:
- There might be unannounced breaking changes.
- Any breaking changes to preview APIs won't produce a new [API version](https://www.canva.dev/docs/apps/rest-apis/versions/).
- Public apps that use preview APIs will not pass the review process, and can't be made available to all Canva users.
The Keys API (`connect/keys`) is a security measure you can use to verify the authenticity
of webhooks you receive from the Canva REST APIs. The Keys API returns a
[JSON Web Key (JWK)](https://www.rfc-editor.org/rfc/rfc7517#section-2), which you can use to
decrypt the webhook signature and verify it came from Canva and not a potentially malicious
actor. This helps to protect your systems from
[Replay attacks](https://owasp.org/Top10/A08_2021-Software_and_Data_Integrity_Failures/).
The keys returned by the Keys API can rotate. We recommend you cache the keys you receive
from this API where possible, and only access this API when you receive a webhook signed
with an unrecognized key. This allows you to verify webhooks quicker than accessing this API
every time you receive a webhook.
operationId: getSigningPublicKeys
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/GetSigningPublicKeysResponse'
description: OK
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
tags:
- connect
/v1/designs:
get:
description: |-
Lists metadata for all the designs in a Canva user's
[projects](https://www.canva.com/help/find-designs-and-folders/). You can also:
- Use search terms to filter the listed designs.
- Show designs either created by, or shared with the user.
- Sort the results.
operationId: listDesigns
parameters:
- description: "Lets you search the user's designs, and designs shared with\
\ the user, using a search term or terms."
example: party invites
explode: true
in: query
name: query
required: false
schema:
maxLength: 255
type: string
style: form
- description: |-
If the success response contains a continuation token, the list contains more designs
you can list. You can use this token as a query parameter and retrieve more
designs from the list, for example
`/v1/designs?continuation={continuation}`.
To retrieve all of a user's designs, you might need to make multiple requests.
example: RkFGMgXlsVTDbMd:MR3L0QjiaUzycIAjx0yMyuNiV0OildoiOwL0x32G4NjNu4FwtAQNxowUQNMMYN
explode: true
in: query
name: continuation
required: false
schema:
type: string
style: form
- description: Filter the list of designs based on the user's ownership of the
designs.
example: any
explode: true
in: query
name: ownership
required: false
schema:
$ref: '#/components/schemas/OwnershipType'
style: form
- description: Sort the list of designs.
example: relevance
explode: true
in: query
name: sort_by
required: false
schema:
$ref: '#/components/schemas/SortByType'
style: form
- description: The number of designs to return.
explode: true
in: query
name: limit
required: false
schema:
default: 25
format: int32
maximum: 100
minimum: 1
type: integer
style: form
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/GetListDesignResponse'
description: OK
"400":
content:
application/json:
examples:
invalid_continuation:
$ref: '#/components/examples/InvalidContinuationError'
invalid_ownership:
$ref: '#/components/examples/InvalidOwnershipError'
invalid_sort_by:
$ref: '#/components/examples/InvalidSortByError'
design_type_not_available:
$ref: '#/components/examples/DesignTypeNotAvailableError'
unable_to_fetch_designs:
$ref: '#/components/examples/UnableToFetchDesignsError'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
"403":
content:
application/json:
examples:
not_allowed_to_access_design_list:
$ref: '#/components/examples/ListDesignsForbiddenError'
find_documents_forbidden:
$ref: '#/components/examples/FindDocumentsForbiddenError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthAuthCode:
- design:meta:read
tags:
- design
x-rate-limit-per-client-user: 100
post:
description: |-
Creates a new Canva design. To create a new design, you can:
- Use a preset design type.
- Set height and width dimensions for a custom design.
NOTE: Custom designs can have a maximum area of 25,000,000 pixels squared (for example, 5000 × 5000 pixels). Each dimension can be between 40 and 8000 pixels, but the total area must stay within this limit.
- Create a copy of an existing design (currently a [preview feature](https://www.canva.dev/docs/apps/rest-apis/#preview-apis)).
- Create a new design from a brand template (currently a [preview feature](https://www.canva.dev/docs/apps/rest-apis/#preview-apis)).
For preset and custom designs, you can also provide the `asset_id` of an asset in the user's [projects](https://www.canva.com/help/find-designs-and-folders/) to add to the new design. Currently, this only supports image assets. To list the assets in a folder in the user's projects, use the [List folder items API](https://www.canva.dev/docs/apps/rest-apis/reference/folders/list-folder-items/).
An asset provided this way is placed in the design as a single flat image, which the user can move, resize, or replace, but not edit as separate elements. If you want the elements of an image to become separate editable layers in the design, use the [Create image-to-design import job API](https://www.canva.dev/docs/apps/rest-apis/reference/design-imports/create-image-to-design-import-job/) instead.
NOTE: Blank designs created with this API are automatically deleted if they're not edited within 7 days. These blank designs bypass the user's Canva trash and are permanently deleted.
operationId: createDesign
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDesignRequest'
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDesignResponse'
description: OK
"400":
content:
application/json:
examples:
invalid_design_type:
$ref: '#/components/examples/InvalidDesignTypeError'
missing_design_type_or_asset_id:
$ref: '#/components/examples/MissingDesignTypeOrAssetIdError'
blank_design_id:
$ref: '#/components/examples/BlankDesignIdError'
blank_brand_template_id:
$ref: '#/components/examples/BlankBrandTemplateIdError'
asset_id_not_image:
$ref: '#/components/examples/AssetIdNotImageError'
invalid_design_dimensions:
$ref: '#/components/examples/InvalidDesignDimensionsError'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
"403":
content:
application/json:
examples:
asset_access_not_allowed:
$ref: '#/components/examples/AssetAccessNotAllowedError'
get_design_dataset_permission_denied:
$ref: '#/components/examples/GetDesignDatasetPermissionDeniedError'
create_design_brand_template_access_denied:
$ref: '#/components/examples/CreateDesignBrandTemplateAccessDeniedError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
create_design_not_found:
$ref: '#/components/examples/CreateDesignNotFoundError'
create_brand_template_not_found:
$ref: '#/components/examples/CreateBrandTemplateNotFoundError'
asset_not_found:
$ref: '#/components/examples/AssetNotFoundError'
design_id_not_found:
$ref: '#/components/examples/DesignIdNotFoundError'
ref_design_type_not_found:
$ref: '#/components/examples/RefDesignTypeNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
"429":
content:
application/json:
examples:
design_creation_throttled:
$ref: '#/components/examples/CreateDesignThrottledError'
schema:
$ref: '#/components/schemas/Error'
description: Too Many Requests
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthAuthCode:
- design:content:write
tags:
- design
x-rate-limit-per-client-user: 20
/v1/designs/{designId}:
get:
description: "Gets the metadata for a design. This includes owner information,\
\ URLs for editing and viewing, and thumbnail information."
operationId: getDesign
parameters:
- description: The design ID.
explode: false
in: path
name: designId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/GetDesignResponse'
description: OK
"403":
content:
application/json:
examples:
design_access_forbidden:
$ref: '#/components/examples/DesignAccessForbiddenError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
design_id_not_found:
$ref: '#/components/examples/DesignIdNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthAuthCode:
- design:meta:read
tags:
- design
x-rate-limit-per-client-user: 100
/v1/designs/{designId}/pages:
get:
description: |-
This API is currently provided as a preview. Be aware of the following:
- There might be unannounced breaking changes.
- Any breaking changes to preview APIs won't produce a new [API version](https://www.canva.dev/docs/apps/rest-apis/versions/).
- Public apps that use preview APIs will not pass the review process, and can't be made available to all Canva users.
Lists metadata for pages in a design, such as page-specific thumbnails.
For the specified design, you can provide `offset` and `limit` values to specify the range of pages to return.
NOTE: Some design types don't have pages (for example, Canva docs).
operationId: getDesignPages
parameters:
- description: The design ID.
explode: false
in: path
name: designId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
- description: |
The page index to start the range of pages to return.
Pages are indexed using one-based numbering, so the first page in a design has the index value `1`.
explode: true
in: query
name: offset
required: false
schema:
default: 1
format: int32
maximum: 500
minimum: 1
type: integer
style: form
- description: "The number of pages to return, starting at the page index specified\
\ using the `offset` parameter."
explode: true
in: query
name: limit
required: false
schema:
default: 50
format: int32
maximum: 200
minimum: 1
type: integer
style: form
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/GetDesignPagesResponse'
description: OK
"400":
content:
application/json:
examples:
design_has_no_pages:
$ref: '#/components/examples/DesignHasNoPagesError'
offset_too_large:
$ref: '#/components/examples/DesignPagesOffsetTooLargeError'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
"403":
content:
application/json:
examples:
design_access_forbidden:
$ref: '#/components/examples/DesignAccessForbiddenError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
design_id_not_found:
$ref: '#/components/examples/DesignIdNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthAuthCode:
- design:content:read
tags:
- design
x-rate-limit-per-client-user: 100
/v1/designs/{designId}/export-formats:
get:
description: |-
Lists the available file formats for [exporting a design](https://www.canva.dev/docs/apps/rest-apis/reference/exports/create-design-export-job/).
The available export formats depend on the design type and the types of pages in the design.
Each format includes the page numbers that support it. If a format is supported by every page in the design, its `page_numbers` are omitted.
operationId: getDesignExportFormats
parameters:
- description: The design ID.
explode: false
in: path
name: designId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/GetDesignExportFormatsResponse'
description: OK
"403":
content:
application/json:
examples:
design_access_denied:
$ref: '#/components/examples/DesignAccessDeniedError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
design_id_not_found:
$ref: '#/components/examples/DesignIdNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthClientCredentials:
- service:design:content:read
- oauthAuthCode:
- design:content:read
tags:
- design
x-rate-limit-per-client-user: 100
x-rate-limit-per-client-credential: 100
/v1/designs/{designId}/dataset:
get:
description: |-
Gets the dataset definition of a design. If the design contains autofill data fields, this API
returns an object with the data field names and the type of data they accept.
To get the dataset definition of a brand template, use the
[Get brand template dataset API](https://www.canva.dev/docs/apps/rest-apis/reference/brand-templates/get-brand-template-dataset/).
Available data field types include:
- Images (which you can autofill with an image or a video asset)
- Text
- Charts
- Sheets
Use the returned field names and types to build the `data` payload for the
[Create a design autofill job API](https://www.canva.dev/docs/apps/rest-apis/reference/autofills/create-design-autofill-job/)
with `type: create_from_design`.
operationId: getDesignDataset
parameters:
- description: The design ID.
explode: false
in: path
name: designId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/GetDesignDatasetResponse'
description: OK
"403":
content:
application/json:
examples:
get_design_dataset_permission_denied:
$ref: '#/components/examples/GetDesignDatasetPermissionDeniedError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
get_design_dataset_not_found:
$ref: '#/components/examples/GetDesignDatasetDesignNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthClientCredentials:
- service:design:content:read
- oauthAuthCode:
- design:content:read
tags:
- design
x-rate-limit-per-client-user: 100
x-rate-limit-per-client-credential: 100
/v1/print-partner/designs:
post:
description: |-
This API is currently provided as a preview. Be aware of the following:
- There might be unannounced breaking changes.
- Any breaking changes to preview APIs won't produce a new [API version](https://www.canva.dev/docs/apps/rest-apis/versions/).
- Public apps that use preview APIs will not pass the review process, and can't be made available to all Canva users.
AVAILABILITY: This API is only available to Print Partners.
Creates a new Canva design using a Print Partner product ID.
Print partner proofing information (such as bleed and page constraints) can optionally be provided in the request. The design URLs that are returned include this information, which Canva applies in the editor when opening the design.
NOTE: Blank designs created with this API are automatically deleted if they're not edited within 7 days. These blank designs bypass the user's Canva trash and are permanently deleted.
operationId: createPrintPartnerDesign
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePrintPartnerDesignRequest'
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePrintPartnerDesignResponse'
description: OK
"400":
content:
application/json:
examples:
invalid_design_dimensions:
$ref: '#/components/examples/InvalidDesignDimensionsError'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
"403":
content:
application/json:
examples:
create_print_partner_design_forbidden:
$ref: '#/components/examples/CreatePrintPartnerDesignForbiddenError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
product_size_not_found:
$ref: '#/components/examples/ProductSizeNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
"429":
content:
application/json:
examples:
design_creation_throttled:
$ref: '#/components/examples/CreateDesignThrottledError'
schema:
$ref: '#/components/schemas/Error'
description: Too Many Requests
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthAuthCode:
- design:content:write
tags:
- design
x-rate-limit-per-client-user: 20
/v1/print-partner/designs/{designId}:
get:
description: |-
This API is currently provided as a preview. Be aware of the following:
- There might be unannounced breaking changes.
- Any breaking changes to preview APIs won't produce a new [API version](https://www.canva.dev/docs/apps/rest-apis/versions/).
- Public apps that use preview APIs will not pass the review process, and can't be made available to all Canva users.
AVAILABILITY: This API is only available to Print Partners.
Gets the metadata for a design. This includes owner information, URLs for editing and viewing, and thumbnail information.
Print partner proofing information (such as bleed and page constraints) isn't stored on Canva, so you can optionally provide it in the request. The design URLs that are returned include this information, which Canva applies in the editor when opening the design.
operationId: getPrintPartnerDesign
parameters:
- description: The design ID.
explode: false
in: path
name: designId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
- description: |-
Bleed in microns to apply around the design in the editor. Bleed is the area
outside the trim line used to avoid white edges after cutting. Use 0 for no bleed. If bleed is not
specified, a default of 3000 microns is used.
explode: true
in: query
name: bleed
required: false
schema:
default: 3000
format: int32
maximum: 150000
minimum: 0
type: integer
style: form
- description: |-
Minimum number of pages the design must have in the editor. The user cannot
reduce the page count below this value. If both min_pages and max_pages are
provided, min_pages must be less than or equal to max_pages.
explode: true
in: query
name: min_pages
required: false
schema:
format: int32
maximum: 500
minimum: 1
type: integer
style: form
- description: |-
Maximum number of pages the design can have in the editor. The user cannot
add pages beyond this value. If both min_pages and max_pages are provided,
min_pages must be less than or equal to max_pages.
explode: true
in: query
name: max_pages
required: false
schema:
format: int32
maximum: 500
minimum: 1
type: integer
style: form
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/GetPrintPartnerDesignResponse'
description: OK
"403":
content:
application/json:
examples:
get_print_partner_design_forbidden:
$ref: '#/components/examples/GetPrintPartnerDesignForbiddenError'
design_access_forbidden:
$ref: '#/components/examples/DesignAccessForbiddenError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
design_id_not_found:
$ref: '#/components/examples/DesignIdNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthAuthCode:
- design:meta:read
tags:
- design
x-rate-limit-per-client-user: 100
/v1/generations:
post:
description: |-
This API is currently provided as a preview. Be aware of the following:
- There might be unannounced breaking changes.
- Any breaking changes to preview APIs won't produce a new [API version](https://www.canva.dev/docs/apps/rest-apis/versions/).
- Public integrations that use preview APIs will not pass the review process, and can't be made available to all Canva users.
Starts a new [asynchronous job](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints) to generate a Canva design from a text brief. A successful job includes metadata for the generated design, which is saved to the user's Canva account.
You can generate a document or presentation. For presentations, you can also provide an outline of the slides to generate.
Requires the `design_generation` capability. You can check whether the user has this capability using the [Get user capabilities API](https://www.canva.dev/docs/apps/rest-apis/reference/users/get-user-capabilities/).
Starting a job consumes the user's [AI credit allowance](https://www.canva.com/help/ai-access/). If the user has reached their AI allowance limit, the request returns a `402` error with the `credit_quota_exceeded` code. Polling for the result of a job doesn't consume any of the allowance.
For more information on the workflow for using asynchronous jobs, see [API requests and responses](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints). You can check the status and get the results of jobs created with this API using the [Get design generation job API](https://www.canva.dev/docs/apps/rest-apis/reference/generations/get-design-generation-job/).
operationId: createDesignGenerationJobV2
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDesignGenerationJobRequestV2'
required: true
responses:
"200":
content:
application/json:
examples:
accepted:
$ref: '#/components/examples/AcceptedDesignGenerationJobExampleV2'
schema:
$ref: '#/components/schemas/CreateDesignGenerationJobResponseV2'
description: OK
"400":
content:
application/json:
examples:
design_generation_invalid_request_v2:
$ref: '#/components/examples/InvalidDesignGenerationRequestErrorV2'
design_generation_invalid_attachment_v2:
$ref: '#/components/examples/InvalidDesignGenerationInputErrorV2'
design_generation_too_many_inputs_v2:
$ref: '#/components/examples/TooManyDesignGenerationInputsErrorV2'
design_generation_unsupported_type_v2:
$ref: '#/components/examples/UnsupportedDesignGenerationTypeErrorV2'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
"401":
content:
application/json:
examples:
InvalidClientError:
$ref: '#/components/examples/InvalidClientError'
InvalidAccessToken:
$ref: '#/components/examples/InvalidAccessToken'
MissingClientCredentialsOrBodyAuthError:
$ref: '#/components/examples/MissingClientCredentialsOrBodyAuthError'
MalformedAuthorizationHeaderComponents:
$ref: '#/components/examples/MalformedAuthorizationHeaderComponents'
MalformedAuthorizationHeaderMode:
$ref: '#/components/examples/MalformedAuthorizationHeaderMode'
TokenIntrospectionFailed:
$ref: '#/components/examples/TokenIntrospectionFailed'
RevokedAccessToken:
$ref: '#/components/examples/RevokedAccessToken'
MissingAuthorizationHeader:
$ref: '#/components/examples/MissingAuthorizationHeader'
MalformedAuthorizationHeader:
$ref: '#/components/examples/MalformedAuthorizationHeader'
schema:
$ref: '#/components/schemas/Error'
description: Unauthorized
x-http-status-code: 401
"402":
content:
application/json:
examples:
user_payment_required:
$ref: '#/components/examples/UserPaymentRequiredError'
app_payment_required:
$ref: '#/components/examples/AppPaymentRequiredError'
schema:
$ref: '#/components/schemas/Error'
description: Payment Required
x-http-status-code: 402
"403":
content:
application/json:
examples:
design_generation_generation_not_available_v2:
$ref: '#/components/examples/DesignGenerationNotAvailableErrorV2'
design_generation_attachment_forbidden_v2:
$ref: '#/components/examples/DesignGenerationInputForbiddenErrorV2'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
design_generation_attachment_not_found_v2:
$ref: '#/components/examples/DesignGenerationInputNotFoundErrorV2'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthClientCredentials:
- service:design:content:write
- oauthAuthCode:
- design:content:write
tags:
- design_generation
x-rate-limit-per-client-user: 20
x-rate-limit-per-client-credential: 100
x-required-capabilities:
- design_generation
/v1/generations/{jobId}:
get:
description: |-
This API is currently provided as a preview. Be aware of the following:
- There might be unannounced breaking changes.
- Any breaking changes to preview APIs won't produce a new [API version](https://www.canva.dev/docs/apps/rest-apis/versions/).
- Public integrations that use preview APIs will not pass the review process, and can't be made available to all Canva users.
Gets the status and result of a design generation job created using the [Create design generation job API](https://www.canva.dev/docs/apps/rest-apis/reference/generations/create-design-generation-job/).
You might need to make multiple requests until the job has a `success` or `failed` status. For more information on the workflow for using asynchronous jobs, see [API requests and responses](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints).
Only the user and integration that created the job can retrieve it, and the user must be in the same team. Jobs expire 24 hours after creation.
Polling doesn't consume the user's [AI credit allowance](https://www.canva.com/help/ai-access/). Reaching the AI allowance limit after job creation doesn't prevent retrieving the result.
Requires the `design_generation` capability.
operationId: getDesignGenerationJobV2
parameters:
- description: The public design generation job ID.
explode: false
in: path
name: jobId
required: true
schema:
example: f81b26fd-a33d-4c2d-9e8c-4a7aca798b17
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
responses:
"200":
content:
application/json:
examples:
in_progress:
$ref: '#/components/examples/InProgressDesignGenerationJobExampleV2'
success:
$ref: '#/components/examples/SuccessDesignGenerationJobExampleV2'
content_not_allowed:
$ref: '#/components/examples/ContentNotAllowedDesignGenerationJobExampleV2'
failed:
$ref: '#/components/examples/FailedDesignGenerationJobExampleV2'
schema:
$ref: '#/components/schemas/GetDesignGenerationJobResponseV2'
description: OK
"400":
content:
application/json:
examples:
design_generation_invalid_job_id_v2:
$ref: '#/components/examples/InvalidDesignGenerationJobIdErrorV2'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
"401":
content:
application/json:
examples:
InvalidClientError:
$ref: '#/components/examples/InvalidClientError'
InvalidAccessToken:
$ref: '#/components/examples/InvalidAccessToken'
MissingClientCredentialsOrBodyAuthError:
$ref: '#/components/examples/MissingClientCredentialsOrBodyAuthError'
MalformedAuthorizationHeaderComponents:
$ref: '#/components/examples/MalformedAuthorizationHeaderComponents'
MalformedAuthorizationHeaderMode:
$ref: '#/components/examples/MalformedAuthorizationHeaderMode'
TokenIntrospectionFailed:
$ref: '#/components/examples/TokenIntrospectionFailed'
RevokedAccessToken:
$ref: '#/components/examples/RevokedAccessToken'
MissingAuthorizationHeader:
$ref: '#/components/examples/MissingAuthorizationHeader'
MalformedAuthorizationHeader:
$ref: '#/components/examples/MalformedAuthorizationHeader'
schema:
$ref: '#/components/schemas/Error'
description: Unauthorized
x-http-status-code: 401
"403":
content:
application/json:
examples:
design_generation_generation_not_available_v2:
$ref: '#/components/examples/DesignGenerationNotAvailableErrorV2'
design_generation_job_forbidden_v2:
$ref: '#/components/examples/DesignGenerationJobForbiddenErrorV2'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
design_generation_job_not_found_v2:
$ref: '#/components/examples/DesignGenerationJobNotFoundErrorV2'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
"429":
content:
application/json:
examples:
TooManyRequestsError:
$ref: '#/components/examples/TooManyRequestsError'
ThrottledTooManyRequests:
$ref: '#/components/examples/ThrottledTooManyRequests'
schema:
$ref: '#/components/schemas/Error'
description: Too Many Requests
x-http-status-code: 429
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthClientCredentials:
- service:design:content:write
- oauthAuthCode:
- design:content:write
tags:
- design_generation
x-rate-limit-per-client-user: 120
x-rate-limit-per-client-credential: 100
x-required-capabilities:
- design_generation
/v1/imports:
post:
description: |-
Starts a new [asynchronous job](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints) to import an external file as a new design in Canva.
The request format for this endpoint has an `application/octet-stream` body of bytes,
and the information about the import is provided using an `Import-Metadata` header.
Supported file types for imports are listed in [Design imports overview](https://www.canva.dev/docs/apps/rest-apis/reference/design-imports/#supported-file-types).
For more information on the workflow for using asynchronous jobs, see [API requests and responses](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints). You can check the status and get the results of design import jobs created with this API using the [Get design import job API](https://www.canva.dev/docs/apps/rest-apis/reference/design-imports/get-design-import-job/).
operationId: createDesignImportJob
parameters:
- content:
application/json:
schema:
$ref: '#/components/schemas/DesignImportMetadata'
in: header
name: Import-Metadata
required: true
requestBody:
content:
application/octet-stream:
schema:
format: binary
type: string
description: Binary of the file to import.
required: true
responses:
"200":
content:
application/json:
examples:
in_progress:
$ref: '#/components/examples/InProgressDesignImportJobExample'
success:
$ref: '#/components/examples/SuccessDesignImportJobExample'
failed:
$ref: '#/components/examples/FailedDesignImportJobExample'
schema:
$ref: '#/components/schemas/CreateDesignImportJobResponse'
description: OK
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthClientCredentials:
- service:design:content:write
- oauthAuthCode:
- design:content:write
tags:
- design_import
x-rate-limit-per-client-user: 20
x-rate-limit-per-client-credential: 100
/v1/imports/{jobId}:
get:
description: |-
Gets the result of a design import job created using the [Create design import job API](https://www.canva.dev/docs/apps/rest-apis/reference/design-imports/create-design-import-job/).
You might need to make multiple requests to this endpoint until you get a `success` or `failed` status. For more information on the workflow for using asynchronous jobs, see [API requests and responses](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints).
operationId: getDesignImportJob
parameters:
- description: The design import job ID.
example: f81b26fd-a33d-4c2d-9e8c-4a7aca798b17
explode: false
in: path
name: jobId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
responses:
"200":
content:
application/json:
examples:
in_progress:
$ref: '#/components/examples/InProgressDesignImportJobExample'
success:
$ref: '#/components/examples/SuccessDesignImportJobExample'
failed:
$ref: '#/components/examples/FailedDesignImportJobExample'
schema:
$ref: '#/components/schemas/GetDesignImportJobResponse'
description: OK
"400":
content:
application/json:
examples:
job_id_invalid:
$ref: '#/components/examples/JobIdInvalidError'
job_not_created_via_connect_api:
$ref: '#/components/examples/JobNotCreatedViaConnectApiError'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
"403":
content:
application/json:
examples:
design_import_job_not_creator:
$ref: '#/components/examples/DesignImportJobNotCreatorError'
get_job_status_not_allowed:
$ref: '#/components/examples/GetJobStatusNotAllowedError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
job_id_not_found:
$ref: '#/components/examples/JobIdNotFoundError'
job_not_found:
$ref: '#/components/examples/JobNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthClientCredentials:
- service:design:content:write
- oauthAuthCode:
- design:content:write
tags:
- design_import
x-rate-limit-per-client-user: 120
x-rate-limit-per-client-credential: 100
/v1/url-imports:
post:
description: |-
Starts a new [asynchronous job](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints) to import an external file from a URL as a new design in Canva.
Supported file types for imports are listed in [Design imports overview](https://www.canva.dev/docs/apps/rest-apis/reference/design-imports/#supported-file-types).
For more information on the workflow for using asynchronous jobs, see [API requests and responses](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints). You can check the status and get the results of design import jobs created with this API using the [Get URL import job API](https://www.canva.dev/docs/apps/rest-apis/reference/design-imports/get-url-import-job/).
operationId: createUrlImportJob
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUrlImportJobRequest'
required: true
responses:
"200":
content:
application/json:
examples:
in_progress:
$ref: '#/components/examples/InProgressDesignImportJobExample'
success:
$ref: '#/components/examples/SuccessDesignImportJobExample'
failed:
$ref: '#/components/examples/FailedDesignImportJobExample'
schema:
$ref: '#/components/schemas/CreateUrlImportJobResponse'
description: OK
"400":
content:
application/json:
examples:
design_import_already_in_progress:
$ref: '#/components/examples/DesignImportAlreadyInProgressError'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
"404":
content:
application/json:
examples:
job_with_id_not_found:
$ref: '#/components/examples/JobWithIdNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthClientCredentials:
- service:design:content:write
- oauthAuthCode:
- design:content:write
tags:
- design_import
x-rate-limit-per-client-user: 20
x-rate-limit-per-client-credential: 100
/v1/url-imports/{jobId}:
get:
description: |-
Gets the result of a URL import job created using the [Create URL import job API](https://www.canva.dev/docs/apps/rest-apis/reference/design-imports/create-url-import-job/).
You might need to make multiple requests to this endpoint until you get a `success` or `failed` status. For more information on the workflow for using asynchronous jobs, see [API requests and responses](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints).
operationId: getUrlImportJob
parameters:
- description: The ID of the URL import job.
example: f81b26fd-a33d-4c2d-9e8c-4a7aca798b17
explode: false
in: path
name: jobId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
responses:
"200":
content:
application/json:
examples:
in_progress:
$ref: '#/components/examples/InProgressDesignImportJobExample'
success:
$ref: '#/components/examples/SuccessDesignImportJobExample'
failed:
$ref: '#/components/examples/FailedDesignImportJobExample'
schema:
$ref: '#/components/schemas/GetUrlImportJobResponse'
description: OK
"400":
content:
application/json:
examples:
job_not_created_via_connect_api:
$ref: '#/components/examples/JobNotCreatedViaConnectApiError'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
"403":
content:
application/json:
examples:
get_job_status_not_allowed:
$ref: '#/components/examples/GetJobStatusNotAllowedError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
job_not_found:
$ref: '#/components/examples/JobNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthClientCredentials:
- service:design:content:write
- oauthAuthCode:
- design:content:write
tags:
- design_import
x-rate-limit-per-client-user: 120
x-rate-limit-per-client-credential: 100
/v1/image-to-design-imports:
post:
description: |-
This API is currently provided as a preview. Be aware of the following:
- There might be unannounced breaking changes.
- Any breaking changes to preview APIs won't produce a new [API version](https://www.canva.dev/docs/apps/rest-apis/versions/).
- Public integrations that use preview APIs will not pass the review process, and can't be made available to all Canva users.
Starts a new [asynchronous job](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints) to convert an image into an editable design in Canva, using [Magic Layers](https://www.canva.com/magic-layers/). Elements in the image become separate editable layers in the resulting design.
Provide the image as an asset that is already in the user's Canva account.
The image must be a standard photo or graphic file, such as a PNG or JPEG. Vector-based formats such as SVG, EPS, or AI files, are not supported. Video assets are not supported.
This conversion is designed for flat, non-photographic images such as posters, flyers, banners, and social graphics.
Starting a job consumes the user's [AI credit allowance](https://www.canva.com/help/ai-access/). If the user has reached their AI allowance limit, the request returns a `402` error with the `credit_quota_exceeded` code. Polling for the result of a job using the [Get image-to-design import job API](https://www.canva.dev/docs/apps/rest-apis/reference/design-imports/get-image-to-design-import-job/) doesn't consume any of the allowance.
Use this API when the user wants to edit the contents of the image, such as changing its text, colors, or individual elements. If you only need to place the image into a design as a single flat image, use the [Create design API](https://www.canva.dev/docs/apps/rest-apis/reference/designs/create-design/) with an `asset_id` instead. The Create design API doesn't consume AI credits.
For more information on the workflow for using asynchronous jobs, see [API requests and responses](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints). You can check the status and get the results of image-to-design import jobs created with this API using the [Get image-to-design import job API](https://www.canva.dev/docs/apps/rest-apis/reference/design-imports/get-image-to-design-import-job/).
operationId: createImageToDesignImportJob
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateImageToDesignImportJobRequest'
required: true
responses:
"200":
content:
application/json:
examples:
in_progress:
$ref: '#/components/examples/InProgressImageToDesignImportJobExample'
success:
$ref: '#/components/examples/SuccessImageToDesignImportJobExample'
failed:
$ref: '#/components/examples/FailedImageToDesignImportJobExample'
schema:
$ref: '#/components/schemas/CreateImageToDesignImportJobResponse'
description: OK
"400":
content:
application/json:
examples:
unsupported_asset:
$ref: '#/components/examples/UnsupportedAssetError'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
"402":
content:
application/json:
examples:
user_payment_required:
$ref: '#/components/examples/UserPaymentRequiredError'
app_payment_required:
$ref: '#/components/examples/AppPaymentRequiredError'
schema:
$ref: '#/components/schemas/Error'
description: Payment Required
x-http-status-code: 402
"403":
content:
application/json:
examples:
asset_access_not_allowed:
$ref: '#/components/examples/AssetAccessNotAllowedError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
asset_not_found:
$ref: '#/components/examples/AssetNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthClientCredentials:
- service:design:content:write
- oauthAuthCode:
- design:content:write
tags:
- design_import
x-required-capabilities:
- image_to_design_imports
x-rate-limit-per-client-user: 20
x-rate-limit-per-client-credential: 100
/v1/image-to-design-imports/{jobId}:
get:
description: |-
This API is currently provided as a preview. Be aware of the following:
- There might be unannounced breaking changes.
- Any breaking changes to preview APIs won't produce a new [API version](https://www.canva.dev/docs/apps/rest-apis/versions/).
- Public integrations that use preview APIs will not pass the review process, and can't be made available to all Canva users.
Gets the result of an image-to-design import job created using the [Create image-to-design import job API](https://www.canva.dev/docs/apps/rest-apis/reference/design-imports/create-image-to-design-import-job/).
You might need to make multiple requests to this endpoint until you get a `success` or `failed` status. For more information on the workflow for using asynchronous jobs, see [API requests and responses](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints).
operationId: getImageToDesignImportJob
parameters:
- description: The ID of the image-to-design import job.
example: f81b26fd-a33d-4c2d-9e8c-4a7aca798b17
explode: false
in: path
name: jobId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
responses:
"200":
content:
application/json:
examples:
in_progress:
$ref: '#/components/examples/InProgressImageToDesignImportJobExample'
success:
$ref: '#/components/examples/SuccessImageToDesignImportJobExample'
failed:
$ref: '#/components/examples/FailedImageToDesignImportJobExample'
schema:
$ref: '#/components/schemas/GetImageToDesignImportJobResponse'
description: OK
"400":
content:
application/json:
examples:
job_id_format_invalid:
$ref: '#/components/examples/BadRequestFieldError'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
"403":
content:
application/json:
examples:
job_not_creator:
$ref: '#/components/examples/JobNotCreatorError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
job_id_not_found:
$ref: '#/components/examples/JobIdNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
"429":
content:
application/json:
examples:
design_creation_throttled:
$ref: '#/components/examples/DesignCreationThrottledError'
schema:
$ref: '#/components/schemas/Error'
description: Too Many Requests
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthClientCredentials:
- service:design:content:write
- oauthAuthCode:
- design:content:write
tags:
- design_import
x-required-capabilities:
- image_to_design_imports
x-rate-limit-per-client-user: 120
x-rate-limit-per-client-credential: 100
/v1/exports:
post:
description: |-
Starts a new [asynchronous job](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints) to export a file from Canva. Once the exported file is generated, you can download
it using the URL(s) provided. The download URLs are only valid for 24 hours.
The request requires the design ID and the exported file format type.
Supported file formats (and export file type values): JPG (`jpg`), PNG (`png`), GIF (`gif`), Microsoft PowerPoint (`pptx`), MP4 (`mp4`), PDF (`pdf`), CSV (`csv`), HTML bundle (`html_bundle`), and standalone HTML (`html_standalone`).
This endpoint has the following additional rate limits:
- **App throttle:** Each app can export a maximum of 750 times per 5-minute window, and 5,000 times per 24-hour window.
- **Document throttle:** Each document can be exported a maximum of 75 times per 5-minute window.
- **User throttle:** Each user can export a maximum of 75 times per 5-minute window, and 500 times per 24-hour window.
For more information on the workflow for using asynchronous jobs, see [API requests and responses](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints). You can check the status and get the results of export jobs created with this API using the [Get design export job API](https://www.canva.dev/docs/apps/rest-apis/reference/exports/get-design-export-job/).
operationId: createDesignExportJob
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDesignExportJobRequest'
responses:
"200":
content:
application/json:
examples:
in_progress:
$ref: '#/components/examples/InProgressExportJobExample'
success:
$ref: '#/components/examples/SuccessExportJobExample'
failed:
$ref: '#/components/examples/FailedExportJobExample'
schema:
$ref: '#/components/schemas/CreateDesignExportJobResponse'
description: OK
"400":
content:
application/json:
examples:
export_invalid_design_id:
$ref: '#/components/examples/ExportInvalidDesignIdError'
export_design_type_not_supported:
$ref: '#/components/examples/UnsupportedDesignType'
export_format_not_supported:
$ref: '#/components/examples/UnsupportedFormatError'
invalid_page_range:
$ref: '#/components/examples/InvalidPageRangeError'
transparent_background_not_allowed:
$ref: '#/components/examples/TransparentBackgroundNotAllowedError'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
x-http-status-code: 400
"403":
content:
application/json:
examples:
design_permission_denied:
$ref: '#/components/examples/DesignPermissionDeniedError'
license_required:
$ref: '#/components/examples/LicenseRequiredError'
svg_export_unavailable:
$ref: '#/components/examples/SvgExportUnavailableError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
x-http-status-code: 403
"404":
content:
application/json:
examples:
export_design_not_found:
$ref: '#/components/examples/ExportDesignNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
x-http-status-code: 404
"429":
content:
application/json:
examples:
client_throttle:
$ref: '#/components/examples/ClientThrottleError'
client_daily_throttle:
$ref: '#/components/examples/ClientDailyThrottleError'
user_throttle:
$ref: '#/components/examples/UserThrottleError'
user_daily_throttle:
$ref: '#/components/examples/UserDailyThrottleError'
design_throttle:
$ref: '#/components/examples/DesignThrottleError'
schema:
$ref: '#/components/schemas/Error'
description: Too Many Requests
x-http-status-code: 429
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthClientCredentials:
- service:design:content:read
- oauthAuthCode:
- design:content:read
tags:
- export
x-rate-limit-per-client-user: 20
x-rate-limit-per-client-credential: 100
/v1/print-partner/exports:
post:
description: |-
This API is currently provided as a preview. Be aware of the following:
- There might be unannounced breaking changes.
- Any breaking changes to preview APIs won't produce a new [API version](https://www.canva.dev/docs/apps/rest-apis/versions/).
- Public apps that use preview APIs will not pass the review process, and can't be made available to all Canva users.
AVAILABILITY: This API is only available to Print Partners.
Starts a new [asynchronous job](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints) to export a Print Partner file from Canva. Once the exported file is generated, you can download
it using the URL(s) provided. The download URLs are only valid for 24 hours.
The request requires the design ID and exports a file as a print-quality PDF.
This endpoint has the following additional rate limits:
- **Integration throttle:** Each integration can export a maximum of 750 times per 5-minute window, and 5,000 times per 24-hour window.
- **Document throttle:** Each document can be exported a maximum of 75 times per 5-minute window.
- **User throttle:** Each user can export a maximum of 75 times per 5-minute window, and 500 times per 24-hour window.
For more information on the workflow for using asynchronous jobs, see [API requests and responses](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints). You can check the status and get the results of export jobs created with this API using the [Get design export job API](https://www.canva.dev/docs/apps/rest-apis/reference/exports/get-design-export-job/).
operationId: createPrintPartnerDesignExportJob
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePrintPartnerDesignExportJobRequest'
responses:
"200":
content:
application/json:
examples:
in_progress:
$ref: '#/components/examples/InProgressExportJobExample'
success:
$ref: '#/components/examples/SuccessExportJobExample'
failed:
$ref: '#/components/examples/FailedExportJobExample'
schema:
$ref: '#/components/schemas/CreatePrintPartnerDesignExportJobResponse'
description: OK
"400":
content:
application/json:
examples:
export_invalid_design_id:
$ref: '#/components/examples/ExportInvalidDesignIdError'
export_design_type_not_supported:
$ref: '#/components/examples/UnsupportedDesignType'
export_format_not_supported:
$ref: '#/components/examples/UnsupportedFormatError'
invalid_page_range:
$ref: '#/components/examples/InvalidPageRangeError'
print_partner_unsupported_design_type:
$ref: '#/components/examples/PrintPartnerUnsupportedDesignTypeError'
print_partner_unsupported_design:
$ref: '#/components/examples/PrintPartnerUnsupportedDesignError'
export_scale_factor_outside_range:
$ref: '#/components/examples/ExportScaleFactorOutsideRangeError'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
x-http-status-code: 400
"403":
content:
application/json:
examples:
print_partner_export_forbidden:
$ref: '#/components/examples/PrintPartnerExportForbidden'
design_permission_denied:
$ref: '#/components/examples/DesignPermissionDeniedError'
license_required:
$ref: '#/components/examples/LicenseRequiredError'
resource_unavailable:
$ref: '#/components/examples/ResourceUnavailableError'
embedded_media_error:
$ref: '#/components/examples/EmbeddedMediaError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
x-http-status-code: 403
"404":
content:
application/json:
examples:
export_design_not_found:
$ref: '#/components/examples/ExportDesignNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
x-http-status-code: 404
"429":
content:
application/json:
examples:
client_throttle:
$ref: '#/components/examples/ClientThrottleError'
client_daily_throttle:
$ref: '#/components/examples/ClientDailyThrottleError'
user_throttle:
$ref: '#/components/examples/UserThrottleError'
user_daily_throttle:
$ref: '#/components/examples/UserDailyThrottleError'
design_throttle:
$ref: '#/components/examples/DesignThrottleError'
schema:
$ref: '#/components/schemas/Error'
description: Too Many Requests
x-http-status-code: 429
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthAuthCode:
- design:content:read
tags:
- export
x-rate-limit-per-client-user: 20
/v1/exports/{exportId}:
get:
description: |-
Gets the result of a design export job that was created using the [Create design export job API](https://www.canva.dev/docs/apps/rest-apis/reference/exports/create-design-export-job/).
If the job is successful, the response includes an array
of download URLs. Depending on the design type and export format, there is a download URL for each page in the design. The download URLs are only valid for 24 hours.
You might need to make multiple requests to this endpoint until you get a `success` or `failed` status. For more information on the workflow for using asynchronous jobs, see [API requests and responses](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints).
operationId: getDesignExportJob
parameters:
- description: The export job ID.
explode: false
in: path
name: exportId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
responses:
"200":
content:
application/json:
examples:
in_progress:
$ref: '#/components/examples/InProgressExportJobExample'
success:
$ref: '#/components/examples/SuccessExportJobExample'
failed:
$ref: '#/components/examples/FailedExportJobExample'
schema:
$ref: '#/components/schemas/GetDesignExportJobResponse'
description: OK
"403":
content:
application/json:
examples:
export_job_permission_denied:
$ref: '#/components/examples/ExportJobPermissionDeniedError'
export_job_result_permission_denied:
$ref: '#/components/examples/ExportJobResultPermissionDeniedError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
export_job_expired:
$ref: '#/components/examples/ExportJobExpiredError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthClientCredentials:
- service:design:content:read
- oauthAuthCode:
- design:content:read
tags:
- export
x-rate-limit-per-client-user: 120
x-rate-limit-per-client-credential: 100
/v1/folders/{folderId}:
delete:
description: |-
Deletes a folder with the specified `folderID`.
Deleting a folder moves the user's content in the folder to the
[Trash](https://www.canva.com/help/deleted-designs/) and content owned by
other users is moved to the top level of the owner's
[projects](https://www.canva.com/help/find-designs-and-folders/).
operationId: deleteFolder
parameters:
- description: The folder ID.
example: FAF2lZtloor
explode: false
in: path
name: folderId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
responses:
"204":
description: OK
"400":
content:
application/json:
examples:
invalid_folder_id:
$ref: '#/components/examples/InvalidFolderIdError'
root_folder_not_supported:
$ref: '#/components/examples/RootFolderNotSupportedError'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
"403":
content:
application/json:
examples:
folder_access_not_allowed:
$ref: '#/components/examples/FolderAccessNotAllowedError'
uploads_folder_not_allowed:
$ref: '#/components/examples/UploadsFolderNotAllowedError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
folder_not_found:
$ref: '#/components/examples/FolderNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthAuthCode:
- folder:write
tags:
- folder
x-rate-limit-per-client-user: 20
get:
description: Gets the name and other details of a folder using a folder's `folderID`.
operationId: getFolder
parameters:
- description: The folder ID.
example: FAF2lZtloor
explode: false
in: path
name: folderId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/GetFolderResponse'
description: OK
"400":
content:
application/json:
examples:
invalid_folder_id:
$ref: '#/components/examples/InvalidFolderIdError'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
"403":
content:
application/json:
examples:
folder_access_not_allowed:
$ref: '#/components/examples/FolderAccessNotAllowedError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
folder_not_found:
$ref: '#/components/examples/FolderNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthAuthCode:
- folder:read
tags:
- folder
x-rate-limit-per-client-user: 100
patch:
description: |-
Updates a folder's details using its `folderID`.
Currently, you can only update a folder's name.
operationId: updateFolder
parameters:
- description: The folder ID.
example: FAF2lZtloor
explode: false
in: path
name: folderId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateFolderRequest'
required: true
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateFolderResponse'
description: OK
"400":
content:
application/json:
examples:
invalid_request_parameters:
$ref: '#/components/examples/FolderInvalidRequestParametersError'
root_folder_not_supported:
$ref: '#/components/examples/RootFolderNotSupportedError'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
"403":
content:
application/json:
examples:
folder_access_not_allowed:
$ref: '#/components/examples/FolderAccessNotAllowedError'
uploads_folder_not_allowed:
$ref: '#/components/examples/UploadsFolderNotAllowedError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
folder_not_found:
$ref: '#/components/examples/FolderNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthAuthCode:
- folder:write
tags:
- folder
x-rate-limit-per-client-user: 20
/v1/folders/{folderId}/items:
get:
description: |-
Lists the items in a folder, including each item's `type`.
Folders can contain:
- Other folders.
- Designs, such as Instagram posts, Presentations, and Documents ([Canva Docs](https://www.canva.com/create/documents/)).
- Image assets.
- Brand templates. To include `brand_template` items in the response, you must explicitly specify it in the `item_types` parameter.
AVAILABILITY: Brand template items are only returned for users on a Canva plan with access to brand templates (such as Canva Pro, Canva Teams, or Canva Enterprise). For more information, see [Brand templates](https://www.canva.dev/docs/apps/rest-apis/reference/brand-templates/).
Currently, video assets are not returned in the response.
operationId: listFolderItems
parameters:
- description: The folder ID.
example: FAF2lZtloor
explode: false
in: path
name: folderId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
- description: |-
If the success response contains a continuation token, the folder contains more items
you can list. You can use this token as a query parameter and retrieve more
items from the list, for example
`/v1/folders/{folderId}/items?continuation={continuation}`.
To retrieve all the items in a folder, you might need to make multiple requests.
example: RkFGMgXlsVTDbMd:MR3L0QjiaUzycIAjx0yMyuNiV0OildoiOwL0x32G4NjNu4FwtAQNxowUQNMMYN
explode: true
in: query
name: continuation
required: false
schema:
type: string
style: form
- explode: true
in: query
name: limit
required: false
schema:
default: 50
description: The number of folder items to return.
format: int32
maximum: 100
minimum: 1
type: integer
style: form
- description: |-
Filter the folder items to only return specified types. The available types are:
`design`, `folder`, `image`, and `brand_template`. To filter for more than one item type,
provide a comma-delimited list.
If not specified, defaults to returning `design`, `folder`, and `image` items.
To include `brand_template` items, you must explicitly specify it in this parameter.
explode: false
in: query
name: item_types
required: false
schema:
default:
- design
- folder
- image
items:
$ref: '#/components/schemas/FolderItemType'
type: array
style: form
- description: Sort the list of folder items.
example: title_ascending
explode: true
in: query
name: sort_by
required: false
schema:
$ref: '#/components/schemas/FolderItemSortBy'
style: form
- description: Filter the folder items by their pinned status.
explode: true
in: query
name: pin_status
required: false
schema:
$ref: '#/components/schemas/FolderItemPinStatus'
style: form
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/ListFolderItemsResponse'
description: OK
"400":
content:
application/json:
examples:
list_items_invalid_continuation:
$ref: '#/components/examples/ListItemsInvalidContinuationError'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
"403":
content:
application/json:
examples:
folder_access_not_allowed:
$ref: '#/components/examples/FolderAccessNotAllowedError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
folder_not_found:
$ref: '#/components/examples/FolderNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthAuthCode:
- folder:read
tags:
- folder
x-rate-limit-per-client-user: 100
/v1/folders/move:
post:
description: |-
Moves an item to another folder. You must specify the folder ID of the destination folder, as well as the ID of the item you want to move.
NOTE: In some situations, a single item can exist in multiple folders. If you attempt to move an item that exists in multiple folders, the API returns an `item_in_multiple_folders` error. In this case, you must use the Canva UI to move the item to another folder.
operationId: moveFolderItem
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MoveFolderItemRequest'
responses:
"204":
description: OK
"400":
content:
application/json:
examples:
invalid_folder_id:
$ref: '#/components/examples/InvalidFolderIdError'
invalid_item_id:
$ref: '#/components/examples/InvalidItemIdError'
target_folder_size_limit_reached:
$ref: '#/components/examples/TargetFolderSizeLimitReachedError'
item_in_multiple_folders:
$ref: '#/components/examples/ItemInMultipleFoldersError'
to_folder_same_as_item:
$ref: '#/components/examples/ToFolderSameAsItemError'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
"403":
content:
application/json:
examples:
folder_access_not_allowed:
$ref: '#/components/examples/FolderAccessNotAllowedError'
move_uploads_folder_not_allowed:
$ref: '#/components/examples/MoveUploadsFolderNotAllowedError'
shared_design_not_allowed_in_root:
$ref: '#/components/examples/SharedDesignNotAllowedInRootError'
folder_item_access_not_allowed:
$ref: '#/components/examples/FolderItemAccessNotAllowedError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
folder_not_found:
$ref: '#/components/examples/FolderNotFoundError'
to_folder_not_found:
$ref: '#/components/examples/ToFolderNotFoundError'
folder_item_not_found:
$ref: '#/components/examples/FolderItemNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthClientCredentials:
- service:folder:write
- oauthAuthCode:
- folder:write
tags:
- folder
x-rate-limit-per-client-user: 100
x-rate-limit-per-client-credential: 100
/v1/folders:
post:
description: |-
Creates a folder in one of the following locations:
- The top level of a Canva user's [projects](https://www.canva.com/help/find-designs-and-folders/) (using the ID `root`),
- The user's Uploads folder (using the ID `uploads`),
- Another folder (using the parent folder's ID).
When a folder is successfully created, the
endpoint returns its folder ID, along with other information.
operationId: createFolder
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateFolderRequest'
required: true
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/CreateFolderResponse'
description: OK
"400":
content:
application/json:
examples:
invalid_request_parameters:
$ref: '#/components/examples/FolderInvalidRequestParametersError'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
"403":
content:
application/json:
examples:
folder_access_not_allowed:
$ref: '#/components/examples/FolderAccessNotAllowedError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
parent_folder_not_found:
$ref: '#/components/examples/ParentFolderNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthAuthCode:
- folder:write
tags:
- folder
x-rate-limit-per-client-user: 20
/v1/image-generations:
post:
description: |-
This API is currently provided as a preview. Be aware of the following:
- There might be unannounced breaking changes.
- Any breaking changes to preview APIs won't produce a new [API version](https://www.canva.dev/docs/apps/rest-apis/versions/).
- Public apps that use preview APIs will not pass the review process, and can't be made available to all Canva users.
Starts a new [asynchronous job](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints) to generate an image from a plain-text prompt. When the image is generated, you can download it using the URL provided. The download URL is only valid for 24 hours.
The request requires a prompt and an idempotency key. Call this API with a user access token that has the `asset:write` scope.
To also save the generated image to the user's Canva account as an image asset, set `asset_upload` to `type: upload`. The job then returns the asset alongside the download URL. Saving the asset requires a user access token.
Starting a job consumes the user's [AI credit allowance](https://www.canva.com/help/ai-access/). If the user has reached their AI allowance limit, the request returns a `402` error with the `credit_quota_exceeded` code.
For more information on the workflow for using asynchronous jobs, see [API requests and responses](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints). You can check the status and get the results of image generation jobs created with this API using the [Get image generation job API](https://www.canva.dev/docs/apps/rest-apis/reference/generations/get-image-generation-job/).
operationId: createImageGenerationJob
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateImageGenerationJobRequest'
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/CreateImageGenerationJobResponse'
description: OK
"400":
content:
application/json:
examples:
BadRequestFieldError:
$ref: '#/components/examples/BadRequestFieldError'
MissingRequiredHeaderError:
$ref: '#/components/examples/MissingRequiredHeaderError'
MissingAccessTokenError:
$ref: '#/components/examples/MissingAccessTokenError'
MissingClientCredentialsError:
$ref: '#/components/examples/MissingClientCredentialsError'
ContentTypeHeaderValueMissing:
$ref: '#/components/examples/ContentTypeHeaderValueMissing'
ContentTypeHeaderValueInvalid:
$ref: '#/components/examples/ContentTypeHeaderValueInvalid'
ValidatingClientFailed:
$ref: '#/components/examples/ValidatingClientFailed'
ValidatingClientFailedWithCode:
$ref: '#/components/examples/ValidatingClientFailedWithCode'
ClientSecretInvalidError:
$ref: '#/components/examples/ClientSecretInvalidError'
InvalidClientCredentialsValue:
$ref: '#/components/examples/InvalidClientCredentialsValue'
InvalidClientCredentialsBase64Encoding:
$ref: '#/components/examples/InvalidClientCredentialsBase64Encoding'
FailedToReadRequestBody:
$ref: '#/components/examples/FailedToReadRequestBody'
ExpectedIntegerQueryParam:
$ref: '#/components/examples/ExpectedIntegerQueryParam'
ExpectedLongQueryParam:
$ref: '#/components/examples/ExpectedLongQueryParam'
ExpectedLongListQueryParam:
$ref: '#/components/examples/ExpectedLongListQueryParam'
TooManyQueryParamValues:
$ref: '#/components/examples/TooManyQueryParamValues'
MissingRequiredQueryParam:
$ref: '#/components/examples/MissingRequiredQueryParam'
ConfidentialClientCorsError:
$ref: '#/components/examples/ConfidentialClientCorsError'
InvalidUriError:
$ref: '#/components/examples/InvalidUriError'
InvalidOriginError:
$ref: '#/components/examples/InvalidOriginError'
InvalidIdsError:
$ref: '#/components/examples/InvalidIdsError'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
x-http-status-code: 400
"401":
content:
application/json:
examples:
InvalidClientError:
$ref: '#/components/examples/InvalidClientError'
InvalidAccessToken:
$ref: '#/components/examples/InvalidAccessToken'
MissingClientCredentialsOrBodyAuthError:
$ref: '#/components/examples/MissingClientCredentialsOrBodyAuthError'
MalformedAuthorizationHeaderComponents:
$ref: '#/components/examples/MalformedAuthorizationHeaderComponents'
MalformedAuthorizationHeaderMode:
$ref: '#/components/examples/MalformedAuthorizationHeaderMode'
TokenIntrospectionFailed:
$ref: '#/components/examples/TokenIntrospectionFailed'
RevokedAccessToken:
$ref: '#/components/examples/RevokedAccessToken'
MissingAuthorizationHeader:
$ref: '#/components/examples/MissingAuthorizationHeader'
MalformedAuthorizationHeader:
$ref: '#/components/examples/MalformedAuthorizationHeader'
schema:
$ref: '#/components/schemas/Error'
description: Unauthorized
x-http-status-code: 401
"402":
content:
application/json:
examples:
user_payment_required:
$ref: '#/components/examples/UserPaymentRequiredError'
app_payment_required:
$ref: '#/components/examples/AppPaymentRequiredError'
schema:
$ref: '#/components/schemas/Error'
description: Payment Required
x-http-status-code: 402
"403":
content:
application/json:
examples:
image_generation_not_enabled:
$ref: '#/components/examples/ImageGenerationNotEnabledError'
missing_scope:
$ref: '#/components/examples/MissingScopeError'
user_role_required:
$ref: '#/components/examples/UserRoleRequiredError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"429":
content:
application/json:
examples:
model_capacity_reached:
$ref: '#/components/examples/ModelCapacityReached'
too_many_requests:
$ref: '#/components/examples/TooManyRequestsError'
schema:
$ref: '#/components/schemas/Error'
description: Too Many Requests
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthClientCredentials:
- service:asset:write
- oauthAuthCode:
- asset:write
tags:
- image_generation
x-required-capabilities:
- image_generation
x-rate-limit-per-client-user: 20
x-rate-limit-per-client-credential: 1000
/v1/image-generations/{jobId}:
get:
description: |-
This API is currently provided as a preview. Be aware of the following:
- There might be unannounced breaking changes.
- Any breaking changes to preview APIs won't produce a new [API version](https://www.canva.dev/docs/apps/rest-apis/versions/).
- Public apps that use preview APIs will not pass the review process, and can't be made available to all Canva users.
Gets the result of an image generation job that was created using the [Create image generation job API](https://www.canva.dev/docs/apps/rest-apis/reference/generations/create-image-generation-job/). Only the app and user that created the job can get it.
If the job is successful, the job's `result` contains a download URL for the generated image. The download URL is only valid for 24 hours. If the job was created with `asset_upload` set to `type: upload`, the `result` also contains the image asset that the image was saved as. These jobs stay `in_progress` until the asset has finished importing, so the returned asset is ready to use.
You might need to make multiple requests to this endpoint until you get a `success` or `failed` status. For more information on the workflow for using asynchronous jobs, see [API requests and responses](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints).
operationId: getImageGenerationJob
parameters:
- description: The image generation job ID.
explode: false
in: path
name: jobId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/GetImageGenerationJobResponse'
description: OK
"401":
content:
application/json:
examples:
InvalidClientError:
$ref: '#/components/examples/InvalidClientError'
InvalidAccessToken:
$ref: '#/components/examples/InvalidAccessToken'
MissingClientCredentialsOrBodyAuthError:
$ref: '#/components/examples/MissingClientCredentialsOrBodyAuthError'
MalformedAuthorizationHeaderComponents:
$ref: '#/components/examples/MalformedAuthorizationHeaderComponents'
MalformedAuthorizationHeaderMode:
$ref: '#/components/examples/MalformedAuthorizationHeaderMode'
TokenIntrospectionFailed:
$ref: '#/components/examples/TokenIntrospectionFailed'
RevokedAccessToken:
$ref: '#/components/examples/RevokedAccessToken'
MissingAuthorizationHeader:
$ref: '#/components/examples/MissingAuthorizationHeader'
MalformedAuthorizationHeader:
$ref: '#/components/examples/MalformedAuthorizationHeader'
schema:
$ref: '#/components/schemas/Error'
description: Unauthorized
x-http-status-code: 401
"403":
content:
application/json:
examples:
MissingScopeError:
$ref: '#/components/examples/MissingScopeError'
UserRoleRequiredError:
$ref: '#/components/examples/UserRoleRequiredError'
IntegrationAccessDeniedError:
$ref: '#/components/examples/IntegrationAccessDeniedError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
x-http-status-code: 403
"404":
content:
application/json:
examples:
image_generation_job_not_found:
$ref: '#/components/examples/ImageGenerationJobNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
"429":
content:
application/json:
examples:
TooManyRequestsError:
$ref: '#/components/examples/TooManyRequestsError'
ThrottledTooManyRequests:
$ref: '#/components/examples/ThrottledTooManyRequests'
schema:
$ref: '#/components/schemas/Error'
description: Too Many Requests
x-http-status-code: 429
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthClientCredentials:
- service:asset:write
- oauthAuthCode:
- asset:write
tags:
- image_generation
x-required-capabilities:
- image_generation
x-rate-limit-per-client-user: 120
x-rate-limit-per-client-credential: 1000
/v1/image-transformations:
post:
description: |-
This API is currently provided as a preview. Be aware of the following:
- There might be unannounced breaking changes.
- Any breaking changes to preview APIs won't produce a new [API version](https://www.canva.dev/docs/apps/rest-apis/versions/).
- Public apps that use preview APIs will not pass the review process, and can't be made available to all Canva users.
Starts a new [asynchronous job](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints) to apply one or more transformations to an image asset. A successful job produces a single new image asset with all of the requested transformations applied. The source asset isn't modified, and intermediate results aren't returned.
The request requires the ID of the source asset and at least one transformation. The source asset must be an image asset, such as one created using the [Asset upload APIs](https://www.canva.dev/docs/apps/rest-apis/reference/assets/).
Transformations are applied in the order provided, with each one stacked on the result of the previous one.
Starting a job consumes the user's [AI credit allowance](https://www.canva.com/help/ai-access/). If the user has reached their AI allowance limit, the request returns a `402` error with the `credit_quota_exceeded` code. Polling for the result of a job using the [Get image transformation job API](https://www.canva.dev/docs/apps/rest-apis/reference/image-transformations/get-image-transformation-job/) doesn't consume any of the allowance.
For more information on the workflow for using asynchronous jobs, see [API requests and responses](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints). You can check the status and get the results of image transformation jobs created with this API using the [Get image transformation job API](https://www.canva.dev/docs/apps/rest-apis/reference/image-transformations/get-image-transformation-job/).
operationId: createImageTransformationJob
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateImageTransformationJobRequest'
responses:
"200":
content:
application/json:
examples:
in_progress:
$ref: '#/components/examples/InProgressImageTransformationJobExample'
success:
$ref: '#/components/examples/SuccessImageTransformationJobExample'
failed:
$ref: '#/components/examples/FailedImageTransformationJobExample'
schema:
$ref: '#/components/schemas/CreateImageTransformationJobResponse'
description: OK
"400":
content:
application/json:
examples:
bad_request_field:
$ref: '#/components/examples/BadRequestFieldError'
unsupported_content_type:
$ref: '#/components/examples/UnsupportedAssetTypeError'
asset_not_ready:
$ref: '#/components/examples/AssetNotReadyError'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
"401":
content:
application/json:
examples:
InvalidClientError:
$ref: '#/components/examples/InvalidClientError'
InvalidAccessToken:
$ref: '#/components/examples/InvalidAccessToken'
MissingClientCredentialsOrBodyAuthError:
$ref: '#/components/examples/MissingClientCredentialsOrBodyAuthError'
MalformedAuthorizationHeaderComponents:
$ref: '#/components/examples/MalformedAuthorizationHeaderComponents'
MalformedAuthorizationHeaderMode:
$ref: '#/components/examples/MalformedAuthorizationHeaderMode'
TokenIntrospectionFailed:
$ref: '#/components/examples/TokenIntrospectionFailed'
RevokedAccessToken:
$ref: '#/components/examples/RevokedAccessToken'
MissingAuthorizationHeader:
$ref: '#/components/examples/MissingAuthorizationHeader'
MalformedAuthorizationHeader:
$ref: '#/components/examples/MalformedAuthorizationHeader'
schema:
$ref: '#/components/schemas/Error'
description: Unauthorized
x-http-status-code: 401
"402":
content:
application/json:
examples:
user_payment_required:
$ref: '#/components/examples/UserPaymentRequiredError'
app_payment_required:
$ref: '#/components/examples/AppPaymentRequiredError'
schema:
$ref: '#/components/schemas/Error'
description: Payment Required
x-http-status-code: 402
"403":
content:
application/json:
examples:
image_transformation_not_enabled:
$ref: '#/components/examples/ImageTransformationNotEnabledError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
asset_not_found:
$ref: '#/components/examples/AssetNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthAuthCode:
- asset:read
- asset:write
tags:
- image_transformation
x-rate-limit-per-client-user: 20
x-rate-limit-per-client-credential: 100
/v1/image-transformations/{jobId}:
get:
description: |-
This API is currently provided as a preview. Be aware of the following:
- There might be unannounced breaking changes.
- Any breaking changes to preview APIs won't produce a new [API version](https://www.canva.dev/docs/apps/rest-apis/versions/).
- Public apps that use preview APIs will not pass the review process, and can't be made available to all Canva users.
Gets the result of an image transformation job that was created using the [Create image transformation job API](https://www.canva.dev/docs/apps/rest-apis/reference/image-transformations/create-image-transformation-job/).
If the job is successful, the job's `result` contains the new image asset produced by the transformations.
You might need to make multiple requests to this endpoint until you get a `success` or `failed` status. For more information on the workflow for using asynchronous jobs, see [API requests and responses](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints).
operationId: getImageTransformationJob
parameters:
- description: The image transformation job ID.
explode: false
in: path
name: jobId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
responses:
"200":
content:
application/json:
examples:
in_progress:
$ref: '#/components/examples/InProgressImageTransformationJobExample'
success:
$ref: '#/components/examples/SuccessImageTransformationJobExample'
failed:
$ref: '#/components/examples/FailedImageTransformationJobExample'
schema:
$ref: '#/components/schemas/GetImageTransformationJobResponse'
description: OK
"401":
content:
application/json:
examples:
InvalidClientError:
$ref: '#/components/examples/InvalidClientError'
InvalidAccessToken:
$ref: '#/components/examples/InvalidAccessToken'
MissingClientCredentialsOrBodyAuthError:
$ref: '#/components/examples/MissingClientCredentialsOrBodyAuthError'
MalformedAuthorizationHeaderComponents:
$ref: '#/components/examples/MalformedAuthorizationHeaderComponents'
MalformedAuthorizationHeaderMode:
$ref: '#/components/examples/MalformedAuthorizationHeaderMode'
TokenIntrospectionFailed:
$ref: '#/components/examples/TokenIntrospectionFailed'
RevokedAccessToken:
$ref: '#/components/examples/RevokedAccessToken'
MissingAuthorizationHeader:
$ref: '#/components/examples/MissingAuthorizationHeader'
MalformedAuthorizationHeader:
$ref: '#/components/examples/MalformedAuthorizationHeader'
schema:
$ref: '#/components/schemas/Error'
description: Unauthorized
x-http-status-code: 401
"404":
content:
application/json:
examples:
image_transformation_job_not_found:
$ref: '#/components/examples/ImageTransformationJobNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
"429":
content:
application/json:
examples:
TooManyRequestsError:
$ref: '#/components/examples/TooManyRequestsError'
ThrottledTooManyRequests:
$ref: '#/components/examples/ThrottledTooManyRequests'
schema:
$ref: '#/components/schemas/Error'
description: Too Many Requests
x-http-status-code: 429
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthAuthCode:
- asset:read
tags:
- image_transformation
x-rate-limit-per-client-user: 120
x-rate-limit-per-client-credential: 100
/v1/merges:
post:
description: |-
This API is currently provided as a preview. Be aware of the following:
- There might be unannounced breaking changes.
- Any breaking changes to preview APIs won't produce a new [API version](https://www.canva.dev/docs/apps/rest-apis/versions/).
- Public apps that use preview APIs will not pass the review process, and can't be made available to all Canva users.
Starts a new [asynchronous job](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints) to merge design pages by applying page operations (such as insert, move, or delete) to produce a new design or modify an existing one.
When the job completes successfully, the job result includes metadata for the created or updated design.
At this stage, only a single operation per request is supported by default, and passing multiple operations will fail. Contact Canva to enable multi-operation mode for your app.
For more information on the workflow for using asynchronous jobs, see [API requests and responses](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints). You can check the status and get the results of jobs created with this API using the [Get design merge job API](https://www.canva.dev/docs/apps/rest-apis/reference/merges/get-design-merge-job/).
operationId: createDesignMergeJob
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDesignMergeJobRequest'
required: true
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDesignMergeJobResponse'
description: OK
"400":
content:
application/json:
examples:
invalid_merge_job_type:
$ref: '#/components/examples/InvalidMergeJobTypeError'
invalid_operation:
$ref: '#/components/examples/InvalidOperationError'
invalid_page_number:
$ref: '#/components/examples/InvalidPageNumberError'
unsupported_page_type:
$ref: '#/components/examples/UnsupportedPageTypeError'
unsupported_document_type:
$ref: '#/components/examples/UnsupportedDocumentTypeError'
operation_not_supported:
$ref: '#/components/examples/OperationNotSupportedError'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
"402":
content:
application/json:
examples:
user_payment_required:
$ref: '#/components/examples/UserPaymentRequiredError'
app_payment_required:
$ref: '#/components/examples/AppPaymentRequiredError'
schema:
$ref: '#/components/schemas/Error'
description: Payment Required
x-http-status-code: 402
"403":
content:
application/json:
examples:
design_forbidden:
$ref: '#/components/examples/DesignForbiddenError'
unauthorized_private_resource:
$ref: '#/components/examples/UnauthorizedPrivateResourceError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
merge_design_not_found:
$ref: '#/components/examples/MergeDesignNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
"413":
content:
application/json:
examples:
request_too_large:
$ref: '#/components/examples/RequestTooLargeError'
schema:
$ref: '#/components/schemas/Error'
description: Request Entity Too Large
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthClientCredentials:
- service:design:content:write
- service:design:meta:read
- oauthAuthCode:
- design:content:write
- design:meta:read
tags:
- merge
x-rate-limit-per-client-user: 100
x-rate-limit-per-client-credential: 100
/v1/merges/{jobId}:
get:
description: |-
This API is currently provided as a preview. Be aware of the following:
- There might be unannounced breaking changes.
- Any breaking changes to preview APIs won't produce a new [API version](https://www.canva.dev/docs/apps/rest-apis/versions/).
- Public apps that use preview APIs will not pass the review process, and can't be made available to all Canva users.
Gets the result of a design merge job that was created using the [Create design merge job API](https://www.canva.dev/docs/apps/rest-apis/reference/merges/create-design-merge-job/).
If the job is successful, the response includes the job status and a `result` object with metadata for the created or updated design.
You might need to make multiple requests to this endpoint until you get a `success` or `failed` status. For more information on the workflow for using asynchronous jobs, see [API requests and responses](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints).
operationId: getDesignMergeJob
parameters:
- description: The design merge job ID.
explode: false
in: path
name: jobId
required: true
schema:
example: a7by3wd-abc123
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/GetDesignMergeJobResponse'
description: OK
"403":
content:
application/json:
examples:
merge_job_forbidden:
$ref: '#/components/examples/MergeJobForbiddenError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
merge_job_not_found:
$ref: '#/components/examples/MergeJobNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthClientCredentials:
- service:design:meta:read
- oauthAuthCode:
- design:meta:read
tags:
- merge
x-rate-limit-per-client-user: 100
x-rate-limit-per-client-credential: 100
/v1/oauth/token:
post:
description: |-
This endpoint implements the OAuth 2.0 `token` endpoint. For more information, see [Authentication](https://www.canva.dev/docs/apps/rest-apis/authentication/).
The way you generate an access token depends on your app type:
- **Public or private apps** act on behalf of a user, using the OAuth authorization code flow with Proof Key for Code Exchange (PKCE). To generate an access token, you provide either an authorization code or a refresh token. You must first [obtain user authorization and get an authorization code](https://www.canva.dev/docs/apps/rest-apis/authentication/#obtain-user-authorization).
- **Service apps** act on behalf of the app itself, using the OAuth client credentials flow. To generate an access token, you authenticate with your app's client ID and client secret. No user authorization is required.
Access tokens may be up to 4 KB in size, and are only valid for a specified period of time. The expiry time (currently 4 hours) is shown in the endpoint response and is subject to change.
**Endpoint authentication**
Requests to this endpoint require authentication with your client ID and client secret, using _one_ of the following methods:
- **Basic access authentication** (Recommended): For [basic access authentication](https://en.wikipedia.org/wiki/Basic_access_authentication), the `{credentials}` string must be a Base64 encoded value of `{client id}:{client secret}`.
- **Body parameters**: Provide your app's credentials using the `client_id` and `client_secret` body parameters.
This endpoint can't be called from a user's web-browser client because it uses client authentication with client secrets. Requests must come from your app's backend, otherwise they'll be blocked by Canva's [Cross-Origin Resource Sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) policy.
**Generate an access token using an authorization code**
Only public or private apps can use this grant type.
To generate an access token with an authorization code, you must:
- Set `grant_type` to `authorization_code`.
- Provide the `code_verifier` value that you generated when creating the user authorization URL.
- Provide the authorization code you received after the user authorized the app.
**Generate an access token using a refresh token**
Only public or private apps can use this grant type.
Using the `refresh_token` value from a previous user token request, you can get a new access token with the same or smaller scope as the previous one, but with a refreshed expiry time. You will also receive a new refresh token that you can use to refresh the access token again.
To refresh an existing access token, you must:
- Set `grant_type` to `refresh_token`.
- Provide the `refresh_token` from a previous token request.
**Generate an access token using client credentials**
Only service apps can use this grant type. The access token acts on behalf of the app itself, so it can only use [scopes for service apps](https://www.canva.dev/docs/apps/rest-apis/scopes/#scopes-for-service-apps).
To generate an access token using client credentials, you must:
- Set `grant_type` to `client_credentials`.
- Authenticate the request with your client ID and client secret, as described in **Endpoint authentication**.
- Optionally, set `scope` to the scopes that the token needs. If you omit `scope`, the token is granted all the scopes that are enabled for your app in the Developer Portal.
The response doesn't include a refresh token. When the access token expires, generate a new one by making the same request again.
operationId: exchangeAccessToken
requestBody:
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/ExchangeAccessTokenRequest'
required: true
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/ExchangeAccessTokenResponse'
description: OK
"400":
content:
application/json:
examples:
client_id_body_param_multiple_values:
$ref: '#/components/examples/ClientIdBodyParamMultipleValues'
client_id_body_param_blank:
$ref: '#/components/examples/ClientIdBodyParamBlank'
client_secret_body_param_multiple_values:
$ref: '#/components/examples/ClientSecretBodyParamMultipleValues'
client_id_basic_auth_param_blank:
$ref: '#/components/examples/ClientIdBasicAuthParamBlank'
secret_basic_auth_param_blank:
$ref: '#/components/examples/SecretBasicAuthParamBlank'
bad_request_body_too_large:
$ref: '#/components/examples/BadRequestBodyTooLarge'
invalid_refresh_token:
$ref: '#/components/examples/InvalidRefreshToken'
unauthorized_client:
$ref: '#/components/examples/UnauthorizedClientError'
token_exchange_invalid_request:
$ref: '#/components/examples/TokenExchangeInvalidRequest'
token_exchange_invalid_grant:
$ref: '#/components/examples/TokenExchangeInvalidGrant'
token_exchange_unauthorized_client:
$ref: '#/components/examples/TokenExchangeUnauthorizedClient'
token_exchange_unsupported_grant_type:
$ref: '#/components/examples/TokenExchangeUnsupportedGrantType'
token_exchange_invalid_scope:
$ref: '#/components/examples/TokenExchangeInvalidScope'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
"401":
content:
application/json:
examples:
client_secret_invalid:
$ref: '#/components/examples/ClientSecretInvalid'
access_token_missing:
$ref: '#/components/examples/AccessTokenMissing'
token_exchange_invalid_client:
$ref: '#/components/examples/TokenExchangeInvalidClient'
token_exchange_unauthorized_user:
$ref: '#/components/examples/TokenExchangeUnauthorizedUser'
schema:
$ref: '#/components/schemas/Error'
description: Unauthorized
"429":
content:
application/json:
examples:
too_many_token_exchange_requests:
$ref: '#/components/examples/TooManyTokenExchangeRequests'
schema:
$ref: '#/components/schemas/Error'
description: Too Many Requests
default:
content:
application/json:
schema:
$ref: '#/components/schemas/OauthError'
description: Error Response
security:
- {}
- basicAuth: []
tags:
- oauth
servers:
- description: Canva REST APIs
url: https://api.canva.com/auth
- description: Canva REST APIs (deprecated)
url: https://api.canva.com/rest
/v1/oauth/introspect:
post:
description: |-
Introspect an access token to see whether it is valid and active. You can also verify some token properties, such as its claims, scopes, and validity times.
Requests to this endpoint require authentication with your client ID and client secret, using _one_ of the following methods:
- **Basic access authentication** (Recommended): For [basic access authentication](https://en.wikipedia.org/wiki/Basic_access_authentication), the `{credentials}` string must be a Base64 encoded value of `{client id}:{client secret}`.
- **Body parameters**: Provide your app's credentials using the `client_id` and `client_secret` body parameters.
This endpoint can't be called from a user's web-browser client because it uses client authentication with client secrets. Requests must come from your app's backend, otherwise they'll be blocked by Canva's [Cross-Origin Resource Sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) policy.
operationId: introspectToken
requestBody:
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/IntrospectTokenRequest'
required: true
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/IntrospectTokenResponse'
description: OK
"400":
content:
application/json:
examples:
client_id_body_param_multiple_values:
$ref: '#/components/examples/ClientIdBodyParamMultipleValues'
client_id_body_param_blank:
$ref: '#/components/examples/ClientIdBodyParamBlank'
client_secret_body_param_multiple_values:
$ref: '#/components/examples/ClientSecretBodyParamMultipleValues'
client_id_basic_auth_param_blank:
$ref: '#/components/examples/ClientIdBasicAuthParamBlank'
secret_basic_auth_param_blank:
$ref: '#/components/examples/SecretBasicAuthParamBlank'
bad_request_body_too_large:
$ref: '#/components/examples/BadRequestBodyTooLarge'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
"401":
content:
application/json:
examples:
client_secret_invalid:
$ref: '#/components/examples/ClientSecretInvalid'
access_token_missing:
$ref: '#/components/examples/AccessTokenMissing'
schema:
$ref: '#/components/schemas/Error'
description: Unauthorized
default:
content:
application/json:
schema:
$ref: '#/components/schemas/OauthError'
description: Error Response
security:
- {}
- basicAuth: []
tags:
- oauth
servers:
- description: Canva REST APIs
url: https://api.canva.com/auth
- description: Canva REST APIs (deprecated)
url: https://api.canva.com/rest
/v1/oauth/revoke:
post:
description: |-
Revoke an access token or a refresh token.
If you revoke a _refresh token_, be aware that:
- The refresh token's lineage is also revoked. This means that access tokens created from that refresh token are also revoked.
- The user's consent for your app is also revoked. This means that the user must go through the OAuth process again to use your app.
Requests to this endpoint require authentication with your client ID and client secret, using _one_ of the following methods:
- **Basic access authentication** (Recommended): For [basic access authentication](https://en.wikipedia.org/wiki/Basic_access_authentication), the `{credentials}` string must be a Base64 encoded value of `{client id}:{client secret}`.
- **Body parameters**: Provide your app's credentials using the `client_id` and `client_secret` body parameters.
This endpoint can't be called from a user's web-browser client because it uses client authentication with client secrets. Requests must come from your app's backend, otherwise they'll be blocked by Canva's [Cross-Origin Resource Sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) policy.
operationId: revokeTokens
requestBody:
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/RevokeTokensRequest'
required: true
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/RevokeTokensResponse'
description: OK
"400":
content:
application/json:
examples:
client_id_body_param_multiple_values:
$ref: '#/components/examples/ClientIdBodyParamMultipleValues'
client_id_body_param_blank:
$ref: '#/components/examples/ClientIdBodyParamBlank'
client_secret_body_param_multiple_values:
$ref: '#/components/examples/ClientSecretBodyParamMultipleValues'
client_id_basic_auth_param_blank:
$ref: '#/components/examples/ClientIdBasicAuthParamBlank'
secret_basic_auth_param_blank:
$ref: '#/components/examples/SecretBasicAuthParamBlank'
bad_request_body_too_large:
$ref: '#/components/examples/BadRequestBodyTooLarge'
invalid_token:
$ref: '#/components/examples/InvalidTokenError'
invalid_request:
$ref: '#/components/examples/InvalidRequestError'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
"401":
content:
application/json:
examples:
client_secret_invalid:
$ref: '#/components/examples/ClientSecretInvalid'
access_token_missing:
$ref: '#/components/examples/AccessTokenMissing'
schema:
$ref: '#/components/schemas/Error'
description: Unauthorized
default:
content:
application/json:
schema:
$ref: '#/components/schemas/OauthError'
description: Error Response
security:
- {}
- basicAuth: []
tags:
- oauth
servers:
- description: Canva REST APIs
url: https://api.canva.com/auth
- description: Canva REST APIs (deprecated)
url: https://api.canva.com/rest
/v1/oidc/jwks:
get:
description: Gets the JSON Web Key Set (public keys) for OIDC. These keys are
used to verify JWTs in OpenID Connect flows.
operationId: getOidcJwks
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/JsonWebKeySet'
description: OK
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security: []
tags:
- oidc
servers:
- description: Canva REST APIs
url: https://api.canva.com/auth
/v1/oidc/userinfo:
get:
description: |-
Fetches the current UserInfo claims for the authorized user. This is the same fields
returned by a id_token returns during authorization.
The claims returned depend on the granted scopes: `profile` claims (`name`, `given_name`,
`family_name`) are only returned when the `profile` scope is granted, and `email` claims
(`email`, `email_verified`) are only returned when the `email` scope is granted. The
`openid` scope is always required.
operationId: userInfo
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/UserInfoResponse'
description: OK
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unauthorized
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthAuthCode:
- openid
- profile
- email
- oauthAuthCode:
- openid
- profile
- oauthAuthCode:
- openid
- email
tags:
- oidc
x-rate-limit-per-client-user: 10
servers:
- description: Canva REST APIs
url: https://api.canva.com/auth
/v1/resizes:
post:
description: |-
To use this API, your app must act on behalf of a user that's on a Canva plan with premium features (such as Canva Pro).
Users on the Canva Free plan have access to a limited trial. For more information, see [Trial quotas](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#trial-quotas).
Starts a new [asynchronous job](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints)
to create a resized copy of a design. The new resized design is
added to the top level of the user's
[projects](https://www.canva.com/help/find-designs-and-folders/) (`root` folder).
To resize a design into a new design, you can either:
- Use a preset design type.
- Set height and width dimensions for a custom design.
Note the following behaviors and restrictions when resizing designs:
- Designs can be resized to a maximum area of 25,000,000 pixels squared.
- Resizing designs using the Canva REST APIs always creates a new design. In-place resizing is currently not available in the Canva REST APIs, but can be done in the Canva UI.
- Resizing a multi-page design results in all pages of the design being resized. Resizing a section of a design is only available in the Canva UI.
- [Canva docs](https://www.canva.com/create/documents/) and [emails](https://www.canva.com/emails/) can't be resized, and other design types can't be resized to a Canva doc or email.
- Canva Code designs can't be resized, and other design types can't be resized to a Canva Code design.
For more information on the workflow for using asynchronous jobs,
see [API requests and responses](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints).
You can check the status and get the results of resize jobs created with this API using the
[Get design resize job API](https://www.canva.dev/docs/apps/rest-apis/reference/resizes/get-design-resize-job/).
operationId: createDesignResizeJob
requestBody:
content:
application/json:
example:
design_id: DAGirp_1ZUA
design_type:
type: custom
width: 1000
height: 1500
schema:
$ref: '#/components/schemas/CreateDesignResizeJobRequest'
responses:
"200":
content:
application/json:
examples:
in_progress:
$ref: '#/components/examples/InProgressResizeJobExample'
success:
$ref: '#/components/examples/SuccessResizeJobExample'
failed:
$ref: '#/components/examples/FailedResizeJobExample'
schema:
$ref: '#/components/schemas/CreateDesignResizeJobResponse'
description: OK
"400":
content:
application/json:
examples:
unsupported_design_type:
$ref: '#/components/examples/UnsupportedDesignTypeError'
invalid_design_type:
$ref: '#/components/examples/InvalidDesignTypeError'
invalid_design_type_input:
$ref: '#/components/examples/InvalidDesignTypeInputError'
dimensions_below_minimum:
$ref: '#/components/examples/DimensionsBelowMinimumError'
dimensions_above_maximum:
$ref: '#/components/examples/DimensionsAboveMaximumError'
area_above_maximum:
$ref: '#/components/examples/AreaAboveMaximumError'
design_not_resizable:
$ref: '#/components/examples/DesignNotResizableError'
page_index_out_of_bounds:
$ref: '#/components/examples/PageIndexOutOfBoundsError'
responsive_pages_not_supported:
$ref: '#/components/examples/ResponsivePagesNotSupportedError'
controlled_pages_not_supported:
$ref: '#/components/examples/ControlledPagesNotSupportedError'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
"402":
content:
application/json:
examples:
user_payment_required:
$ref: '#/components/examples/UserPaymentRequiredError'
app_payment_required:
$ref: '#/components/examples/AppPaymentRequiredError'
schema:
$ref: '#/components/schemas/Error'
description: Payment Required
x-http-status-code: 402
"403":
content:
application/json:
examples:
missing_resize_capability:
$ref: '#/components/examples/MissingResizeCapabilityError'
design_resize_not_allowed:
$ref: '#/components/examples/DesignResizeNotAllowedError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
"404":
content:
application/json:
examples:
resize_design_not_found:
$ref: '#/components/examples/ResizeDesignNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
"429":
content:
application/json:
examples:
feature_quota_exceeded:
$ref: '#/components/examples/FeatureQuotaExceededError'
schema:
$ref: '#/components/schemas/FeatureQuotaExceededError'
description: Too Many Requests
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthClientCredentials:
- service:design:content:read
- service:design:content:write
- oauthAuthCode:
- design:content:read
- design:content:write
tags:
- resize
x-required-capabilities:
- resize
x-rate-limit-per-client-user: 20
x-rate-limit-per-client-credential: 100
/v1/resizes/{jobId}:
get:
description: |-
To use this API, your app must act on behalf of a user that's on a Canva plan with premium features (such as Canva Pro).
Users on the Canva Free plan have access to a limited trial. For more information, see [Trial quotas](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#trial-quotas).
Gets the result of a design resize job that was created using the [Create design resize
job API](https://www.canva.dev/docs/apps/rest-apis/reference/resizes/create-design-resize-job/).
If the job is successful, the response includes a summary of the new resized design, including its metadata.
You might need to make multiple requests to this endpoint until you get a `success` or `failed` status.
For more information on the workflow for using asynchronous jobs,
see [API requests and responses](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints).
operationId: getDesignResizeJob
parameters:
- description: The design resize job ID.
explode: false
in: path
name: jobId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
responses:
"200":
content:
application/json:
examples:
in_progress:
$ref: '#/components/examples/InProgressResizeJobExample'
success:
$ref: '#/components/examples/SuccessResizeJobExample'
failed:
$ref: '#/components/examples/FailedResizeJobExample'
schema:
$ref: '#/components/schemas/GetDesignResizeJobResponse'
description: OK
"404":
content:
application/json:
examples:
resize_job_not_found:
$ref: '#/components/examples/ResizeJobNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthClientCredentials:
- service:design:content:read
- service:design:content:write
- oauthAuthCode:
- design:content:read
- design:content:write
tags:
- resize
x-required-capabilities:
- resize
x-rate-limit-per-client-user: 120
x-rate-limit-per-client-credential: 100
/v1/users/me:
get:
description: |-
Returns the User ID and Team ID of the user
account associated with the provided access token.
operationId: usersMe
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/UsersMeResponse'
description: OK
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthAuthCode: []
tags:
- user
x-rate-limit-per-client-user: 10
/v1/users/me/capabilities:
get:
description: "Lists the API capabilities for the user account associated with\
\ the provided access token. For more information, see [Capabilities](https://www.canva.dev/docs/apps/rest-apis/capabilities/)."
operationId: getUserCapabilities
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/GetUserCapabilitiesResponse'
description: OK
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthAuthCode:
- profile:read
tags:
- user
x-rate-limit-per-client-user: 10
/v1/users/me/profile:
get:
description: "Currently, this returns the display name of the user account associated\
\ with the provided access token. More user information is expected to be\
\ included in the future."
operationId: getUserProfile
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/UserProfileResponse'
description: OK
"404":
content:
application/json:
examples:
user_not_found:
$ref: '#/components/examples/UserNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Error Response
security:
- oauthAuthCode:
- profile:read
tags:
- user
x-rate-limit-per-client-user: 10
components:
examples:
UserPaymentRequiredError:
summary: User has reached their credit quota limit
value:
code: credit_quota_exceeded
message: User has exceeded their credit quota
AppPaymentRequiredError:
summary: App has reached its credit quota limit
value:
code: app_credit_quota_exceeded
message: App has exceeded its credit quota
CreditQuotaExceededError:
summary: User has reached their credit quota limit
value:
code: credit_quota_exceeded
message: User has exceeded their credit quota
quota_usage:
used_percentage: 100
resets_at: 1735689600
using_bonus_credits: false
upgrade_url: https://www.canva.com/upgrade
is_admin: false
generation_pending: false
CreditQuotaCooldownError:
summary: User is in a cooldown period after heavy credit usage
value:
code: credit_quota_cooldown
message: Credit quota cooldown is active
quota_usage:
used_percentage: 100
resets_at: 1735689600
using_bonus_credits: false
upgrade_url: https://www.canva.com/upgrade
cooldown_ends_at: 1767182400
is_admin: false
generation_pending: true
AnalyticsInvalidDesignIdError:
summary: The design ID does not match the expected format.
value:
code: invalid_field
message: designId does not match expected format
AnalyticsPermissionDeniedError:
summary: The caller is not allowed to access design analytics.
value:
code: permission_denied
message: Not allowed to access analytics for this design
AnalyticsDesignNotFoundError:
summary: "The design was not found, or analytics are unavailable."
value:
code: design_not_found
message: Design not found or analytics are not available for this design
AnalyticsInvalidContinuationError:
summary: The continuation token is invalid or expired.
value:
code: invalid_field
message: Invalid continuation token
AnalyticsInvalidTimeRangeError:
summary: The requested time range is invalid.
value:
code: invalid_field
message: start_time must be before end_time
AnalyticsInvalidTimezoneError:
summary: The timezone value is invalid.
value:
code: invalid_field
message: timezone is not a valid UTC offset
AnalyticsInvalidPageViewsFilterError:
summary: The page views filter is invalid.
value:
code: bad_request_body
message: filter must include a valid type discriminator and required fields
AuthKeysNotFoundError:
summary: No auth keys exist for the specified app.
value:
code: app_not_found
message: "Auth keys not found for app {appId}"
InProgressAssetUploadJobExample:
summary: In progress job
value:
job:
id: e08861ae-3b29-45db-8dc1-1fe0bf7f1cc8
status: in_progress
SuccessAssetUploadJobExample:
summary: Successfully completed job
value:
job:
id: e08861ae-3b29-45db-8dc1-1fe0bf7f1cc8
status: success
asset:
id: Msd59349ff
type: image
name: My Awesome Upload
tags:
- image
- holiday
- best day ever
owner:
user_id: oU123456AbCdE
team_id: oB123456AbCdE
created_at: 1377396000
updated_at: 1692928800
thumbnail:
width: 595
height: 335
url: https://document-export.canva.com/Vczz9/zF9vzVtdADc/2/thumbnail/0001.png?
FailedAssetUploadJobExample:
summary: Failed job
value:
job:
id: e08861ae-3b29-45db-8dc1-1fe0bf7f1cc8
status: failed
error:
code: file_too_big
message: Failed to import because the file is too big
AssetNotFoundError:
summary: The asset was not found
value:
code: asset_not_found
message: Asset not found
AssetAccessNotAllowedError:
summary: Not allowed to access the asset
value:
code: permission_denied
message: Not allowed to access this asset
AssetUpdateNotAllowedError:
summary: Not allowed to update the asset
value:
code: permission_denied
message: Not allowed to update this asset
AssetDeleteNotAllowedError:
summary: Not allowed to delete the asset
value:
code: permission_denied
message: Not allowed to delete this asset
AssetUploadJobNotFoundError:
summary: Asset upload job not found
value:
code: not_found
message: "Asset upload job with ID {jobId} not found"
AssetUploadJobNotCreatorError:
summary: Calling user was not the creator of the asset upload job
value:
code: permission_denied
message: Calling user was not the creator of the asset upload job
AssetJobIdNotFoundError:
summary: Job ID not found
value:
code: not_found
message: "Job ID {jobId} not found"
AssetJobNotFoundError:
summary: Job not found
value:
code: not_found
message: "Job {jobId} not found"
AssetJobWithIdNotFoundError:
summary: Job with ID not found
value:
code: not_found
message: "Job with Id {jobId} not found"
AssetUrlInvalidError:
summary: The provided URL is invalid
value:
code: invalid_field
message: '''url'' provided is invalid.'
AssetUploadAlreadyExistsError:
summary: An asset upload for the URL already exists
value:
code: invalid_request
message: "Asset Upload for url {url} already exists"
GetThisJobStatusNotAllowedError:
summary: Not allowed to get this job status
value:
code: permission_denied
message: Not allowed to get this job status
InProgressAutofillJobExample:
summary: In progress job
value:
job:
id: 450a76e7-f96f-43ae-9c37-0e1ce492ac72
status: in_progress
SuccessAutofillJobExample:
summary: Successfully completed job
value:
job:
id: 450a76e7-f96f-43ae-9c37-0e1ce492ac72
status: success
result:
type: create_design
design:
id: DAFVztcvd9z
title: My summer holiday
url: https://www.canva.com/design/DAFVztcvd9z/edit
urls:
edit_url: https://www.canva.com/api/ekimus8HTvsdf&/edit
view_url: https://www.canva.com/api/eylPinTv358hYb8n1U4/view
thumbnail:
width: 595
height: 335
url: https://document-export.canva.com/Vczz9/zF9vzVtdADc/2/thumbnail/0001.png?
created_at: 1586734043
updated_at: 1586734043
trial_information:
uses_remaining: 2
upgrade_url: https://www.canva.com/pro/
FailedAutofillJobExample:
summary: Failed job
value:
job:
id: 450a76e7-f96f-43ae-9c37-0e1ce492ac72
status: failed
error:
code: autofill_error
message: Error autofilling design from brand template
BrandTemplateNotFoundError:
summary: A brand template with the ID specified in the request could not be
found.
value:
code: not_found
message: "Brand template with id '{brandTemplateId}' not found"
BrandTemplateForbiddenError:
summary: |-
The user does not have permission to access the brand template with the ID
specified in the request.
value:
code: permission_denied
message: "Not allowed to access brand template with id '{brandTemplateId}'"
AutofillDesignNotFoundError:
summary: A design with the ID specified in the request could not be found.
value:
code: not_found
message: "Design with id '{designId}' not found"
AutofillDesignForbiddenError:
summary: |-
The user does not have permission to access the design with the ID
specified in the request.
value:
code: permission_denied
message: "Not allowed to access design with id '{designId}'"
AutofillFeatureForbiddenError:
summary: The user's plan does not include access to the autofill feature.
value:
code: permission_denied
message: "Access the autofill feature and other powerful design tools by upgrading\
\ your Canva plan here: {upgradeUrl}"
DesignTitleInvalidError:
summary: The design title specified in the request is not valid.
value:
code: bad_request_params
message: Design title invalid
DesignAutofillJobNotFoundError:
summary: A design autofill job with the ID specified in the request could not
be found.
value:
code: not_found
message: "Job {jobId} not found"
DesignAutofillJobForbiddenError:
summary: |-
The user does not have permission to access the design autofill job with the ID
specified in the request.
value:
code: permission_denied
message: Calling user was not the creator of the autofill job
ChartDataProcessingUnsupportedError:
summary: The chart_data_processing field value is not yet supported.
value:
code: bad_request_params
message: The chart_data_processing field is not yet supported
InvalidBrandTemplateIdError:
summary: The brand template ID specified in the request is not a valid ID format.
value:
code: bad_request_params
message: "Invalid brand template ID {brandTemplateId}"
DesignNotFillableError:
summary: The specified brand template does not contain any autofill capable
elements.
value:
code: design_not_fillable
message: Design does not have any autofill capable elements
AutofillDataInvalidError:
summary: The provided autofill data is not valid for the specified brand template.
value:
code: autofill_data_invalid
message: "{message}"
AutofillFeatureQuotaExceededError:
summary: Feature quota exceeded
value:
code: quota_exceeded
message: Free autofill quota has been exceeded. Present the `upsell_url` to
the user and prompt them to upgrade their Canva account to continue using
the autofill feature.
upsell_url: "{upsellUrl}"
PublishBrandTemplateSuccessExample:
description: Response from successfully publishing a brand template. Note that
the thumbnail might be null initially and will be available after async processing
completes.
summary: Successful brand template publishing
value:
brand_template:
id: EABCtemplate789
title: My Brand Template
view_url: https://www.canva.com/design/EABCtemplate789/view
create_url: https://www.canva.com/design/EABCtemplate789/remix
created_at: 1704110400
updated_at: 1704110400
ResourceLimitExceededError:
summary: Validation error - resource limit exceeded
value:
code: bad_request_params
message: "Design contains {count} {resource_name}, but brand templates can\
\ only contain up to {max}. Reduce the number and try again."
InvalidDesignIdError:
summary: The design ID format is invalid
value:
code: bad_request_params
message: "Design ID '{designId}' is not valid"
PublishBrandTemplateDesignNotFoundError:
summary: The design was not found
value:
code: not_found
message: "Design with id {designId} not found"
PublishPermissionDeniedError:
summary: User does not have permission to publish the design as a brand template
value:
code: permission_denied
message: "User does not have permission to publish design {designId} as a\
\ brand template"
FindBrandTemplatesForbiddenError:
summary: Not allowed to find metadata for brand templates
value:
code: permission_denied
message: Not allowed to find metadata for brand templates
GetBrandTemplateNotFoundError:
summary: Brand template not found
value:
code: not_found
message: "Brand template with id '{brandTemplateId}' not found"
GetBrandTemplatePermissionDeniedError:
summary: Not allowed to access the brand template
value:
code: permission_denied
message: "Not allowed to access brand template with id '{brandTemplateId}'"
GetBrandTemplateDatasetNotFoundError:
summary: Brand template not found
value:
code: not_found
message: "Brand template with id '{brandTemplateId}' not found"
GetBrandTemplateDatasetPermissionDeniedError:
summary: Not allowed to access the brand template
value:
code: permission_denied
message: "User does not have permission to access brand template with id '{brandTemplateId}'"
InvalidMentionIdsError:
summary: Mentions with non-obfuscated IDs are not allowed for this client
value:
code: invalid_field
message: Invalid IDs
MentionedUserNotFoundError:
summary: A mentioned user could not be found
value:
code: user_not_found
message: Invalid user ID
MentionedTeamNotFoundError:
summary: A mentioned user's team could not be found
value:
code: team_not_found
message: Invalid brand ID
AssigneeNotMentionedError:
summary: Assignee must be mentioned in comment content
value:
code: bad_request_body
message: Assignee must be mentioned in comment content
MessageTooLongError:
summary: Message is too long
value:
code: message_too_long
message: Message is too long
TooManyCommentsError:
summary: Design already has the maximum number of allowed comments
value:
code: too_many_comments
message: Design already has the maximum number of allowed comments
NotAllowedToCommentError:
summary: Not allowed to comment on this design
value:
code: permission_denied
message: Not allowed to comment on this design
DesignNotFoundError:
summary: Design not found
value:
code: design_not_found
message: Design not found
TooManyRepliesError:
summary: This comment thread already has the maximum number of allowed replies
value:
code: too_many_replies
message: This comment thread already has the maximum number of allowed replies
NotAllowedToReplyError:
summary: Not allowed to reply on this design
value:
code: permission_denied
message: Not allowed to reply on this design
DesignOrCommentNotFoundForReplyError:
summary: Design or comment not found
value:
code: design_not_found
message: Design or comment not found
NotAllowedToFetchRepliesError:
summary: Not allowed to fetch replies
value:
code: permission_denied
message: Not allowed to fetch replies
DesignOrThreadNotFoundError:
summary: Design or comment not found
value:
code: design_or_thread_not_found
message: Design or comment not found
NotAllowedToFetchCommentError:
summary: Not allowed to fetch this comment
value:
code: permission_denied
message: Not allowed to fetch this comment
NotAllowedToFetchSuggestionError:
summary: Not allowed to fetch this suggestion
value:
code: permission_denied
message: Not allowed to fetch this suggestion
ThreadNotFoundError:
summary: No thread with ID found
value:
code: thread_not_found
message: "No thread with ID {threadId} found"
ThreadNotAttachedToDesignError:
summary: Thread not attached to design
value:
code: thread_not_found
message: "Thread with ID {threadId} is not attached to design {designId},\
\ or design not found"
SuggestionNotFoundError:
summary: No suggestion thread with ID found
value:
code: thread_not_found
message: "Suggestion with ID {threadId} not found"
NotAllowedToFetchReplyError:
summary: Not allowed to fetch this reply
value:
code: permission_denied
message: Not allowed to fetch this reply
ReplyNotFoundError:
summary: Reply not found
value:
code: reply_not_found
message: "Reply with ID {replyId} not found"
SuggestionReplyNotFoundError:
summary: Suggestion reply not found
value:
code: reply_not_found
message: "Suggestion reply with ID {replyId} not found"
ProductSizeNotFoundError:
summary: Product size not found
value:
code: not_found
message: "Product size not found for product {productId}"
CreatePrintPartnerDesignForbiddenError:
summary: Client does not have permission to create a Print Partner design
value:
code: permission_denied
message: Client does not have permission to create a Print Partner design
GetPrintPartnerDesignForbiddenError:
summary: Client does not have permission to get a Print Partner design
value:
code: permission_denied
message: Client does not have permission to get a Print Partner design
CreateDesignNotFoundError:
summary: A design with the ID specified in the request could not be found.
value:
code: not_found
message: "Design with id '{designId}' not found"
CreateBrandTemplateNotFoundError:
summary: A brand template with the ID specified in the request could not be
found.
value:
code: not_found
message: "Brand template with id '{brandTemplateId}' not found"
GetDesignDatasetDesignNotFoundError:
summary: Design not found
value:
code: not_found
message: "Design with id '{designId}' not found"
GetDesignDatasetPermissionDeniedError:
summary: Not allowed to access the design
value:
code: permission_denied
message: "Not allowed to access design with id '{designId}'"
DesignIdNotFoundError:
summary: The design was not found
value:
code: design_not_found
message: "Design with id '{designId}' not found"
DesignAccessDeniedError:
summary: Not allowed to access the design
value:
code: permission_denied
message: "Not allowed to access design with id {designId}"
MissingDesignTypeOrAssetIdError:
summary: Neither design_type nor asset_id was provided
value:
code: invalid_field
message: One of 'design_type' or 'asset_id' must be defined.
BlankDesignIdError:
summary: The design_id must not be blank
value:
code: bad_request_body
message: design_id must not be blank
BlankBrandTemplateIdError:
summary: The brand_template_id must not be blank
value:
code: bad_request_body
message: brand_template_id must not be blank
CreateDesignBrandTemplateAccessDeniedError:
summary: Not allowed to access the brand template
value:
code: permission_denied
message: "Not allowed to access brand template with id '{brandTemplateId}'"
AssetIdNotImageError:
summary: The asset_id does not belong to an image asset
value:
code: bad_request_params
message: '`asset_id` must belong to an image asset'
InvalidDesignDimensionsError:
summary: The specified dimensions for the design are invalid
value:
code: invalid_field
message: The specified dimensions for the design are invalid.
RefDesignTypeNotFoundError:
summary: The design type was not found
value:
code: design_type_not_found
message: "Design type '{refDesignTypeId}' not found."
CreateDesignThrottledError:
summary: Design creation throttling threshold reached
value:
code: too_many_requests
message: You have reached the design creation throttling threshold.
DesignHasNoPagesError:
summary: Canva docs don't have pages
value:
code: page_not_found
message: "Design {designId} has no pages because it's a Canva doc."
DesignPagesOffsetTooLargeError:
summary: The offset is outside the range of pages in the design
value:
code: offset_too_large
message: "Offset {offset} is outside range of [1, {pageCount}]"
InvalidOwnershipError:
summary: The ownership value is invalid
value:
code: invalid_field
message: Invalid ownership
InvalidSortByError:
summary: The sort_by value is invalid
value:
code: invalid_field
message: "Invalid sort by value: {sortBy}"
InvalidContinuationError:
summary: The continuation token is invalid
value:
code: bad_query_params
message: "Invalid continuation: {continuation}"
DesignTypeNotAvailableError:
summary: The design_types filter contains an unavailable design type
value:
code: invalid_field
message: "'design_types' contains a design type that isn't available: {designType}."
ListDesignsForbiddenError:
summary: Not allowed to access the design list
value:
code: permission_denied
message: Not allowed to access design list
UnableToFetchDesignsError:
summary: Unable to fetch designs
value:
code: bad_query_params
message: Unable to fetch designs
FindDocumentsForbiddenError:
summary: Not allowed to find documents
value:
code: permission_denied
message: Not allowed to find documents
DesignAccessForbiddenError:
summary: Not allowed to access the design
value:
code: permission_denied
message: Not allowed to access design
InProgressDesignGenerationJobExampleV2:
summary: In-progress design generation job
value:
job:
id: f81b26fd-a33d-4c2d-9e8c-4a7aca798b17
status: in_progress
SuccessDesignGenerationJobExampleV2:
summary: Successfully completed design generation job
value:
job:
id: f81b26fd-a33d-4c2d-9e8c-4a7aca798b17
status: success
result:
design:
id: DAFVztcvd9z
title: SolarNow Seed Pitch
urls:
edit_url: https://www.canva.com/api/design/example/edit
view_url: https://www.canva.com/api/design/example/view
thumbnail:
width: 800
height: 450
url: https://document-export.canva.com/example/thumbnail/0001.png?signature=example
created_at: 1788768000
updated_at: 1788768000
page_count: 3
ContentNotAllowedDesignGenerationJobExampleV2:
summary: Design generation rejected by content-safety checks
value:
job:
id: f81b26fd-a33d-4c2d-9e8c-4a7aca798b17
status: failed
error:
code: content_not_allowed
message: The design couldn't be generated because the request didn't meet
Canva's content guidelines.
FailedDesignGenerationJobExampleV2:
summary: Design generation failed
value:
job:
id: f81b26fd-a33d-4c2d-9e8c-4a7aca798b17
status: failed
error:
code: generation_failed
message: The design couldn't be generated. Please try again.
InvalidDesignGenerationRequestErrorV2:
summary: The request contains an invalid field
value:
code: invalid_field
message: The presentation outline can only be used with the presentation design
type.
InvalidDesignGenerationInputErrorV2:
summary: An attachment is invalid or unsupported
value:
code: invalid_field
message: The specified attachment must identify a supported image or brand
template.
TooManyDesignGenerationInputsErrorV2:
summary: Too many generation inputs
value:
code: invalid_field
message: At most 20 inputs are allowed across images and brand_templates combined.
UnsupportedDesignGenerationTypeErrorV2:
summary: The design type isn't supported for generation
value:
code: invalid_field
message: "Design generation supports doc, presentation, and whiteboard presets."
DesignGenerationNotAvailableErrorV2:
summary: Design generation isn't available to the user
value:
code: permission_denied
message: Design generation isn't available for this user.
DesignGenerationInputForbiddenErrorV2:
summary: The user can't access an attachment
value:
code: permission_denied
message: The user doesn't have access to the specified attachment.
DesignGenerationInputNotFoundErrorV2:
summary: An attachment wasn't found
value:
code: not_found
message: The specified attachment wasn't found.
InvalidDesignGenerationJobIdErrorV2:
summary: The job ID is invalid
value:
code: invalid_field
message: The design generation job ID is invalid.
DesignGenerationJobForbiddenErrorV2:
summary: The caller didn't create this job
value:
code: permission_denied
message: The user doesn't have access to this design generation job.
DesignGenerationJobNotFoundErrorV2:
summary: The job wasn't found
value:
code: not_found
message: The design generation job wasn't found.
AcceptedDesignGenerationJobExampleV2:
summary: Accepted job
value:
job:
id: f81b26fd-a33d-4c2d-9e8c-4a7aca798b17
status: in_progress
JobIdInvalidError:
summary: The job ID is invalid
value:
code: bad_request_params
message: The jobId is invalid.
JobNotCreatedViaConnectApiError:
summary: The job is not created via Connect API
value:
code: invalid_request
message: The job is not created via Connect API.
DesignImportJobNotCreatorError:
summary: Calling user was not the creator of the design import job
value:
code: permission_denied
message: Calling user was not the creator of the design import job
GetJobStatusNotAllowedError:
summary: Not allowed to get the job status
value:
code: permission_denied
message: Not allowed to get the job status.
JobIdNotFoundError:
summary: Job ID not found
value:
code: not_found
message: "Job ID {jobId} not found"
JobNotFoundError:
summary: Job not found
value:
code: not_found
message: "Job {jobId} not found"
JobWithIdNotFoundError:
summary: Job with ID not found
value:
code: not_found
message: "Job with Id {jobId} not found"
DesignImportAlreadyInProgressError:
summary: A design import for the URL is already in progress
value:
code: invalid_request
message: "Design import for url {url} already in progress"
JobNotCreatorError:
summary: Calling user was not the creator of the job
value:
code: permission_denied
message: Calling user was not the creator of the job
DesignCreationThrottledError:
summary: Design creation throttling threshold reached
value:
code: too_many_requests
message: You have reached the design creation throttling threshold.
InProgressDesignImportJobExample:
summary: In progress job
value:
job:
id: e08861ae-3b29-45db-8dc1-1fe0bf7f1cc8
status: in_progress
SuccessDesignImportJobExample:
summary: Successfully completed job
value:
job:
id: e08861ae-3b29-45db-8dc1-1fe0bf7f1cc8
status: success
result:
designs:
- id: DAGQm2AkzOk
title: My Awesome Design
thumbnail:
width: 376
height: 531
url: https://document-export.canva.com/...
urls:
edit_url: https://www.canva.com/api/design/...
view_url: https://www.canva.com/api/design/...
created_at: 1726198998
updated_at: 1726199000
FailedDesignImportJobExample:
summary: Failed job
value:
job:
id: e08861ae-3b29-45db-8dc1-1fe0bf7f1cc8
status: failed
error:
code: invalid_file
message: Document could not be imported because the file is corrupt.
InProgressImageToDesignImportJobExample:
summary: In progress image-to-design import job
value:
job:
id: f81b26fd-a33d-4c2d-9e8c-4a7aca798b17
status: in_progress
SuccessImageToDesignImportJobExample:
summary: Successfully completed image-to-design import job
value:
job:
id: f81b26fd-a33d-4c2d-9e8c-4a7aca798b17
status: success
result:
design:
id: DAFVztcvd9z
title: My Image Design
thumbnail:
width: 800
height: 600
url: https://document-export.canva.com/...
urls:
edit_url: https://www.canva.com/design/DAFVztcvd9z/edit
view_url: https://www.canva.com/design/DAFVztcvd9z/view
created_at: 1726198998
updated_at: 1726199000
FailedImageToDesignImportJobExample:
summary: Failed image-to-design import job
value:
job:
id: f81b26fd-a33d-4c2d-9e8c-4a7aca798b17
status: failed
error:
code: internal_error
message: An unexpected error occurred while converting the image. Please
try again.
UnsupportedAssetError:
summary: The provided asset is not a supported image type
value:
code: unsupported_asset
message: "'asset_id' must refer to an asset of one of the following types:\
\ png, jpeg, gif, webp, heic, heif, avif, tiff, jp2, jpx, jpm, jxr."
InvalidDesignTypeError:
summary: The requested preset design type is not available.
value:
code: bad_request_body
message: "Design type '{name}' is invalid."
MissingAccessTokenError:
summary: Access token is missing from the request
value:
code: invalid_request
message: Access token is missing from the request.
MissingClientCredentialsError:
summary: Client credentials are missing from the request
value:
code: invalid_request
message: Client credentials are missing from the request.
MissingClientCredentialsOrBodyAuthError:
summary: Client credentials or body auth are missing from the request
value:
code: invalid_client
message: Client credentials or body auth are missing from the request.
UserRoleRequiredError:
summary: Request must be made on behalf of a user
value:
code: user_role_required
message: This request must be made on behalf of a user.
InvalidClientError:
summary: The OAuth client credentials are invalid
value:
code: invalid_client
message: "Client {clientId} not available"
MissingScopeError:
summary: The required OAuth scope is missing
value:
code: missing_scope
message: "Missing scopes: {scopes}"
TooManyRequestsError:
summary: Rate limit exceeded
value:
code: too_many_requests
message: "Too many requests to {operation}"
EndpointNotFoundError:
summary: The requested endpoint was not found
value:
code: endpoint_not_found
message: "Unknown endpoint {method} {path}"
BadRequestFieldError:
summary: The request field does not match expected format
value:
code: invalid_request
message: "{fieldValue} does not match expected format for {fieldName}"
MissingRequiredHeaderError:
summary: A required header is missing
value:
code: invalid_request
message: "missing required header {headerName}"
ContentTypeHeaderValueMissing:
summary: Content-Type header is missing
value:
code: invalid_header_value
message: "Content-Type header is missing for {path}"
ContentTypeHeaderValueInvalid:
summary: Content-Type header is invalid
value:
code: invalid_header_value
message: "Content-Type {contentType} is invalid for {path}"
MalformedAuthorizationHeaderComponents:
summary: Authorization header has wrong number of components
value:
code: invalid_access_token
message: "Malformed Authorization header: wrong number of components"
MalformedAuthorizationHeaderMode:
summary: Authorization header has invalid mode
value:
code: invalid_access_token
message: "Malformed Authorization header: invalid mode"
TokenIntrospectionFailed:
summary: Token couldn't be introspected
value:
code: invalid_access_token
message: Token couldn't be introspected
RevokedAccessToken:
summary: Access token is revoked
value:
code: revoked_access_token
message: Access token is revoked
ValidatingClientFailed:
summary: Validating client failed
value:
code: unauthorized_client
message: "Validating client failed for {clientAppId}"
ValidatingClientFailedWithCode:
summary: Validating client failed with error code
value:
code: unauthorized_client
message: "Validating client failed for {clientAppId}: {errorCode}"
ClientSecretInvalidError:
summary: Client secret is invalid
value:
code: invalid_client
message: "Client secret is invalid for {clientAppId}"
InvalidClientCredentialsBase64Encoding:
summary: Could not decode the base64 value for client credentials
value:
code: invalid_request
message: Credentials could not be decoded from base64
InvalidClientCredentialsValue:
summary: Number of column-separated components in the base64 value is not 2
value:
code: invalid_request
message: Malformed encoded client ID and secret
InvalidAccessToken:
summary: Access token could not be decoded or signature could not be verified.
value:
code: invalid_access_token
message: Access token is invalid
MissingAuthorizationHeader:
summary: Missing Authorization header
value:
code: invalid_access_token
message: Missing Authorization header
MalformedAuthorizationHeader:
summary: Malformed Authorization header
value:
code: invalid_access_token
message: Malformed Authorization header
ThrottledTooManyRequests:
summary: Throttled because too many requests
value:
code: too_many_requests
message: Throttled because too many requests
FailedToReadRequestBody:
summary: Failed to read request body
value:
code: bad_request_body
message: Failed to read request body
ExpectedIntegerQueryParam:
summary: Expected integer for query parameter
value:
code: bad_query_params
message: "Expected integer for query parameter `{key}` but found {value}"
ExpectedLongQueryParam:
summary: Expected long for query parameter
value:
code: bad_query_params
message: "Expected long for query parameter `{key}` but found {value}"
ExpectedLongListQueryParam:
summary: Expected long list for query parameter
value:
code: bad_query_params
message: "Expected long list for query parameter `{key}` but found {value}"
TooManyQueryParamValues:
summary: Expected 1 query parameter but found multiple
value:
code: bad_query_params
message: "Expected 1 query parameter {key} but found {count}"
MissingRequiredQueryParam:
summary: Missing required query parameter
value:
code: bad_query_params
message: "Missing required query parameter: {key}"
ConfidentialClientCorsError:
summary: Confidential clients must not authenticate via CORS requests
value:
code: unauthorized_client
message: Confidential clients must not authenticate via CORS requests
InvalidUriError:
summary: The request URI could not be parsed
value:
code: bad_request_params
message: "Invalid URI: {uri}"
InvalidOriginError:
summary: The Origin header could not be parsed
value:
code: bad_request_params
message: "Invalid Origin: {origin}"
InvalidIdsError:
summary: One or more IDs could not be deobfuscated
value:
code: invalid_field
message: "Invalid Ids: {ids}"
IntegrationAccessDeniedError:
summary: Not allowed to access the integration
value:
code: permission_denied
message: "Not allowed to access integration with client id {clientId}"
EndpointNoLongerAvailableError:
summary: This endpoint is no longer available
value:
code: endpoint_gone
message: This endpoint is no longer available
InProgressExportJobExample:
summary: In progress job
value:
job:
id: e08861ae-3b29-45db-8dc1-1fe0bf7f1cc8
status: in_progress
SuccessExportJobExample:
summary: Successfully completed job
value:
job:
id: e08861ae-3b29-45db-8dc1-1fe0bf7f1cc8
status: success
urls:
- https://export-download.canva.com/...
FailedExportJobExample:
summary: Failed job
value:
job:
id: e08861ae-3b29-45db-8dc1-1fe0bf7f1cc8
status: failed
error:
code: license_required
message: User doesn't have the required license to export in PRO quality.
ExportInvalidDesignIdError:
summary: Request design ID does not match expected format.
value:
code: invalid_request
message: "{designId} does not match expected format for designId"
UnsupportedDesignType:
summary: Export not supported for this design type.
value:
code: bad_request_body
message: "{formatType} export not supported for this design type"
SvgExportUnavailableError:
summary: SVG export is currently unavailable.
value:
code: feature_not_available
message: SVG Export is currently unavailable
ClientThrottleError:
summary: Too many requests for client.
value:
code: too_many_requests
message: Too many export requests for client
ClientDailyThrottleError:
summary: Too many daily requests for client.
value:
code: too_many_requests
message: Too many daily export requests for client
UserThrottleError:
summary: Too many requests for user.
value:
code: too_many_requests
message: Too many export requests for user
UserDailyThrottleError:
summary: Too many daily requests for user.
value:
code: too_many_requests
message: Too many daily export requests for user
DesignThrottleError:
summary: Too many requests for design.
value:
code: too_many_requests
message: Too many export requests for design
ExportJobPermissionDeniedError:
summary: Not allowed to access export job.
value:
code: permission_denied
message: Not allowed to access export job
ExportJobExpiredError:
summary: Export job result has expired.
value:
code: not_found
message: export job result has expired
ExportJobResultPermissionDeniedError:
summary: Not allowed to access export job result.
value:
code: permission_denied
message: Not allowed to access export job result
UnsupportedFormatError:
summary: Export format not supported for requested page(s).
value:
code: bad_request_body
message: "{formatType} export not supported for requested page(s) [{pageNumbers}]"
InvalidPageRangeError:
summary: Requested invalid page range for design.
value:
code: bad_request_body
message: "Requested page(s) [{badPageNumbers}] of a design with {maxPageNumber}\
\ page(s)"
TransparentBackgroundNotAllowedError:
summary: User's plan does not allow exporting PNGs with transparent background.
value:
code: bad_request_params
message: Users on the Canva Free plan can not export PNGs with transparent
background.
LicenseRequiredError:
summary: User doesn't have the required license to export in PRO quality.
value:
code: license_required
message: User doesn't have the required license to export in PRO quality
ExportDesignNotFoundError:
summary: Design not found.
value:
code: design_not_found
message: "Design with id '{designId}' not found"
DesignPermissionDeniedError:
summary: Not allowed to access design.
value:
code: permission_denied
message: "Not allowed to access design with id {designId}"
PrintPartnerUnsupportedDesignTypeError:
summary: Print partner export not supported for this design type.
value:
code: bad_request_body
message: Print partner export not supported for this design type
PrintPartnerUnsupportedDesignError:
summary: Print partner export not supported for this design.
value:
code: bad_request_body
message: Print partner export not supported for this design
PrintPartnerExportForbidden:
summary: Client does not have permission to create a Print Partner export.
value:
code: permission_denied
message: Client does not have permission to create a Print Partner export
ExportScaleFactorOutsideRangeError:
summary: Requested dimensions exceed expected bounds.
value:
code: bad_request_body
message: Requested dimensions exceed expected bounds
ResourceUnavailableError:
summary: One or more of the resources in the design did not upload properly.
value:
code: permission_denied
message: One or more of the resources in the design did not upload properly
EmbeddedMediaError:
summary: The design contains embedded media that no longer work.
value:
code: permission_denied
message: The design contains embedded media that no longer work
InvalidItemIdError:
summary: The item ID does not match any known ID format.
value:
code: invalid_field
message: "The item id `{value}` is invalid"
InvalidFolderIdError:
summary: The provided ID is not a valid folder ID.
value:
code: invalid_field
message: "The folder id `{value}` is invalid"
FolderNotFoundError:
summary: The folder was not found
value:
code: folder_not_found
message: Folder not found
ParentFolderNotFoundError:
summary: The parent folder was not found
value:
code: folder_not_found
message: Parent folder not found
FolderAccessNotAllowedError:
summary: Not allowed to access the folder
value:
code: permission_denied
message: "{message}"
TargetFolderSizeLimitReachedError:
summary: The target folder has reached its size limit
value:
code: quota_exceeded
message: Target folder has reached size limit
ListItemsInvalidContinuationError:
summary: The provided continuation token is invalid
value:
code: bad_query_params
message: "{message}"
FolderInvalidRequestParametersError:
summary: The request parameters are invalid
value:
code: bad_request_body
message: Invalid request parameters
RootFolderNotSupportedError:
summary: "The root ID is an alias, not a folder"
value:
code: bad_request_params
message: The 'root' ID is an alias to list items without a folder. It's not
a folder.
UploadsFolderNotAllowedError:
summary: The operation is not allowed on the uploads folder
value:
code: permission_denied
message: "{method} is not allowed on the 'uploads' folder."
ToFolderSameAsItemError:
summary: The destination folder can't be the same as the item being moved
value:
code: bad_request_params
message: '''to_folder_id'' and ''item_id'' cannot be the same.'
MoveUploadsFolderNotAllowedError:
summary: Not allowed to move the Uploads folder
value:
code: permission_denied
message: Not allowed to move the Uploads folder.
ToFolderNotFoundError:
summary: The destination folder was not found
value:
code: folder_not_found
message: "To folder {folderId} not found"
ItemInMultipleFoldersError:
summary: The item exists in multiple folders
value:
code: item_in_multiple_folders
message: The item lives in multiple folders. Please move it to the new folder
via Canva Desktop App or Canva in a browser.
SharedDesignNotAllowedInRootError:
summary: Shared designs are not allowed in the root folder
value:
code: permission_denied
message: Shared designs are not allowed in the root folder
FolderItemNotFoundError:
summary: The folder item was not found
value:
code: not_found
message: "Folder item '{itemId}' not found"
FolderItemAccessNotAllowedError:
summary: Not allowed to access the folder item
value:
code: permission_denied
message: "Not allowed to access folder item '{itemId}'"
ModelCapacityReached:
summary: The requested image generation model has reached capacity
value:
code: model_capacity_reached
message: The requested model has reached capacity. Try again later or choose
a different model.
ImageGenerationNotEnabledError:
summary: Image generation is not enabled for this client
value:
code: permission_denied
message: Image generation is not enabled
ImageGenerationJobNotFoundError:
summary: The image generation job was not found
value:
code: not_found
message: "Image generation job not found: {jobId}"
InProgressImageTransformationJobExample:
summary: In progress job
value:
job:
id: 450a76e7-f96f-43ae-9c37-0e1ce492ac72
status: in_progress
SuccessImageTransformationJobExample:
summary: Successfully completed job
value:
job:
status: success
result:
asset:
id: Msd59349ff
type: image
name: My Awesome Upload with the background removed
tags:
- image
- holiday
- best day ever
owner:
user_id: oU123456AbCdE
team_id: oB123456AbCdE
created_at: 1377396000
updated_at: 1692928800
thumbnail:
width: 595
height: 335
url: https://document-export.canva.com/Vczz9/zF9vzVtdADc/2/thumbnail/0001.png?
url: https://media-transformation.canva.com/Vczz9/zF9vzVtdADc/result.png?
FailedImageTransformationJobExample:
summary: Failed job
value:
job:
status: failed
error:
code: no_foreground_found
message: "No foreground subject was found in the image, so there is no\
\ background to remove."
UnsupportedAssetTypeError:
summary: The asset is not an image asset
value:
code: unsupported_content_type
message: "Asset is not an image asset: {assetId}"
AssetNotReadyError:
summary: "The asset is still being uploaded, so it can't be transformed yet"
value:
code: asset_not_ready
message: "Asset is still being uploaded and has no image to transform yet:\
\ {assetId}"
ImageTransformationNotEnabledError:
summary: Image transformation is not enabled for this client
value:
code: permission_denied
message: Image transformation is not enabled
ImageTransformationJobNotFoundError:
summary: The image transformation job was not found
value:
code: not_found
message: "Image transformation job not found: {jobId}"
InvalidMergeJobTypeError:
summary: Invalid merge job type
value:
code: invalid_request
message: "Invalid merge job type: {jobType}"
MergeJobNotFoundError:
summary: Merge job not found
value:
code: not_found
message: "Merge job '{jobId}' not found"
MergeJobForbiddenError:
summary: Not allowed to access this merge job
value:
code: permission_denied
message: Not allowed to access this merge job
MergeDesignNotFoundError:
summary: Design not found for merge operation
value:
code: not_found
message: "Design '{designId}' not found"
DesignForbiddenError:
summary: Not allowed to access design
value:
code: permission_denied
message: "Not allowed to access design '{designId}'"
InvalidPageNumberError:
summary: Invalid page number
value:
code: bad_request_params
message: "Page number {pageNumber} is out of range (design has {totalPages}\
\ pages)"
OperationNotSupportedError:
summary: Operation not supported
value:
code: bad_request_params
message: "{message}"
UnsupportedPageTypeError:
summary: Unsupported page type
value:
code: bad_request_params
message: "Source design '{designId}' has unsupported page type: {pageType}.\
\ Only fixed pages are supported."
UnsupportedDocumentTypeError:
summary: Unsupported document type
value:
code: bad_request_params
message: "Design '{designId}' has unsupported document type: {documentType}."
InvalidOperationError:
summary: Invalid operation
value:
code: bad_request_params
message: "Invalid operation: {message}"
RequestTooLargeError:
summary: Request too large
value:
code: bad_request_params
message: "The request size exceeds the maximum allowed limit. Try reducing\
\ the number of pages per request, using simpler page content, or splitting\
\ into multiple smaller operations."
UnauthorizedPrivateResourceError:
summary: Unauthorized access to private resource
value:
code: permission_denied
message: Source design contains private resources that you don't have access
to.
InvalidTokenError:
summary: The token supplied is neither an access token nor a refresh token.
value:
code: bad_request_params
message: Token is neither an access or refresh token
InvalidRequestError:
summary: The request is invalid.
value:
code: invalid_request
message: Invalid request
UnauthorizedClientError:
summary: The client must be authenticated using basic auth or body parameters.
value:
code: unauthorized_client
message: The client must either be authenticated using basic auth or body
parameters.
InvalidRefreshToken:
summary: The refresh token is invalid.
value:
code: invalid_grant
message: Invalid refresh token
ClientIdBodyParamMultipleValues:
summary: client_id body parameter has multiple values
value:
code: invalid_field
message: client_id body param must have a single value
ClientIdBodyParamBlank:
summary: client_id body parameter is blank or empty
value:
code: invalid_field
message: client_id body param must not be blank or empty
ClientSecretBodyParamMultipleValues:
summary: client_secret body parameter has multiple values
value:
code: invalid_field
message: client_secret body param must have a single value
ClientIdBasicAuthParamBlank:
summary: client_id basic auth parameter is blank or empty
value:
code: invalid_field
message: client_id basic auth parameter must not be blank or empty
SecretBasicAuthParamBlank:
summary: secret basic auth parameter is blank or empty
value:
code: invalid_field
message: secret basic auth parameter must not be blank or empty
BadRequestBodyTooLarge:
summary: Request body too large
value:
code: bad_request_body
message: Request body too large
ClientSecretInvalid:
summary: Client secret is invalid (Unauthorized)
value:
code: invalid_access_token
message: "Client secret is invalid for {clientAppId}"
AccessTokenMissing:
summary: Access token is missing
value:
code: invalid_access_token
message: Access token is missing
TokenExchangeInvalidRequest:
summary: The token exchange request is invalid.
value:
code: invalid_request
message: "{description}"
TokenExchangeInvalidClient:
summary: The client credentials are invalid.
value:
code: invalid_client
message: "{description}"
TokenExchangeInvalidGrant:
summary: "The provided authorization grant is invalid, expired, or revoked."
value:
code: invalid_grant
message: "{description}"
TokenExchangeUnauthorizedClient:
summary: The client is not authorized to use this grant type.
value:
code: unauthorized_client
message: "{description}"
TokenExchangeUnauthorizedUser:
summary: The user is not authorized.
value:
code: unauthorized_user
message: "{description}"
TokenExchangeUnsupportedGrantType:
summary: The grant type is not supported.
value:
code: unsupported_grant_type
message: "{description}"
TokenExchangeInvalidScope:
summary: "The requested scope is invalid, unknown, or malformed."
value:
code: invalid_scope
message: "{description}"
TooManyTokenExchangeRequests:
summary: Too many token exchange requests.
value:
code: too_many_requests
message: "Too many {grantType} requests"
InProgressResizeJobExample:
summary: In progress job
value:
job:
id: 450a76e7-f96f-43ae-9c37-0e1ce492ac72
status: in_progress
SuccessResizeJobExample:
summary: Successfully completed job
value:
job:
id: 450a76e7-f96f-43ae-9c37-0e1ce492ac72
status: success
result:
design:
id: DAGirp_1ZUA
title: My summer holiday
thumbnail:
width: 595
height: 335
url: https://document-export.canva.com/Vczz9/zF9vzVtdADc/2/thumbnail/0001.png?
urls:
edit_url: https://www.canva.com/design/DAGhRehVa2c/0L_1s4UXSpZhls8EtPaRKw/edit
view_url: https://www.canva.com/design/DAGhRehVa2c/0L_1s4UXSpZhls8EtPaRKw/view
created_at: 1742856750
updated_at: 1742856752
page_count: 5
trial_information:
uses_remaining: 0
upgrade_url: https://www.canva.com/?tailoringUpsellDialog=GENERIC_C4W
FailedResizeJobExample:
summary: Failed job
value:
job:
id: 450a76e7-f96f-43ae-9c37-0e1ce492ac72
status: failed
error:
code: design_resize_error
message: Failed to resize the design
UnsupportedDesignTypeError:
summary: Unsupported design type
value:
code: bad_request_params
message: "Canva designs can't be resized to the selected design type: `{designTypeName}`"
MissingResizeCapabilityError:
summary: The user's plan does not include the resize feature
value:
code: permission_denied
message: "Not allowed to access createDesignResizeJob, requires one of capabilities\
\ [resize]."
InvalidDesignTypeInputError:
summary: The design type must be custom or preset
value:
code: bad_request_params
message: "Invalid design type provided. Design type must be one of custom\
\ or preset, but was {designType}"
DimensionsBelowMinimumError:
summary: The requested dimensions are below the minimum size
value:
code: invalid_request
message: "width or height cannot be less than {minDimension}px"
DimensionsAboveMaximumError:
summary: The requested dimensions are above the maximum size
value:
code: invalid_request
message: "width or height cannot be more than {maxDimension}px"
AreaAboveMaximumError:
summary: The requested dimensions exceed the maximum design area
value:
code: invalid_request
message: width and height is above the maximum allowed area for a design
DesignNotResizableError:
summary: The design can't be resized to the desired type
value:
code: bad_request_params
message: The Canva design provided can't be resized to the desired type
PageIndexOutOfBoundsError:
summary: The page number is out of bounds
value:
code: bad_request_params
message: The page number provided is out of bounds.
ResponsivePagesNotSupportedError:
summary: Responsive pages can't be resized
value:
code: bad_request_params
message: Responsive type pages are not supported to Magic Resize
ControlledPagesNotSupportedError:
summary: Controlled pages can't be resized
value:
code: bad_request_params
message: Controlled type pages are not supported to Magic Resize
ResizeDesignNotFoundError:
summary: The design to resize was not found
value:
code: design_not_found
message: "Design with id '{designId}' not found"
DesignResizeNotAllowedError:
summary: Not allowed to resize the design
value:
code: permission_denied
message: "Not allowed to resize document with ID {designId}"
ResizeJobNotFoundError:
summary: The design resize job was not found
value:
code: not_found
message: "Job {jobId} not found"
FeatureQuotaExceededError:
summary: Feature quota exceeded
value:
code: quota_exceeded
message: Free resize quota has been exceeded. Present the `upsell_url` to
the user and prompt them to upgrade their Canva account to continue using
the resize feature.
upsell_url: "{upsellUrl}"
UserNotFoundError:
summary: The user was not found.
value:
code: user_not_found
message: User not found
parameters:
appId:
description: The app ID.
explode: false
in: path
name: appId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
brandTemplateId:
description: The brand template ID.
explode: false
in: path
name: brandTemplateId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
threadId:
description: The ID of the thread.
example: KeAbiEAjZEj
explode: false
in: path
name: threadId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
replyId:
description: The ID of the reply.
example: KeAZEAjijEb
explode: false
in: path
name: replyId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
designId:
description: The design ID.
explode: false
in: path
name: designId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
transactionIdParameter:
description: The editing transaction ID.
example: EDT123456
explode: false
in: path
name: transactionId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
pageIndicesParameter:
description: |-
The request with all the page indices
Pages are indexed using one-based numbering, so the first page in a design has the index value `1`.
explode: false
in: query
name: page_indices
required: true
schema:
example:
- 2
- 3
- 4
items:
format: int32
maximum: 500
minimum: 1
type: integer
maxItems: 4
type: array
style: form
exportId:
description: The export job ID.
explode: false
in: path
name: exportId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
fileIdParameter:
description: The file ID.
explode: false
in: path
name: fileId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
folderIdParameter:
description: The folder ID.
example: FAF2lZtloor
explode: false
in: path
name: folderId
required: true
schema:
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
style: simple
featureId:
explode: false
in: path
name: featureId
required: true
schema:
$ref: '#/components/schemas/FeatureId'
style: simple
feature_quota_limit:
explode: true
in: query
name: feature_quota_limit
required: false
schema:
$ref: '#/components/schemas/FeatureQuotaLimit'
style: form
interval:
description: The interval at which the usage resets. 'never' means lifetime
quota that never resets.
explode: true
in: query
name: interval
required: false
schema:
$ref: '#/components/schemas/Interval'
style: form
responses:
CommonCreditQuotaError:
content:
application/json:
examples:
credit_quota_exceeded:
$ref: '#/components/examples/CreditQuotaExceededError'
credit_quota_cooldown:
$ref: '#/components/examples/CreditQuotaCooldownError'
schema:
$ref: '#/components/schemas/CreditQuotaError'
description: Credit Quota Exceeded
x-http-status-code: 429
CommonPaymentRequiredError:
content:
application/json:
examples:
user_payment_required:
$ref: '#/components/examples/UserPaymentRequiredError'
app_payment_required:
$ref: '#/components/examples/AppPaymentRequiredError'
schema:
$ref: '#/components/schemas/Error'
description: Payment Required
x-http-status-code: 402
CommonBadRequest:
content:
application/json:
examples:
BadRequestFieldError:
$ref: '#/components/examples/BadRequestFieldError'
MissingRequiredHeaderError:
$ref: '#/components/examples/MissingRequiredHeaderError'
MissingAccessTokenError:
$ref: '#/components/examples/MissingAccessTokenError'
MissingClientCredentialsError:
$ref: '#/components/examples/MissingClientCredentialsError'
ContentTypeHeaderValueMissing:
$ref: '#/components/examples/ContentTypeHeaderValueMissing'
ContentTypeHeaderValueInvalid:
$ref: '#/components/examples/ContentTypeHeaderValueInvalid'
ValidatingClientFailed:
$ref: '#/components/examples/ValidatingClientFailed'
ValidatingClientFailedWithCode:
$ref: '#/components/examples/ValidatingClientFailedWithCode'
ClientSecretInvalidError:
$ref: '#/components/examples/ClientSecretInvalidError'
InvalidClientCredentialsValue:
$ref: '#/components/examples/InvalidClientCredentialsValue'
InvalidClientCredentialsBase64Encoding:
$ref: '#/components/examples/InvalidClientCredentialsBase64Encoding'
FailedToReadRequestBody:
$ref: '#/components/examples/FailedToReadRequestBody'
ExpectedIntegerQueryParam:
$ref: '#/components/examples/ExpectedIntegerQueryParam'
ExpectedLongQueryParam:
$ref: '#/components/examples/ExpectedLongQueryParam'
ExpectedLongListQueryParam:
$ref: '#/components/examples/ExpectedLongListQueryParam'
TooManyQueryParamValues:
$ref: '#/components/examples/TooManyQueryParamValues'
MissingRequiredQueryParam:
$ref: '#/components/examples/MissingRequiredQueryParam'
ConfidentialClientCorsError:
$ref: '#/components/examples/ConfidentialClientCorsError'
InvalidUriError:
$ref: '#/components/examples/InvalidUriError'
InvalidOriginError:
$ref: '#/components/examples/InvalidOriginError'
InvalidIdsError:
$ref: '#/components/examples/InvalidIdsError'
schema:
$ref: '#/components/schemas/Error'
description: Bad Request
x-http-status-code: 400
CommonUnauthorized:
content:
application/json:
examples:
InvalidClientError:
$ref: '#/components/examples/InvalidClientError'
InvalidAccessToken:
$ref: '#/components/examples/InvalidAccessToken'
MissingClientCredentialsOrBodyAuthError:
$ref: '#/components/examples/MissingClientCredentialsOrBodyAuthError'
MalformedAuthorizationHeaderComponents:
$ref: '#/components/examples/MalformedAuthorizationHeaderComponents'
MalformedAuthorizationHeaderMode:
$ref: '#/components/examples/MalformedAuthorizationHeaderMode'
TokenIntrospectionFailed:
$ref: '#/components/examples/TokenIntrospectionFailed'
RevokedAccessToken:
$ref: '#/components/examples/RevokedAccessToken'
MissingAuthorizationHeader:
$ref: '#/components/examples/MissingAuthorizationHeader'
MalformedAuthorizationHeader:
$ref: '#/components/examples/MalformedAuthorizationHeader'
schema:
$ref: '#/components/schemas/Error'
description: Unauthorized
x-http-status-code: 401
CommonForbidden:
content:
application/json:
examples:
MissingScopeError:
$ref: '#/components/examples/MissingScopeError'
UserRoleRequiredError:
$ref: '#/components/examples/UserRoleRequiredError'
IntegrationAccessDeniedError:
$ref: '#/components/examples/IntegrationAccessDeniedError'
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
x-http-status-code: 403
CommonNotFound:
content:
application/json:
examples:
EndpointNotFoundError:
$ref: '#/components/examples/EndpointNotFoundError'
schema:
$ref: '#/components/schemas/Error'
description: Not Found
x-http-status-code: 404
CommonGone:
content:
application/json:
examples:
EndpointNoLongerAvailableError:
$ref: '#/components/examples/EndpointNoLongerAvailableError'
schema:
$ref: '#/components/schemas/Error'
description: Gone
x-http-status-code: 410
CommonTooManyRequests:
content:
application/json:
examples:
TooManyRequestsError:
$ref: '#/components/examples/TooManyRequestsError'
ThrottledTooManyRequests:
$ref: '#/components/examples/ThrottledTooManyRequests'
schema:
$ref: '#/components/schemas/Error'
description: Too Many Requests
x-http-status-code: 429
schemas:
CreditQuotaUsageSummary:
description: A summary of the caller's credit quota usage at the time of the
request.
properties:
used_percentage:
description: |-
The percentage of the caller's credit quota that has been consumed in the current
billing interval, from 0 to 100.
format: int32
maximum: 100
minimum: 0
type: integer
resets_at:
description: |-
Unix timestamp (seconds from the Unix epoch) of when the credit quota resets for
the caller.
format: int64
type: integer
using_bonus_credits:
description: |-
Whether the caller is currently consuming bonus credits (credits beyond their base
plan allocation).
type: boolean
type: object
CreditQuotaSuccessInfo:
allOf:
- $ref: '#/components/schemas/CreditQuotaUsageSummary'
- properties:
usage_review_link:
description: |-
A URL to the Canva credit usage dashboard where the caller can review their
current credit consumption. Not present if unavailable.
type: string
type: object
description: Credit quota usage information returned on a successful generation
request.
CreditQuotaErrorInfo:
allOf:
- $ref: '#/components/schemas/CreditQuotaUsageSummary'
- properties:
upgrade_url:
description: |-
URL built from the user's current plan and eligibility for an AI pass. Not present
if no upgrade path is available (e.g. already on highest plan or ineligible for AI pass).
type: string
cooldown_ends_at:
description: |-
Unix timestamp (seconds from the Unix epoch) of when the cooldown period ends. Only
set when `code` is `credit_quota_cooldown`. Not present for `credit_quota_exceeded`
errors.
format: int64
type: integer
is_admin:
description: |-
Whether the caller is a team admin. Allows clients to tailor error messaging
(e.g. "contact your admin" vs "upgrade your plan").
type: boolean
generation_pending:
description: |-
True if another generation is currently in flight and consuming quota. Only
meaningful for paid users with cooldown enabled. Not present for free users where this
cannot be determined.
type: boolean
required:
- is_admin
type: object
description: |-
Credit quota information returned when a request is rejected due to quota exhaustion
or a cooldown period.
CreditQuotaError:
allOf:
- $ref: '#/components/schemas/Error'
- properties:
quota_usage:
allOf:
- $ref: '#/components/schemas/CreditQuotaErrorInfo'
description: Credit quota usage at the time of the error. Not present
if quota data is unavailable.
type: object
description: |-
Returned when a request is rejected because the caller has exceeded their credit quota
or is in a cooldown period after heavy usage.
GetDesignAnalyticsResponse:
description: Aggregated analytics metrics for a design.
properties:
average_view_duration_seconds:
description: The average view duration in seconds.
example: 42
format: int64
type: integer
total_view_duration_seconds:
description: The total view duration in seconds.
example: 5040
format: int64
type: integer
unique_view_count:
description: The number of unique viewers.
example: 87
format: int64
type: integer
total_view_count:
description: The total number of views.
example: 120
format: int64
type: integer
required:
- total_view_count
- unique_view_count
type: object
GetDesignAnalyticsViewersResponse:
description: Successful response from a `getDesignAnalyticsViewers` request.
properties:
items:
description: The list of viewers.
items:
$ref: '#/components/schemas/Viewer'
type: array
continuation:
description: |-
If the success response contains a continuation token, there are more viewers you can list. You can use this token as a query parameter and retrieve more viewers from the list, for example `/v1/designs/{designId}/analytics/viewers?continuation={continuation}`.
To retrieve all viewers, you might need to make multiple requests.
example: RkFGMgXlsVTDbMd:MR3L0QjiaUzycIAjx0yMyuNiV0OildoiOwL0x32G4NjNu4FwtAQNxowUQNMMYN
type: string
required:
- items
type: object
Viewer:
description: A viewer and their engagement metrics for the design.
properties:
viewer_id:
description: An opaque identifier for the viewer. Use this value when filtering
page view results by viewer.
example: b2d44753-f996-46ff-8f01-d4143911550f
type: string
user:
allOf:
- $ref: '#/components/schemas/TeamUser'
description: The user details of the viewer. This is omitted for viewers
whose identity is not visible.
last_viewed_at:
description: "When the viewer most recently opened the design, as a Unix\
\ timestamp (in seconds since the Unix Epoch)."
example: 1748044800
format: int64
type: integer
viewer_type:
$ref: '#/components/schemas/DesignAnalyticsViewerType'
visibility:
$ref: '#/components/schemas/DesignAnalyticsViewerVisibility'
total_view_duration_seconds:
description: "The total time this viewer has spent viewing the design, in\
\ seconds."
example: 312
format: int64
type: integer
first_viewed_at:
description: "When the viewer first viewed the design, as a Unix timestamp\
\ (in seconds since the Unix Epoch)."
example: 1745452800
format: int64
type: integer
pages_viewed:
description: The number of pages this viewer viewed for more than one second.
example: 8
format: int64
type: integer
form_factor:
$ref: '#/components/schemas/DesignAnalyticsViewerFormFactor'
device_operating_system:
description: The simplified operating system name for the viewer's device.
example: macOS
type: string
city_country:
description: The viewer location as city and country. This is only returned
for anonymous viewers.
example: "Sydney, Australia"
type: string
total_view_count:
description: The number of times this viewer opened the design.
example: 14
format: int64
type: integer
required:
- last_viewed_at
- viewer_id
- viewer_type
- visibility
type: object
DesignAnalyticsViewerType:
description: How the viewer accessed the design.
enum:
- editor
- commenter
- viewer
type: string
x-enum-descriptions:
- The viewer accessed the design with edit access.
- The viewer accessed the design with comment access.
- The viewer accessed the design with view-only access.
DesignAnalyticsViewerVisibility:
description: How this viewer should be presented to the caller.
enum:
- shown
- anonymous
- opt_out
- another_team
- deleted
type: string
x-enum-descriptions:
- "The viewer's identity is visible, and their user details are included."
- "The viewer is anonymous, so their identity is not available."
- "The viewer has opted out of design analytics, but some data was already collected\
\ for this viewer previosly."
- "The viewer belongs to a different team, so their identity is not shared."
- The viewer's account has been deleted.
DesignAnalyticsViewerFormFactor:
description: The device form factor used to view the design.
enum:
- small
- large
type: string
x-enum-descriptions:
- "A small device, such as a phone."
- "A large device, such as a laptop, desktop, or large tablet."
GetDesignAnalyticsViewsOverTimeResponse:
description: Successful response from a `getDesignAnalyticsViewsOverTime` request.
properties:
items:
description: The list of time buckets.
items:
$ref: '#/components/schemas/ViewsAtTime'
type: array
continuation:
description: |-
If the success response contains a continuation token, there are more time buckets you can list. You can use this token as a query parameter and retrieve more time buckets from the list, for example `/v1/designs/{designId}/analytics/views-over-time?continuation={continuation}`.
To retrieve all time buckets, you might need to make multiple requests.
example: RkFGMgXlsVTDbMd:MR3L0QjiaUzycIAjx0yMyuNiV0OildoiOwL0x32G4NjNu4FwtAQNxowUQNMMYN
type: string
required:
- items
type: object
ViewsAtTime:
description: A single time bucket of view counts.
properties:
count:
description: The number of views in this bucket.
example: 15
format: int64
type: integer
bucket_start_at:
description: "When this time bucket starts, as a Unix timestamp (in seconds\
\ since the Unix Epoch)."
example: 1745452800
format: int64
type: integer
required:
- bucket_start_at
- count
type: object
GetDesignAnalyticsPageViewsRequest:
description: Filters and pagination controls for page-level analytics.
properties:
page_ids:
description: The design page IDs to retrieve view duration data for.
example:
- PBBKfZml7MRHRQVw
- PBBKfZml7Mghjsdg
items:
example: PBBKfZml7MRHRQVw
type: string
maxItems: 100
minItems: 1
type: array
limit:
default: 50
description: The maximum number of page results to return per page.
example: 50
format: int32
maximum: 100
minimum: 1
type: integer
continuation:
description: |-
If the success response contains a continuation token, there are more page results you can list. You can use this token in the request body and retrieve more page results from the list.
To retrieve all page results, you might need to make multiple requests.
example: RkFGMgXlsVTDbMd:MR3L0QjiaUzycIAjx0yMyuNiV0OildoiOwL0x32G4NjNu4FwtAQNxowUQNMMYN
type: string
filter:
$ref: '#/components/schemas/PageViewFilter'
required:
- page_ids
type: object
PageViewFilter:
description: A filter for page view data.
discriminator:
mapping:
by_viewer: '#/components/schemas/PageViewFilterByViewer'
for_editor: '#/components/schemas/PageViewFilterForEditor'
by_link: '#/components/schemas/PageViewFilterByLink'
propertyName: type
oneOf:
- $ref: '#/components/schemas/PageViewFilterByViewer'
- $ref: '#/components/schemas/PageViewFilterForEditor'
- $ref: '#/components/schemas/PageViewFilterByLink'
type: object
PageViewFilterByViewer:
properties:
type:
enum:
- by_viewer
example: by_viewer
type: string
link_id:
description: Filters to viewer traffic from a specific trackable link. Omit
this field to target viewer traffic that did not come from a trackable
link.
example: hddb98a3716
type: string
viewer_id:
description: The viewer ID to filter by.
example: b2d44753-f996-46ff-8f01-d4143911550f
type: string
required:
- type
- viewer_id
type: object
PageViewFilterForEditor:
properties:
type:
enum:
- for_editor
example: for_editor
type: string
required:
- type
type: object
PageViewFilterByLink:
properties:
type:
enum:
- by_link
example: by_link
type: string
link_id:
description: The trackable link ID to filter by.
example: hddb98a3716
type: string
required:
- link_id
- type
type: object
GetDesignAnalyticsPageViewsResponse:
description: Successful response from a `getDesignAnalyticsPageViews` request.
properties:
items:
description: The list of page view durations.
items:
$ref: '#/components/schemas/PageViewDuration'
type: array
continuation:
description: |-
If the success response contains a continuation token, there are more page results you can list. You can use this token in the request body and retrieve more page results from the list.
To retrieve all page results, you might need to make multiple requests.
example: RkFGMgXlsVTDbMd:MR3L0QjiaUzycIAjx0yMyuNiV0OildoiOwL0x32G4NjNu4FwtAQNxowUQNMMYN
type: string
required:
- items
type: object
PageViewDuration:
description: View duration metrics for a single page.
properties:
page_id:
description: The page ID. This is omitted for design types that do not support
page IDs.
example: PBBKfZml7MRHRQVw
type: string
total_view_duration_seconds:
description: "The total time spent viewing this page, in seconds."
example: 1860
format: int64
type: integer
average_duration_seconds:
description: "The average time spent viewing this page, in seconds. This\
\ is omitted for `by_viewer` filters."
example: 21.5
format: double
type: number
unique_view_count:
description: The number of unique viewers for this page. This is omitted
for `by_viewer` filters.
example: 87
format: int64
type: integer
required:
- total_view_duration_seconds
type: object
GetDesignAnalyticsLinksResponse:
description: Successful response from a `getDesignAnalyticsLinks` request.
properties:
items:
description: The list of trackable links.
items:
$ref: '#/components/schemas/TrackableLink'
type: array
continuation:
description: |-
If the success response contains a continuation token, there are more links you can list. You can use this token as a query parameter and retrieve more links from the list, for example `/v1/designs/{designId}/analytics/links?continuation={continuation}`.
To retrieve all links, you might need to make multiple requests.
example: RkFGMgXlsVTDbMd:MR3L0QjiaUzycIAjx0yMyuNiV0OildoiOwL0x32G4NjNu4FwtAQNxowUQNMMYN
type: string
required:
- items
type: object
TrackableLink:
description: Metrics for a trackable link.
properties:
link_id:
description: The ID of the trackable link.
example: hddb98a3716
type: string
name:
description: The user-visible name of the trackable link.
example: Newsletter link
type: string
total_view_count:
description: The total number of views for this link.
example: 64
format: int64
type: integer
unique_view_count:
description: The number of unique viewers for this link.
example: 41
format: int64
type: integer
total_view_duration_seconds:
description: "The total time this link has been viewed, in seconds."
example: 2580
format: int64
type: integer
average_view_duration_seconds:
description: "The average time this link has been viewed, in seconds."
example: 40
format: int64
type: integer
last_viewed_at:
description: "When this link was most recently viewed, as a Unix timestamp\
\ (in seconds since the Unix Epoch)."
example: 1748044800
format: int64
type: integer
required:
- link_id
type: object
GetAppJwksResponse:
properties:
keys:
description: |-
The value of the "keys" parameter is an array of JWK values. The order of keys has no
meaning.
items:
$ref: '#/components/schemas/JsonWebKey'
type: array
required:
- keys
type: object
CreateUrlAssetUploadJobRequest:
properties:
name:
description: A name for the asset.
example: My Awesome Asset
maxLength: 255
minLength: 1
type: string
url:
description: The URL of the file to import. This URL must be accessible
from the internet and be publicly available.
example: https://example.com/my_asset_to_upload.jpg
maxLength: 2048
minLength: 8
type: string
required:
- name
- url
type: object
CreateUrlAssetUploadJobResponse:
properties:
job:
$ref: '#/components/schemas/AssetUploadJob'
required:
- job
type: object
GetUrlAssetUploadJobResponse:
properties:
job:
$ref: '#/components/schemas/AssetUploadJob'
required:
- job
type: object
GetAssetResponse:
properties:
asset:
$ref: '#/components/schemas/Asset'
required:
- asset
type: object
UpdateAssetRequest:
properties:
name:
description: |-
The name of the asset. This is shown in the Canva UI.
When this field is undefined or empty, nothing is updated.
example: My Awesome Upload
maxLength: 50
type: string
tags:
description: |-
The replacement tags for the asset.
When this field is undefined, nothing is updated.
example:
- image
- holiday
- best day ever
items:
maxLength: 50
type: string
maxItems: 50
type: array
type: object
UpdateAssetResponse:
properties:
asset:
$ref: '#/components/schemas/Asset'
required:
- asset
type: object
Asset:
description: "The asset object, which contains metadata about the asset."
properties:
type:
$ref: '#/components/schemas/AssetType'
id:
description: The ID of the asset.
example: Msd59349ff
type: string
name:
description: The name of the asset.
example: My Awesome Upload
type: string
tags:
description: |-
The user-facing tags attached to the asset.
Users can add these tags to their uploaded assets, and they can search their uploaded
assets in the Canva UI by searching for these tags. For information on how users use
tags, see the
[Canva Help Center page on asset tags](https://www.canva.com/help/add-edit-tags/).
example:
- image
- holiday
- best day ever
items:
type: string
type: array
import_status:
$ref: '#/components/schemas/ImportStatus'
created_at:
description: |-
When the asset was added to Canva, as a Unix timestamp (in seconds since the Unix
Epoch).
example: 1377396000
format: int64
type: integer
updated_at:
description: |-
When the asset was last updated in Canva, as a Unix timestamp (in seconds since the
Unix Epoch).
example: 1692928800
format: int64
type: integer
owner:
$ref: '#/components/schemas/TeamUserSummary'
thumbnail:
$ref: '#/components/schemas/Thumbnail'
metadata:
$ref: '#/components/schemas/AssetMetadata'
required:
- created_at
- id
- name
- owner
- tags
- type
- updated_at
type: object
AssetMetadata:
description: Type-specific metadata for the asset.
discriminator:
mapping:
image: '#/components/schemas/ImageMetadata'
video: '#/components/schemas/VideoMetadata'
propertyName: type
oneOf:
- $ref: '#/components/schemas/ImageMetadata'
- $ref: '#/components/schemas/VideoMetadata'
type: object
ImageMetadata:
properties:
type:
enum:
- image
type: string
width:
description: The width of the image in pixels.
example: 1920
format: int32
type: integer
height:
description: The height of the image in pixels.
example: 1080
format: int32
type: integer
smart_tags:
description: AI-generated tags for the image.
example:
- landscape
- sunset
- mountains
- nature
items:
maxLength: 50
type: string
type: array
required:
- type
type: object
VideoMetadata:
properties:
type:
enum:
- video
type: string
width:
description: The width of the video in pixels.
example: 1920
format: int32
type: integer
height:
description: The height of the video in pixels.
example: 1080
format: int32
type: integer
duration:
description: The duration of the video in seconds.
example: 60
format: int32
type: integer
required:
- height
- type
- width
type: object
AssetSummary:
description: An object representing an asset with associated metadata.
properties:
type:
$ref: '#/components/schemas/AssetType'
id:
description: The ID of the asset.
example: Msd59349ff
type: string
name:
description: The name of the asset.
example: My Awesome Upload
type: string
tags:
description: |-
The user-facing tags attached to the asset.
Users can add these tags to their uploaded assets, and they can search their uploaded
assets in the Canva UI by searching for these tags. For information on how users use
tags, see the
[Canva Help Center page on asset tags](https://www.canva.com/help/add-edit-tags/).
example:
- image
- holiday
- best day ever
items:
type: string
type: array
created_at:
description: |-
When the asset was added to Canva, as a Unix timestamp (in seconds since the Unix
Epoch).
example: 1377396000
format: int64
type: integer
updated_at:
description: |-
When the asset was last updated in Canva, as a Unix timestamp (in seconds since the
Unix Epoch).
example: 1692928800
format: int64
type: integer
thumbnail:
$ref: '#/components/schemas/Thumbnail'
required:
- created_at
- id
- name
- tags
- type
- updated_at
type: object
AssetType:
description: Type of an asset.
enum:
- image
- video
example: image
type: string
ImportStatus:
deprecated: true
description: The import status of the asset.
properties:
state:
$ref: '#/components/schemas/ImportStatusState'
error:
$ref: '#/components/schemas/ImportError'
required:
- state
type: object
ImportStatusState:
deprecated: true
description: State of the import job for an uploaded asset.
enum:
- failed
- in_progress
- success
example: success
type: string
ImportError:
deprecated: true
description: "If the import fails, this object provides details about the error."
properties:
code:
$ref: '#/components/schemas/ImportErrorCode'
message:
description: A human-readable description of what went wrong.
type: string
required:
- code
- message
type: object
ImportErrorCode:
deprecated: true
description: |
A short string indicating why the upload failed. This field can be used to handle errors programmatically.
enum:
- file_too_big
- import_failed
type: string
CreateAssetUploadJobResponse:
properties:
job:
$ref: '#/components/schemas/AssetUploadJob'
required:
- job
type: object
GetAssetUploadJobResponse:
properties:
job:
$ref: '#/components/schemas/AssetUploadJob'
required:
- job
type: object
AssetUploadJob:
description: The status of the asset upload job.
example:
id: e08861ae-3b29-45db-8dc1-1fe0bf7f1cc8
status: success
asset:
id: Msd59349ff
type: image
name: My Awesome Upload
tags:
- image
- holiday
- best day ever
owner:
user_id: oU123456AbCdE
team_id: oB123456AbCdE
created_at: 1377396000
updated_at: 1692928800
thumbnail:
width: 595
height: 335
url: https://document-export.canva.com/Vczz9/zF9vzVtdADc/2/thumbnail/0001.png?
properties:
id:
description: The ID of the asset upload job.
example: e08861ae-3b29-45db-8dc1-1fe0bf7f1cc8
type: string
status:
$ref: '#/components/schemas/AssetUploadStatus'
error:
$ref: '#/components/schemas/AssetUploadError'
asset:
$ref: '#/components/schemas/Asset'
required:
- id
- status
type: object
AssetUploadStatus:
description: Status of the asset upload job.
enum:
- failed
- in_progress
- success
example: success
type: string
AssetUploadError:
description: "If the upload fails, this object provides details about the error."
properties:
code:
$ref: '#/components/schemas/AssetUploadErrorCode'
message:
description: A human-readable description of what went wrong.
example: Failed to import because the file is too big.
type: string
required:
- code
- message
type: object
AssetUploadErrorCode:
description: |-
A short string indicating why the upload failed. This field can be used to handle errors
programmatically.
enum:
- file_too_big
- import_failed
- fetch_failed
example: file_too_big
type: string
AssetUploadMetadata:
description: Metadata for the asset being uploaded.
properties:
name_base64:
description: |-
The asset's name, encoded in Base64.
The maximum length of an asset name in Canva (unencoded) is 50 characters.
Base64 encoding allows names containing emojis and other special
characters to be sent using HTTP headers.
For example, "My Awesome Upload 🚀" Base64 encoded
is `TXkgQXdlc29tZSBVcGxvYWQg8J+agA==`.
example: TXkgQXdlc29tZSBVcGxvYWQg8J+agA==
minLength: 1
type: string
required:
- name_base64
type: object
CreateDesignAutofillJobRequest:
description: |-
Body parameters for creating a new autofill job. Use the `type` discriminator to choose
the autofill mode:
- Use `create_from_brand_template` to create a new design from a brand template.
NOTE: For backward compatibility, if `type` isn't specified in the request,
the request type is assumed to be `create_from_brand_template`.
discriminator:
mapping:
create_from_brand_template: '#/components/schemas/CreateFromBrandTemplateAutofillJobRequest'
create_from_design: '#/components/schemas/CreateFromDesignAutofillJobRequest'
update_design: '#/components/schemas/UpdateDesignAutofillJobRequest'
propertyName: type
oneOf:
- $ref: '#/components/schemas/CreateFromBrandTemplateAutofillJobRequest'
- $ref: '#/components/schemas/CreateFromDesignAutofillJobRequest'
- $ref: '#/components/schemas/UpdateDesignAutofillJobRequest'
CreateFromBrandTemplateAutofillJobRequest:
description: Create a new autofilled design from a brand template.
properties:
type:
description: "For backward compatibility, if `type` isn't specified in the\
\ request, the request type is assumed to be `create_from_brand_template`."
enum:
- create_from_brand_template
type: string
brand_template_id:
description: ID of the input brand template.
example: DAFVztcvd9z
type: string
title:
description: |-
Title to use for the autofilled design.
If no design title is provided, the autofilled design will have the same title as the brand template.
example: My autofilled design
maxLength: 255
minLength: 1
type: string
data:
additionalProperties:
$ref: '#/components/schemas/DatasetValue'
description: Data object containing the data fields and values to autofill.
example:
cute_pet_image_of_the_day:
type: image
asset_id: Msd59349ff
cute_pet_video_of_the_day:
type: video
asset_id: VAHCkrNUANI
cute_pet_witty_pet_says:
type: text
text: It was like this when I got here!
cute_pet_sales_chart:
type: chart
chart_data:
column_configs:
- name: Geographic Region
type: string
- name: Sales (millions AUD)
type: number
- name: Target (millions AUD)
type: number
- name: Target met?
type: boolean
- name: Date met
type: date
rows:
- cells:
- type: string
value: Asia Pacific
- type: number
value: 10.2
- type: number
value: 10
- type: boolean
value: true
- type: date
value: 1721944387
- cells:
- type: string
value: EMEA
- type: number
value: 13.8
- type: number
value: 14
- type: boolean
value: false
- type: date
cute_pet_sales_sheet:
type: sheet
sheet_data:
column_configs:
- name: Geographic Region
type: string
- name: Sales (millions AUD)
type: number
- name: Target (millions AUD)
type: number
- name: Target met?
type: boolean
- name: Date met
type: date
rows:
- cells:
- type: string
value: Asia Pacific
- type: number
value: 10.2
- type: number
value: 10
- type: boolean
value: true
- type: date
value: 1721944387
- cells:
- type: string
value: EMEA
- type: number
value: 13.8
- type: number
value: 14
- type: boolean
value: false
- type: date
type: object
required:
- brand_template_id
- data
- type
type: object
CreateFromDesignAutofillJobRequest:
description: Create a new autofilled design from an existing design that contains
autofill data fields.
properties:
type:
enum:
- create_from_design
type: string
design_id:
description: ID of the design to use as the autofill source.
example: DAFVztcvd9z
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
title:
description: |-
Title to use for the autofilled design.
If no design title is provided, the autofilled design will have the same title as the source design.
example: My autofilled design
maxLength: 255
minLength: 1
type: string
data:
additionalProperties:
$ref: '#/components/schemas/DatasetValue'
description: Data object containing the data fields and values to autofill.
example:
cute_pet_image_of_the_day:
type: image
asset_id: Msd59349ff
cute_pet_video_of_the_day:
type: video
asset_id: VAHCkrNUANI
cute_pet_witty_pet_says:
type: text
text: It was like this when I got here!
cute_pet_sales_chart:
type: chart
chart_data:
column_configs:
- name: Geographic Region
type: string
- name: Sales (millions AUD)
type: number
- name: Target (millions AUD)
type: number
- name: Target met?
type: boolean
- name: Date met
type: date
rows:
- cells:
- type: string
value: Asia Pacific
- type: number
value: 10.2
- type: number
value: 10
- type: boolean
value: true
- type: date
value: 1721944387
- cells:
- type: string
value: EMEA
- type: number
value: 13.8
- type: number
value: 14
- type: boolean
value: false
- type: date
cute_pet_sales_sheet:
type: sheet
sheet_data:
column_configs:
- name: Geographic Region
type: string
- name: Sales (millions AUD)
type: number
- name: Target (millions AUD)
type: number
- name: Target met?
type: boolean
- name: Date met
type: date
rows:
- cells:
- type: string
value: Asia Pacific
- type: number
value: 10.2
- type: number
value: 10
- type: boolean
value: true
- type: date
value: 1721944387
- cells:
- type: string
value: EMEA
- type: number
value: 13.8
- type: number
value: 14
- type: boolean
value: false
- type: date
type: object
required:
- data
- design_id
- type
type: object
UpdateDesignAutofillJobRequest:
description: Autofill an existing design in place with the provided data.
properties:
type:
enum:
- update_design
type: string
design_id:
description: ID of the design to autofill in place.
example: DAFVztcvd9z
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
data:
additionalProperties:
$ref: '#/components/schemas/DatasetValue'
description: Data object containing the data fields and values to autofill.
example:
cute_pet_image_of_the_day:
type: image
asset_id: Msd59349ff
cute_pet_video_of_the_day:
type: video
asset_id: VAHCkrNUANI
cute_pet_witty_pet_says:
type: text
text: It was like this when I got here!
cute_pet_sales_chart:
type: chart
chart_data:
column_configs:
- name: Geographic Region
type: string
- name: Sales (millions AUD)
type: number
- name: Target (millions AUD)
type: number
- name: Target met?
type: boolean
- name: Date met
type: date
rows:
- cells:
- type: string
value: Asia Pacific
- type: number
value: 10.2
- type: number
value: 10
- type: boolean
value: true
- type: date
value: 1721944387
- cells:
- type: string
value: EMEA
- type: number
value: 13.8
- type: number
value: 14
- type: boolean
value: false
- type: date
cute_pet_sales_sheet:
type: sheet
sheet_data:
column_configs:
- name: Geographic Region
type: string
- name: Sales (millions AUD)
type: number
- name: Target (millions AUD)
type: number
- name: Target met?
type: boolean
- name: Date met
type: date
rows:
- cells:
- type: string
value: Asia Pacific
- type: number
value: 10.2
- type: number
value: 10
- type: boolean
value: true
- type: date
value: 1721944387
- cells:
- type: string
value: EMEA
- type: number
value: 13.8
- type: number
value: 14
- type: boolean
value: false
- type: date
type: object
required:
- data
- design_id
- type
type: object
CreateDesignAutofillJobResponse:
properties:
job:
$ref: '#/components/schemas/DesignAutofillJob'
required:
- job
type: object
DatasetValue:
description: The data field to autofill.
discriminator:
mapping:
image: '#/components/schemas/DatasetImageValue'
video: '#/components/schemas/DatasetVideoValue'
text: '#/components/schemas/DatasetTextValue'
chart: '#/components/schemas/DatasetChartValue'
sheet: '#/components/schemas/DatasetSheetValue'
propertyName: type
oneOf:
- $ref: '#/components/schemas/DatasetImageValue'
- $ref: '#/components/schemas/DatasetVideoValue'
- $ref: '#/components/schemas/DatasetTextValue'
- $ref: '#/components/schemas/DatasetChartValue'
- $ref: '#/components/schemas/DatasetSheetValue'
type: object
Dataset:
additionalProperties:
$ref: '#/components/schemas/DatasetValue'
description: Data object containing the data fields and values to autofill.
example:
cute_pet_image_of_the_day:
type: image
asset_id: Msd59349ff
cute_pet_video_of_the_day:
type: video
asset_id: VAHCkrNUANI
cute_pet_witty_pet_says:
type: text
text: It was like this when I got here!
cute_pet_sales_chart:
type: chart
chart_data:
column_configs:
- name: Geographic Region
type: string
- name: Sales (millions AUD)
type: number
- name: Target (millions AUD)
type: number
- name: Target met?
type: boolean
- name: Date met
type: date
rows:
- cells:
- type: string
value: Asia Pacific
- type: number
value: 10.2
- type: number
value: 10
- type: boolean
value: true
- type: date
value: 1721944387
- cells:
- type: string
value: EMEA
- type: number
value: 13.8
- type: number
value: 14
- type: boolean
value: false
- type: date
cute_pet_sales_sheet:
type: sheet
sheet_data:
column_configs:
- name: Geographic Region
type: string
- name: Sales (millions AUD)
type: number
- name: Target (millions AUD)
type: number
- name: Target met?
type: boolean
- name: Date met
type: date
rows:
- cells:
- type: string
value: Asia Pacific
- type: number
value: 10.2
- type: number
value: 10
- type: boolean
value: true
- type: date
value: 1721944387
- cells:
- type: string
value: EMEA
- type: number
value: 13.8
- type: number
value: 14
- type: boolean
value: false
- type: date
type: object
DatasetImageValue:
description: If the data field is an image field.
properties:
type:
enum:
- image
type: string
asset_id:
description: '`asset_id` of the image to insert into the template element.'
example: Msd59349ff
type: string
required:
- asset_id
- type
type: object
DatasetVideoValue:
description: If autofilling a video into an image data field.
properties:
type:
enum:
- video
type: string
asset_id:
description: '`asset_id` of the video to insert into the template element.'
example: VAHCkrNUANI
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
required:
- asset_id
- type
type: object
DatasetTextValue:
description: If the data field is a text field.
properties:
type:
enum:
- text
type: string
text:
description: Text to insert into the template element.
example: It was like this when I got here!
type: string
required:
- text
- type
type: object
DatasetChartValue:
description: |-
If the data field is a chart.
Note the following behavior:
- If `column_configs` is not provided, the first row is assumed to contain column headers where applicable.
- Chart autofill supports a maximum of 100 rows and 20 columns.
- `number` cells with formatting metadata are not currently supported for autofill and will result in an error response.
- `media` cells are not supported for chart autofill and will result in an error response.
properties:
type:
enum:
- chart
type: string
chart_data:
$ref: '#/components/schemas/DataTable'
required:
- chart_data
- type
type: object
DatasetSheetValue:
description: |-
If the data field is a sheet element.
Note the following behavior:
- `number` cells with formatting metadata are not currently supported for autofill and will result in an error response.
- `media` cells are not supported for sheet autofill and will result in an error response.
properties:
type:
enum:
- sheet
type: string
sheet_data:
$ref: '#/components/schemas/DataTable'
required:
- sheet_data
- type
type: object
GetDesignAutofillJobResponse:
properties:
job:
$ref: '#/components/schemas/DesignAutofillJob'
required:
- job
type: object
DesignAutofillJob:
description: Details about the autofill job.
properties:
id:
description: ID of the asynchronous job that is creating the design using
the provided data.
example: 450a76e7-f96f-43ae-9c37-0e1ce492ac72
type: string
status:
$ref: '#/components/schemas/DesignAutofillStatus'
result:
$ref: '#/components/schemas/DesignAutofillJobResult'
error:
$ref: '#/components/schemas/AutofillError'
required:
- id
- status
type: object
DesignAutofillJobResult:
description: Result of the design autofill job. Only present if job status is
`success`.
discriminator:
mapping:
create_design: '#/components/schemas/CreateDesignAutofillJobResult'
update_design: '#/components/schemas/UpdateDesignAutofillJobResult'
propertyName: type
oneOf:
- $ref: '#/components/schemas/CreateDesignAutofillJobResult'
- $ref: '#/components/schemas/UpdateDesignAutofillJobResult'
type: object
CreateDesignAutofillJobResult:
description: A new autofilled design has been created and saved to the user's
root folder.
properties:
type:
enum:
- create_design
type: string
design:
$ref: '#/components/schemas/DesignSummary'
trial_information:
$ref: '#/components/schemas/AutofillTrialInformation'
required:
- design
- type
type: object
UpdateDesignAutofillJobResult:
description: The existing design has been autofilled in place.
properties:
type:
enum:
- update_design
type: string
design:
$ref: '#/components/schemas/DesignSummary'
required:
- design
- type
type: object
DesignAutofillStatus:
description: Status of the design autofill job.
enum:
- in_progress
- success
- failed
example: success
type: string
AutofillErrorCode:
enum:
- autofill_error
- thumbnail_generation_error
- create_design_error
- design_approval_error
- trial_quota_exceeded
- design_update_error
type: string
x-enum-descriptions:
- The service encountered an error when autofilling your brand template.
- The service encountered an error when generating a thumbnail for the autofilled
design.
- The service encountered an error when saving the autofilled design.
- The service encountered an error when applying design approval settings to
the autofilled design.
- The user has exceeded their autofill trial quota.
- The service encountered an error when saving the updated design.
AutofillError:
description: "If the autofill job fails, this object provides details about\
\ the error."
properties:
code:
$ref: '#/components/schemas/AutofillErrorCode'
message:
description: A human-readable description of what went wrong.
type: string
required:
- code
- message
type: object
AutofillTrialInformation:
description: |-
WARNING: Trials and trial information are a [preview feature](https://www.canva.dev/docs/apps/rest-apis/#preview-apis).
There might be unannounced breaking changes to this feature which won't produce a new API version.
Trial information for users on a Canva plan that doesn't include autofill access. These
users have a limited number of autofill uses. Once the trial is exhausted, users must
upgrade their Canva plan (such as to Canva Pro, Canva Teams, or Canva Enterprise) to
continue using the Autofill API.
properties:
uses_remaining:
description: The number of uses remaining in the free trial.
example: 0
format: int32
minimum: 0
type: integer
upgrade_url:
description: The URL for a user to upgrade their Canva account to a plan
with autofill access.
example: https://www.canva.com/pro/
type: string
required:
- upgrade_url
- uses_remaining
type: object
DatasetFilter:
default: any
enum:
- any
- non_empty
type: string
x-enum-descriptions:
- Brand templates with and without dataset definitions.
- Brand templates with one or more data fields defined.
ListBrandTemplatesResponse:
properties:
continuation:
description: |-
If the success response contains a continuation token, the user has access to more
brand templates you can list. You can use this token as a query parameter and retrieve
more templates from the list, for example
`/v1/brand-templates?continuation={continuation}`.
To retrieve all the brand templates available to the user, you might need to make
multiple requests.
example: RkFGMgXlsVTDbMd:MR3L0QjiaUzycIAjx0yMyuNiV0OildoiOwL0x32G4NjNu4FwtAQNxowUQNMMYN
type: string
items:
description: The list of brand templates.
items:
$ref: '#/components/schemas/BrandTemplate'
type: array
required:
- items
type: object
GetBrandTemplateResponse:
description: Successful response from a `getBrandTemplate` request.
properties:
brand_template:
$ref: '#/components/schemas/BrandTemplate'
required:
- brand_template
type: object
BrandTemplate:
description: An object representing a brand template with associated metadata.
properties:
id:
description: The brand template ID.
example: DEMzWSwy3BI
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
title:
description: "The brand template title, as shown in the Canva UI."
example: Advertisement Template
type: string
view_url:
description: A URL Canva users can visit to view the brand template.
example: https://www.canva.com/design/DAE35hE8FA4/view
type: string
create_url:
description: A URL Canva users can visit to create a new design from the
template.
example: https://www.canva.com/design/DAE35hE8FA4/remix
type: string
thumbnail:
$ref: '#/components/schemas/Thumbnail'
created_at:
description: |-
When the brand template was created, as a Unix timestamp
(in seconds since the Unix Epoch).
example: 1704110400
format: int64
type: integer
updated_at:
description: |-
When the brand template was last updated, as a Unix timestamp
(in seconds since the Unix Epoch).
example: 1719835200
format: int64
type: integer
required:
- create_url
- created_at
- id
- title
- updated_at
- view_url
type: object
BrandTemplateSummary:
description: An object representing a brand template with associated metadata.
properties:
id:
description: The brand template ID.
example: DEMzWSwy3BI
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
title:
description: "The brand template title, as shown in the Canva UI."
example: Advertisement Template
type: string
view_url:
description: A URL Canva users can visit to view the brand template.
example: https://www.canva.com/design/DAE35hE8FA4/view
type: string
create_url:
description: A URL Canva users can visit to create a new design from the
template.
example: https://www.canva.com/design/DAE35hE8FA4/remix
type: string
thumbnail:
$ref: '#/components/schemas/Thumbnail'
created_at:
description: |-
When the brand template was created, as a Unix timestamp
(in seconds since the Unix Epoch).
example: 1704110400
format: int64
type: integer
updated_at:
description: |-
When the brand template was last updated, as a Unix timestamp
(in seconds since the Unix Epoch).
example: 1719835200
format: int64
type: integer
required:
- create_url
- created_at
- id
- title
- updated_at
- view_url
type: object
GetBrandTemplateDatasetResponse:
description: Successful response from a `getBrandTemplateDataset` request.
properties:
dataset:
additionalProperties:
$ref: '#/components/schemas/DataField'
description: |-
The dataset definition. It contains the data inputs available for use with the
[Create design autofill job API](https://www.canva.dev/docs/apps/rest-apis/reference/autofills/create-design-autofill-job/).
example:
cute_pet_image_of_the_day:
type: image
cute_pet_witty_pet_says:
type: text
cute_pet_sales_chart:
type: chart
type: object
type: object
PublishBrandTemplateRequest:
description: Request body for publishing a design as a brand template
properties:
design_id:
description: "The ID of the design to publish as a brand template. If this\
\ design is a draft of an existing brand template, that template will\
\ be updated. Otherwise, a new brand template is created."
example: DABCdesign123
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
required:
- design_id
type: object
PublishBrandTemplateResponse:
description: Response from a successful publishBrandTemplate request. Contains
the published brand template with all its metadata. Note that the `thumbnail`
field might be `null` initially as thumbnails are generated asynchronously.
properties:
brand_template:
$ref: '#/components/schemas/BrandTemplate'
required:
- brand_template
type: object
Capability:
description: |-
Some APIs are annotated with required capabilities. These endpoints require the user to
possess the required capabilities in order to be called successfully.
enum:
- analytics
- autofill
- background_removal
- brand_template
- design_generation
- export_png_transparency
- image_generation
- image_to_design_imports
- resize
- team_restricted_app
type: string
x-enum-descriptions:
- "Capability required to call the Design analytics APIs. Users that are members\
\ of a [Canva Enterprise](https://www.canva.com/enterprise/) organization\
\ have this capability."
- "Capability required to call autofill APIs. Users on a Canva plan with access\
\ to autofill (such as Canva Pro, Canva Teams, or Canva Enterprise) have this\
\ capability."
- Capability required to apply the `background_removal` transformation using
the Image transformation APIs. Users on a Canva plan with premium features
(such as Canva Pro) have this capability.
- "Capability required to use brand template APIs. Users on a Canva plan with\
\ access to brand templates (such as Canva Pro, Canva Teams, or Canva Enterprise)\
\ have this capability."
- "Capability required to call the Design Generation APIs. Users whose feature\
\ eligibility and [team permission settings](https://www.canva.com/en_au/help/setting-up-team-permissions/)\
\ allow both \"Canva AI\" and \"[Magic Design](https://www.canva.com/magic-design/)\"\
\ have this capability."
- Capability required to export designs in PNG with a transparent background.
Users on a paid Canva plan (such as Canva Pro) have this capability.
- "Capability required to call the Image Generation APIs. Users whose feature\
\ eligibility and [team permission settings](https://www.canva.com/en_au/help/setting-up-team-permissions/)\
\ allow both \"Canva AI\" and \"Magic Media\" have this capability."
- "Capability required to call the Image to Design Import APIs. Users whose\
\ [team permission settings](https://www.canva.com/en_au/help/setting-up-team-permissions/)\
\ allow both \"Canva AI\" and \"[Magic Layers](https://www.canva.com/magic-layers/)\"\
\ have this capability."
- Capability required to create design resize jobs. Users on a Canva plan with
premium features (such as Canva Pro) have this capability.
- "Capability required to create a team-restricted app. Users that are members\
\ of the [Canva Enterprise](https://www.canva.com/enterprise/) or the [Canva\
\ for Education](https://www.canva.com/education/) organization have this\
\ capability."
CreateCommentRequest:
properties:
attached_to:
$ref: '#/components/schemas/CommentObjectInput'
message:
description: |-
The comment message. This is the comment body shown in the Canva UI.
You can also mention users in your message by specifying their User ID and Team ID
using the format `[user_id:team_id]`. If the `assignee_id` parameter is specified, you
must mention the assignee in the message.
example: "Great work [oUnPjZ2k2yuhftbWF7873o:oBpVhLW22VrqtwKgaayRbP]!"
maxLength: 2048
minLength: 1
type: string
assignee_id:
description: |-
Lets you assign the comment to a Canva user using their User ID. You _must_ mention the
assigned user in the `message`.
example: oUnPjZ2k2yuhftbWF7873o
type: string
required:
- attached_to
- message
type: object
CreateReplyV2Request:
properties:
message_plaintext:
description: |-
The comment message of the reply in plaintext. This is the reply comment shown in the Canva UI.
You can also mention users in your message by specifying their User ID and Team ID
using the format `[user_id:team_id]`.
example: Thanks!
maxLength: 2048
minLength: 1
type: string
required:
- message_plaintext
type: object
CreateCommentResponse:
properties:
comment:
$ref: '#/components/schemas/ParentComment'
required:
- comment
type: object
CreateThreadResponse:
properties:
thread:
$ref: '#/components/schemas/Thread'
required:
- thread
type: object
CreateThreadRequest:
properties:
message_plaintext:
description: |-
The comment message in plaintext. This is the comment body shown in the Canva UI.
You can also mention users in your message by specifying their User ID and Team ID
using the format `[user_id:team_id]`. If the `assignee_id` parameter is specified, you
must mention the assignee in the message.
example: "Great work [oUnPjZ2k2yuhftbWF7873o:oBpVhLW22VrqtwKgaayRbP]!"
maxLength: 2048
minLength: 1
type: string
assignee_id:
description: |-
Lets you assign the comment to a Canva user using their User ID. You _must_ mention the
assigned user in the `message`.
example: oUnPjZ2k2yuhftbWF7873o
type: string
required:
- message_plaintext
type: object
CreateReplyV2Response:
properties:
reply:
$ref: '#/components/schemas/Reply'
required:
- reply
type: object
GetThreadResponse:
description: |-
Successful response from a `getThread` request.
The `comment` property is deprecated.
For details of a comment thread, please use the `thread` property.
properties:
comment:
$ref: '#/components/schemas/Comment'
thread:
$ref: '#/components/schemas/Thread'
type: object
GetReplyResponse:
description: Successful response from a `getReply` request.
properties:
reply:
$ref: '#/components/schemas/Reply'
required:
- reply
type: object
Comment:
deprecated: true
description: |-
The comment object, which contains metadata about the comment.
Deprecated in favor of the new `thread` object.
discriminator:
mapping:
parent: '#/components/schemas/ParentComment'
reply: '#/components/schemas/ReplyComment'
propertyName: type
oneOf:
- $ref: '#/components/schemas/ParentComment'
- $ref: '#/components/schemas/ReplyComment'
type: object
ParentComment:
deprecated: true
description: |-
Data about the comment, including the message, author, and
the object (such as a design) the comment is attached to.
properties:
type:
enum:
- parent
type: string
id:
description: |-
The ID of the comment.
You can use this ID to create replies to the comment using the [Create reply API](https://www.canva.dev/docs/apps/rest-apis/reference/comments/create-reply/).
example: KeAbiEAjZEj
type: string
attached_to:
$ref: '#/components/schemas/CommentObject'
message:
description: |-
The comment message. This is the comment body shown in the Canva UI.
User mentions are shown here in the format `[user_id:team_id]`.
example: "Great work [oUnPjZ2k2yuhftbWF7873o:oBpVhLW22VrqtwKgaayRbP]!"
type: string
author:
$ref: '#/components/schemas/User'
created_at:
description: |-
When the comment or reply was created, as a Unix timestamp
(in seconds since the Unix Epoch).
example: 1692928800
format: int64
type: integer
updated_at:
description: |-
When the comment or reply was last updated, as a Unix timestamp
(in seconds since the Unix Epoch).
example: 1692928900
format: int64
type: integer
mentions:
additionalProperties:
$ref: '#/components/schemas/TeamUser'
deprecated: true
description: The Canva users mentioned in the comment.
example:
oUnPjZ2k2yuhftbWF7873o:oBpVhLW22VrqtwKgaayRbP:
user_id: oUnPjZ2k2yuhftbWF7873o
team_id: oBpVhLW22VrqtwKgaayRbP
display_name: John Doe
type: object
assignee:
$ref: '#/components/schemas/User'
resolver:
$ref: '#/components/schemas/User'
required:
- author
- id
- mentions
- message
- type
type: object
ReplyComment:
deprecated: true
description: |-
Data about the reply comment, including the message, author, and
the object (such as a design) the comment is attached to.
properties:
type:
enum:
- reply
type: string
id:
description: The ID of the comment.
example: KeAZEAjijEb
type: string
attached_to:
$ref: '#/components/schemas/CommentObject'
message:
description: |-
The comment message. This is the comment body shown in the Canva UI.
User mentions are shown here in the format `[user_id:team_id]`.
example: Thanks!
type: string
author:
$ref: '#/components/schemas/User'
created_at:
description: |-
When the comment or reply was created, as a Unix timestamp
(in seconds since the Unix Epoch).
example: 1692929800
format: int64
type: integer
updated_at:
description: |-
When the comment or reply was last updated, as a Unix timestamp
(in seconds since the Unix Epoch).
example: 1692929900
format: int64
type: integer
mentions:
additionalProperties:
$ref: '#/components/schemas/TeamUser'
deprecated: true
description: The Canva users mentioned in the comment.
example:
oUnPjZ2k2yuhftbWF7873o:oBpVhLW22VrqtwKgaayRbP:
user_id: oUnPjZ2k2yuhftbWF7873o
team_id: oBpVhLW22VrqtwKgaayRbP
display_name: John Doe
type: object
thread_id:
description: |-
The ID of the comment thread this reply is in. This ID is the same as the `id` of the
parent comment.
example: KeAbiEAjZEj
type: string
required:
- author
- id
- mentions
- message
- thread_id
- type
type: object
CommentObject:
deprecated: true
description: Identifying information about the object (such as a design) that
the comment is attached to.
discriminator:
mapping:
design: '#/components/schemas/DesignCommentObject'
propertyName: type
example:
design_id: DAFVztcvd9z
type: design
oneOf:
- $ref: '#/components/schemas/DesignCommentObject'
type: object
DesignCommentObject:
deprecated: true
description: If the comment is attached to a Canva Design.
properties:
type:
enum:
- design
type: string
design_id:
description: The ID of the design this comment is attached to.
example: DAFVztcvd9z
type: string
required:
- design_id
- type
type: object
CommentObjectInput:
description: |-
An object containing identifying information for the design or other object you want to
attach the comment to.
discriminator:
mapping:
design: '#/components/schemas/DesignCommentObjectInput'
propertyName: type
example:
design_id: DAFVztcvd9z
type: design
oneOf:
- $ref: '#/components/schemas/DesignCommentObjectInput'
type: object
DesignCommentObjectInput:
description: If the comment is attached to a Canva Design.
properties:
type:
enum:
- design
type: string
design_id:
description: The ID of the design you want to attach this comment to.
example: DAFVztcvd9z
type: string
required:
- design_id
- type
type: object
CommentEventDeprecated:
deprecated: true
description: |-
Basic details about the comment.
The `comment` property is deprecated.
For details of the comment event, use the `comment_event` property instead.
properties:
type:
$ref: '#/components/schemas/CommentEventTypeEnum'
data:
$ref: '#/components/schemas/Comment'
required:
- data
- type
type: object
Mentions:
additionalProperties:
$ref: '#/components/schemas/TeamUser'
deprecated: true
description: The Canva users mentioned in the comment.
example:
oUnPjZ2k2yuhftbWF7873o:oBpVhLW22VrqtwKgaayRbP:
user_id: oUnPjZ2k2yuhftbWF7873o
team_id: oBpVhLW22VrqtwKgaayRbP
display_name: John Doe
type: object
CommentEventTypeEnum:
deprecated: true
description: The type of comment event.
enum:
- comment
- reply
- mention
- assign
- resolve
type: string
CommentEvent:
description: "The type of comment event, including additional type-specific\
\ properties."
discriminator:
mapping:
new: '#/components/schemas/NewCommentEvent'
assigned: '#/components/schemas/AssignedCommentEvent'
resolved: '#/components/schemas/ResolvedCommentEvent'
reply: '#/components/schemas/ReplyCommentEvent'
mention: '#/components/schemas/MentionCommentEvent'
propertyName: type
oneOf:
- $ref: '#/components/schemas/NewCommentEvent'
- $ref: '#/components/schemas/AssignedCommentEvent'
- $ref: '#/components/schemas/ResolvedCommentEvent'
- $ref: '#/components/schemas/ReplyCommentEvent'
- $ref: '#/components/schemas/MentionCommentEvent'
type: object
NewCommentEvent:
description: Event type for a new comment thread.
properties:
type:
enum:
- new
type: string
comment_url:
description: "A URL to the design, focused on the comment thread."
example: https://www.canva.com/design/3WCduQdjayTcPVM/z128cqanFu7E3/edit?ui=OdllGgZ4Snnq3MD8uI10bfA
type: string
comment:
$ref: '#/components/schemas/Thread'
required:
- comment
- comment_url
- type
type: object
AssignedCommentEvent:
description: Event type for a comment thread that has been assigned.
properties:
type:
enum:
- assigned
type: string
comment_url:
description: "A URL to the design, focused on the comment thread."
example: https://www.canva.com/design/3WCduQdjayTcPVM/z128cqanFu7E3/edit?ui=OdllGgZ4Snnq3MD8uI10bfA
type: string
comment:
$ref: '#/components/schemas/Thread'
required:
- comment
- comment_url
- type
type: object
ResolvedCommentEvent:
description: Event type for a comment thread that has been resolved.
properties:
type:
enum:
- resolved
type: string
comment_url:
description: "A URL to the design, focused on the comment thread."
example: https://www.canva.com/design/3WCduQdjayTcPVM/z128cqanFu7E3/edit?ui=OdllGgZ4Snnq3MD8uI10bfA
type: string
comment:
$ref: '#/components/schemas/Thread'
required:
- comment
- comment_url
- type
type: object
ReplyCommentEvent:
description: Event type for a reply to a comment thread.
properties:
type:
enum:
- reply
type: string
reply_url:
description: "A URL to the design, focused on the comment reply."
example: https://www.canva.com/design/3WCduQdjayTcPVM/z128cqanFu7E3/edit?ui=OdllGgZ4Snnq3MD8uI10bfA
type: string
reply:
$ref: '#/components/schemas/Reply'
required:
- reply
- reply_url
- type
type: object
MentionCommentEvent:
description: Event type for a mention in a comment thread or reply.
properties:
type:
enum:
- mention
type: string
content:
$ref: '#/components/schemas/MentionEventContent'
required:
- content
- type
type: object
MentionEventContent:
description: "The type of mention event content, along with additional type-specific\
\ properties."
discriminator:
mapping:
thread: '#/components/schemas/ThreadMentionEventContent'
reply: '#/components/schemas/ReplyMentionEventContent'
propertyName: type
oneOf:
- $ref: '#/components/schemas/ThreadMentionEventContent'
- $ref: '#/components/schemas/ReplyMentionEventContent'
type: object
ThreadMentionEventContent:
description: Content for a mention in a comment thread.
properties:
type:
enum:
- thread
type: string
comment_url:
description: "A URL to the design, focused on the comment thread."
example: https://www.canva.com/design/3WCduQdjayTcPVM/z128cqanFu7E3/edit?ui=OdllGgZ4Snnq3MD8uI10bfA
type: string
comment:
$ref: '#/components/schemas/Thread'
required:
- comment
- comment_url
- type
type: object
ReplyMentionEventContent:
description: Content for a mention in a comment reply.
properties:
type:
enum:
- reply
type: string
reply_url:
description: "A URL to the design, focused on the comment reply."
example: https://www.canva.com/design/3WCduQdjayTcPVM/z128cqanFu7E3/edit?ui=OdllGgZ4Snnq3MD8uI10bfA
type: string
reply:
$ref: '#/components/schemas/Reply'
required:
- reply
- reply_url
- type
type: object
ListRepliesResponse:
description: Successful response from a `listReplies` request.
properties:
continuation:
description: |-
If the success response contains a continuation token, the list contains more items
you can list. You can use this token as a query parameter and retrieve more items
from the list, for example `?continuation={continuation}`.
To retrieve all items, you might need to make multiple requests.
example: RkFGMgXlsVTDbMd:MR3L0QjiaUzycIAjx0yMyuNiV0OildoiOwL0x32G4NjNu4FwtAQNxowUQNMMYN
type: string
items:
items:
$ref: '#/components/schemas/Reply'
type: array
required:
- items
type: object
Thread:
description: |-
A discussion thread on a design.
The `type` of the thread can be found in the `thread_type` object, along with additional type-specific properties.
The `author` of the thread might be missing if that user account no longer exists.
properties:
id:
description: |-
The ID of the thread.
You can use this ID to create replies to the thread using the [Create reply API](https://www.canva.dev/docs/apps/rest-apis/reference/comments/create-reply/).
example: KeAbiEAjZEj
type: string
design_id:
description: The ID of the design that the discussion thread is on.
example: DAFVztcvd9z
type: string
thread_type:
$ref: '#/components/schemas/ThreadType'
author:
$ref: '#/components/schemas/User'
created_at:
description: |-
When the thread was created, as a Unix timestamp
(in seconds since the Unix Epoch).
example: 1692928800
format: int64
type: integer
updated_at:
description: |-
When the thread was last updated, as a Unix timestamp
(in seconds since the Unix Epoch).
example: 1692928900
format: int64
type: integer
required:
- created_at
- design_id
- id
- thread_type
- updated_at
type: object
ThreadType:
description: "The type of the discussion thread, along with additional type-specific\
\ properties."
discriminator:
mapping:
comment: '#/components/schemas/CommentThreadType'
suggestion: '#/components/schemas/SuggestionThreadType'
propertyName: type
oneOf:
- $ref: '#/components/schemas/CommentThreadType'
- $ref: '#/components/schemas/SuggestionThreadType'
type: object
CommentThreadType:
description: A comment thread.
properties:
type:
enum:
- comment
type: string
content:
$ref: '#/components/schemas/CommentContent'
mentions:
additionalProperties:
$ref: '#/components/schemas/UserMention'
description: The Canva users mentioned in the comment thread or reply.
example:
oUnPjZ2k2yuhftbWF7873o:oBpVhLW22VrqtwKgaayRbP:
tag: oUnPjZ2k2yuhftbWF7873o:oBpVhLW22VrqtwKgaayRbP
user:
user_id: oUnPjZ2k2yuhftbWF7873o
team_id: oBpVhLW22VrqtwKgaayRbP
display_name: John Doe
type: object
assignee:
$ref: '#/components/schemas/User'
resolver:
$ref: '#/components/schemas/User'
required:
- content
- mentions
- type
type: object
SuggestionThreadType:
description: A suggestion thread.
properties:
type:
enum:
- suggestion
type: string
suggested_edits:
items:
$ref: '#/components/schemas/SuggestedEdit'
minItems: 1
type: array
status:
$ref: '#/components/schemas/SuggestionStatus'
required:
- status
- suggested_edits
- type
type: object
SuggestedEdit:
description: "The type of the suggested edit, along with additional type-specific\
\ properties."
discriminator:
mapping:
add: '#/components/schemas/AddSuggestedEdit'
delete: '#/components/schemas/DeleteSuggestedEdit'
format: '#/components/schemas/FormatSuggestedEdit'
propertyName: type
oneOf:
- $ref: '#/components/schemas/AddSuggestedEdit'
- $ref: '#/components/schemas/DeleteSuggestedEdit'
- $ref: '#/components/schemas/FormatSuggestedEdit'
type: object
AddSuggestedEdit:
description: A suggestion to add some text.
properties:
type:
enum:
- add
type: string
text:
example: fantastic
type: string
required:
- text
- type
type: object
DeleteSuggestedEdit:
description: A suggestion to delete some text.
properties:
type:
enum:
- delete
type: string
text:
example: just
type: string
required:
- text
- type
type: object
FormatSuggestedEdit:
description: A suggestion to format some text.
properties:
type:
enum:
- format
type: string
format:
$ref: '#/components/schemas/SuggestionFormat'
required:
- format
- type
type: object
SuggestionStatus:
description: The current status of the suggestion.
enum:
- open
- accepted
- rejected
type: string
x-enum-descriptions:
- "A suggestion was made, but it hasn't been accepted or rejected yet."
- A suggestion was accepted and applied to the design.
- A suggestion was rejected and not applied to the design.
SuggestionFormat:
description: The suggested format change.
enum:
- font_family
- font_size
- font_weight
- font_style
- color
- background_color
- decoration
- strikethrough
- link
- letter_spacing
- line_height
- direction
- text_align
- list_marker
- list_level
- margin_inline_start
- text_indent
- font_size_modifier
- vertical_align
example: font_style
type: string
Reply:
description: |-
A reply to a thread.
The `author` of the reply might be missing if that user account no longer exists.
properties:
id:
description: The ID of the reply.
example: KeAZEAjijEb
type: string
design_id:
description: The ID of the design that the thread for this reply is attached
to.
example: DAFVztcvd9z
type: string
thread_id:
description: The ID of the thread this reply is in.
example: KeAbiEAjZEj
type: string
author:
$ref: '#/components/schemas/User'
content:
$ref: '#/components/schemas/CommentContent'
mentions:
additionalProperties:
$ref: '#/components/schemas/UserMention'
description: The Canva users mentioned in the comment thread or reply.
example:
oUnPjZ2k2yuhftbWF7873o:oBpVhLW22VrqtwKgaayRbP:
tag: oUnPjZ2k2yuhftbWF7873o:oBpVhLW22VrqtwKgaayRbP
user:
user_id: oUnPjZ2k2yuhftbWF7873o
team_id: oBpVhLW22VrqtwKgaayRbP
display_name: John Doe
type: object
created_at:
description: |-
When the reply was created, as a Unix timestamp
(in seconds since the Unix Epoch).
example: 1692929800
format: int64
type: integer
updated_at:
description: |-
When the reply was last updated, as a Unix timestamp
(in seconds since the Unix Epoch).
example: 1692929900
format: int64
type: integer
required:
- content
- created_at
- design_id
- id
- mentions
- thread_id
- updated_at
type: object
CommentContent:
description: The content of a comment thread or reply.
properties:
plaintext:
description: |-
The content in plaintext.
Any user mention tags are shown in the format `[user_id:team_id]`.
example: "Great work [oUnPjZ2k2yuhftbWF7873o:oBpVhLW22VrqtwKgaayRbP]!"
type: string
markdown:
description: |-
The content in markdown.
Any user mention tags are shown in the format `[user_id:team_id]`
example: "*_Great work_* [oUnPjZ2k2yuhftbWF7873o:oBpVhLW22VrqtwKgaayRbP]!"
type: string
required:
- plaintext
type: object
SuggestionEventType:
description: "The type of suggestion event, along with additional type-specific\
\ properties."
discriminator:
mapping:
new: '#/components/schemas/NewSuggestionEventType'
accepted: '#/components/schemas/AcceptedSuggestionEventType'
rejected: '#/components/schemas/RejectedSuggestionEventType'
reply: '#/components/schemas/ReplySuggestionEventType'
mention: '#/components/schemas/MentionSuggestionEventType'
propertyName: type
oneOf:
- $ref: '#/components/schemas/NewSuggestionEventType'
- $ref: '#/components/schemas/AcceptedSuggestionEventType'
- $ref: '#/components/schemas/RejectedSuggestionEventType'
- $ref: '#/components/schemas/ReplySuggestionEventType'
- $ref: '#/components/schemas/MentionSuggestionEventType'
type: object
NewSuggestionEventType:
description: Event type for a new suggestion.
properties:
type:
enum:
- new
type: string
suggestion_url:
description: "A URL to the design, focused on the suggestion."
example: https://www.canva.com/design/3WCduQdjayTcPVM/z128cqanFu7E3/edit?ui=OdllGgZ4Snnq3MD8uI10bfA
type: string
suggestion:
$ref: '#/components/schemas/Thread'
required:
- suggestion
- suggestion_url
- type
type: object
AcceptedSuggestionEventType:
description: Event type for a suggestion that has been accepted.
properties:
type:
enum:
- accepted
type: string
suggestion_url:
description: "A URL to the design, focused on the suggestion."
example: https://www.canva.com/design/3WCduQdjayTcPVM/z128cqanFu7E3/edit?ui=OdllGgZ4Snnq3MD8uI10bfA
type: string
suggestion:
$ref: '#/components/schemas/Thread'
required:
- suggestion
- suggestion_url
- type
type: object
RejectedSuggestionEventType:
description: Event type for a suggestion that has been rejected.
properties:
type:
enum:
- rejected
type: string
suggestion_url:
description: "A URL to the design, focused on the suggestion."
example: https://www.canva.com/design/3WCduQdjayTcPVM/z128cqanFu7E3/edit?ui=OdllGgZ4Snnq3MD8uI10bfA
type: string
suggestion:
$ref: '#/components/schemas/Thread'
required:
- suggestion
- suggestion_url
- type
type: object
ReplySuggestionEventType:
description: Event type for a reply to a suggestion.
properties:
type:
enum:
- reply
type: string
reply_url:
description: "A URL to the design, focused on the suggestion reply."
example: https://www.canva.com/design/3WCduQdjayTcPVM/z128cqanFu7E3/edit?ui=OdllGgZ4Snnq3MD8uI10bfA
type: string
reply:
$ref: '#/components/schemas/Reply'
required:
- reply
- reply_url
- type
type: object
MentionSuggestionEventType:
description: Event type for a mention in a reply to a suggestion.
properties:
type:
enum:
- mention
type: string
reply_url:
description: "A URL to the design, focused on the suggestion reply."
example: https://www.canva.com/design/3WCduQdjayTcPVM/z128cqanFu7E3/edit?ui=OdllGgZ4Snnq3MD8uI10bfA
type: string
reply:
$ref: '#/components/schemas/Reply'
required:
- reply
- reply_url
- type
type: object
UserMentions:
additionalProperties:
$ref: '#/components/schemas/UserMention'
description: The Canva users mentioned in the comment thread or reply.
example:
oUnPjZ2k2yuhftbWF7873o:oBpVhLW22VrqtwKgaayRbP:
tag: oUnPjZ2k2yuhftbWF7873o:oBpVhLW22VrqtwKgaayRbP
user:
user_id: oUnPjZ2k2yuhftbWF7873o
team_id: oBpVhLW22VrqtwKgaayRbP
display_name: John Doe
type: object
UserMention:
description: Information about the user mentioned in a comment thread or reply.
Each user mention is keyed using the user's user ID and team ID separated
by a colon (`user_id:team_id`).
properties:
tag:
description: The mention tag for the user mentioned in the comment thread
or reply content. This has the format of the user's user ID and team ID
separated by a colon (`user_id:team_id`).
example: oUnPjZ2k2yuhftbWF7873o:oBpVhLW22VrqtwKgaayRbP
type: string
user:
$ref: '#/components/schemas/TeamUser'
required:
- tag
- user
type: object
GetSigningPublicKeysResponse:
properties:
keys:
description: |-
A Json Web Key Set (JWKS) with public keys used for signing webhooks. You can use this JWKS
to verify that a webhook was sent from Canva.
example:
- kid: a418dc7d-ecc5-5c4b-85ce-e1104a8addbe
kty: OKP
crv: Ed25519
x: aIQtqd0nDfB-ug0DrzZbwTum-1ITdXvKxGFak_1VB2j
- kid: c8de5bec1-1b88-4ddaae04acc-ce415-5d7
kty: OKP
crv: Ed25519
x: m2d1FT-gfBXxIzKwdQVTra0D-aBq_ubZ1jI0GuvkDtn
items:
$ref: '#/components/schemas/EdDsaJwk'
type: array
required:
- keys
type: object
EdDsaJwk:
description: |-
A JSON Web Key Set (JWKS) using the Edwards-curve Digital Signature Algorithm (EdDSA), as
described in [RFC-8037](https://www.rfc-editor.org/rfc/rfc8037.html#appendix-A).
properties:
kid:
description: |-
The `kid` (key ID) is a unique identifier for a public key. When the keys used
to sign webhooks are rotated, you can use this ID to select the correct key
within a JWK Set during the key rollover. The `kid` value is case-sensitive.
type: string
kty:
description: |-
The `kty` (key type) identifies the cryptographic algorithm family used with
the key, such as "RSA" or "EC". Only Octet Key Pairs
(`OKPs`) are supported.
The `kty` value is case-sensitive. For more information on the `kty` property
and OKPs, see [RFC-8037 — "kty" (Key Type)
Parameter](https://www.rfc-editor.org/rfc/rfc8037.html#section-2).
type: string
crv:
description: |-
The `crv` (curve) property identifies the curve used for elliptical curve
encryptions. Only "Ed25519" is supported. For more information on the `crv`
property, see [RFC-8037 — Key Type
"OKP"](https://www.rfc-editor.org/rfc/rfc8037.html#section-2).
type: string
x:
description: |-
The `x` property is the public key of an elliptical curve encryption. The key
is Base64urlUInt-encoded. For more information on the `x` property, see
[RFC-8037 — "x" (X Coordinate)
Parameter](https://www.rfc-editor.org/rfc/rfc8037#section-2).
type: string
required:
- crv
- kid
- kty
- x
type: object
DataTable:
description: |-
Tabular data, structured in rows of cells.
- Each cell must have a data type configured.
- All rows must have the same number of cells.
- The number of entries in `column_configs` must match the number of columns in the data.
example:
column_configs:
- name: Geographic Region
type: string
- name: Sales (millions AUD)
type: number
- name: Target (millions AUD)
type: number
- name: Target met?
type: boolean
- name: Date met
type: date
- name: Logo
type: media
rows:
- cells:
- type: string
value: Asia Pacific
- type: number
value: 10.2
metadata:
formatting: "#,##0.0"
- type: number
value: 10
metadata:
formatting: "#,##0.0"
- type: boolean
value: true
- type: date
value: 1721944387
- type: media
value:
- type: image_upload
url: https://example.com/apac-logo.png
thumbnail_url: https://example.com/apac-logo-thumb.png
mime_type: image/png
ai_disclosure: none
- type: video_upload
url: https://example.com/apac-logo.mp4
thumbnail_image_url: https://example.com/apac-logo-thumb.png
thumbnail_video_url: https://example.com/apac-logo-thumb.mp4
mime_type: video/mp4
ai_disclosure: none
- cells:
- type: string
value: EMEA
- type: number
value: 13.8
metadata:
formatting: "#,##0.0"
- type: number
value: 14
metadata:
formatting: "#,##0.0"
- type: boolean
value: false
- type: date
- type: media
value: []
properties:
column_configs:
description: Column definitions with names and data types.
items:
$ref: '#/components/schemas/ColumnConfig'
type: array
rows:
description: Rows of data.
items:
$ref: '#/components/schemas/DataTableRow'
type: array
required:
- rows
type: object
ColumnConfig:
description: Configuration for a data table column.
properties:
name:
description: "Name for the column, displayed as header text."
type: string
type:
$ref: '#/components/schemas/ColumnDataType'
required:
- type
type: object
ColumnDataType:
description: Expected data type for cells in this column.
enum:
- string
- number
- date
- boolean
- media
- variant
type: string
x-enum-descriptions:
- String data
- Numeric data
- Date data
- Boolean data
- "Media data (such as images, videos, or combinations of both)"
- Mixed data types (use where the column contains cells of a combination of
data types)
DataTableRow:
description: A single row of tabular data.
properties:
cells:
description: |-
Cells of data in row.
All rows must have the same number of cells.
items:
$ref: '#/components/schemas/DataTableCell'
type: array
required:
- cells
type: object
DataTableCell:
description: A single tabular data cell.
discriminator:
mapping:
string: '#/components/schemas/StringDataTableCell'
number: '#/components/schemas/NumberDataTableCell'
boolean: '#/components/schemas/BooleanDataTableCell'
date: '#/components/schemas/DateDataTableCell'
media: '#/components/schemas/MediaCollectionDataTableCell'
propertyName: type
oneOf:
- $ref: '#/components/schemas/StringDataTableCell'
- $ref: '#/components/schemas/NumberDataTableCell'
- $ref: '#/components/schemas/BooleanDataTableCell'
- $ref: '#/components/schemas/DateDataTableCell'
- $ref: '#/components/schemas/MediaCollectionDataTableCell'
type: object
StringDataTableCell:
description: A string tabular data cell.
properties:
type:
enum:
- string
type: string
value:
maxLength: 10000
type: string
required:
- type
type: object
NumberDataTableCell:
description: A number tabular data cell.
properties:
type:
enum:
- number
type: string
value:
format: double
type: number
metadata:
$ref: '#/components/schemas/NumberCellMetadata'
required:
- type
type: object
NumberCellMetadata:
description: Formatting metadata for number cells.
properties:
formatting:
description: |-
Formatting pattern using Office Open XML Format.
These patterns control how numbers are displayed to users, including currency symbols,
decimal places, and separators.
type: string
type: object
BooleanDataTableCell:
description: A boolean tabular data cell.
properties:
type:
enum:
- boolean
type: string
value:
type: boolean
required:
- type
type: object
DateDataTableCell:
description: |-
A date tabular data cell.
Specified as a Unix timestamp (in seconds since the Unix Epoch).
properties:
type:
enum:
- date
type: string
value:
format: int64
type: integer
required:
- type
type: object
MediaCollectionDataTableCell:
description: Cell containing a media collection.
properties:
type:
enum:
- media
type: string
value:
description: |-
Media collection values.
Provide an empty array for an empty cell.
items:
$ref: '#/components/schemas/DataTableMedia'
maxItems: 20
type: array
required:
- type
- value
type: object
DataTableMedia:
discriminator:
mapping:
image_upload: '#/components/schemas/DataTableImageUpload'
video_upload: '#/components/schemas/DataTableVideoUpload'
propertyName: type
oneOf:
- $ref: '#/components/schemas/DataTableImageUpload'
- $ref: '#/components/schemas/DataTableVideoUpload'
DataTableImageUpload:
description: Options for uploading an image asset.
properties:
type:
enum:
- image_upload
type: string
url:
description: |-
The URL of the image file to upload.
This can be an external URL or a data URL.
type: string
thumbnail_url:
description: |-
The URL of a thumbnail image to display while the image is queued for upload.
This can be an external URL or a data URL.
type: string
mime_type:
$ref: '#/components/schemas/DataTableImageMimeType'
width:
description: The width of the image in pixels.
format: int32
type: integer
height:
description: The height of the image in pixels.
format: int32
type: integer
ai_disclosure:
$ref: '#/components/schemas/DataTableAiDisclosure'
required:
- ai_disclosure
- mime_type
- thumbnail_url
- type
- url
type: object
DataTableVideoUpload:
description: Options for uploading a video asset.
properties:
type:
enum:
- video_upload
type: string
url:
description: The URL of the video file to upload.
type: string
thumbnail_image_url:
description: |-
The URL of a thumbnail image to use as a fallback if thumbnailVideoUrl isn't provided.
This can be an external URL or a data URL.
type: string
thumbnail_video_url:
description: The URL of a thumbnail video to display while the video is
queued for upload.
type: string
mime_type:
$ref: '#/components/schemas/DataTableVideoMimeType'
width:
description: The width of the video in pixels.
format: int32
type: integer
height:
description: The height of the video in pixels.
format: int32
type: integer
ai_disclosure:
$ref: '#/components/schemas/DataTableAiDisclosure'
required:
- ai_disclosure
- mime_type
- thumbnail_image_url
- type
- url
type: object
DataTableImageMimeType:
description: The MIME type of an image file that's supported by Canva's backend.
enum:
- image/jpeg
- image/heic
- image/png
- image/svg+xml
- image/webp
- image/tiff
type: string
DataTableVideoMimeType:
description: The MIME type of a video file that's supported by Canva's backend.
enum:
- video/avi
- video/x-msvideo
- image/gif
- video/x-m4v
- video/x-matroska
- video/quicktime
- video/mp4
- video/mpeg
- video/webm
- application/json
type: string
x-enum-descriptions:
- ""
- ""
- "GIFs are treated as videos, not images."
- ""
- ""
- ""
- ""
- ""
- ""
- Used for Lottie files.
DataTableAiDisclosure:
description: A disclosure identifying if the app generated this media asset
using AI.
enum:
- app_generated
- none
type: string
x-enum-descriptions:
- App creates or significantly alters content using AI
- No AI involvement in creation or alteration
SortByType:
default: relevance
enum:
- relevance
- modified_descending
- modified_ascending
- title_descending
- title_ascending
type: string
x-enum-descriptions:
- Sort results using a relevance algorithm.
- Sort results by the date last modified in descending order.
- Sort results by the date last modified in ascending order.
- Sort results by title in descending order.
- Sort results by title in ascending order
OwnershipType:
default: any
enum:
- any
- owned
- shared
type: string
x-enum-descriptions:
- Owned by and shared with the user.
- Owned by the user.
- Shared with the user.
GetListDesignResponse:
properties:
continuation:
description: |-
A continuation token.
If the success response contains a continuation token, the list contains more designs
you can list. You can use this token as a query parameter and retrieve more
designs from the list, for example
`/v1/designs?continuation={continuation}`.
To retrieve all of a user's designs, you might need to make multiple requests.
example: RkFGMgXlsVTDbMd:MR3L0QjiaUzycIAjx0yMyuNiV0OildoiOwL0x32G4NjNu4FwtAQNxowUQNMMYN
type: string
items:
description: The list of designs.
items:
$ref: '#/components/schemas/Design'
type: array
required:
- items
type: object
CreateDesignRequest:
description: |-
Body parameters for creating a new design. Use the `type` discriminator to choose the creation mode:
- Use `type_and_asset` to create a design by specifying the design type and/or an asset.
- Use `design` to create a copy of an existing design (currently a [preview feature](https://www.canva.dev/docs/apps/rest-apis/#preview-apis)).
- Use `brand_template` to create a design from a brand template (currently a [preview feature](https://www.canva.dev/docs/apps/rest-apis/#preview-apis)).
NOTE: For backward compatibility, if `type` isn't specified in the request,
the request type will be assumed to be `type_and_asset`.
discriminator:
mapping:
type_and_asset: '#/components/schemas/DesignTypeCreateDesignRequest'
design: '#/components/schemas/DesignCreateDesignRequest'
brand_template: '#/components/schemas/BrandTemplateCreateDesignRequest'
propertyName: type
oneOf:
- $ref: '#/components/schemas/DesignTypeCreateDesignRequest'
- $ref: '#/components/schemas/DesignCreateDesignRequest'
- $ref: '#/components/schemas/BrandTemplateCreateDesignRequest'
type: object
DesignTypeCreateDesignRequest:
description: |-
Create a design by specifying the design type and/or an asset.
At least one of `design_type` or `asset_id` must be defined.
properties:
type:
description: "For backward compatibility, if `type` isn't specified in the\
\ request, the request type will be assumed to be `type_and_asset`."
enum:
- type_and_asset
type: string
design_type:
$ref: '#/components/schemas/DesignTypeInput'
asset_id:
description: "The ID of an asset to insert into the created design. Currently,\
\ this only supports image assets."
example: Msd59349ff
type: string
title:
description: The name of the design.
example: My Holiday Presentation
maxLength: 255
minLength: 1
type: string
required:
- type
type: object
DesignCreateDesignRequest:
description: |-
Creating a copy of an existing design is currently provided as a preview. Be aware of the following:
- There might be unannounced breaking changes.
- Any breaking changes to preview features won't produce a new [API version](https://www.canva.dev/docs/apps/rest-apis/versions/).
- Public apps that use preview features will not pass the review process, and can't be made available to all Canva users.
Body parameters for creating a copy of an existing design.
properties:
type:
enum:
- design
type: string
design_id:
description: The ID of the design to copy.
example: DAFVztcvetc
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
page_numbers:
description: |-
The pages to copy from the source design. If not specified, all pages are copied.
Pages are indexed using one-based numbering.
items:
format: int32
minimum: 1
type: integer
minItems: 1
type: array
required:
- design_id
- type
type: object
BrandTemplateCreateDesignRequest:
description: |-
Creating a copy from a brand template is currently provided as a preview. Be aware of the following:
- There might be unannounced breaking changes.
- Any breaking changes to preview features won't produce a new [API version](https://www.canva.dev/docs/apps/rest-apis/versions/).
- Public apps that use preview features will not pass the review process, and can't be made available to all Canva users.
Body parameters for creating a copy from a brand template.
properties:
type:
enum:
- brand_template
type: string
brand_template_id:
description: The ID of the brand template used to create a design copy.
example: EDMzWSwy3BI
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
page_numbers:
description: |-
The pages to copy from the brand template. If not specified, all pages are copied.
Pages are indexed using one-based numbering.
items:
format: int32
minimum: 1
type: integer
minItems: 1
type: array
required:
- brand_template_id
- type
type: object
CreateDesignResponse:
description: Details about the new design.
properties:
design:
$ref: '#/components/schemas/Design'
required:
- design
type: object
CreatePrintPartnerDesignRequest:
description: Body parameters for creating a new design for a Print Partner.
properties:
design_source:
$ref: '#/components/schemas/PrintPartnerDesignSource'
title:
description: The name of the design.
example: My Holiday Presentation
maxLength: 255
minLength: 1
type: string
bleed:
default: 3000
description: |-
Bleed in microns to apply around the design in the editor. Bleed is the area
outside the trim line used to avoid white edges after cutting. Use 0 for no bleed. If bleed is not
specified, a default of 3000 microns is used.
format: int32
maximum: 150000
minimum: 0
type: integer
min_pages:
description: |-
Minimum number of pages the design must have in the editor. The user cannot
reduce the page count below this value. If both min_pages and max_pages are
provided, min_pages must be less than or equal to max_pages.
format: int32
maximum: 500
minimum: 1
type: integer
max_pages:
description: |-
Maximum number of pages the design can have in the editor. The user cannot
add pages beyond this value. If both min_pages and max_pages are provided,
min_pages must be less than or equal to max_pages.
format: int32
maximum: 500
minimum: 1
type: integer
required:
- design_source
type: object
CreatePrintPartnerDesignResponse:
description: Details about the new design.
properties:
design:
$ref: '#/components/schemas/Design'
required:
- design
type: object
PrintPartnerDesignSource:
description: The desired source for the design creation.
discriminator:
mapping:
dimensions: '#/components/schemas/PrintPartnerDimensionsDesignSource'
partner_product_id: '#/components/schemas/PrintPartnerProductIdDesignSource'
propertyName: type
oneOf:
- $ref: '#/components/schemas/PrintPartnerDimensionsDesignSource'
- $ref: '#/components/schemas/PrintPartnerProductIdDesignSource'
type: object
PrintPartnerProductIdDesignSource:
description: Creates a design using an external partner product ID.
properties:
type:
enum:
- partner_product_id
type: string
partner_product_id:
description: The ID of the partner-defined product.
example: CVAFDC1091
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
required:
- partner_product_id
- type
type: object
PrintPartnerDimensionsDesignSource:
description: Creates a design that matches your dimensions. Add a product type
for more precise template matches.
properties:
type:
enum:
- dimensions
type: string
dimensions:
$ref: '#/components/schemas/PrintPartnerDesignDimensions'
product_type:
description: "The product type is used alongside your dimensions to find\
\ a matching product in Canva Print's product catalogue, and templates\
\ for that product are recommended. If no match is found, only dimensions\
\ are used, so templates may include unrelated product types."
example: tshirt
type: string
required:
- dimensions
- type
type: object
PrintPartnerDesignDimensions:
description: |-
Dimensions of the design. Used to match a product type, or to create a custom-size design if
no product matches.
When no matching product is found, the dimensions of each side, converted to pixels, must be
between 40 and 8000, and the total area (width × height) must not exceed 25,000,000 pixels
squared.
properties:
width:
description: The width of the design.
example: 595
format: double
minimum: 1
type: number
height:
description: The height of the design.
example: 1295
format: double
minimum: 1
type: number
units:
$ref: '#/components/schemas/PrintPartnerDesignDimensionsUnits'
required:
- height
- units
- width
type: object
PrintPartnerDesignDimensionsUnits:
description: The units of the dimensions.
enum:
- in
- cm
- mm
type: string
GetDesignResponse:
description: Successful response from a `getDesign` request.
properties:
design:
$ref: '#/components/schemas/Design'
required:
- design
type: object
GetPrintPartnerDesignResponse:
description: Successful response from a `getPrintPartnerDesign` request.
properties:
design:
$ref: '#/components/schemas/Design'
required:
- design
type: object
GetDesignPagesResponse:
description: Successful response from a `getDesignPages` request.
properties:
items:
description: The list of pages.
items:
$ref: '#/components/schemas/DesignPage'
type: array
required:
- items
type: object
GetDesignExportFormatsResponse:
description: Successful response from a `getDesignExportFormats` request.
properties:
formats:
$ref: '#/components/schemas/ExportFormatOptions'
required:
- formats
type: object
Design:
description: "The design object, which contains metadata about the design."
properties:
id:
description: The design ID.
example: DAFVztcvd9z
type: string
title:
description: The design title.
example: My summer holiday
type: string
owner:
$ref: '#/components/schemas/TeamUserSummary'
thumbnail:
$ref: '#/components/schemas/Thumbnail'
urls:
$ref: '#/components/schemas/DesignLinks'
created_at:
description: |-
When the design was created in Canva, as a Unix timestamp (in seconds since the Unix
Epoch).
example: 1377396000
format: int64
type: integer
updated_at:
description: |-
When the design was last updated in Canva, as a Unix timestamp (in seconds since the
Unix Epoch).
example: 1692928800
format: int64
type: integer
page_count:
description: "The total number of pages in the design. Some design types\
\ don't have pages (for example, Canva docs)."
example: 5
format: int32
minimum: 0
type: integer
design_types:
description: The type of content a design or page contains. The list of
design types may grow over time. The `unknown` value represents design
types that haven't been added to the list.
example:
- presentation
items:
$ref: '#/components/schemas/DesignTypeOutputName'
type: array
required:
- created_at
- design_types
- id
- owner
- updated_at
- urls
type: object
PageNumber:
description: The 1-based page number within the design. The first page in a
design has the value `1`.
example: 1
format: int32
maximum: 500
minimum: 1
type: integer
PageDimensions:
description: "The dimensions of a design page, if it is bounded. Design pages\
\ for non-bounded designs like Whiteboards and Docs will not include this\
\ property."
properties:
width:
description: The width of the design page in pixels.
example: 595
format: double
type: number
height:
description: The height of the design page in pixels.
example: 1295
format: double
type: number
required:
- height
- width
type: object
DesignLinks:
description: A temporary set of URLs for viewing or editing the design.
properties:
edit_url:
description: |-
A temporary editing URL for the design. This URL is only accessible to the user that made the API request, and is designed to support [return navigation](https://www.canva.dev/docs/apps/rest-apis/return-navigation-guide/) workflows.
NOTE: This is not a permanent URL, it is only valid for 30 days.
example: https://www.canva.com/api/design/eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIiwiZXhwaXJ5IjoxNzQyMDk5NDAzMDc5fQ..GKLx2hrJa3wSSDKQ.hk3HA59qJyxehR-ejzt2DThBW0cbRdMBz7Fb5uCpwD-4o485pCf4kcXt_ypUYX0qMHVeZ131YvfwGPIhbk-C245D8c12IIJSDbZUZTS7WiCOJZQ.sNz3mPSQxsETBvl_-upMYA/edit
type: string
view_url:
description: |
A temporary viewing URL for the design. This URL is only accessible to the user that made the API request, and is designed to support [return navigation](https://www.canva.dev/docs/apps/rest-apis/return-navigation-guide/) workflows.
NOTE: This is not a permanent URL, it is only valid for 30 days.
example: https://www.canva.com/api/design/eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIiwiZXhwaXJ5IjoxNzQyMDk5NDAzMDc5fQ..GKLx2hrJa3wSSDKQ.hk3HA59qJyxehR-ejzt2DThBW0cbRdMBz7Fb5uCpwD-4o485pCf4kcXt_ypUYX0qMHVeZ131YvfwGPIhbk-C245D8c12IIJSDbZUZTS7WiCOJZQ.sNz3mPSQxsETBvl_-upMYA/view
type: string
required:
- edit_url
- view_url
type: object
DesignSummary:
description: "Basic details about the design, such as the design's ID, title,\
\ and URL."
properties:
id:
description: The design ID.
example: DAFVztcvd9z
type: string
title:
description: The design title.
example: My summer holiday
type: string
url:
description: URL of the design.
example: https://www.canva.com/design/DAFVztcvd9z/edit
type: string
thumbnail:
$ref: '#/components/schemas/Thumbnail'
urls:
$ref: '#/components/schemas/DesignLinks'
created_at:
description: |-
When the design was created in Canva, as a Unix timestamp (in seconds since the Unix
Epoch).
example: 1377396000
format: int64
type: integer
updated_at:
description: |-
When the design was last updated in Canva, as a Unix timestamp (in seconds since the
Unix Epoch).
example: 1692928800
format: int64
type: integer
page_count:
description: "The total number of pages in the design. Some design types\
\ don't have pages (for example, Canva docs)."
example: 3
format: int32
minimum: 0
type: integer
required:
- created_at
- id
- updated_at
- urls
type: object
DesignPage:
description: "Basic details about a page in a design, such as the page number\
\ and thumbnail."
properties:
id:
description: |-
The ID of the page. This ID is unique within the design and can be used to
correlate a page with per-page data from other APIs.
Some designs might not have page IDs, in which case this property is omitted.
example: PB2NFQ9W78kLDFCK
type: string
index:
deprecated: true
description: |-
WARNING: This property is deprecated. Use `page_number` instead, which returns an identical value.
The index of the page in the design. The first page in a design has the index value `1`.
format: int32
maximum: 500
minimum: 1
type: integer
page_number:
description: The 1-based page number within the design. The first page in
a design has the value `1`.
example: 1
format: int32
maximum: 500
minimum: 1
type: integer
dimensions:
$ref: '#/components/schemas/PageDimensions'
thumbnail:
$ref: '#/components/schemas/Thumbnail'
design_type:
$ref: '#/components/schemas/DesignTypeOutputName'
required:
- design_type
- index
- page_number
type: object
GetDesignDatasetResponse:
description: Successful response from a `getDesignDataset` request.
properties:
dataset:
additionalProperties:
$ref: '#/components/schemas/DataField'
description: |-
The dataset definition. It contains the data inputs available for use with the
[Create design autofill job API](https://www.canva.dev/docs/apps/rest-apis/reference/autofills/create-design-autofill-job/).
example:
cute_pet_image_of_the_day:
type: image
cute_pet_witty_pet_says:
type: text
cute_pet_sales_chart:
type: chart
type: object
type: object
DatasetDefinition:
additionalProperties:
$ref: '#/components/schemas/DataField'
description: |-
The dataset definition. It contains the data inputs available for use with the
[Create design autofill job API](https://www.canva.dev/docs/apps/rest-apis/reference/autofills/create-design-autofill-job/).
example:
cute_pet_image_of_the_day:
type: image
cute_pet_witty_pet_says:
type: text
cute_pet_sales_chart:
type: chart
type: object
DataField:
description: A named data field that can be autofilled.
discriminator:
mapping:
image: '#/components/schemas/ImageDataField'
text: '#/components/schemas/TextDataField'
chart: '#/components/schemas/ChartDataField'
sheet: '#/components/schemas/SheetDataField'
propertyName: type
oneOf:
- $ref: '#/components/schemas/ImageDataField'
- $ref: '#/components/schemas/TextDataField'
- $ref: '#/components/schemas/ChartDataField'
- $ref: '#/components/schemas/SheetDataField'
type: object
ImageDataField:
description: |-
An image data field. You can autofill it with an image by providing its `asset_id`.
You can also autofill it with a video asset.
properties:
type:
enum:
- image
type: string
required:
- type
type: object
TextDataField:
description: A text data field. You can autofill it with a text value.
properties:
type:
enum:
- text
type: string
required:
- type
type: object
ChartDataField:
description: A chart data field. You can autofill it with tabular data.
properties:
type:
enum:
- chart
type: string
required:
- type
type: object
SheetDataField:
description: A sheet data field. You can autofill it with tabular sheet data.
properties:
type:
enum:
- sheet
type: string
required:
- type
type: object
CreateDesignGenerationJobRequestV2:
description: "The brief, design type, and optional presentation outline for\
\ generation."
properties:
brief:
description: |-
A description of the design to generate, including its subject, purpose,
required wording, tone, and visual direction.
example: "A 3-slide pitch deck for a solar-panel startup with an energetic,\
\ modern, blue-and-white visual direction."
maxLength: 5000
minLength: 1
type: string
design_type:
allOf:
- $ref: '#/components/schemas/DesignGenerationDesignTypeInputV2'
description: The preset Canva design type to generate. Supports `doc` and
`presentation`.
outline:
allOf:
- $ref: '#/components/schemas/DesignGenerationOutlineV2'
description: |-
The slide structure to follow. This property is supported only when
`design_type.name` is `presentation`.
required:
- brief
- design_type
type: object
DesignGenerationDesignTypeInputV2:
description: The preset Canva design type to generate.
properties:
type:
$ref: '#/components/schemas/DesignGenerationDesignTypeV2'
name:
$ref: '#/components/schemas/DesignGenerationDesignTypeNameV2'
required:
- name
- type
type: object
DesignGenerationDesignTypeV2:
description: The kind of design type to generate.
enum:
- preset
type: string
x-enum-descriptions:
- A preset Canva design type.
DesignGenerationDesignTypeNameV2:
description: The name of the design type to generate.
enum:
- doc
- presentation
type: string
x-enum-descriptions:
- "A [Canva doc](https://www.canva.com/docs/); a document for Canva's online\
\ text editor."
- "A [presentation](https://www.canva.com/presentations/); lets you create and\
\ collaborate for presenting to an audience."
DesignGenerationOutlineV2:
description: The ordered slide structure for a generated presentation.
properties:
sections:
items:
$ref: '#/components/schemas/DesignGenerationOutlineSectionV2'
maxItems: 100
minItems: 1
type: array
required:
- sections
type: object
DesignGenerationOutlineSectionV2:
description: One slide in a presentation outline.
properties:
title:
description: The slide title.
example: The problem
maxLength: 255
minLength: 1
type: string
description:
description: A short description of what the slide should cover.
example: Rooftop solar installations still take more than six weeks to quote.
maxLength: 2000
minLength: 1
type: string
points:
description: Optional individual points the slide should make.
items:
maxLength: 1000
minLength: 1
type: string
maxItems: 50
type: array
required:
- title
type: object
CreateDesignGenerationJobResponseV2:
properties:
job:
$ref: '#/components/schemas/DesignGenerationJobV2'
required:
- job
type: object
GetDesignGenerationJobResponseV2:
properties:
job:
$ref: '#/components/schemas/DesignGenerationJobV2'
required:
- job
type: object
DesignGenerationJobV2:
description: The status and result of a public design generation job.
properties:
id:
description: The public design generation job ID.
example: f81b26fd-a33d-4c2d-9e8c-4a7aca798b17
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
status:
$ref: '#/components/schemas/DesignGenerationJobStatusV2'
result:
$ref: '#/components/schemas/DesignGenerationJobResultV2'
error:
$ref: '#/components/schemas/DesignGenerationJobErrorV2'
required:
- id
- status
type: object
DesignGenerationJobStatusV2:
description: |-
The public status of the job. `result` is present only for `success`, and
`error` is present only for `failed`.
enum:
- failed
- in_progress
- success
type: string
x-enum-descriptions:
- The design couldn't be generated.
- The design is still being generated.
- The design was generated and saved to the user's Canva account.
DesignGenerationJobResultV2:
description: Present only when the job status is `success`.
properties:
design:
$ref: '#/components/schemas/DesignSummary'
required:
- design
type: object
DesignGenerationJobErrorV2:
description: Details about a failed design generation job.
properties:
code:
$ref: '#/components/schemas/DesignGenerationJobErrorCodeV2'
message:
description: A human-readable description of what went wrong.
type: string
required:
- code
- message
type: object
DesignGenerationJobErrorCodeV2:
description: The reason the design generation job failed.
enum:
- content_not_allowed
- generation_failed
type: string
x-enum-descriptions:
- The brief or generated content didn't pass Canva's content-safety checks.
- Canva couldn't complete the design generation job.
DesignImportMetadata:
description: Metadata about the design that you include as a header parameter
when importing a design.
properties:
title_base64:
description: |-
The design's title, encoded in Base64.
The maximum length of a design title in Canva (unencoded) is 50 characters.
Base64 encoding allows titles containing emojis and other special
characters to be sent using HTTP headers.
For example, "My Awesome Design 😍" Base64 encoded
is `TXkgQXdlc29tZSBEZXNpZ24g8J+YjQ==`.
example: TXkgQXdlc29tZSBEZXNpZ24g8J+YjQ==
minLength: 1
type: string
mime_type:
description: "The MIME type of the file being imported. If not provided,\
\ Canva attempts to automatically detect the type of the file."
example: application/pdf
type: string
required:
- title_base64
type: object
CreateDesignImportJobResponse:
properties:
job:
$ref: '#/components/schemas/DesignImportJob'
required:
- job
type: object
DesignImportJob:
description: The status of the design import job.
properties:
id:
description: The ID of the design import job.
example: e08861ae-3b29-45db-8dc1-1fe0bf7f1cc8
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
status:
$ref: '#/components/schemas/DesignImportStatus'
result:
$ref: '#/components/schemas/DesignImportJobResult'
error:
$ref: '#/components/schemas/DesignImportError'
required:
- id
- status
type: object
DesignImportStatus:
description: The status of the design import job.
enum:
- failed
- in_progress
- success
example: success
type: string
DesignImportError:
description: "If the import job fails, this object provides details about the\
\ error."
properties:
code:
$ref: '#/components/schemas/DesignImportErrorCode'
message:
description: A human-readable description of what went wrong.
example: "We're sorry, but the file upload quota has exceeded. Please try\
\ again later."
type: string
required:
- code
- message
type: object
DesignImportErrorCode:
description: |-
A short string about why the import failed. This field can be used to handle errors
programmatically.
enum:
- design_creation_throttled
- design_import_throttled
- duplicate_import
- internal_error
- invalid_file
- fetch_failed
example: design_creation_throttled
type: string
DesignImportJobResult:
properties:
designs:
description: |-
A list of designs imported from the external file. It usually contains one item.
Imports with a large number of pages or assets are split into multiple designs.
items:
$ref: '#/components/schemas/DesignSummary'
type: array
required:
- designs
type: object
GetDesignImportJobResponse:
properties:
job:
$ref: '#/components/schemas/DesignImportJob'
required:
- job
type: object
CreateUrlImportJobRequest:
properties:
title:
description: A title for the design.
example: My Awesome Design
maxLength: 255
minLength: 1
type: string
url:
description: The URL of the file to import. This URL must be accessible
from the internet and be publicly available.
maxLength: 2048
minLength: 1
type: string
mime_type:
description: "The MIME type of the file being imported. If not provided,\
\ Canva attempts to automatically detect the type of the file."
example: application/vnd.apple.keynote
maxLength: 100
minLength: 1
type: string
required:
- title
- url
type: object
CreateUrlImportJobResponse:
properties:
job:
$ref: '#/components/schemas/DesignImportJob'
required:
- job
type: object
GetUrlImportJobResponse:
properties:
job:
$ref: '#/components/schemas/DesignImportJob'
required:
- job
type: object
CreateImageToDesignImportJobRequest:
properties:
image:
$ref: '#/components/schemas/ImageSource'
title:
description: "A title for the created design. If not provided, Canva generates\
\ a title."
example: My Image Design
maxLength: 255
minLength: 1
type: string
required:
- image
type: object
ImageSource:
description: The image to convert into a design.
properties:
asset_id:
description: |-
The ID of an image asset in the user's Canva account.
The asset must be one of the following image types: `png`, `jpeg`, `gif`,
`webp`, `heic`, `heif`, `avif`, `tiff`, `jp2`, `jpx`, `jpm`, or `jxr`. Video
assets are not supported.
example: Msd59349ff
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
required:
- asset_id
type: object
CreateImageToDesignImportJobResponse:
properties:
job:
$ref: '#/components/schemas/ImageToDesignImportJob'
required:
- job
type: object
GetImageToDesignImportJobResponse:
properties:
job:
$ref: '#/components/schemas/ImageToDesignImportJob'
required:
- job
type: object
ImageToDesignImportJob:
description: The status and result of an image-to-design import job.
properties:
id:
description: The ID of the image-to-design import job.
example: f81b26fd-a33d-4c2d-9e8c-4a7aca798b17
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
status:
$ref: '#/components/schemas/DesignImportStatus'
result:
$ref: '#/components/schemas/ImageToDesignImportJobResult'
error:
$ref: '#/components/schemas/ImageToDesignImportError'
required:
- id
- status
type: object
ImageToDesignImportJobResult:
properties:
design:
$ref: '#/components/schemas/DesignSummary'
required:
- design
type: object
ImageToDesignImportError:
description: "If the import job fails, this object provides details about the\
\ error."
properties:
code:
$ref: '#/components/schemas/ImageToDesignImportErrorCode'
message:
description: A human-readable description of what went wrong.
example: The image could not be converted into a design.
type: string
required:
- code
- message
type: object
ImageToDesignImportErrorCode:
description: |-
A short string about why the import failed. This field can be used to handle errors
programmatically.
enum:
- bad_input
- moderation_error
- quota_exceeded
- design_creation_throttled
- internal_error
example: bad_input
type: string
DesignTypeInput:
description: The desired design type.
discriminator:
mapping:
preset: '#/components/schemas/PresetDesignTypeInput'
custom: '#/components/schemas/CustomDesignTypeInput'
propertyName: type
oneOf:
- $ref: '#/components/schemas/PresetDesignTypeInput'
- $ref: '#/components/schemas/CustomDesignTypeInput'
type: object
PresetDesignTypeInput:
description: Provide the common design type.
properties:
type:
enum:
- preset
type: string
name:
$ref: '#/components/schemas/PresetDesignTypeName'
required:
- name
- type
type: object
PresetDesignTypeName:
description: The name of the design type.
enum:
- doc
- email
- presentation
- whiteboard
type: string
x-enum-descriptions:
- "A [Canva doc](https://www.canva.com/docs/); a document for Canva's online\
\ text editor."
- "An [email](https://www.canva.com/emails/); for creating email campaign designs."
- "A [presentation](https://www.canva.com/presentations/); lets you create and\
\ collaborate for presenting to an audience."
- "A [whiteboard](https://www.canva.com/online-whiteboard/); a design which\
\ gives you infinite space to collaborate."
CustomDesignTypeInput:
description: |-
Provide the width and height to define a custom design type.
Each dimension must be between 40 and 8000 pixels, and the
total area (width × height) must not exceed 25,000,000 pixels
squared. For example, a design with a width of 8000 pixels can
have a maximum height of 3125 pixels.
properties:
type:
enum:
- custom
type: string
width:
description: "The width of the design, in pixels."
example: 320
format: int32
maximum: 8000
minimum: 40
type: integer
height:
description: "The height of the design, in pixels."
example: 200
format: int32
maximum: 8000
minimum: 40
type: integer
required:
- height
- type
- width
type: object
DesignTypeOutputName:
description: The type of content a design or page contains. The list of design
types may grow over time. The `unknown` value represents design types that
haven't been added to the list.
enum:
- doc
- email
- presentation
- sheet
- whiteboard
- custom
- unknown
example: presentation
type: string
Error:
properties:
code:
$ref: '#/components/schemas/ErrorCode'
message:
description: A human-readable description of what went wrong.
type: string
required:
- code
- message
type: object
FeatureQuotaExceededError:
allOf:
- $ref: '#/components/schemas/Error'
- properties:
upsell_url:
description: URL to redirect users to upgrade their Canva account and
reset their quota.
type: string
required:
- upsell_url
type: object
description: Feature quota exceeded
OauthError:
properties:
error:
$ref: '#/components/schemas/ErrorCode'
error_description:
description: A human-readable description of what went wrong.
type: string
required:
- error
- error_description
type: object
ErrorCode:
description: |
A short string indicating what failed. This field can be used to handle errors programmatically.
enum:
- internal_error
- invalid_field
- invalid_header_value
- permission_denied
- too_many_requests
- not_found
- bad_request_body
- bad_http_method
- bad_request_params
- bad_query_params
- user_role_required
- endpoint_not_found
- endpoint_gone
- unsupported_version
- invalid_access_token
- revoked_access_token
- missing_field
- missing_scope
- invalid_grant
- invalid_request
- invalid_client
- unauthorized_client
- unsupported_grant_type
- invalid_scope
- invalid_basic_header
- invalid_file_format
- quota_exceeded
- credit_quota_exceeded
- credit_quota_cooldown
- app_credit_quota_exceeded
- unsupported_content_type
- request_too_large
- model_capacity_reached
- folder_not_found
- item_in_multiple_folders
- asset_not_found
- unsupported_asset
- asset_not_ready
- max_limit_reached
- permission_not_found
- permission_exists
- unauthorized_user
- user_not_found
- user_not_eligible
- group_not_found
- app_not_found
- app_has_non_draft_versions
- invalid_status_transition
- translation_validation_failed
- content_not_found
- doctype_not_found
- design_not_found
- offset_too_large
- page_not_found
- design_or_comment_not_found
- design_or_thread_not_found
- review_dismissed
- design_type_not_found
- team_not_found
- team_is_default
- comment_not_found
- too_many_comments
- too_many_replies
- message_too_long
- thread_not_found
- reply_not_found
- design_not_fillable
- autofill_data_invalid
- feature_not_available
- unsupported_design_type
- design_generation_not_enabled
- design_generation_rejected
- license_required
- input_unsafe
- display_name_unavailable
- user_not_managed
- saml_team_id_conflict
- saml_name_id_not_available
- user_linked_to_another_idp
- user_email_unverified
- user_not_active
- user_pending_consent
- account_exists
- domain_restricted
- user_already_member
type: string
CreateDesignExportJobRequest:
description: |-
Body parameters for starting an export job for a design.
It must include a design ID, and one of the supported export formats.
example:
design_id: DAVZr1z5464
format:
type: pdf
size: a4
pages:
- 2
- 3
- 4
properties:
design_id:
description: The design ID.
type: string
format:
$ref: '#/components/schemas/ExportFormat'
required:
- design_id
- format
type: object
ExportFormat:
description: Details about the desired export format.
discriminator:
mapping:
pdf: '#/components/schemas/PdfExportFormat'
jpg: '#/components/schemas/JpgExportFormat'
png: '#/components/schemas/PngExportFormat'
pptx: '#/components/schemas/PptxExportFormat'
gif: '#/components/schemas/GifExportFormat'
mp4: '#/components/schemas/Mp4ExportFormat'
html_bundle: '#/components/schemas/HtmlBundleExportFormat'
html_standalone: '#/components/schemas/HtmlStandaloneExportFormat'
csv: '#/components/schemas/CsvExportFormat'
propertyName: type
oneOf:
- $ref: '#/components/schemas/PdfExportFormat'
- $ref: '#/components/schemas/JpgExportFormat'
- $ref: '#/components/schemas/PngExportFormat'
- $ref: '#/components/schemas/PptxExportFormat'
- $ref: '#/components/schemas/GifExportFormat'
- $ref: '#/components/schemas/Mp4ExportFormat'
- $ref: '#/components/schemas/HtmlBundleExportFormat'
- $ref: '#/components/schemas/HtmlStandaloneExportFormat'
- $ref: '#/components/schemas/CsvExportFormat'
type: object
PdfExportFormat:
description: Export the design as a PDF. Providing a paper size is optional.
properties:
type:
enum:
- pdf
type: string
export_quality:
$ref: '#/components/schemas/ExportQuality'
size:
$ref: '#/components/schemas/ExportPageSize'
pages:
description: |-
To specify which pages to export in a multi-page design, provide the page numbers as
an array. The first page in a design is page `1`.
If `pages` isn't specified, all the pages are exported.
example:
- 2
- 3
- 4
items:
format: int32
minimum: 1
type: integer
type: array
required:
- type
type: object
GifExportFormat:
description: |-
Export the design as a GIF. Height or width (or both) may be specified, otherwise the file
will be exported at it's default size. Large designs will be scaled down, and aspect ratio
will always be maintained.
properties:
type:
enum:
- gif
type: string
export_quality:
$ref: '#/components/schemas/ExportQuality'
height:
description: |-
Specify the height in pixels of the exported image. Note the following behavior:
- If no height or width is specified, the image is exported using the dimensions of the design.
- If only one of height or width is specified, then the image is scaled to match that dimension, respecting the design's aspect ratio.
- If both the height and width are specified, but the values don't match the design's aspect ratio, the export defaults to the larger dimension.
example: 400
format: int32
maximum: 25000
minimum: 40
type: integer
width:
description: |-
Specify the width in pixels of the exported image. Note the following behavior:
- If no width or height is specified, the image is exported using the dimensions of the design.
- If only one of width or height is specified, then the image is scaled to match that dimension, respecting the design's aspect ratio.
- If both the width and height are specified, but the values don't match the design's aspect ratio, the export defaults to the larger dimension.
example: 400
format: int32
maximum: 25000
minimum: 40
type: integer
pages:
description: |-
To specify which pages to export in a multi-page design, provide the page numbers as
an array. The first page in a design is page `1`.
If `pages` isn't specified, all the pages are exported.
example:
- 2
- 3
- 4
items:
format: int32
minimum: 1
type: integer
type: array
required:
- type
type: object
JpgExportFormat:
description: |-
Export the design as a JPEG. Compression quality must be provided. Height or width (or both)
may be specified, otherwise the file will be exported at it's default size.
If the user is on the Canva Free plan, the export height and width for a fixed-dimension design can't be upscaled by more than a factor of `1.125`.
properties:
type:
enum:
- jpg
type: string
export_quality:
$ref: '#/components/schemas/ExportQuality'
quality:
description: "For the `jpg` type, the `quality` of the exported JPEG determines\
\ how compressed the exported file should be. A _low_ `quality` value\
\ will create a file with a smaller file size, but the resulting file\
\ will have pixelated artifacts when compared to a file created with a\
\ _high_ `quality` value."
example: 80
format: int32
maximum: 100
minimum: 1
type: integer
height:
description: |-
Specify the height in pixels of the exported image. Note the following behavior:
- If no height or width is specified, the image is exported using the dimensions of the design.
- If only one of height or width is specified, then the image is scaled to match that dimension, respecting the design's aspect ratio.
- If both the height and width are specified, but the values don't match the design's aspect ratio, the export defaults to the larger dimension.
example: 400
format: int32
maximum: 25000
minimum: 40
type: integer
width:
description: |-
Specify the width in pixels of the exported image. Note the following behavior:
- If no width or height is specified, the image is exported using the dimensions of the design.
- If only one of width or height is specified, then the image is scaled to match that dimension, respecting the design's aspect ratio.
- If both the width and height are specified, but the values don't match the design's aspect ratio, the export defaults to the larger dimension.
example: 400
format: int32
maximum: 25000
minimum: 40
type: integer
pages:
description: |-
To specify which pages to export in a multi-page design, provide the page numbers as
an array. The first page in a design is page `1`.
If `pages` isn't specified, all the pages are exported.
example:
- 2
- 3
- 4
items:
format: int32
minimum: 1
type: integer
type: array
required:
- quality
- type
type: object
PngExportFormat:
description: |-
Export the design as a PNG. Height or width (or both) may be specified, otherwise
the file will be exported at it's default size. You may also specify whether to export the
file losslessly, and whether to export a multi-page design as a single image.
If the user is on the Canva Free plan, the export height and width for a fixed-dimension design can't be upscaled by more than a factor of `1.125`.
properties:
type:
enum:
- png
type: string
export_quality:
$ref: '#/components/schemas/ExportQuality'
height:
description: |-
Specify the height in pixels of the exported image. Note the following behavior:
- If no height or width is specified, the image is exported using the dimensions of the design.
- If only one of height or width is specified, then the image is scaled to match that dimension, respecting the design's aspect ratio.
- If both the height and width are specified, but the values don't match the design's aspect ratio, the export defaults to the larger dimension.
example: 400
format: int32
maximum: 25000
minimum: 40
type: integer
width:
description: |-
Specify the width in pixels of the exported image. Note the following behavior:
- If no width or height is specified, the image is exported using the dimensions of the design.
- If only one of width or height is specified, then the image is scaled to match that dimension, respecting the design's aspect ratio.
- If both the width and height are specified, but the values don't match the design's aspect ratio, the export defaults to the larger dimension.
example: 400
format: int32
maximum: 25000
minimum: 40
type: integer
lossless:
default: true
description: |-
If set to `true` (default), the PNG is exported without compression.
If set to `false`, the PNG is compressed using a lossy compression algorithm.
AVAILABILITY: Lossy PNG compression is only available to users on a Canva plan that has premium features, such as Canva Pro. If the user is on the Canva Free plan and this parameter is set to `false`, the export operation will fail.
type: boolean
transparent_background:
default: false
description: |-
If set to `true`, the PNG is exported with a transparent background.
AVAILABILITY: This option is only available to users on a Canva plan that has premium features, such as Canva Pro. If the user is on the Canva Free plan and this parameter is set to `true`, the export operation will fail.
type: boolean
as_single_image:
default: false
description: |-
When `true`, multi-page designs are merged into a single image.
When `false` (default), each page is exported as a separate image.
type: boolean
pages:
description: |-
To specify which pages to export in a multi-page design, provide the page numbers as
an array. The first page in a design is page `1`.
If `pages` isn't specified, all the pages are exported.
example:
- 2
- 3
- 4
items:
format: int32
minimum: 1
type: integer
type: array
required:
- type
type: object
PptxExportFormat:
description: Export the design as a PPTX.
properties:
type:
enum:
- pptx
type: string
pages:
description: |-
To specify which pages to export in a multi-page design, provide the page numbers as
an array. The first page in a design is page `1`.
If `pages` isn't specified, all the pages are exported.
example:
- 2
- 3
- 4
items:
format: int32
minimum: 1
type: integer
type: array
required:
- type
type: object
Mp4ExportFormat:
description: Export the design as an MP4. You must specify the quality of the
exported video.
properties:
type:
enum:
- mp4
type: string
export_quality:
$ref: '#/components/schemas/ExportQuality'
quality:
$ref: '#/components/schemas/Mp4ExportQuality'
pages:
description: |-
To specify which pages to export in a multi-page design, provide the page numbers as
an array. The first page in a design is page `1`.
If `pages` isn't specified, all the pages are exported.
example:
- 2
- 3
- 4
items:
format: int32
minimum: 1
type: integer
type: array
required:
- quality
- type
type: object
HtmlBundleExportFormat:
description: Export the email design as an HTML bundle. An HTML bundle is a
zip file that contains an HTML file and the associated assets.
properties:
type:
enum:
- html_bundle
type: string
pages:
description: |-
The pages of the design to export. Currently only a single page can be exported. If not provided,
the first page of the design is used.
example:
- 1
items:
format: int32
minimum: 1
type: integer
maxItems: 1
minItems: 1
type: array
required:
- type
type: object
HtmlStandaloneExportFormat:
description: Export the email design as a standalone HTML file with hosted assets.
properties:
type:
enum:
- html_standalone
type: string
pages:
description: |-
The pages of the design to export. Currently only a single page can be exported. If not provided,
the first page of the design is used.
example:
- 1
items:
format: int32
minimum: 1
type: integer
maxItems: 1
minItems: 1
type: array
required:
- type
type: object
CsvExportFormat:
description: |-
Export the design as a CSV file. CSV export is only available for designs that contain
tabular data, such as Canva Sheets.
properties:
type:
enum:
- csv
type: string
pages:
description: |-
To specify which pages to export in a multi-page design, provide the page numbers as
an array. The first page in a design is page `1`.
If `pages` isn't specified, all the pages are exported.
example:
- 2
- 3
- 4
items:
format: int32
minimum: 1
type: integer
type: array
required:
- type
type: object
CreateDesignExportJobResponse:
properties:
job:
$ref: '#/components/schemas/ExportJob'
required:
- job
type: object
CreatePrintPartnerDesignExportJobRequest:
description: |-
Body parameters for starting a Print Partner export job for a design.
It must include a design ID. Canva Docs are not supported for export.
example:
design_id: DAVZr1z5464
format:
type: pdf
pages:
- 2
- 3
- 4
dimensions:
width: 200
height: 300
units: px
properties:
design_id:
description: The design ID.
type: string
dimensions:
$ref: '#/components/schemas/PrintPartnerExportDimensions'
format:
$ref: '#/components/schemas/PrintPartnerExportFormat'
pages:
description: |-
To specify which pages to export in a multi-page design, provide the page
numbers as an array. The first page in a design is page `1`.
If `pages` isn't specified, all the pages are exported.
example:
- 2
- 3
- 4
items:
format: int32
minimum: 1
type: integer
type: array
required:
- design_id
- format
type: object
PrintPartnerExportDimensions:
description: |-
Dimensions of the export in the specified units. The design dimensions must be
within a scale factor of 0.3 and 3 of the requested export dimensions.
properties:
width:
description: |-
The width of the exported image. Note the following behavior:
- If no height or width is specified, the image is exported using the dimensions of the design.
- If only one of height or width is specified, then the image is scaled to match that dimension, respecting the design's aspect ratio.
- If both the height and width are specified, but the values don't match the design's aspect ratio, the export defaults to the larger dimension.
format: double
minimum: 1
type: number
height:
description: |-
The height of the exported image. Note the following behavior:
- If no height or width is specified, the image is exported using the dimensions of the design.
- If only one of height or width is specified, then the image is scaled to match that dimension, respecting the design's aspect ratio.
- If both the height and width are specified, but the values don't match the design's aspect ratio, the export defaults to the larger dimension.
format: double
minimum: 1
type: number
units:
$ref: '#/components/schemas/PrintPartnerExportDimensionsUnits'
type: object
PrintPartnerExportDimensionsUnits:
default: px
description: "The units of the dimensions. If no units are specified, pixels\
\ are used."
enum:
- px
- in
- cm
- mm
type: string
PrintPartnerExportFormat:
description: Details about the desired export format.
discriminator:
mapping:
pdf: '#/components/schemas/PrintPartnerPdfExportFormat'
jpg: '#/components/schemas/PrintPartnerJpgExportFormat'
png: '#/components/schemas/PrintPartnerPngExportFormat'
propertyName: type
oneOf:
- $ref: '#/components/schemas/PrintPartnerPdfExportFormat'
- $ref: '#/components/schemas/PrintPartnerJpgExportFormat'
- $ref: '#/components/schemas/PrintPartnerPngExportFormat'
type: object
PrintPartnerPdfExportFormat:
description: Export the design as a Print-quality PDF.
properties:
type:
enum:
- pdf
type: string
bleed:
default: 3000
description: "The size of the bleed that should be added to the design.\
\ The units of the bleed must be microns. This should match the bleed\
\ value used when creating the design with the [Create print partner design\
\ API](https://www.canva.dev/docs/apps/rest-apis/reference/print-partner/create-print-partner-design/).\
\ Use 0 for no bleed. If bleed is not specified, a default of 3000 microns\
\ is used."
format: int32
maximum: 150000
minimum: 0
type: integer
crop_marks:
default: false
description: Whether crop marks should be added to the image.
type: boolean
cmyk:
default: false
description: Whether the PDF color space should be converted to CMYK.
type: boolean
pdfx:
default: false
description: |-
Whether the PDF standard should be updated to PDF/X, a printer friendly
standard.
type: boolean
required:
- type
type: object
PrintPartnerJpgExportFormat:
description: Export the design as a print-quality JPEG.
properties:
type:
enum:
- jpg
type: string
required:
- type
type: object
PrintPartnerPngExportFormat:
description: Export the design as a print-quality PNG.
properties:
type:
enum:
- png
type: string
required:
- type
type: object
CreatePrintPartnerDesignExportJobResponse:
properties:
job:
$ref: '#/components/schemas/ExportJob'
required:
- job
type: object
GetDesignExportJobResponse:
properties:
job:
$ref: '#/components/schemas/ExportJob'
required:
- job
type: object
ExportJob:
description: The status of the export job.
properties:
id:
description: The export job ID.
example: e08861ae-3b29-45db-8dc1-1fe0bf7f1cc8
type: string
status:
$ref: '#/components/schemas/DesignExportStatus'
urls:
description: |-
Download URL(s) for the completed export job. These URLs expire after 24 hours.
Depending on the design type and export format, there is a download URL for each page in the design. The list is sorted by page order.
example:
- https://export-download.canva.com/...
items:
type: string
type: array
error:
$ref: '#/components/schemas/ExportError'
required:
- id
- status
type: object
ExportPageSize:
default: a4
description: The paper size of the export PDF file. The `size` attribute is
only supported for Documents (Canva Docs).
enum:
- a4
- a3
- letter
- legal
example: a4
type: string
DesignExportStatus:
description: |-
The export status of the job. A newly created job will be `in_progress` and will eventually
become `success` or `failed`.
enum:
- failed
- in_progress
- success
type: string
ExportHeight:
description: |-
Specify the height in pixels of the exported image. Note the following behavior:
- If no height or width is specified, the image is exported using the dimensions of the design.
- If only one of height or width is specified, then the image is scaled to match that dimension, respecting the design's aspect ratio.
- If both the height and width are specified, but the values don't match the design's aspect ratio, the export defaults to the larger dimension.
example: 400
format: int32
maximum: 25000
minimum: 40
type: integer
ExportWidth:
description: |-
Specify the width in pixels of the exported image. Note the following behavior:
- If no width or height is specified, the image is exported using the dimensions of the design.
- If only one of width or height is specified, then the image is scaled to match that dimension, respecting the design's aspect ratio.
- If both the width and height are specified, but the values don't match the design's aspect ratio, the export defaults to the larger dimension.
example: 400
format: int32
maximum: 25000
minimum: 40
type: integer
Mp4ExportQuality:
description: |-
The resolution of the exported video, as a target number of pixels. The resolution is one of
`480p`, `720p`, `1080p` or `4k`.
The exported video always has the same aspect ratio as the design, which matches creating a
download from the Canva editor. The resolution sets how many pixels to target, and the
design's aspect ratio decides how they're split between width and height, so the
`horizontal` and `vertical` values of a given resolution produce the same output:
- A 2160x3840 portrait design exported as `horizontal_4k` is 2160x3840, not 3840x2160. The
orientation in the value's name doesn't rotate or crop the design.
- A 1000x2000 design exported as `horizontal_720p` is 678x1357, the 1:2 size closest to the
921,600 pixels of 1280x720. Aspect ratios that don't match a standard video size aren't
rounded to one.
- A square design exported as `horizontal_4k` or `vertical_4k` is 2880x2880, the square with
the same number of pixels as 3840x2160.
enum:
- horizontal_480p
- horizontal_720p
- horizontal_1080p
- horizontal_4k
- vertical_480p
- vertical_720p
- vertical_1080p
- vertical_4k
type: string
ExportFormatOptions:
description: The available file formats for exporting the design.
properties:
pdf:
$ref: '#/components/schemas/PdfExportFormatOption'
jpg:
$ref: '#/components/schemas/JpgExportFormatOption'
png:
$ref: '#/components/schemas/PngExportFormatOption'
svg:
$ref: '#/components/schemas/SvgExportFormatOption'
pptx:
$ref: '#/components/schemas/PptxExportFormatOption'
gif:
$ref: '#/components/schemas/GifExportFormatOption'
mp4:
$ref: '#/components/schemas/Mp4ExportFormatOption'
html_bundle:
$ref: '#/components/schemas/HtmlBundleExportFormatOption'
html_standalone:
$ref: '#/components/schemas/HtmlStandaloneExportFormatOption'
csv:
$ref: '#/components/schemas/CsvExportFormatOption'
type: object
PdfExportFormatOption:
description: Whether the design can be exported as a PDF.
properties:
page_numbers:
description: "The page numbers in the design that support this export format,\
\ in ascending order. The first page in a design is page `1`. If omitted,\
\ the format is supported by all pages in the design."
example:
- 1
- 2
- 3
items:
format: int32
minimum: 1
type: integer
type: array
type: object
GifExportFormatOption:
description: Whether the design can be exported as a GIF.
properties:
page_numbers:
description: "The page numbers in the design that support this export format,\
\ in ascending order. The first page in a design is page `1`. If omitted,\
\ the format is supported by all pages in the design."
example:
- 1
- 2
- 3
items:
format: int32
minimum: 1
type: integer
type: array
type: object
JpgExportFormatOption:
description: Whether the design can be exported as a JPEG.
properties:
page_numbers:
description: "The page numbers in the design that support this export format,\
\ in ascending order. The first page in a design is page `1`. If omitted,\
\ the format is supported by all pages in the design."
example:
- 1
- 2
- 3
items:
format: int32
minimum: 1
type: integer
type: array
type: object
PngExportFormatOption:
description: Whether the design can be exported as a PNG.
properties:
page_numbers:
description: "The page numbers in the design that support this export format,\
\ in ascending order. The first page in a design is page `1`. If omitted,\
\ the format is supported by all pages in the design."
example:
- 1
- 2
- 3
items:
format: int32
minimum: 1
type: integer
type: array
type: object
SvgExportFormatOption:
description: Whether the design can be exported as an SVG.
properties:
page_numbers:
description: "The page numbers in the design that support this export format,\
\ in ascending order. The first page in a design is page `1`. If omitted,\
\ the format is supported by all pages in the design."
example:
- 1
- 2
- 3
items:
format: int32
minimum: 1
type: integer
type: array
type: object
PptxExportFormatOption:
description: Whether the design can be exported as a PPTX.
properties:
page_numbers:
description: "The page numbers in the design that support this export format,\
\ in ascending order. The first page in a design is page `1`. If omitted,\
\ the format is supported by all pages in the design."
example:
- 1
- 2
- 3
items:
format: int32
minimum: 1
type: integer
type: array
type: object
Mp4ExportFormatOption:
description: Whether the design can be exported as an MP4.
properties:
page_numbers:
description: "The page numbers in the design that support this export format,\
\ in ascending order. The first page in a design is page `1`. If omitted,\
\ the format is supported by all pages in the design."
example:
- 1
- 2
- 3
items:
format: int32
minimum: 1
type: integer
type: array
type: object
HtmlBundleExportFormatOption:
description: Whether the design can be exported as an HTML bundle.
properties:
page_numbers:
description: "The page numbers in the design that support this export format,\
\ in ascending order. The first page in a design is page `1`. If omitted,\
\ the format is supported by all pages in the design."
example:
- 1
- 2
- 3
items:
format: int32
minimum: 1
type: integer
type: array
type: object
HtmlStandaloneExportFormatOption:
description: Whether the design can be exported as an standalone HTML file.
properties:
page_numbers:
description: "The page numbers in the design that support this export format,\
\ in ascending order. The first page in a design is page `1`. If omitted,\
\ the format is supported by all pages in the design."
example:
- 1
- 2
- 3
items:
format: int32
minimum: 1
type: integer
type: array
type: object
CsvExportFormatOption:
description: Whether the design can be exported as a CSV file.
properties:
page_numbers:
description: "The page numbers in the design that support this export format,\
\ in ascending order. The first page in a design is page `1`. If omitted,\
\ the format is supported by all pages in the design."
example:
- 1
- 2
- 3
items:
format: int32
minimum: 1
type: integer
type: array
type: object
ExportError:
description: "If the export fails, this object provides details about the error."
properties:
code:
$ref: '#/components/schemas/ExportErrorCode'
message:
description: A human-readable description of what went wrong.
type: string
required:
- code
- message
type: object
ExportErrorCode:
description: "If the export failed, this specifies the reason why it failed."
enum:
- license_required
- approval_required
- internal_failure
type: string
x-enum-descriptions:
- "The design contains [premium elements](https://www.canva.com/help/premium-elements/)\
\ that haven't been purchased. You can either buy the elements or upgrade\
\ to a Canva plan (such as Canva Pro) that has premium features, then try\
\ again. Alternatively, you can set `export_quality` to `regular` to export\
\ your document in regular quality."
- "The design requires [reviewer approval](https://www.canva.com/en_au/help/design-approval/)\
\ before it can be exported."
- The service encountered an error when exporting your design.
ExportQuality:
default: regular
description: Specifies the export quality of the design.
enum:
- regular
- pro
type: string
x-enum-descriptions:
- Regular quality export.
- |-
Premium quality export.
NOTE: A `pro` export might fail if the design contains [premium elements](https://www.canva.com/help/premium-elements/) and the calling user either hasn't purchased the elements or isn't on a Canva plan (such as Canva Pro) that has premium features.
FolderItemSortBy:
default: modified_descending
enum:
- created_ascending
- created_descending
- modified_ascending
- modified_descending
- title_ascending
- title_descending
type: string
x-enum-descriptions:
- "Sort results by creation date, in ascending order."
- "Sort results by creation date, in descending order."
- "Sort results by the last modified date, in ascending order."
- "Sort results by the last modified date, in descending order."
- "Sort results by title, in ascending order. The title is either the `name`\
\ field for a folder or asset, or the `title` field for a design or brand\
\ template."
- "Sort results by title, in descending order. The title is either the `name`\
\ field for a folder or asset, or the `title` field for a design or brand\
\ template."
FolderItemType:
enum:
- design
- folder
- image
- brand_template
type: string
FolderItemPinStatus:
default: any
description: Filter folder items by their pinned status.
enum:
- any
- pinned
type: string
x-enum-descriptions:
- Return all items regardless of pinned status (default).
- Return only pinned items.
GetFolderResponse:
description: The folder ID.
properties:
folder:
$ref: '#/components/schemas/Folder'
required:
- folder
type: object
CreateFolderRequest:
description: Body parameters for creating a new folder.
properties:
name:
description: The name of the folder.
example: My awesome holiday
maxLength: 255
minLength: 1
type: string
parent_folder_id:
description: |-
The folder ID of the parent folder. To create a new folder at the top level of a user's
[projects](https://www.canva.com/help/find-designs-and-folders/), use the ID `root`.
To create it in their Uploads folder, use `uploads`.
example: FAF2lZtloor
maxLength: 50
minLength: 1
type: string
required:
- name
- parent_folder_id
type: object
CreateFolderResponse:
description: Details about the new folder.
properties:
folder:
$ref: '#/components/schemas/Folder'
type: object
UpdateFolderRequest:
description: Body parameters for updating the folder's details.
properties:
name:
description: "The folder name, as shown in the Canva UI."
example: My awesome holiday
maxLength: 255
minLength: 1
type: string
required:
- name
type: object
UpdateFolderResponse:
description: Details about the updated folder.
properties:
folder:
$ref: '#/components/schemas/Folder'
type: object
ListFolderItemsResponse:
description: |-
A list of the items in a folder.
If the success response contains a continuation token, the folder contains more items
you can list. You can use this token as a query parameter and retrieve more
items from the list, for example
`/v1/folders/{folderId}/items?continuation={continuation}`.
To retrieve all the items in a folder, you might need to make multiple requests.
properties:
items:
description: An array of items in the folder.
items:
$ref: '#/components/schemas/FolderItemSummary'
type: array
continuation:
description: |-
If the success response contains a continuation token, the folder contains more items
you can list. You can use this token as a query parameter and retrieve more
items from the list, for example
`/v1/folders/{folderId}/items?continuation={continuation}`.
To retrieve all the items in a folder, you might need to make multiple requests.
example: RkFGMgXlsVTDbMd:MR3L0QjiaUzycIAjx0yMyuNiV0OildoiOwL0x32G4NjNu4FwtAQNxowUQNMMYN
type: string
required:
- items
type: object
FolderItemSummary:
description: Details about the folder item.
discriminator:
mapping:
folder: '#/components/schemas/FolderItem'
design: '#/components/schemas/DesignItem'
image: '#/components/schemas/ImageItem'
brand_template: '#/components/schemas/BrandTemplateItem'
propertyName: type
oneOf:
- $ref: '#/components/schemas/FolderItem'
- $ref: '#/components/schemas/DesignItem'
- $ref: '#/components/schemas/ImageItem'
- $ref: '#/components/schemas/BrandTemplateItem'
type: object
FolderItem:
description: Details about the folder.
properties:
type:
enum:
- folder
type: string
folder:
$ref: '#/components/schemas/Folder'
required:
- folder
- type
type: object
DesignItem:
description: Details about the design.
properties:
type:
enum:
- design
type: string
design:
$ref: '#/components/schemas/DesignSummary'
required:
- design
- type
type: object
ImageItem:
description: Details about the image asset.
properties:
type:
enum:
- image
type: string
image:
$ref: '#/components/schemas/AssetSummary'
required:
- image
- type
type: object
BrandTemplateItem:
description: Details about the brand template.
properties:
type:
enum:
- brand_template
type: string
brand_template:
$ref: '#/components/schemas/BrandTemplateSummary'
required:
- brand_template
- type
type: object
MoveFolderItemRequest:
description: Body parameters for moving the folder.
properties:
to_folder_id:
description: |-
The ID of the folder you want to move the item to (the destination folder).
If you want to move the item to the top level of a Canva user's
[projects](https://www.canva.com/help/find-designs-and-folders/), use the ID `root`.
example: FAF2lZtloor
maxLength: 50
minLength: 1
type: string
item_id:
description: "The ID of the item you want to move. Currently, video assets\
\ are not supported."
example: Msd59349ff
maxLength: 50
minLength: 1
type: string
required:
- item_id
- to_folder_id
type: object
Folder:
description: "The folder object, which contains metadata about the folder."
properties:
id:
description: The folder ID.
example: FAF2lZtloor
type: string
name:
description: The folder name.
example: My awesome holiday
type: string
created_at:
description: |-
When the folder was created, as a Unix timestamp (in seconds since the
Unix Epoch).
example: 1377396000
format: int64
type: integer
updated_at:
description: |-
When the folder was last updated, as a Unix timestamp (in seconds since the
Unix Epoch).
example: 1692928800
format: int64
type: integer
thumbnail:
$ref: '#/components/schemas/Thumbnail'
required:
- created_at
- id
- name
- updated_at
type: object
FolderSummary:
description: |-
This object contains some folder metadata. You can retrieve additional metadata
using the folder ID and the `/v1/folders/{folderId}` endpoint.
properties:
id:
description: The folder ID.
example: FAF2lZtloor
type: string
title:
deprecated: true
description: |-
The folder name, as shown in the Canva UI. This property is deprecated, so you should
use the `name` property instead.
example: My awesome holiday
type: string
name:
description: "The folder name, as shown in the Canva UI."
example: My awesome holiday
type: string
created_at:
description: |-
When the folder was created, as a Unix timestamp (in seconds since the
Unix Epoch).
example: 1377396000
format: int64
type: integer
updated_at:
description: |-
When the folder was last updated, as a Unix timestamp (in seconds since the
Unix Epoch).
example: 1692928800
format: int64
type: integer
url:
description: The folder URL.
example: https://www.canva.com/folder/FAF2lZtloor
type: string
required:
- created_at
- id
- name
- updated_at
type: object
Group:
description: |-
Metadata for the Canva Group, consisting of the Group ID,
display name, and whether it's an external Canva Group.
properties:
id:
description: The ID of the group with permissions to access the design.
example: dl9n9SoWoExMsw6Ri1iTg
type: string
display_name:
description: The display name of the group.
example: Sales team
type: string
external:
description: |-
Is the user making the API call (the authenticated user) and the Canva Group
from different Canva Teams?
- When `true`, the user and the group aren't in the same Canva Team.
- When `false`, the user and the group are in the same Canva Team.
type: boolean
required:
- external
- id
type: object
CreateImageGenerationJobRequest:
properties:
prompt:
description: A plain-text description of the image to generate.
maxLength: 10000
minLength: 1
type: string
aspect_ratio:
$ref: '#/components/schemas/ImageGenerationAspectRatio'
model:
$ref: '#/components/schemas/ImageGenerationModel'
idempotency_key:
description: |-
A key to make create requests idempotent. Retrying with the same key returns the
original job without creating a duplicate, even if the other request parameters
differ. Keys are held for 24 hours from job creation.
example: 550e8400-e29b-41d4-a716-446655440000
format: uuid
type: string
asset_upload:
$ref: '#/components/schemas/ImageGenerationAssetUpload'
required:
- idempotency_key
- prompt
type: object
ImageGenerationAssetUpload:
description: |-
Whether to save the generated image as an image asset in the user's Canva account.
Omitting `asset_upload` (or using `type: none`) returns only a download URL.
Saving the asset (`type: upload`) requires a user access token.
discriminator:
mapping:
none: '#/components/schemas/NoneImageGenerationAssetUpload'
upload: '#/components/schemas/UploadImageGenerationAssetUpload'
propertyName: type
oneOf:
- $ref: '#/components/schemas/NoneImageGenerationAssetUpload'
- $ref: '#/components/schemas/UploadImageGenerationAssetUpload'
NoneImageGenerationAssetUpload:
description: Don't save the generated image. The result contains only its download
URL.
properties:
type:
enum:
- none
type: string
required:
- type
type: object
UploadImageGenerationAssetUpload:
description: |-
Save the generated image as an image asset in the user's Canva account. The asset appears
in the user's Uploads, and the generated image in the result includes the `asset`
alongside its download `url`.
properties:
type:
enum:
- upload
type: string
asset_name:
description: |-
A name for the image asset. Canva doesn't localize this value, so provide a name in
the user's language. If omitted, Canva generates a name for the asset.
example: Red apple on a wooden table
maxLength: 255
minLength: 1
type: string
required:
- type
type: object
CreateImageGenerationJobResponse:
properties:
job:
$ref: '#/components/schemas/ImageGenerationJob'
required:
- job
type: object
GetImageGenerationJobResponse:
properties:
job:
$ref: '#/components/schemas/ImageGenerationJob'
required:
- job
type: object
ImageGenerationJob:
description: |-
Details about the image generation job. If the job status is `success`, the job's
`result` is present.
properties:
id:
description: The image generation job ID.
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
status:
$ref: '#/components/schemas/ImageGenerationJobStatus'
result:
$ref: '#/components/schemas/ImageGenerationJobResult'
error:
$ref: '#/components/schemas/ImageGenerationError'
required:
- id
- status
type: object
ImageGenerationJobResult:
description: Result of the image generation job. Only present if job status
is `success`.
properties:
image:
$ref: '#/components/schemas/GeneratedImage'
required:
- image
type: object
GeneratedImage:
description: A generated image.
properties:
url:
description: |-
A download URL for the generated image. The download URL is only valid for 24
hours.
type: string
asset:
allOf:
- $ref: '#/components/schemas/AssetSummary'
description: |-
The image asset the generated image was saved as. Only present if the job was created
with `asset_upload` set to `type: upload` and the asset still exists (for example, it's
absent if the user has since deleted the asset).
width:
description: The width of the generated image in pixels.
example: 1024
format: int32
type: integer
height:
description: The height of the generated image in pixels.
example: 1024
format: int32
type: integer
required:
- height
- url
- width
type: object
ImageGenerationJobStatus:
description: |-
The status of the image generation job. A newly created job will be `in_progress` and
will eventually become `success` or `failed`. If the status is `success`, the job's
`result` is present.
enum:
- failed
- in_progress
- success
type: string
ImageGenerationModel:
description: |-
The model to use for image generation. We recommend omitting this parameter: Canva
then selects the best available model for the request and falls back to another
model if one is temporarily unavailable. Set it only if you need a specific model's
output. If the requested model can't serve the request, the job fails. Canva never
uses a different model to serve the request.
The model strengths below are based on Canva's evaluations. Results vary by
prompt, so test with your own prompts before pinning a model.
enum:
- craft_v1_2k
- lucid_origin
- z_image_turbo
type: string
x-enum-descriptions:
- |-
CRAFT-1 2K, Canva's first-party image generation model. Pick this model for the best
image quality for infographics, posters, slides, people and portraits, abstract art,
patterns, landscapes, nature, products, and marketing materials.
- |-
Lucid Origin. Pick this for architecture, logos, posters, or sci-fi and fantasy
scenes.
- |-
Z Image Turbo. Pick this if the image includes text, or for food, drink, and
general-purpose imagery.
ImageGenerationAspectRatio:
description: |-
The aspect ratio of the generated image. Every aspect ratio is supported by every model
you can select with `model`, so the choice of model never limits the aspect ratios you
can use. The pixel dimensions of the output depend on the model. The job result reports
the actual `width` and `height`. If you omit the aspect ratio, Canva chooses one for the
image. Don't rely on a specific default: set the aspect ratio when the shape matters.
enum:
- square
- landscape
- portrait
- landscape_3_2
- portrait_2_3
- portrait_4_5
- landscape_4_3
- portrait_3_4
- landscape_5_4
- landscape_2_1
- portrait_1_2
type: string
x-enum-descriptions:
- A square (1:1) image.
- "A wide (16:9) image, suitable for landscape-oriented content."
- "A tall (9:16) image, suitable for portrait-oriented content."
- "A wide (3:2) image, suitable for photos and print."
- "A tall (2:3) image, suitable for posters and portrait photos."
- "A tall (4:5) image, suitable for social media feed posts."
- "A wide (4:3) image, suitable for presentations and classic photos."
- "A tall (3:4) image, suitable for portrait prints and social media."
- "A wide (5:4) image, suitable for prints and framed photos."
- "A wide (2:1) image, suitable for banners and panoramic headers."
- "A tall (1:2) image, suitable for tall banners and pins."
ImageGenerationErrorCode:
description: Error code indicating what went wrong with the image generation.
enum:
- unsafe_input
- timeout
- model_not_available
- model_retired
- internal_error
type: string
x-enum-descriptions:
- Content safety checks rejected the prompt.
- The generation did not complete in time.
- |-
The requested model can't currently serve this request, and Canva doesn't retry the job
with another model. This is usually temporary. Retry later, retry without the `model`
parameter to use automatic model selection, or retry with a different model.
- |-
The requested model has been permanently retired from this version of the API, and you
can't use it again in this version. Use a different model. The API documentation lists
retired models, which keep their enum value for the lifetime of this API version.
- An unexpected error occurred during generation.
ImageGenerationError:
description: "If the image generation job fails, this object provides details\
\ about the error. Only present if status is `failed`."
properties:
code:
$ref: '#/components/schemas/ImageGenerationErrorCode'
message:
description: A human-readable description of what went wrong.
type: string
required:
- code
- message
type: object
CreateImageTransformationJobRequest:
properties:
asset_id:
description: |-
The ID of the source asset to transform. The asset must be an image asset;
referencing any other asset type (such as a video) fails with an
`unsupported_content_type` error.
The asset must also have finished uploading. An asset that is still uploading has no
image to transform yet and fails with an `asset_not_ready` error. If you've just
created the asset, poll its upload job — for example with the
[Get asset upload job](https://www.canva.dev/docs/apps/rest-apis/reference/assets/get-asset-upload-job/)
endpoint — until it returns a `success` status before starting a transformation.
example: Msd59349ff
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
name:
description: |-
A name for the new image asset that the job produces. Canva doesn't localize this
value, so provide a name in the user's language. When omitted, the new asset inherits
the name of the source asset.
example: My Awesome Upload with the background removed
maxLength: 255
minLength: 1
type: string
transformations:
description: |-
The transformations to apply, in order. Must contain at least one transformation.
Each transformation is stacked on the result of the previous one. The job's result
is a single new image asset with all of the transformations applied; intermediate
results are not returned.
items:
$ref: '#/components/schemas/ImageTransformationType'
maxItems: 20
minItems: 1
type: array
required:
- asset_id
- transformations
type: object
ImageTransformationType:
description: |-
A transformation to apply to the image asset. Each transformation type is identified
by its `type` value and declares its own parameters; `background_removal` takes no
parameters.
discriminator:
mapping:
background_removal: '#/components/schemas/BackgroundRemovalImageTransformation'
propertyName: type
oneOf:
- $ref: '#/components/schemas/BackgroundRemovalImageTransformation'
BackgroundRemovalImageTransformation:
description: |-
Removes the background from an image, keeping the foreground subject. The resulting
image has a transparent background. This transformation takes no parameters.
The output image is limited to a maximum of 25 megapixels. If the source image is
larger, the output image is scaled down to stay within this limit.
Requires the user to have the `background_removal` capability. To check this before
creating a job, use the
[Get user capabilities API](https://www.canva.dev/docs/apps/rest-apis/reference/users/get-user-capabilities/).
properties:
type:
description: |-
The type of transformation to apply. Currently, the only supported value is
`background_removal`.
enum:
- background_removal
example: background_removal
type: string
required:
- type
type: object
CreateImageTransformationJobResponse:
properties:
job:
$ref: '#/components/schemas/ImageTransformationJob'
required:
- job
type: object
GetImageTransformationJobResponse:
properties:
job:
$ref: '#/components/schemas/ImageTransformationJob'
required:
- job
type: object
ImageTransformationJob:
description: |-
Details about the image transformation job. If the job status is `success`, the job's
`result` is present.
properties:
id:
description: |-
The image transformation job ID. Only present if the job status is `in_progress`.
A job that completes immediately returns its `result` or `error` directly and has
no ID to poll.
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
status:
$ref: '#/components/schemas/ImageTransformationJobStatus'
result:
$ref: '#/components/schemas/ImageTransformationJobResult'
error:
$ref: '#/components/schemas/ImageTransformationError'
required:
- status
type: object
ImageTransformationJobStatus:
description: |-
The status of the image transformation job. A newly created job will be `in_progress`
and will eventually become `success` or `failed`. A job may also complete
immediately, returning `success` or `failed` from job creation. If the status is
`success`, the job's `result` is present.
enum:
- failed
- in_progress
- success
type: string
ImageTransformationJobResult:
description: Result of the image transformation job. Only present if the job
status is `success`.
properties:
asset:
allOf:
- $ref: '#/components/schemas/Asset'
description: The new image asset produced by applying all of the requested
transformations.
url:
description: |-
A URL for retrieving the transformed image at full resolution.
This URL is temporary and includes a query string that's required for retrieving the
image. To get a new URL, call the
[Get image transformation job](https://www.canva.dev/docs/apps/rest-apis/reference/image-transformations/get-image-transformation-job/)
API again.
Only present if the user is allowed to access the transformed image at full
resolution. For example, it's omitted if the source asset contains premium content
that the user doesn't have a license for.
example: https://media-private.canva.com/Vczz9/zF9vzVtdADc/1/p.png?
type: string
required:
- asset
type: object
ImageTransformationErrorCode:
description: Error code indicating what went wrong with the image transformation.
enum:
- no_foreground_found
- quota_exceeded
- internal_error
type: string
x-enum-descriptions:
- "No foreground subject was found in the image, so there is no background to\
\ remove."
- "The user has run out of quota, such as their AI credit quota. The quota isn't\
\ necessarily specific to the requested transformations."
- An unexpected error occurred during the transformation.
ImageTransformationError:
description: |-
If the image transformation job fails, this object provides details about the error.
Only present if the job status is `failed`.
properties:
code:
$ref: '#/components/schemas/ImageTransformationErrorCode'
message:
description: A human-readable description of what went wrong.
type: string
required:
- code
- message
type: object
JsonWebKeySet:
properties:
keys:
description: An array of JSON Web Key values. The order of keys has no meaning.
items:
$ref: '#/components/schemas/JsonWebKey'
type: array
required:
- keys
type: object
JsonWebKey:
description: |-
Standard Json Web Key specification following https://www.rfc-editor.org/rfc/rfc7517 and
https://www.rfc-editor.org/rfc/rfc7518.html.
properties:
alg:
description: |-
The "alg" (algorithm) parameter identifies the algorithm intended for
use with the key.
See https://www.rfc-editor.org/rfc/rfc7517#section-4
type: string
kid:
description: |-
The "kid" (key ID) parameter is used to match a specific key. This
is used, for instance, to choose among a set of keys within a JWK Set
during key rollover. When "kid" values are used within a JWK Set,
different keys within the JWK Set SHOULD use distinct "kid" values.
The "kid" value is a case-sensitive string.
See https://www.rfc-editor.org/rfc/rfc7517#section-4
type: string
kty:
description: |-
The "kty" (key type) parameter identifies the cryptographic algorithm
family used with the key, such as "RSA" or "EC". The "kty" value is a
case-sensitive string. At the moment, only "RSA" is supported.
See https://www.rfc-editor.org/rfc/rfc7517#section-4
type: string
"n":
description: |-
The "n" (modulus) parameter contains the modulus value for the RSA
public key. It is represented as a Base64urlUInt-encoded value.
See https://www.rfc-editor.org/rfc/rfc7518.html#section-6.3
type: string
e:
description: |-
The "e" (exponent) parameter contains the exponent value for the RSA
public key. It is represented as a Base64urlUInt-encoded value.
See https://www.rfc-editor.org/rfc/rfc7518.html#section-6.3
type: string
use:
description: |-
The "use" (public key use) parameter identifies the intended use of
the public key. The "use" parameter is employed to indicate whether
a public key is used for encrypting data or verifying the signature
on data. Values are commonly "sig" (signature) or "enc" (encryption).
See https://www.rfc-editor.org/rfc/rfc7517#section-4
type: string
required:
- e
- kid
- kty
- "n"
type: object
CreateDesignMergeJobRequest:
discriminator:
mapping:
create_new_design: '#/components/schemas/NewDesignCreateDesignMergeJobRequest'
modify_existing_design: '#/components/schemas/ModifyDesignCreateDesignMergeJobRequest'
propertyName: type
oneOf:
- $ref: '#/components/schemas/NewDesignCreateDesignMergeJobRequest'
- $ref: '#/components/schemas/ModifyDesignCreateDesignMergeJobRequest'
NewDesignCreateDesignMergeJobRequest:
description: Creates a new design by inserting pages from other designs.
properties:
type:
description: The type of merge job to create.
enum:
- create_new_design
example: create_new_design
type: string
operations:
description: "For this job type, only insert operations are supported."
items:
$ref: '#/components/schemas/DesignMergeOperation'
maxItems: 500
minItems: 1
type: array
title:
description: Title for the new design.
example: My merged design
maxLength: 255
minLength: 1
type: string
required:
- operations
- title
- type
type: object
ModifyDesignCreateDesignMergeJobRequest:
description: "Modifies an existing design by inserting, moving, or deleting\
\ pages."
properties:
type:
description: The type of merge job to create.
enum:
- modify_existing_design
example: modify_existing_design
type: string
design_id:
description: The ID of the design to modify.
example: DAFVztcvd9z
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
operations:
description: "Supports insert, move, and delete operations."
items:
$ref: '#/components/schemas/DesignMergeOperation'
maxItems: 500
minItems: 1
type: array
title:
description: Optional new title for the design.
example: My updated design
maxLength: 255
minLength: 1
type: string
required:
- design_id
- operations
- type
type: object
DesignMergeOperation:
discriminator:
mapping:
insert_pages: '#/components/schemas/InsertPagesDesignMergeOperation'
move_pages: '#/components/schemas/MovePagesDesignMergeOperation'
delete_pages: '#/components/schemas/DeletePagesDesignMergeOperation'
propertyName: type
oneOf:
- $ref: '#/components/schemas/InsertPagesDesignMergeOperation'
- $ref: '#/components/schemas/MovePagesDesignMergeOperation'
- $ref: '#/components/schemas/DeletePagesDesignMergeOperation'
InsertPagesDesignMergeOperation:
description: Inserts pages from a source design into the target design.
properties:
type:
description: The type of merge operation.
enum:
- insert_pages
example: insert_pages
type: string
source:
$ref: '#/components/schemas/MergeSourceForInsertPagesOperation'
after_page_number:
description: |
Insert after this one-based page number in the evolving target layout. Use 0 to insert at the beginning, and the default is inserting at the end (append).
example: 2
format: int32
minimum: 0
type: integer
required:
- source
- type
type: object
MovePagesDesignMergeOperation:
description: Moves pages within the target design to a new position.
properties:
type:
description: The type of merge operation.
enum:
- move_pages
example: move_pages
type: string
from_page_numbers:
description: One-based number of the pages to move (evaluated at the time
this operation runs). Pages are moved in order.
example:
- 1
- 3
items:
format: int32
minimum: 1
type: integer
minItems: 1
type: array
to_after_page_number:
description: |
Destination position: insert the moved pages after this one-based page number. Use 0 to move to the beginning.
example: 2
format: int32
minimum: 0
type: integer
required:
- from_page_numbers
- to_after_page_number
- type
type: object
DeletePagesDesignMergeOperation:
description: Deletes pages from the target design.
properties:
type:
description: The type of merge operation.
enum:
- delete_pages
example: delete_pages
type: string
page_numbers:
description: One-based numbers of the pages to delete (evaluated at the
time this operation runs). Pages are deleted in reverse order to maintain
page numbers.
example:
- 2
- 4
items:
format: int32
minimum: 1
type: integer
minItems: 1
type: array
required:
- page_numbers
- type
type: object
MergeSourceForInsertPagesOperation:
discriminator:
mapping:
design: '#/components/schemas/DesignMergeSourceForInsertPagesOperation'
propertyName: type
oneOf:
- $ref: '#/components/schemas/DesignMergeSourceForInsertPagesOperation'
DesignMergeSourceForInsertPagesOperation:
description: A design source from which pages are inserted.
properties:
type:
description: The type of source to insert pages from.
enum:
- design
example: design
type: string
design_id:
description: The ID of the source design.
example: DAFVztcvd9z
pattern: "^[a-zA-Z0-9_-]{1,50}$"
type: string
page_numbers:
description: "One-based page numbers to insert from the source design. If\
\ omitted, all pages from the design are inserted."
example:
- 1
- 2
items:
format: int32
minimum: 1
type: integer
minItems: 1
type: array
required:
- design_id
- type
type: object
CreateDesignMergeJobResponse:
properties:
job:
$ref: '#/components/schemas/DesignMergeJob'
required:
- job
type: object
GetDesignMergeJobResponse:
properties:
job:
$ref: '#/components/schemas/DesignMergeJob'
required:
- job
type: object
DesignMergeJob:
description: The details of a design merge job.
properties:
id:
description: The ID of the design merge job.
example: a7by3wd-abc123
type: string
status:
$ref: '#/components/schemas/DesignMergeJobStatus'
result:
$ref: '#/components/schemas/DesignMergeJobResult'
error:
$ref: '#/components/schemas/DesignMergeError'
required:
- id
- status
type: object
DesignMergeJobStatus:
enum:
- in_progress
- success
- failed
type: string
x-enum-descriptions:
- The merge job is still running.
- The merge job completed successfully.
- The merge job failed.
DesignMergeJobResult:
properties:
design:
$ref: '#/components/schemas/DesignSummary'
required:
- design
type: object
DesignMergeErrorCode:
enum:
- thumbnail_generation_error
- merge_error
- create_design_error
- modify_design_error
type: string
DesignMergeError:
description: "If the merge job fails, this object provides details about the\
\ error."
properties:
code:
$ref: '#/components/schemas/DesignMergeErrorCode'
message:
description: A human-readable description of what went wrong.
example: The merge job failed due to an internal error.
type: string
required:
- code
- message
type: object
ExchangeAccessTokenRequest:
discriminator:
mapping:
authorization_code: '#/components/schemas/ExchangeAuthCodeRequest'
refresh_token: '#/components/schemas/ExchangeRefreshTokenRequest'
client_credentials: '#/components/schemas/ExchangeClientCredentialsRequest'
propertyName: grant_type
oneOf:
- $ref: '#/components/schemas/ExchangeAuthCodeRequest'
- $ref: '#/components/schemas/ExchangeRefreshTokenRequest'
- $ref: '#/components/schemas/ExchangeClientCredentialsRequest'
type: object
ExchangeAuthCodeRequest:
properties:
grant_type:
description: For exchanging an authorization code for an access token.
enum:
- authorization_code
example: authorization_code
type: string
code_verifier:
description: The `code_verifier` value that you generated when creating
the user authorization URL.
example: i541qdcfkb4htnork0w92lnu43en99ls5a48ittv6udqgiflqon8vusojojakbq4
type: string
code:
description: The authorization code you received after the user authorized
the app.
example: kp8nnroja7qnx00.opyc1p76rcbyflsxbycjqfp3ub8vzsvltpzwafy9q5l45dn5fxzhe7i7a6mg1i2t8jpsa6sebdeumkzzhicskabgevrxsssec4dvjwfvhq4gs3ugghguar0voiqpfb7axsapiojoter8v3w2s5s3st84jpv2l06h667iw241xngy9c8=vu1tnjp7sz
type: string
client_id:
description: |
Your app's unique ID, for authenticating the request.
NOTE: We recommend that you use basic access authentication instead of specifying `client_id` and `client_secret` as body parameters.
example: OC-FAB12-AbCdEf
type: string
client_secret:
description: |
Your app's client secret, for authenticating the request. Begins with `cnvca`.
NOTE: We recommend that you use basic access authentication instead of specifying `client_id` and `client_secret` as body parameters.
example: cnvcaAbcdefg12345_hijklm6789
type: string
redirect_uri:
description: |
Only required if a redirect URL was supplied when you [created the user authorization URL](https://www.canva.dev/docs/apps/rest-apis/authentication/#create-the-authorization-url).
Must be one of those already specified by the client. If not supplied, the first redirect_uri defined for the client will be used by default.
example: https://example.com/process-auth
type: string
required:
- code
- code_verifier
- grant_type
type: object
ExchangeRefreshTokenRequest:
properties:
grant_type:
description: For generating an access token using a refresh token.
enum:
- refresh_token
example: refresh_token
type: string
client_id:
description: |
Your app's unique ID, for authenticating the request.
NOTE: We recommend that you use basic access authentication instead of specifying `client_id` and `client_secret` as body parameters.
example: OC-FAB12-AbCdEf
type: string
client_secret:
description: |
Your app's client secret, for authenticating the request. Begins with `cnvca`.
NOTE: We recommend that you use basic access authentication instead of specifying `client_id` and `client_secret` as body parameters.
example: cnvcaAbcdefg12345_hijklm6789
type: string
refresh_token:
description: The refresh token to be exchanged. You can copy this value
from the successful response received when generating an access token.
example: JABix5nolsk9k8n2r0f8nq1gw4zjo40ht6sb4i573wgdzmkwdmiy6muh897hp0bxyab276wtgqkvtob2mg9aidt5d6rcltcbcgs101
type: string
scope:
description: |
Optional scope value when refreshing an access token. Separate multiple [scopes](https://www.canva.dev/docs/apps/rest-apis/scopes/) with a single space between each scope.
The requested scope cannot include any permissions not already granted, so this parameter allows you to limit the scope when refreshing a token. If omitted, the scope for the token remains unchanged.
example: design:meta:read
type: string
required:
- grant_type
- refresh_token
type: object
ExchangeClientCredentialsRequest:
properties:
grant_type:
description: For generating an access token using your app's client credentials.
Only service apps can use this grant type.
enum:
- client_credentials
example: client_credentials
type: string
client_id:
description: |
Your app's unique ID, for authenticating the request.
NOTE: We recommend that you use basic access authentication instead of specifying `client_id` and `client_secret` as body parameters.
example: OC-FAB12-AbCdEf
type: string
client_secret:
description: |
Your app's client secret, for authenticating the request. Begins with `cnvca`.
NOTE: We recommend that you use basic access authentication instead of specifying `client_id` and `client_secret` as body parameters.
example: cnvcaAbcdefg12345_hijklm6789
type: string
scope:
description: |
Optional scope value when generating an access token using client credentials. Separate multiple [scopes for service apps](https://www.canva.dev/docs/apps/rest-apis/scopes/#scopes-for-service-apps) with a single space between each scope.
The requested scopes must be enabled for your app in the Developer Portal. If omitted, the token is granted all the scopes that are enabled for your app.
example: service:design:meta:read
type: string
required:
- grant_type
type: object
ExchangeAccessTokenResponse:
description: Exchange auth token to access token.
properties:
access_token:
description: "The bearer access token to use to authenticate to Canva REST\
\ API endpoints. If requested using `authorization_code` or `refresh_token`,\
\ this allows you to act on behalf of a user. If requested using `client_credentials`,\
\ this allows your service app to act on its own behalf."
example: JagALLazU0i2ld9WW4zTO4kaG0lkvP8Y5sSO206ZwxNF4E1y3xKJKF7TzN17BXTfaNOeY0P88AeRCE6cRF7SJzvf3Sx97rA80sGHtFplFo
type: string
refresh_token:
description: |
The token that you can use to refresh the access token.
This is only returned when the access token was requested using `authorization_code` or `refresh_token`. Access tokens requested using `client_credentials` don't have a refresh token, so service apps generate a new access token instead.
example: JABix5nolsk9k8n2r0f8nq1gw4zjo40ht6sb4i573wgdzmkwdmiy6muh897hp0bxyab276wtgqkvtob2mg9aidt5d6rcltcbcgs101
type: string
token_type:
description: The token type returned. This is always `Bearer`.
example: Bearer
type: string
expires_in:
description: The expiry time (in seconds) for the access token.
example: 14400
format: int64
type: integer
scope:
description: "The [scopes](https://www.canva.dev/docs/apps/rest-apis/scopes/)\
\ that the token has been granted."
example: asset:read design:meta:read design:permission:read folder:read
type: string
required:
- access_token
- expires_in
- refresh_token
- token_type
type: object
IntrospectTokenRequest:
properties:
token:
description: The token to introspect.
example: JagALLazU0i2ld9WW4zTO4kaG0lkvP8Y5sSO206ZwxNF4E1y3xKJKF7TzN17BXTfaNOeY0P88AeRCE6cRF7SJzvf3Sx97rA80sGHtFplFo
type: string
client_id:
description: |
Your app's unique ID, for authenticating the request.
NOTE: We recommend that you use basic access authentication instead of specifying `client_id` and `client_secret` as body parameters.
example: OC-FAB12-AbCdEf
type: string
client_secret:
description: |
Your app's client secret, for authenticating the request. Begins with `cnvca`.
NOTE: We recommend that you use basic access authentication instead of specifying `client_id` and `client_secret` as body parameters.
example: cnvcaAbcdefg12345_hijklm6789
type: string
required:
- token
type: object
IntrospectTokenResponse:
description: Introspection result of access or refresh tokens
properties:
active:
description: |
Whether the access token is active.
If `true`, the access token is valid and active. If `false`, the access token is invalid.
example: true
type: boolean
scope:
description: "The [scopes](https://www.canva.dev/docs/apps/rest-apis/scopes/)\
\ that the token has been granted."
example: asset:read design:meta:read design:permission:read folder:read
type: string
client:
description: The ID of the client that requested the token.
example: OC-FAB12-AbCdEf
type: string
exp:
description: "The expiration time of the token, as a [Unix timestamp](https://en.wikipedia.org/wiki/Unix_time)\
\ in seconds."
example: 1712216144
format: int64
type: integer
iat:
description: "When the token was issued, as a [Unix timestamp](https://en.wikipedia.org/wiki/Unix_time)\
\ in seconds."
example: 1712201744
format: int64
type: integer
nbf:
description: "The \"not before\" time of the token, which specifies the\
\ time before which the access token most not be accepted, as a [Unix\
\ timestamp](https://en.wikipedia.org/wiki/Unix_time) in seconds."
example: 1712201744
format: int64
type: integer
jti:
description: A unique ID for the access token.
example: AbC1d-efgHIJKLMN2oPqrS
type: string
sub:
description: |
The subject of the claim. This is the ID of the Canva user that the access token acts on behalf of.
This is an obfuscated value, so a single user has a unique ID for each app. If the same user authorizes another app, their ID in that other app is different.
example: oBCdEF1Gh2i3jkLmno-pq
type: string
required:
- active
type: object
RevokeTokensRequest:
description: Supply an access token or refresh token to have its lineage revoked.
properties:
token:
description: The token to revoke.
example: agALLazU0i2ld9WW4zTO4kaG0lkvP8Y5sSO206ZwxNF4E1y3xKJKF7TzN17BXTfaNOeY0P88AeRCE6cRF7SJzvf3Sx97rA80sGHtFplFo
type: string
client_id:
description: |
Your app's unique ID, for authenticating the request.
NOTE: We recommend that you use basic access authentication instead of specifying `client_id` and `client_secret` as body parameters.
example: OC-FAB12-AbCdEf
type: string
client_secret:
description: |
Your app's client secret, for authenticating the request. Begins with `cnvca`.
NOTE: We recommend that you use basic access authentication instead of specifying `client_id` and `client_secret` as body parameters.
example: cnvcaAbcdefg12345_hijklm6789
type: string
required:
- token
type: object
RevokeTokensResponse:
description: The response on a successful token revocation.
type: object
scope_response:
description: "The [scopes](https://www.canva.dev/docs/apps/rest-apis/scopes/)\
\ that the token has been granted."
example: asset:read design:meta:read design:permission:read folder:read
type: string
client_id:
description: |
Your app's unique ID, for authenticating the request.
NOTE: We recommend that you use basic access authentication instead of specifying `client_id` and `client_secret` as body parameters.
example: OC-FAB12-AbCdEf
type: string
client_secret:
description: |
Your app's client secret, for authenticating the request. Begins with `cnvca`.
NOTE: We recommend that you use basic access authentication instead of specifying `client_id` and `client_secret` as body parameters.
example: cnvcaAbcdefg12345_hijklm6789
type: string
UserInfoResponse:
example:
sub: UAAAAAAAAA
name: Alice Person
given_name: Alice
family_name: Person
email: alice.person@example.com
email_verified: true
properties:
sub:
description: Identifier for the End-User at the Issuer.
type: string
name:
description: |-
End-User's full name in displayable form including all name parts, possibly including
titles and suffixes, ordered according to the End-User's locale and preferences.
type: string
given_name:
description: |-
Given name(s) or first name(s) of the End-User. Note that in some cultures, people can
have multiple given names; all can be present, with the names being separated by space
characters.
type: string
family_name:
description: |-
Surname(s) or last name(s) of the End-User. Note that in some cultures, people can have
multiple family names or no family name; all can be present, with the names being
separated by space characters.
type: string
email:
description: |-
End-User's preferred e-mail address. Its value MUST conform to the RFC 5322 [RFC5322]
addr-spec syntax. The RP MUST NOT rely upon this value being unique, as discussed in
Section 5.7.
format: email
type: string
email_verified:
description: |-
True if the End-User's e-mail address has been verified; otherwise false. When this
Claim Value is true, this means that the OP took affirmative steps to ensure that this
e-mail address was controlled by the End-User at the time the verification was
performed. The means by which an e-mail address is verified is context specific,
and dependent upon the trust framework or contractual agreements within which the
parties are operating.
type: boolean
required:
- sub
type: object
Interval:
description: The interval at which the usage resets. 'never' means lifetime
quota that never resets.
enum:
- day
- week
- month
- year
- never
type: string
FeatureId:
description: "Unique identification string for the feature. Need to be in `{application-id}.{feature-name}`\
\ pattern"
example: ingredient-generation.generate-image
pattern: "^[a-z0-9-]+\\.[a-z0-9-]+$"
type: string
FeatureQuotaLimit:
description: |
The quota limit set by the caller for this feature. This limit is used to determine if usage exceeds the customer-defined threshold.
If not provided, we assume the usage is unlimited.
format: int32
minimum: 1
type: integer
CreateDesignResizeJobRequest:
description: |-
Body parameters for starting a resize job for a design.
It must include a design ID, and one of the supported design type.
properties:
design_id:
description: The design ID.
type: string
design_type:
$ref: '#/components/schemas/DesignTypeInput'
required:
- design_id
- design_type
type: object
CreateDesignResizeJobResponse:
properties:
job:
$ref: '#/components/schemas/DesignResizeJob'
required:
- job
type: object
GetDesignResizeJobResponse:
properties:
job:
$ref: '#/components/schemas/DesignResizeJob'
required:
- job
type: object
DesignResizeJob:
description: Details about the design resize job.
properties:
id:
description: The design resize job ID.
example: bbd8dfcd-ead1-4871-81d5-962bfec82274
type: string
status:
$ref: '#/components/schemas/DesignResizeStatus'
result:
$ref: '#/components/schemas/DesignResizeJobResult'
error:
$ref: '#/components/schemas/DesignResizeError'
required:
- id
- status
type: object
DesignResizeJobResult:
description: |-
Design has been created and saved to user's root
([projects](https://www.canva.com/help/find-designs-and-folders/)) folder.
properties:
design:
$ref: '#/components/schemas/DesignSummary'
trial_information:
$ref: '#/components/schemas/TrialInformation'
required:
- design
type: object
DesignResizeStatus:
description: Status of the design resize job.
enum:
- in_progress
- success
- failed
example: success
type: string
DesignResizeErrorCode:
enum:
- thumbnail_generation_error
- design_resize_error
- create_design_error
- trial_quota_exceeded
type: string
DesignResizeError:
description: "If the design resize job fails, this object provides details about\
\ the error."
properties:
code:
$ref: '#/components/schemas/DesignResizeErrorCode'
message:
description: A human-readable description of what went wrong.
type: string
required:
- code
- message
type: object
TrialInformation:
description: |-
WARNING: Trials and trial information are a [preview feature](https://www.canva.dev/docs/apps/rest-apis/#preview-apis).
There might be unannounced breaking changes to this feature which won't produce a new API version.
Trial information for non-qualifying users. Non-qualifying users have a limited number of
resize uses. Once the trial is exhausted, users must upgrade to a Canva plan with premium
features (such as Canva Pro) to continue using the Resize API.
properties:
uses_remaining:
description: The number of uses remaining in the free trial.
example: 0
format: int32
minimum: 0
type: integer
upgrade_url:
description: The URL for a user to upgrade their Canva account.
example: https://www.canva.com/?tailoringUpsellDialog=GENERIC_C4W
type: string
required:
- upgrade_url
- uses_remaining
type: object
Team:
description: |-
Metadata for the Canva Team, consisting of the Team ID,
display name, and whether it's an external Canva Team.
properties:
id:
description: The ID of the Canva Team.
example: Oi2RJILTrKk0KRhRUZozX
type: string
display_name:
description: The name of the Canva Team as shown in the Canva UI.
example: Acme Corporation
type: string
external:
description: |-
Is the user making the API call (the authenticated user) from the Canva Team shown?
- When `true`, the user isn't in the Canva Team shown.
- When `false`, the user is in the Canva Team shown.
type: boolean
required:
- display_name
- external
- id
type: object
Thumbnail:
description: A thumbnail image representing the object.
properties:
width:
description: The width of the thumbnail image in pixels.
example: 595
format: int32
type: integer
height:
description: The height of the thumbnail image in pixels.
example: 335
format: int32
type: integer
url:
description: |-
A URL for retrieving the thumbnail image.
This URL expires after 15 minutes. This URL includes a query string
that's required for retrieving the thumbnail.
example: https://document-export.canva.com/Vczz9/zF9vzVtdADc/2/thumbnail/0001.png?
type: string
required:
- height
- url
- width
type: object
User:
description: "Metadata for the user, consisting of the User ID and display name."
properties:
id:
description: The ID of the user.
example: uKakKUfI03Fg8k2gZ6OkT
type: string
display_name:
description: The name of the user as shown in the Canva UI.
example: John Doe
type: string
required:
- id
type: object
TeamUserSummary:
description: "Metadata for the user, consisting of the User ID and Team ID."
properties:
user_id:
description: The ID of the user.
example: auDAbliZ2rQNNOsUl5OLu
type: string
team_id:
description: The ID of the user's Canva Team.
example: Oi2RJILTrKk0KRhRUZozX
type: string
required:
- team_id
- user_id
type: object
TeamUser:
description: "Metadata for the user, consisting of the User ID, Team ID, and\
\ display name."
properties:
user_id:
description: The ID of the user.
example: auDAbliZ2rQNNOsUl5OLu
type: string
team_id:
description: The ID of the user's Canva Team.
example: Oi2RJILTrKk0KRhRUZozX
type: string
display_name:
description: The name of the user as shown in the Canva UI.
example: Jane Doe
type: string
type: object
UserProfile:
description: "Profile for the user, consisting of the display name and other\
\ attributes."
properties:
display_name:
description: The name of the user as shown in the Canva UI.
example: Jane Doe
type: string
type: object
UsersMeResponse:
properties:
team_user:
$ref: '#/components/schemas/TeamUserSummary'
required:
- team_user
type: object
UserProfileResponse:
properties:
profile:
$ref: '#/components/schemas/UserProfile'
required:
- profile
type: object
GetUserCapabilitiesResponse:
properties:
capabilities:
items:
$ref: '#/components/schemas/Capability'
type: array
type: object
Notification:
properties:
id:
description: The unique identifier for the notification.
example: eb595730
type: string
created_at:
description: |-
When the notification was created, as a UNIX timestamp (in seconds
since the UNIX epoch).
example: 1377396000
format: int64
type: integer
content:
$ref: '#/components/schemas/NotificationContent'
required:
- content
- created_at
- id
type: object
NotificationContent:
description: "The notification content object, which contains metadata about\
\ the event."
discriminator:
mapping:
share_design: '#/components/schemas/ShareDesignNotificationContent'
share_folder: '#/components/schemas/ShareFolderNotificationContent'
comment: '#/components/schemas/CommentNotificationContent'
design_access_requested: '#/components/schemas/DesignAccessRequestedNotificationContent'
design_approval_requested: '#/components/schemas/DesignApprovalRequestedNotificationContent'
design_approval_response: '#/components/schemas/DesignApprovalResponseNotificationContent'
design_approval_reviewer_invalidated: '#/components/schemas/DesignApprovalReviewerInvalidatedNotificationContent'
design_mention: '#/components/schemas/DesignMentionNotificationContent'
team_invite: '#/components/schemas/TeamInviteNotificationContent'
folder_access_requested: '#/components/schemas/FolderAccessRequestedNotificationContent'
suggestion: '#/components/schemas/SuggestionNotificationContent'
propertyName: type
oneOf:
- $ref: '#/components/schemas/ShareDesignNotificationContent'
- $ref: '#/components/schemas/ShareFolderNotificationContent'
- $ref: '#/components/schemas/CommentNotificationContent'
- $ref: '#/components/schemas/DesignAccessRequestedNotificationContent'
- $ref: '#/components/schemas/DesignApprovalRequestedNotificationContent'
- $ref: '#/components/schemas/DesignApprovalResponseNotificationContent'
- $ref: '#/components/schemas/DesignApprovalReviewerInvalidatedNotificationContent'
- $ref: '#/components/schemas/DesignMentionNotificationContent'
- $ref: '#/components/schemas/TeamInviteNotificationContent'
- $ref: '#/components/schemas/FolderAccessRequestedNotificationContent'
- $ref: '#/components/schemas/SuggestionNotificationContent'
type: object
ShareDesignNotificationContent:
description: The notification content for when someone shares a design.
properties:
type:
enum:
- share_design
example: share_design
type: string
triggering_user:
$ref: '#/components/schemas/User'
receiving_team_user:
$ref: '#/components/schemas/TeamUser'
design:
$ref: '#/components/schemas/DesignSummary'
share_url:
description: A URL that the user who receives the notification can use to
access the shared design.
example: https://www.canva.com/api/action?token=zWiz3GqRaWVkolwSgfBa9sKbsKgfHAoxv_mjs-mlX2M
type: string
share:
$ref: '#/components/schemas/ShareAction'
required:
- design
- receiving_team_user
- share_url
- triggering_user
- type
type: object
ShareFolderNotificationContent:
description: The notification content for when someone shares a folder.
properties:
type:
enum:
- share_folder
example: share_folder
type: string
triggering_user:
$ref: '#/components/schemas/User'
receiving_team_user:
$ref: '#/components/schemas/TeamUser'
folder:
$ref: '#/components/schemas/FolderSummary'
share:
$ref: '#/components/schemas/ShareAction'
required:
- folder
- receiving_team_user
- triggering_user
- type
type: object
CommentNotificationContent:
description: The notification content for when someone comments on a design.
properties:
type:
enum:
- comment
example: comment
type: string
triggering_user:
$ref: '#/components/schemas/User'
receiving_team_user:
$ref: '#/components/schemas/TeamUser'
design:
$ref: '#/components/schemas/DesignSummary'
comment_url:
deprecated: true
description: |-
A URL to the design, focused on the new comment.
The `comment_url` property is deprecated.
For details of the comment event, use the `comment_event` property instead.
example: https://www.canva.com/design/3WCduQdjayTcPVM/z128cqanFu7E3/edit?ui=OdllGgZ4Snnq3MD8uI10bfA
type: string
comment:
$ref: '#/components/schemas/CommentEventDeprecated'
comment_event:
$ref: '#/components/schemas/CommentEvent'
required:
- design
- receiving_team_user
- triggering_user
- type
type: object
DesignAccessRequestedNotificationContent:
description: The notification content for when someone requests access to a
design.
properties:
type:
enum:
- design_access_requested
example: design_access_requested
type: string
triggering_user:
$ref: '#/components/schemas/TeamUser'
receiving_team_user:
$ref: '#/components/schemas/TeamUser'
design:
$ref: '#/components/schemas/DesignSummary'
grant_access_url:
description: |-
A URL, which is scoped only to the user that can grant the requested access to the
design, that approves the requested access.
example: https://www.canva.com/api/action?token=OosRN8M_eO2-QbLpUmP5JCwTMSXWfadtQYWuj9WKzoE
type: string
required:
- design
- grant_access_url
- receiving_team_user
- triggering_user
- type
type: object
DesignApprovalRequestedNotificationContent:
description: |-
The notification content for when someone requests a user to
[approve a design](https://www.canva.com/help/get-approval/).
properties:
type:
enum:
- design_approval_requested
example: design_approval_requested
type: string
triggering_user:
$ref: '#/components/schemas/User'
initial_requesting_user:
$ref: '#/components/schemas/TeamUser'
receiving_team_user:
$ref: '#/components/schemas/TeamUser'
requested_groups:
items:
$ref: '#/components/schemas/Group'
type: array
design:
$ref: '#/components/schemas/DesignSummary'
approve_url:
description: |-
A URL, which is scoped only to the user requested to review the design, that links to
the design with the approval UI opened.
example: https://canva.com/api/action?token=HZb0lLHaEhNkT1qQrAwoe0-8SqyXUgJ4vnHGvN2rLZ0
type: string
approval_request:
$ref: '#/components/schemas/ApprovalRequestAction'
required:
- approval_request
- approve_url
- design
- initial_requesting_user
- receiving_team_user
- requested_groups
- triggering_user
- type
type: object
DesignApprovalResponseNotificationContent:
description: The notification content for when someone approves a design or
gives feedback.
properties:
type:
enum:
- design_approval_response
example: design_approval_response
type: string
triggering_user:
$ref: '#/components/schemas/User'
receiving_team_user:
$ref: '#/components/schemas/TeamUser'
initial_requesting_user:
$ref: '#/components/schemas/TeamUser'
responding_groups:
items:
$ref: '#/components/schemas/Group'
type: array
design:
$ref: '#/components/schemas/DesignSummary'
approval_response:
$ref: '#/components/schemas/ApprovalResponseAction'
required:
- approval_response
- design
- initial_requesting_user
- receiving_team_user
- responding_groups
- triggering_user
- type
type: object
DesignApprovalReviewerInvalidatedNotificationContent:
description: The notification content for when a reviewer in a design is invalidated.
properties:
type:
enum:
- design_approval_reviewer_invalidated
example: design_approval_reviewer_invalidated
type: string
receiving_team_user:
$ref: '#/components/schemas/TeamUserSummary'
design:
$ref: '#/components/schemas/DesignSummary'
required:
- design
- receiving_team_user
- type
type: object
DesignMentionNotificationContent:
description: |-
The notification content for when someone mentions a user in a design.
The link to the design in this notification is valid for 30 days, and can only be opened by
the recipient of the notification.
properties:
type:
enum:
- design_mention
example: design_mention
type: string
triggering_user:
$ref: '#/components/schemas/User'
receiving_team_user:
$ref: '#/components/schemas/TeamUser'
design:
$ref: '#/components/schemas/DesignSummary'
required:
- design
- receiving_team_user
- triggering_user
- type
type: object
TeamInviteNotificationContent:
description: |-
The notification content for when someone is invited to a
[Canva team](https://www.canva.com/help/about-canva-for-teams/).
properties:
type:
enum:
- team_invite
example: team_invite
type: string
triggering_user:
$ref: '#/components/schemas/User'
receiving_user:
$ref: '#/components/schemas/User'
inviting_team:
$ref: '#/components/schemas/Team'
required:
- inviting_team
- receiving_user
- triggering_user
- type
type: object
FolderAccessRequestedNotificationContent:
description: The notification content for when someone requests access to a
folder.
properties:
type:
enum:
- folder_access_requested
example: folder_access_requested
type: string
triggering_user:
$ref: '#/components/schemas/TeamUser'
receiving_team_user:
$ref: '#/components/schemas/TeamUser'
folder:
$ref: '#/components/schemas/FolderSummary'
required:
- folder
- receiving_team_user
- triggering_user
- type
type: object
SuggestionNotificationContent:
description: |-
The notification content when someone does one of the following actions:
- Suggests edits to a design.
- Applies or rejects a suggestion.
- Replies to a suggestion.
- Mentions a user in a reply to a suggestion.
properties:
type:
enum:
- suggestion
type: string
triggering_user:
$ref: '#/components/schemas/User'
receiving_team_user:
$ref: '#/components/schemas/TeamUser'
design:
$ref: '#/components/schemas/DesignSummary'
suggestion_event_type:
$ref: '#/components/schemas/SuggestionEventType'
required:
- design
- receiving_team_user
- suggestion_event_type
- triggering_user
- type
type: object
ShareAction:
description: Metadata about the share event.
properties:
message:
description: |-
The optional message users can include when sharing something with another
user using the Canva UI.
example: Check this out!
type: string
required:
- message
type: object
ApprovalRequestAction:
description: Metadata about the design approval request.
properties:
message:
description: The message included by the user when requesting a design approval.
example: LGTM!
type: string
type: object
ApprovalResponseAction:
description: Metadata about the design approval response.
properties:
approved:
description: |-
Whether the design was approved. When `true`, the reviewer has approved
the design.
type: boolean
ready_to_publish:
description: |-
Whether the design is ready to publish. When `true`, the design has been approved
by all reviewers and can be published.
type: boolean
message:
description: The message included by a user responding to a design approval
request.
type: string
required:
- approved
type: object
securitySchemes:
basicAuth:
scheme: basic
type: http
oauthClientCredentials:
flows:
clientCredentials:
scopes:
service:design:content:write: Create designs on the app's behalf.
service:design:content:read: View the contents of the app's designs.
service:design:meta:read: View the metadata of the app's designs.
service:folder:write: "Move designs, assets, and folders between folders\
\ on the app's behalf."
service:asset:write: Upload assets on the app's behalf.
service:asset:read: "View the metadata for the app's assets, such as uploaded\
\ images."
service:brandtemplate:meta:read: View the metadata of the brand templates
associated with the developer's brand.
service:brandtemplate:content:read: Read the content of the brand templates
associated with the developer's brand.
tokenUrl: https://api.canva.com/auth/v1/oauth/token
type: oauth2
oauthAuthCode:
flows:
authorizationCode:
authorizationUrl: https://www.canva.com/api/oauth/authorize
scopes:
design:content:read: View the contents of the user's designs.
design:meta:read: View the metadata of the user's designs.
design:content:write: Create designs on the user's behalf.
folder:read: |-
View the metadata and contents of the user's folders, including their **Projects**
folder.
folder:write: |-
Add, move, or remove the user's folders. It also lets you edit folder metadata,
such as the folder's name.
folder:permission:write: "Set, update, or remove permissions assigned\
\ to the user's folders."
asset:read: "View the metadata for the user's assets, such as uploaded\
\ images."
asset:write: "Upload, update, or delete assets on the user's behalf."
comment:read: "View the comments on the user's designs, and the associated\
\ metadata."
comment:write: Create comments and replies on the user's designs.
collaboration:event: Receive webhook notifications about events relevant
to the user.
brandtemplate:meta:read: View the metadata of the brand templates associated
with the user's brand.
brandtemplate:content:read: Read the content of the brand templates associated
with the user's brand.
brandtemplate:content:write: Publish brand templates associated with the
user's brand.
profile:read: Read a user's profile and account information.
openid: Read user information through Open ID Connect (OIDC).
profile: Read user profile information through OIDC.
email: Read user email address through OIDC.
tokenUrl: https://api.canva.com/rest/v1/oauth/token
type: oauth2