openapi: 3.2.0
info:
  description: MISO Public Specification to support Market System Enhancement (MSE) new Market User Interface (MUI 2.0).
  title: MUI - Public Specification Admin API
  contact:
    name: MUI 2.0 Questions
    url: https://www.misoenergy.org/markets-and-operations/MSE/market-user-interface/
    email: MSEQuestions@misoenergy.org
  license:
    name: For use by MISO member companies and thier vendors
  version: 3.3.0
servers:
- url: https://cce.midwestiso.org/dart2/
- url: https://markets.midwestiso.org/dart2/
tags:
- name: Admin
paths:
  /markets/common/{day}/mui-meta/participants/{participantName}:
    description: Return particiant specific MUI metadata.
    parameters:
    - $ref: '#/components/parameters/x-acting-participant'
    get:
      tags:
      - Admin
      description: 'Return participant specific MUI metadata. Metadata returned by this call includes:

        1. Participant Control Areas - Control Areas administered by a particular participant. If the participant

        does not administer any control area or is invalid participant then an empty list is returned. A control area

        is included if the participant is active from day specified through the end of the market horizon.

        '
      operationId: getParticipantMetadata
      parameters:
      - $ref: '#/components/parameters/MarketOperatingDay'
      - $ref: '#/components/parameters/Participant'
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParticipantMetadata'
          headers:
            http-x-request-id:
              $ref: '#/components/headers/http-x-request-id'
        '400':
          $ref: '#/components/responses/BadRequestApiResponse'
        '403':
          $ref: '#/components/responses/UnauthorizedApiResponse'
        '404':
          $ref: '#/components/responses/NotFoundApiResponse'
        '500':
          $ref: '#/components/responses/InternalErrorApiResponse'
  /markets/common/{day}/mui-meta:
    description: Returns general MUI metadata that is not participant specific.
    parameters:
    - $ref: '#/components/parameters/x-acting-participant'
    get:
      tags:
      - Admin
      description: 'Return general MUI metadata, that is not participant specific. Metadata returned by this call includes:

        1. Reserve Zones - List of reserve zones available in the system. A reserve zone can appear in this list and still not have any EPnodes assigned to it so it may not appear in reports.

        2. List of Market Participants - The list of Market Participants is used when updating bilateral contracts.

        3. List of Dispatch Status - List of valid Dispatch Status values organized by unit offer type (GEN, DIR, DRR1, DRR2, EAR, SER).

        4. List of Commit Status - List of valid Commit Status values organized by unit offer type (GEN, DIR, DRR1, DRR2, EAR, SER).

        5. List of RT Offer Override Reasons - List of RT Offer Override Reasons organized by unit offer type (GEN, DIR, DRR1, DRR2, EAR, SER).

        6. List of Market Options - List of Market Options which impact MUI behavior provided as name value pairs.

        7. List of CostSchedule Types - List of cost schedule for the Day-Ahead and Balancing (Real-Time) markets.

        '
      operationId: getMuiMetadata
      parameters:
      - $ref: '#/components/parameters/MarketOperatingDay'
      - name: metadataGroups
        description: Metadata group.
        in: query
        required: false
        schema:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/MetadatGroups'
        style: form
        explode: false
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MuiMetadata'
          headers:
            http-x-request-id:
              $ref: '#/components/headers/http-x-request-id'
        '400':
          $ref: '#/components/responses/BadRequestApiResponse'
        '403':
          $ref: '#/components/responses/UnauthorizedApiResponse'
        '404':
          $ref: '#/components/responses/NotFoundApiResponse'
        '500':
          $ref: '#/components/responses/InternalErrorApiResponse'
  /markets/portfolios/participants/{participantName}:
    description: Returns pnodes in all portfolios for a participant with an optional filter on day and details to limit what effective pnodes and how much pnode information is included.
    parameters:
    - $ref: '#/components/parameters/x-acting-participant'
    get:
      tags:
      - Admin
      description: Returns pnodes in all portfolios for a participant with an optional filter on day and details to limit what effective pnodes and how much pnode information is included.
      operationId: getParticipantPortfolios
      parameters:
      - $ref: '#/components/parameters/Participant'
      - name: portfolio
        description: Optional parameter to specify an individual Portfolio to return, otherwise return all.
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/PortfolioName'
      - name: details
        description: Flag to enable querying of pnode and unit details. Defaults to false if not provided.
        in: query
        required: false
        schema:
          type: string
          enum:
          - 'false'
          - 'true'
      - name: day
        description: The operating day for which active pnodes in portfolios will be returned. Defaults to null (unspecified) if not provided.
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/MarketOperatingDay'
      - name: context
        description: Context filter for the report.
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ContextFilter'
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrievedPortfolios'
          headers:
            http-x-request-id:
              $ref: '#/components/headers/http-x-request-id'
        '400':
          $ref: '#/components/responses/BadRequestApiResponse'
        '403':
          $ref: '#/components/responses/UnauthorizedApiResponse'
        '404':
          $ref: '#/components/responses/NotFoundApiResponse'
        '500':
          $ref: '#/components/responses/InternalErrorApiResponse'
  /markets/portfolios/participants/{participantName}/{action}:
    description: Returns pnodes for a specific Portfolio with an optional filter on day and details to limit what effective pnodes and how much pnode information is included.
    parameters:
    - $ref: '#/components/parameters/x-acting-participant'
    post:
      tags:
      - Admin
      description: Creates or updates or removes a participant Portfolio.
      operationId: postPortfolios
      parameters:
      - $ref: '#/components/parameters/Participant'
      - name: action
        description: An operation to execute.
        in: path
        required: true
        schema:
          type: string
          enum:
          - create
          - replace
          - remove
      responses:
        '200':
          $ref: '#/components/responses/OkApiResponse'
        '400':
          $ref: '#/components/responses/BadRequestApiResponse'
        '403':
          $ref: '#/components/responses/UnauthorizedApiResponse'
        '404':
          $ref: '#/components/responses/NotFoundApiResponse'
        '500':
          $ref: '#/components/responses/InternalErrorApiResponse'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Portfolio'
  /markets/swagger/v3/api-docs/json/{spec}:
    description: Returns the swagger spec in json format.
    parameters:
    - $ref: '#/components/parameters/x-acting-participant'
    get:
      tags:
      - Admin
      description: Returns the swagger spec in json format.
      operationId: getSwaggerSpecJson
      parameters:
      - name: spec
        description: Internal or Public specification.
        in: path
        required: true
        schema:
          type: string
          enum:
          - public
          - internal
      responses:
        '200':
          description: Successful operation. Returns an OpenAPI/Swagger spec in json.
          content:
            application/json:
              schema:
                type: object
          headers:
            http-x-request-id:
              $ref: '#/components/headers/http-x-request-id'
        '400':
          $ref: '#/components/responses/BadRequestApiResponse'
        '403':
          $ref: '#/components/responses/UnauthorizedApiResponse'
        '404':
          $ref: '#/components/responses/NotFoundApiResponse'
        '500':
          $ref: '#/components/responses/InternalErrorApiResponse'
  /markets/swagger/v3/api-docs/yaml/{spec}:
    description: Returns the swagger spec in yaml format.
    parameters:
    - $ref: '#/components/parameters/x-acting-participant'
    get:
      tags:
      - Admin
      description: Returns the swagger spec in yaml format.
      operationId: getSwaggerSpecYaml
      parameters:
      - name: spec
        description: Internal or Public specification.
        in: path
        required: true
        schema:
          type: string
          enum:
          - public
          - internal
      responses:
        '200':
          description: Successful operation. Returns an OpenAPI/Swagger spec in yaml.
          content:
            application/x-yaml:
              schema:
                type: object
          headers:
            http-x-request-id:
              $ref: '#/components/headers/http-x-request-id'
        '400':
          $ref: '#/components/responses/BadRequestApiResponse'
        '403':
          $ref: '#/components/responses/UnauthorizedApiResponse'
        '404':
          $ref: '#/components/responses/NotFoundApiResponse'
        '500':
          $ref: '#/components/responses/InternalErrorApiResponse'
