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.0.2
tags:
  - name: Power
    description: A way to request power metrics and change settings
  - name: Dynamic
    description: A way to request dynamic energy parameters
paths:
  /api/v1/power/status:
    get:
      tags:
        - Power
      summary: Returns the current power state and metrics
      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"
        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/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'
        '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
        - frequency
      type: object
      properties:
        sessy:
          type: object
          required:
            - state_of_charge
            - power
            - power_setpoint
            - system_state
          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)
            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
        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
    dynamic_schedule:
      type: object
      required:
        - power_strategy
        - energy_prices
      properties:
        power_strategy:
          type: array
          nullable: true
          description: An array of the dynamic power schedules, null if there is no schedule available
          items:
            type: object
            required:
              - date
              - power
            properties:
              date:
                description: Date of the power array, formatted as YYYY-MM-DD
                type: string
                example: 2022-10-23
              power:
                description: An array of 24 power values, one for each hour of the day starting at 00:00. Positive representing Sessy is generating power, and a negative representing Sessy is charging.
                type: array
                items:
                  type: integer
                example: [0,0,0,0,2200,2200,2200,0,0,0,0,0,-2200,-2200,0,0,0,0,0,0,0,0,0,0]
        energy_prices:
          type: array
          nullable: true
          description: An array of dynamic (EPEX day ahead) prices, null if there are no energy prices available
          items:
            type: object
            required:
              - date
              - energy_prices
            properties:
              date:
                description: Date of the energy_prices array, formatted as YYYY-MM-DD
                type: string
                example: 2022-10-23
              energy_prices:
                description: |-
                  An array of 24 energy prices, one for each hour of the day starting at 00:00. 
                  This is 0.00001 euro per kWh, divide by 100000 to get euro per kWh.
                  These are ENTSO-E prices, meaning they are excluding taxes and other additional costs.
                type: array
                items:
                  type: integer
                example: [6329,5690,5752,5700,5465,6002,7142,8700,8199,6571,5432,4260,2099,3000,4659,5482,6599,8564,10235,8992,7362,6296,5953,5091]
    api_ok_response:
      required:
        - status
      type: object
      properties:
        status:
          type: string
          example: "ok"