openapi: 3.0.1
info:
  title: Asset Upload
  description: >
    Upload assets into a Canto DAM library, track upload status, import CSV
    metadata, create shareable upload links, and import assets submitted
    through an upload link.


    Uploading a file is a two-step process: call Get upload setting to
    obtain a one-time S3 upload policy (valid for 5 hours), then POST the
    file as multipart/form-data directly to the S3 URL the settings
    response provides -- not to this API's own host. Max upload size is 5
    GB.
  version: 1.0.0
servers:
  - url: "https://{tenantSubdomain}.{region}/api/v1"
    variables:
      tenantSubdomain:
        default: demo
      region:
        default: canto.com
        enum:
          - canto.com
          - canto.global
          - canto.de
          - au.canto.com
          - ca.canto.com
security:
  - cantoOAuth2: []
  - bearerAuth: []
tags:
  - name: Asset Upload
    description: Upload assets, track status, and import metadata or upload-link submissions.
paths:
  /upload/setting:
    get:
      tags:
        - Asset Upload
      summary: Get upload setting
      operationId: get_v1_upload_setting
      description: >
        Returns a one-time S3 upload policy: the destination `url` to POST
        the file to, plus the form fields (`key`, `acl`,
        `AWSAccessKeyId`, `Policy`, `Signature`, and the `x-amz-meta-*`
        fields) required by Upload file. The setting is valid for 5 hours;
        call this again after that to continue uploading.
      responses:
        "200":
          description: A one-time S3 upload policy.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/upload_setting"
              example:
                url: https://<upload-bucket>.s3-accelerate.amazonaws.com/
                key: <upload-key>/${filename}
                acl: private
                AWSAccessKeyId: <access-key-id>
                Policy: <base64-policy>
                Signature: <signature>
                x-amz-meta-file_name: "${filename}"
                x-amz-meta-tag: ""
                x-amz-meta-scheme: ""
                x-amz-meta-id: ""
                x-amz-meta-album_id: ""
  /upload-file:
    post:
      tags:
        - Asset Upload
      summary: Upload file
      operationId: post_upload_file
      description: >
        Uploads a file directly into the Canto S3 bucket. This request goes
        to the S3 `url` returned by Get upload setting -- an S3 host, not
        this API's own host -- so it is documented here as a standalone
        path for reference purposes rather than as a real path on the
        server above. Construct a multipart/form-data form (RFC 1867) from
        the retrieved upload setting.


        The form and policy must be UTF-8 encoded (via the HTML heading or
        a request header). The `file` field must be the last part of the
        request; only one file may be uploaded per request; use a distinct
        filename on every upload.


        This is the standard-region variant, and expects `key`, `acl`,
        `AWSAccessKeyId`, `Policy`, and `Signature` from the upload
        setting. See Upload file (.de and .ca.canto.com Environment) for
        the AWS SigV4 variant used on those regions.
      security: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [key, acl, AWSAccessKeyId, Policy, Signature, x-amz-meta-file_name, x-amz-meta-tag, x-amz-meta-scheme, x-amz-meta-id, x-amz-meta-album_id, file]
              properties:
                key:
                  type: string
                  description: The upload key from the upload settings.
                acl:
                  type: string
                  description: The uploadAcl value from the upload settings (usually "private").
                AWSAccessKeyId:
                  type: string
                  description: The uploadAWSAccessKeyId from the upload settings.
                Policy:
                  type: string
                  description: The Policy from the upload settings.
                Signature:
                  type: string
                  description: The Signature from the upload settings.
                x-amz-meta-file_name:
                  type: string
                  description: The name of the file, with extension.
                x-amz-meta-tag:
                  type: string
                  description: Reserved for future use. Leave empty.
                x-amz-meta-scheme:
                  type: string
                  description: >
                    To update an existing asset, the scheme of that asset.
                    Leave empty to upload a new asset. Returned by Query
                    upload status if set.
                x-amz-meta-id:
                  type: string
                  description: >
                    To update an existing asset, the id of that asset.
                    Leave empty to upload a new asset. Returned by Query
                    upload status if set.
                x-amz-meta-album_id:
                  type: string
                  description: >
                    To assign the asset to an existing album, that album's
                    id. Leave empty to leave the asset unassigned.
                x-amz-meta-refer_id:
                  type: string
                  description: >
                    Optional caller-defined tracking value, returned by
                    Query upload status if set. Requires refer=true on Get
                    upload setting.
                file:
                  type: string
                  format: binary
                  description: The file to upload. Must be the last part of the request.
      responses:
        "204":
          description: Uploaded successfully (a standard S3 POST-policy upload response, typically with an empty body).
  /upload-file-de-ca:
    post:
      tags:
        - Asset Upload
      summary: Upload file (.de and .ca.canto.com Environment)
      operationId: post_upload_file_de_ca
      description: >
        The .de and .ca.canto.com equivalent of Upload file, using AWS
        Signature Version 4 fields (`x-amz-date`, `x-amz-algorithm`,
        `x-amz-credential`, `x-amz-Signature`) instead of the standard
        `AWSAccessKeyId`/`Signature` pair. Like Upload file, this goes to
        the S3 `url` from Get upload setting, not this API's own host.
      security: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [key, acl, Policy, x-amz-meta-file_name, x-amz-meta-tag, x-amz-meta-scheme, x-amz-meta-id, x-amz-meta-album_id, x-amz-date, x-amz-algorithm, x-amz-credential, x-amz-Signature, file]
              properties:
                key:
                  type: string
                  description: The upload key from the upload settings.
                acl:
                  type: string
                  description: The uploadAcl value from the upload settings (usually "private").
                Policy:
                  type: string
                  description: The Policy from the upload settings.
                x-amz-meta-file_name:
                  type: string
                  description: The name of the file, with extension.
                x-amz-meta-tag:
                  type: string
                  description: Reserved for future use. Leave empty.
                x-amz-meta-scheme:
                  type: string
                  description: To update an existing asset, the scheme of that asset. Leave empty to upload a new asset.
                x-amz-meta-id:
                  type: string
                  description: To update an existing asset, the id of that asset. Leave empty to upload a new asset.
                x-amz-meta-album_id:
                  type: string
                  description: To assign the asset to an existing album, that album's id.
                x-amz-date:
                  type: string
                  description: From the upload settings.
                x-amz-algorithm:
                  type: string
                  description: The signing algorithm token from the upload settings.
                x-amz-credential:
                  type: string
                  description: The credential value from the upload settings.
                x-amz-Signature:
                  type: string
                  description: The signature value from the upload settings.
                x-amz-meta-refer_id:
                  type: string
                  description: Optional caller-defined tracking value, returned by Query upload status if set.
                file:
                  type: string
                  format: binary
                  description: The file to upload. Must be the last part of the request.
      responses:
        "204":
          description: Uploaded successfully (a standard S3 POST-policy upload response, typically with an empty body).
  /upload/status:
    get:
      tags:
        - Asset Upload
      summary: Query upload status
      operationId: get_v1_upload_status
      description: Queries the processing status of recently uploaded files.
      parameters:
        - name: hours
          in: query
          required: false
          description: How many hours back to look. 1-24.
          schema:
            type: integer
            default: 1
      responses:
        "200":
          description: The recent upload statuses.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/upload_status_result"
              examples:
                initial:
                  summary: Just submitted, not yet processed
                  value:
                    found: 1
                    results:
                      - name: canto-support@canto.com
                        time: "20210106155226000"
                        status: Initial
                processing:
                  summary: Currently being processed
                  value:
                    found: 1
                    results:
                      - name: myFile.jpg
                        time: "20210106160233861"
                        id: <content-id>
                        status: Processing
                done:
                  summary: Finished processing
                  value:
                    found: 1
                    results:
                      - scheme: image
                        name: myFile.jpg
                        time: "20210106160233861"
                        id: <content-id>
                        status: Done
                        referId: reference id
  /uploadlink:
    post:
      tags:
        - Asset Upload
      summary: Create Upload Links
      operationId: post_v1_uploadlink
      description: >
        Creates an upload link: a shareable page that lets external
        recipients submit files without a Canto account.


        `removeDuplicateType` controls duplicate handling when
        `allowDuplicateCheck` is true: 0 add as new file, 1 (default)
        don't import, 2 new version, 3 new version and append metadata, 5
        don't import and append metadata. `duplicateCheckMode` is 0 (MD5,
        default) or 1 (filename), also only written when
        `allowDuplicateCheck` is true.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [portalName, emailSubject, emailBody, isNeverExpired, recipients]
              properties:
                portalName:
                  type: string
                  description: Upload link name.
                description:
                  type: string
                emailSubject:
                  type: string
                  description: Email subject sent to the recipient.
                emailBody:
                  type: string
                  description: Email body sent to the recipient.
                isNeverExpired:
                  type: boolean
                displayExpireDate:
                  type: string
                  description: Required if isNeverExpired is false; not needed if true.
                recipients:
                  type: array
                  items:
                    type: object
                    required: [firstName, lastName, email]
                    properties:
                      firstName:
                        type: string
                      lastName:
                        type: string
                      email:
                        type: string
                importToAlbums:
                  type: array
                  description: Albums the imported assets will be assigned to.
                  items:
                    type: object
                    required: [albumId, pathWithName]
                    properties:
                      albumId:
                        type: string
                      pathWithName:
                        type: string
                        description: The full album path, including the album name.
                      portalId:
                        type: string
                      portalName:
                        type: string
                removeDuplicateType:
                  type: integer
                  enum: [0, 1, 2, 3, 5]
                  default: 1
                defaultApprovalStatus:
                  type: string
                  enum: [Approved, Restricted, Pending]
                  default: Approved
                removeDuplicateWhenImport:
                  type: boolean
                  default: false
                duplicateCheckMode:
                  type: integer
                  enum: [0, 1]
                  default: 0
                allowDuplicateCheck:
                  type: boolean
                  default: false
      responses:
        "200":
          description: The created upload link's id, as plain text.
          content:
            text/plain:
              schema:
                type: string
              example: "u-<upload-link-id>"
  /import/metadata:
    post:
      tags:
        - Asset Upload
      summary: Metadata Import
      operationId: post_v1_import_metadata
      description: Imports metadata for existing assets from a CSV file.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                isAppend:
                  type: boolean
                  default: false
                  description: If true, appends metadata; if false, replaces it.
                file:
                  type: string
                  format: binary
                  description: The CSV file to import metadata from.
      responses:
        "200":
          description: An import request id, as plain text, to poll via Metadata import progress.
          content:
            text/plain:
              schema:
                type: string
              example: "csvmeta-<import-id>"
  /import/metadata/progress:
    get:
      tags:
        - Asset Upload
      summary: Metadata import progress
      operationId: get_v1_import_metadata_progress
      description: Returns the progress of a metadata import started via Metadata Import.
      parameters:
        - name: request
          in: query
          required: true
          description: The import request id returned by Metadata Import.
          schema:
            type: string
      responses:
        "200":
          description: The import's progress.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/metadata_import_progress"
  /uploadlink/import:
    post:
      tags:
        - Asset Upload
      summary: Import from uploadlink
      operationId: post_uploadlink_import
      description: >
        Imports assets that were submitted through an upload link into the
        library. `option` controls duplicate handling: 0 add as new file, 1
        don't import, 5 don't import but append metadata (only takes
        effect when the tenant has duplicate-check dialog enabled).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [uploadLink, contents]
              properties:
                uploadLink:
                  type: string
                  description: The upload link id to import from.
                albumPath:
                  type: string
                  description: The id of the album to import into.
                contents:
                  type: array
                  items:
                    type: object
                    required: [id, scheme]
                    properties:
                      id:
                        type: string
                      displayName:
                        type: string
                      scheme:
                        type: string
                deleteAtOnce:
                  type: boolean
                  description: Whether to delete the submitted files from the upload link immediately after import.
                requestId:
                  type: number
                  description: A caller-supplied timestamp identifying this import request.
                metadata:
                  type: object
                  description: Metadata to append to imported contents when option=5.
                option:
                  type: integer
                  enum: [0, 1, 5]
                  default: 0
      responses:
        "200":
          description: The import outcome, split into success/fail/duplicate lists.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/uploadlink_import_result"
