Skip navigation

Skip to main content

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

requestDataTable

API reference for the requestDataTable 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.

Retrieves a DataTable from a Data Connector.

The data can be selected through the data selection modal (dataSelectionDisplay: 'show') or fetched directly for a given data source reference (dataSelectionDisplay: 'hide').

Usage

Open the data connector selection modal to request data

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


const dataTable = await requestDataTable({
  withDataConnector: 'self',
  dataSelectionDisplay: 'show',
});
TS

Request data from the data connector without a preview

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


const dataTable = await requestDataTable({
  withDataConnector: 'self',
  dataSelectionDisplay: 'hide',
  dataSourceRef: { source: 'serialized_content' },
});
TS

Parameters

optsRequestDataTableOptions
Required

The configuration options for retrieving the data.

withDataConnectorstring
Required

The Data Connector to retrieve the data from. Only the app's own Data Connector ('self') is supported.

The only valid value is "self".

limitDataTableLimit
Optional

An optional limit for the retrieved data table. If not provided, a default limit of { row: 100, column: 20 } is applied.

rownumber
Required

The maximum number of rows allowed.

Your app should ensure data does not exceed this limit.

columnnumber
Required

The maximum number of columns allowed.

Your app should ensure data does not exceed this limit.

dataSelectionDisplaystring
Required

Displays the data preview modal so the user can select and preview the data before importing.

The only valid value is "show".

dataSelectionDisplaystring
Required

Skips the data preview modal and fetches the referenced data directly.

The only valid value is "hide".

dataSourceRefDataSourceRef
Required

The data source reference passed to the Data Connector intent to fetch the data.

sourcestring
Required

Information needed to identify and retrieve data from your source.

This string should contain all the information your app needs to fetch the exact data selection later. Typically, this is a serialized object with query parameters, identifiers, or filters.

You are responsible for encoding and decoding this value appropriately.

Maximum size: 5KB

titlestring
Optional

A human-readable description of the data reference.

This title may be displayed to users in the Canva interface to help them identify the data source.

Maximum length: 255 characters

Returns

Structured tabular data for import into Canva. Mirrors the public DataTable but with the Beta DataTableRow (whose media cells may contain references to already-imported media). This is a Promise that resolves with the following object:

rowsDataTableRow[]

The data rows containing the actual values.

cellsDataTableCell<DataType>[]

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

Indicates this cell contains a date value.

The only valid value is "date".

valuenumber | undefined

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

Indicates this cell contains a string value.

The only valid value is "string".

valuestring | undefined

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

Indicates this cell contains a number value.

The only valid value is "number".

valuenumber | undefined

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

Indicates this cell contains a boolean value.

The only valid value is "boolean".

valueboolean | undefined

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

Indicates this cell contains a media collection.

The only valid value is "media".

valueobject[]

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

Indicates this value contains options for image uploading.

The only valid value is "image_upload".

urlstring

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

The MIME type of the image file.

Available values:

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

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

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

Indicates this value contains options for video uploading.

The only valid value is "video_upload".

urlstring

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

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

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

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

Indicates this value references an already-imported image.

The only valid value is "image_reference".

refstring

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

Indicates this value references an already-imported video.

The only valid value is "video_reference".

refstring

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

Name for the column, displayed as header text.

If undefined, the column will have no header text.

typeobject

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