Skip navigation

Skip to main content

API reference
Intents: Content
Intents: design
API reference

prepareContentPublisher

API reference for the prepareContentPublisher method.
This version of the 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.

Prepares a Content Publisher Intent.

Usage

import { prepareContentPublisher } from "@canva/intents/content";


prepareContentPublisher({
 getPublishConfiguration: async (params) => {
   // Implement the logic to get the publish configuration
 },
 renderSettingsUi: (params) => {
   // Implement the UI for settings view
 },
 renderPreviewUi: (params) => {
   // Implement the UI for preview view
 },
 publishContent: async (params) => {
   // Implement the logic to publish the content
 },
});
TSX

Parameters

implementationContentPublisherIntent
Required

Main interface for implementing the ContentPublisher intent.

Implementing the ContentPublisher intent enables apps to publish contents to external platforms. This allows users to configure publish settings, preview their designs, and share with others.

The publishing flow follows this process:

  1. User initiates publish action
  2. Your app provides publish configuration via getPublishConfiguration
  3. User selects an output type
  4. Your app renders settings UI via renderSettingsUi
  5. Your app renders preview UI via renderPreviewUi
  6. User reviews settings and preview
  7. Your app publishes the content via publishContent
getPublishConfigurationfunction
Required

Provides the configuration for the publishing platform.

This action is called when the user initiates the publish flow and needs to select an output type for the target platform.

Use this to define different publishing configurations for your platform, such as social media posts, videos, or other output types.

Example: Defining publish configuration for a social media platform

import type { GetPublishConfigurationResponse } from '@canva/intents/content';


async function getPublishConfiguration(): Promise<GetPublishConfigurationResponse> {
  return {
    status: 'completed',
    outputTypes: [
      {
        id: 'instagram_post',
        displayName: 'Instagram Post',
        mediaSlots: [
          {
            id: 'main_image',
            displayName: 'Post Image',
            fileCount: { min: 1, max: 10 },
            accepts: {
              image: { format: 'jpg', aspectRatio: { min: 0.8, max: 1.91 } }
            }
          }
        ]
      }
    ]
  };
}
TS

Returns

A promise resolving to the publish configuration or an error. This is a Promise that resolves with the following object:

Successful response from getting publish configuration.

statusstring

The only valid value is "completed".

outputTypesOutputType[]

Array of available output types for your platform.

Define different output types for various content formats that your platform supports (e.g., posts, stories, videos).

idstring

Unique identifier for this output type.

Use descriptive IDs like "instagram_post" or "youtube_video".

displayNamestring

User-facing name for this output type.

This is displayed to users when selecting where to publish. Examples: "Instagram Post", "YouTube Video", "Twitter Post".

mediaSlotsMediaSlot[]

Array of media slots defining what content is needed.

Each slot represents a piece of media required for publishing, such as a main image, thumbnail, or video.

idstring

Unique identifier for this media slot within the output type.

displayNamestring

User-facing name for this media slot.

Examples: "Post Image", "Video Thumbnail", "Main Video".

acceptsobject

File type requirements for this slot.

Note the following behavior:

  • Provide at least one of image or video
  • If both are provided, files for this slot may be either images or videos; each file must satisfy the corresponding requirement for its media type
  • To restrict the slot to a single media type, provide only that requirement
  • fileCount applies across all files accepted by the slot regardless of media type
imageImageRequirement
Optional

Image file requirements for a media slot.

Specifies format, aspect ratio, and size constraints for images.

Example: Image requirements for social media post

const imageReq: ImageRequirement = {
  format: 'jpg',
  aspectRatio: { min: 0.8, max: 1.91 },
  maxFileSizeMb: 8
};
TS
formatstring

Supported image format.

Available values:

  • "png"
  • "jpg"
maxFileSizeMbnumber
Optional

Maximum file size in megabytes.

Example: 10 for 10 MB maximum

aspectRatioValueRange
Optional

Aspect ratio constraint (width / height).

Examples:

  • { exact: 16/9 }: Widescreen (16:9)
  • { min: 0.8, max: 1.91 }: Instagram range

Exact value range constraint.

Example: Exact value range

const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
TS
exactnumber

Minimum value range constraint.

Example: Minimum value range

const minValue: ValueRange = { min: 3 }; // At least 3
TS
minnumber

Maximum value range constraint.

Example: Maximum value range

const maxValue: ValueRange = { max: 10 }; // At most 10
TS
maxnumber

Minimum and maximum value range constraint. Ranges are inclusive (min ≤ value ≤ max).

Example: Minimum and maximum value range

const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
TS
minnumber
maxnumber
videoVideoRequirement
Optional

Video file requirements for a media slot.

Specifies format, aspect ratio, duration, and size constraints for videos.

Example: Video requirements for YouTube

const videoReq: VideoRequirement = {
  format: 'mp4',
  aspectRatio: { exact: 16/9 },
  durationMs: { min: 1000, max: 600000 },
  maxFileSizeMb: 100
};
TS
formatstring

Supported video format.

The only valid value is "mp4".

maxFileSizeMbnumber
Optional

Maximum file size in megabytes.

Example: 10 for 10 MB maximum

aspectRatioValueRange
Optional

Aspect ratio constraint (width / height).

Examples:

  • { exact: 16/9 }: Widescreen
  • { exact: 9/16 }: Vertical/Story format

