openapi: 3.0.3
info:
  title: Sessy API
  description: |-
    This is an overview of everything you can view and change in your Sessy via its API. You can use it to geek out on stats at home, or integrate Sessy into your home automation.
    Wouldn't it be cool to have Sessy talk to all kinds of home automation software out there? Enjoy!
  version: 1.1.0
tags:
  - name: Power
    description: A way to request power metrics and change settings
  - name: Energy
    description: A way to request energy metrics
  - name: Dynamic
    description: A way to request dynamic energy parameters
paths:
  /api/v1/power/status:
    get:
      tags:
        - Power
      summary: |
        Returns the current Sessy, battery, pv and grid status.
        Updated values (like state of charge) 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/power_status'
        '500':
          description: An error occurred (error message in response body)
  /api/v1/power/active_strategy:
    get:
      tags:
        - Power
      summary: Returns the active power strategy
      description: A power strategy determines how your Sessy device charges and delivers power back to the net throughout the day.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/active_power_strategy'
        '500':
          description: An error occurred (error message in response body)
    post:
      tags:
        - Power
      summary: Change the active power strategy
      requestBody:
        description: See the _Schema_ tab for valid values of "strategy"
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/active_power_strategy'
        required: true
      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)
  /api/v1/power/setpoint:
    post:
      tags:
        - Power
      summary: Change the wanted generating/charging power
      requestBody:
        description: |
          Only works when the power strategy is set to "POWER_STRATEGY_API".
          If the network connection is lost, set setpoint will be set to 0.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/power_setpoint'
        required: true
      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)
  /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 different meters.
        Find out how much energy Sessy has charged or discharged and optionally how much energy is generated by the solar panels if connected.
        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/v2/dynamic/schedule:
    get:
      tags:
        - Dynamic
      summary: Get the timeslots available in Sessy for dynamic energy
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dynamic_schedule_v2'
        '500':
          description: An error occurred (error message in response body)
