openapi: 3.0.1
info:
  title: Asset Export
  description: >
    Export asset metadata from a Canto DAM library as CSV (emailed once
    ready) or JSON (returned directly), library-wide, filtered, or scoped
    to a single album or folder.
  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 Export
    description: Export asset metadata as CSV or JSON.
paths:
  /export/metadata:
    post:
      tags:
        - Asset Export
      summary: Export Metadata
      operationId: post_v1_export_metadata
      description: >
        Exports library-wide metadata to a CSV file. An email notification
        with a download link is sent once the export completes -- by
        default to the API token user's own address; pass a different
        plain-text email address as the request body to send it elsewhere
        instead.
      requestBody:
        required: false
        content:
          text/plain:
            schema:
              type: string
              description: An email address to send the export to, instead of the token user's own address.
              example: someone@example.com
      responses:
        "200":
          description: The export was accepted; an email will follow once it's ready.
          content:
            text/plain:
              schema:
                type: string
              example: You will receive an email with the link to the CSV when complete.
        "400":
          description: The given email address was not valid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
              example:
                code: 2110
                message: Invalid input.
  /file/metadata:
    post:
      tags:
        - Asset Export
      summary: Export Metadata With Filter
      operationId: post_v1_file_metadata
      description: >
        Advanced metadata export: choose which columns to export and
        narrow the exported set with a filter, consistent with the Search
        / Filter API's filter semantics. Returns the result directly as
        JSON rather than emailing a CSV.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                filter:
                  type: object
                  properties:
                    lastModified:
                      type: string
                      description: Filter by last-modified time (Unix timestamp), consistent with Search / Filter.
                    uploadedTime:
                      type: string
                      description: Filter by upload time (Unix timestamp), consistent with Search / Filter.
                    limit:
                      type: integer
                      default: 100
                      description: Maximum number of items to return.
                    start:
                      type: integer
                      default: 0
                      description: Offset of the first item to return.
                columns:
                  type: array
                  description: 'The fields to export, e.g. ["Content ID", "File Name", "MD5", "Description"].'
                  items:
                    type: string
      responses:
        "200":
          description: The exported rows, one object per asset with the requested columns as keys.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties:
                    type: string
              example:
                - Description: ""
                  Content ID: <content-id>
                  File Name: 10012.jpg
                  MD5: <md5-hash>
  /album/{albumId}/export/metadata:
    post:
      tags:
        - Asset Export
      summary: Export Metadata of album
      operationId: post_v1_album_albumId_export_metadata
      description: >
        Exports the metadata of an album's contents to a CSV file. An
        email notification with a download link is sent once the export
        completes -- by default to the API token user's own address; pass
        a different plain-text email address as the request body to send
        it elsewhere instead.
      parameters:
        - name: albumId
          in: path
          required: true
          description: The specific album (or folder) id.
          schema:
            type: string
      requestBody:
        required: false
        content:
          text/plain:
            schema:
              type: string
              description: An email address to send the export to, instead of the token user's own address.
              example: someone@example.com
      responses:
        "200":
          description: The export was accepted; an email will follow once it's ready.
          content:
            text/plain:
              schema:
                type: string
              example: You will receive an email with the link to the CSV when complete.
  /folder/{folderId}/export/metadata:
    post:
      tags:
        - Asset Export
      summary: Export Metadata of folder
      operationId: post_v1_folder_folderId_export_metadata
      description: >
        Exports the metadata of a folder's contents to a CSV file. An
        email notification with a download link is sent once the export
        completes -- by default to the API token user's own address; pass
        a different plain-text email address as the request body to send
        it elsewhere instead.
      parameters:
        - name: folderId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: false
        content:
          text/plain:
            schema:
              type: string
              description: An email address to send the export to, instead of the token user's own address.
              example: someone@example.com
      responses:
        "200":
          description: The export was accepted; an email will follow once it's ready.
          content:
            text/plain:
              schema:
                type: string
              example: You will receive an email with the link to the CSV when complete.
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:
    error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string