Exact value range constraint.

Example: Exact value range

const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
TS
exactnumber

Minimum value range constraint.

Example: Minimum value range

const minValue: ValueRange = { min: 3 }; // At least 3
TS
minnumber

Maximum value range constraint.

Example: Maximum value range

const maxValue: ValueRange = { max: 10 }; // At most 10
TS
maxnumber

Minimum and maximum value range constraint. Ranges are inclusive (min ≤ value ≤ max).

Example: Minimum and maximum value range

const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
TS
minnumber
maxnumber
durationMsValueRange
Optional

Duration constraint in milliseconds.

Examples:

  • { max: 60000 }: Maximum 60 seconds
  • { min: 3000, max: 600000 }: Between 3 seconds and 10 minutes

Exact value range constraint.

Example: Exact value range

const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
TS
exactnumber

Minimum value range constraint.

Example: Minimum value range

const minValue: ValueRange = { min: 3 }; // At least 3
TS
minnumber

Maximum value range constraint.

Example: Maximum value range

const maxValue: ValueRange = { max: 10 }; // At most 10
TS
maxnumber

Minimum and maximum value range constraint. Ranges are inclusive (min ≤ value ≤ max).

Example: Minimum and maximum value range

const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
TS
minnumber
maxnumber
durationValueRange
Deprecated

use durationMs instead.

Exact value range constraint.

Example: Exact value range

const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
TS
exactnumber

Minimum value range constraint.

Example: Minimum value range

const minValue: ValueRange = { min: 3 }; // At least 3
TS
minnumber

Maximum value range constraint.

Example: Maximum value range

const maxValue: ValueRange = { max: 10 }; // At most 10
TS
maxnumber

Minimum and maximum value range constraint. Ranges are inclusive (min ≤ value ≤ max).

Example: Minimum and maximum value range

const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
TS
minnumber
maxnumber
fileCountValueRange
Optional

Number of files accepted in this slot.

Use this to specify single or multiple file requirements. Examples:

  • { exact: 1 }: Exactly one file
  • { min: 1, max: 10 }: Between 1 and 10 files
  • undefined: Any number of files

Exact value range constraint.

Example: Exact value range

const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
TS
exactnumber

Minimum value range constraint.

Example: Minimum value range

const minValue: ValueRange = { min: 3 }; // At least 3
TS
minnumber

Maximum value range constraint.

Example: Maximum value range

const maxValue: ValueRange = { max: 10 }; // At most 10
TS
maxnumber

Minimum and maximum value range constraint. Ranges are inclusive (min ≤ value ≤ max).

Example: Minimum and maximum value range

const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
TS
minnumber
maxnumber

GetPublishConfigurationError error indicating a custom error occurred.

statusstring

The only valid value is "app_error".

messagestring
Optional

User-friendly message explaining the error.

renderSettingsUifunction
Required

Renders a user interface for configuring publish settings.

This action is called after the user selects an output type. Your UI should allow users to configure platform-specific settings such as captions, tags, privacy settings, or publishing destinations.

Use the updatePublishSettings callback to save user settings and validate them. Settings are stored in the publishRef string (maximum 5KB).

Example: Rendering a settings UI with publish configuration

import { createRoot } from 'react-dom/client';
import type { RenderSettingsUiRequest } from '@canva/intents/content';


function renderSettingsUi(request: RenderSettingsUiRequest): void {
  const SettingsUiApp = () => (
     <AppUiProvider>
      <SettingsUi request={request} />
    </AppUiProvider>
  );


  createRoot().render(<SettingsUiApp />)
}
TS

Parameters

requestRenderSettingsUiRequest
Required

Configuration and callbacks for the publish settings UI.

updatePublishSettingsfunction
Required

Callback to save and validate the user's publish settings.

Call this function whenever the user modifies their settings to:

  • Save the settings for later use in publishContent
  • Validate that required fields are filled
  • Enable or disable the publish button based on validity

Store all necessary publishing information in the publishRef string. This will be provided to your publishContent method when the user publishes.

Throws

Will throw CanvaError('bad_request') if PublishSettings.publishRef exceeds 5KB.

Example: Updating settings as user types

// As user fills in form fields, update settings
function handleCaptionChange(caption: string) {
  const settings = { caption, tags: currentTags };
  const publishRef = JSON.stringify(settings);


  updatePublishSettings({
    publishRef,
    validityState: caption ? 'valid' : 'invalid_missing_required_fields'
  });
}
TS

Parameters

publishSettingsPublishSettings
Required

Configuration for publish settings.

Contains the user's settings and their validation state. Use this to control whether the publish button is enabled.

validityStatePublishRefValidityState
Required

Validation state of the publish settings.

Controls whether the publish button is enabled:

  • "valid": Settings are complete and valid, publish button is enabled
  • "invalid_missing_required_fields": Required settings are missing, publish button is disabled
  • "invalid_authentication_required": User must authenticate before publishing can proceed

Available values:

  • "valid"
  • "invalid_missing_required_fields"
  • "invalid_authentication_required"
publishRefstring
Optional

Serialized platform-specific settings for publishing.

Store all information your app needs to publish the content in this string. This might include:

  • Captions or descriptions
  • Tags or hashtags
  • Privacy settings
  • Publishing destination (account, page, etc.)
  • Scheduling information

