openapi: 3.0.1

################################################################################
# API Information                                                              #
################################################################################
info:
  title: Clowder
  description: Welcome to Clowder, a scalable data repository where you can share, organize and analyze data. This is a demo instance to try the system out. Please do not use this instance to store real data. We delete the content of this instance when we need to and it does not have very much disk space available. Thank you.
  version: "1.23.0"
  termsOfService: https://clowder.ncsa.illinois.edu/clowder/tos
  contact: 
    name: Clowder
    url: https://clowder.ncsa.illinois.edu/clowder/email

################################################################################
# Servers                                                                      #
################################################################################
servers:
- url: https://clowder.ncsa.illinois.edu/clowder/api

################################################################################
# Security                                                                     #
################################################################################
security:
  - login: []
  - apikey: []
  - key: []

################################################################################
# Tags                                                                         #
################################################################################
tags:
  - name: search
    description: The basic search endpoint allows searching across resources.
  - name: files
    description: A file is the raw bytes plus metadata.
  - name: folders
    description: A folder is a container of files and other folders
  - name: datasets
    description: A dataset is a container for files and metadata
  - name: collections
    description: Collections are groupings of datasets
  - name: spaces
    description: Spaces are groupings of collections and datasets.
  - name: extractions
    description: Extractions for Files.
  - name: thumbnails
    description: A thumbnail is the raw bytes plus metadata.
  - name: curations
    description: |
      A curation object is a request for publication that captures the state of
      a dataset ready for publication
  - name: logos
    description: Logos and other data used in Clowder that is customizable
  - name: metadata
    description: Metadata is the descrption or data of data
  - name: section
    description: Files section is a select part from image file, with a tag or comment
  - name: admin
    description: Server admin actions


################################################################################
# Parameters                                                                   #
################################################################################

