Canva Design Import API

openapi: 3.2.0
info:
  contact:
    name: Canva Developer Community
    url: https://community.canva.dev/
  description: API for building integrations with Canva via a REST api
  license:
    name: ©2023 All Rights Reserved
  termsOfService: https://www.canva.com/trust/legal/
  title: Canva Connect Design Import API
  version: 2024-06-18
servers:
- description: Canva Connect API
  url: https://api.canva.com/rest
tags:
- name: design_import
paths:
  /v1/imports:
    post:
      description: 'Starts a new asynchronous job to import an external file as a new design in Canva.


        The request format for this endpoint has an `application/octet-stream` body of bytes,

        and the information about the import is provided using an `Import-Metadata` header.


        Supported file types for imports are listed in Design imports overview.


        For more information on the workflow for using asynchronous jobs, see API requests and responses. You can check the status and get the results of design import jobs created with this API using the Get design import job API.'
      operationId: createDesignImportJob
      parameters:
      - content:
          application/json:
            schema:
              $ref: '#/components/schemas/DesignImportMetadata'
        in: header
        name: Import-Metadata
        required: true
      requestBody:
        content:
          application/octet-stream:
            schema:
              format: binary
              type: string
        description: Binary of the file to import.
        required: true
      responses:
        '200':
          content:
            application/json:
              examples:
                in_progress:
                  $ref: '#/components/examples/InProgressDesignImportJobExample'
                success:
                  $ref: '#/components/examples/SuccessDesignImportJobExample'
                failed:
                  $ref: '#/components/examples/FailedDesignImportJobExample'
              schema:
                $ref: '#/components/schemas/CreateDesignImportJobResponse'
          description: OK
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Error Response
      security:
      - oauthAuthCode:
        - design:content:write
      tags:
      - design_import
      x-rate-limit-per-client-user: 20
      summary: Create design import job
      x-summary-source: derived
  /v1/imports/{jobId}:
    get:
      description: 'Gets the result of a design import job created using the Create design import job API.


        You might need to make multiple requests to this endpoint until you get a `success` or `failed` status. For more information on the workflow for using asynchronous jobs, see API requests and responses.'
      operationId: getDesignImportJob
      parameters:
      - description: The design import job ID.
        example: f81b26fd-a33d-4c2d-9e8c-4a7aca798b17
        explode: false
        in: path
        name: jobId
        required: true
        schema:
          pattern: ^[a-zA-Z0-9_-]{1,50}$
          type: string
        style: simple
      responses:
        '200':
          content:
            application/json:
              examples:
                in_progress:
                  $ref: '#/components/examples/InProgressDesignImportJobExample'
                success:
                  $ref: '#/components/examples/SuccessDesignImportJobExample'
                failed:
                  $ref: '#/components/examples/FailedDesignImportJobExample'
              schema:
                $ref: '#/components/schemas/GetDesignImportJobResponse'
          description: OK
        '400':
          content:
            application/json:
              examples:
                job_id_invalid:
                  $ref: '#/components/examples/JobIdInvalidError'
                job_not_created_via_connect_api:
                  $ref: '#/components/examples/JobNotCreatedViaConnectApiError'
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request
        '403':
          content:
            application/json:
              examples:
                design_import_job_not_creator:
                  $ref: '#/components/examples/DesignImportJobNotCreatorError'
                get_job_status_not_allowed:
                  $ref: '#/components/examples/GetJobStatusNotAllowedError'
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden
        '404':
          content:
            application/json:
              examples:
                job_id_not_found:
                  $ref: '#/components/examples/JobIdNotFoundError'
                job_not_found:
                  $ref: '#/components/examples/JobNotFoundError'
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Error Response
      security:
      - oauthAuthCode:
        - design:content:write
      tags:
      - design_import
      x-rate-limit-per-client-user: 120
      summary: Get design import job
      x-summary-source: derived
  /v1/url-imports:
    post:
      description: 'Starts a new asynchronous job to import an external file from a URL as a new design in Canva.


        Supported file types for imports are listed in Design imports overview.


        For more information on the workflow for using asynchronous jobs, see API requests and responses. You can check the status and get the results of design import jobs created with this API using the Get URL import job API.'
      operationId: createUrlImportJob
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUrlImportJobRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              examples:
                in_progress:
                  $ref: '#/components/examples/InProgressDesignImportJobExample'
                success:
                  $ref: '#/components/examples/SuccessDesignImportJobExample'
                failed:
                  $ref: '#/components/examples/FailedDesignImportJobExample'
              schema:
                $ref: '#/components/schemas/CreateUrlImportJobResponse'
          description: OK
        '400':
          content:
            application/json:
              examples:
                design_import_already_in_progress:
                  $ref: '#/components/examples/DesignImportAlreadyInProgressError'
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request
        '404':
          content:
            application/json:
              examples:
                job_with_id_not_found:
                  $ref: '#/components/examples/JobWithIdNotFoundError'
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Error Response
      security:
      - oauthAuthCode:
        - design:content:write
      tags:
      - design_import
      x-rate-limit-per-client-user: 20
      summary: Create url import job
      x-summary-source: derived
  /v1/url-imports/{jobId}:
    get:
      description: 'Gets the result of a URL import job created using the Create URL import job API.


        You might need to make multiple requests to this endpoint until you get a `success` or `failed` status. For more information on the workflow for using asynchronous jobs, see API requests and responses.'
      operationId: getUrlImportJob
      parameters:
      - description: The ID of the URL import job.
        example: f81b26fd-a33d-4c2d-9e8c-4a7aca798b17
        explode: false
        in: path
        name: jobId
        required: true
        schema:
          pattern: ^[a-zA-Z0-9_-]{1,50}$
          type: string
        style: simple
      responses:
        '200':
          content:
            application/json:
              examples:
                in_progress:
                  $ref: '#/components/examples/InProgressDesignImportJobExample'
                success:
                  $ref: '#/components/examples/SuccessDesignImportJobExample'
                failed:
                  $ref: '#/components/examples/FailedDesignImportJobExample'
              schema:
                $ref: '#/components/schemas/GetUrlImportJobResponse'
          description: OK
        '400':
          content:
            application/json:
              examples:
                job_not_created_via_connect_api:
                  $ref: '#/components/examples/JobNotCreatedViaConnectApiError'
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request
        '403':
          content:
            application/json:
              examples:
                get_job_status_not_allowed:
                  $ref: '#/components/examples/GetJobStatusNotAllowedError'
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden
        '404':
          content:
            application/json:
              examples:
                job_not_found:
                  $ref: '#/components/examples/JobNotFoundError'
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Error Response
      security:
      - oauthAuthCode:
        - design:content:write
      tags:
      - design_import
      x-rate-limit-per-client-user: 120
      summary: Get url import job
      x-summary-source: derived