This reference will be provided to your publishContent method when publishing.

Maximum size: 5KB

Example: Serializing settings

const settings = {
  caption: 'Check out my design!',
  tags: ['design', 'creative'],
  privacy: 'public'
};
const publishRef = JSON.stringify(settings);
TS

Returns

A promise that resolves when the settings are successfully saved. This is a Promise that resolves with the following object:

statusstring

The only valid value is "completed".

registerOnSettingsUiContextChangefunction
Required

Registers a callback to be invoked when the settings UI context changes.

This callback is triggered when the user changes the output type in the publish flow. Use this to update your settings UI to match the requirements of the new output type.

Example: Adapting UI for different output types

registerOnSettingsUiContextChange((context) => {
  if (context.outputType.id === 'instagram_post') {
    // Show Instagram-specific settings
    showHashtagField();
  } else if (context.outputType.id === 'instagram_story') {
    // Show instagram_story settings
    showCaptionField();
  }
});
TS

Parameters

callbackfunction
Required

The callback invoked when settings context is updated.

Parameters

contextSettingsUiContext
Required

Context information for the publish settings UI.

Provides information about the current state of the settings UI to help you adapt the interface based on the selected output type.

outputTypeOutputType
Required

The currently selected output type.

Use this to customize your settings UI based on the requirements of different output types.

idstring
Required

Unique identifier for this output type.

Use descriptive IDs like "instagram_post" or "youtube_video".

displayNamestring
Required

User-facing name for this output type.

This is displayed to users when selecting where to publish. Examples: "Instagram Post", "YouTube Video", "Twitter Post".

mediaSlotsMediaSlot[]
Required

Array of media slots defining what content is needed.

Each slot represents a piece of media required for publishing, such as a main image, thumbnail, or video.

idstring
Required

Unique identifier for this media slot within the output type.

displayNamestring
Required

User-facing name for this media slot.

Examples: "Post Image", "Video Thumbnail", "Main Video".

acceptsobject
Required

File type requirements for this slot.

Note the following behavior:

  • Provide at least one of image or video
  • If both are provided, files for this slot may be either images or videos; each file must satisfy the corresponding requirement for its media type
  • To restrict the slot to a single media type, provide only that requirement
  • fileCount applies across all files accepted by the slot regardless of media type
imageImageRequirement
Optional

Image file requirements for a media slot.

Specifies format, aspect ratio, and size constraints for images.

Example: Image requirements for social media post

const imageReq: ImageRequirement = {
  format: 'jpg',
  aspectRatio: { min: 0.8, max: 1.91 },
  maxFileSizeMb: 8
};
TS
formatstring
Required

Supported image format.

Available values:

  • "png"
  • "jpg"
maxFileSizeMbnumber
Optional

Maximum file size in megabytes.

Example: 10 for 10 MB maximum

aspectRatioValueRange
Optional

Aspect ratio constraint (width / height).

Examples:

  • { exact: 16/9 }: Widescreen (16:9)
  • { min: 0.8, max: 1.91 }: Instagram range

Exact value range constraint.

Example: Exact value range

const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
TS
exactnumber
Required

Minimum value range constraint.

Example: Minimum value range

const minValue: ValueRange = { min: 3 }; // At least 3
TS
minnumber
Required

Maximum value range constraint.

Example: Maximum value range

const maxValue: ValueRange = { max: 10 }; // At most 10
TS
maxnumber
Required

Minimum and maximum value range constraint. Ranges are inclusive (min ≤ value ≤ max).

Example: Minimum and maximum value range

const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
TS
minnumber
Required
maxnumber
Required
videoVideoRequirement
Optional

Video file requirements for a media slot.

Specifies format, aspect ratio, duration, and size constraints for videos.

Example: Video requirements for YouTube

const videoReq: VideoRequirement = {
  format: 'mp4',
  aspectRatio: { exact: 16/9 },
  durationMs: { min: 1000, max: 600000 },
  maxFileSizeMb: 100
};
TS
formatstring
Required

Supported video format.

The only valid value is "mp4".

maxFileSizeMbnumber
Optional

Maximum file size in megabytes.

Example: 10 for 10 MB maximum

aspectRatioValueRange
Optional

Aspect ratio constraint (width / height).

Examples:

  • { exact: 16/9 }: Widescreen
  • { exact: 9/16 }: Vertical/Story format

Exact value range constraint.

Example: Exact value range

const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
TS
exactnumber
Required

Minimum value range constraint.

Example: Minimum value range

const minValue: ValueRange = { min: 3 }; // At least 3
TS
minnumber
Required

Maximum value range constraint.

Example: Maximum value range

const maxValue: ValueRange = { max: 10 }; // At most 10
TS
maxnumber
Required

Minimum and maximum value range constraint. Ranges are inclusive (min ≤ value ≤ max).

Example: Minimum and maximum value range

const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
TS
minnumber
Required
maxnumber
Required
durationMsValueRange
Optional

Duration constraint in milliseconds.

Examples:

  • { max: 60000 }: Maximum 60 seconds
  • { min: 3000, max: 600000 }: Between 3 seconds and 10 minutes

Exact value range constraint.

Example: Exact value range

const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
TS
exactnumber
Required

Minimum value range constraint.

Example: Minimum value range

const minValue: ValueRange = { min: 3 }; // At least 3
TS
minnumber
Required

