---
openapi: 3.0.0
info:
  title: pydss RESTful API documentation
  version: 3.0.2
  description: The API enables creating pydss instances, running simulations and creation
    of new projects.
paths:
  "/simulators/pydss/instances":
    head:
      summary: Returns UUIDs of all the instances currently running on the server
      tags:
      - simulation status
      responses:
        '200':
          description: UUIDs of all currently running pydss instances have been returned
          content:
            application/json:
              schema:
                type: object
              examples:
                get_instance_status:
                  value:
                    Status: 200
                    Message: 2 pydss instances currently running
                    UUID: []
        '204':
          description: No active pydss instance found
          content:
            application/json:
              schema:
                type: object
              examples:
                get_instance_status:
                  value:
                    Status: 204
                    Message: No pydss instance currently running
                    UUID:
                    - 96c21e00-cd3c-4943-a914-14451f5f7ab6
                    - 96c21e045-cd6c-8394-a914-14451f5f7ab6
    get:
      summary: Returns UUIDs of all the instances currently running on the server
      tags:
      - simulation status
      responses:
        '200':
          description: UUIDs of all currently running pydss instances have been returned
          content:
            application/json:
              schema:
                type: object
              examples:
                get_instance_status:
                  value:
                    Status: 200
                    Message: 2 pydss instances currently running
                    UUID: []
        '204':
          description: No active pydss instance found
          content:
            application/json:
              schema:
                type: object
              examples:
                get_instance_status:
                  value:
                    Status: 204
                    Message: No pydss instance currently running
                    UUID:
                    - 96c21e00-cd3c-4943-a914-14451f5f7ab6
                    - 96c21e045-cd6c-8394-a914-14451f5f7ab6
  "/simulators/pydss/status/uuid/{uuid}":
    head:
      summary: Returns states of process of with UUID matching the passed UUID
      tags:
      - simulation status
      parameters:
      - name: uuid
        in: path
        required: true
        schema:
          type: string
          format: uuid
          example: 96c21e00-cd3c-4943-a914-14451f5f7ab6
        style: simple
        explode: false
      responses:
        '200':
          description: pydss instance with the provided UUID is currently running
          content:
            application/json:
              schema:
                type: object
              examples:
                get_instance_status:
                  value:
                    Status: 200
                    Message: pydss instance with the provided UUID is currently running
                    UUID: 96c21e00-cd3c-4943-a914-14451f5f7ab6
        '204':
          description: pydss instance with the provided UUID does not exist
          content:
            application/json:
              schema:
                type: object
              examples:
                get_instance_status:
                  value:
                    Status: 204
                    Message: pydss instance with the provided UUID does not exist
                    UUID: None
    get:
      summary: Returns states of process of with UUID matching the passed UUID
      tags:
      - simulation status
      parameters:
      - name: uuid
        in: path
        required: true
        schema:
          type: string
          format: uuid
          example: 96c21e00-cd3c-4943-a914-14451f5f7ab6
        style: simple
        explode: false
      responses:
        '200':
          description: pydss instance with the provided UUID is currently running
          content:
            application/json:
              schema:
                type: object
              examples:
                get_instance_status:
                  value:
                    Status: 200
                    Message: pydss instance with the provided UUID is currently running
                    UUID: 96c21e00-cd3c-4943-a914-14451f5f7ab6
        '204':
          description: pydss instance with the provided UUID does not exist
          content:
            application/json:
              schema:
                type: object
              examples:
                get_instance_status:
                  value:
                    Status: 204
                    Message: pydss instance with the provided UUID does not exist
                    UUID: None
  "/simulators/pydss/info":
    head:
      summary: Returns a dictionary of valid project and scenarios in the provided
        path
      tags:
      - pydss project
      parameters:
      - name: path
        in: query
        required: true
        schema:
          type: string
          example: C:/Users/alatif/Desktop/pydss_2.0/pydss/examples
        style: form
        explode: true
      responses:
        '200':
          description: Successfully retrieved project information
          content:
            application/json:
              schema:
                type: object
              examples:
                get_instance_status:
                  value:
                    Status: 200
                    Message: pydss instance with the provided UUID is currently running
                    UUID: 96c21e00-cd3c-4943-a914-14451f5f7ab6
                    Data:
                      Project1:
                        Scenario1: 
                        Scenario2: 
                      Project2:
                        Scenario1: 
        '406':
          description: Provided path does not exist
          content:
            application/json:
              schema:
                type: object
              examples:
                get_instance_status:
                  value:
                    Status: 406
                    Message: Provided path does not exist
                    UUID: None
    get:
      summary: Returns a dictionary of valid project and scenarios in the provided
        path
      tags:
      - pydss project
      parameters:
      - name: path
        in: query
        required: true
        schema:
          type: string
          example: C:/Users/alatif/Desktop/pydss_2.0/pydss/examples
        style: form
        explode: true
      responses:
        '200':
          description: Successfully retrieved project information
          content:
            application/json:
              schema:
                type: object
              examples:
                get_instance_status:
                  value:
                    Status: 200
                    Message: pydss instance with the provided UUID is currently running
                    UUID: 96c21e00-cd3c-4943-a914-14451f5f7ab6
                    Data:
                      Project1:
                        Scenario1: 
                        Scenario2: 
                      Project2:
                        Scenario1: 
        '406':
          description: Provided path does not exist
          content:
            application/json:
              schema:
                type: object
              examples:
                get_instance_status:
                  value:
                    Status: 406
                    Message: Provided path does not exist
                    UUID: None
  "/simulators/pydss":
    put:
      summary: Run a command on an active instance of pydss
      tags:
      - Simulation
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                uuid:
                  type: string
                  format: UUID
                  example: 96c21e00-cd3c-4943-a914-14451f5f7ab6
                command:
                  type: string
                  example: initialize
                parameters:
                  type: object
            examples:
              Example_1:
                value:
                  UUID: 96c21e00-cd3c-4943-a914-14451f5f7ab6
                  command: run
                  parameters: {}
        required: false
      responses:
        '200':
          description: Successfully retrieved project information
          content:
            application/json:
              schema:
                type: object
              examples:
                get_instance_status:
                  value:
                    Status: 200
                    Message: Command submitted, awaiting response
                    UUID: 96c21e00-cd3c-4943-a914-14451f5f7ab6
        '401':
          description: Provided path does not exist
          content:
            application/json:
              schema:
                type: object
              examples:
                get_instance_status:
                  value:
                    Status: 401
                    Message: Please provide a command and parameters
                    UUID: None
        '403':
          description: Provided path does not exist
          content:
            application/json:
              schema:
                type: object
              examples:
                get_instance_status:
                  value:
                    Status: 403
                    Message: Provided UUID is not valid pydss instance id
                    UUID: None
    post:
      summary: Creates an instance of pydss and runs the simulation
      tags:
      - Simulation
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                parameters:
                  type: object
            examples:
              Example 1:
                value:
                  parameters:
                    Start Year: 2017
                    Start Day: 1
                    Start Time (min): 0
                    End Day: 1
                    End Time (min): 1439
                    Date offset: 0
                    Step resolution (sec): 900
                    Max Control Iterations: 50
                    Error tolerance: 0.001
                    Control mode: Static
                    Simulation Type: QSTS
                    Project Path: C:/Users/alatif/Desktop/pydss_2.0/pydss/examples
                    Active Project: custom_contols
                    Active Scenario: base_case
                    DSS File: Master_Spohn_existing_VV.dss
                    Co-simulation Mode: false
                    Log Results: false
                    Export Data Tables: true
                    Export Data In Memory: true
                    Federate name: pydss_x
        required: false
      responses:
        '200':
          description: Successfully retrieved project information
          content:
            application/json:
              schema:
                type: object
              examples:
                get_instance_status:
                  value:
                    Status: 200
                    Message: Starting a pydss instance
                    UUID: 96c21e00-cd3c-4943-a914-14451f5f7ab6
        '500':
          description: Provided path does not exist
          content:
            application/json:
              schema:
                type: object
              examples:
                get_instance_status:
                  value:
                    Status: 500
                    Message: Failed to create a pydss instance
                    UUID: None
    delete:
      summary: Deletes an active instance of pydss
      tags:
      - Simulation
      parameters:
      - name: uuid
        in: path
        required: true
        schema:
          type: string
          format: uuid
          example: 96c21e00-cd3c-4943-a914-14451f5f7ab6
        style: simple
        explode: false
      responses:
        '200':
          description: Successfully retrieved project information
          content:
            application/json:
              schema:
                type: object
              examples:
                get_instance_status:
                  value:
                    Status: 200
                    Message: Successfully deleted a pydss instance
                    UUID: 96c21e00-cd3c-4943-a914-14451f5f7ab6
        '403':
          description: Provided path does not exist
          content:
            application/json:
              schema:
                type: object
              examples:
                get_instance_status:
                  value:
                    Status: 403
                    Message: Error closing pydss instance
                    UUID: None
  "/simulators/pydss/create":
    post:
      summary: Creates a new project for pydss (User uploads a zipped OpenDSS model)
      tags:
      - pydss project
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                master_file:
                  type: string
                  example: Master_Spohn_existing_VV.dss
                project:
                  type: string
                  example: test_project
                scenarios:
                  type: string
                  description: comma separated list of pydss scenarios to be created
                  example: base_case,pv_scenario
                controller_types:
                  type: string
                  description: comma separated list of pydss controller names
                  example: PvController,StorageController
                visualization_types:
                  type: string
                  description: comma separated list of pydss plot names
                  example: Histogram,TimeSeries
                fileName:
                  type: string
                  format: binary
        required: false
      responses:
        '200':
          description: Successfully retrieved project information
          content:
            application/json:
              schema:
                type: object
              examples:
                get_instance_status:
                  value:
                    Status: 200
                    Message: pydss project created
                    UUID: None
        '403':
          description: Provided path does not exist
          content:
            application/json:
              schema:
                type: object
              examples:
                get_instance_status:
                  value:
                    Status: 403
                    Message: User does not have access to delete folders
                    UUID: None