components:
  schemas:
    MarketOperatingDay:
      description: Effective Market operating day of data. RFC 3339. 'YYYY-MM-DD'.
      type: string
      format: date
      example: '2019-03-14'
    PNodeName:
      description: Commercial Pricing Node (PNode) name.
      type: string
      minLength: 1
      maxLength: 30
      example: PNODE1
    ParticipantName:
      description: Market participant name.
      type: string
      minLength: 1
      maxLength: 40
      example: MP
    APIResponse:
      description: General container for API response.
      type: object
      properties:
        action:
          description: A general action code summary of the result. HTTP status codes will be applied that match. These indicate the type of operation that was done (or not). Note, some APIs use REST verbiage like created/updated/deleted while others use submit/query.
          enum:
          - CREATED
          - UPDATED
          - DELETED
          - CREATE_FAILED
          - UPDATE_FAILED
          - DELETE_FAILED
          - GET_FAILED
          - SUBMITTED
          - SUBMIT_FAILED
          - QUERY
          - QUERY_FAILED
        responses:
          description: List of responses in case multiple resources are modified, or general errors that are not resource specific.
          type: array
          minItems: 0
          items:
            description: A single response which may contain multiple messages, both error and warning, per response.
            type: object
            properties:
              messages:
                description: List of warnings and errors resulting from the command.
                type: array
                minItems: 0
                items:
                  description: An individual warning or error message.  Designed to be either localized or categorized as an event.
                  type: object
                  properties:
                    level:
                      description: An indication of severity of the message.
                      type: string
                      enum:
                      - ERROR
                      - WARNING
                      - INFO
                    msgId:
                      description: A categorized ID for this message, identifying it as a particular type of event. Useful for checking for specific errors, or localization.
                      type: string
                    params:
                      description: Ordered list of parameter values for the message.
                      type: array
                      items:
                        type: string
                    userMsg:
                      description: The message, fully rendered in the default locale on the service side.
                      type: string
        transactionId:
          description: Unique identifier for the transaction which can be queried at a later date. Identifier is a GUID represented without hyphens. Only returned for submissions and errors though all calls generate a transaction ID that is returned in the http-x-request-id response header.
          type: string
          format: guid
        transactionTime:
          description: The time at which the transaction was received by the system.
          type: string
          format: date-time
    MarketType:
      description: Energy Market types.
      type: string
      enum:
      - day-ahead
      - real-time
    MetadatGroups:
      description: Mui Meta-data groups.
      type: string
      enum:
      - ReserveZones
      - Participants
      - CommitStatus
      - DispatchStatus
      - RealTimeOfferOverrideReasons
      - MarketOptions
      - CostScheduleTypes
    Portfolio:
      description: A single submitted portfolio. Each portfolio is a named association of resource pricing node (pnode) locations. A portfolio can contain resource pnode locations for generator units, demand response resources, and other pnodes.
      type: object
      properties:
        name:
          $ref: '#/components/schemas/PortfolioName'
        portfolioLocations:
          description: A list of pnodes identified by name.
          type:
          - array
          - 'null'
          items:
            type: object
            additionalProperties: false
            properties:
              name:
                $ref: '#/components/schemas/PNodeName'
      required:
      - name
      - portfolioLocations
    ContextFilter:
      description: Context filter for the report.
      type: string
      enum:
      - System
      - Portfolio
      - FinSched
      - Supply
      - DemandBid
      - VirtualBid
      - VirtualOffer
      - Lmp
      example: System
    ParticipantMetadata:
      description: MUI and participant metadata.
      type: object
      properties:
        day:
          $ref: '#/components/schemas/MarketOperatingDay'
        participantControlAreas:
          description: Control Areas administered by a particular participant.
          type: array
          items:
            type: object
            properties:
              areaShortName:
                type: string
                example: Area1
              internalArea:
                type: boolean
                example: true
      required:
      - day
      - participantControlAreas
    PortfolioName:
      description: Portfolio name which is unique to a participant company and may be shared among users registered with the same company.
      type: string
      minLength: 1
      maxLength: 40
      example: Sample Portfolio
    MuiMetadata:
      description: General MUI Meta Data, that is not participant specific.
      type: object
      properties:
        day:
          $ref: '#/components/schemas/MarketOperatingDay'
        reserveZones:
          type: array
          items:
            type: object
            properties:
              zone:
                $ref: '#/components/schemas/ReserveZone'
              zoneName:
                type: string
                example: NonZone
        participants:
          type: array
          items:
            $ref: '#/components/schemas/ParticipantName'
        commitStatus:
          type: array
          items:
            type: object
            properties:
              commitStatus:
                type: string
                example: EC
              commitStatusCode:
                type: string
                example: '1'
              commitStatusDesc:
                type: string
                example: Economic
              unitType:
                type: string
                example: DRR1
        dispatchStatus:
          type: array
          items:
            type: object
            properties:
              dispatchStatus:
                type: string
                example: EC
              dispatchStatusCode:
                type: string
                example: '1'
              dispatchStatusDesc:
                type: string
                example: Economic
              dispatchStatusType:
                type: string
                example: SPIN
              unitType:
                type: string
                example: DRR1
        rtOfferOverrideReason:
          type: array
          items:
            type: object
            properties:
              unitType:
                type: string
                example: DRR1
              reasonCode:
                type: string
                example: BoilerTubeLeak
              reasonDesc:
                type: string
                example: Boiler Tube Leak
        marketOptions:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                example: NotificationKeepDays
              value:
                type: string
                example: '4'
        costScheduleTypes:
          type: array
          items:
            type: object
            properties:
              unitScheduleTypeId:
                type: integer
                example: 31
              unitScheduleTypeDesc:
                type: string
                example: DayAhead Mitigated Cost 31
              marketType:
                $ref: '#/components/schemas/MarketType'
      required:
      - day
    ReserveZone:
      description: Used to represent a reserve zone.
      type: number
      minimum: 1
      maximum: 999
      example: 1
    RetrievedPortfolios:
      description: A list of portfolios.
      type: array
      items:
        description: A single retrieved portfolio. Each portfolio is a named association of resource pricing node (pnode) locations. A portfolio can contain resource pnode locations for generator units, demand response resources, and other pnodes. Can include additional metadata about the pnode depending on query parameters provided.
        type: object
        properties:
          name:
            $ref: '#/components/schemas/PortfolioName'
          portfolioLocations:
            description: Participant pnodes.
            type: array
            items:
              type: object
              additionalProperties: false
              properties:
                name:
                  $ref: '#/components/schemas/PNodeName'
                pnodeType:
                  type: string
                  enum:
                  - Aggregate
                  - Bus
                  - Hub
                  - Interface
                  - Zone
                  - 500 KV
                virtualIncBidsAllowed:
                  type: boolean
                  example: true
                virtualDecBidsAllowed:
                  type: boolean
                  example: true
                unitOfferType:
                  type: string
                  enum:
                  - GEN
                  - DIR
                  - DRR1
                  - DRR2
                  - EAR
                  - ESR
                  - SER
                  - NA
                intermittentStatus:
                  type: string
                  enum:
                  - Dispatchable
                  - Intermittent
                  - Non-Intermittent
                  - NA
        required:
        - name
        - portfolioLocations
  headers:
    http-x-request-id:
      description: Response header contains a unique transaction identifier assigned by MUI. Identifier is a GUID represented without hyphens.
      schema:
        type: string
        format: guid
      example: 34571c664e48ca0b1e30d7ffb9b3b287
  responses:
    InternalErrorApiResponse:
      description: Internal error occurred, details in server-side logs.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIResponse'
          example:
            action: <action enum>
            responses:
            - messages:
              - level: ERROR
                msgId: MESSAGE_ID
                params: []
                userMsg: Internal error message for MESSAGE_ID.
            transactionId: 34571c664e48ca0b1e30d7ffb9b3b287
            transactionTime: '2020-07-02T17:45:00-05:00'
      headers:
        http-x-request-id:
          $ref: '#/components/headers/http-x-request-id'
    BadRequestApiResponse:
      description: User error. Request was invalid for some reason. See response for details.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIResponse'
          example:
            action: <action enum>
            responses:
            - messages:
              - level: ERROR
                msgId: MESSAGE_ID
                params: []
                userMsg: Bad request message for MESSAGE_ID.
            transactionId: 34571c664e48ca0b1e30d7ffb9b3b287
            transactionTime: '2020-07-02T17:45:00-05:00'
      headers:
        http-x-request-id:
          $ref: '#/components/headers/http-x-request-id'
    OkApiResponse:
      description: Successful operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIResponse'
          example:
            action: <action enum>
            responses: []
            transactionId: 34571c664e48ca0b1e30d7ffb9b3b287
            transactionTime: '2020-07-02T17:45:00-05:00'
      headers:
        http-x-request-id:
          $ref: '#/components/headers/http-x-request-id'
    UnauthorizedApiResponse:
      description: Rejected due to insufficient permissions.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIResponse'
          example:
            action: <action enum>
            responses:
            - messages:
              - level: ERROR
                msgId: MESSAGE_ID
                params: []
                userMsg: Unauthorized message for MESSAGE_ID.
            transactionId: 34571c664e48ca0b1e30d7ffb9b3b287
            transactionTime: '2020-07-02T17:45:00-05:00'
      headers:
        http-x-request-id:
          $ref: '#/components/headers/http-x-request-id'
    NotFoundApiResponse:
      description: Resource not found. The path provided does not point to an entity in the system.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIResponse'
          example:
            action: <action enum>
            responses:
            - messages:
              - level: ERROR
                msgId: MESSAGE_ID
                params: []
                userMsg: Not found message for MESSAGE_ID.
            transactionId: 34571c664e48ca0b1e30d7ffb9b3b287
            transactionTime: '2020-07-02T17:45:00-05:00'
      headers:
        http-x-request-id:
          $ref: '#/components/headers/http-x-request-id'
  parameters:
    x-acting-participant:
      in: header
      name: x-acting-participant
      description: Header to override default acting participant of NERC ID. Will be validated against participant collection resource when specified in path.
      schema:
        type: string
      example: MP
    MarketOperatingDay:
      in: path
      name: day
      description: The operating day of the data.
      required: true
      schema:
        $ref: '#/components/schemas/MarketOperatingDay'
    Participant:
      in: path
      name: participantName
      description: The NERC ID of asset owner specified in the path for a collection resource.
      required: true
      schema:
        $ref: '#/components/schemas/ParticipantName'