Maximum value range constraint.

Example: Maximum value range

const maxValue: ValueRange = { max: 10 }; // At most 10
TS
maxnumber
Required

Minimum and maximum value range constraint. Ranges are inclusive (min ≤ value ≤ max).

Example: Minimum and maximum value range

const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
TS
minnumber
Required
maxnumber
Required
durationValueRange
Deprecated

use durationMs instead.

Exact value range constraint.

Example: Exact value range

const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
TS
exactnumber
Required

Minimum value range constraint.

Example: Minimum value range

const minValue: ValueRange = { min: 3 }; // At least 3
TS
minnumber
Required

Maximum value range constraint.

Example: Maximum value range

const maxValue: ValueRange = { max: 10 }; // At most 10
TS
maxnumber
Required

Minimum and maximum value range constraint. Ranges are inclusive (min ≤ value ≤ max).

Example: Minimum and maximum value range

const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
TS
minnumber
Required
maxnumber
Required
fileCountValueRange
Optional

Number of files accepted in this slot.

Use this to specify single or multiple file requirements. Examples:

  • { exact: 1 }: Exactly one file
  • { min: 1, max: 10 }: Between 1 and 10 files
  • undefined: Any number of files

Exact value range constraint.

Example: Exact value range

const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
TS
exactnumber
Required

Minimum value range constraint.

Example: Minimum value range

const minValue: ValueRange = { min: 3 }; // At least 3
TS
minnumber
Required

Maximum value range constraint.

Example: Maximum value range

const maxValue: ValueRange = { max: 10 }; // At most 10
TS
maxnumber
Required

Minimum and maximum value range constraint. Ranges are inclusive (min ≤ value ≤ max).

Example: Minimum and maximum value range

const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
TS
minnumber
Required
maxnumber
Required

Returns

void

Returns

A disposer function that cleans up the registered callback.

() => void

Returns

void

renderPreviewUifunction
Required

Renders a user interface for previewing the content.

This action is called after the settings UI is rendered. Your UI should display a preview of how the content will appear on the target platform.

Previews update dynamically as users modify their content or settings. For videos, start with lightweight thumbnails and use requestPreviewUpgrade to load full video previews on demand to optimize performance.

Example: Rendering a preview UI with video optimization

import { createRoot } from 'react-dom/client';
import type { RenderPreviewUiRequest } from '@canva/intents/content';


function renderPreviewUi(request: RenderPreviewUiRequest): void {
  const PreviewUiApp = () => (
     <AppUiProvider>
      <PreviewUi request={request} />
    </AppUiProvider>
  );


  createRoot().render(<PreviewUiApp />)
}
TS

Parameters

requestRenderPreviewUiRequest
Required

Configuration and callbacks for the preview UI.

requestPreviewUpgradefunction
Required

Callback to upgrade video thumbnail previews to full video media.

Call this function when you need full video previews instead of lightweight thumbnails. This helps optimize performance by deferring full video loading until needed.

Upgrades may complete asynchronously; listen to registerOnPreviewChange for updates to receive the upgraded video previews.

Example: Upgrading video previews on user interaction

// When user clicks on a video thumbnail, upgrade to full video
if (preview.kind === 'video' && preview.status === 'thumbnail') {
  requestPreviewUpgrade([preview.id]);
}
TS

Parameters

previewIdsstring[]
Required

Array of preview IDs to upgrade from thumbnail to full video

Returns

void

registerOnPreviewChangefunction
Required

Registers a callback to be invoked when preview data changes.

This callback is triggered when:

  • The design content changes
  • The output type changes
  • Preview media is upgraded from thumbnail to full video
  • Export settings are modified

Use this to update your preview UI in real-time as users modify their design.

Example: Handling preview updates

const disposer = registerOnPreviewChange(({ previewMedia, outputType, publishRef }) => {
  // Update your preview UI with the new preview media
  previewMedia.forEach((media) => {
    media.previews.forEach((preview) => {
      if (preview.status === 'ready') {
        displayPreview(preview);
      }
    });
  });
});


// Clean up when preview UI is unmounted
onUnmount(() => disposer());
TS

Parameters

callbackfunction
Required

The callback invoked when preview data is updated

Parameters

optsobject
Required
previewMediaPreviewMedia[]
Required

Preview media for a specific media slot.

Contains preview URLs and metadata for images or videos in the design.

mediaSlotIdstring
Required

ID of the media slot this preview belongs to.

Matches a media slot ID from your output type definition.

previewsPreview[]
Required

Array of preview items for this media slot.

May contain multiple previews if the media slot accepts multiple files.

Image preview in various states.

Image preview that is currently being generated.

Display a loading state until the preview transitions to "ready" or "error".

idstring
Required

Unique identifier for this preview.

Use this ID with requestPreviewUpgrade to upgrade video thumbnails.

widthPxnumber
Required

Width of the preview in pixels.

heightPxnumber
Required

Height of the preview in pixels.

kindstring
Required

Type of media in this preview.

The only valid value is "image".

statusstring
Required

Current state of the preview.

The only valid value is "loading".

Image preview that is ready to display.

Contains the URL to the preview image.

idstring
Required

Unique identifier for this preview.

Use this ID with requestPreviewUpgrade to upgrade video thumbnails.

widthPxnumber
Required

Width of the preview in pixels.

heightPxnumber
Required