################################################################################
# Paths                                                                        #
################################################################################
paths:

  ##############################################################################
  # Search                                                                     #
  ##############################################################################

  /search:
    get:
      tags:
        - search
      summary: Perform a basic search
      description: |
        Return files, datasets and/or collections matching query criteria. Search
        can be filtered by a specific resource ID, limited to tags or specific
        metadata fields.
      parameters:
        - name: query
          in: query
          description: String term to search for. Can include regular expressions using
            Elasticsearch syntax.
          schema:
            type: string
        - name: resource_type
          in: query
          description: Restrict search results to "file", "dataset", or "collection".
          schema:
            type: string
        - name: datasetid
          in: query
          description: Return only resources belonging to a specific dataset.
          schema:
            type: string
        - name: collectionid
          in: query
          description: Return only resources belonging to a specific collection.
          schema:
            type: string
        - name: spaceid
          in: query
          description: Return only resources belonging to a specific space.
          schema:
            type: string
        - name: folderid
          in: query
          description: Return only resources belonging to a specific folder.
          schema:
            type: string
        - name: field
          in: query
          description: Restrict search to a specific metadata field, e.g. "Alternative
            Title".
          schema:
            type: string
        - name: tag
          in: query
          description: Search for resources with a specific tag.
          schema:
            type: string
        - name: from
          in: query
          description: Starting index of first result; useful for pagination.
          schema:
            type: integer
        - name: size
          in: query
          description: Number of search results to include; useful for pagination.
          schema:
            type: integer
        - name: page
          in: query
          description: An alternative to "from" for pagination. Return the Nth page
            assuming "size" items per page.
          schema:
            type: integer
        - name: sort
          in: query
          description: A date or numeric field to sort by. If order is given but no field specified, created date is used.
          schema:
            type: string
        - name: order
          in: query
          description: Whether to scored in asc (ascending) or desc (descending) order. If a field is given without an order, asc is used.
          schema:
            type: string
            enum: [asc, desc]
            default: asc
      responses:
        200:
          description: OK
          content: {}

  ##############################################################################
  # Files                                                                      #
  ##############################################################################

  /files:
    get:
      tags:
        - files
      summary: List all files
      description: Returns list of files and descriptions.
      responses:
        '200':
          description: Successfully returns a list of files
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/File'
        '401':
          $ref: '#/components/responses/Disabled'

  /files/{id}:
    parameters:
      - $ref: '#/components/parameters/fileId'
    get:
      tags:
        - files
      summary: Download file
      description: |
        Can use Chunked transfer encoding if the HTTP header RANGE is set.
        This function will be reused to actually download the metadata of
        the file, please use /files/{id}/blob to get the actual bytes.
      responses:
        200:
          $ref: '#/components/responses/Blob'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
        - files
      summary: Delete file
      description: |
        Cascading action (removes file from any datasets containing it and
        deletes its previews, metadata and thumbnail).
      responses:
        200:
          description: OK
          content: {}
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

  /files/{id}/blob:
    get:
      tags:
        - files
      summary: Download file
      description: Can use Chunked transfer encoding if the HTTP header RANGE is set.
      parameters:
        - $ref: '#/components/parameters/fileId'
      responses:
        200:
          $ref: '#/components/responses/Blob'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

  /files/{id}/remove:
    post:
      tags:
        - files
      summary: Delete file
      description: use DELETE /files/{id} instead
      parameters:
        - $ref: '#/components/parameters/fileId'
      responses:
        200:
          description: OK
          content: {}
      deprecated: true

  /files/bulkRemove:
    post:
      tags:
        - files
      summary: Deletes files
      description: Deletes a list of files by fileIds
      responses:
        '200':
          description: Returns Status Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UUID'
        '401':
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

  /files/{id}/getPreviews:
    get:
      tags:
        - files
      summary: Get file previews
      description: |
        Return the currently existing previews of the selected file (full
        description, including paths to preview files, previewer names etc).
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /files/{id}/metadata:
    get:
      tags:
        - files
      summary: Retrieve physical file object metadata
      description: |
        Get information of the file object (not the resource it describes) as JSON.
        For example, size of file, date created, content type, filename.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successfully returns a list of files
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File'
        '401':
          $ref: '#/components/responses/Disabled'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags:
        - files
      summary: Add technical metadata to file
      description: |
        Metadata in attached JSON object will describe the file's described
        resource, not the file object itself.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
        required: false
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /files/{id}/sections:
    get:
      tags:
        - files
      summary: Get the sections of a file
      description: |
        Get the sections of a file.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UUID'
        404:
          $ref: '#/components/responses/NotFound'
      

  /files/{id}/paths:
    get:
      tags:
        - files
      summary: Get path to file in dataset
      description: |
        Return the path from the dataset down to the folder
        containing this file id.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /files/{id}/sendArchiveRequest:
    post:
      tags:
        - files
      summary: Submit this file to be archived
      description: |
        Submit this file to the queue to be archived.
        This requires RabbitMQ and a compatible archival extractor to be running.
        See https://github.com/clowder-framework/extractors-archival
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /files/{id}/archive:
    post:
      tags:
        - files
      summary: Changes a file's status to ARCHIVED
      description: |
        Callback that will change a file's status to ARCHIVED.
        This is used by archival extractors and is not typically used by clients.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /files/{id}/sendUnarchiveRequest:
    post:
      tags:
        - files
      summary: Submit this file to be unarchived
      description: |
        Submit this file to the queue to be unarchived.
        This requires RabbitMQ and a compatible archival extractor to be running.
        See https://github.com/clowder-framework/extractors-archival
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /files/{id}/unarchive:
    post:
      tags:
        - files
      summary: Changes a file's status back to PROCESSED
      description: |
        Callback that will change a file's status back to PROCESSED.
        This is used by archival extractors and is not typically used by clients.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'


  /files/{id}/extractions:
    post:
      tags:
        - files
        - extractions
      summary: Submit file for extraction by a specific extractor
      description: Extractions for Files.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                parameters:
                  type: array
                  items:
                    type: string
                extractor:
                  type: string
                  description: the extractor Id
              example:
                extractor: ncsa.image.metadata
        required: true
      responses:
        200:
          description: OK
          content: {}


  /files/{id}/extractions/{msg_id}:
    delete:
      tags:
        - files
        - extractions
      summary: Cancel a submitted file extraction.
      description: Extractions for file.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: msg_id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /uploadToDataset/{id}:
    post:
      tags:
        - files
        - datasets
      summary: Upload a file to a specific dataset
      description: |
        Uploads the file, then links it with the dataset. Returns file id as
        JSON object, or ids with filenames if multiple files are sent. ID can be
        used to work on the file using the API. Uploaded file can be an XML
        metadata file to be added to the dataset. If the optional Boolean
        parameter extract is set to false, it does not send the file for
        extraction. By default, Boolean parameter extract is set to true.
      parameters:
        - name: id
          in: path
          description: the dataset id
          required: true
          schema:
            type: string
        - name: showPreviews
          in: query
          description: default as "DatasetLevel"
          schema:
            type: string
        - name: originalZipFile
          in: query
          description: the UUID string of original zip file
          schema:
            type: string
        - name: flags
          in: query
          description: flags for previews
          schema:
            type: string
        - name: extract
          in: query
          schema:
            type: boolean
        - name: folder_id
          in: query
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
                - File
              properties:
                File:
                  type: string
                  description: |
                    The file to upload to the dataset. if no specific key is provided,
                    will attempt to upload every file. Otherwise, only upload the specific
                    key we were given (e.g. "File")
                  format: binary
        required: true
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /files/{id}/unfollow:
    post:
      tags:
        - files
      summary: Unfollow file
      description: |
        Remove user from file followers and remove file from user followed
        files.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /files/{id}/listpreviews:
    get:
      tags:
        - files
      summary: List file previews
      description: |
        Return the currently existing previews' basic characteristics (id,
        filename, content type) of the selected file.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /files/withFlags/{flags}:
    post:
      tags:
        - files
      summary: Upload file
      description: |
        Upload the attached file using multipart form enconding. Returns file id
        as JSON object, or ids with filenames if multiple files are sent. ID can
        be used to work on the file using the API. Uploaded file can be an XML
        metadata file.
      parameters:
        - name: flags
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /files/{id}/usermetadata:
    post:
      tags:
        - files
      summary: Add user-generated metadata to file
      description: |
        Metadata in attached JSON object will describe the file's described
        resource, not the file object itself.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
        required: true
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'
      x-codegen-request-body-name: metadata

  /files/getRDFURLsForFile/{id}:
    get:
      tags:
        - files
      summary: Get URLs of file's RDF metadata exports.
      description: |
        URLs of metadata files exported from XML (if the file was an XML
        metadata file) as well as the URL used to export the file's
        user-generated metadata as RDF.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /previews:
    post:
      tags:
        - files
        - previews
      summary: Upload a preview
      description: Upload a preview
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
                - File
              properties:
                File:
                  type: string
                  description: |
                    The preview to upload to the dataset. if no specific key is provided,
                    will attempt to upload every file. Otherwise, only upload the specific
                    key we were given (e.g. "File")
                  format: binary
      responses:
        200:
          description: OK
          content: {}

  /files/{id}/previews/{p_id}:
    post:
      tags:
        - files
      summary: Attach existing preview to file
      description: A file is the raw bytes plus metadata.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: p_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                extractor_id:
                  type: string
        required: false
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /files/{id}/isBeingProcessed:
    get:
      tags:
        - files
      summary: Is being processed
      description: Return whether a file is currently being processed by a preprocessor.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /files/{id}/reindex:
    post:
      tags:
        - files
      summary: Reindex a file
      description: Reindex the existing file.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /files/{id}/filename:
    put:
      tags:
        - files
      summary: Update a file name
      description: |
        Takes one argument, a UUID of the file. Request body takes a key-value
        pair for the name
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
        required: true
      responses:
        200:
          description: OK
          content: {}

  /files/{id}/updateMetadata:
    post:
      tags:
        - files
      summary: Update technical metadata of a file generated by a specific extractor
      description: |
        Metadata in attached JSON object will describe the file's described
        resource, not the file object itself. The method will search the entire
        techincal metadata array for the metadata generated by a specific
        extractor (using extractor_id provided as an argument) and if a match is
        found, it will update the corresponding metadata element.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: extractor_id
          in: query
          schema:
            type: string
      requestBody:
        description: json body that can be parsed as DBObject
        content:
          application/json:
            schema:
              type: object
        required: true
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'
      x-codegen-request-body-name: metadata

  /files/{id}/follow:
    post:
      tags:
        - files
      summary: Follow file
      description: Add user to file followers and add file to user followed files.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /files/{id}/metadata.jsonld:
    get:
      tags:
        - files
      summary: Retrieve metadata as JSON-LD
      description: Get metadata of the file object as JSON-LD.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: extractor
          in: query
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'
    post:
      tags:
        - files
      summary: Add JSON-LD metadata to the database.
      description: |
        Metadata in attached JSON-LD object will be added to metadata Mongo db
        collection.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JSONLD'
        required: true
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'
      x-codegen-request-body-name: matadata.jsonld
    delete:
      tags:
        - files
      summary: Remove JSON-LD metadata, filtered by extractor if necessary
      description: Remove JSON-LD metadata from file object
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: extractor
          in: query
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /files/metadata.jsonld:
    get:
      tags:
        - files
      summary: Retrieve metadata as JSON-LD for multiple files at once
      description: Use ?id=123&id=456&... to retrieve metadata for multiple files
        at once.
      parameters:
        - name: id
          in: query
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
    post:
      tags:
        - files
      summary: Add JSON-LD metadata to multiple files at once.
      description: |
        JSON object in post should have a list of file IDs under "files" key and metadata under "metadata" key.
        Metadata will be added to each file in metadata Mongo db collection.
      requestBody:
        description: the metadata to add and the file IDs to add it to
        content:
          application/json:
            schema:
              required:
                - files
                - metadata
              type: object
              properties:
                files:
                  type: array
                  items:
                    type: string
                metadata:
                  type: object
                  properties: {}
        required: false
      responses:
        200:
          description: OK
          content: {}
      x-codegen-request-body-name: contents

  /files/{id}/tags:
    get:
      tags:
        - files
      summary: Gets tags of a file
      description: Returns a list of strings, List[String].
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
    post:
      tags:
        - files
      summary: Adds tags to a file
      description: |
        Tag's (name, userId, extractor_id) tuple is used as a unique key. In
        other words, the same tag names but diff userId or extractor_id are
        considered as diff tags, so will be added.  The tags are expected as a
        list of strings: List[String].  An example is:<br>    curl -H
        'Content-Type: application/json' -d '{"tags":["namo", "amitabha"],
        "extractor_id": "curl"}'
        "http://localhost:9000/api/files/533c2389e4b02a14f0943356/tags?key=theKey"
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Tags'
        required: true
      responses:
        200:
          description: OK
          content: {}
    delete:
      tags:
        - files
      summary: Removes tags of a file
      description: |
        Tag's (name, userId, extractor_id) tuple is unique key. Same tag names
        but diff userId or extractor_id are considered diff tags. Tags can only
        be removed by the same user or extractor.  The tags are expected as a
        list of strings: List[String].
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /files/{id}/license:
    post:
      tags:
        - files
      summary: Update License information of a file
      description: |
        Takes four arguments, all Strings. licenseType, rightsHolder,
        licenseText, licenseUrl
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/License'
        required: true
      responses:
        200:
          description: OK
          content: {}

  /files/{id}/versus_metadata:
    get:
      tags:
        - files
      summary: Get Versus metadata of the resource described by the file
      description: A file is the raw bytes plus metadata.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /files/{id}/updateDescription:
    put:
      tags:
        - files
      summary: Update file description
      description: |
        Takes one argument, a UUID of the file. Request body takes key-value
        pair for the description
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              required:
                - description
              type: object
              properties:
                description:
                  type: string
        required: true
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'
      x-codegen-request-body-name: description

  /files/{id}/technicalmetadatajson:
    get:
      tags:
        - files
      summary: Get technical metadata of the resource described by the file
      description: A file is the raw bytes plus metadata.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /files/sendJob/{fileId}/{fileType}:
    post:
      tags:
        - files
      summary: (Re)send preprocessing job for file
      description: |
        Force Clowder to (re)send preprocessing job for selected file,
        processing the file as a file of the selected MIME type. Returns file id
        on success. In the requested file type, replace / with __ (two
        underscores).
      parameters:
        - name: fileId
          in: path
          required: true
          schema:
            type: string
        - name: fileType
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /files/{id}/xmlmetadatajson:
    get:
      tags:
        - files
      summary: |
        Get metadata of the resource described by the file that were input as
        XML
      description: A file is the raw bytes plus metadata.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /files/{id}/extracted_metadata:
    get:
      tags:
        - files
      summary: Provides metadata extracted for a file
      description: A file is the raw bytes plus metadata.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /files/{id}/comment:
    post:
      tags:
        - files
      summary: Add comment to file
      description: A file is the raw bytes plus metadata.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Comment'
        required: true
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'
      x-codegen-request-body-name: comment

  /files/{id}/tags/remove:
    post:
      tags:
        - files
      summary: Removes a tag from a file
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
      deprecated: true

  /files/{id}/tags/remove_all:
    post:
      tags:
        - files
      summary: Removes all tags of a file
      description: |
        This is a big hammer -- it does not check the userId or extractor_id and
        forcefully remove all tags for this file.  It is mainly intended for
        testing.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /fileThumbnail:
    post:
      tags:
        - files
      summary: Upload a thumbnail
      description: Upload a thumbnail.
      responses:
        200:
          description: OK
          content: {}
        400:
          $ref: '#/components/responses/BadRequest'

  /fileThumbnail/{id}/blob:
    post:
      tags:
        - files
      summary: Download a thumbnail
      description: Download a thumbnail.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'


  /files/{id}/thumbnails/{thumbnail_id}:
    post:
      tags:
        - files
      summary: Add thumbnail to file
      description: Attaches an already-existing thumbnail to a file.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: thumbnail_id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /files/{id}/metadataDefinitions:
    get:
      tags:
        - files
      summary: Get metadata definitions available for a file
      description: |
        The metadata definitions come from the spaces that the dataset the file
        is part of. Directly or within a folder
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /files/rdfUserMetadata/{id}:
    get:
      tags:
        - files
      summary: Get the user-generated metadata of the selected file in an RDF file
      description: A file is the raw bytes plus metadata.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /files/{id}/usermetadatajson:
    get:
      tags:
        - files
      summary: Get community-generated metadata of the resource described by the file
      description: A file is the raw bytes plus metadata.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /queries/{id}:
    get:
      tags:
        - files
      summary: Fetches and downloads a particular query
      description: Fetches and downloads a particular query.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'


  /queries/{file_id}/thumbnails/{thumbnail_id}:
    post:
      tags:
        - files
      summary: Add thumbnail to a query image
      description: Attaches an already-existing thumbnail to a query image.
      parameters:
        - name: file_id
          in: path
          required: true
          schema:
            type: string
        - name: thumbnail_id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

        ##############################################################################
        # Metadata                                                                   #
        ##############################################################################

  /metadata.jsonld/{id}:
    delete:
      tags:
        - metadata
      summary: Delete the metadata by id.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        400:
          description: Invalid Metadata
          content: {}

  /metadata/autocompletenames:
    get:
      tags:
        - metadata
      summary: Get set of metadata fields containing filter substring for autocomplete.
      parameters:
        - name: filter
          in: query
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /metadata/distinctdefinitions:
    get:
      tags:
        - metadata
      summary: Get Vocabulary definitions with distinct names.
      responses:
        200:
          description: OK
          content: {}

  /metadata/definitions:
    get:
      tags:
        - metadata
      summary: Get Vocabulary definitions.
      responses:
        200:
          description: OK
          content: {}

  /metadata/definitions/{id}:
    get:
      tags:
        - metadata
      summary: Get Vocabulary definitions by id.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}


  ##############################################################################
  # StandardVocabulary                                                         #
  ##############################################################################

  /standardvocab:
    get:
      tags:
        - metadata
      summary: List all Standard Vocabularies
      description: |
        Retrieve all Standard Vocabulary objects.
      responses:
        200:
          description: OK
          content: {}
        400:
          description: Bad request
          content: {}
        401:
          description: Not authorized
          content: {}
        403:
          description: Forbidden
          content: {}
    post:
      tags:
        - metadata
      summary: Create a new Standard Vocabulary
      description: |
        Requires that the request body contains a List[String] of terms.
      requestBody:
        description: The list of terms to add to this vocabulary.
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
        required: true
      responses:
        200:
          description: OK
          content: {}
        400:
          description: Bad request
          content: {}
        401:
          description: Not authorized
          content: {}
        403:
          description: Forbidden
          content: {}

  /standardvocab/{id}:
    get:
      tags:
        - metadata
      summary: Get a specific Standard Vocabulary
      description: |
        Lookup and return an existing Standard Vocabulary using its ID.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        400:
          description: Bad request
          content: {}
        401:
          description: Not authorized
          content: {}
        403:
          description: Forbidden
          content: {}
    put:
      tags:
        - metadata
      summary: Update a Standard Vocabulary
      description: |
        Requires that the request body contains a List[String] of terms.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        description: The list of terms to add to this vocabulary.
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
        required: true
      responses:
        200:
          description: OK
          content: {}
        400:
          description: Bad request
          content: {}
        401:
          description: Not authorized
          content: {}
        403:
          description: Forbidden
          content: {}
    delete:
      tags:
        - metadata
      summary: Delete a Standard Vocabulary
      description: |
        Lookup and remove a Standard Vocabulary using its ID.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /standardvocab/{id}/terms:
    get:
      tags:
        - metadata
      summary: Get the terms list of a specific Standard Vocabulary
      description: |
        Lookup and return the term list of an existing Standard Vocabulary
        using its ID.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        400:
          description: Bad request
          content: {}
        401:
          description: Not authorized
          content: {}
        403:
          description: Forbidden
          content: {}

  ##############################################################################
  # Folders                                                                    #
  ##############################################################################

  /datasets/{parentDatasetId}/newFolder:
    post:
      tags:
        - folders
      summary: Create a Folder
      description: |
        New empty folder. Requires the ID of the dataset within the folder will
        be created, and the parent information
      parameters:
        - name: parentDatasetId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                parentId:
                  type: string
                parentType:
                  type: string
                  enum:
                    - dataset
                    - folder
        required: true
      responses:
        200:
          description: OK
          content: {}


  /datasets/{parentDatasetId}/updateName/{folderId}:
    put:
      tags:
        - folders
      summary: Update folder name
      description: Updates a folder's name
      parameters:
        - name: parentDatasetId
          in: path
          required: true
          schema:
            type: string
        - name: folderId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
        required: true
      responses:
        200:
          description: OK
          content: {}


  /datasets/{parentDatasetId}/deleteFolder/{folderId}:
    delete:
      tags:
        - folders
      summary: Delete a folder
      description: Deletes all the files and folder within a folder and then deletes
        itself
      parameters:
        - name: parentDatasetId
          in: path
          required: true
          schema:
            type: string
        - name: folderId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  ##############################################################################
  # DATASETS ENDPOINTS                                                         #
  ##############################################################################
  /datasets:
    get:
      tags:
        - datasets
      summary: List all datasets the user can view
      description: This will check for Permission.ViewDataset
      parameters:
        - name: when
          in: query
          required: false
          schema:
            type: string
        - name: date
          in: query
          required: false
          schema:
            type: string
        - name: title
          in: query
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: The number of collections returns, default as 12.
          schema:
            type: integer
        - name: exact
          in: query
          schema:
            type: boolean
      responses:
        200:
          description: OK
          content: {}
    post:
      tags:
        - datasets
      summary: Create new dataset
      description: |
        New dataset containing one existing file, based on values of fields in
        attached JSON. Returns dataset id as JSON object.
      requestBody:
        content:
          application/json:
            schema:
              required:
                - file_id
                - name
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
                space:
                  type: string
                file_id:
                  type: string
        required: true
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /datasets/{id}:
    get:
      tags:
        - datasets
      summary: Get a specific dataset
      description: This will return a specific dataset requested
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
        - datasets
      summary: Delete dataset
      description: |
        Cascading action (deletes all previews and metadata of the dataset and
        all files existing only in the deleted dataset).
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'


  /datasets/{ds_id}/copyDatasetToSpace/{space_id}:
    post:
      tags:
        - datasets
      summary: |
        Copy the dataset, as well as the folders and files within the dataset
        into a space, return the new dataset id
      description: Check AddResourceToSpace permission.
      parameters:
        - name: ds_id
          in: path
          required: true
          schema:
            type: string
        - name: space_id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'


  /datasets/{ds_id}/files/{file_id}:
    post:
      tags:
        - datasets
      summary: Attach existing file to dataset
      description: |
        If the file is an XML metadata file, the metadata are added to the
        dataset.
      parameters:
        - name: ds_id
          in: path
          required: true
          schema:
            type: string
        - name: file_id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /datasets/{ds_id}/moveFile/{folder_id}/{file_id}:
    post:
      tags:
        - datasets
      summary: Move existing file to a new folder within the same dataset
      parameters:
        - name: ds_id
          in: path
          required: true
          schema:
            type: string
        - name: folder_id
          in: path
          description: destination folder id
          required: true
          schema:
            type: string
        - name: file_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                folderId:
                  type: string
                  description: old folder id
        required: true
      responses:
        200:
          description: OK
          content: {}

  /datasets/{ds_id}/moveToDataset/{folder_id}/{file_id}:
    post:
      tags:
        - datasets
      summary: Move existing file from the old folder to a new dataset
      parameters:
        - name: ds_id
          in: path
          required: true
          schema:
            type: string
        - name: folder_id
          in: path
          description: old folder id
          required: true
          schema:
            type: string
        - name: file_id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /datasets/{ds_id}/filesRemove/{file_id}/{ignoreNotFound}:
    post:
      tags:
        - datasets
      summary: Detach existing file from a dataset
      description: Check CreateDataset permission
      parameters:
        - name: ds_id
          in: path
          required: true
          schema:
            type: string
        - name: file_id
          in: path
          required: true
          schema:
            type: string
        - name: ignoreNotFound
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /datasets/{ds_id}/folders:
    get:
      tags:
        - datasets
      summary: list all folders in the dataset
      parameters:
        - name: ds_id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /datasets/{id}/tags/remove_all:
    post:
      tags:
        - datasets
      summary: Remove all tags of dataset
      description: |
        Forcefully remove all tags for this dataset.  It is mainly intended for
        testing.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /datasets/{ds_id}/extractions:
    post:
      tags:
        - extractions
      summary: Submit dataset for extraction by a specific extractor
      description: Extractions for dataset.
      parameters:
        - name: ds_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                parameters:
                  type: array
                  items:
                    type: string
                extractor:
                  type: string
                  description: the extractor Id
              example:
                extractor: ncsa.image.metadata
        required: true
      responses:
        200:
          description: OK
          content: {}

  /datasets/{ds_id}/extractions/{msg_id}:
    delete:
      tags:
        - extractions
      summary: Cancel a submitted dataset extraction.
      description: Extractions for dataset.
      parameters:
        - name: ds_id
          in: path
          required: true
          schema:
            type: string
        - name: msg_id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /datasets/{id}/tags:
    get:
      tags:
        - datasets
      summary: Get the tags associated with this dataset
      description: Returns a JSON object of multiple fields
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
    post:
      tags:
        - datasets
      summary: Add tags to dataset
      description: |
        Requires that the request body contains a 'tags' field of List[String]
        type.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Tags'
        required: true
      responses:
        200:
          description: OK
          content: {}
    delete:
      tags:
        - datasets
      summary: Remove tags of dataset
      description: |
        Requires that the request body contains a 'tags' field of List[String]
        type.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /datasets/{id}/addFileEvent:
    post:
      tags:
        - datasets
      summary: Insert add_file Event
      description: Insert an Event into the Events Collection
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: inFolder
          in: query
          description: if the file is add directly to the dataset or add to a folder
          required: true
          schema:
            type: boolean
        - name: fileCount
          in: query
          required: true
          schema:
            type: number
      responses:
        200:
          description: OK
          content: {}

  /datasets/{id}/isBeingProcessed:
    get:
      tags:
        - datasets
      summary: Is being processed
      description: Return whether a dataset is currently being processed by a preprocessor.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /datasets/createempty:
    post:
      tags:
        - datasets
      summary: Create new dataset with no file
      description: |
        New dataset requiring zero files based on values of fields in attached
        JSON. Returns dataset id as JSON object. Requires name, description, and
        space. Optional list of existing file ids to add.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Dataset'
        required: true
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'
      x-codegen-request-body-name: dataset

  /datasets/{id}/description:
    put:
      tags:
        - datasets
      summary: Update dataset description.
      description: |
        Takes one argument, a UUID of the dataset. Request body takes key-value
        pair for description.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              required:
                - description
              type: object
              properties:
                description:
                  type: string
        required: true
      responses:
        200:
          description: OK
          content: {}
      x-codegen-request-body-name: description

  /datasets/{id}/usermetadata:
    post:
      tags:
        - datasets
      summary: Add user-generated metadata to dataset
      description: A dataset is a container for files and metadata
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
        required: false
      responses:
        200:
          description: OK
          content: {}
      x-codegen-request-body-name: metadata

  /datasets/{id}/technicalmetadatajson:
    get:
      tags:
        - datasets
      summary: List extractors generated metadata of a dataset
      description: A dataset is a container for files and metadata
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /datasets/{id}/usermetadatajson:
    get:
      tags:
        - datasets
      summary: Get community-generated metadata of the resource described by the dataset
      description: A dataset is a container for files and metadata
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /datasets/{id}/xmlmetadatajson:
    get:
      tags:
        - datasets
      summary: |
        Get metadata of the resource described by the dataset that were input as
        XML
      description: A dataset is a container for files and metadata
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /datasets/{ds_id}/{file_id}:
    delete:
      tags:
        - datasets
      summary: Detach file from dataset
      description: |
        File is not deleted, only separated from the selected dataset. If the
        file is an XML metadata file, the metadata are removed from the dataset.
      parameters:
        - name: ds_id
          in: path
          required: true
          schema:
            type: string
        - name: file_id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /datasets/{id}/comment:
    post:
      tags:
        - datasets
      summary: Add comment to dataset
      description: A dataset is a container for files and metadata
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Comment'
        required: true
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'
      x-codegen-request-body-name: comment

  /datasets/{id}/user:
    get:
      tags:
        - datasets
      summary: List all users in the spaces that contain this dataset in json-ld format
      description: A dataset is a container for files and metadata
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /datasets/{id}/metadata:
    get:
      tags:
        - datasets
      summary: |
        Retrieve available metadata definitions for a dataset. It is an
        aggregation of the metadata that a space belongs to.
      description: A dataset is a container for files and metadata
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'
    post:
      tags:
        - datasets
      summary: Add metadata to dataset
      description: |
        The extractor is set as "http://clowder.ncsa.illinois.edu/extractors/deprecatedapi",
        contextURL and contextID as None.
        Returns success or failure.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
        required: true
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'
      x-codegen-request-body-name: json

  /datasets/getRDFURLsForDataset/{id}:
    get:
      tags:
        - datasets
      summary: Get URLs of dataset's RDF metadata exports
      description: |
        URLs of metadata exported as RDF from XML files contained in the
        dataset, as well as the URL used to export the dataset's user-generated
        metadata as RDF.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /datasets/rdfUserMetadata/{id}:
    get:
      tags:
        - datasets
      summary: Get the user-generated metadata of the selected dataset in an RDF file
      description: A dataset is a container for files and metadata
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /datasets/{id}/unfollow:
    post:
      tags:
        - datasets
      summary: Unfollow dataset.
      description: |
        Remove user from dataset followers and remove dataset from user followed
        datasets.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /datasets/{id}/creator:
    post:
      tags:
        - datasets
      summary: Add a creator to the Dataset's list of Creators.
      description: |
        Takes one argument, a UUID of the dataset. Request body takes key-value
        pair for creator.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                creator:
                  type: string
        required: true
      responses:
        200:
          description: OK
          content: {}
      x-codegen-request-body-name: creator

  /datasets/{id}/creator/remove:
    delete:
      tags:
        - datasets
      summary: Remove a creator from the Dataset's list of Creators.
      description: Takes the UUID of the dataset and the entry to delete (a String).
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: creator
          in: query
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /datasets/{id}/creator/reorder:
    put:
      tags:
        - datasets
      summary: Move a creator in a Dataset's list of creators.
      description: |
        Takes the UUID of the dataset, the creator to move (a String) and the
        new position of the creator in the overall list of creators.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: creator
          in: query
          required: true
          schema:
            type: string
        - name: newPos
          in: query
          required: true
          schema:
            type: integer
      responses:
        200:
          description: OK
          content: {}

  /datasets/{id}/detachdelete:
    post:
      tags:
        - datasets
      summary: Detach and delete dataset
      description: |
        Detaches all files before proceeding to perform the stanadard delete on
        the dataset.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /datasets/{id}/access:
    put:
      tags:
        - datasets
      summary: change the access of dataset
      description: Downloads all files contained in a dataset.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: access
          in: query
          description: default as PRIVATE
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /datasets/canEdit:
    get:
      tags:
        - datasets
      summary: List all datasets the user can edit
      description: |
        This will check for Permission.AddResourceToDataset and
        Permission.EditDataset
      parameters:
        - name: when
          in: query
          required: false
          schema:
            type: string
        - name: date
          in: query
          required: false
          schema:
            type: string
        - name: title
          in: query
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: The number of collections returns, default as 12.
          schema:
            type: integer
        - name: exact
          in: query
          schema:
            type: boolean
      responses:
        200:
          description: OK
          content: {}

  /datasets/{id}/title:
    put:
      tags:
        - datasets
      summary: Update dataset name
      description: |
        Takes one argument, a UUID of the dataset. Request body takes key-value
        pair for name.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              required:
                - name
              type: object
              properties:
                name:
                  type: string
        required: true
      responses:
        200:
          description: OK
          content: {}

  /datasets/{id}/queueArchival:
    post:
      tags:
        - datasets
      summary: Queue up all files in a dataset to be marked as ARCHIVED
      description: |
        Queue up all files in a dataset to be marked as ARCHIVED
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /datasets/{id}/queueUnarchival:
    post:
      tags:
        - datasets
      summary: Queue up all files in a dataset to be marked as PROCESSED
      description: |
        Queue up all files in a dataset to be marked as PROCESSED
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /collections/{coll_id}/getDatasets:
    get:
      tags:
        - datasets
      summary: List all datasets in a collection
      description: Returns list of datasets and descriptions.
      parameters:
        - name: coll_id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
      deprecated: true

  /datasets/listOutsideCollection/{coll_id}:
    get:
      tags:
        - datasets
      summary: List all datasets outside a collection
      description: Returns list of datasets and descriptions.
      parameters:
        - name: coll_id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /datasets/{id}/editing:
    post:
      tags:
        - datasets
      summary: Update dataset administrative information
      description: |
        Takes one argument, a UUID of the dataset. Request body takes key-value
        pairs for name and description.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              required:
                - description
                - name
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
        required: true
      responses:
        200:
          description: OK
          content: {}

  /datasets/{id}/getPreviews:
    get:
      tags:
        - datasets
      summary: Get dataset previews
      description: |
        Return the currently existing previews of the selected dataset (full
        description, including paths to preview files, previewer names etc).
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /datasets/searchmetadata:
    post:
      tags:
        - datasets
      summary: List datasets satisfying a general metadata search tree
      requestBody:
        content:
          application/json:
            schema:
              type: object
        required: true
      responses:
        200:
          description: OK
          content: {}

  /datasets/searchusermetadata:
    post:
      tags:
        - datasets
      summary: List datasets satisfying a user metadata search tree
      requestBody:
        content:
          application/json:
            schema:
              type: object
        required: true
      responses:
        200:
          description: OK
          content: {}

  /datasets/{id}/metadata.jsonld:
    get:
      tags:
        - datasets
      summary: Retrieve metadata as JSON-LD
      description: Get metadata of the dataset object as JSON-LD.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: extractor
          in: query
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'
    post:
      tags:
        - datasets
      summary: Add JSON-LD metadata to the database.
      description: |
        Metadata in attached JSON-LD object will be added to metadata Mongo db
        collection.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JSONLD'
        required: true
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'
      x-codegen-request-body-name: matadata.jsonld
    delete:
      tags:
        - datasets
      summary: Remove JSON-LD metadata, filtered by extractor if necessary
      description: Remove JSON-LD metadata from dataset object
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: extractor
          in: query
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /datasets/{id}/license:
    post:
      tags:
        - datasets
      summary: Update license information of a dataset
      description: |
        Takes four arguments, all Strings. licenseType, rightsHolder,
        licenseText, licenseUrl
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/License'
        required: true
      responses:
        200:
          description: OK
          content: {}

  /datasets/{id}/follow:
    post:
      tags:
        - datasets
      summary: Follow dataset
      description: Add user to dataset followers and add dataset to user followed
        datasets.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /datasets/attachmultiple:
    post:
      tags:
        - datasets
      summary: Attach multiple files to an existing dataset
      description: |
        Add multiple files, by ID, to a dataset that is already in the system.
        Requires file ids and dataset id.
      requestBody:
        content:
          application/json:
            schema:
              required:
                - datasetid
                - existingfiles
              type: object
              properties:
                datasetid:
                  type: string
                existingfiles:
                  type: string
                  description: file ids seperated by comma
        required: true
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /datasets/{id}/reindex:
    post:
      tags:
        - datasets
      summary: Reindex a dataset
      description: |
        Reindex the existing dataset, if recursive is set to true if will also
        reindex all files in that dataset.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /datasets/{id}/files:
    get:
      tags:
        - datasets
      summary: List files in dataset, including those within folders
      description: Datasets and descriptions.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: max
          in: query
          schema:
            type: number
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'
    post:
      tags:
        - datasets
      summary: Upload files and attach to given dataset
      description: |
        This will take a list of url or path objects that point to files that
        will be ingested and added to this dataset.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
                - File
              properties:
                File:
                  type: string
                  description: |
                    The file to upload to the dataset. if no specific key is provided,
                    will attempt to upload every file. Otherwise, only upload the specific
                    key we were given (e.g. "File")
                  format: binary
        required: true
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /datasets/{id}/urls:
    post:
      tags:
        - datasets
      summary: Upload files and attach to given dataset
      description: |
        This will take an URL of file object that are added to this dataset,
        the file source will be added as metadata. Request body takes key-value
        pairs for file url, the key can be fileurl, weburl or url.
        This can also add metadata at the same time.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        description: the key can be fileurl, weburl or url
        content:
          application/json:
            schema:
              type: object
        required: false
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /datasets/moveFileToDataset:
    get:
      tags:
        - datasets
      summary: |
        List all datasets in the space the user can edit and thus move the file
        to
      description: |
        This will check for Permission.AddResourceToDataset and
        Permission.EditDataset
      responses:
        200:
          description: OK
          content: {}

  /datasets/{id}/listFiles:
    get:
      tags:
        - datasets
      summary: List files in dataset not in any folders
      description: Datasets and descriptions.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /datasets/{ds_id}/listAllFiles:
    get:
      tags:
        - datasets
      summary: List all file within a dataset
      parameters:
        - name: ds_id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /datasets/{id}/removeTag:
    post:
      tags:
        - datasets
      summary: Remove tag of dataset
      description: A dataset is a container for files and metadata
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        description: The body of the POST request.
        content:
          application/json:
            schema:
              required:
                - tagId
              type: object
              properties:
                tagId:
                  type: string
        required: true
      responses:
        200:
          description: OK
          content: {}

  /datasets/{datasetId}/moveBetweenDatasets/{toDataset}/{fileId}:
    post:
      tags:
        - datasets
      summary: Attach existing file to a new dataset and delete it from the old one
      description: |
        If the file is an XML metadata file, the metadata are added to the
        dataset.
      parameters:
        - name: datasetId
          in: path
          required: true
          schema:
            type: string
        - name: toDataset
          in: path
          required: true
          schema:
            type: string
        - name: fileId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /datasets/{id}/download:
    get:
      tags:
        - datasets
      summary: Download dataset
      description: Downloads all files contained in a dataset.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: compression
          in: query
          description: default as -1
          schema:
            type: number
        - name: tracking
          in: query
          description: default as true
          schema:
            type: boolean
      responses:
        200:
          description: OK
          content: {}

  /datasets/{id}/downloadPartial:
    get:
      tags:
        - datasets
      summary: Download a subset of files from a dataset
      description: Takes dataset ID and a JSON-string representing a list of file IDs
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: fileList
          in: query
          description: ID of the files to download from the dataset
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /datasets/{id}/downloadFolder:
    get:
      tags:
        - datasets
      summary: Download a folder from a dataset
      description: Takes dataset ID and a folder ID in that dataset and streams just that folder and sub-folders as a zip
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: folderId
          in: query
          description: ID of the folder to download
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /datasets/clearOldDatasetsTrash:
    delete:
      tags:
        - datasets
      summary: Deleted all datasets in trash older than days specified
      description: Server admin action.
      parameters:
        - name: days
          in: query
          schema:
            type: number
      responses:
        200:
          description: OK
          content: {}

  /datasets/emptyTrash:
    delete:
      tags:
        - datasets
      summary: Emptying trash datasets
      responses:
        200:
          description: OK
          content: {}

  /datasets/listTrash:
    get:
      tags:
        - datasets
      summary: list trash datasets
      parameters:
        - name: limit
          in: query
          schema:
            type: number
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /datasets/restore/{id}:
    put:
      tags:
        - datasets
      summary: restore a trash dataset
      description: |
        This will check for Permission.DeleteDataset
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /datasets/{id}/tags/remove:
    post:
      tags:
        - datasets
      summary: remove a tag from a dataset
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
      deprecated: true


  ##############################################################################
  # COLLECTIONS ENDPOINTS                                                      #
  ##############################################################################
  /collections:
    get:
      tags:
        - collections
      summary: Return a list of collections that fit the query standard and user has
        view permission
      description: Collections are groupings of datasets
      parameters:
        - name: when
          in: query
          required: false
          schema:
            type: string
        - name: title
          in: query
          description: The title/ name of colletions
          schema:
            type: string
        - name: date
          in: query
          description: The date collection is created
          schema:
            type: string
        - name: limit
          in: query
          description: The number of collections returns, default as 12.
          schema:
            type: integer
        - name: exact
          in: query
          schema:
            type: boolean
      responses:
        401:
          description: Not authorized
          content: {}
    post:
      tags:
        - collections
      summary: Create a collection
      description: Collections are groupings of datasets
      requestBody:
        description: The body of the POST request to create a collection.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Collection'
        required: false
      responses:
        200:
          description: OK
          content: {}
      x-codegen-request-body-name: collection

  /collections/{coll_id}:
    get:
      tags:
        - collections
      summary: Get a specific collection
      description: Get a specific collection
      parameters:
        - name: coll_id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
    delete:
      tags:
        - collections
      summary: Remove collection
      description: Does not delete the individual datasets in the collection.
      parameters:
        - name: coll_id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /collections/{coll_id}/getParentCollections:
    get:
      tags:
        - collections
      summary: Get parent collections for collection
      description: Collections are groupings of datasets
      parameters:
        - name: coll_id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /collections/allCollections:
    get:
      tags:
        - collections
      summary: Get all collections
      description: Collections are groupings of datasets
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
        - name: showAll
          in: query
          schema:
            type: boolean
      responses:
        200:
          description: OK
          content: {}

  /collections/{coll_id}/title:
    put:
      tags:
        - collections
      summary: Update a collection name
      description: |
        Takes one argument, a UUID of the collection. Request body takes a
        key-value pair for the name
      parameters:
        - name: coll_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              required:
                - name
              type: object
              properties:
                name:
                  type: string
        required: true
      responses:
        200:
          description: OK
          content: {}

  /collections/possibleParents:
    get:
      tags:
        - collections
      summary: |
        List all collections the user can edit except itself and its parent
        collections
      description: |
        This will check for Permission.AddResourceToCollection and
        Permission.EditCollection
      parameters:
        - name: when
          in: query
          required: false
          schema:
            type: string
        - name: currentCollectionId
          in: query
          required: true
          schema:
            type: string
        - name: title
          in: query
          schema:
            type: string
        - name: date
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: number
        - name: exact
          in: query
          schema:
            type: boolean
      responses:
        200:
          description: OK
          content: {}

  /collections/{id}/unfollow:
    post:
      tags:
        - collections
      summary: Unfollow collection.
      description: |
        Remove user from collection followers and remove collection from user
        followed collections.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /collections/topLevelCollections:
    get:
      tags:
        - collections
      summary: Get all root collections or collections that do not have a parent
      description: Collections are groupings of datasets
      responses:
        200:
          description: OK
          content: {}

  /collections/rootCollections:
    get:
      tags:
        - collections
      summary: Get all root collections
      description: Collections are groupings of datasets
      responses:
        200:
          description: OK
          content: {}

  /collections/{coll_id}/removeSubCollection/{sub_coll_id}:
    post:
      tags:
        - collections
      summary: Remove subcollection from collection
      description: Collections are groupings of datasets
      parameters:
        - name: coll_id
          in: path
          required: true
          schema:
            type: string
        - name: sub_coll_id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /collections/canEdit:
    get:
      tags:
        - collections
      summary: List all collections the user can edit
      description: |
        This will check for Permission.AddResourceToCollection and
        Permission.EditCollection
      parameters:
        - name: when
          in: query
          required: false
          schema:
            type: string
        - name: title
          in: query
          schema:
            type: string
        - name: date
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: number
        - name: exact
          in: query
          schema:
            type: boolean
      responses:
        200:
          description: OK
          content: {}

  /collections/clearOldCollectionsTrash:
    delete:
      tags:
        - collections
      summary: Deleted all collections in trash older than days specified
      description: Server admin action.
      parameters:
        - name: days
          in: query
          schema:
            type: number
      responses:
        200:
          description: OK
          content: {}

  /collections/emptyTrash:
    delete:
      tags:
        - collections
      summary: Emptying trash collections
      responses:
        200:
          description: OK
          content: {}

  /collections/listTrash:
    get:
      tags:
        - collections
      summary: list trash collections
      parameters:
        - name: limit
          in: query
          schema:
            type: number
      responses:
        200:
          description: OK
          content: {}

  /collections/restore/{coll_id}:
    put:
      tags:
        - collections
      summary: restore a trash collection
      description: |
        This will check for Permission.DeleteCollection
      parameters:
        - name: coll_id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /collections/{coll_id}/addSubCollection/{sub_coll_id}:
    post:
      tags:
        - collections
      summary: Add subcollection to collection
      description: Collections are groupings of datasets
      parameters:
        - name: coll_id
          in: path
          required: true
          schema:
            type: string
        - name: sub_coll_id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /collections/{coll_id}/getChildCollections:
    get:
      tags:
        - collections
      summary: Get child collections in collection
      description: Collections are groupings of datasets
      parameters:
        - name: coll_id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /collections/{coll_id}/datasets:
    get:
      tags:
        - collections
      summary: list all datasets in the collection
      description: Collections are groupings of datasets
      parameters:
        - name: coll_id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /collections/{coll_id}/datasetPossibleParents/{ds_id}:
    get:
      tags:
        - collections
      summary: |
        If dataset is in a space, list all collections can be the parent of
        the dataset in this space, otherwise list all possiable collections
      description: Collections are groupings of datasets
      parameters:
        - name: when
          in: query
          required: false
          schema:
            type: string
        - name: coll_id
          in: path
          required: true
          schema:
            type: string
        - name: ds_id
          in: path
          required: true
          schema:
            type: string
        - name: title
          in: query
          schema:
            type: string
        - name: date
          in: query
          schema:
            type: string
        - name: limit
          in: query
          description: default as 12
          schema:
            type: number
        - name: exact
          in: query
          description: default as false
          schema:
            type: boolean
      responses:
        200:
          description: OK
          content: {}

  /collections/{coll_id}/datasets/{ds_id}:
    post:
      tags:
        - collections
      summary: Add dataset to collection
      description: Collections are groupings of datasets
      parameters:
        - name: coll_id
          in: path
          required: true
          schema:
            type: string
        - name: ds_id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
    delete:
      tags:
        - collections
      summary: Detach a dataset from collection
      description: Collections are groupings of datasets
      parameters:
        - name: coll_id
          in: path
          required: true
          schema:
            type: string
        - name: ds_id
          in: path
          required: true
          schema:
            type: string
        - name: ignoreNotFound
          in: query
          description: default as True
          schema:
            type: boolean
      responses:
        200:
          description: OK
          content: {}

  /collections/{c_id}/previews/{p_id}:
    post:
      tags:
        - collections
      summary: Attach existing preview to collection
      description: Collections are groupings of datasets
      parameters:
        - name: c_id
          in: path
          required: true
          schema:
            type: string
        - name: p_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                extractor_id:
                  type: string
                preview_type:
                  type: string
        required: false
      responses:
        200:
          description: OK
          content: {}

  /collections/{id}/follow:
    post:
      tags:
        - collections
      summary: Follow collection.
      description: |
        Add user to collection followers and add collection to user followed
        collections.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /collections/{coll_id}/getParentCollectionIds:
    get:
      tags:
        - collections
      summary: Get parent collection ids of collection
      description: Collections are groupings of datasets
      parameters:
        - name: coll_id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /collections/{coll_id}/reindex:
    post:
      tags:
        - collections
      summary: Reindex a collection
      description: |
        Reindex the existing collection, if recursive is set to true it will
        also reindex all datasets and files.
      parameters:
        - name: coll_id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /collections/{coll_id}/unsetRootFlag/{spaceId}:
    post:
      tags:
        - collections
      summary: Removes root flag from a collection in  a space
      description: Collections are groupings of datasets
      parameters:
        - name: coll_id
          in: path
          required: true
          schema:
            type: string
        - name: spaceId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /collections/{coll_id}/removeFromSpaceAllowed/{space_id}:
    get:
      tags:
        - collections
      summary: Checks if we can remove a collection from a space
      description: |
        This will check if the collection has parent collection in this space.
        If not, we can remove the collection from the space
      parameters:
        - name: coll_id
          in: path
          required: true
          schema:
            type: string
        - name: space_id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
                example: true

  /collections/{coll_id}/getChildCollectionIds:
    get:
      tags:
        - collections
      summary: Get child collection ids in collection
      description: Collections are groupings of datasets
      parameters:
        - name: coll_id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /collections/newCollectionWithParent:
    post:
      tags:
        - collections
      summary: Create a collection with parent
      description: Collections are groupings of datasets
      requestBody:
        description: The body of the POST request to create a collection.
        content:
          application/json:
            schema:
              required:
                - name
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
                space:
                  type: string
                googleAnalytics:
                  type: string
                parentId:
                  type: string
        required: false
      responses:
        200:
          description: OK
          content: {}
      x-codegen-request-body-name: collection

  /collections/{coll_id}/description:
    put:
      tags:
        - collections
      summary: Update collection description
      description: |
        Takes one argument, a UUID of the collection. Request body takes
        key-value pair for the description
      parameters:
        - name: coll_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              required:
                - description
              type: object
              properties:
                description:
                  type: string
        required: true
      responses:
        200:
          description: OK
          content: {}
        404:
          description: Not Found
          content: {}
      x-codegen-request-body-name: description

  /collections/{coll_id}/rootFlag/{spaceId}:
    post:
      tags:
        - collections
      summary: Add root flags for a collection in space
      description: Collections are groupings of datasets
      parameters:
        - name: coll_id
          in: path
          required: true
          schema:
            type: string
        - name: spaceId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /collections/{id}/download:
    get:
      tags:
        - collections
      summary: Download collection
      description: Downloads all child collections, datasets and files in a collection.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: compression
          in: query
          description: default as -1
          schema:
            type: number
      responses:
        200:
          description: OK
          content: {}

  /collections/list:
    get:
      tags:
        - collections
      summary: List all collections the user can view
      description: This will check for Permission.ViewCollection
      parameters:
        - name: when
          in: query
          required: false
          schema:
            type: string
        - name: title
          in: query
          schema:
            type: string
        - name: date
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: number
        - name: exact
          in: query
          schema:
            type: boolean
      responses:
        200:
          description: OK
          content: {}
      deprecated: true

  /collections/{coll_id}/datasetsRemove/{ds_id}/{ignoreNotFound}:
    post:
      tags:
        - collections
      summary: Remove a dataset from a collection.
      parameters:
        - name: coll_id
          in: path
          required: true
          schema:
            type: string
        - name: ds_id
          in: path
          required: true
          schema:
            type: string
        - name: ignoreNotFound
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
      deprecated: true

  /collections/{coll_id}/remove:
    post:
      tags:
        - collections
      summary: remove a collection
      parameters:
        - name: coll_id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
      deprecated: true

  ##############################################################################
  # SPACES ENDPOINTS                                                           #
  ##############################################################################
  /spaces:
    get:
      tags:
        - spaces
      summary: List spaces the user can view
      description: Retrieves information about spaces
      parameters:
        - name: when
          in: query
          required: false
          schema:
            type: string
        - name: title
          in: query
          schema:
            type: string
        - name: date
          in: query
          schema:
            type: string
        - name: limit
          in: query
          description: default as 12
          schema:
            type: number
      responses:
        200:
          description: OK
          content: {}
    post:
      tags:
        - spaces
      summary: Create a space
      description: Spaces are groupings of collections and datasets.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Space'
        required: true
      responses:
        200:
          description: OK
          content: {}
        400:
          $ref: '#/components/responses/BadRequest'

  /spaces/{id}:
    get:
      tags:
        - spaces
      summary: Get a space
      description: Retrieves information about a space
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
        - spaces
      summary: Remove a space
      description: Does not delete the individual datasets and collections in the
        space.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /spaces/{spaceId}/removeDataset/{datasetId}:
    post:
      tags:
        - spaces
      summary: Remove a dataset from a space
      description: Spaces are groupings of collections and datasets.
      parameters:
        - name: spaceId
          in: path
          required: true
          schema:
            type: string
        - name: datasetId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /spaces/{id}/collections:
    get:
      tags:
        - spaces
      summary: List UUIDs of all collections in a space
      description: Spaces are groupings of collections and datasets.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: limit
          in: query
          description: default as 12
          schema:
            type: number
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /spaces/{id}/datasets:
    get:
      tags:
        - spaces
      summary: List UUIDs of all datasets in a space
      description: Spaces are groupings of collections and datasets.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: limit
          in: query
          description: default as 12
          schema:
            type: number
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /spaces/{id}/verify:
    put:
      tags:
        - spaces
      summary: Set the space as verified
      description: Server Admin Action
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /spaces/{spaceId}/addCollectionToSpace/{collectionId}:
    post:
      tags:
        - spaces
      summary: Associate a collection to a space
      description: Spaces are groupings of collections and datasets.
      parameters:
        - name: spaceId
          in: path
          required: true
          schema:
            type: string
        - name: collectionId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /spaces/{id}/rejectRequest:
    post:
      tags:
        - spaces
      summary: Reject Request
      description: |
        Reject user's request to the space, remove the request and send email to
        the request user
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /spaces/{id}/acceptRequest:
    post:
      tags:
        - spaces
      summary: Accept Request
      description: |
        Accept user's request to the space and assign a specific Role, remove
        the request and send email to the request user
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /spaces/{spaceId}/removeCollection/{collectionId}:
    post:
      tags:
        - spaces
      summary: Remove a collection from a space
      description: Spaces are groupings of collections and datasets.
      parameters:
        - name: spaceId
          in: path
          required: true
          schema:
            type: string
        - name: collectionId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /spaces/{id}/updateUsers:
    post:
      tags:
        - spaces
      summary: Update the user information associated with a space
      description: Spaces are groupings of collections and datasets.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                rolesandusers:
                  type: object
                  properties: {}
                  description: A map that contains a role level as a key and a comma
                    separated String of user IDs as the value
        required: true
      responses:
        200:
          description: OK
          content: {}
        400:
          description: rolesandusers data is missing from the updateUsers call.
          content: {}
        404:
          $ref: '#/components/responses/NotFound'

  /spaces/canEdit:
    get:
      tags:
        - spaces
      summary: List spaces the user can add to
      description: Retrieves a list of spaces that the user has permission to add
        to
      parameters:
        - name: when
          in: query
          required: false
          schema:
            type: string
        - name: title
          in: query
          schema:
            type: string
        - name: date
          in: query
          schema:
            type: string
        - name: limit
          in: query
          description: default as 12
          schema:
            type: number
      responses:
        200:
          description: OK
          content: {}

  /spaces/{id}/removeUser:
    post:
      tags:
        - spaces
      summary: Remove a user from a space
      description: Spaces are groupings of collections and datasets.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: removeUser
          in: query
          description: the UUID of the user
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /spaces/{id}/update:
    post:
      tags:
        - spaces
      summary: Update the information associated with a space
      description: Spaces are groupings of collections and datasets.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              required:
                - access
                - description
                - enabled
                - name
                - timetolive
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
                timetolive:
                  type: string
                enabled:
                  type: boolean
                access:
                  type: string
        required: true
      responses:
        200:
          description: OK
          content: {}

  /spaces/{id}/unfollow:
    post:
      tags:
        - spaces
      summary: Unfollow space
      description: |
        Remove user from space followers and remove space from user followed
        spaces.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /spaces/{id}/follow:
    post:
      tags:
        - spaces
      summary: Follow space
      description: Add user to space followers and add space to user followed spaces.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /spaces/{spaceId}/addDatasetToSpace/{datasetId}:
    post:
      tags:
        - spaces
      summary: Associate a dataset to a space
      description: Spaces are groupings of collections and datasets.
      parameters:
        - name: spaceId
          in: path
          required: true
          schema:
            type: string
        - name: datasetId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /spaces/{spaceId}/metadata:
    post:
      tags:
        - spaces
      summary: add metadata definition to a space
      description: |
        If uri is not defined, the uri will be set as
        "http://clowder.ncsa.illinois.edu/metadata/{uuid}#CamelCase"
      parameters:
        - name: spaceId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              required:
                - description
                - label
                - type
              type: object
              properties:
                label:
                  type: string
                type:
                  type: string
                description:
                  type: string
                uri:
                  type: string
        required: true
      responses:
        200:
          description: OK
          content: {}

  ##############################################################################
  # SPACE CURATION ENDPOINTS                                                   #
  ##############################################################################
  /spaces/curations/{id}/matchmaker:
    post:
      tags:
        - curations
      summary: Update the user repository preferences and call the matchmaker
      description: |
        A curation object is a request for publication that captures the state
        of a dataset ready for publication
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /spaces/curations/retract/{id}:
    delete:
      tags:
        - curations
      summary: Retract the publication request
      description: |
        A curation object is a request for publication that captures the state
        of a dataset ready for publication
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /spaces/curations/{id}/folders/{curationFolderId}:
    delete:
      tags:
        - curations
      summary: Delete a folder from a publication request
      description: |
        A curation object is a request for publication that captures the state
        of a dataset ready for publication
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: curationFolderId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /spaces/curations/{id}/curationFile:
    get:
      tags:
        - curations
      summary: Get files in publication request
      description: |
        A curation object is a request for publication that captures the state
        of a dataset ready for publication
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /spaces/curations/{id}/files/{curationFileId}:
    delete:
      tags:
        - curations
      summary: Delete a file from a publication request
      description: |
        A curation object is a request for publication that captures the state
        of a dataset ready for publication
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: curationFileId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /curations/{curationId}/ore:
    get:
      tags:
        - curations
      summary: Get the ORE map for the proposed publication
      description: |
        A curation object is a request for publication that captures the state
        of a dataset ready for publication
      parameters:
        - name: curationId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}



  ##############################################################################
  # EXTRACTORS ENDPOINTS                                                       #
  ##############################################################################
  /extractors:
    get:
      tags:
        - extractors
      summary: Lists information about all known extractors
      description: Extractions for Files.
      responses:
        200:
          description: OK
          content: {}
    post:
      tags:
        - extractors
      summary: Register information about an extractor
      description: |
        Register information about an extractor.
        Used when an extractor starts up.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: |
                All fields in example are required.
                The value of repository can be single value or an array.
              example:
                name: test
                version: 0.1.0
                description: test
                author: Yan
                contributors: []
                contexts: []
                repository: []
                external_services: []
                libraries: []
                bibtex: []
                process: []
        required: true
      responses:
        200:
          description: OK
          content: {}

  /extractors/{name}:
    get:
      tags:
        - extractors
      summary: Lists information about a specific extractor
      description: Extractions for Files.
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        404:
          description: Not found
          content: {}

  /extractors/labels:
    post:
      tags:
        - extractors
      summary: Create a new extractor label in the database
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtractorsLabel'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractorsLabel'

  /extractors/labels/{id}:
    put:
      tags:
        - extractors
      summary: Updates an extractor label in the database
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtractorsLabel'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractorsLabel'
    delete:
      tags:
        - extractors
      summary: Deletes an extractor label from the database
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractorsLabel'

  ##############################################################################
  # EXTRACTIONS ENDPOINTS                                                      #
  ##############################################################################
  /extractions/servers_ips:
    get:
      tags:
        - extractions
      summary: Lists servers IPs running the extractors
      description: Extractions for Files.
      responses:
        200:
          description: OK
          content: {}

  /extractions/extractors_names:
    get:
      tags:
        - extractions
      summary: Lists the currently running extractors
      description: Extractions for Files.
      responses:
        200:
          description: OK
          content: {}

  /extractions/upload_url:
    post:
      tags:
        - extractions
      summary: Uploads a file for extraction using the file's URL
      description: |
        Saves the uploaded file and sends it for extraction. If the optional URL
        parameter extract is set to false, it does not send the file for
        extraction. Does not index the file.
      parameters:
        - name: extract
          in: query
          description: default as true
          schema:
            type: boolean
      requestBody:
        content:
          application/json:
            schema:
              type: array
              description: can only use fileurl as the key in body
              example:
                - fileurl: http://browndog.ncsa.illinois.edu/examples/pecan/ameriflux.sipnet.xml
                  dataset: 58d9a0fbe4b03103c1487b72
              items:
                type: object
                properties: {}
        required: false
      responses:
        200:
          description: OK
          content: {}

  /extractions/upload_file:
    post:
      tags:
        - extractions
      summary: Uploads a file for extraction of metadata and returns file id
      description: |
        Saves the uploaded file and sends it for extraction to Rabbitmq. If the
        optional URL parameter extract is set to false, it does not send the
        file for extraction. Does not index the file. Same as upload() except
        for upload()
      parameters:
        - name: extract
          in: query
          description: default as true
          schema:
            type: boolean
        - name: showPreviews
          in: query
          description: default as DatasetLevel
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
                - File
              properties:
                File:
                  type: string
                  description: file to upload
                  format: binary
        required: true
      responses:
        200:
          description: OK
          content: {}

  /extractions/supported_input_types:
    get:
      tags:
        - extractions
      summary: Lists the input file format supported by currenlty running extractors
      description: Extractions for Files.
      responses:
        200:
          description: OK
          content: {}

  /extractions/multiple_uploadby_url:
    post:
      tags:
        - extractions
      summary: Uploads files for a given list of files' URLs
      description: |
        Saves the uploaded files and sends it for extraction. Does not index the
        files. Returns id for the web resource
      responses:
        200:
          description: OK
          content: {}

  /extractions/{id}/statuses:
    get:
      tags:
        - extractions
      summary: Checks for the extraction statuses of all files
      description: Returns a list (file id, status of extractions)
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /extractions/requests:
    get:
      tags:
        - extractions
      summary: Lists dts extraction requests information
      description: Extractions for Files.
      responses:
        200:
          description: OK
          content: {}

  /extractions/{id}/metadata:
    get:
      tags:
        - extractions
      summary: Provides the metadata extracted from the file
      description: Retruns Status of extractions and metadata extracted so far
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /extractions/extractors_details:
    get:
      tags:
        - extractions
      summary: Lists the currenlty details running extractors
      description: Extractions for Files.
      responses:
        200:
          description: OK
          content: {}

  /extractions/{id}/status:
    get:
      tags:
        - extractions
      summary: Checks for the status of all extractors processing the file with id
      description: |
        A list of status of all extractors responsible for extractions on the
        file and the final status of extraction job
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  ##############################################################################
  # LOGOS ENDPOINTS                                                            #
  ##############################################################################
  /logos:
    get:
      tags:
        - logos
      summary: List logos
      description: List logos known to system
      responses:
        200:
          description: OK
          content: {}
    post:
      tags:
        - logos
      summary: Upload file
      description: |
        Files uploaded to this endpoint will be marked as special files, such as
        favicon.png, logo.png. The file needs to be specified with image.
      responses:
        200:
          description: OK
          content: {}

  /logos/{id}:
    get:
      tags:
        - logos
      summary: Get logo
      description: Return logo information
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
    put:
      tags:
        - logos
      summary: Set logo
      description: Updates logo information
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
    delete:
      tags:
        - logos
      summary: Delete file
      description: Delete a static file
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /logos/{id}/blob:
    get:
      tags:
        - logos
      summary: Download file
      description: Download a static file, or the alternate file
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /logos/{path}/{name}:
    get:
      tags:
        - logos
      summary: Get logo
      description: Return logo information
      parameters:
        - name: path
          in: path
          required: true
          schema:
            type: string
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
    put:
      tags:
        - logos
      summary: Set logo
      description: Updates logo information
      parameters:
        - name: path
          in: path
          required: true
          schema:
            type: string
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
    delete:
      tags:
        - logos
      summary: Delete file
      description: Delete a static file
      parameters:
        - name: path
          in: path
          required: true
          schema:
            type: string
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /logos/{path}/{name}/blob:
    get:
      tags:
        - logos
      summary: Download file
      description: Download a static file, or the alternate file
      parameters:
        - name: path
          in: path
          required: true
          schema:
            type: string
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  ##############################################################################
  # PROXY ENDPOINTS                                                            #
  ##############################################################################
  /proxy/{endpoint_key}:
    get:
      tags:
        - proxy
      summary: Proxy a GET request to an endpoint specified in the proxy's configuration.
      description: Access to the endpoint will be restricted by Clowder authentication.
      parameters:
        - name: endpoint_key
          in: path
          required: true
          schema:
            type: string
      responses:
        401:
          description: Not authorized
          content: {}
        404:
          description: Endpoint not configured
          content: {}
    put:
      tags:
        - proxy
      summary: Proxy a PUT request to an endpoint specified in the proxy's configuration.
      description: Access to the endpoint will be restricted by Clowder authentication.
      parameters:
        - name: endpoint_key
          in: path
          required: true
          schema:
            type: string
      requestBody:
        description: The body of the PUT request to proxy.
        content:
          application/json:
            schema:
              type: object
        required: false
      responses:
        401:
          description: Not authorized
          content: {}
        404:
          description: Endpoint not configured
          content: {}
    post:
      tags:
        - proxy
      summary: Proxy a POST request to an endpoint specified in the proxy's configuration.
      description: Access to the endpoint will be restricted by Clowder authentication.
      parameters:
        - name: endpoint_key
          in: path
          required: true
          schema:
            type: string
      requestBody:
        description: The body of the POST request to proxy.
        content:
          application/json:
            schema:
              type: object
        required: false
      responses:
        401:
          description: Not authorized
          content: {}
        404:
          description: Endpoint not configured
          content: {}
    delete:
      tags:
        - proxy
      summary: Proxy a DELETE request to an endpoint specified in the proxy's configuration.
      description: Access to the endpoint will be restricted by Clowder authentication.
      parameters:
        - name: endpoint_key
          in: path
          required: true
          schema:
            type: string
      responses:
        401:
          description: Not authorized
          content: {}
        404:
          description: Endpoint not configured
          content: {}

  /proxy/{endpoint_key}/{pathSuffix}:
    get:
      tags:
        - proxy
      summary: Proxy a GET request to an endpoint specified in the proxy's configuration.
      description: Access to the endpoint will be restricted by Clowder authentication.
      parameters:
        - name: endpoint_key
          in: path
          required: true
          schema:
            type: string
        - name: pathSuffix
          in: path
          required: true
          schema:
            type: string
      responses:
        401:
          description: Not authorized
          content: {}
        404:
          description: Endpoint not configured
          content: {}
    put:
      tags:
        - proxy
      summary: Proxy a PUT request to an endpoint specified in the proxy's configuration.
      description: Access to the endpoint will be restricted by Clowder authentication.
      parameters:
        - name: endpoint_key
          in: path
          required: true
          schema:
            type: string
        - name: pathSuffix
          in: path
          required: true
          schema:
            type: string
      requestBody:
        description: The body of the PUT request to proxy.
        content:
          application/json:
            schema:
              type: object
        required: false
      responses:
        401:
          description: Not authorized
          content: {}
        404:
          description: Endpoint not configured
          content: {}
    post:
      tags:
        - proxy
      summary: Proxy a POST request to an endpoint specified in the proxy's configuration.
      description: Access to the endpoint will be restricted by Clowder authentication.
      parameters:
        - name: endpoint_key
          in: path
          required: true
          schema:
            type: string
        - name: pathSuffix
          in: path
          required: true
          schema:
            type: string
      requestBody:
        description: The body of the POST request to proxy.
        content:
          application/json:
            schema:
              type: object
        required: false
      responses:
        401:
          description: Not authorized
          content: {}
        404:
          description: Endpoint not configured
          content: {}
    delete:
      tags:
        - proxy
      summary: Proxy a DELETE request to an endpoint specified in the proxy's configuration.
      description: Access to the endpoint will be restricted by Clowder authentication.
      parameters:
        - name: endpoint_key
          in: path
          required: true
          schema:
            type: string
        - name: pathSuffix
          in: path
          required: true
          schema:
            type: string
      responses:
        401:
          description: Not authorized
          content: {}
        404:
          description: Endpoint not configured
          content: {}

  ##############################################################################
  # REPORTING ENDPOINTS                                                        #
  ##############################################################################
  /reports/metrics:
    get:
      tags:
        - reporting
      summary: Download usage metrics report for files, datasets and collections as
        CSV.
      description: |
        Download usage metrics report for files, datasets and collections as a CSV file.
        Must be a server admin to access the report.
      responses:
        200:
          description: A CSV with usage metrics
          content:
            text/csv:
              schema:
                type: string
                format: binary
        401:
          description: Not authorized
          content: {}

  /reports/metrics/files:
    get:
      tags:
        - reporting
      summary: Download usage metrics report for files as CSV.
      description: |
        Download usage metrics report for files as a CSV file.
        Must be a server admin to access the report. Supports ISO8601 date range filters.
      parameters:
        - name: since
          in: query
          required: false
          schema:
            type: string
        - name: until
          in: query
          required: false
          schema:
            type: string
      responses:
        200:
          description: A CSV with usage metrics
          content:
            application/json:
              schema:
                type: string
                format: binary
        401:
          description: Not authorized
          content: {}

  /reports/metrics/datasets:
    get:
      tags:
        - reporting
      summary: Download usage metrics report for datasets as CSV.
      description: |
        Download usage metrics report for datasets as a CSV file.
        Must be a server admin to access the report. Supports ISO8601 date range filters.
      parameters:
        - name: since
          in: query
          required: false
          schema:
            type: string
        - name: until
          in: query
          required: false
          schema:
            type: string
      responses:
        200:
          description: A CSV with usage metrics
          content:
            application/json:
              schema:
                type: string
                format: binary
        401:
          description: Not authorized
          content: {}

  /reports/metrics/collections:
    get:
      tags:
        - reporting
      summary: Download usage metrics report for collections as CSV.
      description: |
        Download usage metrics report for collections as a CSV file.
        Must be a server admin to access the report.
      responses:
        200:
          description: A CSV with usage metrics
          content:
            application/json:
              schema:
                type: string
                format: binary
        401:
          description: Not authorized
          content: {}

  /reports/storage/spaces:
    get:
      tags:
        - reporting
      summary: Download storage metrics report for spaces as CSV.
      description: |
        Download storage metrics report for files in a space as a CSV file. Space id is optional parameter.
        Must be a server admin to access the report. Supports ISO8601 date range filters.
      parameters:
        - name: space
          in: query
          required: false
          schema:
            type: string
        - name: since
          in: query
          required: false
          schema:
            type: string
        - name: until
          in: query
          required: false
          schema:
            type: string
      responses:
        200:
          description: A CSV with usage metrics
          content:
            application/json:
              schema:
                type: string
                format: binary
        401:
          description: Not authorized
          content: {}

  ##############################################################################
  # SECTIONS ENDPOINTS                                                         #
  ##############################################################################
  /sections:
    post:
      tags:
        - section
      summary: Add a section.
      requestBody:
        description: The body of the POST request.
        content:
          application/json:
            schema:
              required:
                - file_id
              type: object
              properties:
                file_id:
                  type: string
              example:
                file_id: 5b2a836d5e0e8956ed865b29
                area:
                  x: 0.23466666666666666
                  y: 0.4729458917835671
                  w: 0.248
                  h: 0.23046092184368738
        required: true
      responses:
        400:
          description: No "file_id" specified, request body.
          content: {}

  /sections/{id}:
    get:
      tags:
        - section
      summary: Get a section.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
                example:
                  id: 5c6722eb5e0e9475289cd79a
                  file_id: 5b2a836d5e0e8956ed865b29
                  startTime: -1
                  tags:
                    - a object
    delete:
      tags:
        - section
      summary: Delete a section.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /sections/{id}/comments:
    post:
      tags:
        - section
      summary: Add comment to a section.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        description: The body of the POST request.
        content:
          application/json:
            schema:
              required:
                - text
              type: object
              properties:
                text:
                  type: string
        required: true
      responses:
        200:
          description: OK
          content: {}

  /sections/{id}/description:
    post:
      tags:
        - section
      summary: Add description to a section.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        description: The body of the POST request.
        content:
          application/json:
            schema:
              required:
                - description
              type: object
              properties:
                description:
                  type: string
        required: true
      responses:
        200:
          description: OK
          content: {}
        400:
          description: no section description specified.
          content: {}

  /sections/{id}/thumbnails/{thumbnail_id}:
    post:
      tags:
        - section
      summary: Add thumbnail to section.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: thumbnail_id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
        400:
          description: Thumbnail not found.
          content: {}

  /sections/{id}/tags:
    get:
      tags:
        - section
      summary: Get tags of a section.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
    post:
      tags:
        - section
      summary: Add tags to section.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              required:
                - tags
              type: object
              properties:
                tags:
                  type: array
                  items:
                    type: string
        required: true
      responses:
        200:
          description: OK
          content: {}
    delete:
      tags:
        - section
      summary: Delete tags from section.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  /sections/{id}/tags/remove:
    post:
      tags:
        - section
      summary: remove a tag from a section
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}
      deprecated: true

  /sections/{id}/tags/remove_all:
    post:
      tags:
        - section
      summary: Delete all tags from section.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content: {}

  ##############################################################################
  # ADMIN ENDPOINTS                                                            #
  ##############################################################################
  /reindex:
    post:
      tags:
        - admin
      summary: Force a reindex of all resources in Elasticsearch.
      description: |
        Force a reindex of all resources in Elasticsearch.
        Must be a server admin.
      responses:
        401:
          description: Not authorized
          content: {}
        403:
          description: Forbidden
          content: {}

  /admin/configuration:
    post:
      tags:
        - admin
      summary: Update system configuration.
      description: |
        Update system configuration.
        Must be a server admin.
      requestBody:
        description: The body of the POST request.
        content:
          application/json:
            schema:
              type: object
              properties:
                theme:
                  type: string
                displayName:
                  type: string
                welcomeMessage:
                  type: string
                googleAnalytics:
                  type: string
                sensors:
                  type: string
                sensor:
                  type: string
                parameters:
                  type: string
                parameter:
                  type: string
                tosText:
                  type: string
                tosHtml:
                  type: string
        required: true
      responses:
        401:
          description: Not authorized
          content: {}
        403:
          description: Forbidden
          content: {}

  /admin/mail:
    post:
      tags:
        - admin
      summary: Send email to admins.
      description: |
        Send email to admins.
        Must be a server admin.
      requestBody:
        description: The body of the POST request.
        content:
          application/json:
            schema:
              type: object
              properties:
                body:
                  type: string
                subject:
                  type: string
        required: true
      responses:
        401:
          description: Not authorized
          content: {}
        403:
          description: Forbidden
          content: {}

  /admin/users:
    post:
      tags:
        - admin
      summary: Update all users status, set a list of users as active, inactive, admin
        or normal user.
      description: |
        Update all users status, set a list of users as active, inactive, admin or normal user.
        Must be a server admin.
      requestBody:
        description: The body of the POST request.
        content:
          application/json:
            schema:
              type: object
              properties:
                active:
                  type: array
                  items:
                    type: string
                inactive:
                  type: array
                  items:
                    type: string
                admin:
                  type: array
                  items:
                    type: string
                unadmin:
                  type: array
                  items:
                    type: string
        required: true
      responses:
        401:
          description: Not authorized
          content: {}
        403:
          description: Forbidden
          content: {}

  /changeAppearance:
    post:
      tags:
        - admin
      summary: Change themes of the clowder instance.
      description: |
        Change themes of the clowder instance.
        Must be a server admin.
      requestBody:
        description: The body of the POST request.
        content:
          application/json:
            schema:
              type: object
              properties:
                theme:
                  type: string
                displayName:
                  type: string
                welcomeMessage:
                  type: string
                googleAnalytics:
                  type: string
        required: true
      responses:
        401:
          description: Not authorized
          content: {}


  ##############################################################################
  # 3DTEXTURES ENDPOINTS                                                       #
  ##############################################################################
  /3dTextures:
    post:
      tags:
        - 3dTextures
      summary: Upload a 3D texture
      description: |
        Upload a 3D texture file to Clowder.
      responses:
        401:
          description: Not authorized
          content: {}
      deprecated: true


  ##############################################################################
  # MISC ENDPOINTS                                                             #
  ##############################################################################
  /me:
    get:
      summary: Fetch current user's info
      description: |
        Retrieve informatation on the currently logged-in user.
      responses:
        200:
          description: OK
          content: {}
        401:
          description: Not authorized
          content: {}
  /status:
    get:
      summary: Gets the status of the system
      description: |
        Returns a nested JSON object that contains the status of Clowder.
        This includes health checks, enabled plugins, as well as helpful debug
        information, such as the current size of the reindex queue.
      responses:
        200:
          description: OK
          content: {}
  /tree/getChildrenOfNode:
    get:
      summary: Fetch children of the given node in the file tree
      description: |
        Fetch children of the given node in the file tree.
      responses:
        200:
          description: OK
          content: {}
        401:
          description: Not authorized
          content: {}

  ##############################################################################
  # SELECTION ENDPOINTS                                                        #
  ##############################################################################
  /selected:
    get:
      tags:
        - files
      summary: Get the list of user-selected files
      description: |
        Get the list of user-selected files.
      responses:
        200:
          description: OK
          content: {}
        401:
          description: Not authorized
          content: {}
    post:
      tags:
        - files
      summary: Select a specific file
      description: |
        Select a specific file.
      responses:
        200:
          description: OK
          content: {}
        401:
          description: Not authorized
          content: {}

  /selected/remove:
    post:
      tags:
        - files
      summary: De-select a specific file
      description: |
        De-select a specific file.
      responses:
        200:
          description: OK
          content: {}
        401:
          description: Not authorized
          content: {}

  /selected/files:
    get:
      tags:
        - files
      summary: Download all selected files
      description: |
        Download all selected files.
      responses:
        200:
          description: OK
          content: {}
        401:
          description: Not authorized
          content: {}
    delete:
      tags:
        - files
      summary: Delete all selected files
      description: |
        Delete all selected files.
      responses:
        200:
          description: OK
          content: {}
        401:
          description: Not authorized
          content: {}

  /selected/clear:
    post:
      tags:
        - files
      summary: De-select all files
      description: |
        De-select all files.
      responses:
        200:
          description: OK
          content: {}
        401:
          description: Not authorized
          content: {}

  /selected/tag:
    post:
      tags:
        - files
      summary: Apply a tag to all selected files
      description: |
        Apply a tag to all selected files.
      responses:
        200:
          description: OK
          content: {}
        401:
          description: Not authorized
          content: {}

  /selected/submit/{ds_id}/{file_ids}:
    post:
      tags:
        - extractions
        - files
      summary: Submit all selected files for extraction
      description: |
        Submit all selected files for extraction.
      parameters:
        - name: ds_id
          in: path
          required: true
          schema:
            type: string
        - name: file_ids
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                parameters:
                  type: array
                  items:
                    type: string
                extractor:
                  type: string
                  description: the extractor Id
              example:
                extractor: ncsa.image.metadata
        required: true
      responses:
        200:
          description: OK
          content: {}
        401:
          description: Not authorized
          content: {}


