Skip navigation

Skip to main content

On September 25th, 2024, we released v2 of the Apps SDK. To learn what’s new and how to upgrade, see Upgrade FAQ and Upgrade guide.
API reference
Intents: design
API reference

prepareDataConnector

API reference for the intents prepareDataConnector method.

Prepares a DataConnector Intent.

Usage

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


prepareDataConnector({
 getDataTable: async (params) => {
   // Implement the logic to fetch the data table
 },
 renderSelectionUi: (params) => {
   // Implement the UI for the data table selection
 },
});
TSX

Parameters

implementationDataConnectorIntent
Required

Main interface for implementing the Data Connector intent.

Implementing the Data Connector intent enables apps to import external data into Canva. This allows users to select, preview, and refresh data from external sources.

getDataTablefunction
Required

Gets structured data from an external source.

This action is called in two scenarios:

  • During data selection to preview data before import (when RenderSelectionUiRequest.updateDataRef is called).
  • When refreshing previously imported data (when the user requests an update).

Example: Getting data from an external source

import type { GetDataTableRequest, GetDataTableResponse } from '@canva/intents/data';


async function getDataTable(request: GetDataTableRequest): Promise<GetDataTableResponse> {
  const { dataSourceRef, limit, signal } = request;


  // Check if the operation has been aborted.
  if (signal.aborted) {
    return { status: 'app_error', message: 'The data fetch operation was cancelled.' };
  }


  // ... data fetching logic using dataSourceRef, limit, and signal ...


  // Placeholder for a successful result.
  return {
    status: 'completed',
    dataTable: { rows: [{ cells: [{ type: 'string', value: 'Fetched data' }] }] }
  };
}
TS

Parameters

requestGetDataTableRequest
Required

Parameters for the data fetching operation.

dataSourceRefDataSourceRef
Required

Reference to the data source to fetch.

This contains the information needed to identify and retrieve the specific data that was previously selected by the user.

Use this to query your external data service.

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

limitDataTableLimit
Required

Maximum row and column limits for the imported data.

Your app must ensure the returned data does not exceed these limits.

If the requested data would exceed these limits, either:

  • Truncate the data to fit within limits, or
  • Return a 'data_table_limit_exceeded' error
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.

signalAbortSignal
Required

Standard DOM AbortSignal for cancellation support.

Your app should monitor this signal and abort any ongoing operations if it becomes aborted.

Returns

A promise resolving to either a successful result with data or an error. This is a Promise that resolves with the following object:

Successful result from getDataTable action.

statusstring

Indicates the operation completed successfully

This must be "completed".

dataTableDataTable

The fetched data formatted as a data table.

rowsDataTableRow[]

The data rows containing the actual values.

Each row contains an array of cells with typed data values.

cellsDataTableCell<DataType>[]

Array of cells containing the data values.

Each cell must have a type that matches the corresponding column definition (if provided).

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.

This must be "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.

This must be "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.

This must be "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.

This must be "boolean".

valueboolean | undefined

Boolean value (true or false).

Use undefined for an empty cell.

Cell containing a media collection (images) value.

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.

This must be "media".

valueobject[]

Media collection values.

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

This must be "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"

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

typestring

Indicates this value contains options for video uploading.

This must be "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: 100MB
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"
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
columnConfigsColumnConfig[]
Optional

Column definitions with names and data types.

These help Canva interpret and display your data correctly.

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"

This must be "variant".

metadataDataTableMetadata
Optional

Optional metadata providing additional context about the data.

descriptionstring
Optional

A human-readable description of the dataset.

This description helps users understand what data they are importing.

providerInfoobject
Optional

Information about the data provider or source.

namestring

Name of the data provider.

urlstring
Optional

URL to the provider's website or related resource.

Error results that can be returned from getDataTable method.

GetDataTableError indicating the data source reference is no longer valid. This will trigger a re-selection flow for the user.

statusstring

The data source reference is no longer valid.

Return this error when the DataSourceRef cannot be used to retrieve data, for example:

  • The referenced dataset has been deleted
  • Access permissions have changed
  • The structure of the data has fundamentally changed

This will trigger a re-selection flow, allowing the user to choose a new data source.

This must be "outdated_source_ref".

GetDataTableError indicating failure to fetch data from the external source. Typically due to network issues or API failures.

statusstring

Failed to fetch data from the external source.

Return this error for network issues, API failures, or other connectivity problems that prevent data retrieval.

This must be "remote_request_failed".

GetDataTableError indicating custom error occurred in the app's implementation. This can be used to indicate specific issues that are not covered by other error types.

statusstring

A custom error occurred in your app.

Return this for application-specific errors that don't fit the other categories. Include a descriptive message explaining the error to the user.

This must be "app_error".

messagestring
Optional

Optional message explaining the error.

renderSelectionUifunction
Required

