Skip navigation

Skip to main content

API reference
Intents
Intents: Asset
Intents: Content
Intents: design
API reference

autofillDesign

API reference for the autofillDesign method.

This API is a preview. Preview APIs are unstable and may change without warning. You can't release public apps using this API until it's stable.

Fills the tagged elements of the current design using the provided data table.

Resolves with { status: 'success' } when the design is filled, or { status: 'no_matched_fields' } when the design has no fields tagged for Autofill. Unexpected failures — including the user not having access to Autofill — reject the promise with a CanvaError.

Usage: Autofill the current design with a data table

import { autofillDesign } from "@canva/design";
import { requestDataTable } from "@canva/intents/data";


const dataTable = await requestDataTable({ dataSelectionDisplay: 'show' });


const response = await autofillDesign({ dataTable });
if (response.status === 'no_matched_fields') {
  console.warn('The current design has no fields tagged for Autofill.');
}
TYPESCRIPT

Parameters

optsAutofillOptions
Required

The configuration options for this Autofill call.

dataTableDataTable
Required

The data used to fill in the tagged elements of the current design. This is the same DataTable type returned by a Data Connector (requestDataTable).

rowsDataTableRow[]
Required

The data rows containing the actual values.

cellsDataTableCell<DataType>[]
Required

Array of cells containing the data values.

Cell containing a date value.

Example: Creating a date cell

import type { DateDataTableCell } from '@canva/intents/data';


const todayCell: DateDataTableCell = {
  type: 'date',
  value: Math.floor(Date.now() / 1000) // Unix timestamp in seconds
};


const emptyDateCell: DateDataTableCell = {
  type: 'date',
  value: undefined
};
TS
typestring
Required

Indicates this cell contains a date value.

The only valid value is "date".

valuenumber | undefined
Required

Unix timestamp in seconds representing the date.

Use undefined for an empty cell.

Cell containing a text value.

Example: Creating a string cell

import type { StringDataTableCell } from '@canva/intents/data';


const nameCell: StringDataTableCell = {
  type: 'string',
  value: 'John Doe'
};


const emptyStringCell: StringDataTableCell = {
  type: 'string',
  value: undefined
};
TS
typestring
Required

Indicates this cell contains a string value.

The only valid value is "string".

valuestring | undefined
Required

Text content of the cell.

Maximum length: 10,000 characters

Use undefined for an empty cell.

Cell containing a numeric value.

Example: Creating a number cell

import type { NumberCellMetadata, NumberDataTableCell } from '@canva/intents/data';


const priceCell: NumberDataTableCell = {
  type: 'number',
  value: 29.99,
  metadata: { formatting: '[$$]#,##0.00' }
};


const quantityCell: NumberDataTableCell = {
  type: 'number',
  value: 150
};


const emptyNumberCell: NumberDataTableCell = {
  type: 'number',
  value: undefined
};
TS
typestring
Required

Indicates this cell contains a number value.

The only valid value is "number".

valuenumber | undefined
Required

Numeric value within safe integer range.

Valid range: Number.MIN_SAFE_INTEGER to Number.MAX_SAFE_INTEGER

Invalid values:

  • Infinity or -Infinity
  • NaN
  • Negative zero (-0)
  • Denormalized numbers

Use undefined for an empty cell.

metadataNumberCellMetadata
Optional

Optional formatting information for displaying the number.

Example: Applying display formatting to a number

import type { NumberCellMetadata } from '@canva/intents/data';


const currencyFormatting: NumberCellMetadata = { formatting: '[$USD]#,##0.00' };
const percentageFormatting: NumberCellMetadata = { formatting: '0.00%' };
TS
formattingstring
Optional

Formatting pattern using Office Open XML Format.

These patterns control how numbers are displayed to users, including currency symbols, decimal places, and separators.

Cell containing a boolean value.

Examples

Creating a boolean cell

import type { BooleanDataTableCell } from '@canva/intents/data';


const isActiveCell: BooleanDataTableCell = {
  type: 'boolean',
  value: true
};
TS

Creating a boolean cell with false value

import type { BooleanDataTableCell } from '@canva/intents/data';


const isCompleteCell: BooleanDataTableCell = {
  type: 'boolean',
  value: false
};
TS

Creating an empty boolean cell

import type { BooleanDataTableCell } from '@canva/intents/data';


const emptyBooleanCell: BooleanDataTableCell = {
  type: 'boolean',
  value: undefined
};
TS
typestring
Required

Indicates this cell contains a boolean value.

The only valid value is "boolean".

valueboolean | undefined
Required

Boolean value (true or false).

Use undefined for an empty cell.

Cell containing a media collection. In the Preview (Beta) API this additionally accepts references to already-imported Canva media (image_reference / video_reference).

Examples

Creating a media cell with an image

import type { MediaCollectionDataTableCell } from '@canva/intents/data';