components:
  schemas:
    power_status:
      required:
        - sessy
        - renewable_energy_phase1
        - renewable_energy_phase2
        - renewable_energy_phase3
      type: object
      properties:
        sessy:
          type: object
          required:
            - state_of_charge
            - power
            - external_power
            - pack_voltage
            - power_setpoint
            - system_state
            - system_state_details
            - frequency
            - inverter_current_ma
            - strategy_overridden
          properties:
            state_of_charge:
              type: number
              example: 0.6
              minimum: 0.0
              maximum: 1.0
              description: 0.0 indicates an empty battery pack, 1.0 a full one
            power:
              type: integer
              example: 1000
              description: Currently delivered power in Watts (positive for generating / sending into net, negative for charging / extracting from net)
            external_power:
              type: integer
              example: 0
              description: Power going through the external power port (positive for outgoing power / consumed by an external device, negative for incoming power / produced by an external device)
            pack_voltage:
              type: integer
              example: 51200
              description: Voltage of the battery pack, in millivolt
            power_setpoint:
              type: integer
              example: 1000
              description: How much power in Watts the current power strategy wants to generate (positive value) or charge with (negative value)
            system_state:
              type: string
              example: SYSTEM_STATE_RUNNING_SAFE
              enum:
                - SYSTEM_STATE_INIT
                - SYSTEM_STATE_WAIT_FOR_PERIPHERALS
                - SYSTEM_STATE_STANDBY
                - SYSTEM_STATE_WAITING_FOR_SAFE_SITUATION
                - SYSTEM_STATE_WAITING_IN_SAFE_SITUATION
                - SYSTEM_STATE_RUNNING_SAFE
                - SYSTEM_STATE_OVERRIDE_OVERFREQUENCY
                - SYSTEM_STATE_OVERRIDE_UNDERFREQUENCY
                - SYSTEM_STATE_DISCONNECT
                - SYSTEM_STATE_RECONNECT
                - SYSTEM_STATE_ERROR
                - SYSTEM_STATE_BATTERY_FULL
                - SYSTEM_STATE_BATTERY_EMPTY
                - SYSTEM_STATE_OVERRIDE_BATTERY_UNDERVOLTAGE
              description: The current state that Sessy's power subsystem is in
            system_state_details:
              type: string
              example: ""
              description: "Details on why the system_state is in a certain way. Might still be set after an issue is resolved. System state is leading!"
            frequency:
              type: integer
              example: 50000
              description: The measured frequency of the mains net in milli Hertz
            inverter_current_ma:
              type: integer
              example: 4200
              description: The measured current of the inverter in milliamps
            strategy_overridden:
              type: boolean
              example: false
              description: Whether the active power strategy is currently overridden by an external party
        renewable_energy_phase1:
          $ref: '#/components/schemas/phase'
        renewable_energy_phase2:
          $ref: '#/components/schemas/phase'
        renewable_energy_phase3:
          $ref: '#/components/schemas/phase'
    active_power_strategy:
      required:
        - strategy
        - status
      type: object
      properties:
        strategy:
          type: string
          example: POWER_STRATEGY_API
          enum:
            - POWER_STRATEGY_NOM
            - POWER_STRATEGY_ROI
            - POWER_STRATEGY_API
            - POWER_STRATEGY_IDLE
            - POWER_STRATEGY_SESSY_CONNECT
            - POWER_STRATEGY_ECO
    power_setpoint:
      required:
        - setpoint
      type: object
      properties:
        setpoint:
          type: integer
          example: 1000
          description: The wanted power generated from (positive value) or charged into (negative value) the Sessy, from the active power strategy
    phase:
      type: object
      required:
        - voltage_rms
        - current_rms
        - power
      properties:
        voltage_rms:
          type: number
          example: 230.0
        current_rms:
          type: number
          example: 4.1
        power:
          type: integer
          example: 1200
          description: The real (as opposed to apparent) power passing through this phase
    energy_response:
      type: object
      required:
        - sessy_energy
        - energy_phase1
        - energy_phase2
        - energy_phase3
      properties:
        sessy_energy:
          type: object
          required:
            - import_wh
            - export_wh
          properties:
            import_wh:
              type: number
              description: The total energy Sessy imported from the grid, in Wh.
              example: 1234
            export_wh:
              type: number
              description: The total energy Sessy exported to the grid, in Wh.
              example: 1234
        energy_phase1:
          type: object
          required:
            - import_wh
            - export_wh
          properties:
            import_wh:
              type: number
              description: The total energy consumed on phase 1 if connected, in Wh.
              example: 1234
            export_wh:
              type: number
              description: The total energy from the solar panels generated on phase 1 if connected, in Wh.
              example: 1234
        energy_phase2:
          type: object
          required:
            - import_wh
            - export_wh
          properties:
            import_wh:
              type: number
              description: The total energy consumed on phase 1 if connected, in Wh.
              example: 1234
            export_wh:
              type: number
              description: The total energy from the solar panels generated on phase 1 if connected, in Wh.
              example: 1234
        energy_phase3:
          type: object
          required:
            - import_wh
            - export_wh
          properties:
            import_wh:
              type: number
              description: The total energy consumed on phase 1 if connected, in Wh.
              example: 1234
            export_wh:
              type: number
              description: The total energy from the solar panels generated on phase 1 if connected, in Wh.
              example: 1234
    dynamic_schedule_v2:
      type: object
      required:
        - dynamic_schedule
        - energy_prices
      properties:
        dynamic_schedule:
          type: array
          nullable: true
          description: An array of the dynamic mode schedule, null if there is no schedule available. Order of the list os not guaranteed.
          items:
            type: object
            required:
              - start_time
              - end_time
              - power
            properties:
              start_time:
                description: Time at which the timeslot starts being activate, as a unix timestamp
                type: integer
                example: 1666483200
              end_time:
                description: Time at which the timeslot stops being activate, as a unix timestamp
                type: integer
                example: 1666494000
              power:
                description: |
                  The power calculated for the dynamic mode for this time.
                  Positive representing Sessy is generating power, and a negative representing Sessy is charging.
                type: integer
                example: 1000
        energy_prices:
          type: array
          nullable: true
          description: An array of dynamic (EPEX day ahead) prices, null if there are no energy prices available. Order of the list os not guaranteed.
          items:
            type: object
            required:
              - start_time
              - end_time
              - price
            properties:
              start_time:
                description: Time at which the timeslot starts being activate, as a unix timestamp
                type: integer
                example: 1666483200
              end_time:
                description: Time at which the timeslot stops being activate, as a unix timestamp
                type: integer
                example: 1666494000
              price:
                description: |
                  The ENTSO-E price for this moment, meaning they are excluding taxes and other additional costs.
                  This is 0.001 cent per kWh, divide by 100000 to get euro per kWh.
                type: integer
                example: 1337
    api_ok_response:
      required:
        - status
      type: object
      properties:
        status:
          type: string
          example: "ok"