Lunar Energy Diff Requests API

openapi: 3.2.0
info:
  title: Gridshare Partner Diff Requests API
  description: 'The Gridshare Partner API is Lunar Energy''s operator-facing surface for

    utilities, retailers, and DER aggregators managing residential

    distributed energy resources at fleet scale. Covers Sites, Devices,

    Telemetry, Operation Mode, Overlay Plans, Periodical Tariffs, Dynamic

    Tariffs, Flex Groups, Flex Events, Flex Dispatches, Prognoses with

    Diff Requests and Diff Orders, Counterfactuals, and on-site Visits.


    Authentication is OAuth 2.0 client-credentials against an Amazon Cognito

    user pool. Tokens expire after 1 hour and are sent as

    `Authorization: Bearer <access_token>` on every request.

    '
  version: v1.0
  contact:
    name: Lunar Energy
    url: https://www.gridshare.com
    email: developers@gridshare.com
  x-logo:
    url: https://www.lunarenergy.com/favicon.ico
servers:
- url: https://developer-api.partner.us.mygridshare.com
  description: Production server (US)
- url: https://developer-api.partner.mygridshare.com
  description: Production server (Rest of World)
- url: https://developer-api.partner.dev0.us.mygridshare.com
  description: Development server (US)
- url: https://developer-api.partner.dev0.mygridshare.com
  description: Development server (Rest of World)
security:
- bearerAuth: []
tags:
- name: Diff Requests
  description: Request and commit differential adjustments to a prognosis
paths:
  /api/v1/prognoses/{prognosisId}/prognosisdiffrequests:
    parameters:
    - in: path
      name: prognosisId
      required: true
      schema:
        type: string
    post:
      operationId: createPrognosisDiffRequest
      summary: Create Prognosis Diff Request
      description: 'Request a modification to a prognosis profile. Allows charging or

        discharging to the network in a coordinated manner by submitting a

        differential profile over the original prognosis. Asynchronous —

        poll the Diff Request endpoint for status.

        '
      tags:
      - Diff Requests
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrognosisDiffRequest'
      responses:
        '202':
          description: Accepted
  /api/v1/prognosisdiffrequests/{prognosisDiffRequestId}:
    parameters:
    - in: path
      name: prognosisDiffRequestId
      required: true
      schema:
        type: string
    get:
      operationId: getPrognosisDiffRequest
      summary: Get Prognosis Diff Request
      description: Poll status and feasible offer for a prognosis diff request.
      tags:
      - Diff Requests
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrognosisDiffRequest'
  /api/v1/prognosisdiffrequests/{prognosisDiffRequestId}/prognosisdifforders:
    parameters:
    - in: path
      name: prognosisDiffRequestId
      required: true
      schema:
        type: string
    post:
      operationId: createPrognosisDiffOrder
      summary: Create Prognosis Diff Order
      description: 'Confirm and commit to the offer associated with a prognosis diff

        request. Commands are dispatched to the underlying devices.

        '
      tags:
      - Diff Requests
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrognosisDiffOrder'
      responses:
        '201':
          description: Created
  /api/v1/prognosisdifforders/{prognosisDiffOrderId}:
    parameters:
    - in: path
      name: prognosisDiffOrderId
      required: true
      schema:
        type: string
    get:
      operationId: getPrognosisDiffOrder
      summary: Get Prognosis Diff Order
      description: Retrieve a committed flex offer order including price and power profile.
      tags:
      - Diff Requests
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrognosisDiffOrder'
components:
  schemas:
    PrognosisDiffRequest:
      type: object
      properties:
        prognosisDiffRequestId:
          type: string
        prognosisId:
          type: string
        diffProfile:
          type: array
          items:
            type: object
            properties:
              start:
                type: string
                format: date-time
              end:
                type: string
                format: date-time
              deltaPower_W:
                type: number
        status:
          type: string
          enum:
          - pending
          - offered
          - expired
          - rejected
          - committed
        offer:
          type: object
          properties:
            feasiblePower_W:
              type: number
            price:
              type: number
            currency:
              type: string
    PrognosisDiffOrder:
      type: object
      properties:
        prognosisDiffOrderId:
          type: string
        prognosisDiffRequestId:
          type: string
        acceptedAt:
          type: string
          format: date-time
        powerProfile:
          type: array
          items:
            type: object
            properties:
              start:
                type: string
                format: date-time
              end:
                type: string
                format: date-time
              power_W:
                type: number
        price:
          type: number
        currency:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'OAuth 2.0 client-credentials access token obtained from the

        Gridshare partner Cognito authentication endpoint.

        '