components:
  securitySchemes:
    cantoOAuth2:
      type: oauth2
      description: >
        Authorize against your own Canto account. Choose the tenant and its
        region in the portal first; the portal fills in the application
        identifier for that region and pre-fills your account name on
        Canto's sign-in page. This is a public-client PKCE flow: no client
        secret is used, and none is held by the portal.
      flows:
        authorizationCode:
          authorizationUrl: https://oauth.canto.com/oauth/api/oauth2/universal2/authorize
          tokenUrl: https://oauth.canto.com/oauth/api/oauth2/universal2/token
          scopes: {}
          x-usePkce: plain
          x-tokenName: accessToken
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: AccessToken
      description: >
        Paste a Target-API OAuth Token obtained out-of-band. Use the
        Authorize button instead to obtain one interactively.
  schemas:
    upload_setting:
      type: object
      properties:
        url:
          type: string
          description: The S3 destination URL to POST the upload form to.
        key:
          type: string
        acl:
          type: string
        AWSAccessKeyId:
          type: string
        Policy:
          type: string
        Signature:
          type: string
        x-amz-meta-file_name:
          type: string
        x-amz-meta-tag:
          type: string
        x-amz-meta-scheme:
          type: string
        x-amz-meta-id:
          type: string
        x-amz-meta-album_id:
          type: string
    upload_status_item:
      type: object
      properties:
        name:
          type: string
        time:
          type: string
        id:
          type: string
        scheme:
          type: string
        status:
          type: string
          enum: [Initial, Processing, Done]
        referId:
          type: string
    upload_status_result:
      type: object
      properties:
        found:
          type: integer
        results:
          type: array
          items:
            $ref: "#/components/schemas/upload_status_item"
    metadata_import_progress:
      type: object
      properties:
        status:
          type: integer
        total:
          type: integer
        finished:
          type: integer
        failed:
          type: integer
        notFound:
          type: integer
        unFinishedId:
          type: string
          nullable: true
        importTime:
          type: integer
        finishTime:
          type: integer
        fileName:
          type: string
          nullable: true
    uploadlink_import_file:
      type: object
      properties:
        id:
          type: string
        scheme:
          type: string
        displayName:
          type: string
          nullable: true
        portalId:
          type: string
          nullable: true
    uploadlink_import_result:
      type: object
      properties:
        portalId:
          type: string
          nullable: true
        portalName:
          type: string
          nullable: true
        portalShortName:
          type: string
          nullable: true
        successFiles:
          type: array
          items:
            $ref: "#/components/schemas/uploadlink_import_file"
        failFiles:
          type: array
          items:
            $ref: "#/components/schemas/uploadlink_import_file"
        duplicateFiles:
          type: array
          items:
            $ref: "#/components/schemas/uploadlink_import_file"
        duplicateDestFiles:
          type: array
          items:
            $ref: "#/components/schemas/uploadlink_import_file"
        versionKeys:
          type: array
          items:
            type: string