openapi: 3.0.1
info:
  title: Library Tree
  description: >
    Browse, search, and manage the folder/album hierarchy of a Canto DAM
    library: the full library tree or a sub-tree, folder and album detail,
    folder/album creation and renaming, "My Collections", and batch
    delete/restore of folders and albums.


    A folder can contain sub-folders and albums; an album can only contain
    content. Content can never be assigned directly to a folder, only to an
    album -- the last level of any structure is always an album.
  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: Library Tree
    description: Browse and manage the folder/album hierarchy.
paths:
  /folder/{folderId}:
    get:
      tags:
        - Library Tree
      summary: Search under a folder
      operationId: get_v1_folder_folderId
      description: >
        Lists everything under a specified folder, page by page, matching
        every sub-folder/album and its contents. Supports the same filter
        parameters as Search / Filter, scoped to the folder subtree.


        Use the literal value `__null__` to match assets with no value set
        in a field, or `__exists__` to match assets with any value set in a
        field.
      parameters:
        - name: folderId
          in: path
          required: true
          description: The id of the folder.
          schema:
            type: string
        - name: keyword
          in: query
          required: false
          schema:
            type: string
        - name: scheme
          in: query
          required: false
          description: image, video, audio, document, presentation, or other. Case sensitive. Supports OR combination.
          schema:
            type: string
        - name: tags
          in: query
          required: false
          schema:
            type: string
        - name: tagsLiteral
          in: query
          required: false
          schema:
            type: string
        - name: keywords
          in: query
          required: false
          schema:
            type: string
        - name: approval
          in: query
          required: false
          schema:
            type: string
        - name: owner
          in: query
          required: false
          schema:
            type: string
        - name: fileSize
          in: query
          required: false
          schema:
            type: string
        - name: created
          in: query
          required: false
          schema:
            type: string
        - name: createdTime
          in: query
          required: false
          schema:
            type: string
        - name: uploadedTime
          in: query
          required: false
          schema:
            type: string
        - name: lastModified
          in: query
          required: false
          schema:
            type: string
        - name: width
          in: query
          required: false
          schema:
            type: string
        - name: height
          in: query
          required: false
          schema:
            type: string
        - name: imageRangeOperation
          in: query
          required: false
          schema:
            type: string
            enum: [or, and]
            default: or
        - name: dimension
          in: query
          required: false
          schema:
            type: string
        - name: resolution
          in: query
          required: false
          schema:
            type: string
        - name: storageClass
          in: query
          required: false
          schema:
            type: string
            enum: [standard, freeze]
        - name: orientation
          in: query
          required: false
          schema:
            type: string
            enum: [landscape, portrait, square]
        - name: duration
          in: query
          required: false
          schema:
            type: string
        - name: pageNumber
          in: query
          required: false
          schema:
            type: string
        - name: searchInField
          in: query
          required: false
          schema:
            type: string
        - name: exactMatch
          in: query
          required: false
          schema:
            type: boolean
            default: false
        - name: operator
          in: query
          required: false
          schema:
            type: string
            enum: [and, or]
            default: and
        - name: sortBy
          in: query
          required: false
          schema:
            type: string
            enum: [name, time, scheme, owner, size]
            default: time
        - name: sortDirection
          in: query
          required: false
          schema:
            type: string
            enum: [ascending, descending]
            default: descending
        - name: start
          in: query
          required: false
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 100
      responses:
        "200":
          description: A page of matching assets under the folder, with search facets.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/search_result"
    put:
      tags:
        - Library Tree
      summary: Update folder name
      operationId: put_v1_folder_folderId
      description: Updates a folder's multi-language name information.
      parameters:
        - name: folderId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/locale_name"
      responses:
        "200":
          description: The literal text "success" on completion.
          content:
            text/plain:
              schema:
                type: string
              example: success
  /tree:
    get:
      tags:
        - Library Tree
      summary: Get full library tree view
      operationId: get_v1_tree
      description: >
        Returns the whole folder/album tree. Not paginated -- omitting
        `layer` returns the complete tree, including every folder and
        album.
      parameters:
        - name: sortBy
          in: query
          required: false
          schema:
            type: string
            enum: [name, time, scheme, owner, size]
            default: time
        - name: sortDirection
          in: query
          required: false
          schema:
            type: string
            enum: [ascending, descending]
        - name: layer
          in: query
          required: false
          description: Maximum depth of folder/album items to return. -1 (default) means no limit.
          schema:
            type: integer
            default: -1
      responses:
        "200":
          description: The folder/album tree.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/tree_result"
  /tree/{folderId}:
    get:
      tags:
        - Library Tree
      summary: Get sub tree view
      operationId: get_v1_tree_folderId
      description: >
        Returns the sub-tree under the specified folder: the folders and
        albums directly and recursively contained within it. Only folders
        can contain a folder or album -- don't pass an album id here.
      parameters:
        - name: folderId
          in: path
          required: true
          description: Parent folder id.
          schema:
            type: string
        - name: sortBy
          in: query
          required: false
          schema:
            type: string
            enum: [name, time, scheme, owner, size]
            default: time
        - name: sortDirection
          in: query
          required: false
          schema:
            type: string
            enum: [ascending, descending]
        - name: layer
          in: query
          required: false
          description: Maximum depth of folder/album items to return. -1 (default) means no limit.
          schema:
            type: integer
            default: -1
      responses:
        "200":
          description: The folder/album sub-tree.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/tree_result"
        "404":
          description: The folder does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
  /folder/{parentFolderId}/{folderName}:
    post:
      tags:
        - Library Tree
      summary: Create folder
      operationId: post_v1_folder_parentFolderId_folderName
      description: >
        Creates a folder under the specified parent folder, or at the
        library root if `parentFolderId` is empty. The request body is
        optional and only needed to set the folder name in multiple
        languages.
      parameters:
        - name: parentFolderId
          in: path
          required: true
          description: The id of the parent folder. Leave empty to create at the library root.
          schema:
            type: string
        - name: folderName
          in: path
          required: true
          description: >
            The name of the folder. Max length 80. Avoid \, /, :, *, ?, ",
            <, >, or | in the name.
          schema:
            type: string
        - name: description
          in: query
          required: false
          description: The description of the folder. Max length 400.
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/locale_name"
      responses:
        "200":
          description: The created folder.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/tree_node"
  /info/folder/{folderId}:
    get:
      tags:
        - Library Tree
      summary: Get folder detail info
      operationId: get_v1_info_folder_folderId
      description: Returns detail information for a specific folder.
      parameters:
        - name: folderId
          in: path
          required: true
          schema:
            type: string
        - name: extendedMultiLangInfo
          in: query
          required: false
          description: >
            If true, adds a multiLanguageData array with multi-language
            names to the response. If false, multiLanguageData is omitted.
          schema:
            type: boolean
            default: false
      responses:
        "200":
          description: The folder's detail information.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/folder_album_detail"
  /mycollections/{collectionId}:
    get:
      tags:
        - Library Tree
      summary: Get My Collection detail info
      operationId: get_v1_mycollections_collectionId
      description: Returns detail information for a My Collection (saved search/favorites).
      parameters:
        - name: collectionId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The contents of the collection, with search facets.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/search_result"
  /album/{parentFolderId}/{albumName}:
    post:
      tags:
        - Library Tree
      summary: Create album
      operationId: post_v1_album_parentFolderId_albumName
      description: >
        Creates an album under the specified parent folder, or at the
        library root if `parentFolderId` is empty. The request body is
        optional and only needed to set the album name in multiple
        languages.
      parameters:
        - name: parentFolderId
          in: path
          required: true
          description: The id of the parent folder. Leave empty to create at the library root.
          schema:
            type: string
        - name: albumName
          in: path
          required: true
          description: >
            The name of the album. Max length 80. Avoid \, /, :, *, ?, ",
            <, >, or | in the name.
          schema:
            type: string
        - name: description
          in: query
          required: false
          description: The description of the album. Max length 400.
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/locale_name"
      responses:
        "200":
          description: The created album.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/tree_node"
        "404":
          description: The parent folder does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
  /info/album/{albumId}:
    get:
      tags:
        - Library Tree
      summary: Get album detail info
      operationId: get_v1_info_album_albumId
      description: Returns detail information for a specific album.
      parameters:
        - name: albumId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The album's detail information.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/folder_album_detail"
  /album/{albumId}:
    put:
      tags:
        - Library Tree
      summary: Update album name
      operationId: put_v1_album_albumId
      description: Updates an album's multi-language name information.
      parameters:
        - name: albumId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/locale_name"
      responses:
        "200":
          description: The literal text "success" on completion.
          content:
            text/plain:
              schema:
                type: string
              example: success
    get:
      tags:
        - Library Tree
      summary: List content of a specified album
      operationId: get_v1_album_albumId
      description: >
        Lists the content of an album, page by page, with brief content
        info only. Pass `Unassigned` as albumId to list every asset not
        assigned to any album. Supports the same filter parameters as
        Search / Filter, scoped to the album.
      parameters:
        - name: albumId
          in: path
          required: true
          description: The id of the album, or "Unassigned" for assets not assigned to any album.
          schema:
            type: string
        - name: keyword
          in: query
          required: false
          schema:
            type: string
        - name: scheme
          in: query
          required: false
          schema:
            type: string
        - name: tags
          in: query
          required: false
          schema:
            type: string
        - name: tagsLiteral
          in: query
          required: false
          schema:
            type: string
        - name: keywords
          in: query
          required: false
          schema:
            type: string
        - name: approval
          in: query
          required: false
          schema:
            type: string
        - name: owner
          in: query
          required: false
          schema:
            type: string
        - name: fileSize
          in: query
          required: false
          schema:
            type: string
        - name: created
          in: query
          required: false
          schema:
            type: string
        - name: createdTime
          in: query
          required: false
          schema:
            type: string
        - name: uploadedTime
          in: query
          required: false
          schema:
            type: string
        - name: lastModified
          in: query
          required: false
          schema:
            type: string
        - name: dimension
          in: query
          required: false
          schema:
            type: string
        - name: resolution
          in: query
          required: false
          schema:
            type: string
        - name: orientation
          in: query
          required: false
          schema:
            type: string
            enum: [landscape, portrait, square]
        - name: duration
          in: query
          required: false
          schema:
            type: string
        - name: pageNumber
          in: query
          required: false
          schema:
            type: string
        - name: storageClass
          in: query
          required: false
          schema:
            type: string
            enum: [standard, freeze]
        - name: searchInField
          in: query
          required: false
          schema:
            type: string
        - name: exactMatch
          in: query
          required: false
          schema:
            type: boolean
            default: false
        - name: operator
          in: query
          required: false
          schema:
            type: string
            enum: [and, or]
            default: and
        - name: sortBy
          in: query
          required: false
          schema:
            type: string
            enum: [name, time, scheme, owner, size]
            default: time
        - name: sortDirection
          in: query
          required: false
          schema:
            type: string
            enum: [ascending, descending]
        - name: start
          in: query
          required: false
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 100
      responses:
        "200":
          description: A page of the album's content, with search facets.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/search_result"
  /mycollections:
    get:
      tags:
        - Library Tree
      summary: List My Collections
      operationId: get_v1_mycollections
      description: Lists the current user's My Collections (saved searches/favorites).
      parameters:
        - name: orderBy
          in: query
          required: false
          schema:
            type: string
            enum: [name, time, type, owner, size]
            default: time
        - name: sortDirection
          in: query
          required: false
          schema:
            type: string
            enum: [ascending, descending]
      responses:
        "200":
          description: The current user's My Collections.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/my_collections_result"
  /batch/folder:
    delete:
      tags:
        - Library Tree
      summary: Batch delete Folder/Album to trash bin
      operationId: delete_v1_batch_folder
      description: Moves a batch of folders and/or albums to the trash bin.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/folder_or_album_ref"
      responses:
        "200":
          description: The delete outcome, including any ids that could not be deleted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/batch_delete_result"
  /batch/folder/permanent:
    delete:
      tags:
        - Library Tree
      summary: Batch Permanently delete the Folder/Album
      operationId: delete_v1_batch_folder_permanent
      description: Permanently deletes a batch of folders and/or albums from the trash bin.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/folder_or_album_ref"
      responses:
        "200":
          description: The delete outcome, including any ids that could not be deleted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/batch_delete_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:
    locale_name:
      type: object
      required: [localeCode, name]
      properties:
        localeCode:
          type: string
          description: 'A locale code, e.g. de-DE or en-US.'
        name:
          type: string
        description:
          type: string
    folder_or_album_ref:
      type: object
      required: [id, scheme]
      properties:
        id:
          type: string
          description: The id of the folder or album.
        scheme:
          type: string
          enum: [folder, album]
    tree_node:
      type: object
      description: >
        One node of the library tree: a folder or album, with folders
        recursively nesting their children.
      properties:
        id:
          type: string
        scheme:
          type: string
          enum: [folder, album]
        name:
          type: string
        namePath:
          type: string
        idPath:
          type: string
        size:
          type: string
        owner:
          type: string
        ownerName:
          type: string
        created:
          type: string
        time:
          type: string
        width:
          type: string
        height:
          type: string
        dpi:
          type: string
        url:
          type: object
          properties:
            preview:
              type: string
            detail:
              type: string
        children:
          type: array
          description: Present on a folder node; contains its direct child folders and albums.
          items:
            $ref: "#/components/schemas/tree_node"
    tree_result:
      type: object
      properties:
        sortBy:
          type: string
        sortDirection:
          type: string
        results:
          type: array
          items:
            $ref: "#/components/schemas/tree_node"
    folder_album_detail:
      type: object
      properties:
        id:
          type: string
        scheme:
          type: string
          enum: [folder, album]
        name:
          type: string
        namePath:
          type: string
        idPath:
          type: string
        description:
          type: string
        size:
          type: string
        owner:
          type: string
        created:
          type: string
        time:
          type: string
        width:
          type: string
        height:
          type: string
        dpi:
          type: string
        url:
          type: object
          properties:
            detail:
              type: string
        multiLanguageData:
          type: array
          description: Present only when extendedMultiLangInfo=true.
          items:
            type: object
            properties:
              localeCode:
                type: string
              name:
                type: string
              namePath:
                type: string
    my_collection_item:
      type: object
      properties:
        id:
          type: string
        scheme:
          type: string
          enum: [savedFavorites]
        name:
          type: string
        type:
          type: string
          description: 'e.g. "Personal".'
        syncFlag:
          type: string
        size:
          type: string
        owner:
          type: string
        width:
          type: string
        height:
          type: string
        dpi:
          type: string
        time:
          type: string
        url:
          type: object
          properties:
            detail:
              type: string
    my_collections_result:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: "#/components/schemas/my_collection_item"
        sortBy:
          type: string
        sortDirection:
          type: string
        found:
          type: integer
    batch_delete_result:
      type: object
      properties:
        status:
          type: string
          example: success
        permissionFail:
          type: array
          description: Ids that failed to delete because of missing permissions.
          items:
            type: string
        deleteFail:
          type: array
          description: Ids that failed to delete because of an error during deletion.
          items:
            type: string
    search_facet:
      type: object
      properties:
        name:
          type: string
        min:
          type: integer
        max:
          type: integer
        mix:
          type: integer
        value:
          type: array
          items:
            type: string
    search_result:
      type: object
      description: >
        Shared search/listing result shape (also used by the Assets
        catalog's Search / Filter and List the content of specified
        scheme).
      properties:
        facets:
          type: array
          items:
            $ref: "#/components/schemas/search_facet"
        limit:
          type: integer
        found:
          type: integer
        sortBy:
          type: string
        sortDirection:
          type: string
        results:
          type: array
          items:
            type: object
            additionalProperties: true
    error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string