const mediaCell: MediaCollectionDataTableCell = {
  type: 'media',
  value: [{
    type: 'image_upload',
    url: 'https://www.canva.dev/example-assets/image-import/image.jpg',
    mimeType: 'image/jpeg',
    thumbnailUrl: 'https://www.canva.dev/example-assets/image-import/thumbnail.jpg',
    aiDisclosure: 'none'
  }]
};
TS

Creating an empty media cell

import type { MediaCollectionDataTableCell } from '@canva/intents/data';


const emptyMediaCell: MediaCollectionDataTableCell = {
  type: 'media',
  value: []
};
TS
typestring
Required

Indicates this cell contains a media collection.

The only valid value is "media".

valueobject[]
Required

Media collection values. Use an empty array for an empty cell.

Options for uploading an image asset to the user's private media library.

typestring
Required

Indicates this value contains options for image uploading.

The only valid value is "image_upload".

urlstring
Required

The URL of the image file to upload. This can be an external URL or a data URL.

Requirements for external URLs:

  • Must use HTTPS
  • Must return a 200 status code
  • Content-Type must match the file's MIME type
  • Must be publicly accessible (i.e. not a localhost URL)
  • Must not redirect
  • Must not contain an IP address
  • Maximum length: 4096 characters
  • Must not contain whitespace
  • Must not contain these characters: >, <, {, }, ^, backticks
  • Maximum file size: 50MB

Requirements for data URLs:

  • Must include ;base64 for base64-encoded data
  • Maximum size: 10MB (10 × 1024 × 1024 characters)

Requirements for SVGs:

  • Disallowed elements:
    • a
    • altglyph
    • altglyphdef
    • altglyphitem
    • animate
    • animatemotion
    • animatetransform
    • cursor
    • discard
    • font
    • font-face
    • font-face-format
    • font-face-name
    • font-face-src
    • font-face-uri
    • foreignobject
    • glyph
    • glyphref
    • missing-glyph
    • mpath
    • script
    • set
    • switch
    • tref
  • Disallowed attributes:
    • crossorigin
    • lang
    • media
    • onload
    • ping
    • referrerpolicy
    • rel
    • rendering-intent
    • requiredextensions
    • requiredfeatures
    • systemlanguage
    • tabindex
    • transform-origin
    • unicode
    • vector-effect
  • The href attribute of an image element only supports data URLs for PNG and JPEG images.
  • The URL in the href attribute must not point to a location outside of the SVG.
  • The style attribute must not use the mix-blend-mode property.
mimeTypeImageMimeType
Required

The MIME type of the image file.

Available values:

  • "image/jpeg"
  • "image/heic"
  • "image/png"
  • "image/svg+xml"
  • "image/webp"
  • "image/tiff"
thumbnailUrlstring
Required

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.

Requirements for external URLs:

Requirements for data URLs:

  • Must include ;base64 for base64-encoded data
  • Maximum size: 10MB (10 × 1024 × 1024 characters)
aiDisclosureAiDisclosure
Required

A disclosure identifying if the app generated this image using AI

Helps users make informed decisions about the content they interact with. See AiDisclosure for the full definition.

App Generated

'app_generated' indicates when the app creates or significantly alters an asset using AI. Includes when the app requests a third-party service to take similar action on an image using AI.

Required for the following cases (this list is not exhaustive):

Case
Reason
AI generates a new image from scratch
Creates new creative content
AI changes the style of the image e.g. makes it cartoon
Significantly alters the style
AI removes an object and replaces it with new content
Creates new creative content
AI changes the facial expression of a person in an image
Can alter content's original meaning
AI composites multiple images together
Significantly alters context
AI expands an image by generating new content to fill the edges
Creates new creative content
AI replaces background by generating new content
Creates new creative content

None

'none' indicates when the app doesn't create or significantly alter an asset using AI, or as a part of a request to third-party hosted content.

Required for the following cases (this list is not exhaustive):

Case
Reason
Asset comes from an asset library
Didn't generate the asset itself
AI corrects red eyes
A minor correction
AI removes background without replacement
Doesn't change original meaning by itself
AI changes the color of an object in an image
Doesn't change original meaning by itself
AI detects image defects and suggests manual fixes
Didn't change the asset itself
AI adjusts brightness and contrast on an image
Doesn't change original meaning by itself
AI upscales an image
Doesn't change original meaning by itself

Available values:

  • "app_generated"
  • "none"
namestring
Optional

A human-readable name for the image asset.

This name is displayed in the user's media library and helps users identify and find the asset later. If not provided, Canva will generate a name based on the asset's URL or a unique identifier.

Requirements:

  • Minimum length: 1 character (empty strings are not allowed)
  • Maximum length: 255 characters

Options for uploading a video asset to the user's private media library.

typestring
Required

Indicates this value contains options for video uploading.

