dicoogle_web_api.yaml

openapi: 3.0.0
info:
  description:
    <p>Specification of the Dicoogle's PACS archive public API. This page describes all services available
    by default to the common user of the Dicoogle open-source PACS archive.
    In the given examples, the Demo website is used to try out the services. They may also be tried in
    your local deploy of Dicoogle through the base path <a href="http://localhost:8080">http://localhost:8080</a>,
    or another base path previously set. More information about Dicoogle configuration available in
    <a href="https://bioinformatics-ua.github.io/dicoogle-learning-pack/">Dicoogle Learning Pack</a>.</p>

    <p>Finally, the Dicoogle Team encourage you to try out the official Javascript client API,
    dicoogle-client-js, available in <a href="https://github.com/bioinformatics-ua/dicoogle-client-js">GitHub</a>
    and documented in detail in <a href="https://bioinformatics-ua.github.io/dicoogle-client-js/">GitHub Pages</a>.</p>

    <p>Useful external links:</p>
    <p>- <a href="https://www.dicoogle.com">Dicoogle Website</a> </p>
    <p>- <a href="https://github.com/bioinformatics-ua/dicoogle">Dicoogle GitHub</a> </p>
    <p>- <a href="https://bioinformatics-ua.github.io/dicoogle-learning-pack/">Dicoogle Learning Pack</a> </p>
    <p>- <a href="https://bioinformatics-ua.github.io/dicoogle-api/javadoc/">Dicoogle Javadoc</a> </p>
    <p>- <a href="https://github.com/bioinformatics-ua/dicoogle-client-js">Dicoogle Javascript Client</a> </p>
    <br>
  version: 3.3.1
  title: Dicoogle
  contact:
    name: Support
    url: https://dicoogle.com/about/
  license:
    name: GNU General Public License v3.0
    url: https://www.gnu.org/licenses/gpl-3.0.en.html
servers:
  - url: https://demo.dicoogle.com/
  - url: http://localhost:8080/
  - url: http://yourdicooglehost/
externalDocs:
  description: Dicoogle API
  url: https://bioinformatics-ua.github.io/dicoogle-api/
tags:
  - name: Authentication
    description: Authentication related services
  - name: User
    description: User related services
  - name: Search
    description: Search related services
  - name: Index
    description: Index related services
  - name: Management
    description: Management related services
  - name: Misc
    description: Misc related services
  - name: Machine Learning
    description: Machine learning services
