openapi: 3.1.0
info:
  title: evcc
  description: smart charging. open source energy management.
  version: 0.2.0
  contact:
    url: https://github.com/evcc-io/evcc
servers:
  - url: https://demo.evcc.io/api
tags:
  - name: state
  - name: auth
  - name: battery
  - name: db
  - name: experimental
  - name: general
  - name: loadpoints
  - name: sessions
  - name: system
  - name: tariffs
  - name: vehicles
paths:
  /auth/login:
    post:
      operationId: login
      summary: Login
      description: Administrator login. Returns authorization cookie required for all protected endpoints.
      tags:
        - auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                password:
                  $ref: '#/components/schemas/Password'
      responses:
        '200':
          description: Success
          headers:
            Set-Cookie:
              description: The authorization cookie
              schema:
                type: string
                example: auth=ey...qY; Path=/; Expires=Fri, 04 Apr 2025 14:35:37 GMT; HttpOnly; SameSite=Strict
        '401':
          description: Invalid password provided
  /auth/logout:
    post:
      operationId: logout
      summary: Logout
      description: Logout and delete authorization cookie
      tags:
        - auth
      responses:
        '200':
          description: Success
          headers:
            Set-Cookie:
              description: The authorization cookie
              schema:
                type: string
                enum:
                  - auth=; Path=/; HttpOnly
  /auth/password:
    put:
      operationId: changePassword
      summary: Change admin password
      description: Changes the admin password.
      tags:
        - auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangePassword'
      responses:
        '202':
          description: Success
        '400':
          description: Invalid password provided
  /auth/status:
    get:
      operationId: getAuthStatus
      summary: Authentication status
      description: Whether the current user is logged in.
      tags:
        - auth
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                type: string
                enum:
                  - 'true'
                  - 'false'
  /auth/apikey:
    get:
      operationId: getApiKeyStatus
      summary: API key status
      description: |
        Reports whether an API key has been generated. The key itself is
        only returned once at creation time (POST), never on subsequent
        reads.
      tags:
        - auth
      security:
        - cookieAuth: []
        - bearerAuth: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  configured:
                    type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: regenerateApiKey
      summary: Generate or rotate the API key
      description: |
        Generates a fresh API key, replacing any existing one. The
        returned key is shown only once; store it immediately.

        Even when the request is authenticated via API key (Bearer), the
        admin password must be supplied in the request body to prevent a
        leaked key from rotating itself. The password check is skipped
        when the server is started with `--disable-auth`.
      tags:
        - auth
      security:
        - cookieAuth: []
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                password:
                  $ref: '#/components/schemas/Password'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  key:
                    type: string
                    description: The new API key (cleartext, shown once).
                    example: evcc_aB3xYz7k0Pq2sN5mWtR4
        '401':
          description: Invalid admin password
        '403':
          description: Forbidden in demo mode
  /batterydischargecontrol/{enable}:
    post:
      operationId: setBatteryDischargeControl
      summary: Control battery-discharge
      description: Prevent home battery discharge during vehicle fast charging.
      externalDocs:
        url: https://docs.evcc.io/en/features/battery
      tags:
        - battery
      parameters:
        - $ref: '#/components/parameters/enable'
      responses:
        '200':
          $ref: '#/components/responses/BooleanResult'
  /batterygriddischarge/{enable}:
    post:
      operationId: setBatteryGridDischarge
      summary: Control battery grid discharge
      description: Allow the home battery to discharge to the grid. Enabling may require `force=true` to confirm country-specific grid export restrictions.
      externalDocs:
        url: https://docs.evcc.io/en/features/battery
      tags:
        - battery
        - experimental
      parameters:
        - $ref: '#/components/parameters/enable'
        - name: force
          in: query
          description: Confirm country-specific grid export restrictions
          schema:
            type: boolean
      responses:
        '200':
          $ref: '#/components/responses/BooleanResult'
        '428':
          description: Confirmation required
  /batterygridchargelimit:
    delete:
      operationId: removeBatteryGridChargeLimit
      summary: Remove battery grid charge limit
      description: Remove battery grid charge limit.
      externalDocs:
        url: https://docs.evcc.io/en/features/battery
      tags:
        - battery
      responses:
        '200':
          $ref: '#/components/responses/NullResult'
  /batterygridchargelimit/{cost}:
    post:
      operationId: setBatteryGridChargeLimit
      summary: Set battery grid charge limit
      description: Charge home battery from grid when price or emissions are below the threshold. Uses price if a dynamic tariff exists. Uses emissions if a CO₂-tariff is configured. Ignored otherwise.
      externalDocs:
        url: https://docs.evcc.io/en/features/battery
      tags:
        - battery
      parameters:
        - $ref: '#/components/parameters/costLimit'
      responses:
        '200':
          $ref: '#/components/responses/NumberResult'
  /batterygriddischargelimit:
    delete:
      operationId: removeBatteryGridDischargeLimit
      summary: Remove battery grid discharge limit
      description: Remove battery grid discharge limit (experimental).
      externalDocs:
        url: https://docs.evcc.io/en/features/battery
      tags:
        - battery
      responses:
        '200':
          $ref: '#/components/responses/NullResult'
  /batterygriddischargelimit/{cost}:
    post:
      operationId: setBatteryGridDischargeLimit
      summary: Set battery grid discharge limit
      description: Discharge home battery to grid when the grid export price is at or above the threshold (experimental). Requires a grid export tariff and the battery grid discharge setting. Ignored otherwise.
      externalDocs:
        url: https://docs.evcc.io/en/features/battery
      tags:
        - battery
      parameters:
        - $ref: '#/components/parameters/costLimit'
      responses:
        '200':
          $ref: '#/components/responses/NumberResult'
  /batterymode:
    delete:
      operationId: disableExternalBatteryControl
      summary: Disable external battery control
      description: Default evcc control behavior is restored
      tags:
        - battery
      responses:
        '200':
          $ref: '#/components/responses/BatteryModeResult'
  /batterymode/{batteryMode}:
    post:
      operationId: setExternalBatteryMode
      summary: Set external battery mode
      description: Directly controls the mode of all controllable batteries. evcc behavior like 'price limit' or 'prevent discharge while fast charging' is overruled. External mode resets after 60s. The external system has to call this endpoint regularly.
      tags:
        - battery
      parameters:
        - $ref: '#/components/parameters/batteryMode'
      responses:
        '200':
          $ref: '#/components/responses/BatteryModeResult'
  /buffersoc/{soc}:
    post:
      operationId: setBufferSoc
      summary: Set battery buffer SoC
      description: Set battery buffer SoC.
      externalDocs:
        url: https://docs.evcc.io/en/features/battery
      tags:
        - battery
      parameters:
        - $ref: '#/components/parameters/soc'
      responses:
        '200':
          $ref: '#/components/responses/NumberResult'
  /bufferstartsoc/{soc}:
    post:
      operationId: setBufferStartSoc
      summary: Set battery buffer start SoC
      description: Set battery buffer start SoC.
      externalDocs:
        url: https://docs.evcc.io/en/features/battery
      tags:
        - battery
      parameters:
        - $ref: '#/components/parameters/soc'
      responses:
        '200':
          $ref: '#/components/responses/NumberResult'
  /loadpoints/{id}/alwayscharge/{alwaysCharge}:
    post:
      operationId: setLoadpointAlwaysCharge
      summary: Set always charge
      description: Updates the always charge state. When active, smart mode charges continuously at least at minimum power. The once state resets when the vehicle is disconnected.
      externalDocs:
        url: https://docs.evcc.io/en/features/solar-charging
      tags:
        - loadpoints
      parameters:
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/alwaysCharge'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlwaysCharge'
        '400':
          description: Not supported for chargers without current control.
  /loadpoints/{id}/batteryboost/{enable}:
    post:
      operationId: setLoadpointBatteryBoost
      summary: Set battery boost
      description: 'Enable or disable battery boost. When active, the maximum available home battery power is added until the home battery is drained to configured SoC limit. Note: boost will not work while the battery is on hold (e.g. during fast charging or planned charging with discharge prevention enabled).'
      externalDocs:
        url: https://docs.evcc.io/en/features/battery#battery-boost
      tags:
        - loadpoints
      parameters:
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/enable'
      responses:
        '200':
          $ref: '#/components/responses/BooleanResult'
  /loadpoints/{id}/batteryboostlimit/{soc}:
    post:
      operationId: setLoadpointBatteryBoostLimit
      summary: Set battery boost SoC limit
      description: Set the SoC limit for battery boost. Home battery will be used to support charging up to this SoC level. A value of 100 (default) disabled the boost feature in UI and API.
      externalDocs:
        url: https://docs.evcc.io/en/features/battery#battery-boost
      tags:
        - loadpoints
      parameters:
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/soc'
      responses:
        '200':
          $ref: '#/components/responses/IntegerResult'
  /loadpoints/{id}/disable/delay/{delay}:
    post:
      operationId: setLoadpointDisableDelay
      summary: Disable threshold-delay
      description: Delay before charging stops in smart mode.
      externalDocs:
        url: https://docs.evcc.io/en/reference/configuration/loadpoints
      tags:
        - loadpoints
      parameters:
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/delay'
      responses:
        '200':
          $ref: '#/components/responses/NanoSecondsResult'
  /loadpoints/{id}/disable/threshold/{threshold}:
    post:
      operationId: setLoadpointDisableThreshold
      summary: Disable threshold
      description: Specifies the grid draw power to stop charging in smart mode.
      externalDocs:
        url: https://docs.evcc.io/en/reference/configuration/loadpoints#threshold-1
      tags:
        - loadpoints
      parameters:
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/threshold'
      responses:
        '200':
          $ref: '#/components/responses/NumberResult'
  /loadpoints/{id}/enable/delay/{delay}:
    post:
      operationId: setLoadpointEnableDelay
      summary: Enable threshold-delay
      description: Delay before charging starts in smart mode.
      externalDocs:
        url: https://docs.evcc.io/en/reference/configuration/loadpoints#delay
      tags:
        - loadpoints
      parameters:
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/delay'
      responses:
        '200':
          $ref: '#/components/responses/NanoSecondsResult'
  /loadpoints/{id}/enable/threshold/{threshold}:
    post:
      operationId: setLoadpointEnableThreshold
      summary: Enable threshold
      description: Specifies the available surplus power to start charging in smart mode.
      externalDocs:
        url: https://docs.evcc.io/en/reference/configuration/loadpoints#threshold
      tags:
        - loadpoints
      parameters:
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/threshold'
      responses:
        '200':
          $ref: '#/components/responses/NumberResult'
  /loadpoints/{id}/limitenergy/{energy}:
    post:
      operationId: setLoadpointEnergyLimit
      summary: Update energy limit
      description: Updates the energy limit of the loadpoint. Only available for guest vehicles and vehicles with unknown SoC. Limit is removed on vehicle disconnect.
      externalDocs:
        url: https://docs.evcc.io/en/features/limits
      tags:
        - loadpoints
      parameters:
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/energy'
      responses:
        '200':
          $ref: '#/components/responses/NumberResult'
  /loadpoints/{id}/limitsoc/{soc}:
    post:
      operationId: setLoadpointSocLimit
      summary: Update session SoC limit
      description: Sets the session SoC limit. Cleared on disconnect. Takes precedence over the vehicle's configured limit while set; once cleared (set to 0), the vehicle limit applies again.
      externalDocs:
        url: https://docs.evcc.io/en/features/limits
      tags:
        - loadpoints
      parameters:
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/soc'
      responses:
        '200':
          $ref: '#/components/responses/NumberResult'
  /loadpoints/{id}/maxcurrent/{current}:
    post:
      operationId: setLoadpointMaxCurrent
      summary: Update maximum current
      description: Updates the maximum current of the loadpoint.
      tags:
        - loadpoints
      parameters:
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/current'
      responses:
        '200':
          $ref: '#/components/responses/NumberResult'
  /loadpoints/{id}/mincurrent/{current}:
    post:
      operationId: setLoadpointMinCurrent
      summary: Update minimum current
      description: Updates the minimum current of the loadpoint.
      tags:
        - loadpoints
      parameters:
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/current'
      responses:
        '200':
          $ref: '#/components/responses/NumberResult'
  /loadpoints/{id}/mintemp/{temp}:
    post:
      operationId: setLoadpointMinTemp
      summary: Update minimum temperature
      description: Sets the minimum temperature for heating devices. The device is heated as fast as possible while below this value. Set to 0 to disable.
      externalDocs:
        url: https://docs.evcc.io/en/features/limits
      tags:
        - loadpoints
      parameters:
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/temp'
      responses:
        '200':
          $ref: '#/components/responses/NumberResult'
  /loadpoints/{id}/mode/{mode}:
    post:
      operationId: setLoadpointMode
      summary: Update charge mode
      description: Changes the charging behavior of the loadpoint.
      externalDocs:
        url: https://docs.evcc.io/en/features/solar-charging
      tags:
        - loadpoints
      parameters:
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/mode'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeMode'
  /loadpoints/{id}/phases/{phases}:
    post:
      operationId: setLoadpointPhases
      summary: Update allowed phases
      description: Updates the allowed phases of the loadpoint. Selects the desired phase mode for chargers with automatic phase switching. For manual phase switching chargers (via cable or Lasttrennschalter) this value tells evcc the actual phases.
      externalDocs:
        url: https://docs.evcc.io/en/reference/configuration/loadpoints#phases
      tags:
        - loadpoints
      parameters:
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/phases'
      responses:
        '200':
          $ref: '#/components/responses/NumberResult'
        '400':
          description: Invalid phases-value. You have most likely entered the value 0 for a charger that cannot switch phases automatically.
  /loadpoints/{id}/plan:
    get:
      operationId: getLoadpointPlan
      summary: Get charging plan
      description: Returns the current charging plan for this loadpoint.
      externalDocs:
        url: https://docs.evcc.io/en/features/plans
      tags:
        - loadpoints
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties:
                      planId:
                        $ref: '#/components/schemas/Id'
                  - $ref: '#/components/schemas/PlanRates'
  /loadpoints/{id}/plan/energy:
    delete:
      operationId: deleteLoadpointEnergyPlan
      summary: Delete energy-based charging plan
      description: Delete charging plan. Only available when a vehicle without SoC is connected.
      externalDocs:
        url: https://docs.evcc.io/en/features/plans
      tags:
        - loadpoints
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          $ref: '#/components/responses/EmptyResult'
  /loadpoints/{id}/plan/energy/{energy}/{timestamp}:
    post:
      operationId: setLoadpointEnergyPlan
      summary: Set energy-based charging plan
      description: Create charging plan with fixed time and energy target. Only available when a vehicle without SoC is connected.
      externalDocs:
        url: https://docs.evcc.io/en/features/plans
      tags:
        - loadpoints
      parameters:
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/energy'
        - $ref: '#/components/parameters/timestamp'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StaticEnergyPlan'
  /loadpoints/{id}/plan/repeating/preview/{soc}/{weekdays}/{hourMinuteTime}/{timezone}:
    get:
      operationId: previewLoadpointRepeatingPlan
      summary: Repeating plan preview
      description: Simulate repeating charging plan and return the result. Does not alter the actual charging plan.
      externalDocs:
        url: https://docs.evcc.io/en/features/plans
      tags:
        - loadpoints
      parameters:
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/soc'
        - $ref: '#/components/parameters/weekdays'
        - $ref: '#/components/parameters/hourMinuteTime'
        - $ref: '#/components/parameters/timezone'
      responses:
        '200':
          $ref: '#/components/responses/PlanRatesResult'
  /loadpoints/{id}/plan/static/preview/soc/{soc}/{timestamp}:
    get:
      operationId: previewLoadpointSocPlan
      summary: Simulate SoC-based charging plan
      description: Simulate charging plan based on SoC goal. Does not alter the actual charging plan.
      externalDocs:
        url: https://docs.evcc.io/en/features/plans
      tags:
        - loadpoints
      parameters:
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/soc'
        - $ref: '#/components/parameters/timestamp'
      responses:
        '200':
          $ref: '#/components/responses/PlanRatesResult'
  /loadpoints/{id}/plan/static/preview/energy/{energy}/{timestamp}:
    get:
      operationId: previewLoadpointEnergyPlan
      summary: Simulate energy-based charging plan
      description: Simulate charging plan based on energy goal. Does not alter the actual charging plan.
      externalDocs:
        url: https://docs.evcc.io/en/features/plans
      tags:
        - loadpoints
      parameters:
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/energy'
        - $ref: '#/components/parameters/timestamp'
      responses:
        '200':
          $ref: '#/components/responses/PlanRatesResult'
  /loadpoints/{id}/plan/strategy:
    post:
      operationId: setLoadpointPlanStrategy
      summary: Set plan strategy
      description: Updates the charging plan strategy for the loadpoint.
      externalDocs:
        url: https://docs.evcc.io/en/features/plans
      tags:
        - loadpoints
      parameters:
        - $ref: '#/components/parameters/id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlanStrategy'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanStrategy'
  /loadpoints/{id}/priority/{priority}:
    post:
      operationId: setLoadpointPriority
      summary: Set priority
      description: Set loadpoint priority.
      externalDocs:
        url: https://docs.evcc.io/en/reference/configuration/loadpoints#priority
      tags:
        - loadpoints
      parameters:
        - $ref: '#/components/parameters/id'
        - name: priority
          in: path
          description: Higher number means higher priority.
          required: true
          example: 2
          schema:
            type: integer
            minimum: 0
      responses:
        '200':
          $ref: '#/components/responses/IntegerResult'
  /loadpoints/{id}/smartcostlimit:
    delete:
      operationId: deleteLoadpointSmartCostLimit
      summary: Delete smart charging cost limit
      description: Delete cost or emission limit for fast-charging with grid energy.
      externalDocs:
        url: https://docs.evcc.io/en/features/dynamic-prices
      tags:
        - loadpoints
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          $ref: '#/components/responses/NullResult'
  /loadpoints/{id}/smartcostlimit/{cost}:
    post:
      operationId: setLoadpointSmartCostLimit
      summary: Set smart charging cost limit
      description: Set cost or emission limit for fast-charging with grid energy.
      externalDocs:
        url: https://docs.evcc.io/en/features/dynamic-prices
      tags:
        - loadpoints
      parameters:
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/costLimit'
      responses:
        '200':
          $ref: '#/components/responses/NumberResult'
  /loadpoints/{id}/smartfeedinprioritylimit:
    delete:
      operationId: deleteLoadpointSmartFeedInPriorityLimit
      summary: Delete smart feed-in priority limit
      description: Delete limit for feed-in priority optimization.
      tags:
        - loadpoints
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          $ref: '#/components/responses/NullResult'
  /loadpoints/{id}/smartfeedinprioritylimit/{cost}:
    post:
      operationId: setLoadpointSmartFeedInPriorityLimit
      summary: Set smart feed-in priority limit
      description: Set limit for feed-in priority optimization.
      tags:
        - loadpoints
      parameters:
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/costLimit'
      responses:
        '200':
          $ref: '#/components/responses/NumberResult'
  /loadpoints/{id}/solarshare/{share}:
    post:
      operationId: setLoadpointSolarShare
      summary: Set solar share
      description: Set the share of the minimum charging power that must come from solar surplus in smart mode. 1 (default) requires full surplus, 0 starts charging as soon as there is no grid import. Ignored while enable/disable thresholds are configured. Usually 0 to 1; values outside that range are possible for special cases.
      tags:
        - loadpoints
      parameters:
        - $ref: '#/components/parameters/id'
        - name: share
          in: path
          description: Solar share of the minimum charging power.
          required: true
          example: 0.5
          schema:
            type: number
      responses:
        '200':
          $ref: '#/components/responses/NumberResult'
  /loadpoints/{id}/vehicle:
    delete:
      operationId: removeLoadpointVehicle
      summary: Remove vehicle
      description: Remove vehicle from loadpoint. Connected vehicle is treated as guest vehicle.
      externalDocs:
        url: https://docs.evcc.io/en/features/vehicle
      tags:
        - loadpoints
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          $ref: '#/components/responses/EmptyResult'
    patch:
      operationId: startLoadpointVehicleDetection
      summary: Start vehicle detection
      description: Starts the automatic vehicle detection process.
      externalDocs:
        url: https://docs.evcc.io/en/features/vehicle
      tags:
        - loadpoints
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          $ref: '#/components/responses/EmptyResult'
  /loadpoints/{id}/vehicle/{name}:
    post:
      operationId: assignLoadpointVehicle
      summary: Assign vehicle
      description: Assigns vehicle to loadpoint.
      externalDocs:
        url: https://docs.evcc.io/en/features/vehicle
      tags:
        - loadpoints
      parameters:
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/vehicleName'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  vehicle:
                    $ref: '#/components/schemas/VehicleTitle'
  /prioritysoc/{soc}:
    post:
      operationId: setPrioritySoc
      summary: Set battery priority SoC
      description: Set battery priority SoC.
      externalDocs:
        url: https://docs.evcc.io/en/features/battery
      tags:
        - battery
      parameters:
        - $ref: '#/components/parameters/soc'
      responses:
        '200':
          $ref: '#/components/responses/NumberResult'
  /residualpower/{power}:
    post:
      operationId: setResidualPower
      summary: Set grid residual power
      description: Set grid connection operating point.
      externalDocs:
        url: https://docs.evcc.io/en/reference/configuration/site#residualpower
      tags:
        - battery
      parameters:
        - $ref: '#/components/parameters/power'
      responses:
        '200':
          $ref: '#/components/responses/NumberResult'
  /gridexportlimit/{power}:
    post:
      operationId: setGridExportLimit
      summary: Set grid export limit
      description: Set the static grid export power limit in W used as optimizer constraint. 0 disables the limit. An active HEMS curtailment takes precedence.
      tags:
        - general
      parameters:
        - $ref: '#/components/parameters/power'
      responses:
        '200':
          $ref: '#/components/responses/NumberResult'
  /solaradjusted/{enable}:
    post:
      operationId: setSolarAdjusted
      summary: Adjust solar forecast
      description: Adjust the solar forecast to real production data of the current day.
      tags:
        - experimental
      parameters:
        - $ref: '#/components/parameters/enable'
      responses:
        '200':
          $ref: '#/components/responses/BooleanResult'
  /config/optimizerautomatic/{value}:
    post:
      operationId: setOptimizerAutomatic
      summary: Set optimizer automatic level
      description: Let the optimizer directly control the home battery (`battery`) or home battery and loadpoints (`full`) instead of only advising (`off`). Requires a sponsor token.
      security:
        - cookieAuth: []
        - bearerAuth: []
      tags:
        - experimental
      parameters:
        - name: value
          description: What the optimizer controls.
          in: path
          required: true
          schema:
            type: string
            enum:
              - 'off'
              - battery
              - full
      responses:
        '200':
          $ref: '#/components/responses/StringResult'
  /config/onboarding:
    put:
      operationId: setOnboarding
      summary: Set onboarding state
      description: Setup wizard completion and dismissed setup checklist items.
      security:
        - cookieAuth: []
        - bearerAuth: []
      tags:
        - general
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnboardingState'
      responses:
        '200':
          description: Updated onboarding state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingState'
        '400':
          description: Invalid item
  /smartfeedinprioritylimit:
    delete:
      operationId: removeGlobalSmartFeedInPriorityLimit
      summary: Remove smart feed-in priority limit for all loadpoints.
      description: Convenience method to remove limit for all loadpoints at once. Value is applied to each individual loadpoint.
      tags:
        - general
      responses:
        '200':
          $ref: '#/components/responses/NullResult'
  /smartfeedinprioritylimit/{cost}:
    post:
      operationId: setGlobalSmartFeedInPriorityLimit
      summary: Set smart feed-in priority limit for all loadpoints
      description: Convenience method to set smart feed-in priority limit for all loadpoints at once. Value is applied to each individual loadpoint.
      tags:
        - general
      parameters:
        - $ref: '#/components/parameters/costLimit'
      responses:
        '200':
          $ref: '#/components/responses/NumberResult'
  /session/{id}:
    parameters:
      - $ref: '#/components/parameters/id'
    put:
      operationId: updateSession
      summary: Update charging session
      description: Update vehicle, loadpoint or odometer of a charging session. Only provided fields are changed; a null odometer clears the stored value.
      externalDocs:
        url: https://docs.evcc.io/en/features/sessions
      tags:
        - sessions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                vehicle:
                  $ref: '#/components/schemas/VehicleName'
                loadpoint:
                  $ref: '#/components/schemas/LoadpointName'
                odometer:
                  $ref: '#/components/schemas/Odometer'
      responses:
        '200':
          description: Success
    delete:
      operationId: deleteSession
      summary: Delete charging session
      description: Delete charging session.
      externalDocs:
        url: https://docs.evcc.io/en/features/sessions
      tags:
        - sessions
      responses:
        '200':
          $ref: '#/components/responses/NullResult'
  /gridsessions:
    get:
      operationId: getGridSessions
      summary: Grid limitation sessions
      description: Returns a list of HEMS grid limitation events.
      tags:
        - sessions
      parameters:
        - name: format
          in: query
          description: Response format (default json)
          schema:
            type: string
            enum:
              - csv
        - name: lang
          in: query
          description: Language (defaults to accept header)
          schema:
            type: string
            example: de
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GridSessions'
            text/csv:
              schema:
                description: Download csv-file
                type: string
                format: binary
  /sessions:
    get:
      operationId: getSessions
      summary: Charging sessions
      description: Returns a list of charging sessions.
      externalDocs:
        url: https://docs.evcc.io/en/features/sessions
      tags:
        - sessions
      parameters:
        - name: format
          in: query
          description: Response format (default json)
          schema:
            type: string
            enum:
              - csv
        - name: lang
          in: query
          description: Language (defaults to accept header)
          schema:
            type: string
            example: de
        - name: month
          in: query
          description: Month filter
          schema:
            type: integer
            example: 2
            minimum: 1
            maximum: 12
        - name: year
          in: query
          description: Year filter
          schema:
            type: integer
            example: 2025
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargingSessions'
            text/csv:
              schema:
                description: Download csv-file
                type: string
                format: binary
  /config/currency:
    put:
      operationId: setCurrency
      summary: Set currency
      description: Set the currency used for prices, costs and savings.
      tags:
        - general
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: string
              description: ISO 4217 currency code
              example: EUR
      responses:
        '200':
          $ref: '#/components/responses/BlankResponse'
        '400':
          description: Invalid currency code
  /config/country:
    put:
      operationId: setCountry
      summary: Set country
      description: Set the site country. Used for region-specific hints and defaults. Empty string clears the setting.
      tags:
        - general
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: string
              description: ISO 3166-1 alpha-2 country code
              example: DE
      responses:
        '200':
          $ref: '#/components/responses/BlankResponse'
        '400':
          description: Invalid country code
  /config/gridconnection:
    put:
      operationId: setGridConnection
      summary: Set grid connection
      description: Set the grid connection. 3p4w for three-phase four-wire grids with neutral (3 x 230/400 V), 3p3w for three-phase three-wire grids without neutral (3 x 230 V).
      tags:
        - general
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: string
              enum:
                - 3p4w
                - 3p3w
              example: 3p3w
      responses:
        '200':
          $ref: '#/components/responses/BlankResponse'
        '400':
          description: Invalid grid connection
  /settings/telemetry/{enable}:
    post:
      operationId: setTelemetryStatus
      summary: Enable/disable telemetry
      description: 'Enable or disable telemetry. Note: Telemetry requires sponsorship.'
      externalDocs:
        url: https://docs.evcc.io/en/reference/configuration/telemetry
      tags:
        - system
      parameters:
        - $ref: '#/components/parameters/enable'
      responses:
        '200':
          $ref: '#/components/responses/BooleanResult'
        '400':
          description: Sponsorship required
  /smartcostlimit:
    delete:
      operationId: removeGlobalSmartCostLimit
      summary: Remove smart charging cost limit for all loadpoints.
      description: Convenience method to remove limit for all loadpoints at once. Value is applied to each individual loadpoint.
      tags:
        - general
      responses:
        '200':
          $ref: '#/components/responses/NullResult'
  /smartcostlimit/{cost}:
    post:
      operationId: setGlobalSmartCostLimit
      summary: Set smart charging cost limit for all loadpoints
      description: Convenience method to set smart charging cost limit for all loadpoints at once. Value is applied to each individual loadpoint.
      tags:
        - general
      parameters:
        - $ref: '#/components/parameters/costLimit'
      responses:
        '200':
          $ref: '#/components/responses/NumberResult'
  /state:
    get:
      operationId: getState
      summary: System state
      description: 'Returns the complete state of the system. This structure is used by the UI and also published via websocket and MQTT. It can be filtered by JQ to only return a subset of the data. Note: the response mirrors the internal UI state and carries no compatibility promise. Fields may change or disappear between releases.'
      externalDocs:
        url: https://docs.evcc.io/en/reference/state
      tags:
        - state
      parameters:
        - name: jq
          in: query
          description: Filter the state with JQ
          schema:
            type: string
          examples:
            all:
              value: .
              summary: complete state
            firstLoadpoint:
              value: .loadpoints[0]
              summary: only first loadpoint
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/State'
  /system/log:
    get:
      operationId: getSystemLogs
      summary: Logs
      description: Returns the latest log lines.
      externalDocs:
        url: https://docs.evcc.io/en/reference/configuration/log
      security:
        - cookieAuth: []
        - bearerAuth: []
      tags:
        - system
      parameters:
        - $ref: '#/components/parameters/logAreas'
        - $ref: '#/components/parameters/logLevel'
        - name: count
          in: query
          description: Number of log lines to return
          example: 100
          schema:
            type: integer
        - name: format
          in: query
          description: File type
          schema:
            type: string
            enum:
              - txt
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
            text/plain:
              schema:
                description: Download txt-file
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
  /system/log/areas:
    get:
      operationId: getLogAreas
      summary: List of all log areas
      description: Returns a list of all log areas (e.g. `lp-1`, `site`, `db`).
      security:
        - cookieAuth: []
        - bearerAuth: []
      tags:
        - system
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogAreas'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /system/cache:
    delete:
      operationId: clearCache
      summary: Clear cache
      description: Clears all cached data. This resets all cached values from tariffs, vehicle APIs, and other components that use caching.
      security:
        - cookieAuth: []
        - bearerAuth: []
      tags:
        - system
      responses:
        '200':
          $ref: '#/components/responses/SuccessResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /system/shutdown:
    post:
      operationId: shutdownSystem
      summary: Shutdown evcc
      description: Shut down instance. There is no reboot command. We expect the underlying system (docker, systemd, etc.) to restart the evcc instance once it's terminated.
      security:
        - cookieAuth: []
        - bearerAuth: []
      tags:
        - system
      responses:
        '204':
          $ref: '#/components/responses/BlankResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /tariff/{type}:
    get:
      operationId: getTariffInfo
      summary: Tariff information
      description: Returns the prices or emission values for the upcoming hours
      externalDocs:
        url: https://docs.evcc.io/en/tariffs
      tags:
        - tariffs
      parameters:
        - name: type
          in: path
          description: Tariff type
          required: true
          schema:
            type: string
            enum:
              - grid
              - feedin
              - co2
              - planner
              - solar
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  rates:
                    $ref: '#/components/schemas/Rates'
        '404':
          description: Tariff not defined
  /vehicles/{name}/limitsoc/{soc}:
    post:
      operationId: setVehicleSocLimit
      summary: Set SoC limit
      description: Charging will stop when this SoC is reached.
      externalDocs:
        url: https://docs.evcc.io/en/features/limits
      tags:
        - vehicles
      parameters:
        - $ref: '#/components/parameters/vehicleName'
        - $ref: '#/components/parameters/soc'
      responses:
        '200':
          $ref: '#/components/responses/SocResult'
  /vehicles/{name}/minsoc/{soc}:
    post:
      operationId: setVehicleMinSoc
      summary: Set minimum SoC
      description: Vehicle will be fast-charged until this SoC is reached.
      externalDocs:
        url: https://docs.evcc.io/en/features/limits
      tags:
        - vehicles
      parameters:
        - $ref: '#/components/parameters/vehicleName'
        - $ref: '#/components/parameters/soc'
      responses:
        '200':
          $ref: '#/components/responses/SocResult'
  /vehicles/{name}/mode:
    delete:
      operationId: deleteVehicleMode
      summary: Reset charge mode
      description: Resets the vehicle charge mode to keep the last selected mode.
      externalDocs:
        url: https://docs.evcc.io/en/features/solar-charging
      tags:
        - vehicles
      parameters:
        - $ref: '#/components/parameters/vehicleName'
      responses:
        '200':
          $ref: '#/components/responses/NullResult'
  /vehicles/{name}/mode/{mode}:
    post:
      operationId: setVehicleMode
      summary: Set charge mode
      description: Sets the charge mode applied when this vehicle becomes active on a loadpoint.
      externalDocs:
        url: https://docs.evcc.io/en/features/solar-charging
      tags:
        - vehicles
      parameters:
        - $ref: '#/components/parameters/vehicleName'
        - $ref: '#/components/parameters/mode'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  mode:
                    $ref: '#/components/schemas/ChargeMode'
  /vehicles/{name}/alwayscharge:
    delete:
      operationId: deleteVehicleAlwaysCharge
      summary: Reset always charge
      description: Resets the vehicle always charge default to keep the loadpoint state.
      externalDocs:
        url: https://docs.evcc.io/en/features/solar-charging
      tags:
        - vehicles
      parameters:
        - $ref: '#/components/parameters/vehicleName'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  alwaysCharge:
                    anyOf:
                      - $ref: '#/components/schemas/VehicleAlwaysCharge'
                      - type: string
                        enum:
                          - ''
  /vehicles/{name}/alwayscharge/{alwaysCharge}:
    post:
      operationId: setVehicleAlwaysCharge
      summary: Set always charge
      description: Sets the always charge state applied when this vehicle becomes active on a loadpoint.
      externalDocs:
        url: https://docs.evcc.io/en/features/solar-charging
      tags:
        - vehicles
      parameters:
        - $ref: '#/components/parameters/vehicleName'
        - $ref: '#/components/parameters/vehicleAlwaysCharge'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  alwaysCharge:
                    $ref: '#/components/schemas/VehicleAlwaysCharge'
  /vehicles/{name}/plan/repeating:
    post:
      operationId: updateVehicleRepeatingPlans
      summary: Update repeating plans
      description: Updates the repeating charging plan.
      externalDocs:
        url: https://docs.evcc.io/en/features/plans
      tags:
        - vehicles
      parameters:
        - $ref: '#/components/parameters/vehicleName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/RepeatingPlan'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RepeatingPlan'
  /vehicles/{name}/plan/soc:
    delete:
      operationId: deleteVehicleSocPlan
      summary: Delete a SoC-based charging plan
      description: Delete the charging plan
      externalDocs:
        url: https://docs.evcc.io/en/features/plans
      tags:
        - vehicles
      parameters:
        - $ref: '#/components/parameters/vehicleName'
      responses:
        '200':
          $ref: '#/components/responses/EmptyResult'
  /vehicles/{name}/plan/soc/{soc}/{timestamp}:
    post:
      operationId: setVehicleSocPlan
      summary: Set a SoC-based charging plan
      description: Create charging plan with fixed time and SoC target.
      externalDocs:
        url: https://docs.evcc.io/en/features/plans
      tags:
        - vehicles
      parameters:
        - $ref: '#/components/parameters/vehicleName'
        - $ref: '#/components/parameters/soc'
        - $ref: '#/components/parameters/timestamp'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  soc:
                    $ref: '#/components/schemas/Soc'
                  time:
                    $ref: '#/components/schemas/Timestamp'
  /vehicles/{name}/plan/strategy:
    post:
      operationId: setVehiclePlanStrategy
      summary: Set plan strategy
      description: Updates the charging plan strategy for the vehicle.
      externalDocs:
        url: https://docs.evcc.io/en/features/plans
      tags:
        - vehicles
      parameters:
        - $ref: '#/components/parameters/vehicleName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlanStrategy'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanStrategy'
  /db/backup:
    get:
      operationId: downloadBackup
      summary: Download database backup
      description: Downloads the SQLite database as a backup file. Session users must supply the admin password in the X-Admin-Password header. API key holders via Bearer token are exempt.
      tags:
        - db
      security:
        - cookieAuth: []
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/adminPassword'
      responses:
        '200':
          description: SQLite database file
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
  /db/restore:
    post:
      operationId: restoreBackup
      summary: Restore database backup
      description: Restores the database from a previously downloaded backup file. Session users must supply the admin password in the X-Admin-Password header. API key holders via Bearer token are exempt. The instance restarts after a successful restore.
      tags:
        - db
      security:
        - cookieAuth: []
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/adminPassword'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: SQLite database backup file
      responses:
        '204':
          description: Restore successful, instance is restarting
        '400':
          description: Invalid file or missing fields
        '401':
          $ref: '#/components/responses/Unauthorized'
  /db/reset:
    post:
      operationId: resetDatabase
      summary: Reset database
      description: Selectively deletes sessions, settings and/or remote access data from the database. Session users must supply the admin password in the X-Admin-Password header. API key holders via Bearer token are exempt. The instance restarts after a successful reset.
      tags:
        - db
      security:
        - cookieAuth: []
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/adminPassword'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sessions:
                  type: boolean
                  description: Delete all charging sessions
                settings:
                  type: boolean
                  description: Delete all settings, configs, and meters
                remote:
                  type: boolean
                  description: Delete remote access configuration and registered clients
      responses:
        '204':
          description: Reset successful, instance is restarting
        '401':
          $ref: '#/components/responses/Unauthorized'
  /db/metrics/energy:
    delete:
      operationId: deleteEnergyMetrics
      summary: Delete energy metrics
      description: Deletes recorded energy slots in the given time range, optionally narrowed by entity. Filter parameters match /history/energy, so the same request can be previewed there before deleting. Session users must supply the admin password in the X-Admin-Password header. API key holders via Bearer token are exempt.
      tags:
        - db
      security:
        - cookieAuth: []
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/adminPassword'
        - name: from
          in: query
          required: true
          description: Start time, inclusive (RFC3339)
          schema:
            type: string
            format: date-time
            example: '2026-07-01T00:00:00Z'
        - name: to
          in: query
          required: true
          description: End time, exclusive (RFC3339)
          schema:
            type: string
            format: date-time
            example: '2026-07-02T00:00:00Z'
        - name: group
          in: query
          description: Filter by entity group
          schema:
            type: string
            example: forecast
            enum:
              - forecast
              - battery
              - grid
              - pv
              - home
              - loadpoint
              - meter
              - consumer
              - temperature
        - name: name
          in: query
          description: Filter by entity name
          schema:
            type: string
            example: db:8
        - name: title
          in: query
          description: Filter by entity title
          schema:
            type: string
            example: Battery
      responses:
        '200':
          $ref: '#/components/responses/Deleted'
        '400':
          description: Invalid parameters or database offline
        '401':
          $ref: '#/components/responses/Unauthorized'
  /db/metrics/tariffs:
    delete:
      operationId: deleteTariffMetrics
      summary: Delete tariff metrics
      description: Deletes recorded tariff values in the given time range. Without usage the entire record is removed, otherwise only that usage is cleared and records left without any value are removed. Session users must supply the admin password in the X-Admin-Password header. API key holders via Bearer token are exempt.
      tags:
        - db
      security:
        - cookieAuth: []
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/adminPassword'
        - name: from
          in: query
          required: true
          description: Start time, inclusive (RFC3339)
          schema:
            type: string
            format: date-time
            example: '2026-07-01T00:00:00Z'
        - name: to
          in: query
          required: true
          description: End time, exclusive (RFC3339)
          schema:
            type: string
            format: date-time
            example: '2026-07-02T00:00:00Z'
        - name: usage
          in: query
          description: Limit deletion to a single tariff usage
          schema:
            type: string
            example: co2
            enum:
              - grid
              - feedin
              - co2
              - temperature
      responses:
        '200':
          $ref: '#/components/responses/Deleted'
        '400':
          description: Invalid parameters or database offline
        '401':
          $ref: '#/components/responses/Unauthorized'
  /history/energy:
    get:
      operationId: getEnergyHistory
      summary: Energy history
      description: Returns aggregated energy history data. Aggregate granularity defaults to 15 minutes. Supports CSV export.
      tags:
        - experimental
      parameters:
        - $ref: '#/components/parameters/historyFrom'
        - $ref: '#/components/parameters/historyTo'
        - name: aggregate
          in: query
          description: 'Aggregation interval. Examples: 15m, 1h, day, month'
          schema:
            type: string
            default: 15m
            example: 1h
        - name: grouped
          in: query
          description: Group results by loadpoint
          schema:
            type: boolean
            default: false
            example: false
        - name: group
          in: query
          description: Filter by entity group
          schema:
            type: string
            example: battery
            enum:
              - forecast
              - battery
              - grid
              - pv
              - home
              - loadpoint
              - meter
              - consumer
        - name: name
          in: query
          description: Filter by entity name
          schema:
            type: string
            example: db:8
        - name: title
          in: query
          description: Filter by entity title
          schema:
            type: string
            example: Battery
        - name: format
          in: query
          description: Response format
          schema:
            type: string
            enum:
              - json
              - csv
            default: json
            example: json
        - name: lang
          in: query
          description: Language for CSV column headers (BCP 47, e.g. de, en). Defaults to Accept-Language header.
          schema:
            type: string
            example: de
      responses:
        '200':
          description: Energy history data
          content:
            application/json:
              schema:
                type: array
                description: One series per entity, or per group when grouped
                items:
                  type: object
                  properties:
                    title:
                      type: string
                      description: Entity title, omitted when grouped
                    group:
                      type: string
                      enum:
                        - pv
                        - battery
                        - grid
                        - loadpoint
                        - consumer
                        - meter
                        - home
                        - forecast
                        - temperature
                    isTemp:
                      type: boolean
                      description: socTemp values are temperatures, not state of charge
                    data:
                      type: array
                      items:
                        type: object
                        properties:
                          start:
                            type: string
                            format: date-time
                          end:
                            type: string
                            format: date-time
                          energy:
                            type: number
                            description: kWh
                          returnEnergy:
                            type: number
                            description: kWh exported or discharged
                          socTemp:
                            type: number
                            description: State of charge in percent or temperature of a single slot
                          cost:
                            type: number
                            description: Grid import cost, where a price exists
                          pricedEnergy:
                            type: number
                            description: kWh imported where a price exists
                          returnCost:
                            type: number
                            description: Grid export revenue, where a price exists
                          pricedReturnEnergy:
                            type: number
                            description: kWh exported where a price exists
            text/csv:
              schema:
                type: string
        '400':
          description: Invalid parameters or database offline
  /history/flow:
    get:
      operationId: getEnergyFlow
      summary: Energy flow
      description: Returns the energy attributed from sources (pv, battery, grid) to sinks (home, battery, loadpoint, export) over the period, plus grid cost and CO₂ sums where tariff data exists.
      tags:
        - experimental
      parameters:
        - $ref: '#/components/parameters/historyFrom'
        - $ref: '#/components/parameters/historyTo'
      responses:
        '200':
          description: Energy flow data
          content:
            application/json:
              schema:
                type: object
                properties:
                  flows:
                    type: array
                    items:
                      $ref: '#/components/schemas/Flow'
                  entities:
                    type: array
                    description: Flows into each consumer and loadpoint, priced per slot
                    items:
                      type: object
                      properties:
                        group:
                          type: string
                          enum:
                            - consumer
                            - loadpoint
                        title:
                          type: string
                        virtual:
                          type: boolean
                          description: Home consumption not covered by a consumer
                        flows:
                          type: array
                          items:
                            $ref: '#/components/schemas/Flow'
                  cost:
                    type: object
                    description: Grid cost sums, omitted without grid price data
                    properties:
                      import:
                        type: number
                      export:
                        type: number
                      importEnergy:
                        type: number
                        description: kWh where a price exists
                      exportEnergy:
                        type: number
                        description: kWh where a price exists
                      avgGrid:
                        type: number
                  co2:
                    type: object
                    description: Grid CO₂ sums in kg, omitted without CO₂ data
                    properties:
                      consumption:
                        type: number
                        description: Emissions of the grid share that went to home and loadpoints
                      consumptionEnergy:
                        type: number
                        description: kWh
                      baseline:
                        type: number
                      avgCo2:
                        type: number
                        description: g/kWh
        '400':
          description: Invalid parameters or database offline
  /history/tariffs:
    get:
      operationId: getTariffHistory
      summary: Tariff history
      description: Returns the persisted 15 minute tariff slots in the period, or their averages per hour, day or month.
      tags:
        - experimental
      parameters:
        - name: aggregate
          in: query
          description: Bucket size, 15 minute slots by default
          schema:
            type: string
            enum:
              - 15m
              - hour
              - day
              - month
        - $ref: '#/components/parameters/historyFrom'
        - $ref: '#/components/parameters/historyTo'
      responses:
        '200':
          description: Tariff slots
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    start:
                      type: string
                      format: date-time
                    grid:
                      type: number
                      description: Grid price per kWh, the bucket average when aggregated
                    gridMin:
                      type: number
                      description: Lowest slot price in the bucket, aggregated only
                    gridMax:
                      type: number
                      description: Highest slot price in the bucket, aggregated only
                    feedin:
                      type: number
                      description: Grid export price per kWh, the bucket average when aggregated
                    feedinMin:
                      type: number
                    feedinMax:
                      type: number
                    co2:
                      type: number
                      description: g/kWh
                    temperature:
                      type: number
                      description: °C
        '400':
          description: Invalid parameters or database offline