Height of the preview in pixels.

kindstring
Required

Type of media in this preview.

The only valid value is "image".

statusstring
Required

Current state of the preview.

The only valid value is "ready".

formatstring
Required

Image format of the preview.

Available values:

  • "png"
  • "jpg"
urlstring
Required

URL to the preview image.

Use this URL to display the preview to users.

Image preview that failed to generate.

Display an error state to the user.

idstring
Required

Unique identifier for this preview.

Use this ID with requestPreviewUpgrade to upgrade video thumbnails.

widthPxnumber
Required

Width of the preview in pixels.

heightPxnumber
Required

Height of the preview in pixels.

kindstring
Required

Type of media in this preview.

The only valid value is "image".

statusstring
Required

Current state of the preview.

The only valid value is "error".

userFacingErrorMessagestring
Optional

Optional, user-facing error message to display in the preview UI.

Video preview in various states.

Videos transition through states: "loading" → "thumbnail" → "upgrading" → "ready". Start with thumbnails for better performance, then upgrade to full video using requestPreviewUpgrade.

Video preview that is currently being generated.

Display a loading state until the preview transitions to "thumbnail" or "error".

idstring
Required

Unique identifier for this preview.

Use this ID with requestPreviewUpgrade to upgrade video thumbnails.

widthPxnumber
Required

Width of the preview in pixels.

heightPxnumber
Required

Height of the preview in pixels.

kindstring
Required

Type of media in this preview.

The only valid value is "video".

statusstring
Required

Current state of the preview.

The only valid value is "loading".

Video preview with lightweight thumbnail available.

This is the initial state for video previews. Show the thumbnail image and call requestPreviewUpgrade when the user needs the full video.

idstring
Required

Unique identifier for this preview.

Use this ID with requestPreviewUpgrade to upgrade video thumbnails.

widthPxnumber
Required

Width of the preview in pixels.

heightPxnumber
Required

Height of the preview in pixels.

kindstring
Required

Type of media in this preview.

The only valid value is "video".

statusstring
Required

Current state of the preview.

The only valid value is "thumbnail".

thumbnailFormatstring
Required

Format of the thumbnail image.

Available values:

  • "png"
  • "jpg"
thumbnailUrlstring
Required

URL to the thumbnail image.

Display this lightweight image until full video is needed.

durationMsnumber
Optional

Video duration in milliseconds.

Video preview that is being upgraded from thumbnail to full video.

Display the thumbnail with a loading indicator until the video is ready.

idstring
Required

Unique identifier for this preview.

Use this ID with requestPreviewUpgrade to upgrade video thumbnails.

widthPxnumber
Required

Width of the preview in pixels.

heightPxnumber
Required

Height of the preview in pixels.

kindstring
Required

Type of media in this preview.

The only valid value is "video".

statusstring
Required

Current state of the preview.

The only valid value is "upgrading".

thumbnailFormatstring
Required

Format of the thumbnail image.

Available values:

  • "png"
  • "jpg"
thumbnailUrlstring
Required

URL to the thumbnail image.

Continue showing the thumbnail while the full video loads.

durationMsnumber
Optional

Video duration in milliseconds.

Video preview with full video ready to play.

Contains URLs for both the video and thumbnail.

idstring
Required

Unique identifier for this preview.

Use this ID with requestPreviewUpgrade to upgrade video thumbnails.

widthPxnumber
Required

Width of the preview in pixels.

heightPxnumber
Required

Height of the preview in pixels.

kindstring
Required

Type of media in this preview.

The only valid value is "video".

statusstring
Required

Current state of the preview.

The only valid value is "ready".

formatstring
Required

Video format.

The only valid value is "mp4".

urlstring
Required

URL to the full video.

Use this URL in a video player.

thumbnailFormatstring
Required

Format of the thumbnail image.

Available values:

  • "png"
  • "jpg"
thumbnailUrlstring
Required

URL to the thumbnail image.

Can be used as a poster image for the video player.

durationMsnumber
Optional

Video duration in milliseconds.

Video preview that failed to generate.

Display an error state to the user.

idstring
Required

Unique identifier for this preview.

Use this ID with requestPreviewUpgrade to upgrade video thumbnails.

widthPxnumber
Required

Width of the preview in pixels.

heightPxnumber
Required

Height of the preview in pixels.

kindstring
Required

Type of media in this preview.

The only valid value is "video".

statusstring
Required

Current state of the preview.

The only valid value is "error".

userFacingErrorMessagestring
Optional

Optional, user-facing error message to display in the preview UI.

outputTypeOutputType
Required

The output type that the preview data is for

idstring
Required

Unique identifier for this output type.

Use descriptive IDs like "instagram_post" or "youtube_video".

displayNamestring
Required

User-facing name for this output type.

This is displayed to users when selecting where to publish. Examples: "Instagram Post", "YouTube Video", "Twitter Post".

mediaSlotsMediaSlot[]
Required

Array of media slots defining what content is needed.

Each slot represents a piece of media required for publishing, such as a main image, thumbnail, or video.

idstring
Required

Unique identifier for this media slot within the output type.

displayNamestring
Required

User-facing name for this media slot.

Examples: "Post Image", "Video Thumbnail", "Main Video".

acceptsobject
Required

File type requirements for this slot.