The only valid value is "video_upload".

urlstring
Required

The URL of the video file to upload.

Requirements:

  • Must use HTTPS
  • Must return a 200 status code
  • Content-Type must match the file's MIME type
  • Must be publicly accessible (i.e. not a localhost URL)
  • Must not redirect
  • Must not contain an IP address
  • Maximum length: 4096 characters
  • Must not contain whitespace
  • Must not contain these characters: >, <, {, }, ^, backticks
  • Maximum file size: 1000MB (1GB)
mimeTypeVideoMimeType
Required

The MIME type of the video file.

Available values:

  • "video/avi"
  • "video/x-msvideo"
  • "image/gif"
  • "video/x-m4v"
  • "video/x-matroska"
  • "video/quicktime"
  • "video/mp4"
  • "video/mpeg"
  • "video/webm"
  • "application/json"
thumbnailImageUrlstring
Required

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.

Requirements for external URLs:

Requirements for data URLs:

  • Must include ;base64 for base64-encoded data
  • Maximum size: 10MB (10 × 1024 × 1024 characters)
  • The dimensions of the thumbnail must match the video's aspect ratio to prevent the thumbnail from appearing squashed or stretched
aiDisclosureAiDisclosure
Required

A disclosure identifying if the app generated this video using AI.

Helps users make informed decisions about the content they interact with. See AiDisclosure for the full definition.

App Generated

'app_generated' indicates when the app creates or significantly alters an asset using AI. Includes when the app requests a third-party service to take similar action on a video using AI.

Required for the following cases (this list is not exhaustive):

Case
Reason
AI generates a new video from scratch
Creates new creative content
AI changes the style of the video e.g. makes it cartoon
Significantly alters the style
AI adds subtitles that rely on subjective interpretation
Creates new creative content
AI expands a video by generating new content to fill the edges
Creates new creative content
AI animates an image
Creates new creative content
AI fixes defects e.g. blur in a video by generating details
Creates new creative content
AI generates a talking head presenter
Creates new creative content

None

'none' indicates when the app doesn't create or significantly alter an asset using AI, or as a part of a request to third-party hosted content.

Required for the following cases (this list is not exhaustive):

Case
Reason
Asset comes from an asset library
Didn't generate the asset itself
AI corrects red eyes
A minor correction
AI adjusts brightness and contrast on a video
Doesn't change original meaning by itself
AI creates a slow motion effect in a video
Doesn't change original meaning by itself
AI adds AI word-by-word transcribed subtitles to a video
Doesn't change original meaning by itself

Available values:

  • "app_generated"
  • "none"
namestring
Optional

A human-readable name for the video asset.

This name is displayed in the user's media library and helps users identify and find the asset later. If not provided, Canva will generate a name based on the asset's URL or a unique identifier.

Requirements:

  • Minimum length: 1 character (empty strings are not allowed)
  • Maximum length: 255 characters
thumbnailVideoUrlstring
Optional

The URL of a thumbnail video to display while the video is queued for upload.

Requirements:

  • Must use HTTPS
  • Must support Cross-Origin Resource Sharing
  • Maximum length: 4096 characters
  • The dimensions of the thumbnail video must match the video's aspect ratio to prevent the thumbnail from appearing squashed or stretched
  • Must not be an AVI file. Although our APIs support uploading AVI videos, Canva can't preview them because of native support of browsers

A reference to an image already imported into the user's Canva media library. requestDataTable returns Data Connector media as references; pass them through unchanged to requestAutofillDesign or requestDataFieldMatching.

typestring
Required

Indicates this value references an already-imported image.

The only valid value is "image_reference".

refstring
Required

Opaque Canva media reference. Treat as a handle — do not construct or parse it.

A reference to a video already imported into the user's Canva media library. See DataTableImageReference.

typestring
Required

Indicates this value references an already-imported video.

The only valid value is "video_reference".

refstring
Required

Opaque Canva media reference. Treat as a handle — do not construct or parse it.

columnConfigsColumnConfig[]
Optional

Column definitions with names and data types.

namestring | undefined
Required

Name for the column, displayed as header text.

If undefined, the column will have no header text.

typeobject
Required

Expected data type for cells in this column.

Use a specific DataType for columns with consistent types, or 'variant' for columns that may contain mixed types.

Data types supported for table cells.

Available values:

  • "string"
  • "number"
  • "date"
  • "boolean"
  • "media"

The only valid value is "variant".

Returns

Response object from the Autofill operation.

Unexpected failures — including the current user not having access to Autofill — reject the promise with a CanvaError. This is a Promise that resolves with the following object:

statusAutofillStatus

The outcome of an Autofill operation.

  • success: the design was filled with the provided data.
  • no_matched_fields: the current design has no fields tagged for Autofill, so nothing was filled.

Available values:

  • "success"
  • "no_matched_fields"