paths:
  /login:
    post:
      tags:
        - Authentication
      summary: Log in to Dicoogle using the given credentials
      operationId: login
      parameters:
        - in: query
          name: username
          description: The unique user name for the client
          required: true
          schema:
            type: string
        - in: query
          name: password
          description: The user's password for authentication
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
        "401":
          description: Wrong login credentials
    get:
      tags:
        - Authentication
      summary: Check if logged in
      operationId: status
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FullUser"
      security:
        - dicoogle_auth:
            - user
  /logout:
    post:
      tags:
        - Authentication
      summary: Log out from the server
      operationId: logout
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
      security:
        - dicoogle_auth:
            - user
  /user:
    # Was PUT in Dicoogle 2
    post:
      tags:
        - User
      summary: Create a user in the system
      operationId: createUser
      parameters:
        - in: query
          name: username
          description: The unique user name for the client
          required: true
          schema:
            type: string
        - in: query
          name: password
          description: The user's password for authentication
          required: true
          schema:
            type: string
        - in: query
          name: admin
          description: Whether the user has administrator privileges or not
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
    get:
      tags:
        - User
      summary: Get all the users in the system
      operationId: getUsers
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Users"
  /user/{username}:
    delete:
      tags:
        - User
      summary: Remove a user from the system
      operationId: deleteUser
      parameters:
        - in: path
          name: username
          description: The unique user name for the client
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Operation done, returns whether a user with that name was deleted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
  /search:
    get:
      tags:
        - Search
      summary: Perform a text query
      operationId: search
      parameters:
        - in: query
          name: query
          description: the text query
          required: true
          schema:
            type: string
        - in: query
          name: provider
          description: a list of provider plugins
          required: false
          schema:
            type: string
        - in: query
          name: field
          description: ""
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Results"
        "400":
          description: Invalid supplied parameters
  /searchDIM:
    get:
      tags:
        - Search
      summary: Perform a text query with DIM-formatted outcome
      operationId: searchDIM
      parameters:
        - in: query
          name: query
          description: the text query
          required: true
          schema:
            type: string
        - in: query
          name: provider
          description: a list of provider plugins
          required: false
          schema:
            type: string
        - in: query
          name: field
          description: ""
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DIMResults"
        "400":
          description: Invalid supplied parameters
  /dump:
    get:
      tags:
        - Misc
      summary: Retrieve an image's meta-data (perform an information dump)
      operationId: dumpMetadata
      parameters:
        - in: query
          name: uid
          description: the SOP instance UID
          required: true
          schema:
            type: string
        - in: query
          name: provider
          description: a list of provider plugins
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Result"
        "400":
          description: Invalid supplied parameters
  /management/settings/index/path:
    get:
      tags:
        - Management
      summary: Get the current Dicoogle watcher directory
      operationId: getWatchingDir
      responses:
        "200":
          description: Successful operation
          content:
            text/plain:
              schema:
                type: string
    post:
      tags:
        - Management
      summary: Set the current Dicoogle watcher directory
      operationId: setWatchDir
      parameters:
        - in: query
          name: path
          description: the Dicoogle watcher directory
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
        "400":
          description: Invalid supplied parameters
  /management/settings/index/effort:
    get:
      tags:
        - Management
      summary: Get the indexation effort
      operationId: getIndexEffort
      responses:
        "200":
          description: Successful operation
          content:
            text/plain:
              schema:
                type: string
    post:
      tags:
        - Management
      summary: Set the indexation effort
      operationId: setIndexEffort
      parameters:
        - in: query
          name: effort
          description: the indexation effort
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Successful operation
        "400":
          description: Invalid supplied parameters
  /management/settings/index/thumbnail:
    get:
      tags:
        - Management
      summary: Check thumbnail indexation
      operationId: getThumbnailIndex
      responses:
        "200":
          description: Successful operation
          content:
            text/plain:
              schema:
                type: string
    post:
      tags:
        - Management
      summary: Set thumbnail indexation
      operationId: setThumbnailIndex
      parameters:
        - in: query
          name: saveThumbnail
          description: save thumbnail
          required: true
          schema:
            type: boolean
      responses:
        "200":
          description: Successful operation
        "400":
          description: Invalid supplied parameters
  /management/settings/index/watcher:
    get:
      tags:
        - Management
      summary: Check if Dicoogle watcher directory is enabled
      operationId: getWatchDirEnabled
      responses:
        "200":
          description: Successful operation
          content:
            text/plain:
              schema:
                type: string
    post:
      tags:
        - Management
      summary: Set if the watcher directory is enabled
      operationId: setWatchDirEnabled
      parameters:
        - in: query
          name: watcher
          description: enable the Dicoogle watcher directory
          required: true
          schema:
            type: boolean
      responses:
        "200":
          description: Successful operation
        "400":
          description: Invalid supplied parameters
  /management/settings/index/thumbnail/size:
    get:
      tags:
        - Management
      summary: Get the thumbnail size
      operationId: getThumbnailSize
      responses:
        "200":
          description: Successful operation
          content:
            text/plain:
              schema:
                type: string
    post:
      tags:
        - Management
      summary: Set the thumbnail size
      operationId: setThumbnailSize
      parameters:
        - in: query
          name: thumbnailSize
          description: the thumbnail size
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Successful operation
        "400":
          description: Invalid supplied parameters
  /management/settings/index:
    get:
      tags:
        - Management
      summary: Get all of the current Indexer settings
      operationId: getIndexSettings
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IndexSettings"
    post:
      tags:
        - Management
      summary: Set all the Indexer settings
      operationId: setIndexSettings
      parameters:
        - in: query
          name: path
          description: the Dicoogle watcher directory
          required: true
          schema:
            type: string
        - in: query
          name: watcher
          description: enable the Dicoogle watcher directory
          required: true
          schema:
            type: boolean
        - in: query
          name: zip
          description: index zip files
          required: true
          schema:
            type: boolean
        - in: query
          name: saveThumbnail
          description: save thumbnail
          required: true
          schema:
            type: boolean
        - in: query
          name: effort
          description: the indexation effort
          required: true
          schema:
            type: integer
        - in: query
          name: thumbnailSize
          description: the thumbnail size
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Successful operation
        "400":
          description: Invalid supplied parameters
  /management/settings/transfer:
    get:
      tags:
        - Management
      summary: Get the list of current transfer syntax settings available
      operationId: getAvailableTS
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TransferSyntaxSettingsList"
    post:
      tags:
        - Management
      summary: Set (or reset) an option of a particular transfer syntax
      operationId: setOptionTS
      parameters:
        - in: query
          name: uid
          description: the unique identifier of the transfer syntax
          required: true
          schema:
            type: string
        - in: query
          name: option
          description: the name of the option to modify
          required: true
          schema:
            type: string
        - in: query
          name: value
          description: whether to set (true) or reset (false) the option
          required: true
          schema:
            type: boolean
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
  /wado:
    get:
      tags:
        - Misc
      summary: ""
      operationId: wado
      responses:
        "200":
          description: Successful operation
          content:
            text/plain:
              schema:
                type: string
  /providers:
    get:
      tags:
        - Index
      summary: Retrieve a list of index provider plugins
      operationId: getIndexPlugins
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListOfStrings"
  /management/settings/dicom/query:
    get:
      tags:
        - Management
      summary: Get all of the current DICOM Query-Retrieve settings
      operationId: getQueryRetrieveSettings
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QuerySettings"
    post:
      tags:
        - Management
      summary: Set a group of DICOM Query/Retrieve settings
      operationId: setQueryRetrieveSettings
      parameters:
        - in: query
          name: acceptTimeout
          description: ""
          required: false
          schema:
            type: integer
        - in: query
          name: connectionTimeout
          description: ""
          required: false
          schema:
            type: integer
        - in: query
          name: idleTimeout
          description: ""
          required: false
          schema:
            type: integer
        - in: query
          name: maxAssociations
          description: ""
          required: false
          schema:
            type: integer
        - in: query
          name: maxPduReceive
          description: ""
          required: false
          schema:
            type: integer
        - in: query
          name: maxPduSend
          description: ""
          required: false
          schema:
            type: integer
        - in: query
          name: responseTimeout
          description: ""
          required: false
          schema:
            type: integer
      responses:
        "200":
          description: Successful operation
  /management/tasks/index:
    post:
      tags:
        - Index
      summary: Request a new indexing task over a given URI (recursively)
      operationId: addIndexTaskURI
      parameters:
        - in: query
          name: uri
          description:
            a URI or array of URIs representing the root resource of the files
            to be indexed
          required: true
          schema:
            type: string
          explode: true
          style: form
        - in: query
          name: plugin
          description: a list of provider plugins
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  tasks:
                    $ref: "#/components/schemas/Tasks"
        "400":
          description: Invalid supplied parameters
  /management/tasks/unindex:
    post:
      tags:
        - Index
      summary:
        Request that a list of entries is unindexed in the specified indexers,
        or all of them if left unspecified. Exactly one of the fields `uri`,
        `SOPInstanceUID` and `SeriesInstanceUID` must be given.
      operationId: addUnindexTaskList
      parameters:
        - in: query
          name: uri
          description:
            A URI or array of URIs representing the files to be unindexed.
            Unlike [`addIndexTaskURI`](#/paths/~1management~1tasks~1index/post),
            there is no recursive walk
            and the URIs must point directly to the files.
          required: false
          schema:
            type: string
          explode: true
          style: form
        - in: query
          name: SOPInstanceUID
          description:
            a UID or list of UIDs representing the DICOM instances to be
            unindexed
          required: false
          schema:
            type: string
          explode: true
          style: form
        - in: query
          name: SeriesInstanceUID
          description: a UID or list of UIDs representing the DICOM series to be unindexed
          required: false
          schema:
            type: string
          explode: true
          style: form
        - in: query
          name: StudyInstanceUID
          description: a UID or list of UIDs representing the DICOM studies to be unindexed
          required: false
          schema:
            type: string
          explode: true
          style: form
        - in: query
          name: provider
          description: a list of provider plugins
          required: false
          schema:
            type: string
          explode: true
          style: form
      responses:
        "200":
          description: Successful operation
        "400":
          description: Invalid supplied parameters
  /management/tasks/remove:
    post:
      tags:
        - Index
      summary: Request that the file at the given URI is permanently removed
      operationId: addRemoveTaskURI
      parameters:
        - in: query
          name: uri
          description:
            a URI or array of URIs representing the root resource of the files
            to be indexed
          required: true
          schema:
            type: string
          explode: true
          style: form
      responses:
        "200":
          description: Successful operation
        "400":
          description: Invalid supplied parameters
  /management/dicom/storage:
    get:
      tags:
        - Management
      summary: Check the storage's service status
      operationId: getStorageStatus
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServiceStatus"
    post:
      tags:
        - Management
      summary: Change the storage's service status
      operationId: setStorageStatus
      parameters:
        - in: query
          name: running
          description: whether the service should be running or should be stopped
          required: false
          schema:
            type: boolean
        - in: query
          name: port
          description: the port where the service should be running
          required: false
          schema:
            type: integer
        - in: query
          name: hostname
          description: the hostname or IP address that the service should be bound to 
          required: false
          schema:
            type: string
        - in: query
          name: autostart
          description: whether the service should start on boot or not
          required: false
          schema:
            type: boolean
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
  /management/dicom/query:
    get:
      tags:
        - Management
      summary: Check the query's service status
      operationId: getQueryStatus
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServiceStatus"
    post:
      tags:
        - Management
      summary: Change the query's service status
      operationId: setQueryStatus
      parameters:
        - in: query
          name: running
          description: whether the service should be running oshould be stopped
          required: false
          schema:
            type: boolean
        - in: query
          name: port
          description: the port where the service should be running
          required: false
          schema:
            type: integer
        - in: query
          name: hostname
          description: the hostname or IP address that the service should be bound to 
          required: false
          schema:
            type: string
        - in: query
          name: autostart
          description: whether the service should start on boot or not
          required: false
          schema:
            type: boolean
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
  /management/settings/dicom:
    get:
      tags:
        - Management
      summary: Retrieve the AE title of the Dicoogle archive
      operationId: getAETitle
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AETitle"
    put:
      tags:
        - Management
      summary: Redefine the AE title of the Dicoogle archive
      operationId: setAETitle
      parameters:
        - in: query
          name: aetitle
          description: a valid AE title for the PACS archive
          required: true
          example: MY-STORAGE
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
        "400":
          description: Invalid supplied parameter
  /plugins:
    get:
      tags:
        - Management
      summary: Retrieve the list of existing plugins
      operationId: getPluginList
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  plugins:
                    $ref: "#/components/schemas/Plugins"
  /logger:
    get:
      tags:
        - Misc
      summary: Retrieve the Dicoogle server's log text
      operationId: getLogText
      responses:
        "200":
          description: Successful operation
          content:
            text/plain:
              schema:
                type: string
        "400":
          description: Invalid supplied parameters
  /index/task:
    get:
      tags:
        - Index
      summary: Get indexing tasks
      operationId: getIndexTasks
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TaskResults"
        "400":
          description: Invalid supplied parameters
    post:
      tags:
        - Index
      summary: Change an indexing task
      operationId: setIndexTask
      parameters:
        - in: query
          name: type
          description: the type of action to change the task
          required: true
          schema:
            type: string
        - in: query
          name: uid
          description: ""
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
        "400":
          description: Invalid supplied parameters
  /export/cvs:
    get:
      tags:
        - Misc
      summary: Request a CSV file export of the results
      operationId: exportCSV
      parameters:
        - in: query
          name: query
          description: the query to perform
          required: true
          schema:
            type: string
        - in: query
          name: fields
          description:
            a set of field names to be passed to the query providers when
            requesting the query
          required: true
          schema:
            type: string
        - in: query
          name: providers
          description: a set of query provider names
          required: false
          schema:
            type: string
        - in: query
          name: keyword
          description: force whether the query is keyword-based
          required: false
          schema:
            type: boolean
      responses:
        "200":
          description: Successful operation
        "400":
          description: Invalid supplied parameter
  /export/list:
    get:
      tags:
        - Misc
      summary: Get a list of known valid DICOM fields
      operationId: getValidDicomFields
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
  /management/settings/storage/dicom:
    get:
      tags:
        - Management
      summary: Get the currently associated remote servers
      operationId: getAssociatedServers
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RemoteServers"
        "400":
          description: Invalid supplied parameters
    post:
      tags:
        - Management
      summary: Associate or remove a remote server
      operationId: setAssociatedServer
      parameters:
        - in: query
          name: type
          description: whether the server is being associated or removed
          required: true
          schema:
            type: boolean
        - in: query
          name: ip
          description: ""
          required: true
          schema:
            type: string
        - in: query
          name: aetitle
          description: ""
          required: true
          schema:
            type: string
        - in: query
          name: port
          description: ""
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  tasks:
                    $ref: "#/components/schemas/Tasks"
        "400":
          description: Invalid supplied parameters
  /ext/version:
    get:
      tags:
        - Misc
      summary: Retrieve the running Dicoogle version
      operationId: getVersion
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Version"
        "400":
          description: Invalid supplied parameters
  /roi:
    get:
      tags:
        - Misc
      summary: Retrieve a rectangular region of a WSI
      operationId: getImageROI
      parameters:
        - in: query
          name: uid
          description: SOPInstanceUID
          required: true
          schema:
            type: string
        - in: query
          name: x
          description: left coordinate of the top left corner of the ROI in relation to the SOPInstanceUID provided
          required: true
          schema:
            type: number
        - in: query
          name: y
          description: top coordinate of the top left corner of the ROI in relation to the SOPInstanceUID provided
          required: true
          schema:
            type: number
        - in: query
          name: width
          description: Width of the ROI in pixels
          required: true
          schema:
            type: number
        - in: query
          name: height
          description: Height of the ROI in pixels
          required: true
          schema:
            type: number
      responses:
        "200":
          description: Successful operation
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
        "400":
          description: Invalid supplied parameters
        "404":
          description: SOPInstanceUID provided does not exist
    post:
      tags:
        - Misc
      summary: Retrieve an arbitrary region of a WSI
      operationId: postImageROI
      requestBody:
        description: Describes the region to extract
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                uid:
                  type: string
                  description: SOPInstanceUID
                type:
                  type: string
                  enum: [RECTANGLE, ELLIPSE, POLYGON, POLYLINE, POINT]
                points:
                  type: array
                  items:
                    type: object
                    description: A list of points that defines the shape to extract
                    properties:
                      x:
                        type: number
                      y:
                        type: number
      responses:
        "200":
          description: Successful operation
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
        "400":
          description: Invalid supplied parameters
        "404":
          description: SOPInstanceUID provided does not exist
  /ml/datastore:
    post:
      tags:
        - Machine Learning
      summary: "[EXPERIMENTAL] Datastore endpoint for machine learning providers, used to upload images and labels to services"
      operationId: mlDatastore
      requestBody:
        description: Describes the data to upload to the provider
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatastoreRequest'
      responses:
        '200':
          description: The datastore request was successfully processed and sent to the provider
        '400':
          description: Malformed request
  /ml/infer/single:
    post:
      tags:
        - Machine Learning
      summary: "[EXPERIMENTAL] Infer endpoint for a single object, image or DICOM object (series or sop instance). It has split functionality for WSI images."
      operationId: mlInferSingle
      parameters:
        - in: query
          name: provider
          description: The name of the provider, e.g "MONAI"
          required: true
          schema:
            type: string
        - in: query
          name: modelID
          description: Model identifier that will perform the inference
          required: true
          schema:
            type: string
        - in: query
          name: wsi
          description: Flag to identify WSI requests. Defaults to false.
          required: false
          schema:
            type: boolean
            default: false
        - in: query
          name: level
          description:
            The DIM level. Required if wsi is false
          required: false
          schema:
            type: string
            enum: [PATIENT, STUDY, SERIES, INSTANCE]
        - in: query
          name: uid
          description: The unique identifier of the DIM object. Required if wsi is false
          required: false
          schema:
            type: string
      responses:
        '200':
          description: The datastore request was successully processed and sent to the provider
          content:
            application/dicom:
              schema:
                type: string
                format: binary
                description: A DICOMSeg file
            multipart/form-data:
              schema:
                type: object
                properties:
                  params:
                    type: object
                    description: Extra information the inference might return
                  dicomseg:
                    type: string
                    format: binary
                    description: DICOMSeg file containing the segmentations returned by the inference
            application/json:
              schema:
                $ref: '#/components/schemas/MLInference'
        '400':
          description: Malformed request
  /ml/infer/bulk:
    post:
      tags:
        - Machine Learning
      summary: "[EXPERIMENTAL] Infer endpoint for a bulk of objects, images or DICOM objects (series or sop instance)"
      operationId: mlInferBulk
      responses:
        '501':
          description: Not implemented
  /ml/train:
    post:
      tags:
        - Machine Learning
      summary: "[EXPERIMENTAL] Request a training task"
      operationId: mlTrain
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrainRequest'
      responses:
        '200':
          description: The training request was successfully processed and sent to the provider
        '400':
          description: Malformed request
    delete:
      tags:
        - Machine Learning
      summary: "[EXPERIMENTAL] Cancel a training"
      operationId: mlCancelTrain
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrainRequest'
      responses:
        '200':
          description: The training request was successfully cancelled
        '400':
          description: Malformed request
  /ml/model/list:
    get:
      tags:
        - Machine Learning
      summary: "[EXPERIMENTAL] Get a list of models from all providers or a specific one"
      operationId: mlModelList
      parameters:
        - in: query
          name: provider
          description: The name of the provider to request the models from. If specified, only models from this provider are returned.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: The list of providers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MLProvider'
        '400':
          description: Malformed request
  /ml/model/info:
    get:
      tags:
        - Machine Learning
      summary: "[EXPERIMENTAL] Get training info a model"
      operationId: mlModelInfo
      parameters:
        - in: query
          name: provider
          description: The name of the provider, e.g "MONAI"
          required: true
          schema:
            type: string
        - in: query
          name: modelID
          description: Model identifier
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The training information of the specified model
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MLModelTrainInfo'
        '400':
          description: Malformed request
  /ml/cache:
    post:
      tags:
        - Machine Learning
      summary: "[EXPERIMENTAL] Cache DICOM objects on a provider"
      operationId: mlCache
      parameters:
        - in: query
          name: provider
          description: The name of the provider, e.g "MONAI"
          required: true
          schema:
            type: string
      requestBody:
        description: Contains the DICOM files to cache
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DICOMDataset'
      responses:
        '200':
          description: The cache request was successfully processed and sent to the provider
        '400':
          description: Malformed request
  /ml/provider/methods:
    get:
      tags:
        - Machine Learning
      summary: "[EXPERIMENTAL] Retrieves the implemented methods of the machine learning interface from a provider"
      operationId: mlCache
      parameters:
        - in: query
          name: provider
          description: The name of the provider, e.g "MONAI"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A list of the implemented methods
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '400':
          description: Malformed request

components:
  securitySchemes:
    dicoogle_auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: yourdicoogledomain/login
          scopes:
            user: perform operations as a regular user
            admin: perform administration operations
  schemas:
    Success:
      type: object
      properties:
        success:
          type: boolean
    User:
      type: object
      properties:
        username:
          type: string
    Users:
      type: array
      items:
        $ref: "#/components/schemas/User"
    FullUser:
      type: object
      properties:
        user:
          type: string
        admin:
          type: boolean
        roles:
          $ref: "#/components/schemas/ListOfStrings"
    Result:
      type: object
      properties:
        uri:
          type: string
          format: uri
          example: file:/root/CT/P9850721e/1.dcm
        fields:
          type: object
          properties:
            PatientID:
              type: string
              example: P9850721e
            SeriesDate:
              type: string
              example: "20150120"
            StudyDate:
              type: string
              example: "20150120"
            PatientName:
              type: string
              example: Doe^John
            StudyInstanceUID:
              type: string
              example: "1.2.345678.9999"
            SOPInstanceUID:
              type: string
              example: "1.2.345678.9999.1.1"
            Modality:
              type: string
              example: CT
            SeriesInstanceUID:
              type: string
              example: "1.2.345678.9999.1"
    Results:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: "#/components/schemas/Result"
        elapsedTime:
          type: integer
          example: 559
        numResults:
          type: integer
          example: 5
    DIMPatient:
      type: object
      required:
        - "id"
        - "name"
        - "birthdate"
        - "gender"
        - "nStudies"
        - "studies"
      properties:
        id:
          type: string
          description: The DICOM Patient ID
          example: "P123"
        name:
          type: string
          description: The DICOM Patient Name
        birthdate:
          type: string
          example: "19781023"
        gender:
          type: string
          description: The DICOM Patient Sex
          example: F
        nStudies:
          type: number
          format: i32
          example: 1
        studies:
          type: array
          items:
            $ref: "#/components/schemas/DIMStudy"
    DIMStudy:
      type: object
      required:
        - "institutionName"
        - "modalities"
        - "studyDate"
        - "studyDescription"
        - "series"
      properties:
        institutionName:
          type: string
          description: The DICOM Institution Name
        modalities:
          type: string
          example: "MG,US"
        studyDate:
          type: string
          description: The DICOM Study Date
          example: "20141029"
        studyDescription:
          type: string
          description: The DICOM Study Description
          example: "Routine scan"
        studyInstanceUID:
          type: string
          description: The DICOM Study Instance UID
          example: "1.2.876543.9999"
        series:
          type: array
          items:
            $ref: "#/components/schemas/DIMSeries"
    DIMSeries:
      type: object
      required:
        - "serieModality"
        - "serieInstanceUID"
        - "serieNumber"
        - "serieDescription"
        - "images"
      properties:
        serieModality:
          type: string
          description: The DICOM Modality
          example: "MG"
        serieInstanceUID:
          type: string
          description: The DICOM Series Instance UID
          example: "1.2.876543.9999.1"
        serieNumber:
          type: number
          description: The DICOM Series Number
          example: 1
        serieDescription:
          type: string
          description: The DICOM Series Description
          example: "routine breast x-ray scan"
        images:
          type: array
          items:
            $ref: "#/components/schemas/DIMInstance"
    DIMInstance:
      type: object
      required:
        - "uri"
        - "filename"
        - "rawPath"
        - "sopInstanceUID"
      properties:
        filename:
          type: string
          example: "1_1.dcm"
        number:
          type: number
          example: 1
        rawPath:
          type: string
          example: "/root/MG/123/1_1.dcm"
        sopInstanceUID:
          type: string
          description: The DICOM SOP Instance UID
          example: "1.2.876543.9999.1.1"
        uri:
          type: string
          example: "file:/root/MG/123/1_1.dcm"
    DIMResults:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: "#/components/schemas/DIMPatient"
        elapsedTime:
          type: integer
          example: 5
        numResults:
          type: integer
          example: 1
    IndexSettings:
      type: object
      properties:
        path:
          type: string
          example: /tmp
        zip:
          type: boolean
          example: false
        effort:
          type: string
          description: "Indexing effort, as an integer between 0 and 100"
          example: "100"
        thumbnail:
          type: boolean
          example: true
        thumbnailSize:
          type: string
          example: "64"
        watcher:
          type: boolean
          example: false
    QuerySettings:
      type: object
      properties:
        acceptTimeout:
          type: integer
          example: 60
        connectionTimeout:
          type: integer
          example: 60
        idleTimeout:
          type: integer
          example: 60
        maxAssociations:
          type: integer
          example: 20
        maxPduReceive:
          type: integer
          example: 16364
        maxPduSend:
          type: integer
          example: 6364
        responseTimeout:
          type: integer
          example: 0
    Task:
      type: object
      properties:
        canceled:
          type: boolean
          example: false
        done:
          type: boolean
          example: false
        name:
          type: string
          example: "[lucene]index storage/"
        progress:
          type: integer
          example: 0
        uid:
          type: string
          example: 5c5f36ec-a946-49db-b903-e815e2f08dee
    Tasks:
      type: array
      items:
        $ref: "#/components/schemas/Task"
    ServiceStatus:
      type: object
      required:
        - isRunning
        - port
        - autostart
      properties:
        isRunning:
          description: Whether the service is running
          type: boolean
          example: true
        port:
          description: TCP port that the service is listening to
          type: integer
          example: 6666
        hostname:
          description: Hostname or IP address that the service is bound to
          type: string
          example: 127.0.0.1
        autostart:
          description: Whether this service starts on boot
          type: boolean
          example: true
    AETitle:
      type: object
      properties:
        aetitle:
          type: string
          description: Application Entity title
          example: DICOOGLE-STORAGE
    Plugin:
      type: object
      properties:
        name:
          type: string
          example: lucene
        type:
          type: string
          example: query
        enabled:
          type: boolean
          example: true
    Plugins:
      type: array
      items:
        $ref: "#/components/schemas/Plugin"
    TaskResult:
      type: object
      properties:
        uid:
          type: string
          example: 92b099fe-eea1-49bd-9a84-b3d0d6135c37
        taskName:
          type: string
          example: "[lucene]index"
        taskTimeCreated:
          type: string
          example: "2022-07-05T14:48:50.49"
        taskProgress:
          type: number
          example: 1.0
        complete:
          type: boolean
          example: true
        elapsedTime:
          type: integer
          example: 9
        nIndexed:
          type: integer
          example: 3
        nErrors:
          type: integer
          example: 0
    TaskResults:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: "#/components/schemas/TaskResult"
        count:
          type: integer
          example: 1
    RemoteServer:
      type: object
      properties:
        AETitle:
          type: string
        description:
          type: string
        ipAddrs:
          type: string
        isPublic:
          type: boolean
        port:
          type: integer
        public:
          type: boolean
    RemoteServers:
      type: array
      items:
        $ref: "#/components/schemas/RemoteServer"
    TransferSyntaxSettingsOption:
      type: object
      properties:
        name:
          type: string
        value:
          type: boolean
    TransferSyntaxSettings:
      type: object
      properties:
        uid:
          type: string
        sop_name:
          type: string
        options:
          type: array
          items:
            $ref: "#/components/schemas/TransferSyntaxSettingsOption"
    TransferSyntaxSettingsList:
      type: array
      items:
        $ref: "#/components/schemas/TransferSyntaxSettings"
    Version:
      type: object
      properties:
        version:
          type: string
    ListOfStrings:
      type: array
      items:
        type: string
    DatastoreRequest:
      type: object
      properties:
        provider:
          type: string
          description: Provider name
          example: MONAI
        dataType:
          type: string
          enum: [CSV, IMAGE, DICOM]
        dimLevel:
          type: string
          enum: [PATIENT, STUDY, SERIES, INSTANCE]
        uids:
          type: array
          items:
            type: string
        dataset:
          type: object
          description: A map where keys represent SOPInstances and the values are annotations to upload
    DICOMDataset:
      type: object
      properties:
        level:
          type: string
          enum: [PATIENT, STUDY, SERIES, INSTANCE]
        dimUIDs:
          type: array
          items:
            type: string
    TrainRequest:
      type: object
      properties:
        provider:
          type: string
          description: Provider name
          example: MONAI
        modelID:
          type: string
          description: Model identifier
          example: spleen_model
    MLInference:
      type: object
      properties:
        metrics:
          type: object
          description: A key-value dictionary of extra metrics the inference might return
        version:
          type: string
          description: Version of the model that generated this inference
        annotations:
          type: array
          description: A list of annotations
          items:
            type: object
    MLProvider:
      type: object
      properties:
        name:
          type: string
          description: The name of this provider
        models:
          type: array
          items:
            type: object
          description: A list of models that belongs to this provider
        datasets:
          type: array
          items:
            type: object
          description: A list of datasets that belongs to this provider
    MLModelTrainInfo:
      type: object
      properties:
        modifiedTime:
          type: string
        startTime:
          type: string
        currentEpoch:
          type: number
        totalEpochs:
          type: number
        bestMetric:
          type: number
          description: Numerical value of the best metric identifier by the best metric key.
        bestMetricKey:
          type: string
        metrics:
          type: object
          description: A key-value containing the training metrics of the model, such as accuracy, precision, f1-score, etc.