Note the following behavior:

  • Provide at least one of image or video
  • If both are provided, files for this slot may be either images or videos; each file must satisfy the corresponding requirement for its media type
  • To restrict the slot to a single media type, provide only that requirement
  • fileCount applies across all files accepted by the slot regardless of media type
imageImageRequirement
Optional

Image file requirements for a media slot.

Specifies format, aspect ratio, and size constraints for images.

Example: Image requirements for social media post

const imageReq: ImageRequirement = {
  format: 'jpg',
  aspectRatio: { min: 0.8, max: 1.91 },
  maxFileSizeMb: 8
};
TS
formatstring
Required

Supported image format.

Available values:

  • "png"
  • "jpg"
maxFileSizeMbnumber
Optional

Maximum file size in megabytes.

Example: 10 for 10 MB maximum

aspectRatioValueRange
Optional

Aspect ratio constraint (width / height).

Examples:

  • { exact: 16/9 }: Widescreen (16:9)
  • { min: 0.8, max: 1.91 }: Instagram range

Exact value range constraint.

Example: Exact value range

const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
TS
exactnumber
Required

Minimum value range constraint.

Example: Minimum value range

const minValue: ValueRange = { min: 3 }; // At least 3
TS
minnumber
Required

Maximum value range constraint.

Example: Maximum value range

const maxValue: ValueRange = { max: 10 }; // At most 10
TS
maxnumber
Required

Minimum and maximum value range constraint. Ranges are inclusive (min ≤ value ≤ max).

Example: Minimum and maximum value range

const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
TS
minnumber
Required
maxnumber
Required
videoVideoRequirement
Optional

Video file requirements for a media slot.

Specifies format, aspect ratio, duration, and size constraints for videos.

Example: Video requirements for YouTube

const videoReq: VideoRequirement = {
  format: 'mp4',
  aspectRatio: { exact: 16/9 },
  durationMs: { min: 1000, max: 600000 },
  maxFileSizeMb: 100
};
TS
formatstring
Required

Supported video format.

The only valid value is "mp4".

maxFileSizeMbnumber
Optional

Maximum file size in megabytes.

Example: 10 for 10 MB maximum

aspectRatioValueRange
Optional

Aspect ratio constraint (width / height).

Examples:

  • { exact: 16/9 }: Widescreen
  • { exact: 9/16 }: Vertical/Story format

Exact value range constraint.

Example: Exact value range

const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
TS
exactnumber
Required

Minimum value range constraint.

Example: Minimum value range

const minValue: ValueRange = { min: 3 }; // At least 3
TS
minnumber
Required

Maximum value range constraint.

Example: Maximum value range

const maxValue: ValueRange = { max: 10 }; // At most 10
TS
maxnumber
Required

Minimum and maximum value range constraint. Ranges are inclusive (min ≤ value ≤ max).

Example: Minimum and maximum value range

const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
TS
minnumber
Required
maxnumber
Required
durationMsValueRange
Optional

Duration constraint in milliseconds.

Examples:

  • { max: 60000 }: Maximum 60 seconds
  • { min: 3000, max: 600000 }: Between 3 seconds and 10 minutes

Exact value range constraint.

Example: Exact value range

const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
TS
exactnumber
Required

Minimum value range constraint.

Example: Minimum value range

const minValue: ValueRange = { min: 3 }; // At least 3
TS
minnumber
Required

Maximum value range constraint.

Example: Maximum value range

const maxValue: ValueRange = { max: 10 }; // At most 10
TS
maxnumber
Required

Minimum and maximum value range constraint. Ranges are inclusive (min ≤ value ≤ max).

Example: Minimum and maximum value range

const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
TS
minnumber
Required
maxnumber
Required
durationValueRange
Deprecated

use durationMs instead.

Exact value range constraint.

Example: Exact value range

const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
TS
exactnumber
Required

Minimum value range constraint.

Example: Minimum value range

const minValue: ValueRange = { min: 3 }; // At least 3
TS
minnumber
Required

Maximum value range constraint.

Example: Maximum value range

const maxValue: ValueRange = { max: 10 }; // At most 10
TS
maxnumber
Required

Minimum and maximum value range constraint. Ranges are inclusive (min ≤ value ≤ max).

Example: Minimum and maximum value range

const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
TS
minnumber
Required
maxnumber
Required
fileCountValueRange
Optional

Number of files accepted in this slot.

Use this to specify single or multiple file requirements. Examples:

  • { exact: 1 }: Exactly one file
  • { min: 1, max: 10 }: Between 1 and 10 files
  • undefined: Any number of files

Exact value range constraint.

Example: Exact value range

const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
TS
exactnumber
Required

Minimum value range constraint.

Example: Minimum value range

const minValue: ValueRange = { min: 3 }; // At least 3
TS
minnumber
Required

Maximum value range constraint.

Example: Maximum value range

const maxValue: ValueRange = { max: 10 }; // At most 10
TS
maxnumber
Required

Minimum and maximum value range constraint. Ranges are inclusive (min ≤ value ≤ max).

Example: Minimum and maximum value range

const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
TS
minnumber
Required
maxnumber
Required
publishRefstring
Optional

The current publish settings reference, if available

Returns

void

Returns

A disposer function that cleans up the registered callback.

() => void

Returns

void

publishContentfunction
Required

Publishes the content to the external platform.

This action is called when the user confirms the publish action after reviewing settings and preview. Your implementation should send the exported files to your platform's API.

