openapi: 3.0.1 info: title: Asset Download description: > Download and preview assets in Canto's Digital Asset Management library: authenticated and unauthenticated direct URLs, converted renditions (JPG/PNG), original files, metadata XML, resize/crop/preset downloads, CloudFront URLs for embedded browsers that don't support redirects, batch ZIP downloads, and the download-preset and watermark lists that back them. version: 1.0.0 servers: - url: "https://{tenantSubdomain}.{region}" 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 Download description: Download, preview, and obtain rendition URLs for assets. paths: /direct/{scheme}/{contentId}/{hash}/original: get: tags: - Asset Download summary: Direct Url original operationId: get_direct_scheme_contentId_hash_original description: > Direct, unauthenticated URL to the original asset. The URL is only valid with the correct, randomly generated hash value -- it cannot be constructed from just the scheme and content id. Read the complete URL (including the hash) from the `url.directUrlOriginal` field returned by Get content details or Search / Filter. security: [] parameters: - name: scheme in: path required: true description: The scheme of the asset. schema: type: string enum: [image, video, audio, document, presentation, other] - name: contentId in: path required: true description: The id of the asset. schema: type: string - name: hash in: path required: true description: The random hash value from url.directUrlOriginal. schema: type: string - name: name in: query required: false description: > The file name to send in the response headers, so a browser downloads the file under this name. schema: type: string responses: "200": description: The original asset binary. /api_binary/v1/{scheme}/{contentId}/preview: get: tags: - Asset Download summary: Download Preview operationId: get_api_binary_v1_scheme_contentId_preview description: > Returns an image view of the content: the first page for document content, or a smaller-size image for image content. 240px by default (the longest side, when scaled down); use /preview/{dimension} to request a different size, capped at the account's configured maximum preview size. parameters: - name: scheme in: path required: true schema: type: string enum: [image, video, audio, document, presentation, other] - name: contentId in: path required: true schema: type: string responses: "200": description: > The preview image binary at the default 240px dimension. For `document`-scheme content, this returns an `image/png` page-preview thumbnail rather than JSON/XML. /api_binary/v1/{scheme}/{contentId}/preview/{dimension}: get: tags: - Asset Download summary: Download Preview (with dimension) operationId: get_api_binary_v1_scheme_contentId_preview_dimension description: > Same as Download Preview, but at the given dimension (the longest side, when scaled down) instead of the default 240px, capped at the account's configured maximum preview size. parameters: - name: scheme in: path required: true schema: type: string enum: [image, video, audio, document, presentation, other] - name: contentId in: path required: true schema: type: string - name: dimension in: path required: true description: The longest side, in pixels, of the returned preview. schema: type: integer responses: "200": description: The preview image binary at the given dimension. /direct/{scheme}/{contentId}/{hash}/m240/{dimension}: get: tags: - Asset Download summary: Direct Url preview operationId: get_direct_scheme_contentId_hash_m240_dimension description: > Direct, unauthenticated URL to a preview of the asset, requiring the random hash value read from `url.directUrlPreview`. Same dimension/scaling behavior as Download Preview. Supported scalings: 100, 240, 320, 500, 640, 800, 2000. security: [] parameters: - name: scheme in: path required: true schema: type: string enum: [image, video, audio, document, presentation, other] - name: contentId in: path required: true schema: type: string - name: hash in: path required: true description: The random hash value from url.directUrlPreview. schema: type: string - name: dimension in: path required: true description: The longest side, in pixels. Supported values 100, 240, 320, 500, 640, 800, 2000. schema: type: integer enum: [100, 240, 320, 500, 640, 800, 2000] responses: "200": description: The preview image binary. /api_binary/v1/{scheme}/{contentId}/HighJPG: get: tags: - Asset Download summary: Download as High JPG operationId: get_api_binary_v1_scheme_contentId_HighJPG description: > Downloads an image as a JPG in high quality. This operation is image-specific: calling it for a non-image scheme (e.g. `document`) does not return a JSON/XML error -- it returns a 200 with the web app's own HTML page as the body. Treat a `text/html` response as this operation not applying to the given content, not as success. parameters: - name: scheme in: path required: true schema: type: string enum: [image, video, audio, document, presentation, other] - name: contentId in: path required: true schema: type: string responses: "200": description: The high-quality JPG binary. /api_binary/v1/{scheme}/{contentId}/LowJPG: get: tags: - Asset Download summary: Download as Low JPG operationId: get_api_binary_v1_scheme_contentId_LowJPG description: > Downloads an image as a JPG in low quality (smaller file size). Same non-image-scheme caveat as Download as High JPG: a 200 with `text/html` means it didn't apply, not success. parameters: - name: scheme in: path required: true schema: type: string enum: [image, video, audio, document, presentation, other] - name: contentId in: path required: true schema: type: string responses: "200": description: The low-quality JPG binary. /api_binary/v1/{scheme}/{contentId}/PNG: get: tags: - Asset Download summary: Download as PNG operationId: get_api_binary_v1_scheme_contentId_PNG description: > Downloads an image as a PNG. Same non-image-scheme caveat as Download as High JPG: a 200 with `text/html` means it didn't apply, not success. parameters: - name: scheme in: path required: true schema: type: string enum: [image, video, audio, document, presentation, other] - name: contentId in: path required: true schema: type: string responses: "200": description: The PNG binary. /api_binary/v1/{scheme}/{contentId}/metadata: get: tags: - Asset Download summary: Download Metadata XML operationId: get_api_binary_v1_scheme_contentId_metadata description: > Downloads the XML metadata extracted from the original file. This has more detail than the metadata returned by Get content details and preserves the original data format, unlike the normalized fields on that endpoint. parameters: - name: scheme in: path required: true schema: type: string enum: [image, video, audio, document, presentation, other] - name: contentId in: path required: true schema: type: string responses: "200": description: The metadata XML file. content: application/xml: {} /api_binary/v1/{scheme}/{contentId}: get: tags: - Asset Download summary: Download original content file operationId: get_api_binary_v1_scheme_contentId description: Downloads the original content file. parameters: - name: scheme in: path required: true schema: type: string enum: [image, video, audio, document, presentation, other] - name: contentId in: path required: true schema: type: string responses: "200": description: The original file binary. /api_binary/v1/advance/image/{contentId}/download: get: tags: - Asset Download summary: Advanced Download Options operationId: get_api_binary_v1_advance_image_contentId_download description: > Downloads an image with resize, crop, and/or preset options applied. parameters: - name: contentId in: path required: true description: The id of the content. schema: type: string - name: resize in: query required: false description: 'Format: widthxheight.' schema: type: string - name: crop in: query required: false description: > Format: widthxheight+top+left. The + character must be URL encoded as %2B. schema: type: string - name: dpi in: query required: false description: The result image's DPI. schema: type: integer - name: type in: query required: false description: The result image type. schema: type: string enum: [jpg, png] - name: version in: query required: false description: The content version to render. If omitted, the latest version is used. schema: type: string - name: preset in: query required: false description: A preset id from Get Preset List. schema: type: string - name: proportion in: query required: false description: > true: do not adhere to the original proportions when resizing. false: adhere to the original proportions. schema: type: boolean default: true responses: "200": description: > The rendered image binary, resized/cropped per the query parameters. /api_binary/v1/{scheme}/{contentId}/previewURI: get: tags: - Asset Download summary: Obtain asset preview Cloudfront URL operationId: get_api_binary_v1_scheme_contentId_previewURI description: > Returns the CloudFront URL for a preview directly, without a redirect -- for embedded browsers that don't support redirect URLs. Use /previewURI/{dimension} to request a specific dimension. parameters: - name: scheme in: path required: true schema: type: string enum: [image, video, audio, document, presentation, other] - name: contentId in: path required: true description: Id of the content. schema: type: string responses: "200": description: The CloudFront preview URL, as plain text. content: text/plain: schema: type: string example: "https://.cloudfront.net/?response-content-disposition=inline&Expires=&Signature=&Key-Pair-Id=" /api_binary/v1/{scheme}/{contentId}/previewURI/{dimension}: get: tags: - Asset Download summary: Obtain asset preview Cloudfront URL (with dimension) operationId: get_api_binary_v1_scheme_contentId_previewURI_dimension description: > Same as Obtain asset preview Cloudfront URL, at the given dimension instead of the default. parameters: - name: scheme in: path required: true schema: type: string enum: [image, video, audio, document, presentation, other] - name: contentId in: path required: true description: Id of the content. schema: type: string - name: dimension in: path required: true schema: type: integer responses: "200": description: The CloudFront preview URL, as plain text. content: text/plain: schema: type: string example: "https://.cloudfront.net/?response-content-disposition=inline&Expires=&Signature=&Key-Pair-Id=" /api_binary/v1/{scheme}/{contentId}/directuri: get: tags: - Asset Download summary: Obtain asset download Cloudfront URL operationId: get_api_binary_v1_scheme_contentId_directuri description: > Returns the CloudFront URL for downloading the asset directly, without a redirect -- for embedded browsers that don't support redirect URLs. The URL expires after 1 day by default; use /directuri/{expireTimeInSeconds} to set a different expiration. parameters: - name: scheme in: path required: true schema: type: string enum: [image, video, audio, document, presentation, other] - name: contentId in: path required: true description: Id of the content. schema: type: string responses: "200": description: The CloudFront download URL, as plain text. content: text/plain: schema: type: string example: "https://.cloudfront.net/.?response-content-disposition=attachment&Expires=&Signature=&Key-Pair-Id=" /api_binary/v1/{scheme}/{contentId}/directuri/{expireTimeInSeconds}: get: tags: - Asset Download summary: Obtain asset download Cloudfront URL (with expiration) operationId: get_api_binary_v1_scheme_contentId_directuri_expireTimeInSeconds description: > Same as Obtain asset download Cloudfront URL, with an explicit expiration instead of the default 1 day (86400 seconds). parameters: - name: scheme in: path required: true schema: type: string enum: [image, video, audio, document, presentation, other] - name: contentId in: path required: true description: Id of the content. schema: type: string - name: expireTimeInSeconds in: path required: true description: When the URL should expire, in seconds. schema: type: integer responses: "200": description: The CloudFront download URL, as plain text. content: text/plain: schema: type: string example: "https://.cloudfront.net/.?response-content-disposition=attachment&Expires=&Signature=&Key-Pair-Id=" /api_binary/v1/batch/directuri: post: tags: - Asset Download summary: Batch Obtain asset download Cloudfront URL operationId: post_api_binary_v1_batch_directuri description: > Returns CloudFront download URLs for a batch of contents directly, without a redirect -- for embedded browsers that don't support redirect URLs. requestBody: required: true content: application/json: schema: type: array items: $ref: "#/components/schemas/content_ref" responses: "200": description: The CloudFront download URL for each requested content. content: application/json: schema: type: array items: $ref: "#/components/schemas/batch_directuri_item" /api/v1/batch/download: post: tags: - Asset Download summary: Batch Download operationId: post_v1_batch_download description: > Starts an asynchronous batch download of multiple assets as a single ZIP file, with resize/quality/color-mode conversion options. The result is emailed as a download link once processing completes -- to `userAddress` if given, otherwise to the calling token's account email. If `preset` is set, `resize` and `proportion` have no effect. requestBody: required: true content: application/json: schema: type: object required: [zipFileName, folderAlbumContents] properties: zipFileName: type: string description: The target ZIP file's name. folderAlbumContents: type: array description: 'Contents to include, as "scheme:id" strings.' items: type: string preset: type: string description: A preset id. If set, resize and proportion have no effect. quality: type: string description: The downloaded image quality, 1-100. type: type: string enum: [JPEG, PNG] description: Required if this is not an original-file download. colorMode: type: string enum: [RGB, CMYK] description: > Required if this is not an original-file download. When type is PNG, colorMode can only be RGB. resize: type: string description: 'Format: widthxheight.' proportion: type: boolean description: > false: resize proportionally to the image's own aspect ratio. true: force the exact size given by resize. userAddress: type: string description: > A valid email to notify when ready. If omitted, the current token user's default email is used. responses: "200": description: The batch download was accepted and queued. content: application/json: schema: $ref: "#/components/schemas/status_message" example: code: 200 message: We will send you an email with a link to download the files as soon as the files are processed. "413": description: The batch exceeds the 1000-file limit. content: application/json: schema: $ref: "#/components/schemas/status_message" example: code: 413 message: Bulk download file count is limited to 1000. "429": description: Another bulk download is already in progress for this tenant. content: application/json: schema: $ref: "#/components/schemas/status_message" example: code: 429 message: Another bulk download is being processed, please wait for it to finish and try again. /api/v1/tenant/download/presets: get: tags: - Asset Download summary: Get Preset List operationId: get_v1_tenant_download_presets description: > Returns the account's configured download presets. Retrieve this list before using a preset with Advanced Download Options or Batch Download. responses: "200": description: The account's download presets. content: application/json: schema: type: array items: $ref: "#/components/schemas/download_preset" /api/v1/tenant/watermark/presets: get: tags: - Asset Download summary: Get list of watermarks operationId: get_v1_tenant_watermark_presets description: > Returns the account's registered watermark presets. Watermarks are configured in the Canto UI under Settings > Configuration Options > Digital Rights Management. responses: "200": description: The account's watermark presets. content: application/json: schema: type: array items: $ref: "#/components/schemas/watermark_preset" 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: content_ref: type: object required: [id, scheme] properties: id: type: string scheme: type: string enum: [image, video, audio, document, presentation, other] batch_directuri_item: type: object properties: id: type: string scheme: type: string displayName: type: string preview: type: string directUri: type: string status_message: type: object properties: code: type: integer message: type: string download_preset: type: object properties: id: type: string description: The preset id, used as the preset parameter on Advanced Download Options and Batch Download. name: type: string description: type: string height: type: integer width: type: integer dpi: type: integer keepAspectRatio: type: boolean mainLibraryEnabled: type: boolean portalEnabled: type: boolean presizeEnabled: type: boolean cropEnabled: type: boolean scaleEnabled: type: boolean version: type: integer watermark_preset: type: object properties: id: type: string name: type: string description: type: string position: type: integer size: type: integer lastUploadTime: type: integer watermarkBase64: type: string nullable: true type: type: integer watermarkText: type: string nullable: true textColor: type: string nullable: true transparency: type: integer nullable: true rotate: type: integer nullable: true versionId: type: string