openapi: 3.0.3
info:
  title: Sessy API
  description: |-
    This is an overview of everything you can view and change in your CT meter via its API. You can use it to geek out on stats at home, or integrate into your home automation.
    Wouldn't it be cool to have Sessy's CT meter talk to all kinds of home automation software out there? Enjoy!
  version: 1.0.1
tags:
  - name: CT Meter
    description: A way to request power metrics and change settings
  - name: Energy
    description: A way to request energy metrics
  - name: Grid target
    description: |-
      A way to set a grid target.
paths:
  /api/v1/ct/details:
    get:
      tags:
        - CT Meter
      summary: Returns power and state metrics of the CT meter
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ct_details'
        '500':
          description: An error occurred (error message in response body)
  /api/v1/energy/status:
    get:
      tags:
      - Energy
      summary: Get the latest value for Sessy's energy meters
      description: |
        With this endpoint you can request the energy status of grid meters.
        Find out how much energy the household has used and exported.
        Keep in mind that these values are not usable for any legal purposes.
        The accuracy is ±1% but not guaranteed.
        Updated values might not be stored in case of a hard shutdown such as a power outage.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/energy_response'
        '500':
          description: An error occurred (error message in response body)

  /api/v1/meter/grid_target:
    get:
      tags:
        - Grid target
      summary: Returns the grid target
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grid_target_get'
        '500':
          description: An error occurred
    post:
      tags:
        - Grid target
      summary: Sets the grid_target
      requestBody:
        description: Sets grid target
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/grid_target_post'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_ok_response'
        '500':
          description: An error occurred (error message in response body)

components:
  schemas:
    ct_details:
      required:
        - status
        - total_power
        - power_l1
        - power_l2
        - power_l3
        - voltage_l1
        - voltage_l2
        - voltage_l3
        - current_l1
        - current_l2
        - current_l3
      type: object
      properties:
        status:
          type: string
          example: ok
        total_power:
          type: number
          example: 2250
          description: Indicates the net power in Watts measured by the CT meter
        power_l1:
          type: number
          example: 1000
          description: Indicates the net power in Watts measured by the CT meter
        power_l2:
          type: number
          example: 1000
          description: Indicates the net power in Watts measured by the CT meter
        power_l3:
          type: number
          example: 250
          description: Indicates the net power in Watts measured by the CT meter
        voltage_l1:
          type: number
          example: 231000
          description: Phase voltage measured by the ct meter in milli volts
        voltage_l2:
          type: number
          example: 232000
          description: Phase voltage measured by the ct meter in milli volts
        voltage_l3:
          type: number
          example: 233000
          description: Phase voltage measured by the ct meter in milli volts
        current_l1:
          type: number
          example: 2345
          description: Phase current measured by the ct meter in milli amps
        current_l2:
          type: number
          example: 2345
          description: Phase current measured by the ct meter in milli amps
        current_l3:
          type: number
          example: 2345
          description: Phase current measured by the ct meter in milli amps
    grid_target_get:
      required:
        - status
        - grid_target
      type: object
      properties:
        status:
          type: string
          example: ok
        grid_target:
          type: integer
          example: 0
          description: Power to subtract from the measured power of the meter
    energy_response:
      type: object
      required:
        - energy_phase1
        - energy_phase2
        - energy_phase3
      properties:
        energy_phase1:
          type: object
          required:
            - import_wh
            - export_wh
          properties:
            import_wh:
              type: number
              description: The total energy phase 1 imported from the grid, in Wh.
              example: 1234
            export_wh:
              type: number
              description: The total energy phase 1 exported to the grid, in Wh.
              example: 1234
        energy_phase2:
          type: object
          required:
            - import_wh
            - export_wh
          properties:
            import_wh:
              type: number
              description: The total energy phase 2 imported from the grid, in Wh.
              example: 1234
            export_wh:
              type: number
              description: The total energy phase 2 exported to the grid, in Wh.
              example: 1234
        energy_phase3:
          type: object
          required:
            - import_wh
            - export_wh
          properties:
            import_wh:
              type: number
              description: The total energy phase 3 imported from the grid, in Wh.
              example: 1234
            export_wh:
              type: number
              description: The total energy phase 3 exported to the grid, in Wh.
              example: 1234
    grid_target_post:
      required:
        - grid_target
      type: object
      properties:
        grid_target:
          type: integer
          example: 0
          description: Power to subtract from the measured power of the meter
    api_ok_response:
      required:
        - status
      type: object
      properties:
        status:
          type: string
          example: "ok"