components:
  schemas:
    ChangePassword:
      type: object
      properties:
        current:
          $ref: '#/components/schemas/Password'
        new:
          $ref: '#/components/schemas/Password'
    ChargingSessions:
      description: Charging sessions
      type: array
      items:
        type: object
        properties:
          id:
            $ref: '#/components/schemas/Id'
          created:
            $ref: '#/components/schemas/Timestamp'
          finished:
            $ref: '#/components/schemas/Timestamp'
          loadpoint:
            $ref: '#/components/schemas/LoadpointName'
          vehicle:
            $ref: '#/components/schemas/VehicleName'
          odometer:
            $ref: '#/components/schemas/Odometer'
          meterStart:
            nullable: true
            type: number
            description: Meter reading at start of charging session
          meterStop:
            nullable: true
            type: number
            description: Meter reading at end of charging session
          chargedEnergy:
            type: number
            description: Charged energy in kWh
    GridSessions:
      description: Grid limitation sessions
      type: array
      items:
        type: object
        properties:
          id:
            $ref: '#/components/schemas/Id'
          created:
            $ref: '#/components/schemas/Timestamp'
          finished:
            $ref: '#/components/schemas/Timestamp'
          type:
            type: string
            enum:
              - consumption
              - feedin
            description: Type of grid limitation event
          gridPower:
            type: number
            description: Grid power in watts
          limitPower:
            type: number
            description: Limitation power in watts
          chargeDuration:
            type: number
            description: Duration of active charging
          solarPercentage:
            type: number
            description: Solar percentage of the session
          price:
            type: number
            description: Total price of the session
          pricePerKWh:
            type: number
            description: Average price per kWh
          co2PerKWh:
            type: number
            description: Average CO₂ emissions per kWh
    VehicleAlwaysCharge:
      description: Always charge default applied on identification. Once is not supported for vehicles.
      type: string
      enum:
        - 'off'
        - 'on'
    ChargeModeInput:
      description: 'Charging behavior. The values `pv` and `minpv` are deprecated aliases: `pv` maps to `smart`, `minpv` maps to `smart` with always charge enabled.'
      type: string
      enum:
        - 'off'
        - smart
        - now
        - pv
        - minpv
      example: smart
    Current:
      description: Electric current in A
      type: number
      example: 16
      minimum: 0
    Energy:
      description: Energy in kWh
      type: number
      example: 25.5
      minimum: 0
    Flow:
      type: object
      properties:
        from:
          type: string
          enum:
            - pv
            - battery
            - grid
        to:
          type: string
          enum:
            - home
            - battery
            - loadpoint
            - export
        energy:
          type: number
          description: kWh
        cost:
          type: number
          description: Cost of the energy, for home and loadpoint
        pricedEnergy:
          type: number
          description: kWh where a price exists
    Delay:
      description: Duration in seconds.
      type: integer
      example: 60
    HourMinuteTime:
      description: Time in `HH:MM` format
      type: string
      pattern: '[0-1][0-9]:[0-5][0-9]'
      format: HH:MM
      example: '12:30'
    IANATimeZone:
      description: Timezone in IANA format
      externalDocs:
        url: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List
      type: string
      example: Europe/Berlin
    Id:
      description: Loadpoint index starting at 1.
      type: integer
      example: 1
      minimum: 1
    LoadpointName:
      externalDocs:
        url: https://docs.evcc.io/en/reference/configuration/loadpoints#title
      type: string
      example: Garage
    LogArea:
      externalDocs:
        url: https://docs.evcc.io/en/reference/configuration/log#levels
      type: string
    LogAreas:
      externalDocs:
        url: https://docs.evcc.io/en/reference/configuration/log#levels
      type: array
      example:
        - lp-1
        - site
        - db
      items:
        $ref: '#/components/schemas/LogArea'
    LogLevel:
      externalDocs:
        url: https://docs.evcc.io/en/reference/configuration/log#log
      type: string
      example: DEBUG
      enum:
        - FATAL
        - ERROR
        - WARN
        - INFO
        - DEBUG
        - TRACE
    Odometer:
      nullable: true
      type: number
      description: Vehicle odometer reading in kilometers
    Password:
      description: Admin password
      type: string
    Phases:
      description: 'Number of phases. (0: auto, 1: 1-phase, 3: 3-phase)'
      type: string
      example: '3'
      enum:
        - '0'
        - '1'
        - '3'
    PlanRates:
      type: object
      properties:
        duration:
          description: Duration in s
          type: integer
          minimum: 0
        plan:
          $ref: '#/components/schemas/Rates'
        planTime:
          $ref: '#/components/schemas/Timestamp'
        power:
          $ref: '#/components/schemas/Power'
    Power:
      description: Power in W
      type: number
      minimum: 0
      example: 2500
    Precondition:
      description: Late charging duration in seconds.
      type: integer
      example: 3600
      minimum: 0
    Rates:
      type: array
      items:
        $ref: '#/components/schemas/Rate'
    Soc:
      description: SoC in %
      type: number
      example: 60
      minimum: 0
      maximum: 100
    Temp:
      description: Temperature in °C
      type: number
      example: 50
      minimum: 0
    Timestamp:
      description: Timestamp in RFC3339 format
      type: string
      format: date-time
    VehicleName:
      externalDocs:
        url: https://docs.evcc.io/en/reference/configuration/vehicles#name
      type: string
      minLength: 1
      pattern: '[a-zA-Z0-9_.:-]+'
      example: vehicle_1
    VehicleTitle:
      externalDocs:
        url: https://docs.evcc.io/en/reference/configuration/vehicles#title
      type: string
      example: blauer e-Golf
    Weekdays:
      description: The Weekdays
      type: array
      uniqueItems: true
      example:
        - 1
        - 3
        - 4
      items:
        description: '0: Sunday, 1: Monday, 2: Tuesday, 3: Wednesday, 4: Thursday, 5: Friday, 6: Saturday'
        type: integer
        minimum: 0
        maximum: 6
    BatteryMode:
      description: Battery operation mode.
      type: string
      enum:
        - unknown
        - normal
        - hold
        - charge
        - holdcharge
        - discharge
    AlwaysCharge:
      description: Always charge state. Smart mode charges continuously at least at minimum power.
      type: string
      enum:
        - 'off'
        - 'on'
        - once
    ChargeMode:
      description: Charging mode.
      type: string
      enum:
        - 'off'
        - smart
        - now
    Rate:
      description: A time slot with an associated price or emission value.
      type: object
      properties:
        start:
          description: Start of the time slot.
          type: string
          format: date-time
        end:
          description: End of the time slot.
          type: string
          format: date-time
        value:
          description: Price per kWh in the configured currency or emissions in g/kWh.
          type: number
      required:
        - start
        - end
        - value
    StaticEnergyPlan:
      description: Charging plan with an energy goal.
      type: object
      properties:
        energy:
          description: Energy goal in kWh.
          type: number
        time:
          description: Target time.
          type: string
          format: date-time
      required:
        - energy
        - time
    PlanStrategy:
      description: Charging plan strategy.
      type: object
      properties:
        continuous:
          description: Force continuous charging without gaps.
          type: boolean
        precondition:
          description: Duration of uninterrupted charging directly before the target time, in seconds.
          type: number
      required:
        - continuous
        - precondition
    OnboardingItem:
      description: Setup checklist item.
      type: string
      enum:
        - battery
        - pv
        - grid
        - loadpoint
        - heater
        - consumer
        - gridImport
        - gridExport
        - co2
        - solar
    OnboardingState:
      description: Setup wizard and checklist state.
      type: object
      properties:
        done:
          description: Setup wizard was finished or skipped.
          type: boolean
        dismissed:
          description: Dismissed setup checklist items.
          type: array
          items:
            $ref: '#/components/schemas/OnboardingItem'
      required:
        - done
        - dismissed
    ChargerStatusReason:
      description: Reason why the charger is waiting.
      type: string
      enum:
        - unknown
        - waitingforauthorization
        - disconnectrequired
    PhaseAction:
      description: Pending phase switching action in smart mode.
      type: string
      enum:
        - inactive
        - scale1p
        - scale3p
    PvAction:
      description: Pending charge start or stop action in smart mode.
      type: string
      enum:
        - inactive
        - enable
        - disable
    LoadpointSuggestion:
      description: Battery optimizer suggestion for a loadpoint.
      type: object
      properties:
        action:
          description: Suggested charging action.
          type: string
          enum:
            - charge
            - stop
        charge:
          description: Recommended charge power in W.
          type: number
        discharge:
          description: Recommended discharge power in W.
          type: number
        grid:
          description: Planned site grid flow of the slot in W, positive means import.
          type: number
        battery:
          description: Planned home battery discharge feeding the site in W.
          type: number
        actionable:
          description: Suggestion differs from the current operating mode.
          type: boolean
      required:
        - action
    LoadpointUi:
      description: Display-only UI settings of a loadpoint.
      type: object
      properties:
        minTemp:
          description: Lower bound of the temperature scale for heating devices, in degrees.
          type: number
        maxTemp:
          description: Upper bound of the temperature scale for heating devices, in degrees.
          type: number
      required:
        - minTemp
        - maxTemp
    Loadpoint:
      description: A charging location with a charger, an optional dedicated meter and an optional vehicle.
      type: object
      properties:
        name:
          description: Unique loadpoint identifier used in API routes and configuration.
          type: string
        alwaysCharge:
          $ref: '#/components/schemas/AlwaysCharge'
          description: Always charge state. Smart mode charges continuously at least at minimum power.
        batteryBoost:
          description: Battery boost is active. When enabled, home battery power is used for fast charging.
          type: boolean
        chargeCurrents:
          description: Charging current per phase in A.
          type: array
          items:
            type: number
        chargeDuration:
          description: Duration of the current charging session in seconds.
          type: number
        chargePower:
          description: Current charging power in W.
          type: number
        chargeRemainingDuration:
          description: Estimated remaining charging time in seconds.
          type: number
        chargeRemainingEnergy:
          description: Estimated remaining energy in kWh.
          type: number
        chargeTotalImport:
          description: Total energy imported by the charge meter in kWh.
          type: number
        chargeVoltages:
          description: Charging voltage per phase in V.
          type: array
          items:
            type: number
        chargedEnergy:
          description: Energy charged in the current charging session in kWh.
          type: number
        chargerFeatureAutodetectDisabled:
          description: The connected vehicle is not identified automatically by its status.
          type: boolean
        chargerFeatureAverage:
          description: Values are averaged.
          type: boolean
        chargerFeatureCacheable:
          description: Values are cached.
          type: boolean
        chargerFeatureClimaterDisabled:
          description: The climater state of the connected vehicle is ignored for charge control.
          type: boolean
        chargerFeatureCoarseCurrent:
          description: Charger only supports full ampere steps for current control.
          type: boolean
        chargerFeatureContinuous:
          description: Charger is a heating device where disabled means normal operation.
          type: boolean
        chargerFeatureDemandTemperature:
          description: Heating device demand forecast uses daily average profile scaled by outdoor temperature.
          type: boolean
        chargerFeatureDemandWeekday:
          description: Heating device demand forecast uses same-weekday average over past 4 weeks.
          type: boolean
        chargerFeatureHeating:
          description: Charger is a heating device. SoC values represent temperature in degrees.
          type: boolean
        chargerFeatureIntegratedDevice:
          description: Charger is an always-connected device without vehicles and charging sessions, like a heat pump.
          type: boolean
        chargerFeatureOffline:
          description: The connected vehicle only provides data while charging.
          type: boolean
        chargerFeatureRetryable:
          description: Vehicle API calls are retried on failure.
          type: boolean
        chargerFeatureStreaming:
          description: The connected vehicle pushes data updates instead of being polled.
          type: boolean
        chargerFeatureSwitchDevice:
          description: Charger is a switchable device without current control, like a heat pump or switch socket.
          type: boolean
        chargerFeatureWakeUpDisabled:
          description: No wake-up calls are sent to the connected vehicle.
          type: boolean
        chargerFeatureWelcomeCharge:
          description: The connected vehicle may need a short welcome charge to start communicating.
          type: boolean
        chargerIcon:
          description: Charger icon name for UI display.
          type: string
          nullable: true
        chargerPhases1p3p:
          description: Charger supports automatic switching between 1-phase and 3-phase charging.
          type: boolean
        chargerSinglePhase:
          description: Charger is physically connected with a single phase.
          type: boolean
        chargerStatusReason:
          description: Reason why the charger is waiting, like a pending authorization or a required disconnect.
          nullable: true
          allOf:
            - $ref: '#/components/schemas/ChargerStatusReason'
        charging:
          description: A vehicle is connected and charging.
          type: boolean
        connected:
          description: A vehicle is connected to the charger.
          type: boolean
        connectedDuration:
          description: Duration since the vehicle was connected, in seconds.
          type: number
        disabled:
          description: Loadpoint is disabled via configuration.
          type: boolean
        disableDelay:
          description: Delay before charging stops in smart mode, in seconds.
          type: number
        disableThreshold:
          description: Grid draw power above which charging stops in smart mode, in W.
          type: number
        effectiveLimitSoc:
          description: Currently applied SoC limit in %.
          type: number
        effectiveMaxCurrent:
          description: Currently applied maximum charging current in A.
          type: number
        effectiveMinCurrent:
          description: Currently applied minimum charging current in A.
          type: number
        effectiveMinSoc:
          description: Currently applied minimum SoC in %.
          type: number
        effectivePlanId:
          description: Id of the currently applied charging plan. Zero if no plan is active.
          type: number
        effectivePlanSoc:
          description: SoC goal in % of the currently applied charging plan.
          type: number
        effectivePlanTime:
          description: Target time of the currently applied charging plan.
          type: string
          nullable: true
          format: date-time
        effectivePlanStrategy:
          $ref: '#/components/schemas/PlanStrategy'
          description: Currently applied charging plan strategy.
        effectivePriority:
          description: Currently applied priority.
          type: number
        enableDelay:
          description: Delay before charging starts in smart mode, in seconds.
          type: number
        enableThreshold:
          description: Available surplus power above which charging starts in smart mode, in W.
          type: number
        enabled:
          description: Charger is currently allowed to charge.
          type: boolean
        limitEnergy:
          description: Session energy limit in kWh. Zero means no limit.
          type: number
        limitSoc:
          description: Session SoC limit in %. Zero means no limit.
          type: number
        maxCurrent:
          description: Maximum charging current in A.
          type: number
        minCurrent:
          description: Minimum charging current in A.
          type: number
        minSoc:
          description: Minimum SoC in %. Vehicle is fast-charged until this level is reached.
          type: number
        minSocNotReached:
          description: Vehicle SoC is below the configured minimum SoC.
          type: boolean
        mode:
          $ref: '#/components/schemas/ChargeMode'
          description: Charging behavior.
        offeredCurrent:
          description: Current offered to the vehicle in A.
          type: number
        optimizerControlled:
          description: Optimizer decides start/stop for this loadpoint, replacing the price limits.
          type: boolean
        phaseAction:
          $ref: '#/components/schemas/PhaseAction'
          description: Pending phase switching action in smart mode.
        phaseRemaining:
          description: Remaining time until the pending phase switching action executes, in seconds.
          type: number
        phasesActive:
          description: Number of phases expected to be used for charging.
          type: number
        phasesConfigured:
          description: Configured phase mode. 0 is automatic switching, 1 and 3 select a fixed phase count.
          type: number
        plan:
          description: Time slots of the current charging plan.
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/Rate'
        planActive:
          description: The current time slot is an active charging slot of the plan.
          type: boolean
        planEnergy:
          description: Energy goal of the charging plan in kWh.
          type: number
        planOverrun:
          description: Duration in seconds the charging plan is projected to miss its target time.
          type: number
        planStrategy:
          $ref: '#/components/schemas/PlanStrategy'
          description: Charging plan strategy.
        planProjectedEnd:
          description: Projected end of the charging plan. End of the last planned slot.
          type: string
          nullable: true
          format: date-time
        planProjectedStart:
          description: Projected start of the charging plan. Start of the earliest planned slot.
          type: string
          nullable: true
          format: date-time
        planTime:
          description: Target time of the charging plan.
          type: string
          nullable: true
          format: date-time
        priority:
          description: Priority for surplus distribution. Higher number means higher priority.
          type: number
        pvAction:
          $ref: '#/components/schemas/PvAction'
          description: Pending charge start or stop action in smart mode.
        pvRemaining:
          description: Remaining time until the pending charge start or stop action executes, in seconds.
          type: number
        last24hEnergy:
          description: Energy used in the last 24 hours in kWh.
          type: number
        last7dEnergy:
          description: Energy used in the last 7 days in kWh.
          type: number
        sessionCo2PerKWh:
          description: Average CO₂ emissions of the current charging session in g/kWh.
          type: number
          nullable: true
        sessionEnergy:
          description: Energy charged in the current charging session in kWh.
          type: number
        sessionPrice:
          description: Total cost of the current charging session in the configured currency.
          type: number
          nullable: true
        sessionPricePerKWh:
          description: Average energy price of the current charging session per kWh in the configured currency.
          type: number
          nullable: true
        sessionSolarPercentage:
          description: Share of solar energy in the current charging session in %.
          type: number
        smartCostActive:
          description: Fast charging with cheap or clean grid energy is currently active.
          type: boolean
        smartCostLimit:
          description: Price or emission limit for fast charging with grid energy.
          type: number
          nullable: true
        smartCostNextStart:
          description: Start of the next fast charging period with cheap or clean grid energy.
          type: string
          nullable: true
          format: date-time
        smartFeedInPriorityActive:
          description: Charging pause for prioritized feed-in is currently active.
          type: boolean
        smartFeedInPriorityLimit:
          description: Feed-in rate limit above which charging is paused.
          type: number
          nullable: true
        smartFeedInPriorityNextStart:
          description: Start of the next charging pause for prioritized feed-in.
          type: string
          nullable: true
          format: date-time
        solarShare:
          description: Required solar share. Usually 0 to 1; values outside that range are possible via API for special cases.
          type: number
        suggestion:
          description: Charging suggestion from the battery optimizer.
          nullable: true
          allOf:
            - $ref: '#/components/schemas/LoadpointSuggestion'
        title:
          description: Loadpoint title for UI display.
          type: string
        todayEnergy:
          description: Energy used since midnight in kWh.
          type: number
        vehicleClimaterActive:
          description: Climater of the connected vehicle is active.
          type: boolean
          nullable: true
        vehicleDetectionActive:
          description: Automatic vehicle detection is running.
          type: boolean
        vehicleLimitSoc:
          description: SoC limit configured in the vehicle itself, in %.
          type: number
        vehicleName:
          description: Unique name of the connected vehicle. Empty for guest vehicles.
          type: string
        vehicleOdometer:
          description: Odometer reading of the connected vehicle in km.
          type: number
        vehicleRange:
          description: Range of the connected vehicle in km.
          type: number
        vehicleSoc:
          description: Charge level of the connected vehicle in %. Temperature in degrees for heating devices.
          type: number
        vehicleTitle:
          description: Title of the connected vehicle for UI display.
          type: string
        vehicleWelcomeActive:
          description: A short welcome charge is active to enable vehicle communication.
          type: boolean
        batteryBoostLimit:
          description: SoC limit for battery boost in %.
          type: number
        ui:
          $ref: '#/components/schemas/LoadpointUi'
          description: Display-only UI settings.
      required:
        - name
        - alwaysCharge
        - batteryBoost
        - chargeDuration
        - chargePower
        - chargedEnergy
        - chargerFeatureAutodetectDisabled
        - chargerFeatureAverage
        - chargerFeatureCacheable
        - chargerFeatureClimaterDisabled
        - chargerFeatureCoarseCurrent
        - chargerFeatureContinuous
        - chargerFeatureDemandTemperature
        - chargerFeatureDemandWeekday
        - chargerFeatureHeating
        - chargerFeatureIntegratedDevice
        - chargerFeatureOffline
        - chargerFeatureRetryable
        - chargerFeatureStreaming
        - chargerFeatureSwitchDevice
        - chargerFeatureWakeUpDisabled
        - chargerFeatureWelcomeCharge
        - chargerIcon
        - chargerPhases1p3p
        - chargerSinglePhase
        - charging
        - connected
        - connectedDuration
        - disableDelay
        - disableThreshold
        - effectiveLimitSoc
        - effectiveMaxCurrent
        - effectiveMinCurrent
        - effectiveMinSoc
        - effectivePlanId
        - effectivePlanSoc
        - effectivePlanTime
        - effectivePlanStrategy
        - effectivePriority
        - enableDelay
        - enableThreshold
        - enabled
        - limitEnergy
        - limitSoc
        - maxCurrent
        - minCurrent
        - minSoc
        - minSocNotReached
        - mode
        - offeredCurrent
        - optimizerControlled
        - phaseAction
        - phaseRemaining
        - phasesActive
        - phasesConfigured
        - plan
        - planActive
        - planEnergy
        - planOverrun
        - planStrategy
        - planProjectedEnd
        - planProjectedStart
        - planTime
        - priority
        - pvAction
        - pvRemaining
        - sessionCo2PerKWh
        - sessionEnergy
        - sessionPrice
        - sessionPricePerKWh
        - sessionSolarPercentage
        - smartCostActive
        - smartCostLimit
        - smartCostNextStart
        - smartFeedInPriorityActive
        - smartFeedInPriorityLimit
        - smartFeedInPriorityNextStart
        - solarShare
        - title
        - vehicleClimaterActive
        - vehicleDetectionActive
        - vehicleLimitSoc
        - vehicleName
        - vehicleOdometer
        - vehicleRange
        - vehicleSoc
        - vehicleTitle
        - vehicleWelcomeActive
        - batteryBoostLimit
    ForecastSlot:
      description: A forecast time slot as [start, end, value] array. Start and end are unix seconds. Value unit depends on the forecast type.
      type: array
      items:
        type: number
      minItems: 3
      maxItems: 3
    EnergyByDay:
      description: Expected solar production energy of a day.
      type: object
      properties:
        energy:
          description: Expected production energy in kWh.
          type: number
        complete:
          description: Forecast data covers the whole day.
          type: boolean
      required:
        - energy
        - complete
    TimeseriesEntry:
      description: A forecast value at a point in time as [ts, val] array. ts is unix seconds, val is power in W.
      type: array
      items:
        type: number
      minItems: 2
      maxItems: 2
    SolarDetails:
      description: Solar production forecast.
      type: object
      properties:
        scale:
          description: Correction factor applied to the forecast based on past production.
          type: number
        today:
          $ref: '#/components/schemas/EnergyByDay'
          description: Expected production today.
        tomorrow:
          $ref: '#/components/schemas/EnergyByDay'
          description: Expected production tomorrow.
        dayAfterTomorrow:
          $ref: '#/components/schemas/EnergyByDay'
          description: Expected production the day after tomorrow.
        timeseries:
          description: Expected production power over time.
          type: array
          items:
            $ref: '#/components/schemas/TimeseriesEntry'
    Forecast:
      description: Price, CO₂ and solar production forecasts.
      type: object
      properties:
        grid:
          description: Grid price forecast. Price per kWh in the configured currency per time slot.
          type: array
          items:
            $ref: '#/components/schemas/ForecastSlot'
        co2:
          description: CO₂ emission forecast in g/kWh per time slot.
          type: array
          items:
            $ref: '#/components/schemas/ForecastSlot'
        solar:
          $ref: '#/components/schemas/SolarDetails'
          description: Solar production forecast.
        planner:
          description: Charging cost forecast used by the plan optimizer per time slot.
          type: array
          items:
            $ref: '#/components/schemas/ForecastSlot'
        feedin:
          description: Grid export price forecast. Price per kWh in the configured currency per time slot.
          type: array
          items:
            $ref: '#/components/schemas/ForecastSlot'
        temperature:
          description: Temperature forecast in °C per time slot.
          type: array
          items:
            $ref: '#/components/schemas/ForecastSlot'
    Currency:
      description: Currency in ISO 4217 format.
      type: string
      enum:
        - AUD
        - BGN
        - BRL
        - CAD
        - CHF
        - CNY
        - CZK
        - EUR
        - GBP
        - HUF
        - ILS
        - JPY
        - NZD
        - NOK
        - PLN
        - RON
        - USD
        - DKK
        - SEK
        - ZAR
        - TRY
        - MYR
        - THB
        - BYN
        - UAH
        - RUB
        - KZT
    FatalError:
      description: A fatal startup error.
      type: object
      properties:
        error:
          description: Error message.
          type: string
        class:
          description: Device class the error originates from, like meter or charger.
          type: string
        device:
          description: Name of the device that caused the error.
          type: string
      required:
        - error
    AuthProviders:
      description: Status of configured vehicle authentication providers, keyed by provider name.
      type: object
      additionalProperties:
        type: object
        properties:
          id:
            type: string
          authenticated:
            type: boolean
        required:
          - id
          - authenticated
    BatterySuggestion:
      description: Battery optimizer suggestion for a home battery.
      type: object
      properties:
        action:
          description: Suggested operation mode.
          type: string
          enum:
            - normal
            - hold
            - charge
            - holdcharge
            - discharge
        charge:
          description: Recommended charge power in W.
          type: number
        discharge:
          description: Recommended discharge power in W.
          type: number
        grid:
          description: Planned site grid flow of the slot in W, positive means import.
          type: number
        actionable:
          description: Suggestion differs from the current operating mode.
          type: boolean
      required:
        - action
    BatteryMeter:
      description: Measurement data of a single home battery meter.
      type: object
      properties:
        name:
          description: Unique device name of the meter.
          type: string
        power:
          description: Current power in W.
          type: number
        title:
          description: Meter title for UI display.
          type: string
        icon:
          description: Meter icon name for UI display.
          type: string
        energy:
          description: Total energy in kWh.
          type: number
        returnEnergy:
          description: Total exported energy in kWh.
          type: number
        powers:
          description: Power per phase in W.
          type: array
          items:
            type: number
        currents:
          description: Current per phase in A.
          type: array
          items:
            type: number
        soc:
          description: Charge level in %.
          type: number
        controllable:
          description: Battery supports external control of its operation mode.
          type: boolean
        modes:
          description: Battery modes supported by the device.
          type: array
          items:
            type: string
        capacity:
          description: Battery capacity in kWh. Zero when not specified.
          type: number
        minSoc:
          description: Minimum soc (reserve) in % as configured on the device.
          type: number
        maxSoc:
          description: Maximum soc (charge limit) in % as configured on the device.
          type: number
        suggestion:
          $ref: '#/components/schemas/BatterySuggestion'
          description: Battery optimizer suggestion.
      required:
        - capacity
        - controllable
        - power
        - soc
    BatteryForecastPoint:
      description: A projected home battery charge level at a point in time.
      type: object
      properties:
        soc:
          description: Projected charge level in %.
          type: number
        time:
          description: Time of the projected charge level.
          type: string
          format: date-time
        limit:
          description: The projection hits the upper or lower battery limit.
          type: boolean
      required:
        - soc
        - time
    BatteryForecast:
      description: Projected home battery charge levels based on the solar and price forecast.
      type: object
      properties:
        highest:
          $ref: '#/components/schemas/BatteryForecastPoint'
          description: Projected highest charge level.
        lowest:
          $ref: '#/components/schemas/BatteryForecastPoint'
          description: Projected lowest charge level.
    Battery:
      description: Home battery state. Aggregated across all battery meters.
      type: object
      properties:
        power:
          description: Current battery power in W. Positive means discharging, negative means charging.
          type: number
        capacity:
          description: Total battery capacity in kWh.
          type: number
        soc:
          description: Charge level in %. Weighted by capacity across all batteries.
          type: number
        energy:
          description: Total discharged energy in kWh.
          type: number
        returnEnergy:
          description: Total charged energy in kWh.
          type: number
        devices:
          description: Measurement data per battery meter.
          type: array
          items:
            $ref: '#/components/schemas/BatteryMeter'
        forecast:
          $ref: '#/components/schemas/BatteryForecast'
          description: Projected charge levels based on the solar and price forecast.
      required:
        - power
        - capacity
        - soc
    Meter:
      description: Measurement data of a single meter.
      type: object
      properties:
        name:
          description: Unique device name of the meter.
          type: string
        power:
          description: Current power in W.
          type: number
        title:
          description: Meter title for UI display.
          type: string
        icon:
          description: Meter icon name for UI display.
          type: string
        energy:
          description: Total energy in kWh.
          type: number
        returnEnergy:
          description: Total exported energy in kWh.
          type: number
        powers:
          description: Power per phase in W.
          type: array
          items:
            type: number
        currents:
          description: Current per phase in A.
          type: array
          items:
            type: number
      required:
        - power
    GRID_CONNECTION:
      description: Grid connection, with or without neutral conductor.
      type: string
      enum:
        - 3p4w
        - 3p3w
    GenericConfigStatus:
      description: Configuration and runtime status of an integration. Structure depends on configuration.
      type: object
      properties:
        config:
          description: Static configuration.
        status:
          description: Runtime status.
        yamlSource:
          description: Source of the configuration, evcc.yaml file or database.
          type: string
          enum:
            - file
            - db
    MqttConfig:
      description: MQTT integration configuration.
      type: object
      properties:
        broker:
          description: Broker address.
          type: string
        topic:
          description: Root topic all values are published under.
          type: string
        user:
          description: Broker username.
          type: string
        password:
          description: Broker password. Redacted.
          type: string
        clientID:
          description: MQTT client id.
          type: string
        insecure:
          description: Skip TLS certificate verification.
          type: boolean
        caCert:
          description: CA certificate for TLS connections.
          type: string
        clientCert:
          description: Client certificate for TLS connections.
          type: string
        clientKey:
          description: Client key for TLS connections.
          type: string
      required:
        - broker
        - topic
    InfluxConfig:
      description: InfluxDB integration configuration.
      type: object
      properties:
        url:
          description: InfluxDB server URL.
          type: string
        database:
          description: Database name (InfluxDB 1.x) or bucket (InfluxDB 2.x).
          type: string
        org:
          description: Organization (InfluxDB 2.x).
          type: string
        token:
          description: Access token (InfluxDB 2.x). Redacted.
          type: string
        user:
          description: Username (InfluxDB 1.x).
          type: string
        password:
          description: Password (InfluxDB 1.x). Redacted.
          type: string
        insecure:
          description: Skip TLS certificate verification.
          type: boolean
      required:
        - url
        - database
        - org
    Network:
      description: Network configuration.
      type: object
      properties:
        schema:
          description: URL schema, http or https.
          type: string
        host:
          description: Hostname.
          type: string
        port:
          description: HTTP port.
          type: number
        externalUrl:
          description: Externally reachable URL.
          type: string
        internalUrl:
          description: URL in the local network.
          type: string
      required:
        - host
        - port
    HemsConfig:
      description: Home energy management system configuration.
      type: object
      properties:
        configured:
          description: A home energy management system is configured.
          type: boolean
      required:
        - configured
    HemsStatus:
      description: Current external limits imposed by the home energy management system.
      type: object
      properties:
        dimmed:
          description: Consumption is currently limited.
          type: boolean
        curtailed:
          description: Allowed grid export in %. Values below 100 mean production is curtailed.
          type: number
        maxConsumptionPower:
          description: Maximum allowed consumption power in W.
          type: number
        maxProductionPower:
          description: Maximum allowed production power in W.
          type: number
    Hems:
      description: Home energy management system integration.
      type: object
      properties:
        config:
          $ref: '#/components/schemas/HemsConfig'
          description: Static configuration.
        status:
          $ref: '#/components/schemas/HemsStatus'
          description: Runtime status.
        yamlSource:
          description: Source of the configuration, evcc.yaml file or database.
          type: string
          enum:
            - file
            - db
    ShmConfig:
      description: SMA Home Manager configuration.
      type: object
      properties:
        vendorId:
          description: SMA vendor id.
          type: string
        deviceId:
          description: SMA device id.
          type: string
        deviceSerial:
          description: SMA device serial.
          type: string
      required:
        - vendorId
        - deviceId
    SponsorStatus:
      description: Sponsorship status.
      type: object
      properties:
        name:
          description: Name of the sponsor.
          type: string
        expiresAt:
          description: Expiry time of the sponsor token.
          type: string
          format: date-time
        expiresSoon:
          description: Sponsor token expires soon.
          type: boolean
        token:
          description: Sponsor token. Redacted.
          type: string
        hardware:
          description: Hardware sponsorship.
          type: boolean
    Sponsor:
      description: Sponsorship status.
      type: object
      properties:
        config:
          description: Static configuration.
        status:
          $ref: '#/components/schemas/SponsorStatus'
          description: Runtime status.
        yamlSource:
          description: Source of the configuration, evcc.yaml file or database.
          type: string
          enum:
            - file
            - db
    Certificate:
      description: A TLS certificate key pair.
      type: object
      properties:
        public:
          description: Public certificate in PEM format.
          type: string
        private:
          description: Private key in PEM format. Redacted.
          type: string
      required:
        - public
        - private
    EebusConfig:
      description: EEBUS integration configuration.
      type: object
      properties:
        uri:
          description: URI the EEBUS service listens on.
          type: string
        port:
          description: Port the EEBUS service listens on.
          type: number
        shipid:
          description: SHIP id.
          type: string
        interfaces:
          description: Network interfaces the EEBUS service uses.
          type: array
          items:
            type: string
        certificate:
          $ref: '#/components/schemas/Certificate'
          description: TLS certificate.
      required:
        - port
        - shipid
    EebusStatus:
      description: EEBUS runtime status.
      type: object
      properties:
        ski:
          description: SKI (subject key identifier) used for pairing.
          type: string
        qr:
          description: QR code payload for pairing.
          type: string
      required:
        - ski
    Eebus:
      description: EEBUS integration configuration and status.
      type: object
      properties:
        config:
          $ref: '#/components/schemas/EebusConfig'
          description: Static configuration.
        status:
          $ref: '#/components/schemas/EebusStatus'
          description: Runtime status.
        yamlSource:
          description: Source of the configuration, evcc.yaml file or database.
          type: string
          enum:
            - file
            - db
    RemoteConfig:
      description: Remote access configuration.
      type: object
      properties:
        enabled:
          description: Remote access is enabled.
          type: boolean
      required:
        - enabled
    RemoteStatus:
      description: Remote access connection status.
      type: object
      properties:
        connected:
          description: Connection to the remote access server is established.
          type: boolean
        url:
          description: Remote access URL.
          type: string
        loginBlocked:
          description: Remote login attempts are currently blocked by the rate limiter.
          type: boolean
        lastSeen:
          description: Last remote activity per client, keyed by username. RFC3339 timestamps.
          type: object
          additionalProperties:
            type: string
        error:
          description: Last connection error.
          type: string
      required:
        - connected
        - loginBlocked
    Remote:
      description: Remote access configuration and connection status.
      type: object
      properties:
        config:
          $ref: '#/components/schemas/RemoteConfig'
          description: Static configuration.
        status:
          $ref: '#/components/schemas/RemoteStatus'
          description: Runtime status.
        yamlSource:
          description: Source of the configuration, evcc.yaml file or database.
          type: string
          enum:
            - file
            - db
    ModbusProxyReadonly:
      description: How the Modbus proxy handles write requests.
      type: string
      enum:
        - 'false'
        - 'true'
        - deny
    ModbusBaudrate:
      description: Serial baud rate.
      type: number
      enum:
        - 1200
        - 9600
        - 19200
        - 38400
        - 57600
        - 115200
    ModbusComset:
      description: Serial communication parameters.
      type: string
      enum:
        - 8N1
        - '8E1'
        - 8N2
    ModbusProxySettings:
      description: Connection settings of a Modbus device.
      type: object
      properties:
        uri:
          description: Device address for TCP connections.
          type: string
        rtu:
          description: Use RTU protocol over TCP.
          type: boolean
        device:
          description: Serial device path.
          type: string
        baudrate:
          $ref: '#/components/schemas/ModbusBaudrate'
          description: Serial baud rate.
        comset:
          $ref: '#/components/schemas/ModbusComset'
          description: Serial communication parameters.
    ModbusProxy:
      description: A Modbus proxy forwarding requests to a physical device.
      type: object
      properties:
        port:
          description: Port the proxy listens on.
          type: number
        readonly:
          $ref: '#/components/schemas/ModbusProxyReadonly'
          description: How write requests are handled.
        settings:
          $ref: '#/components/schemas/ModbusProxySettings'
          description: Connection settings of the physical device.
      required:
        - port
        - readonly
        - settings
    MessagingEvent:
      description: A configured notification message.
      type: object
      properties:
        title:
          description: Message title template.
          type: string
        msg:
          description: Message body template.
          type: string
        disabled:
          description: Notifications for this event are disabled.
          type: boolean
      required:
        - title
        - msg
        - disabled
    MessagingEvents:
      description: Configured notification messages, keyed by event type.
      type: object
      properties:
        start:
          $ref: '#/components/schemas/MessagingEvent'
        stop:
          $ref: '#/components/schemas/MessagingEvent'
        connect:
          $ref: '#/components/schemas/MessagingEvent'
        disconnect:
          $ref: '#/components/schemas/MessagingEvent'
        soc:
          $ref: '#/components/schemas/MessagingEvent'
        guest:
          $ref: '#/components/schemas/MessagingEvent'
        asleep:
          $ref: '#/components/schemas/MessagingEvent'
        planoverrun:
          $ref: '#/components/schemas/MessagingEvent'
        suggestion:
          $ref: '#/components/schemas/MessagingEvent'
      required:
        - start
        - stop
        - connect
        - disconnect
        - soc
        - guest
        - asleep
        - planoverrun
        - suggestion
      additionalProperties: false
    Circuit:
      description: A load management circuit limiting power and current of its assigned loadpoints.
      type: object
      properties:
        name:
          description: Circuit name used as configuration reference.
          type: string
        title:
          description: Circuit title for UI display.
          type: string
        icon:
          description: Circuit icon name for UI display.
          type: string
        parent:
          description: Name of the parent circuit.
          type: string
        power:
          description: Current power in W.
          type: number
        current:
          description: Current in A.
          type: number
        maxPower:
          description: Maximum allowed power in W.
          type: number
        maxCurrent:
          description: Maximum allowed current in A.
          type: number
      required:
        - power
    SmartCostType:
      description: Type of the smart charging limit.
      type: string
      enum:
        - co2
        - pricedynamic
        - priceforecast
        - pricestatic
    DeviceColorEntry:
      description: Color assigned to a device for consistent UI display.
      type: object
      properties:
        title:
          description: Device title the color is assigned to.
          type: string
        color:
          description: Assigned color as CSS value.
          type: string
      required:
        - title
        - color
    StaticSocPlan:
      description: Charging plan with a SoC goal.
      type: object
      properties:
        soc:
          description: SoC goal in %.
          type: number
        time:
          description: Target time.
          type: string
          format: date-time
      required:
        - soc
        - time
    StaticPlan:
      description: Charging plan with a fixed target time and a SoC or energy goal.
      anyOf:
        - $ref: '#/components/schemas/StaticSocPlan'
        - $ref: '#/components/schemas/StaticEnergyPlan'
    RepeatingPlan:
      description: A repeating charging plan.
      type: object
      properties:
        weekdays:
          description: Weekdays the plan is active. 0 is Sunday, 6 is Saturday.
          type: array
          items:
            type: number
        time:
          description: Target time in HH:MM format.
          type: string
        tz:
          description: Time zone of the target time, like Europe/Berlin.
          type: string
        soc:
          description: SoC goal in %.
          type: number
        active:
          description: Plan is active.
          type: boolean
      required:
        - weekdays
        - time
        - tz
        - soc
        - active
    Vehicle:
      description: A configured vehicle.
      type: object
      properties:
        name:
          description: Unique vehicle name used in API routes and configuration.
          type: string
        mode:
          description: Charge mode applied when the vehicle connects.
          anyOf:
            - $ref: '#/components/schemas/ChargeMode'
            - type: string
              enum:
                - ''
        alwaysCharge:
          description: Always charge state applied when the vehicle connects.
          anyOf:
            - $ref: '#/components/schemas/AlwaysCharge'
            - type: string
              enum:
                - ''
        minSoc:
          description: Minimum SoC in %. Vehicle is fast-charged until this level is reached.
          type: number
        limitSoc:
          description: SoC limit in %. Charging stops when reached.
          type: number
        plan:
          $ref: '#/components/schemas/StaticPlan'
          description: Charging plan with a fixed target time and SoC or energy goal.
        repeatingPlans:
          description: Repeating charging plans.
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/RepeatingPlan'
        planStrategy:
          $ref: '#/components/schemas/PlanStrategy'
          description: Charging plan strategy.
        title:
          description: Vehicle title for UI display.
          type: string
        features:
          description: Feature flags of the vehicle implementation.
          type: array
          items:
            type: string
        capacity:
          description: Usable battery capacity in kWh.
          type: number
        icon:
          description: Vehicle icon name for UI display.
          type: string
      required:
        - repeatingPlans
        - planStrategy
        - title
    StatisticsData:
      description: Aggregated charging statistics for a time period.
      type: object
      properties:
        avgCo2:
          description: Average CO₂ emissions in g/kWh.
          type: number
        avgPrice:
          description: Average energy price per kWh in the configured currency.
          type: number
        chargedKWh:
          description: Total charged energy in kWh.
          type: number
        solarPercentage:
          description: Share of solar energy in %.
          type: number
      required:
        - avgCo2
        - avgPrice
        - chargedKWh
        - solarPercentage
    Statistics:
      description: Charging statistics, keyed by time period.
      type: object
      properties:
        30d:
          $ref: '#/components/schemas/StatisticsData'
        365d:
          $ref: '#/components/schemas/StatisticsData'
        thisYear:
          $ref: '#/components/schemas/StatisticsData'
        total:
          $ref: '#/components/schemas/StatisticsData'
      required:
        - 30d
        - 365d
        - thisYear
        - total
    OcppConfig:
      description: OCPP server configuration.
      type: object
      properties:
        port:
          description: Port the OCPP server listens on.
          type: number
      required:
        - port
    OcppConnectionStatus:
      description: Connection status of an OCPP station.
      type: string
      enum:
        - unknown
        - configured
        - connected
    OcppStationStatus:
      description: Connection status of an OCPP station.
      type: object
      properties:
        id:
          description: Station id.
          type: string
        status:
          $ref: '#/components/schemas/OcppConnectionStatus'
          description: Connection status.
      required:
        - id
        - status
    OcppStatus:
      description: OCPP server status.
      type: object
      properties:
        externalUrl:
          description: Externally reachable URL of the OCPP server.
          type: string
        stations:
          description: Connection status per configured station.
          type: array
          items:
            $ref: '#/components/schemas/OcppStationStatus'
      required:
        - stations
    Ocpp:
      description: OCPP server configuration and status.
      type: object
      properties:
        config:
          $ref: '#/components/schemas/OcppConfig'
          description: OCPP server configuration.
        status:
          $ref: '#/components/schemas/OcppStatus'
          description: OCPP server status.
      required:
        - config
        - status
    OcppForwarderRule:
      description: A rule forwarding an OCPP station to an upstream backend.
      type: object
      properties:
        stationId:
          description: Station id to forward.
          type: string
        upstreamUrl:
          description: URL of the upstream OCPP backend.
          type: string
        password:
          description: Password for upstream authentication. Redacted.
          type: string
        upstreamStationId:
          description: Station id used towards the upstream backend.
          type: string
        username:
          description: Username for upstream authentication.
          type: string
        insecure:
          description: Skip TLS certificate verification.
          type: boolean
        caCert:
          description: CA certificate for TLS connections.
          type: string
        readOnly:
          description: Only forward read operations to the station.
          type: boolean
      required:
        - stationId
        - upstreamUrl
    OcppForwarderSession:
      description: Connection status of an OCPP forwarder rule.
      type: object
      properties:
        chargerId:
          description: Charger id.
          type: string
        upstreamUrl:
          description: URL of the upstream OCPP backend.
          type: string
        upstreamConnected:
          description: Connection to the upstream backend is established.
          type: boolean
        error:
          description: Last connection error.
          type: string
      required:
        - chargerId
        - upstreamUrl
        - upstreamConnected
    OcppForwarder:
      description: OCPP forwarder rules and upstream connection status.
      type: object
      properties:
        config:
          description: Static configuration.
          type: array
          items:
            $ref: '#/components/schemas/OcppForwarderRule'
        status:
          description: Runtime status.
          type: array
          items:
            $ref: '#/components/schemas/OcppForwarderSession'
        yamlSource:
          description: Source of the configuration, evcc.yaml file or database.
          type: string
          enum:
            - file
            - db
    OptimizerAutomatic:
      type: string
      enum:
        - 'off'
        - battery
        - full
    State:
      description: Complete system state as returned by /api/state and pushed via websocket and MQTT. This structure mirrors the internal UI state and carries no compatibility promise. Fields may change or disappear between releases.
      type: object
      properties:
        telemetry:
          description: Telemetry is enabled.
          type: boolean
        experimental:
          description: Experimental UI features are enabled.
          type: boolean
        setupRequired:
          description: Initial setup is required.
          type: boolean
        onboarding:
          $ref: '#/components/schemas/OnboardingState'
          description: Setup wizard and checklist state.
        startupCompleted:
          description: Startup has completed.
          type: boolean
        apiReady:
          description: HTTP API is ready to accept requests.
          type: boolean
        loadpoints:
          description: Charging locations. One entry per configured loadpoint.
          type: array
          items:
            $ref: '#/components/schemas/Loadpoint'
        forecast:
          $ref: '#/components/schemas/Forecast'
          description: Price, CO₂ and solar production forecasts.
        currency:
          $ref: '#/components/schemas/Currency'
          description: Configured currency for all monetary values.
        country:
          description: Configured site country as ISO 3166-1 alpha-2 code. Empty when not set.
          type: string
          example: DE
        fatal:
          description: Fatal startup errors.
          type: array
          items:
            $ref: '#/components/schemas/FatalError'
        authProviders:
          $ref: '#/components/schemas/AuthProviders'
          description: Status of configured vehicle authentication providers, keyed by provider name.
        version:
          description: Running evcc version.
          type: string
        availableVersion:
          description: Latest available evcc version.
          type: string
        system:
          description: Operating system and architecture.
          type: string
          example: linux/amd64
        timezone:
          description: Server time zone abbreviation and UTC offset.
          type: string
          example: CEST +02:00
        battery:
          $ref: '#/components/schemas/Battery'
          description: Aggregated home battery state.
        batteryMode:
          $ref: '#/components/schemas/BatteryMode'
          description: Current operation mode of the home battery.
        grid:
          $ref: '#/components/schemas/Meter'
          description: Grid meter data.
        gridConfigured:
          description: A grid meter is configured.
          type: boolean
        gridConnection:
          $ref: '#/components/schemas/GRID_CONNECTION'
          description: Grid connection, with or without neutral conductor.
        voltage:
          description: Nominal grid voltage in V, line-to-line without neutral.
          type: number
        pv:
          description: Solar meters. One entry per configured meter.
          type: array
          items:
            $ref: '#/components/schemas/Meter'
        pvPower:
          description: Total solar power in W. Sum of all solar meters.
          type: number
        pvEnergy:
          description: Total solar production in kWh.
          type: number
        aux:
          description: Auxiliary consumption meters. Their power is treated as available for charging.
          type: array
          items:
            $ref: '#/components/schemas/Meter'
        auxPower:
          description: Total power of all auxiliary meters in W.
          type: number
        ext:
          description: Additional meters for monitoring purposes.
          type: array
          items:
            $ref: '#/components/schemas/Meter'
        consumers:
          description: Consumption meters of individual devices for monitoring purposes.
          type: array
          items:
            $ref: '#/components/schemas/Meter'
        homePower:
          description: Home consumption power in W.
          type: number
        residualPower:
          description: Configured grid operating point in W. Positive values maintain grid import.
          type: number
        gridExportLimit:
          description: Static grid export power limit in W used as optimizer constraint, 0 = disabled. An active HEMS curtailment takes precedence.
          type: number
        profilePercentile:
          description: Percentile of the historic energy profiles used for demand prediction in %, e.g. 50 = median. Null uses the average.
          type: number
          nullable: true
        greenShareHome:
          description: Share of green energy in home consumption, between 0 and 1.
          type: number
        greenShareLoadpoints:
          description: Share of green energy used for charging, between 0 and 1.
          type: number
        tariffs:
          $ref: '#/components/schemas/GenericConfigStatus'
          description: Configured tariffs. Structure depends on configuration.
        tariffGrid:
          description: Current grid energy price per kWh in the configured currency.
          type: number
        tariffFeedIn:
          description: Current grid export price per kWh in the configured currency.
          type: number
        tariffCo2:
          description: Current grid CO₂ emissions in g/kWh.
          type: number
        tariffSolar:
          description: Current cost of solar production per kWh in the configured currency.
          type: number
        tariffPriceHome:
          description: Current energy price of home consumption per kWh, taking the green energy share into account.
          type: number
        tariffPriceLoadpoints:
          description: Current energy price of charging per kWh, taking the green energy share into account.
          type: number
        tariffCo2Home:
          description: Current CO₂ emissions of home consumption in g/kWh, taking the green energy share into account.
          type: number
        tariffCo2Loadpoints:
          description: Current CO₂ emissions of charging in g/kWh, taking the green energy share into account.
          type: number
        tariffTemperature:
          description: Current outside temperature in °C.
          type: number
        mqtt:
          $ref: '#/components/schemas/MqttConfig'
          description: MQTT integration configuration.
        influx:
          $ref: '#/components/schemas/InfluxConfig'
          description: InfluxDB integration configuration.
        network:
          $ref: '#/components/schemas/Network'
          description: Network configuration.
        hems:
          $ref: '#/components/schemas/Hems'
          description: Home energy management system integration.
        shm:
          $ref: '#/components/schemas/ShmConfig'
          description: SMA Home Manager configuration.
        sponsor:
          $ref: '#/components/schemas/Sponsor'
          description: Sponsorship status.
        eebus:
          $ref: '#/components/schemas/Eebus'
          description: EEBUS integration configuration and status.
        remote:
          $ref: '#/components/schemas/Remote'
          description: Remote access configuration and connection status.
        modbusproxy:
          description: Modbus proxy configuration.
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/ModbusProxy'
        messaging:
          $ref: '#/components/schemas/GenericConfigStatus'
          description: Messaging services configuration. Structure depends on configuration.
        messagingEvents:
          description: Configured notification messages per event type.
          nullable: true
          allOf:
            - $ref: '#/components/schemas/MessagingEvents'
        interval:
          description: Update interval of the control loop in seconds.
          type: number
        circuits:
          description: Load management circuits, keyed by circuit name.
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Circuit'
        circuitsConfig:
          $ref: '#/components/schemas/GenericConfigStatus'
          description: Load management configuration.
        bufferSoc:
          description: Battery buffer SoC in %. Energy above this level may be used for charging in smart mode.
          type: number
        prioritySoc:
          description: Battery priority SoC in %. Home battery is charged first while below this level.
          type: number
        bufferStartSoc:
          description: Battery buffer start SoC in %. Solar charging starts automatically above this level.
          type: number
        batteryDischargeControl:
          description: Home battery discharge is prevented during fast charging and planned charging.
          type: boolean
        batteryGridDischarge:
          description: Home battery is allowed to discharge to the grid (experimental).
          type: boolean
        solarAdjusted:
          description: Solar forecast is adjusted to real production data (experimental).
          type: boolean
        batteryGridChargeLimit:
          description: Price or emission limit for charging the home battery from grid.
          type: number
          nullable: true
        batteryGridChargeActive:
          description: Home battery is currently charged from grid.
          type: boolean
        batteryGridDischargeLimit:
          description: Grid export price limit for discharging the home battery to the grid (experimental).
          type: number
          nullable: true
        batteryGridDischargeActive:
          description: Home battery is currently discharged to the grid.
          type: boolean
        smartCostAvailable:
          description: A dynamic grid price or CO₂ forecast is configured.
          type: boolean
        smartCostType:
          $ref: '#/components/schemas/SmartCostType'
          description: Type of the smart charging limit, price based or emission based.
        smartFeedInPriorityAvailable:
          description: A grid export tariff with forecast is configured.
          type: boolean
        historyUpdated:
          description: Time of the last energy history update.
          type: string
          format: date-time
        siteTitle:
          description: Configured site title.
          type: string
        deviceColors:
          description: Colors assigned to devices for consistent UI display.
          type: array
          items:
            $ref: '#/components/schemas/DeviceColorEntry'
        vehicles:
          description: Configured vehicles, keyed by vehicle name.
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Vehicle'
        statistics:
          $ref: '#/components/schemas/Statistics'
          description: Charging statistics over different time periods.
        authDisabled:
          description: Authentication is disabled.
          type: boolean
        config:
          description: Path of the evcc configuration file.
          type: string
        database:
          description: Path of the evcc database.
          type: string
        ocpp:
          $ref: '#/components/schemas/Ocpp'
          description: OCPP server configuration and connected stations.
        ocppforwarder:
          $ref: '#/components/schemas/OcppForwarder'
          description: OCPP forwarder rules and upstream connection status.
        optimizer:
          description: Battery optimizer is enabled.
          type: boolean
        optimizerAutomatic:
          $ref: '#/components/schemas/OptimizerAutomatic'
          description: 'What the optimizer controls instead of only advising: nothing, the home battery, or battery and loadpoints.'
        optimizerChargingStrategy:
          description: Selected battery optimizer charging strategy.
          type: string
        optimizerChargingStrategies:
          description: Available battery optimizer charging strategies.
          type: array
          items:
            type: string
        mcp:
          description: Built-in MCP server is enabled.
          type: boolean
        demoMode:
          description: Instance runs in demo mode.
          type: boolean
      required:
        - loadpoints
        - forecast
        - vehicles
  parameters:
    historyFrom:
      name: from
      in: query
      description: Start time (RFC3339)
      schema:
        type: string
        format: date-time
        example: '2026-07-01T00:00:00Z'
    historyTo:
      name: to
      in: query
      description: End time (RFC3339)
      schema:
        type: string
        format: date-time
        example: '2026-07-02T00:00:00Z'
    adminPassword:
      name: X-Admin-Password
      in: header
      description: Admin password (required for session auth, not needed for API key)
      schema:
        $ref: '#/components/schemas/Password'
    id:
      name: id
      description: Loadpoint index starting at 1
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Id'
    phases:
      name: phases
      description: 'Number of phases. (0: auto, 1: 1-phase, 3: 3-phase)'
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Phases'
    weekdays:
      name: weekdays
      description: The Weekdays
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Weekdays'
    hourMinuteTime:
      name: hourMinuteTime
      description: Time in `HOURS:MINUTES` format
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/HourMinuteTime'
    timezone:
      name: timezone
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/IANATimeZone'
    logAreas:
      name: areas
      description: Comma-separated list of log areas
      in: query
      explode: true
      schema:
        $ref: '#/components/schemas/LogAreas'
    logLevel:
      name: level
      description: Log level
      in: query
      required: true
      schema:
        $ref: '#/components/schemas/LogLevel'
    delay:
      name: delay
      description: Duration in seconds.
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Delay'
    mode:
      name: mode
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/ChargeModeInput'
    alwaysCharge:
      name: alwaysCharge
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/AlwaysCharge'
    soc:
      name: soc
      description: SoC in %
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Soc'
    temp:
      name: temp
      description: Temperature in °C
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Temp'
    timestamp:
      name: timestamp
      description: Timestamp in RFC3339 format
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Timestamp'
    vehicleName:
      name: name
      description: Vehicle name
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/VehicleName'
    vehicleAlwaysCharge:
      name: alwaysCharge
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/VehicleAlwaysCharge'
    current:
      name: current
      description: Electric current in A
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Current'
    power:
      name: power
      description: Power in W
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Power'
    energy:
      name: energy
      description: Energy in kWh
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Energy'
    threshold:
      name: threshold
      description: Power in W
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Power'
    batteryMode:
      name: batteryMode
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/BatteryMode'
    costLimit:
      name: cost
      description: Cost limit in configured currency (default EUR) or CO₂ limit in g/kWh
      example: 0.25
      in: path
      required: true
      schema:
        type: number
    enable:
      name: enable
      description: Charging mode.
      in: path
      required: true
      schema:
        type: string
        enum:
          - 'true'
          - 'false'
          - '1'
          - '0'
  responses:
    Deleted:
      description: Success - number of deleted records
      content:
        application/json:
          schema:
            type: object
            properties:
              deleted:
                type: integer
                example: 96
    NanoSecondsResult:
      description: Success - Number result - Unit is **nanoseconds**
      content:
        application/json:
          schema:
            type: integer
    NumberResult:
      description: Success - Number result
      content:
        application/json:
          schema:
            type: number
    IntegerResult:
      description: Success - Integer result
      content:
        application/json:
          schema:
            type: integer
    SocResult:
      description: Success - SoC result
      content:
        application/json:
          schema:
            type: object
            properties:
              soc:
                $ref: '#/components/schemas/Soc'
    PlanRatesResult:
      description: Success - PlanRates result
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PlanRates'
    BooleanResult:
      description: Success - Boolean result
      content:
        application/json:
          schema:
            type: boolean
    StringResult:
      description: Success - String result
      content:
        application/json:
          schema:
            type: string
    NullResult:
      description: Success - Null result
      content:
        application/json:
          schema:
            description: Value is always null
            nullable: true
            type: object
    BlankResponse:
      description: Success - Blank response
    SuccessResult:
      description: Success
      content:
        application/json:
          schema:
            type: string
            example: OK
    EmptyResult:
      description: Success - Empty result
      content:
        application/json:
          schema:
            type: object
    Unauthorized:
      description: Unauthorized - Login and try again
      content:
        text/plain:
          schema:
            type: string
            enum:
              - Unauthorized
    BatteryModeResult:
      description: Battery mode
      content:
        application/json:
          schema:
            type: integer
            description: 'Battery mode. 0: unknown, 1: normal, 2: hold, 3: charge, 4: holdcharge, 5: discharge'
            minimum: 0
            maximum: 5
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: auth
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        Long-lived API key (prefixed `evcc_`, managed via /auth/apikey).
        Grants access to /api/db/* without requiring the X-Admin-Password header.