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 Resize API
  version: 2024-06-18
servers:
- description: Canva Connect API
  url: https://api.canva.com/rest
tags:
- name: resize
paths:
  /v1/resizes:
    post:
      description: "<Availability>\n\nTo use this API, your integration must act on behalf of a user that's on a Canva plan with premium features (such as Canva Pro).\n\nUsers on the Canva Free plan have access to a limited trial. For more information, see [Trial quotas](https://www.canva.dev/docs/connect/api-requests-responses/#trial-quotas).\n\n</Availability>\n\nStarts a new [asynchronous job](https://www.canva.dev/docs/connect/api-requests-responses/#asynchronous-job-endpoints)\nto create a resized copy of a design. The new resized design is\nadded to the top level of the user's\n[projects](https://www.canva.com/help/find-designs-and-folders/) (`root` folder).\n\nTo resize a design into a new design, you can either:\n\n  - Use a preset design type.\n  - Set height and width dimensions for a custom design.\n\nNote the following behaviors and restrictions when resizing designs:\n- Designs can be resized to a maximum area of 25,000,000 pixels squared.\n- Resizing designs using the Connect API always creates a new design. In-place resizing is currently not available in the Connect API, but can be done in the Canva UI.\n- Resizing a multi-page design results in all pages of the design being resized. Resizing a section of a design is only available in the Canva UI.\n- [Canva docs](https://www.canva.com/create/documents/) and [emails](https://www.canva.com/emails/) can't be resized, and other design types can't be resized to a Canva doc or email.\n- Canva Code designs can't be resized, and other design types can't be resized to a Canva Code design.\n\n<Note>\nFor more information on the workflow for using asynchronous jobs,\nsee [API requests and responses](https://www.canva.dev/docs/connect/api-requests-responses/#asynchronous-job-endpoints).\nYou can check the status and get the results of resize jobs created with this API using the\n[Get design resize job API](https://www.canva.dev/docs/connect/api-reference/resizes/get-design-resize-job/).\n</Note>"
      operationId: createDesignResizeJob
      requestBody:
        content:
          application/json:
            example:
              design_id: DAGirp_1ZUA
              design_type:
                type: custom
                width: 1000
                height: 1500
            schema:
              $ref: '#/components/schemas/CreateDesignResizeJobRequest'
      responses:
        '200':
          content:
            application/json:
              examples:
                in_progress:
                  $ref: '#/components/examples/InProgressResizeJobExample'
                success:
                  $ref: '#/components/examples/SuccessResizeJobExample'
                failed:
                  $ref: '#/components/examples/FailedResizeJobExample'
              schema:
                $ref: '#/components/schemas/CreateDesignResizeJobResponse'
          description: OK
        '400':
          content:
            application/json:
              examples:
                unsupported_design_type:
                  $ref: '#/components/examples/UnsupportedDesignTypeError'
                invalid_design_type:
                  $ref: '#/components/examples/InvalidDesignTypeError'
                invalid_design_type_input:
                  $ref: '#/components/examples/InvalidDesignTypeInputError'
                dimensions_below_minimum:
                  $ref: '#/components/examples/DimensionsBelowMinimumError'
                dimensions_above_maximum:
                  $ref: '#/components/examples/DimensionsAboveMaximumError'
                area_above_maximum:
                  $ref: '#/components/examples/AreaAboveMaximumError'
                design_not_resizable:
                  $ref: '#/components/examples/DesignNotResizableError'
                page_index_out_of_bounds:
                  $ref: '#/components/examples/PageIndexOutOfBoundsError'
                responsive_pages_not_supported:
                  $ref: '#/components/examples/ResponsivePagesNotSupportedError'
                controlled_pages_not_supported:
                  $ref: '#/components/examples/ControlledPagesNotSupportedError'
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request
        '403':
          content:
            application/json:
              examples:
                missing_resize_capability:
                  $ref: '#/components/examples/MissingResizeCapabilityError'
                design_resize_not_allowed:
                  $ref: '#/components/examples/DesignResizeNotAllowedError'
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden
        '404':
          content:
            application/json:
              examples:
                resize_design_not_found:
                  $ref: '#/components/examples/ResizeDesignNotFoundError'
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        '429':
          content:
            application/json:
              examples:
                feature_quota_exceeded:
                  $ref: '#/components/examples/FeatureQuotaExceededError'
              schema:
                $ref: '#/components/schemas/FeatureQuotaExceededError'
          description: Too Many Requests
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Error Response
      security:
      - oauthAuthCode:
        - design:content:read
        - design:content:write
      tags:
      - resize
      x-required-capabilities:
      - resize
      x-rate-limit-per-client-user: 20
  /v1/resizes/{jobId}:
    get:
      description: '<Availability>


        To use this API, your integration must act on behalf of a user that''s on a Canva plan with premium features (such as Canva Pro).


        Users on the Canva Free plan have access to a limited trial. For more information, see [Trial quotas](https://www.canva.dev/docs/connect/api-requests-responses/#trial-quotas).


        </Availability>


        Gets the result of a design resize job that was created using the [Create design resize

        job API](https://www.canva.dev/docs/connect/api-reference/resizes/create-design-resize-job/).


        If the job is successful, the response includes a summary of the new resized design, including its metadata.


        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](https://www.canva.dev/docs/connect/api-requests-responses/#asynchronous-job-endpoints).'
      operationId: getDesignResizeJob
      parameters:
      - description: The design resize job ID.
        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/InProgressResizeJobExample'
                success:
                  $ref: '#/components/examples/SuccessResizeJobExample'
                failed:
                  $ref: '#/components/examples/FailedResizeJobExample'
              schema:
                $ref: '#/components/schemas/GetDesignResizeJobResponse'
          description: OK
        '404':
          content:
            application/json:
              examples:
                resize_job_not_found:
                  $ref: '#/components/examples/ResizeJobNotFoundError'
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Error Response
      security:
      - oauthAuthCode:
        - design:content:read
        - design:content:write
      tags:
      - resize
      x-required-capabilities:
      - resize
      x-rate-limit-per-client-user: 120
components:
  schemas:
    FeatureQuotaExceededError:
      allOf:
      - $ref: '#/components/schemas/Error'
      - properties:
          upsell_url:
            description: URL to redirect users to upgrade their Canva account and reset their quota.
            type: string
        required:
        - upsell_url
        type: object
      description: Feature quota exceeded
    DesignResizeJob:
      description: Details about the design resize job.
      properties:
        id:
          description: The design resize job ID.
          example: bbd8dfcd-ead1-4871-81d5-962bfec82274
          type: string
        status:
          $ref: '#/components/schemas/DesignResizeStatus'
        result:
          $ref: '#/components/schemas/DesignResizeJobResult'
        error:
          $ref: '#/components/schemas/DesignResizeError'
      required:
      - id
      - status
      type: object
    TrialInformation:
      description: 'WARNING: Trials and trial information are a [preview feature](https://www.canva.dev/docs/connect/#preview-apis).

        There might be unannounced breaking changes to this feature which won''t produce a new API version.


        Trial information for non-qualifying users. Non-qualifying users have a limited number of

        resize uses. Once the trial is exhausted, users must upgrade to a Canva plan with premium

        features (such as Canva Pro) to continue using the Resize API.'
      properties:
        uses_remaining:
          description: The number of uses remaining in the free trial.
          example: 0
          format: int32
          minimum: 0
          type: integer
        upgrade_url:
          description: The URL for a user to upgrade their Canva account.
          example: https://www.canva.com/?tailoringUpsellDialog=GENERIC_C4W
          type: string
      required:
      - upgrade_url
      - uses_remaining
      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
    DesignResizeJobResult:
      description: 'Design has been created and saved to user''s root

        ([projects](https://www.canva.com/help/find-designs-and-folders/)) folder.'
      properties:
        design:
          $ref: '#/components/schemas/DesignSummary'
        trial_information:
          $ref: '#/components/schemas/TrialInformation'
      required:
      - design
      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
    CreateDesignResizeJobResponse:
      properties:
        job:
          $ref: '#/components/schemas/DesignResizeJob'
      required:
      - job
      type: object
    DesignTypeInput:
      description: The desired design type.
      discriminator:
        mapping:
          preset: '#/components/schemas/PresetDesignTypeInput'
          custom: '#/components/schemas/CustomDesignTypeInput'
        propertyName: type
      oneOf:
      - $ref: '#/components/schemas/PresetDesignTypeInput'
      - $ref: '#/components/schemas/CustomDesignTypeInput'
      type: object
    PresetDesignTypeInput:
      description: Provide the common design type.
      properties:
        type:
          enum:
          - preset
          type: string
        name:
          $ref: '#/components/schemas/PresetDesignTypeName'
      required:
      - name
      - type
      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
    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
    DesignResizeErrorCode:
      enum:
      - thumbnail_generation_error
      - design_resize_error
      - create_design_error
      - trial_quota_exceeded
      type: string
    GetDesignResizeJobResponse:
      properties:
        job:
          $ref: '#/components/schemas/DesignResizeJob'
      required:
      - job
      type: object
    DesignResizeError:
      description: If the design resize job fails, this object provides details about the error.
      properties:
        code:
          $ref: '#/components/schemas/DesignResizeErrorCode'
        message:
          description: A human-readable description of what went wrong.
          type: string
      required:
      - code
      - message
      type: object
    CustomDesignTypeInput:
      description: 'Provide the width and height to define a custom design type.


        Each dimension must be between 40 and 8000 pixels, and the

        total area (width × height) must not exceed 25,000,000 pixels

        squared. For example, a design with a width of 8000 pixels can

        have a maximum height of 3125 pixels.'
      properties:
        type:
          enum:
          - custom
          type: string
        width:
          description: The width of the design, in pixels.
          example: 320
          format: int32
          maximum: 8000
          minimum: 40
          type: integer
        height:
          description: The height of the design, in pixels.
          example: 200
          format: int32
          maximum: 8000
          minimum: 40
          type: integer
      required:
      - height
      - type
      - width
      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
    DesignResizeStatus:
      description: Status of the design resize job.
      enum:
      - in_progress
      - success
      - failed
      example: success
      type: string
    CreateDesignResizeJobRequest:
      description: 'Body parameters for starting a resize job for a design.

        It must include a design ID, and one of the supported design type.'
      properties:
        design_id:
          description: The design ID.
          type: string
        design_type:
          $ref: '#/components/schemas/DesignTypeInput'
      required:
      - design_id
      - design_type
      type: object
    PresetDesignTypeName:
      description: The name of the design type.
      enum:
      - doc
      - email
      - presentation
      - whiteboard
      type: string
      x-enum-descriptions:
      - A [Canva doc](https://www.canva.com/docs/); a document for Canva's online text editor.
      - An [email](https://www.canva.com/emails/); for creating email campaign designs.
      - A [presentation](https://www.canva.com/presentations/); lets you create and collaborate for presenting to an audience.
      - A [whiteboard](https://www.canva.com/online-whiteboard/); a design which gives you infinite space to collaborate.
  examples:
    AreaAboveMaximumError:
      summary: The requested dimensions exceed the maximum design area
      value:
        code: invalid_request
        message: width and height is above the maximum allowed area for a design
    ControlledPagesNotSupportedError:
      summary: Controlled pages can't be resized
      value:
        code: bad_request_params
        message: Controlled type pages are not supported to Magic Resize
    DimensionsBelowMinimumError:
      summary: The requested dimensions are below the minimum size
      value:
        code: invalid_request
        message: width or height cannot be less than {minDimension}px
    SuccessResizeJobExample:
      summary: Successfully completed job
      value:
        job:
          id: 450a76e7-f96f-43ae-9c37-0e1ce492ac72
          status: success
          result:
            design:
              id: DAGirp_1ZUA
              title: My summer holiday
              thumbnail:
                width: 595
                height: 335
                url: https://document-export.canva.com/Vczz9/zF9vzVtdADc/2/thumbnail/0001.png?<query-string>
              urls:
                edit_url: https://www.canva.com/design/DAGhRehVa2c/0L_1s4UXSpZhls8EtPaRKw/edit
                view_url: https://www.canva.com/design/DAGhRehVa2c/0L_1s4UXSpZhls8EtPaRKw/view
              created_at: 1742856750
              updated_at: 1742856752
              page_count: 5
            trial_information:
              uses_remaining: 0
              upgrade_url: https://www.canva.com/?tailoringUpsellDialog=GENERIC_C4W
    UnsupportedDesignTypeError:
      summary: Unsupported design type
      value:
        code: bad_request_params
        message: 'Canva designs can''t be resized to the selected design type: `{designTypeName}`'
    FeatureQuotaExceededError:
      summary: Feature quota exceeded
      value:
        code: quota_exceeded
        message: Free resize quota has been exceeded. Present the `upsell_url` to the user and prompt them to upgrade their Canva account to continue using the resize feature.
        upsell_url: '{upsellUrl}'
    ResponsivePagesNotSupportedError:
      summary: Responsive pages can't be resized
      value:
        code: bad_request_params
        message: Responsive type pages are not supported to Magic Resize
    DesignNotResizableError:
      summary: The design can't be resized to the desired type
      value:
        code: bad_request_params
        message: The Canva design provided can't be resized to the desired type
    ResizeJobNotFoundError:
      summary: The design resize job was not found
      value:
        code: not_found
        message: Job {jobId} not found
    InvalidDesignTypeError:
      summary: The requested preset design type is not available.
      value:
        code: bad_request_body
        message: Design type '{name}' is invalid.
    PageIndexOutOfBoundsError:
      summary: The page number is out of bounds
      value:
        code: bad_request_params
        message: The page number provided is out of bounds.
    MissingResizeCapabilityError:
      summary: The user's plan does not include the resize feature
      value:
        code: permission_denied
        message: Not allowed to access createDesignResizeJob, requires one of capabilities [resize].
    FailedResizeJobExample:
      summary: Failed job
      value:
        job:
          id: 450a76e7-f96f-43ae-9c37-0e1ce492ac72
          status: failed
          error:
            code: design_resize_error
            message: Failed to resize the design
    InvalidDesignTypeInputError:
      summary: The design type must be custom or preset
      value:
        code: bad_request_params
        message: Invalid design type provided. Design type must be one of custom or preset, but was {designType}
    DesignResizeNotAllowedError:
      summary: Not allowed to resize the design
      value:
        code: permission_denied
        message: Not allowed to resize document with ID {designId}
    ResizeDesignNotFoundError:
      summary: The design to resize was not found
      value:
        code: design_not_found
        message: Design with id '{designId}' not found
    DimensionsAboveMaximumError:
      summary: The requested dimensions are above the maximum size
      value:
        code: invalid_request
        message: width or height cannot be more than {maxDimension}px
    InProgressResizeJobExample:
      summary: In progress job
      value:
        job:
          id: 450a76e7-f96f-43ae-9c37-0e1ce492ac72
          status: in_progress
  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