Canva Merge 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 Merge API
  version: 2024-06-18
servers:
- description: Canva Connect API
  url: https://api.canva.com/rest
tags:
- name: Merge
paths:
  /v1/merges:
    post:
      description: 'This API is currently provided as a preview. Be aware of the following:


        - There might be unannounced breaking changes.

        - Any breaking changes to preview APIs won''t produce a new API version.

        - Public integrations that use preview APIs will not pass the review process, and can''t be made available to all Canva users.


        Starts a new asynchronous job to merge design pages by applying page operations (such as insert, move, or delete) to produce a new design or modify an existing one.


        When the job completes successfully, the job result includes metadata for the created or updated design.


        At this stage, only a single operation per request is supported by default, and passing multiple operations will fail. Contact Canva to enable multi-operation mode for your integration.


        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 jobs created with this API using the Get design merge job API.'
      operationId: createDesignMergeJob
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDesignMergeJobRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateDesignMergeJobResponse'
          description: OK
        '400':
          content:
            application/json:
              examples:
                invalid_merge_job_type:
                  $ref: '#/components/examples/InvalidMergeJobTypeError'
                invalid_operation:
                  $ref: '#/components/examples/InvalidOperationError'
                invalid_page_number:
                  $ref: '#/components/examples/InvalidPageNumberError'
                unsupported_page_type:
                  $ref: '#/components/examples/UnsupportedPageTypeError'
                unsupported_document_type:
                  $ref: '#/components/examples/UnsupportedDocumentTypeError'
                operation_not_supported:
                  $ref: '#/components/examples/OperationNotSupportedError'
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request
        '403':
          content:
            application/json:
              examples:
                design_forbidden:
                  $ref: '#/components/examples/DesignForbiddenError'
                unauthorized_private_resource:
                  $ref: '#/components/examples/UnauthorizedPrivateResourceError'
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden
        '404':
          content:
            application/json:
              examples:
                merge_design_not_found:
                  $ref: '#/components/examples/MergeDesignNotFoundError'
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        '413':
          content:
            application/json:
              examples:
                request_too_large:
                  $ref: '#/components/examples/RequestTooLargeError'
              schema:
                $ref: '#/components/schemas/Error'
          description: Request Entity Too Large
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Error Response
      security:
      - oauthAuthCode:
        - design:content:write
        - design:meta:read
      tags:
      - Merge
      x-rate-limit-per-client-user: 100
      summary: Create design merge job
      x-summary-source: derived
  /v1/merges/{jobId}:
    get:
      description: 'This API is currently provided as a preview. Be aware of the following:


        - There might be unannounced breaking changes.

        - Any breaking changes to preview APIs won''t produce a new API version.

        - Public integrations that use preview APIs will not pass the review process, and can''t be made available to all Canva users.


        Gets the result of a design merge job that was created using the Create design merge job API.


        If the job is successful, the response includes the job status and a `result` object with metadata for the created or updated design.


        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: getDesignMergeJob
      parameters:
      - description: The design merge job ID.
        explode: false
        in: path
        name: jobId
        required: true
        schema:
          example: a7by3wd-abc123
          pattern: ^[a-zA-Z0-9_-]{1,50}$
          type: string
        style: simple
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDesignMergeJobResponse'
          description: OK
        '403':
          content:
            application/json:
              examples:
                merge_job_forbidden:
                  $ref: '#/components/examples/MergeJobForbiddenError'
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden
        '404':
          content:
            application/json:
              examples:
                merge_job_not_found:
                  $ref: '#/components/examples/MergeJobNotFoundError'
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Error Response
      security:
      - oauthAuthCode:
        - design:meta:read
      tags:
      - Merge
      x-rate-limit-per-client-user: 100
      summary: Get design merge job
      x-summary-source: derived