The outputMedia contains production-ready files that match the requirements specified in your output types. The publishRef contains the user's settings from the settings UI.

Example: Publishing content to an external platform

import type { PublishContentRequest, PublishContentResponse } from '@canva/intents/content';


async function publishContent(request: PublishContentRequest): Promise<PublishContentResponse> {
  const { publishRef, outputType, outputMedia } = request;


  try {
    // Parse settings from publishRef
    const settings = publishRef ? JSON.parse(publishRef) : {};


    // Upload files to your platform
    const uploadedFiles = await Promise.all(
      outputMedia.flatMap(media =>
        media.files.map(file => uploadFile(file.url))
      )
    );


    // Create post on your platform
    const result = await createPost({
      files: uploadedFiles,
      caption: settings.caption
    });


    return {
      status: 'completed',
      externalId: result.id,
      externalUrl: result.url
    };
  } catch (error) {
    return {
      status: 'remote_request_failed'
    };
  }
}
TS

Parameters

requestPublishContentRequest
Required

Parameters for the publish operation.

outputTypeOutputType
Required

The output type selected by the user for this publish operation.

This matches one of the output types you provided in getPublishConfiguration.

idstring
Required

Unique identifier for this output type.

Use descriptive IDs like "instagram_post" or "youtube_video".

displayNamestring
Required

User-facing name for this output type.

This is displayed to users when selecting where to publish. Examples: "Instagram Post", "YouTube Video", "Twitter Post".

mediaSlotsMediaSlot[]
Required

Array of media slots defining what content is needed.

Each slot represents a piece of media required for publishing, such as a main image, thumbnail, or video.

idstring
Required

Unique identifier for this media slot within the output type.

displayNamestring
Required

User-facing name for this media slot.

Examples: "Post Image", "Video Thumbnail", "Main Video".

acceptsobject
Required

File type requirements for this slot.

Note the following behavior:

  • Provide at least one of image or video
  • If both are provided, files for this slot may be either images or videos; each file must satisfy the corresponding requirement for its media type
  • To restrict the slot to a single media type, provide only that requirement
  • fileCount applies across all files accepted by the slot regardless of media type
imageImageRequirement
Optional

Image file requirements for a media slot.

Specifies format, aspect ratio, and size constraints for images.

Example: Image requirements for social media post

const imageReq: ImageRequirement = {
  format: 'jpg',
  aspectRatio: { min: 0.8, max: 1.91 },
  maxFileSizeMb: 8
};
TS
formatstring
Required

Supported image format.

Available values:

  • "png"
  • "jpg"
maxFileSizeMbnumber
Optional

Maximum file size in megabytes.

Example: 10 for 10 MB maximum

aspectRatioValueRange
Optional

Aspect ratio constraint (width / height).

Examples:

  • { exact: 16/9 }: Widescreen (16:9)
  • { min: 0.8, max: 1.91 }: Instagram range

Exact value range constraint.

Example: Exact value range

const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
TS
exactnumber
Required

Minimum value range constraint.

Example: Minimum value range

const minValue: ValueRange = { min: 3 }; // At least 3
TS
minnumber
Required

Maximum value range constraint.

Example: Maximum value range

const maxValue: ValueRange = { max: 10 }; // At most 10
TS
maxnumber
Required

Minimum and maximum value range constraint. Ranges are inclusive (min ≤ value ≤ max).

Example: Minimum and maximum value range

const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
TS
minnumber
Required
maxnumber
Required
videoVideoRequirement
Optional

Video file requirements for a media slot.

Specifies format, aspect ratio, duration, and size constraints for videos.

Example: Video requirements for YouTube

const videoReq: VideoRequirement = {
  format: 'mp4',
  aspectRatio: { exact: 16/9 },
  durationMs: { min: 1000, max: 600000 },
  maxFileSizeMb: 100
};
TS
formatstring
Required

Supported video format.

The only valid value is "mp4".

maxFileSizeMbnumber
Optional

Maximum file size in megabytes.

Example: 10 for 10 MB maximum

aspectRatioValueRange
Optional

Aspect ratio constraint (width / height).

Examples:

  • { exact: 16/9 }: Widescreen
  • { exact: 9/16 }: Vertical/Story format

Exact value range constraint.

Example: Exact value range

const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
TS
exactnumber
Required

Minimum value range constraint.

Example: Minimum value range

const minValue: ValueRange = { min: 3 }; // At least 3
TS
minnumber
Required

Maximum value range constraint.

Example: Maximum value range

const maxValue: ValueRange = { max: 10 }; // At most 10
TS
maxnumber
Required

Minimum and maximum value range constraint. Ranges are inclusive (min ≤ value ≤ max).

Example: Minimum and maximum value range

const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
TS
minnumber
Required
maxnumber
Required
durationMsValueRange
Optional

Duration constraint in milliseconds.

Examples:

  • { max: 60000 }: Maximum 60 seconds
  • { min: 3000, max: 600000 }: Between 3 seconds and 10 minutes

Exact value range constraint.

Example: Exact value range

const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
TS
exactnumber
Required

Minimum value range constraint.

Example: Minimum value range

const minValue: ValueRange = { min: 3 }; // At least 3
TS
minnumber
Required

Maximum value range constraint.

Example: Maximum value range

