---
openapi: 3.0.3
info:
  title: Braze REST API – Duplicate Canvases using the API
  description: |
    ## Prerequisites

    To use this endpoint, you must generate an API key with the `canvas.duplicate` permission.

    ## Rate limit

    This endpoint is limited to 100 API calls per minute.
  version: 1.0.0
  contact:
    name: Braze Support
    url: https://www.braze.com/docs/braze_support/
  license:
    name: Braze Documentation
    url: https://www.braze.com/docs/api/home/
servers:
  - url: https://rest.iad-01.braze.com
    description: US-01
  - url: https://rest.iad-02.braze.com
    description: US-02
  - url: https://rest.iad-03.braze.com
    description: US-03
  - url: https://rest.iad-04.braze.com
    description: US-04
  - url: https://rest.iad-05.braze.com
    description: US-05
  - url: https://rest.iad-06.braze.com
    description: US-06
  - url: https://rest.iad-07.braze.com
    description: US-07
  - url: https://rest.iad-08.braze.com
    description: US-08
  - url: https://rest.us-10.braze.com
    description: US-10
  - url: https://rest.fra-01.braze.eu
    description: EU-01
  - url: https://rest.fra-02.braze.eu
    description: EU-02
  - url: https://rest.au-01.braze.com
    description: AU-01
  - url: https://rest.id-01.braze.com
    description: ID-01
  - url: https://rest.jp-01.braze.com
    description: JP-01
  - url: https://rest.kr-01.braze.com
    description: KR-01
security:
- BearerAuth: []
paths:
  "/canvas/duplicate":
    post:
      summary: Duplicate Canvases using the API
      operationId: post_canvas_duplicate_post_duplicate_canvases
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DuplicateCanvasesRequest'
            examples:
              duplicate_canvas:
                summary: Duplicate a Canvas
                value:
                  canvas_id: canvas_identifier
                  name: Copy of my Canvas
                  description: Duplicated with the API
                  tag_names:
                    - example_tag
      responses:
        "202":
          description: |
            The request was accepted and the Canvas is duplicated asynchronously. No action needed.

            This endpoint returns a `202` status code, and the Canvas creation occurs asynchronously. You can use the [Security event download]({{site.baseurl}}/user_guide/administer/global/admin_settings/security_settings/#security-event-report) to see records of when Canvases were duplicated and by which API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DuplicateCanvasesResponse'
              examples:
                success:
                  summary: Duplication accepted
                  value:
                    message: success
        "400":
          description: |
            Bad request. To resolve it:

            - **The `canvas_id` is missing or isn't a valid Canvas API identifier:** Pass a valid `canvas_id`. Find it with the [Export Canvas list endpoint]({{site.baseurl}}/api/endpoints/export/canvas/get_canvases/).
            - **The `name` isn't a string, or is longer than 256 bytes:** Pass a `name` string of 256 bytes or fewer.
            - **The `description` isn't a string, or is longer than 250 characters:** Pass a `description` of 250 characters or fewer.
            - **The `tag_names` value isn't an array of strings:** Pass `tag_names` as an array of strings.
            - **A tag in `tag_names` doesn't exist in this workspace:** Create the tag first, or remove it from `tag_names`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_canvas_id:
                  summary: Missing or invalid canvas_id
                  value:
                    message: "'canvas_id' must be a string of the object api identifier"
                invalid_name:
                  summary: Invalid name
                  value:
                    message: "'name' must be a string no more than 256 bytes"
                invalid_description:
                  summary: Invalid description
                  value:
                    message: "'description' must be a string no longer than 250 characters"
                invalid_tag_names:
                  summary: tag_names isn't an array of strings
                  value:
                    message: "'tag_names' must be an array of strings"
                tag_does_not_exist:
                  summary: Tag doesn't exist
                  value:
                    message: "'tag_name' \"...\" does not exist"
        "401":
          description: |
            Unauthorized. The REST API key is missing, malformed, or sent to the wrong REST endpoint. Send the key as `Authorization: Bearer YOUR_REST_API_KEY` to the correct [REST endpoint]({{site.baseurl}}/api/basics/#endpoints). For more causes, see [Errors and responses]({{site.baseurl}}/api/errors/#fatal-errors).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_api_key:
                  summary: Invalid API key
                  value:
                    message: 'Invalid API key: YOUR_REST_API_KEY'
        "403":
          description: Access denied. The REST API key doesn't have the required permission. Use a REST API key that has the `canvas.duplicate` permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                access_denied:
                  summary: Missing permission
                  value:
                    message: Access Denied
        "429":
          description: |
            Rate limited. You exceeded the rate limit for this endpoint. Slow your request rate and retry with exponential backoff. See [API rate limits]({{site.baseurl}}/api/api_limits/).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        5XX:
          description: |
            Internal server error. An unexpected error occurred on the Braze server. Retry with exponential backoff. If the error persists, contact [Support]({{site.baseurl}}/braze_support/).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: REST API key
      description: |
        REST API keys are created in the Braze dashboard at **Settings → APIs and
        Identifiers → API Keys**. The key must include the `canvas.duplicate` permission.
        Pass the key as `Authorization: Bearer YOUR_REST_API_KEY`.
  schemas:
    DuplicateCanvasesRequest:
      title: Duplicate Canvas request
      type: object
      required: [canvas_id, name]
      properties:
        canvas_id:
          type: string
          description: The Canvas identifier. See [Canvas identifier](https://www.braze.com/docs/api/identifier_types/).
          example: canvas_identifier
        name:
          type: string
          description: The name of the resulting Canvas.
          example: Copy of my Canvas
        description:
          type: string
          maxLength: 250
          description: The description field for the resulting Canvas.
          example: Duplicated with the API
        tag_names:
          type: array
          items:
            type: string
          description: The tags for the resulting Canvas. These must be existing tags. If you add new tags in the request, they overwrite any tags that were on the original Canvas.
          example:
            - example_tag
    DuplicateCanvasesResponse:
      title: Duplicate Canvas response
      type: object
      properties:
        message:
          type: string
          description: Returns `success` when the request completes without errors.
          example: success
    ErrorResponse:
      title: Error
      type: object
      properties:
        message:
          type: string
          description: The error message describing why the request failed.
        errors:
          type: array
          description: Non-fatal errors encountered while processing the request. Data unaffected by these errors is still processed.
          items:
            type: object
            properties:
              type:
                type: string
                description: The error type.