################################################################################
# Components                                                                   #
################################################################################
components:

  ##############################################################################
  # Models                                                                     #
  ##############################################################################
  schemas:
    UUID:
      type: string
      description: ID of an object
    File:
      type: object
      description: holds all information about a file
      properties:
        id:
          type: string
          example: "5b8e969d5e0e8690971ee23e"
        filename:
          type: string
          example: "cat.jpg"
        filepath:
          type: string
          description: |
            only specified if user is serveradmin, and storage is
            DiskByteStorageService
          example: "/home/clowder/data/uploads/41/e2/1e/5b8e969d5e0e8690971ee241"
        service-endpoint:
          type: string
          description: |
            only specified if user is serveradmin, and storage is
            S3ByteStorageService
        bucket-name:
          type: string
          description: |
            only specified if user is serveradmin, and storage is
            S3ByteStorageService
        object-key:
          type: string
          description: |
            only specified if user is serveradmin, and storage is
            S3ByteStorageService
        filedescription:
          type: string
          example: "Picture of a cat"
        content-type:
          type: string
          example: "image/jpeg"
        date-created:
          type: string # should be date-time
          example: "Tue Sep 04 09:28:45 CDT 2018"
        size:
          type: string # should be integer int64
          format: int64
          example: "190497"
        authorId:
          type: string # should be miniuser
          description: id of user who uploaded the file
          #$ref: '#/components/schemas/MiniUser'
          example: "5447f889fa429866bbd44dbd"
        thumbnail:
          type: string
          description: |
            optinal id of the thumbnail image of this file
          example: "5bfd5a2640c6cd6147bb27e0"
        status:
          type: string # should be enum
          description: |
            status of the file, this can be one of the following:
            - CREATED file is created, but blob is not in final place yes
            - PROCESSING blob is in final place, final processing is done such as sending messagess to RabbitMQ
            - PROCESSED file is fully procesed by clowder
          example: "PROCESSED"
    MiniUser:
      type: object
    Space:
      type: object
      required:
        - description
        - name
      properties:
        name:
          type: string
        description:
          type: string
    Collection:
      required:
        - name
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        space:
          type: string
        googleAnalytics:
          type: string
    Dataset:
      required:
        - name
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        access:
          type: string
          enum:
            - PUBLIC
            - PRIVATE
            - DEFAULT
            - TRIAL
        space:
          type: array
          description: if space is not set or set as default, this dataset will not
            be add to any Spaces.
          items:
            type: string
        collection:
          type: array
          description: if collection is not set or set as default, this dataset will
            not be add to any Collections.
          items:
            type: string
        existingfiles:
          type: string
          description: the list of file ids, seperated with comma
      example:
        name: A dataset
    JSONLD:
      type: object
      example:
        '@context':
          - https://clowderframework.org/contexts/metadata.jsonld
          - csv_headers: http://clowder.ncsa.illinois.edu/metadata/ncsa.csvheaders
        attached_to:
          resource_type: cat:file
          url: https://clowderframework.org/clowder/files/5b2a836d5e0e8956ed865b29
        created_at: Wed Jun 20 11:40:25 CDT 2018
        agent:
          '@type': cat:extractor
          name: https://clowderframework.org/clowder/extractors/ncsa.csvheaders/1.0
          extractor_id: https://clowderframework.org/clowder/extractors/ncsa.csvheaders/1.0
        content:
          csv_headers:
            - Site_ID
            - Date&Time
            - Discharge(cms)
    Tags:
      type: object
      properties:
        tags:
          type: array
          items:
            type: string
        extractor_id:
          type: string
      example:
        tags:
          - test1
          - test2
    Comment:
      required:
        - text
      type: object
      properties:
        text:
          type: string
    License:
      required:
        - allowDownload
        - licenseText
        - licenseType
        - licenseUrl
        - rightsHolder
      type: object
      properties:
        licenseType:
          type: string
        rightsHolder:
          type: string
        licenseUrl:
          type: string
        licenseText:
          type: string
          enum:
            - by-nc-nd
            - by-nd
            - by-nc
            - by-nc-sa
            - by-sa
            - by
        allowDownload:
          type: string
    ExtractorsLabel:
      type: object
      description: An arbitrary text label on which users can filter the Extractor Catalog
      properties:
        id:
          type: string
          example: "5b8e969d5e0e8690971ee23e"
        name:
          type: string
          example: "Image"
        category:
          type: string
          example: "Type"
        extractors:
          type: array
          example: ["ncsa.image.preview", "ncsa.image.metadata"]
          items:
            type: string

  ##############################################################################
  # Parameters                                                                 #
  ##############################################################################
  parameters:
    fileId:
      name: id
      in: path
      description: ID of file object
      required: true
      schema:
        type: string

  ##############################################################################
  # Responses                                                                  #
  ##############################################################################
  responses:
    Blob:
      description: The requested data in binary form
      content:
        application/octet-stream:
          schema:
            type: string
            format: binary

    BadRequest:
      description: |
        The server could not process your request, this happens for example when
        the id specified is not of the correct form. See the message field for
        more information.
      content:
        application/json:
          schema:
            type: string

    Disabled:
      description: |
        Access to this resource is disabled
      content:
        application/json:
          schema:
            type: string

    Unauthorized:
      description: |
        The request has not been applied because it lacks valid authentication
        credentials for the target resource.
      content:
        application/json:
          schema:
            type: string

    NotFound:
      description: The requested resource was not found
      content:
        text/plain:
          schema:
            type: string

  # authentication, can be used in code
  securitySchemes:
    login:
      type: http
      scheme: basic
    apikey:
      type: apiKey
      in: header
      name: X-API-Key
    key:
      type: apiKey
      in: query
      description: This is deprecated, use X-API-Key in header instead
      name: key