const maxValue: ValueRange = { max: 10 }; // At most 10
TS
maxnumber
Required

Minimum and maximum value range constraint. Ranges are inclusive (min ≤ value ≤ max).

Example: Minimum and maximum value range

const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
TS
minnumber
Required
maxnumber
Required
durationValueRange
Deprecated

use durationMs instead.

Exact value range constraint.

Example: Exact value range

const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
TS
exactnumber
Required

Minimum value range constraint.

Example: Minimum value range

const minValue: ValueRange = { min: 3 }; // At least 3
TS
minnumber
Required

Maximum value range constraint.

Example: Maximum value range

const maxValue: ValueRange = { max: 10 }; // At most 10
TS
maxnumber
Required

Minimum and maximum value range constraint. Ranges are inclusive (min ≤ value ≤ max).

Example: Minimum and maximum value range

const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
TS
minnumber
Required
maxnumber
Required
fileCountValueRange
Optional

Number of files accepted in this slot.

Use this to specify single or multiple file requirements. Examples:

  • { exact: 1 }: Exactly one file
  • { min: 1, max: 10 }: Between 1 and 10 files
  • undefined: Any number of files

Exact value range constraint.

Example: Exact value range

const exactValue: ValueRange = { exact: 1 }; // Must be exactly 1
TS
exactnumber
Required

Minimum value range constraint.

Example: Minimum value range

const minValue: ValueRange = { min: 3 }; // At least 3
TS
minnumber
Required

Maximum value range constraint.

Example: Maximum value range

const maxValue: ValueRange = { max: 10 }; // At most 10
TS
maxnumber
Required

Minimum and maximum value range constraint. Ranges are inclusive (min ≤ value ≤ max).

Example: Minimum and maximum value range

const minMaxValue: ValueRange = { min: 1, max: 10 }; // Between 1 and 10
TS
minnumber
Required
maxnumber
Required
outputMediaOutputMedia[]
Required

Production-ready exported files matching the requirements from your output type.

These files are ready to upload to your platform and match the format, size, and aspect ratio requirements specified in your media slots.

mediaSlotIdstring
Required

ID of the media slot these files belong to.

Matches a media slot ID from your output type definition.

filesOutputFile[]
Required

Array of exported files for this media slot.

Files match the requirements specified in your media slot configuration.

Exported image file ready for publishing.

formatPublishFileFormat
Required

File format.

Available values:

  • "png"
  • "jpg"
  • "mp4"
urlstring
Required

URL to download the exported file.

Your app should download from this URL and upload to your platform.

widthPxnumber
Required

Width of the image in pixels.

heightPxnumber
Required

Height of the image in pixels.

Exported video file ready for publishing.

formatPublishFileFormat
Required

File format.

Available values:

  • "png"
  • "jpg"
  • "mp4"
urlstring
Required

URL to download the exported file.

Your app should download from this URL and upload to your platform.

widthPxnumber
Required

Width of the video in pixels.

heightPxnumber
Required

Height of the video in pixels.

publishRefstring
Optional

Platform-specific settings reference containing user configurations.

This is the same reference you saved via updatePublishSettings in the settings UI. Parse this string to retrieve the user's publish settings (e.g., captions, tags, privacy).

Maximum size: 5KB

Returns

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

Successful response from publishing a content.

Examples

Basic successful publish

return {
  status: 'completed',
  externalId: 'post_12345',
  externalUrl: 'https://example.com/posts/12345'
};
TS

Successful publish with redirect

return {
  status: 'completed',
  externalId: 'video_67890',
  externalUrl: 'https://example.com/videos/67890',
  postPublishAction: {
    type: 'redirect',
    url: 'https://example.com/videos/67890/edit'
  }
};
TS
statusstring

The only valid value is "completed".

externalIdstring
Optional

Unique identifier returned from your external platform. You can use this for:

  • Tracking published content
  • Fetching insights data for the published content
  • Linking back to the content in future operations
externalUrlstring
Optional

Direct URL to the published content on your platform.

Users can visit this URL to view their published content. This may be displayed to users or used for sharing.

postPublishActionPostPublishAction
Optional

Optional action to perform after publishing completes.

Currently supports redirecting users to a specific URL after publishing.

typestring

The only valid value is "redirect".

urlstring

The URL to redirect the user to after publishing.

Error response from publishing a content.

Return the appropriate error type based on the failure:

  • "remote_request_failed": Network or API errors with your platform
  • "app_error": Custom application errors with optional message

PublishContentError indicating failure of the remote request to the external platform.

Return this error for:

  • Network connectivity issues
  • API endpoint failures
  • HTTP errors from your platform
  • Timeout errors

Example: Handling network errors

try {
  await uploadToExternalPlatform(file);
} catch (error) {
  return { status: 'remote_request_failed' };
}
TS
statusstring

The only valid value is "remote_request_failed".

PublishContentError indicating a custom error occurred in your app's implementation.

Return this for application-specific errors such as:

  • Validation failures
  • Authentication errors
  • Rate limiting
  • Platform-specific restrictions

Example: Returning custom error with message

if (userQuotaExceeded) {
  return {
    status: 'app_error',
    message: 'You have reached your monthly publish limit. Please upgrade your plan.'
  };
}
TS
statusstring

The only valid value is "app_error".

messagestring
Optional

User-friendly message explaining the error.

Returns

void