Renders a user interface for selecting and configuring data from your external sources.

Example: Rendering a data selection UI

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


async function renderSelectionUi(request: RenderSelectionUiRequest): Promise<void> {
  // UI rendering logic.
  // Example: if user selects data 'ref123'.
  const selectedRef = { source: 'ref123', title: 'My Selected Table' };
  try {
    const result = await request.updateDataRef(selectedRef);
    if (result.status === 'completed') {
      console.log('Selection valid and preview updated.');
    } else {
      console.error('Selection error:', result.status);
    }
  } catch (error) {
     console.error('An unexpected error occurred during data ref update:', error);
  }
}
TS

Parameters

requestRenderSelectionUiRequest
Required

Configuration and callbacks for the data selection UI.

invocationContextInvocationContext
Required

Context information about why the data selection UI is being launched.

Use this to adapt your UI for different scenarios:

  • 'data_selection': Initial data selection or editing existing data
  • 'outdated_source_ref': Previous reference is no longer valid, guide user to reselect
  • 'app_error': Custom error occurred, show error message and recovery options

When dataSourceRef is provided, pre-populate your UI with this selection.

InvocationContext indicating initial data selection flow or edit of existing data.

reasonstring
Required

Initial data selection or editing existing data.

This is the standard flow when:

  • A user is selecting data for the first time
  • A user is editing a previous selection

If dataSourceRef is provided, this indicates an edit flow, and you should pre-populate your UI with this selection.

This must be "data_selection".

dataSourceRefDataSourceRef
Optional

If dataSourceRef is provided, this is an edit of existing data flow and UI should be pre-populated.

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

InvocationContext indicating an error occurred because the previously selected data source reference is no longer valid. Triggered when getDataTable returned 'outdated_source_ref' during data refresh. UI should guide the user to reselect or reconfigure their data.

reasonstring
Required

Previously selected data source reference is no longer valid.

This occurs when getDataTable returned 'outdated_source_ref' during a refresh attempt. Your UI should guide the user to select a new data source or update their selection.

The outdated reference is provided to help you suggest an appropriate replacement.

This must be "outdated_source_ref".

dataSourceRefDataSourceRef
Optional

The outdated data source reference that caused the error during refresh.

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

InvocationContext indicating a custom error occurred during data refresh. Triggered when getDataTable returned 'app_error' status. UI should display the error message and help users recover.

reasonstring
Required

A custom error occurred during data refresh.

This occurs when getDataTable returned 'app_error' during a refresh attempt. Your UI should display the error message and help users recover from the specific issue.

This must be "app_error".

dataSourceRefDataSourceRef
Optional

The data source reference that caused the error during refresh.

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

messagestring
Optional

The error message to display to the user.

limitDataTableLimit
Required

Maximum allowed rows and columns for the imported data.

Your UI should inform users of these constraints and prevent or warn about selections that would exceed them. This helps users understand why certain data sets might not be available for selection.

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.

updateDataReffunction
Required

Callback to preview selected data before finalizing import.

Call this function when the user selects data to:

  1. Show a preview of the selected data to the user
  2. Validate that the selection meets system requirements

Calling this function will trigger your getDataTable implementation. Wait for the promise to resolve to determine if the selection is valid.

Throws

Will throw CanvaError('bad_request') if

  1. DataSourceRef.source exceeds 5kb.
  2. DataSourceRef.title exceeds 255 characters.
  3. GetDataTableCompleted.dataTable exceeds DataTableLimit or contains invalid data.

Parameters

dataSourceRefDataSourceRef
Required

Reference object identifying the selected 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

Promise resolving to success or an error result. This is a Promise that resolves with the following object:

Successful result from the RenderSelectionUiRequest.updateDataRef callback.

statusstring

The data selection was successful and can be previewed.

This must be "completed".

Error results that can be returned from getDataTable method.

GetDataTableError indicating the data source reference is no longer valid. This will trigger a re-selection flow for the user.

statusstring

The data source reference is no longer valid.

Return this error when the DataSourceRef cannot be used to retrieve data, for example:

  • The referenced dataset has been deleted
  • Access permissions have changed
  • The structure of the data has fundamentally changed

This will trigger a re-selection flow, allowing the user to choose a new data source.

This must be "outdated_source_ref".

GetDataTableError indicating failure to fetch data from the external source. Typically due to network issues or API failures.

statusstring

Failed to fetch data from the external source.

Return this error for network issues, API failures, or other connectivity problems that prevent data retrieval.

This must be "remote_request_failed".

GetDataTableError indicating custom error occurred in the app's implementation. This can be used to indicate specific issues that are not covered by other error types.

statusstring

A custom error occurred in your app.

Return this for application-specific errors that don't fit the other categories. Include a descriptive message explaining the error to the user.

This must be "app_error".

messagestring
Optional

Optional message explaining the error.

Returns

void

Returns

void