evcc (self-hosted) Experimental API

openapi: 3.2.0
info:
  title: evcc Experimental API
  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: Experimental
paths:
  /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:
      - 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
  /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'
  /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:
    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
  responses:
    StringResult:
      description: Success - String result
      content:
        application/json:
          schema:
            type: string
    BooleanResult:
      description: Success - Boolean result
      content:
        application/json:
          schema:
            type: boolean
  parameters:
    historyTo:
      name: to
      in: query
      description: End time (RFC3339)
      schema:
        type: string
        format: date-time
        example: '2026-07-02T00:00:00Z'
    historyFrom:
      name: from
      in: query
      description: Start time (RFC3339)
      schema:
        type: string
        format: date-time
        example: '2026-07-01T00:00:00Z'
    enable:
      name: enable
      description: Charging mode.
      in: path
      required: true
      schema:
        type: string
        enum:
        - 'true'
        - 'false'
        - '1'
        - '0'
  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.

        '