---
title: "POST /v1/merges"
method: POST
path: "/v1/merges"
tags: ["merge"]
---

# POST /v1/merges

`POST /v1/merges`

<Warning>

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](https://www.canva.dev/docs/connect/versions/).
- Public integrations that use preview APIs will not pass the review process, and can't be made available to all Canva users.

</Warning>

Starts a new [asynchronous job](https://www.canva.dev/docs/connect/api-requests-responses/#asynchronous-job-endpoints) 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.

<Note>

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.

</Note>

<Note>

For more information on the workflow for using asynchronous jobs, see [API requests and responses](https://www.canva.dev/docs/connect/api-requests-responses/#asynchronous-job-endpoints). You can check the status and get the results of jobs created with this API using the [Get design merge job API](https://www.canva.dev/docs/connect/api-reference/merges/get-design-merge-job/).

</Note>

## Request body

- union
  - NewDesignCreateDesignMergeJobRequest — Creates a new design by inserting pages from other designs.
    - `type` 'create_new_design', required — The type of merge job to create.
    - `operations` DesignMergeOperation[], required — For this job type, only insert operations are supported.
      - union
        - InsertPagesDesignMergeOperation — Inserts pages from a source design into the target design.
          - `type` 'insert_pages', required — The type of merge operation.
          - `source` MergeSourceForInsertPagesOperation, required — A design source from which pages are inserted.
            - `type` 'design', required — The type of source to insert pages from.
            - `design_id` string, required — The ID of the source design.
            - `page_numbers` integer[] — One-based page numbers to insert from the source design. If omitted, all pages from the design are inserted.
          - `after_page_number` integer — 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).
        - MovePagesDesignMergeOperation — Moves pages within the target design to a new position.
          - `type` 'move_pages', required — The type of merge operation.
          - `from_page_numbers` integer[], required — One-based number of the pages to move (evaluated at the time this operation runs). Pages are moved in order.
          - `to_after_page_number` integer, required — Destination position: insert the moved pages after this one-based page number. Use 0 to move to the beginning.
        - DeletePagesDesignMergeOperation — Deletes pages from the target design.
          - `type` 'delete_pages', required — The type of merge operation.
          - `page_numbers` integer[], required — 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.
    - `title` string, required — Title for the new design.
  - ModifyDesignCreateDesignMergeJobRequest — Modifies an existing design by inserting, moving, or deleting pages.
    - `type` 'modify_existing_design', required — The type of merge job to create.
    - `design_id` string, required — The ID of the design to modify.
    - `operations` DesignMergeOperation[], required — Supports insert, move, and delete operations.
      - union
        - InsertPagesDesignMergeOperation — Inserts pages from a source design into the target design.
          - `type` 'insert_pages', required — The type of merge operation.
          - `source` MergeSourceForInsertPagesOperation, required — A design source from which pages are inserted.
            - `type` 'design', required — The type of source to insert pages from.
            - `design_id` string, required — The ID of the source design.
            - `page_numbers` integer[] — One-based page numbers to insert from the source design. If omitted, all pages from the design are inserted.
          - `after_page_number` integer — 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).
        - MovePagesDesignMergeOperation — Moves pages within the target design to a new position.
          - `type` 'move_pages', required — The type of merge operation.
          - `from_page_numbers` integer[], required — One-based number of the pages to move (evaluated at the time this operation runs). Pages are moved in order.
          - `to_after_page_number` integer, required — Destination position: insert the moved pages after this one-based page number. Use 0 to move to the beginning.
        - DeletePagesDesignMergeOperation — Deletes pages from the target design.
          - `type` 'delete_pages', required — The type of merge operation.
          - `page_numbers` integer[], required — 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.
    - `title` string — Optional new title for the design.

## Response `200`

OK

- CreateDesignMergeJobResponse
  - `job` DesignMergeJob, required — The details of a design merge job.
    - `id` string, required — The ID of the design merge job.
    - `status` 'in_progress' | 'success' | 'failed', required
    - `result` DesignMergeJobResult
      - `design` DesignSummary, required — Basic details about the design, such as the design's ID, title, and URL.
        - `id` string, required — The design ID.
        - `title` string — The design title.
        - `url` string — URL of the design.
        - `thumbnail` Thumbnail — A thumbnail image representing the object.
          - `width` integer, required — The width of the thumbnail image in pixels.
          - `height` integer, required — The height of the thumbnail image in pixels.
          - `url` string, required — 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.
        - `urls` DesignLinks, required — A temporary set of URLs for viewing or editing the design.
          - `edit_url` string, required — 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.
          - `view_url` string, required — 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.
        - `created_at` integer, required — When the design was created in Canva, as a Unix timestamp (in seconds since the Unix Epoch).
        - `updated_at` integer, required — When the design was last updated in Canva, as a Unix timestamp (in seconds since the Unix Epoch).
        - `page_count` integer — The total number of pages in the design. Some design types don't have pages (for example, Canva docs).
    - `error` DesignMergeError — If the merge job fails, this object provides details about the error.
      - `code` 'thumbnail_generation_error' | 'merge_error' | 'create_design_error' | 'modify_design_error', required
      - `message` string, required — A human-readable description of what went wrong.

## Other responses

- `400` — Bad Request
- `403` — Forbidden
- `404` — Not Found
- `413` — Request Entity Too Large
- `default` — Error Response

---

[API](https://skmtc.net/canva/apis/canva-connect-api.md) · [All operations](https://skmtc.net/canva/apis/canva-connect-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/canva/canva-connect-api/versions/499c392c7720/schema)