components:
  examples:
    JobWithIdNotFoundError:
      summary: Job with ID not found
      value:
        code: not_found
        message: Job with Id {jobId} not found
    DesignImportJobNotCreatorError:
      summary: Calling user was not the creator of the design import job
      value:
        code: permission_denied
        message: Calling user was not the creator of the design import job
    JobNotCreatedViaConnectApiError:
      summary: The job is not created via Connect API
      value:
        code: invalid_request
        message: The job is not created via Connect API.
    SuccessDesignImportJobExample:
      summary: Successfully completed job
      value:
        job:
          id: e08861ae-3b29-45db-8dc1-1fe0bf7f1cc8
          status: success
          result:
            designs:
            - id: DAGQm2AkzOk
              title: My Awesome Design
              thumbnail:
                width: 376
                height: 531
                url: https://document-export.canva.com/...
              urls:
                edit_url: https://www.canva.com/api/design/...
                view_url: https://www.canva.com/api/design/...
              created_at: 1726198998
              updated_at: 1726199000
    JobNotFoundError:
      summary: Job not found
      value:
        code: not_found
        message: Job {jobId} not found
    InProgressDesignImportJobExample:
      summary: In progress job
      value:
        job:
          id: e08861ae-3b29-45db-8dc1-1fe0bf7f1cc8
          status: in_progress
    FailedDesignImportJobExample:
      summary: Failed job
      value:
        job:
          id: e08861ae-3b29-45db-8dc1-1fe0bf7f1cc8
          status: failed
          error:
            code: invalid_file
            message: Document could not be imported because the file is corrupt.
    JobIdNotFoundError:
      summary: Job ID not found
      value:
        code: not_found
        message: Job ID {jobId} not found
    JobIdInvalidError:
      summary: The job ID is invalid
      value:
        code: bad_request_params
        message: The jobId is invalid.
    DesignImportAlreadyInProgressError:
      summary: A design import for the URL is already in progress
      value:
        code: invalid_request
        message: Design import for url {url} already in progress
    GetJobStatusNotAllowedError:
      summary: Not allowed to get the job status
      value:
        code: permission_denied
        message: Not allowed to get the job status.
  schemas:
    CreateUrlImportJobResponse:
      properties:
        job:
          $ref: '#/components/schemas/DesignImportJob'
      required:
      - job
      type: object
    ErrorCode:
      description: 'A short string indicating what failed. This field can be used to handle errors programmatically.

        '
      enum:
      - internal_error
      - invalid_field
      - invalid_header_value
      - permission_denied
      - too_many_requests
      - not_found
      - bad_request_body
      - bad_http_method
      - bad_request_params
      - bad_query_params
      - user_role_required
      - endpoint_not_found
      - endpoint_gone
      - unsupported_version
      - invalid_access_token
      - revoked_access_token
      - missing_field
      - missing_scope
      - invalid_grant
      - invalid_request
      - invalid_client
      - unauthorized_client
      - unsupported_grant_type
      - invalid_scope
      - invalid_basic_header
      - invalid_file_format
      - quota_exceeded
      - ai_credit_quota_exceeded
      - ai_credit_quota_cooldown
      - unsupported_content_type
      - request_too_large
      - folder_not_found
      - item_in_multiple_folders
      - asset_not_found
      - max_limit_reached
      - permission_not_found
      - permission_exists
      - unauthorized_user
      - user_not_found
      - user_not_eligible
      - group_not_found
      - app_not_found
      - app_has_non_draft_versions
      - invalid_status_transition
      - translation_validation_failed
      - content_not_found
      - doctype_not_found
      - design_not_found
      - offset_too_large
      - page_not_found
      - design_or_comment_not_found
      - design_or_thread_not_found
      - review_dismissed
      - design_type_not_found
      - team_not_found
      - team_is_default
      - comment_not_found
      - too_many_comments
      - too_many_replies
      - message_too_long
      - thread_not_found
      - reply_not_found
      - design_not_fillable
      - autofill_data_invalid
      - feature_not_available
      - unsupported_design_type
      - design_generation_not_enabled
      - license_required
      - input_unsafe
      - display_name_unavailable
      - user_not_managed
      - saml_team_id_conflict
      - saml_name_id_not_available
      - user_email_unverified
      - user_not_active
      - user_pending_consent
      - account_exists
      type: string
    DesignImportMetadata:
      description: Metadata about the design that you include as a header parameter when importing a design.
      properties:
        title_base64:
          description: 'The design''s title, encoded in Base64.


            The maximum length of a design title in Canva (unencoded) is 50 characters.


            Base64 encoding allows titles containing emojis and other special

            characters to be sent using HTTP headers.

            For example, "My Awesome Design 😍" Base64 encoded

            is `TXkgQXdlc29tZSBEZXNpZ24g8J+YjQ==`.'
          example: TXkgQXdlc29tZSBEZXNpZ24g8J+YjQ==
          minLength: 1
          type: string
        mime_type:
          description: The MIME type of the file being imported. If not provided, Canva attempts to automatically detect the type of the file.
          example: application/pdf
          type: string
      required:
      - title_base64
      type: object
    DesignImportJob:
      description: The status of the design import job.
      properties:
        id:
          description: The ID of the design import job.
          example: e08861ae-3b29-45db-8dc1-1fe0bf7f1cc8
          pattern: ^[a-zA-Z0-9_-]{1,50}$
          type: string
        status:
          $ref: '#/components/schemas/DesignImportStatus'
        result:
          $ref: '#/components/schemas/DesignImportJobResult'
        error:
          $ref: '#/components/schemas/DesignImportError'
      required:
      - id
      - status
      type: object
    CreateDesignImportJobResponse:
      properties:
        job:
          $ref: '#/components/schemas/DesignImportJob'
      required:
      - job
      type: object
    CreateUrlImportJobRequest:
      properties:
        title:
          description: A title for the design.
          example: My Awesome Design
          maxLength: 255
          minLength: 1
          type: string
        url:
          description: The URL of the file to import. This URL must be accessible from the internet and be publicly available.
          maxLength: 2048
          minLength: 1
          type: string
        mime_type:
          description: The MIME type of the file being imported. If not provided, Canva attempts to automatically detect the type of the file.
          example: application/vnd.apple.keynote
          maxLength: 100
          minLength: 1
          type: string
      required:
      - title
      - url
      type: object
    DesignImportErrorCode:
      description: 'A short string about why the import failed. This field can be used to handle errors

        programmatically.'
      enum:
      - design_creation_throttled
      - design_import_throttled
      - duplicate_import
      - internal_error
      - invalid_file
      - fetch_failed
      example: design_creation_throttled
      type: string
    Thumbnail:
      description: A thumbnail image representing the object.
      properties:
        width:
          description: The width of the thumbnail image in pixels.
          example: 595
          format: int32
          type: integer
        height:
          description: The height of the thumbnail image in pixels.
          example: 335
          format: int32
          type: integer
        url:
          description: 'A URL for retrieving the thumbnail image.

            This URL expires after 15 minutes. This URL includes a query string

            that''s required for retrieving the thumbnail.'
          example: https://document-export.canva.com/Vczz9/zF9vzVtdADc/2/thumbnail/0001.png?<query-string>
          type: string
      required:
      - height
      - url
      - width
      type: object
    GetDesignImportJobResponse:
      properties:
        job:
          $ref: '#/components/schemas/DesignImportJob'
      required:
      - job
      type: object
    DesignImportError:
      description: If the import job fails, this object provides details about the error.
      properties:
        code:
          $ref: '#/components/schemas/DesignImportErrorCode'
        message:
          description: A human-readable description of what went wrong.
          example: We're sorry, but the file upload quota has exceeded. Please try again later.
          type: string
      required:
      - code
      - message
      type: object
    Error:
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          description: A human-readable description of what went wrong.
          type: string
      required:
      - code
      - message
      type: object
    DesignLinks:
      description: A temporary set of URLs for viewing or editing the design.
      properties:
        edit_url:
          description: 'A temporary editing URL for the design. This URL is only accessible to the user that made the API request, and is designed to support [return navigation](https://www.canva.dev/docs/connect/return-navigation-guide/) workflows.


            NOTE: This is not a permanent URL, it is only valid for 30 days.'
          example: https://www.canva.com/api/design/eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIiwiZXhwaXJ5IjoxNzQyMDk5NDAzMDc5fQ..GKLx2hrJa3wSSDKQ.hk3HA59qJyxehR-ejzt2DThBW0cbRdMBz7Fb5uCpwD-4o485pCf4kcXt_ypUYX0qMHVeZ131YvfwGPIhbk-C245D8c12IIJSDbZUZTS7WiCOJZQ.sNz3mPSQxsETBvl_-upMYA/edit
          type: string
        view_url:
          description: 'A temporary viewing URL for the design. This URL is only accessible to the user that made the API request, and is designed to support [return navigation](https://www.canva.dev/docs/connect/return-navigation-guide/) workflows.


            NOTE: This is not a permanent URL, it is only valid for 30 days.

            '
          example: https://www.canva.com/api/design/eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIiwiZXhwaXJ5IjoxNzQyMDk5NDAzMDc5fQ..GKLx2hrJa3wSSDKQ.hk3HA59qJyxehR-ejzt2DThBW0cbRdMBz7Fb5uCpwD-4o485pCf4kcXt_ypUYX0qMHVeZ131YvfwGPIhbk-C245D8c12IIJSDbZUZTS7WiCOJZQ.sNz3mPSQxsETBvl_-upMYA/view
          type: string
      required:
      - edit_url
      - view_url
      type: object
    GetUrlImportJobResponse:
      properties:
        job:
          $ref: '#/components/schemas/DesignImportJob'
      required:
      - job
      type: object
    DesignImportStatus:
      description: The status of the design import job.
      enum:
      - failed
      - in_progress
      - success
      example: success
      type: string
    DesignSummary:
      description: Basic details about the design, such as the design's ID, title, and URL.
      properties:
        id:
          description: The design ID.
          example: DAFVztcvd9z
          type: string
        title:
          description: The design title.
          example: My summer holiday
          type: string
        url:
          description: URL of the design.
          example: https://www.canva.com/design/DAFVztcvd9z/edit
          type: string
        thumbnail:
          $ref: '#/components/schemas/Thumbnail'
        urls:
          $ref: '#/components/schemas/DesignLinks'
        created_at:
          description: 'When the design was created in Canva, as a Unix timestamp (in seconds since the Unix

            Epoch).'
          example: 1377396000
          format: int64
          type: integer
        updated_at:
          description: 'When the design was last updated in Canva, as a Unix timestamp (in seconds since the

            Unix Epoch).'
          example: 1692928800
          format: int64
          type: integer
        page_count:
          description: The total number of pages in the design. Some design types don't have pages (for example, Canva docs).
          example: 3
          format: int32
          minimum: 0
          type: integer
      required:
      - created_at
      - id
      - updated_at
      - urls
      type: object
    DesignImportJobResult:
      properties:
        designs:
          description: 'A list of designs imported from the external file. It usually contains one item.

            Imports with a large number of pages or assets are split into multiple designs.'
          items:
            $ref: '#/components/schemas/DesignSummary'
          type: array
      required:
      - designs
      type: object
  securitySchemes:
    basicAuth:
      scheme: basic
      type: http
    oauthAuthCode:
      flows:
        authorizationCode:
          authorizationUrl: https://www.canva.com/api/oauth/authorize
          scopes:
            design:content:read: View the contents of the user's designs.
            design:meta:read: View the metadata of the user's designs.
            design:content:write: Create designs on the user's behalf.
            folder:read: 'View the metadata and contents of the user''s folders, including their **Projects**

              folder.'
            folder:write: 'Add, move, or remove the user''s folders. It also lets you edit folder metadata,

              such as the folder''s name.'
            folder:permission:write: Set, update, or remove permissions assigned to the user's folders.
            asset:read: View the metadata for the user's assets, such as uploaded images.
            asset:write: Upload, update, or delete assets on the user's behalf.
            comment:read: View the comments on the user's designs, and the associated metadata.
            comment:write: Create comments and replies on the user's designs.
            collaboration:event: Receive webhook notifications about events relevant to the user.
            brandtemplate:meta:read: View the metadata of the brand templates associated with the user's brand.
            brandtemplate:content:read: Read the content of the brand templates associated with the user's brand.
            brandtemplate:content:write: Publish brand templates associated with the user's brand.
            profile:read: Read a user's profile and account information.
            openid: Read user information through Open ID Connect (OIDC).
            profile: Read user profile information through OIDC.
            email: Read user email address through OIDC.
          tokenUrl: https://api.canva.com/rest/v1/oauth/token
      type: oauth2