Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we
store it to create your key and to recognise you if you sign in with another
provider. See our Privacy Policy and
Terms.
openapi: 3.2.0
info:
title: evcc General 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: General
paths:
/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'
/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'
/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
/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'
components:
schemas:
Power:
description: Power in W
type: number
minimum: 0
example: 2500
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
parameters:
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
power:
name: power
description: Power in W
in: path
required: true
schema:
$ref: '#/components/schemas/Power'
responses:
BlankResponse:
description: Success - Blank response
NullResult:
description: Success - Null result
content:
application/json:
schema:
description: Value is always null
nullable: true
type: object
NumberResult:
description: Success - Number result
content:
application/json:
schema:
type: number
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.
'