components:
  schemas:
    NewDesignCreateDesignMergeJobRequest:
      description: Creates a new design by inserting pages from other designs.
      properties:
        type:
          description: The type of merge job to create.
          enum:
          - create_new_design
          example: create_new_design
          type: string
        operations:
          description: For this job type, only insert operations are supported.
          items:
            $ref: '#/components/schemas/DesignMergeOperation'
          maxItems: 500
          minItems: 1
          type: array
        title:
          description: Title for the new design.
          example: My merged design
          maxLength: 255
          minLength: 1
          type: string
      required:
      - operations
      - title
      - type
      type: object
    ModifyDesignCreateDesignMergeJobRequest:
      description: Modifies an existing design by inserting, moving, or deleting pages.
      properties:
        type:
          description: The type of merge job to create.
          enum:
          - modify_existing_design
          example: modify_existing_design
          type: string
        design_id:
          description: The ID of the design to modify.
          example: DAFVztcvd9z
          pattern: ^[a-zA-Z0-9_-]{1,50}$
          type: string
        operations:
          description: Supports insert, move, and delete operations.
          items:
            $ref: '#/components/schemas/DesignMergeOperation'
          maxItems: 500
          minItems: 1
          type: array
        title:
          description: Optional new title for the design.
          example: My updated design
          maxLength: 255
          minLength: 1
          type: string
      required:
      - design_id
      - operations
      - type
      type: object
    DesignMergeErrorCode:
      enum:
      - thumbnail_generation_error
      - merge_error
      - create_design_error
      - modify_design_error
      type: string
    DesignMergeError:
      description: If the merge job fails, this object provides details about the error.
      properties:
        code:
          $ref: '#/components/schemas/DesignMergeErrorCode'
        message:
          description: A human-readable description of what went wrong.
          example: The merge job failed due to an internal error.
          type: string
      required:
      - code
      - message
      type: object
    CreateDesignMergeJobResponse:
      properties:
        job:
          $ref: '#/components/schemas/DesignMergeJob'
      required:
      - job
      type: object
    DesignMergeJob:
      description: The details of a design merge job.
      properties:
        id:
          description: The ID of the design merge job.
          example: a7by3wd-abc123
          type: string
        status:
          $ref: '#/components/schemas/DesignMergeJobStatus'
        result:
          $ref: '#/components/schemas/DesignMergeJobResult'
        error:
          $ref: '#/components/schemas/DesignMergeError'
      required:
      - id
      - status
      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
    InsertPagesDesignMergeOperation:
      description: Inserts pages from a source design into the target design.
      properties:
        type:
          description: The type of merge operation.
          enum:
          - insert_pages
          example: insert_pages
          type: string
        source:
          $ref: '#/components/schemas/MergeSourceForInsertPagesOperation'
        after_page_number:
          description: 'Insert after this one-based page number in the evolving target layout. Use 0 to insert at the beginning, and the default is inserting at the end (append).

            '
          example: 2
          format: int32
          minimum: 0
          type: integer
      required:
      - source
      - type
      type: object
    MergeSourceForInsertPagesOperation:
      discriminator:
        mapping:
          design: '#/components/schemas/DesignMergeSourceForInsertPagesOperation'
        propertyName: type
      oneOf:
      - $ref: '#/components/schemas/DesignMergeSourceForInsertPagesOperation'
    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
    DesignMergeOperation:
      discriminator:
        mapping:
          insert_pages: '#/components/schemas/InsertPagesDesignMergeOperation'
          move_pages: '#/components/schemas/MovePagesDesignMergeOperation'
          delete_pages: '#/components/schemas/DeletePagesDesignMergeOperation'
        propertyName: type
      oneOf:
      - $ref: '#/components/schemas/InsertPagesDesignMergeOperation'
      - $ref: '#/components/schemas/MovePagesDesignMergeOperation'
      - $ref: '#/components/schemas/DeletePagesDesignMergeOperation'
    Error:
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          description: A human-readable description of what went wrong.
          type: string
      required:
      - code
      - message
      type: object
    DesignMergeJobResult:
      properties:
        design:
          $ref: '#/components/schemas/DesignSummary'
      required:
      - design
      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
    DeletePagesDesignMergeOperation:
      description: Deletes pages from the target design.
      properties:
        type:
          description: The type of merge operation.
          enum:
          - delete_pages
          example: delete_pages
          type: string
        page_numbers:
          description: One-based numbers of the pages to delete (evaluated at the time this operation runs). Pages are deleted in reverse order to maintain page numbers.
          example:
          - 2
          - 4
          items:
            format: int32
            minimum: 1
            type: integer
          minItems: 1
          type: array
      required:
      - page_numbers
      - type
      type: object
    DesignMergeSourceForInsertPagesOperation:
      description: A design source from which pages are inserted.
      properties:
        type:
          description: The type of source to insert pages from.
          enum:
          - design
          example: design
          type: string
        design_id:
          description: The ID of the source design.
          example: DAFVztcvd9z
          pattern: ^[a-zA-Z0-9_-]{1,50}$
          type: string
        page_numbers:
          description: One-based page numbers to insert from the source design. If omitted, all pages from the design are inserted.
          example:
          - 1
          - 2
          items:
            format: int32
            minimum: 1
            type: integer
          minItems: 1
          type: array
      required:
      - design_id
      - type
      type: object
    DesignMergeJobStatus:
      enum:
      - in_progress
      - success
      - failed
      type: string
      x-enum-descriptions:
      - The merge job is still running.
      - The merge job completed successfully.
      - The merge job failed.
    GetDesignMergeJobResponse:
      properties:
        job:
          $ref: '#/components/schemas/DesignMergeJob'
      required:
      - job
      type: object
    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
    MovePagesDesignMergeOperation:
      description: Moves pages within the target design to a new position.
      properties:
        type:
          description: The type of merge operation.
          enum:
          - move_pages
          example: move_pages
          type: string
        from_page_numbers:
          description: One-based number of the pages to move (evaluated at the time this operation runs). Pages are moved in order.
          example:
          - 1
          - 3
          items:
            format: int32
            minimum: 1
            type: integer
          minItems: 1
          type: array
        to_after_page_number:
          description: 'Destination position: insert the moved pages after this one-based page number. Use 0 to move to the beginning.

            '
          example: 2
          format: int32
          minimum: 0
          type: integer
      required:
      - from_page_numbers
      - to_after_page_number
      - type
      type: object
    CreateDesignMergeJobRequest:
      discriminator:
        mapping:
          create_new_design: '#/components/schemas/NewDesignCreateDesignMergeJobRequest'
          modify_existing_design: '#/components/schemas/ModifyDesignCreateDesignMergeJobRequest'
        propertyName: type
      oneOf:
      - $ref: '#/components/schemas/NewDesignCreateDesignMergeJobRequest'
      - $ref: '#/components/schemas/ModifyDesignCreateDesignMergeJobRequest'
  examples:
    RequestTooLargeError:
      summary: Request too large
      value:
        code: bad_request_params
        message: The request size exceeds the maximum allowed limit. Try reducing the number of pages per request, using simpler page content, or splitting into multiple smaller operations.
    InvalidOperationError:
      summary: Invalid operation
      value:
        code: bad_request_params
        message: 'Invalid operation: {message}'
    OperationNotSupportedError:
      summary: Operation not supported
      value:
        code: bad_request_params
        message: '{message}'
    InvalidPageNumberError:
      summary: Invalid page number
      value:
        code: bad_request_params
        message: Page number {pageNumber} is out of range (design has {totalPages} pages)
    DesignForbiddenError:
      summary: Not allowed to access design
      value:
        code: permission_denied
        message: Not allowed to access design '{designId}'
    MergeJobNotFoundError:
      summary: Merge job not found
      value:
        code: not_found
        message: Merge job '{jobId}' not found
    UnauthorizedPrivateResourceError:
      summary: Unauthorized access to private resource
      value:
        code: permission_denied
        message: Source design contains private resources that you don't have access to.
    MergeJobForbiddenError:
      summary: Not allowed to access this merge job
      value:
        code: permission_denied
        message: Not allowed to access this merge job
    UnsupportedPageTypeError:
      summary: Unsupported page type
      value:
        code: bad_request_params
        message: 'Source design ''{designId}'' has unsupported page type: {pageType}. Only fixed pages are supported.'
    MergeDesignNotFoundError:
      summary: Design not found for merge operation
      value:
        code: not_found
        message: Design '{designId}' not found
    UnsupportedDocumentTypeError:
      summary: Unsupported document type
      value:
        code: bad_request_params
        message: 'Design ''{designId}'' has unsupported document type: {documentType}.'
    InvalidMergeJobTypeError:
      summary: Invalid merge job type
      value:
        code: invalid_request
        message: 'Invalid merge job type: {jobType}'
  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