openapi: 3.1.0
x-redocly:
openapi:
hideSchemaTitles: true
info:
title: ev.energy v2 API
version: '2.0'
contact:
email: developers@ev.energy
url: developers.ev.energy
name: ev.energy developers
description: The official API for ev.energy, version 2.
license:
name: Proprietary
url: https://ev.energy
termsOfService: ''
servers:
- url: https://api.ev.energy/v2
description: Live API for both production and sandbox requests.
x-internal: false
- description: Staging server for internal testing only.
url: https://api-staging.ev.energy/v2
x-internal: true
paths:
/:
get:
summary: API root
description: Get links to resources accessible in the API.
operationId: get-root
responses:
'200':
description: Returns a list of all top-level collection URLs in the API.
content:
application/json:
schema:
type: object
properties:
users:
type: string
format: uri
carbon_feeds:
type: string
format: uri
evses:
type: string
format: uri
evse_models:
type: string
format: uri
evse_makes:
type: string
format: uri
vehicles:
type: string
format: uri
vehicle_trims:
type: string
format: uri
vehicle_models:
type: string
format: uri
vehicle_makes:
type: string
format: uri
suppliers:
type: string
format: uri
tariffs:
type: string
format: uri
support_tickets:
type: string
format: uri
dispatch_coordinators:
type: string
format: uri
grid_feeds:
type: string
format: uri
examples:
Example:
value:
users: https://api.ev.energy/v2/users/
carbon_feeds: https://api.ev.energy/v2/carbon_feeds/
evses: https://api.ev.energy/v2/evses/
evse_models: https://api.ev.energy/v2/evse_models/
evse_makes: https://api.ev.energy/v2/evse_makes/
vehicles: https://api.ev.energy/v2/vehicles/
vehicle_trims: https://api.ev.energy/v2/vehicle_trims/
vehicle_models: https://api.ev.energy/v2/vehicle_models/
vehicle_makes: https://api.ev.energy/v2/vehicle_makes/
suppliers: https://api.ev.energy/v2/suppliers/
tariffs: https://api.ev.energy/v2/tariffs/
support_tickets: https://api.ev.energy/v2/support_tickets/
dispatch_coordinators: https://api.ev.energy/v2/dispatch_coordinators/
grid_feeds: https://api.ev.energy/v2/grid_feeds/
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
security: []
parameters:
- $ref: '#/components/parameters/version-2'
tags:
- Root
/users:
get:
summary: List users
tags:
- Users
responses:
'200':
description: Returns a list of Users.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-users
description: List all the users that the authorization token has access to.
parameters:
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/expand-on-user'
- $ref: '#/components/parameters/email'
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/user'
security:
- oauth2:
- user:read
post:
summary: Create user
tags:
- Users
responses:
'201':
description: User Created Successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: post-users
security:
- oauth2:
- user:write
description: Create an individual user in the ev.energy system.
parameters:
- $ref: '#/components/parameters/version-2'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/User'
multipart/form-data:
schema:
$ref: '#/components/schemas/User'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/User'
/users/{user_id}:
parameters:
- $ref: '#/components/parameters/user_id'
get:
summary: Retrieve user
description: Retrieve information about a single, specific user.
tags:
- Users
responses:
'200':
description: Returns a single User.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-users-user_id
parameters:
- $ref: '#/components/parameters/expand-on-user'
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- user:read
patch:
summary: Update User
tags:
- Users
responses:
'200':
description: User updated successfully.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: patch-users-user_id
security:
- oauth2:
- user:write
description: Update user information.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/User'
multipart/form-data:
schema:
$ref: '#/components/schemas/User'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/User'
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/expand-on-user'
/users/{user_id}/notification_preferences:
parameters:
- $ref: '#/components/parameters/user_id'
get:
summary: Retrieve user notification preferences
description: >-
Retrieve the set of notification groups the user is currently subscribed
to.
tags:
- Users
responses:
'200':
description: Returns the user's notification preferences.
content:
application/json:
schema:
$ref: '#/components/schemas/UserNotificationPreferences'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'405':
$ref: '#/components/responses/Problem405MethodNotAllowed'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-users-user_id-notification_preferences
parameters:
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- notification_preferences:read
patch:
summary: Update user notification preferences
description: |-
Update the user's notification group opt-in state.
The `groups` object is treated as a partial map: only the keys you
include are modified. Keys you omit are left untouched. This means
clients only need to send the groups they want to change, and adding
new groups to the API in the future cannot accidentally clobber an
old client's silence on them.
`PATCH {}` and `PATCH {"groups": {}}` are valid no-ops. Unknown group
names produce a `400`.
tags:
- Users
responses:
'200':
description: Notification preferences updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/UserNotificationPreferences'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
'400':
$ref: >-
#/components/responses/Problem400UpdateNotificationPreferencesValidationFailed
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'405':
$ref: '#/components/responses/Problem405MethodNotAllowed'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: patch-users-user_id-notification_preferences
security:
- oauth2:
- notification_preferences:write
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UserNotificationPreferences'
parameters:
- $ref: '#/components/parameters/version-2'
/users/{user_id}/route_planner_preferences:
parameters:
- $ref: '#/components/parameters/user_id'
get:
summary: Retrieve route planner preferences
description: |-
Retrieve the user's EV Route Planner preferences (default vehicle,
en-route minimum charger power, and default arrival battery floor).
A preferences row is created with defaults on first access, so this
never 404s for an existing, accessible user.
tags:
- Users
operationId: get-users-user_id-route_planner_preferences
responses:
'200':
description: Returns the user's route planner preferences.
content:
application/json:
schema:
$ref: '#/components/schemas/RoutePlannerPreferences'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'405':
$ref: '#/components/responses/Problem405MethodNotAllowed'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
parameters:
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- route_planner_preferences:read
patch:
summary: Update route planner preferences
description: |-
Update the user's EV Route Planner preferences.
The body is treated as a partial map: only the keys you include are
modified, omitted keys are left untouched. `PATCH {}` is a valid no-op.
`preferred_vehicle` accepts a vehicle URL or `null`;
`min_charger_power_watts` accepts one of
`22000, 50000, 100000, 150000, 250000` or `null`.
tags:
- Users
operationId: patch-users-user_id-route_planner_preferences
responses:
'200':
description: Route planner preferences updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/RoutePlannerPreferences'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
'400':
$ref: >-
#/components/responses/Problem400UpdateRoutePlannerPreferencesValidationFailed
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'405':
$ref: '#/components/responses/Problem405MethodNotAllowed'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
security:
- oauth2:
- route_planner_preferences:write
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RoutePlannerPreferencesUpdate'
parameters:
- $ref: '#/components/parameters/version-2'
/vehicles/{vehicle_id}/connectors:
parameters:
- $ref: '#/components/parameters/vehicle_id'
get:
summary: Retrieve a vehicle's charging connectors
description: |-
Retrieve the vehicle's DC-fast charging connectors: its native plug and
any adapters it carries. `native_connector` is the per-vehicle value,
falling back to the vehicle model's default when not overridden (both
may be null when not yet known).
tags:
- Vehicles
responses:
'200':
description: Returns the vehicle's connector configuration.
content:
application/json:
schema:
$ref: '#/components/schemas/VehicleConnectors'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'405':
$ref: '#/components/responses/Problem405MethodNotAllowed'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-vehicles-vehicle_id-connectors
parameters:
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- vehicle:read
patch:
summary: Update a vehicle's charging connectors
description: |-
Update the vehicle's connectors. The body is a partial map: only the
keys you include are changed. Set `native_connector` to override the
model default for this vehicle, or `null` to inherit it. `adaptors`
replaces the adapter list (send `[]` to clear); adaptors must be
distinct and must not include the native connector. `PATCH {}` is a
valid no-op.
tags:
- Vehicles
responses:
'200':
description: Connectors updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/VehicleConnectors'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
'400':
$ref: >-
#/components/responses/Problem400UpdateVehicleConnectorsValidationFailed
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'405':
$ref: '#/components/responses/Problem405MethodNotAllowed'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: patch-vehicles-vehicle_id-connectors
security:
- oauth2:
- vehicle:write
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/VehicleConnectorsUpdate'
parameters:
- $ref: '#/components/parameters/version-2'
/vehicles/{vehicle_id}/state_of_charge:
parameters:
- $ref: '#/components/parameters/vehicle_id'
get:
summary: Retrieve a vehicle's current state of charge
description: |-
Retrieve the vehicle's current battery percentage used to seed route
plans. `source` indicates where the value came from: `MANUAL` when the
driver entered it, or `CONNECTED` when it comes from the vehicle's
telemetry. All fields are null when no value is available.
tags:
- Vehicles
responses:
'200':
description: Returns the vehicle's current state of charge.
content:
application/json:
schema:
$ref: '#/components/schemas/VehicleStateOfCharge'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'405':
$ref: '#/components/responses/Problem405MethodNotAllowed'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-vehicles-vehicle_id-state_of_charge
parameters:
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- vehicle:read
patch:
summary: Update a vehicle's current state of charge
description: |-
Set the vehicle's current battery percentage (Mode-1 manual entry). The
body is a partial map: `PATCH {}` is a valid no-op. Send
`state_of_charge_percentage: null` to clear it. `source` is read-only.
tags:
- Vehicles
responses:
'200':
description: State of charge updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/VehicleStateOfCharge'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
'400':
$ref: >-
#/components/responses/Problem400UpdateVehicleStateOfChargeValidationFailed
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'405':
$ref: '#/components/responses/Problem405MethodNotAllowed'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: patch-vehicles-vehicle_id-state_of_charge
security:
- oauth2:
- vehicle:write
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/VehicleStateOfChargeUpdate'
parameters:
- $ref: '#/components/parameters/version-2'
/auth/password_reset:
post:
summary: Request a password reset email
description: |-
Request a password reset email for the account with the supplied
email address. The response status and body are identical whether
or not an account exists for the email; clients must not treat the
success response as confirmation that an account exists.
tags:
- Auth
operationId: post-auth-password_reset
security: []
parameters:
- $ref: '#/components/parameters/version-2'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PasswordResetRequest'
responses:
'200':
description: Reset email request accepted.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/PasswordResetResult'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'422':
$ref: '#/components/responses/Problem422PasswordResetValidationFailed'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
/evse_compatibility/check:
get:
summary: Check EVSE model compatibility in a country
description: |-
Returns whether the given `EVSEModel` is supported in the supplied
country, and whether the support is `beta` (early-access) or live.
Used by the onboarding flow to tell the user upfront whether their
hardware will work before any account-linking step.
Public endpoint — callable pre-account, no authentication required.
Country resolution follows this order: explicit `country` query
parameter, then the `Accept-Language` header, then `US`.
When `program_id` is supplied, program membership is applied as an
additional filter on top of the global compatibility check: the
model must be in the program's `supported_evse_models` list AND
pass the global region + `EvseCompatibility` check. Region is
derived from the program's country, so the `country` query
parameter and `Accept-Language` header are ignored in that case.
Error responses follow RFC 9457 Problem Details. Problem types
emitted by this endpoint:
- `validation-failed-evse-compatibility-check` — missing or
invalid `evse_model_id` / `country` query parameter (`400`).
- `evse-model-not-found` — `evse_model_id` does not resolve to
an `EVSEModel` (`404`).
- `program-not-found` — `program_id` does not resolve to a
program (`404`).
tags:
- EVSEs
operationId: get-evse_compatibility-check
parameters:
- $ref: '#/components/parameters/version-2'
- name: evse_model_id
in: query
required: true
description: '`EVSEModel.uid` to check compatibility for.'
schema:
type: string
pattern: emod[A-Z\d]{26}
- name: country
in: query
required: false
description: ISO-3166 alpha-2 country code. See description for fallback chain.
schema:
type: string
pattern: ^[A-Za-z]{2}$
minLength: 2
maxLength: 2
- $ref: '#/components/parameters/Accept-Language'
- name: client_id
in: query
required: false
description: |-
OAuth `Application.client_id`. Mirrors the pre-account
onboarding endpoints: when supplied and the application has
sandbox mode enabled, the endpoint returns a canned response
without touching the database.
schema:
type: string
- name: program_id
in: query
required: false
description: |-
Program uid. When supplied, the model must be in the
program's `supported_evse_models` list AND pass the global
region + `EvseCompatibility` check. Region is derived from
the program's country; `country` and `Accept-Language` are
ignored in that case. Omit for the core app's pre-account
flow where the program is not yet known.
schema:
type: string
pattern: prog[A-Z\d]{26}
responses:
'200':
description: Compatibility verdict for the supplied model and country.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/EVSECompatibilityCheckResult'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'404':
$ref: '#/components/responses/Problem404NotFound'
'405':
$ref: '#/components/responses/Problem405MethodNotAllowed'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
security: []
/users/{user_id}/payout_method:
parameters:
- $ref: '#/components/parameters/user_id'
get:
summary: Retrieve payout method
description: |
Retrieve the user's preferred payout method. Returns null fields when
the user has not set up a payout method.
tags:
- Users
operationId: get-users-user_id-payout-method
responses:
'200':
description: Returns the user's payout method.
content:
application/json:
schema:
$ref: '#/components/schemas/PayoutMethod'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'405':
$ref: '#/components/responses/Problem405MethodNotAllowed'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
parameters:
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- payout_method:read
patch:
summary: Update payout method
description: |
Create or update the user's preferred payout method. The request must
always include `receiver_wallet`. For `PAYPAL` and `VENMO` the
client must also supply `receiver` (an email or phone respectively).
For `BILL_CREDITS` the `receiver` must not be supplied — it is
derived server-side from the user's linked billing account.
tags:
- Users
operationId: patch-users-user_id-payout-method
responses:
'200':
description: Payout method updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PayoutMethod'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
'400':
$ref: '#/components/responses/Problem400UpdatePayoutMethodValidationFailed'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'405':
$ref: '#/components/responses/Problem405MethodNotAllowed'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
parameters:
- $ref: '#/components/parameters/version-2'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PayoutMethodUpdate'
security:
- oauth2:
- payout_method:write
delete:
summary: Delete payout method
description: |
Clear the user's preferred payout method. The user's stored
``UserPayoutMethod`` records are not removed; only the
``preferred_payout_method`` link on the user is cleared. Returns 204
even when the user already has no payout method set (no-op).
tags:
- Users
operationId: delete-users-user_id-payout-method
responses:
'204':
description: Payout method cleared.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'405':
$ref: '#/components/responses/Problem405MethodNotAllowed'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
parameters:
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- payout_method:write
/users/{user_id}/saved_routes:
parameters:
- $ref: '#/components/parameters/user_id'
get:
summary: List saved routes
description: |
List the user's saved route-planner routes. A saved route is a reusable
"recipe" — origin, destination, waypoints and planning preferences — not
a stored charging plan; the plan is recalculated on each re-plan.
tags:
- Users
operationId: get-users-user_id-saved_routes
responses:
'200':
description: Returns the user's saved routes.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SavedRoute'
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'405':
$ref: '#/components/responses/Problem405MethodNotAllowed'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
security:
- oauth2:
- saved_routes:read
post:
summary: Create a saved route
description: |
Create a new saved route for the user. The route is owned by the user
named in the path; `id`, `url`, `user` and `created_at` are assigned by
the server. `last_used_at` defaults to now when omitted.
A user may save at most 50 routes; exceeding this returns a `400`.
tags:
- Users
operationId: post-users-user_id-saved_routes
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SavedRouteCreate'
responses:
'201':
description: The saved route was created.
content:
application/json:
schema:
$ref: '#/components/schemas/SavedRoute'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
'400':
$ref: '#/components/responses/Problem400SavedRouteValidationFailed'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'405':
$ref: '#/components/responses/Problem405MethodNotAllowed'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
parameters:
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- saved_routes:write
/users/{user_id}/saved_routes/{saved_route_id}:
parameters:
- $ref: '#/components/parameters/user_id'
- $ref: '#/components/parameters/saved_route_id'
get:
summary: Retrieve a saved route
tags:
- Users
operationId: get-users-user_id-saved_routes-saved_route_id
responses:
'200':
description: Returns the saved route.
content:
application/json:
schema:
$ref: '#/components/schemas/SavedRoute'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'405':
$ref: '#/components/responses/Problem405MethodNotAllowed'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
parameters:
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- saved_routes:read
patch:
summary: Update a saved route
description: |
Partially update a saved route: rename it, toggle `favourite`, bump
`last_used_at` after a re-plan, or edit the endpoints. Only the fields
supplied are changed.
tags:
- Users
operationId: patch-users-user_id-saved_routes-saved_route_id
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SavedRoutePatch'
responses:
'200':
description: The saved route was updated.
content:
application/json:
schema:
$ref: '#/components/schemas/SavedRoute'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
'400':
$ref: '#/components/responses/Problem400SavedRouteValidationFailed'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'405':
$ref: '#/components/responses/Problem405MethodNotAllowed'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
parameters:
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- saved_routes:write
delete:
summary: Delete a saved route
tags:
- Users
operationId: delete-users-user_id-saved_routes-saved_route_id
responses:
'204':
description: The saved route was deleted.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'405':
$ref: '#/components/responses/Problem405MethodNotAllowed'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
parameters:
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- saved_routes:write
/evses:
get:
summary: List EVSEs
tags:
- EVSEs
responses:
'200':
description: Returns a list of EVSEs.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/EVSE'
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-evses
parameters:
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/expand-on-evse'
- $ref: '#/components/parameters/cpid'
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/user'
description: List all the EVSEs that the authorization token has access to.
security:
- oauth2:
- evse:read
/evses/{evse_id}:
parameters:
- $ref: '#/components/parameters/evse_id'
get:
summary: Retrieve an EVSE
tags:
- EVSEs
responses:
'200':
description: Returns a single EVSE.
content:
application/json:
schema:
$ref: '#/components/schemas/EVSE'
examples:
Example 1:
value:
id: evse01HSH04KDEWF6Z4DB2J77J74K5
url: >-
https://api.ev.energy/v2/evses/evse01HSH04KDEWF6Z4DB2J77J74K5
model:
id: emod01HS9A004X5TB5JCMHENB5Z446
name: EVWC2S22
make:
id: emak01HS8FRXKJD5JZZ7ZN6W8H21P8
name: BG SyncEV
user: >-
https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-evses-evse_id
parameters:
- $ref: '#/components/parameters/expand-on-evse'
- $ref: '#/components/parameters/version-2'
description: Retrieve a single, specific EVSE's details.
security:
- oauth2:
- evse:read
patch:
summary: Update an EVSE
tags:
- EVSEs
responses:
'200':
description: EVSE updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/EVSE'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400UpdateEVSEValidationFailed'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: patch-evses-evse_id
parameters:
- $ref: '#/components/parameters/expand-on-evse'
- $ref: '#/components/parameters/version-2'
description: >-
Update an EVSE. Only the EVSE's `location` may be changed via this
endpoint; all other fields are read-only.
A `400` is returned when the request body fails validation (for example
a non-numeric, non-finite or out-of-range coordinate), with the
offending fields listed under `field_errors`.
security:
- oauth2:
- evse:write
requestBody:
description: The EVSE fields to update.
content:
application/json:
schema:
type: object
properties:
location:
type:
- object
- 'null'
properties:
latitude:
type: number
format: double
example: 51.5074
longitude:
type: number
format: double
example: -0.1278
required:
- latitude
- longitude
description: >-
The geographic location of the EVSE as a latitude/longitude
point. Send `null` to clear it.
delete:
summary: Decommission an EVSE
tags:
- EVSEs
responses:
'204':
description: The EVSE has been decommissioned successfully.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: delete-evses-evse_id
parameters:
- $ref: '#/components/parameters/version-2'
description: Decommission the EVSE by disconnecting it from the ev.energy system.
security:
- oauth2:
- evse:write
/evse_models:
get:
summary: List EVSE models
tags:
- EVSEs
responses:
'200':
description: Returns a list of EVSE models.
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/EVSEModel'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-evse_models
parameters:
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/expand-on-evsemodel'
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/available_for_user_id'
- $ref: '#/components/parameters/user'
- $ref: '#/components/parameters/evse_make_id_q'
description: |-
List all the EVSE models known by the ev.energy system.
Anonymous callers are rate limited to 50 requests per hour per IP.
security: []
/evse_models/{evse_model_id}:
get:
summary: Retrieve an EVSE model
tags:
- EVSEs
responses:
'200':
description: Return a single EVSE model.
content:
application/json:
schema:
$ref: '#/components/schemas/EVSEModel'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-evse_models-evse_model_id
parameters:
- $ref: '#/components/parameters/expand-on-evsemodel'
- $ref: '#/components/parameters/version-2'
description: |-
Retrieve details for a single, specific EVSE model.
Anonymous callers are rate limited to 50 requests per hour per IP.
security: []
parameters:
- $ref: '#/components/parameters/evse_model_id'
/evse_makes:
get:
summary: List EVSE makes
tags:
- EVSEs
responses:
'200':
description: Return a list of EVSE Makes.
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/EVSEMake'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-evse_makes
parameters:
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/available_for_user_id'
- $ref: '#/components/parameters/user'
description: |-
List all the EVSE makes known by the ev.energy system.
Anonymous callers are rate limited to 50 requests per hour per IP.
security: []
parameters: []
/evse_makes/{evse_make_id}:
parameters:
- $ref: '#/components/parameters/evse_make_id'
get:
summary: Retrieve an EVSE make
tags:
- EVSEs
responses:
'200':
description: Return a single EVSE make.
content:
application/json:
schema:
$ref: '#/components/schemas/EVSEMake'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-evse_makes-evse_make_id
parameters:
- $ref: '#/components/parameters/version-2'
description: |-
Retrieve details for a single, specific EVSE make.
Anonymous callers are rate limited to 50 requests per hour per IP.
security: []
/evses/{evse_id}/status_logs:
get:
summary: List status logs for an EVSE
description: >-
List the historical status logs for a specific EVSE. Used to find out
the state of the EVSE at each point it reported in to ev.energy.
tags:
- EVSEs
responses:
'200':
description: List all status logs for a specific EVSE, sorted newest first.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/EVSEStatusLog'
headers:
Link:
$ref: '#/components/headers/link-timestamps'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-evses-evse_id-status_logs
parameters:
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/sampled_at__gte'
- $ref: '#/components/parameters/sampled_at__lte'
- $ref: '#/components/parameters/expand-on-evsestatuslog'
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- evse:read
parameters:
- $ref: '#/components/parameters/evse_id'
/evses/{evse_id}/status_logs/{sampled_at}:
parameters:
- $ref: '#/components/parameters/evse_id'
- schema:
type: string
format: date-time
name: sampled_at
in: path
required: true
description: The time the log's data was recorded on the device.
example: '2024-04-17T09:39:45.984584Z'
get:
summary: Retrieve a status log for an EVSE
description: >-
An EVSE status log is uniquely identified by the combination of EVSE ID
and the time it was sampled at.
tags:
- EVSEs
responses:
'200':
description: Retrieve a single status log for a specific EVSE.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/EVSEStatusLog'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-evses-evse_id-status_logs-timestamp
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/expand-on-evsestatuslog'
security:
- oauth2:
- evse:read
/evses/{evse_id}/command_logs:
parameters:
- $ref: '#/components/parameters/evse_id'
get:
summary: List command logs for an EVSE
description: >-
List the historical command logs for a specific EVSE. These logs record
commands that were sent to the EVSE.
tags:
- EVSEs
responses:
'200':
description: List all command logs for a specific EVSE, sorted newest first.
headers:
Link:
$ref: '#/components/headers/link-timestamps'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/EVSECommandLog'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-evses-evse_id-command_logs
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/logged_at__gte'
- $ref: '#/components/parameters/logged_at__lte'
- $ref: '#/components/parameters/expand-on-evsecommandlog'
security:
- oauth2:
- debug:read
/evses/{evse_id}/command_logs/{logged_at}:
parameters:
- $ref: '#/components/parameters/evse_id'
- schema:
type: string
format: date-time
name: logged_at
in: path
required: true
description: The time the command was logged.
example: '2024-04-17T09:39:45.984584Z'
get:
summary: Retrieve a command log for an EVSE
description: >-
An EVSE command log is uniquely identified by the combination of EVSE ID
and the time it was logged at.
tags:
- EVSEs
responses:
'200':
description: Retrieve a single command log for a specific EVSE.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/EVSECommandLog'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-evses-evse_id-command_logs-timestamp
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/expand-on-evsecommandlog'
security:
- oauth2:
- debug:read
/evses/{evse_id}/error_logs:
parameters:
- $ref: '#/components/parameters/evse_id'
get:
summary: List API error logs for an EVSE
description: >-
List the historical API error logs for a specific EVSE. These logs
capture errors that occurred when attempting to communicate with the
EVSE's hardware API.
tags:
- EVSEs
responses:
'200':
description: List all API error logs for a specific EVSE, sorted newest first.
headers:
Link:
$ref: '#/components/headers/link-timestamps'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/EVSEAPIErrorLog'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-evses-evse_id-error_logs
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/sampled_at__gte'
- $ref: '#/components/parameters/sampled_at__lte'
- $ref: '#/components/parameters/expand-on-evseerrorlog'
security:
- oauth2:
- debug:read
/evses/{evse_id}/error_logs/{sampled_at}:
parameters:
- $ref: '#/components/parameters/evse_id'
- schema:
type: string
format: date-time
name: sampled_at
in: path
required: true
description: The time the error was sampled.
example: '2024-04-17T09:39:45.984584Z'
get:
summary: Retrieve a specific API error log for an EVSE
description: >-
A single API error log for a particular EVSE is uniquely identified by
the timestamp it was sampled at.
tags:
- EVSEs
responses:
'200':
description: Returns the EVSE API error logged at a specific time.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/EVSEAPIErrorLog'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-evses-evse_id-error_logs-timestamp
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/expand-on-evseerrorlog'
security:
- oauth2:
- debug:read
/evses/{evse_id}/ocpp_logs:
parameters:
- $ref: '#/components/parameters/evse_id'
get:
summary: List OCPP logs for an EVSE
description: >-
List the historical OCPP message logs for a specific EVSE. These logs
record OCPP messages sent to or received from the charger.
tags:
- EVSEs
responses:
'200':
description: List all OCPP logs for a specific EVSE, sorted newest first.
headers:
Link:
$ref: '#/components/headers/link-timestamps'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/EVSEOCPPLog'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-evses-evse_id-ocpp_logs
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/sampled_at__gte'
- $ref: '#/components/parameters/sampled_at__lte'
- $ref: '#/components/parameters/ocpp-action'
- $ref: '#/components/parameters/ocpp-action__in'
- $ref: '#/components/parameters/ocpp-direction'
- $ref: '#/components/parameters/ocpp-error_code'
- $ref: '#/components/parameters/ocpp-error_code__in'
- $ref: '#/components/parameters/expand-on-evseocpplog'
security:
- oauth2:
- debug:read
/evses/{evse_id}/ocpp_logs/{sampled_at}:
parameters:
- $ref: '#/components/parameters/evse_id'
- schema:
type: string
format: date-time
name: sampled_at
in: path
required: true
description: The time the OCPP message was recorded.
example: '2024-04-17T09:39:45.984584Z'
get:
summary: Retrieve an OCPP log for an EVSE
description: >-
An EVSE OCPP log is uniquely identified by the combination of EVSE ID
and the time it was sampled at.
tags:
- EVSEs
responses:
'200':
description: Retrieve a single OCPP log for a specific EVSE.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/EVSEOCPPLog'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-evses-evse_id-ocpp_logs-timestamp
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/expand-on-evseocpplog'
security:
- oauth2:
- debug:read
/evses/{evse_id}/vpp_modes:
parameters:
- $ref: '#/components/parameters/evse_id'
get:
summary: Get VPP modes for an EVSE
description: >-
Returns the VPP (Virtual Power Plant) control modes supported by this
EVSE.
tags:
- EVSEs
- VPP
responses:
'200':
description: Returns the VPP modes supported by this EVSE.
content:
application/json:
schema:
$ref: '#/components/schemas/VPPModes'
examples:
EVSE VPP Modes:
value:
target_power: true
import_max_power: true
export_max_power: false
charge_mode: true
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-evses-evse_id-vpp_modes
parameters:
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- evse:read
/evses/{evse_id}/connectivity:
parameters:
- $ref: '#/components/parameters/evse_id'
get:
summary: Get connectivity information for an EVSE
description: >-
Returns a snapshot of the EVSE's connectivity metrics including signal
strength, SIM data, firmware version, and connection reliability.
tags:
- EVSEs
responses:
'200':
description: Returns the connectivity information for this EVSE.
content:
application/json:
schema:
$ref: '#/components/schemas/EVSEConnectivity'
examples:
EVSE Connectivity:
value:
signal_strength_rssi_dbm: -65
lowest_signal_strength_rssi_dbm_7d: -89
highest_signal_strength_rssi_dbm_7d: -57
connection_reliability_30d: 97
ip_address: 10.193.28.42
iccid: '8944110000001234567'
firmware_version: 1.2.3
latest_status_log: >-
https://api.ev.energy/v2/evses/evse01HSH04KDEWF6Z4DB2J77J74K5/status_logs/2024-04-17T09:39:45.984584Z/
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-evses-evse_id-connectivity
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/expand-on-evse-connectivity'
security:
- oauth2:
- evse:read
/ct_clamps:
get:
summary: List CT Clamps
tags:
- CT Clamps
responses:
'200':
description: Returns a list of CT clamps.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CTClamp'
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-ct-clamps
parameters:
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/expand-on-ctclamp'
- $ref: '#/components/parameters/version-2'
description: List all CT clamps that the authorization token has access to.
security:
- oauth2:
- evse:read
/ct_clamps/{ct_clamp_id}:
parameters:
- $ref: '#/components/parameters/ct_clamp_id'
get:
summary: Retrieve a CT Clamp
tags:
- CT Clamps
responses:
'200':
description: Returns a single CT clamp.
content:
application/json:
schema:
$ref: '#/components/schemas/CTClamp'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-ct-clamps-ct_clamp_id
parameters:
- $ref: '#/components/parameters/expand-on-ctclamp'
- $ref: '#/components/parameters/version-2'
description: Retrieve a single CT clamp's details.
security:
- oauth2:
- evse:read
/ct_clamps/{ct_clamp_id}/logs:
parameters:
- $ref: '#/components/parameters/ct_clamp_id'
get:
summary: List logs for a CT Clamp
description: List the historical current measurement logs for a specific CT clamp.
tags:
- CT Clamps
responses:
'200':
description: Returns a list of CT clamp logs.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CTClampLog'
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-ct-clamps-ct_clamp_id-logs
parameters:
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/sampled_at__gte'
- $ref: '#/components/parameters/sampled_at__lte'
- $ref: '#/components/parameters/expand-on-ctclamplog'
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- evse:read
/ct_clamps/{ct_clamp_id}/logs/{sampled_at}:
parameters:
- $ref: '#/components/parameters/ct_clamp_id'
- schema:
type: string
format: date-time
name: sampled_at
in: path
required: true
description: The time the log's data was recorded on the device.
example: '2024-04-17T09:39:45.984584Z'
get:
summary: Retrieve a log for a CT Clamp
tags:
- CT Clamps
responses:
'200':
description: Returns a single CT clamp log.
content:
application/json:
schema:
$ref: '#/components/schemas/CTClampLog'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-ct-clamps-ct_clamp_id-logs-sampled_at
parameters:
- $ref: '#/components/parameters/expand-on-ctclamplog'
- $ref: '#/components/parameters/version-2'
description: Retrieve a single CT clamp log entry.
security:
- oauth2:
- evse:read
/evses/{evse_id}/reconnect:
parameters:
- $ref: '#/components/parameters/evse_id'
post:
summary: Create EVSE reconnection URL
tags:
- EVSEs
responses:
'201':
description: Returns the newly generated reconnection URL.
content:
application/json:
schema:
$ref: '#/components/schemas/EVSEReconnectionUrl'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestCreate'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: post-evses-evse_id-reconnect
x-stoplight:
id: evse-reconnect-endpoint
description: >-
Create a reconnection request URL for the EVSE. The EVSE must have a
user assigned.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EVSEReconnectionUrl'
parameters:
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- evse:write
/evse_firmware_versions:
get:
summary: List EVSE firmware versions
description: |-
List EVSE firmware versions available in the catalogue. Only firmware
versions flagged as production releases are returned.
tags:
- EVSEs
responses:
'200':
description: Returns a list of EVSE firmware versions.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/EVSEFirmwareVersion'
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-evse_firmware_versions
parameters:
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- evse:read
/evse_firmware_versions/{evse_firmware_version_id}:
parameters:
- $ref: '#/components/parameters/evse_firmware_version_id'
get:
summary: Retrieve an EVSE firmware version
description: Retrieve a single EVSE firmware version by ID.
tags:
- EVSEs
responses:
'200':
description: Returns an EVSE firmware version.
content:
application/json:
schema:
$ref: '#/components/schemas/EVSEFirmwareVersion'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-evse_firmware_versions-evse_firmware_version_id
parameters:
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- evse:read
/evse_onboarding:
get:
summary: Initiate EVSE onboarding
tags:
- EVSEs
responses:
'200':
description: >-
Returned only when `response_type=json` is supplied. Carries an
absolute URL to the EVSE onboarding wrapper that the client opens in
a WebView (mobile) or redirects the browser to (web). The wrapper
view either redirects to the provider (when a model was supplied) or
shows the make picker.
content:
application/json:
schema:
$ref: '#/components/schemas/EVSEOnboardingJsonResponse'
'302':
description: >-
Have the user's browser follow the redirect to be prompted to
connect their EVSE to the ev.energy system.
If a make or model were not provided, the user will first be
redirected to a screen to select these.
headers:
Location:
schema:
type: string
description: >-
The URL that the users browser will be redirected to in order to
integrate their EVSE.
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'404':
$ref: '#/components/responses/Problem404NotFound'
operationId: get-evse_onboarding
description: >-
Initiate the onboarding process for a new EVSE in your user's browser
(or an embedded web view in an app).
If neither `make_id` or `model_id` are passed as query parameters, the
user will be shown a user interface to pick their EVSE make.
## Native clients (`response_type=json`)
Native mobile clients that need to open the onboarding URL in a WebView
(rather than follow a 302 redirect) can pass `response_type=json` to
receive a JSON payload instead. In that case at least one of `make_id`
or `model_id` is required (otherwise the endpoint responds with `400`).
## Final redirect
After the user completes the web flow, the browser is redirected to the
`redirect_uri` query parameter (when supplied and valid) or otherwise
the `onboarding_redirect_url` configured on your application. The
redirect URL will carry two query parameters identifying the onboarded
EVSE:
- `evse_uid` — the v2 UID of the onboarded EVSE (preferred). Use this to
call `GET /v2/evses/{evse_uid}` for further details.
- `evse_id` — the legacy integer primary key. Prefer `evse_uid`.
Example: `https://your-redirect/?evse_id=123&evse_uid=evse01...`.
parameters:
- $ref: '#/components/parameters/user_id_onboarding'
- schema:
type: string
example: emak01HN2NJQRGDQP0GBE1F7R6PB3D
in: query
name: make_id
description: Specify the make of EVSE to be onboarded.
- schema:
type: string
example: emod01HN2NJHAJJAQD32QJ4QXTDSGW
in: query
name: model_id
description: Specify the model of EVSE to be onboarded.
- $ref: '#/components/parameters/client_id'
- schema:
type: string
enum:
- json
in: query
name: response_type
description: >-
When set to `json`, the endpoint returns a JSON payload (200)
instead of a 302 redirect. Used by native mobile clients that prefer
to open the onboarding URL in a WebView. Requires at least one of
`make_id` or `model_id`.
- schema:
type: string
format: uri
example: https://drivers.ev.energy/acme
in: query
name: redirect_uri
description: >-
Optional URL to return the user to after onboarding completes. Its
scheme and host must match one of the application's registered
`redirect_uris` or its `onboarding_redirect_url`, otherwise the
endpoint responds with `400`. When omitted, the application's static
`onboarding_redirect_url` is used.
security: []
parameters: []
/evse_onboarding/import:
post:
summary: Import an EVSE by serial number
tags:
- EVSEs
responses:
'201':
description: Returns the newly imported EVSE, linked to the authenticated user.
content:
application/json:
schema:
$ref: '#/components/schemas/EVSE'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestCreate'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
description: >-
The provider's system has no EVSE matching the supplied serial
number for the authenticated user's email.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/RFC9457ProblemDetail'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'422':
description: >-
The import could not be completed — either the EVSE is already
registered in our database, the integration provider returned an
error, or the provider is not supported for serial-number-based
import.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/RFC9457ProblemDetail'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: post-evse_onboarding-import
description: >-
Import an EVSE into the ev.energy system using its serial number and the
authenticated user's email. The backend calls the provider's API to look
up the device and link it; the response is the freshly created `EVSE`
resource, shape-identical to `GET /evses/{evse_id}`.
Supported providers (serial-number-based onboarding): `ChargePoint`,
`EO`, `SyncEV`, `EnelX`, `Easee`, `Wallbox`, `Zaptec`. Other EVSE
providers use the OAuth flow via `GET /evse_onboarding/` instead.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EVSEImportRequest'
parameters:
- $ref: '#/components/parameters/expand-on-evse'
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- evse:write
/evse_waitlist:
post:
summary: Add user to the EVSE waitlist
description: >-
Captures a user who hit an `incompatible` result on the EVSE
compatibility check, so we can notify them once their hardware becomes
supported. Pre-account, anonymous endpoint — no OAuth token required.
The request body must identify the device in exactly one of two modes:
- **Picker mode** — supply `evse_model_id` (uid of an `EVSEModel`).
`evse_make_name` and `evse_model_name` must be omitted / null.
- **Manual entry** — supply both `evse_make_name` and `evse_model_name`
as free-text strings. `evse_model_id` must be omitted / null.
Any other combination — including all three null — returns `400`.
Country is derived server-side: from `program.country` when `program_id`
is supplied; otherwise from the `Accept-Language` header (defaulting to
`US`).
Error responses follow RFC 9457 Problem Details. Problem types emitted
by this endpoint:
- `validation-failed-evse-waitlist` — request body fails validation
(missing required field, mode constraint violation, unknown
`evse_model_id` / `program_id`).
tags:
- EVSEs
operationId: post-evse_waitlist
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/Accept-Language'
- name: client_id
in: query
required: false
description: >-
OAuth `Application.client_id`. Mirrors the pre-account onboarding
and compatibility-check endpoints: when supplied and the application
has sandbox mode enabled, the endpoint returns a canned `201`
without persisting anything.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EVSEWaitlistRequest'
responses:
'201':
description: Waitlist entry created. Body echoes the new entry's uid.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/EVSEWaitlistResponse'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'405':
$ref: '#/components/responses/Problem405MethodNotAllowed'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
security: []
/vehicles:
get:
summary: List vehicles
tags:
- Vehicles
responses:
'200':
description: Return a list of vehicles.
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Vehicle'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-vehicles
parameters:
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/expand-on-vehicle'
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/user'
description: List all the vehicles that the authorization token has access to.
security:
- oauth2:
- vehicle:read
post:
summary: Create unintegrated vehicle
tags:
- Vehicles
responses:
'201':
description: Returns the newly created vehicle resource.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/Vehicle'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: post-vehicles
description: >-
If a vehicle cannot be integrated with our system, an "unintegrated"
vehicle must be created instead to represent it and record important
details like battery size.
To add a vehicle that can be integrated, see the [Onboarding
documentation](docs/howto/onboarding_custom.md).
security:
- oauth2:
- vehicle:write
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/expand'
- $ref: '#/components/parameters/evenergy-user-required'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/VehicleWrite'
/vehicles/{vehicle_id}:
parameters:
- $ref: '#/components/parameters/vehicle_id'
get:
summary: Retrieve a vehicle
tags:
- Vehicles
responses:
'200':
description: Return a single vehicle.
content:
application/json:
schema:
$ref: '#/components/schemas/Vehicle'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-vehicles-vehicle_id
parameters:
- $ref: '#/components/parameters/expand-on-vehicle'
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/user'
description: Retrieve a single, specific vehicle's details.
security:
- oauth2:
- vehicle:read
patch:
summary: Update a vehicle
tags:
- Vehicles
responses:
'200':
description: Vehicle updated successfully.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: object
$ref: '#/components/schemas/Vehicle'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: patch-vehicles
parameters:
- $ref: '#/components/parameters/expand-on-vehicle'
- $ref: '#/components/parameters/version-2'
description: Update a vehicle.
security:
- oauth2:
- vehicle:write
requestBody:
description: Details of Vehicle to be updated.
content:
application/json:
schema:
type: object
properties:
battery_size_watt_hours:
type: integer
minimum: 1000
maximum: 300000
description: >-
Battery size in watt-hours. Editable only for unintegrated
vehicles; sending it for an integrated vehicle is rejected.
Setting it flags the battery size as user-provided. Stored
to the nearest 0.01 kWh (10 Wh), so the value read back may
be rounded.
maximum_charge_limit_percentage:
type: integer
minimum: 50
maximum: 100
description: >-
The required target state of charge of the car as a
percentage between 50 and 100. The car will not be smart
charged above this value.
smart_charging_enabled:
type: boolean
description: >-
Whether smart (dynamic) charging is enabled for this
vehicle.
vehicle_class:
type:
- string
- 'null'
enum:
- PASSENGER
- COMMERCIAL
- null
description: Class of vehicle, passenger or commercial.
delete:
summary: Remove a vehicle
tags:
- Vehicles
responses:
'200':
description: The vehicle has been deleted.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: object
additionalProperties:
type: integer
examples:
Example:
value:
remaining_car_count: 0
'204':
description: Sandbox vehicles are not deleted.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'405':
$ref: '#/components/responses/Problem405MethodNotAllowed'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: delete-vehicles
description: Remove a vehicle by disconnecting it from the ev.energy system.
security:
- oauth2:
- vehicle:write
parameters:
- $ref: '#/components/parameters/version-2'
/vehicle_trims:
get:
summary: List vehicle trims
tags:
- Vehicles
responses:
'200':
description: Return a list of vehicle trims.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/VehicleTrim'
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-vehicle_trims
parameters:
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/expand-on-vehicletrim'
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/user'
- $ref: '#/components/parameters/vehicle_model_id_q'
- $ref: '#/components/parameters/ordering_by_name'
description: >-
List all the vehicle trims known by the ev.energy system.
Trim refers to a set of features that can be applied to a particular
model of vehicle: https://en.wikipedia.org/wiki/Car_model#Trim_level.
Pass `?ordering=name` (or `-name`) to sort results alphabetically by
name. Without an `ordering` parameter, results are returned in their
default creation order.
security:
- oauth2:
- vehicle:read
post:
summary: Create a custom vehicle trim
tags:
- Vehicles
responses:
'201':
description: Returns the newly created vehicle trim resource.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/VehicleTrim'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: post-vehicle_trims
description: |-
Creates a new trim for the specified model that can be used if
we are missing a trim. These trims will not be available in the
list trims api call
security:
- oauth2:
- vehicle:write
parameters:
- $ref: '#/components/parameters/version-2'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/VehicleTrimCreate'
parameters: []
/vehicle_trims/{vehicle_trim_id}:
get:
summary: Retrieve a vehicle trim
tags:
- Vehicles
responses:
'200':
description: Return a single vehicle trim.
content:
application/json:
schema:
$ref: '#/components/schemas/VehicleTrim'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-vehicle_trims-vehicle_trim_id
parameters:
- $ref: '#/components/parameters/expand-on-vehicletrim'
- $ref: '#/components/parameters/version-2'
description: >-
Retrieve details for a single, specific vehicle trim.
Trim refers to a set of features that can be applied to a particular
model of vehicle: https://en.wikipedia.org/wiki/Car_model#Trim_level.
security:
- oauth2:
- vehicle:read
parameters:
- $ref: '#/components/parameters/vehicle_trim_id'
/vehicle_models:
get:
summary: List vehicle models
tags:
- Vehicles
responses:
'200':
description: Return a list of vehicle models.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/VehicleModel'
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-vehicle_models
parameters:
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/expand-on-vehiclemodel'
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/user'
- $ref: '#/components/parameters/vehicle_make_id_q'
- $ref: '#/components/parameters/available_for_user_id'
- $ref: '#/components/parameters/ordering_by_name'
description: >-
List all the vehicle models known by the ev.energy system.
Use the `available_for_user_id` query parameter to narrow the list to
only those supported for a specific user's program and tier.
Pass `?ordering=name` (or `-name`) to sort results alphabetically by
name. Without an `ordering` parameter, results are returned in their
default creation order.
Anonymous callers are rate limited to 50 requests per hour per IP.
security: []
post:
summary: Create vehicle model
tags:
- Vehicles
responses:
'201':
description: Returns the newly created vehicle model resource.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/VehicleModel'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: post-vehicle_models
description: >-
Create a new vehicle model in the ev.energy system.
Newly created models are hidden by default and must be reviewed before
becoming visible.
security:
- oauth2:
- vehicle:write
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/user'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/VehicleModelWrite'
parameters: []
/vehicle_models/{vehicle_model_id}/connectors:
parameters:
- $ref: '#/components/parameters/vehicle_model_id'
get:
summary: List a vehicle model's regional connectors
description: |
List a vehicle model's DC-fast connectors, one per charging region. A
model's connector can differ by market (e.g. NACS in North America, CCS
in Europe), so each row records the connector for one region. Public
catalogue data.
tags:
- Vehicles
operationId: get-vehicle_models-vehicle_model_id-connectors
responses:
'200':
description: Returns the vehicle model's regional connectors.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/VehicleModelConnector'
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'404':
$ref: '#/components/responses/Problem404NotFound'
'405':
$ref: '#/components/responses/Problem405MethodNotAllowed'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/page_size'
security: []
post:
summary: Add a regional connector to a vehicle model
description: |
Create a connector row for one region of a vehicle model.
`(vehicle_model, region)` is unique; adding a second row for the same
region returns a `400`. Requires the `vehicle_catalogue:write` scope.
tags:
- Vehicles
operationId: post-vehicle_models-vehicle_model_id-connectors
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/VehicleModelConnectorCreate'
responses:
'201':
description: The regional connector was created.
content:
application/json:
schema:
$ref: '#/components/schemas/VehicleModelConnector'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
'400':
$ref: >-
#/components/responses/Problem400VehicleModelConnectorValidationFailed
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'405':
$ref: '#/components/responses/Problem405MethodNotAllowed'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
parameters:
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- vehicle_catalogue:write
/vehicle_models/{vehicle_model_id}/connectors/{region}:
parameters:
- $ref: '#/components/parameters/vehicle_model_id'
- $ref: '#/components/parameters/region'
get:
summary: Retrieve a vehicle model's connector for a region
tags:
- Vehicles
operationId: get-vehicle_models-vehicle_model_id-connectors-region
responses:
'200':
description: Returns the vehicle model's connector for the region.
content:
application/json:
schema:
$ref: '#/components/schemas/VehicleModelConnector'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'404':
$ref: '#/components/responses/Problem404NotFound'
'405':
$ref: '#/components/responses/Problem405MethodNotAllowed'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
parameters:
- $ref: '#/components/parameters/version-2'
security: []
patch:
summary: Update a vehicle model's connector for a region
description: |
Partially update the connector row for one region. Only the fields
supplied are changed; `region` is the key and cannot be changed.
Requires the `vehicle_catalogue:write` scope.
tags:
- Vehicles
operationId: patch-vehicle_models-vehicle_model_id-connectors-region
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/VehicleModelConnectorPatch'
responses:
'200':
description: The regional connector was updated.
content:
application/json:
schema:
$ref: '#/components/schemas/VehicleModelConnector'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
'400':
$ref: >-
#/components/responses/Problem400VehicleModelConnectorValidationFailed
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'405':
$ref: '#/components/responses/Problem405MethodNotAllowed'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
parameters:
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- vehicle_catalogue:write
/vehicle_models/{vehicle_model_id}:
get:
summary: Retrieve a vehicle model
tags:
- Vehicles
responses:
'200':
description: Return a list of vehicle models.
content:
application/json:
schema:
$ref: '#/components/schemas/VehicleModel'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-vehicle_models-vehicle_model_id
parameters:
- $ref: '#/components/parameters/expand-on-vehiclemodel'
- $ref: '#/components/parameters/version-2'
description: |-
Retrieve details for a single, specific vehicle model.
Anonymous callers are rate limited to 50 requests per hour per IP.
security: []
patch:
summary: Update a vehicle model
description: >-
Update editable catalogue fields on a vehicle model. Currently only
`default_connector_type` is editable. Intended for staff/agent
maintenance of the shared catalogue and requires the
`vehicle_catalogue:write` scope — ordinary user/app tokens cannot use
it.
tags:
- Vehicles
operationId: patch-vehicle_models-vehicle_model_id
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/VehicleModelUpdate'
responses:
'200':
description: The vehicle model was updated.
content:
application/json:
schema:
$ref: '#/components/schemas/VehicleModel'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'405':
$ref: '#/components/responses/Problem405MethodNotAllowed'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
parameters:
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- vehicle_catalogue:write
parameters:
- $ref: '#/components/parameters/vehicle_model_id'
/vehicle_makes:
get:
summary: List vehicle makes
tags:
- Vehicles
responses:
'200':
description: Return a list of vehicle makes.
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/VehicleMake'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-vehicle_makes
parameters:
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/user'
- $ref: '#/components/parameters/available_for_user_id'
- $ref: '#/components/parameters/ordering_by_name'
description: >-
List all the vehicle makes known by the ev.energy system.
Use the `available_for_user_id` query parameter to narrow the list to
only those supported for a specific user's program and tier.
Pass `?ordering=name` (or `-name`) to sort results alphabetically by
name. Without an `ordering` parameter, results are returned in their
default creation order.
Anonymous callers are rate limited to 50 requests per hour per IP.
security: []
/vehicle_makes/{vehicle_make_id}:
parameters:
- $ref: '#/components/parameters/vehicle_make_id'
get:
summary: Retrieve a vehicle make
description: |-
Retrieve details for a single, specific vehicle make.
Anonymous callers are rate limited to 50 requests per hour per IP.
tags:
- Vehicles
responses:
'200':
description: Return a single vehicle make.
content:
application/json:
schema:
$ref: '#/components/schemas/VehicleMake'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-vehicle_makes-vehicle_make_id
parameters:
- $ref: '#/components/parameters/version-2'
security: []
/vehicles/{vehicle_id}/status_logs:
parameters:
- $ref: '#/components/parameters/vehicle_id'
get:
summary: List status logs for a vehicle
description: >-
List the historical status logs for a specific Vehicle. Used to find out
the state of the Vehicle at each point it reported in to ev.energy.
tags:
- Vehicles
responses:
'200':
description: >-
List all the status logs for a specific Vehicle, sorted newest
first.
headers:
Link:
$ref: '#/components/headers/link-timestamps'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/VehicleStatusLog'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-vehicles-vehicle_id-status_logs
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/sampled_at__gte'
- $ref: '#/components/parameters/sampled_at__lte'
- $ref: '#/components/parameters/expand-on-vehiclestatuslog'
security:
- oauth2:
- vehicle:read
/vehicles/{vehicle_id}/status_logs/{sampled_at}:
parameters:
- $ref: '#/components/parameters/vehicle_id'
- schema:
type: string
format: date-time
name: sampled_at
in: path
required: true
description: The time the log's data was recorded on the device.
example: '2024-04-17T09:39:45.984584Z'
get:
summary: Retrieve a specific status log for a vehicle
description: >-
A single status log for a particular vehicle is uniquely identified by
the timestamp it was logged at.
tags:
- Vehicles
responses:
'200':
description: Returns the Vehicle status logged at a specific time.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/VehicleStatusLog'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-vehicles-vehicle_id-status_logs-timestamp
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/expand-on-vehiclestatuslog'
security:
- oauth2:
- vehicle:read
/vehicles/{vehicle_id}/error_logs:
parameters:
- $ref: '#/components/parameters/vehicle_id'
get:
summary: List API error logs for a vehicle
description: >-
List the historical API error logs for a specific Vehicle. These logs
capture errors that occurred when attempting to communicate with the
vehicle's telematics API.
tags:
- Vehicles
responses:
'200':
description: >-
List all the API error logs for a specific Vehicle, sorted newest
first.
headers:
Link:
$ref: '#/components/headers/link-timestamps'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/VehicleAPIErrorLog'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-vehicles-vehicle_id-error_logs
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/logged_at__gte'
- $ref: '#/components/parameters/logged_at__lte'
- $ref: '#/components/parameters/expand-on-vehicleapierrorlog'
security:
- oauth2:
- vehicle:read
/vehicles/{vehicle_id}/error_logs/{logged_at}:
parameters:
- $ref: '#/components/parameters/vehicle_id'
- schema:
type: string
format: date-time
name: logged_at
in: path
required: true
description: The time the error was logged.
example: '2024-04-17T09:39:45.984584Z'
get:
summary: Retrieve a specific API error log for a vehicle
description: >-
A single API error log for a particular vehicle is uniquely identified
by the timestamp it was logged at.
tags:
- Vehicles
responses:
'200':
description: Returns the Vehicle API error logged at a specific time.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/VehicleAPIErrorLog'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-vehicles-vehicle_id-error_logs-timestamp
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/expand-on-vehicleapierrorlog'
security:
- oauth2:
- vehicle:read
/vehicles/{vehicle_id}/location_logs:
parameters:
- $ref: '#/components/parameters/vehicle_id'
get:
summary: List location logs for a vehicle
description: >-
List the historical location log timestamps for a specific Vehicle.
Returns metadata about when location data was recorded, without exposing
the actual location coordinates.
tags:
- Vehicles
responses:
'200':
description: >-
List all the location log timestamps for a specific Vehicle, sorted
newest first.
headers:
Link:
$ref: '#/components/headers/link-timestamps'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/VehicleLocationLog'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-vehicles-vehicle_id-location_logs
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/sampled_at__gte'
- $ref: '#/components/parameters/sampled_at__lte'
- $ref: '#/components/parameters/expand-on-vehiclelocationlog'
security:
- oauth2:
- vehicle:read
/vehicles/{vehicle_id}/location_logs/{sampled_at}:
parameters:
- $ref: '#/components/parameters/vehicle_id'
- schema:
type: string
format: date-time
name: sampled_at
in: path
required: true
description: The time the location data was sampled from the vehicle.
example: '2024-04-17T09:39:45.984584Z'
get:
summary: Retrieve a specific location log for a vehicle
description: >-
A single location log for a particular vehicle is uniquely identified by
the timestamp it was sampled at. Returns metadata only, without exposing
the actual location coordinates.
tags:
- Vehicles
responses:
'200':
description: Returns the Vehicle location log metadata at a specific time.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/VehicleLocationLog'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-vehicles-vehicle_id-location_logs-timestamp
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/expand-on-vehiclelocationlog'
security:
- oauth2:
- vehicle:read
/vehicles/{vehicle_id}/command_logs:
parameters:
- $ref: '#/components/parameters/vehicle_id'
get:
summary: List command logs for a vehicle
description: >-
List the historical command logs for a specific Vehicle. These logs
record commands that were sent to the vehicle.
tags:
- Vehicles
responses:
'200':
description: >-
List all the command logs for a specific Vehicle, sorted newest
first.
headers:
Link:
$ref: '#/components/headers/link-timestamps'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/VehicleCommandLog'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-vehicles-vehicle_id-command_logs
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/logged_at__gte'
- $ref: '#/components/parameters/logged_at__lte'
- $ref: '#/components/parameters/expand-on-vehiclecommandlog'
security:
- oauth2:
- debug:read
/vehicles/{vehicle_id}/command_logs/{logged_at}:
parameters:
- $ref: '#/components/parameters/vehicle_id'
- schema:
type: string
format: date-time
name: logged_at
in: path
required: true
description: The time the command was logged.
example: '2024-04-17T09:39:45.984584Z'
get:
summary: Retrieve a specific command log for a vehicle
description: >-
A single command log for a particular vehicle is uniquely identified by
the timestamp it was logged at.
tags:
- Vehicles
responses:
'200':
description: Returns the Vehicle command logged at a specific time.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/VehicleCommandLog'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-vehicles-vehicle_id-command_logs-timestamp
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/expand-on-vehiclecommandlog'
security:
- oauth2:
- debug:read
/vehicles/{vehicle_id}/vpp_modes:
parameters:
- $ref: '#/components/parameters/vehicle_id'
get:
summary: Get VPP modes for a vehicle
description: >-
Returns the VPP (Virtual Power Plant) control modes supported by this
vehicle.
tags:
- Vehicles
- VPP
responses:
'200':
description: Returns the VPP modes supported by this vehicle.
content:
application/json:
schema:
$ref: '#/components/schemas/VPPModes'
examples:
Vehicle VPP Modes:
value:
target_power: true
import_max_power: false
export_max_power: false
charge_mode: true
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-vehicles-vehicle_id-vpp_modes
parameters:
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- vehicle:read
/vehicle_onboarding:
get:
summary: Initiate vehicle onboarding
tags:
- Vehicles
responses:
'200':
description: >-
Returned only when `response_type=json` is supplied. Carries the
integration provider's authorization URL plus the metadata native
clients need (auth method, OAuth scopes, single-select hint) so they
can either open the URL in a WebView or launch the provider's native
SDK.
content:
application/json:
schema:
$ref: '#/components/schemas/VehicleOnboardingJsonResponse'
'302':
description: >-
Have the user's browser follow the redirect to be prompted to
connect their vehicle to the ev.energy system.
If a make, model or trim were not provided, the user will first be
redirect to a screen to select these.
headers:
Location:
schema:
type: string
description: >-
The URL that the users browser will be redirected to in order to
integrate their Vehicle.
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'404':
$ref: '#/components/responses/Problem404NotFound'
'422':
description: >-
Returned only on the `response_type=json` path when the integration
provider could not produce an authorization URL — for example
because the vehicle make is not supported, the provider is currently
unavailable, or it returned an error code.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/RFC9457ProblemDetail'
operationId: get-vehicle_onboarding
description: >-
Initiate the onboarding process for a new vehicle in your user's browser
(or an embedded web view in an app).
If none of `make_id`, `model_id` or `trim_id` are passed as query
parameters, the user will be shown a user interface to pick their
vehicle make.
## Native clients (`response_type=json`)
Native mobile clients that need to launch a provider SDK (e.g. Smartcar
Connect for BMW/MINI) instead of opening a WebView can pass
`response_type=json` to receive a JSON payload instead of a 302
redirect. In that case at least one of `make_id`, `model_id` or
`trim_id` is required (otherwise the endpoint responds with `400`).
## Final redirect
After the user completes the web flow, the browser is redirected to the
`redirect_uri` query parameter (when supplied and valid) or otherwise
the `onboarding_redirect_url` configured on your application. The
redirect URL will carry one or more query parameters identifying the
onboarded vehicles:
- `vehicle_uid` — the v2 UID of each onboarded vehicle (preferred). Use
this to call `GET /v2/vehicles/{vehicle_uid}` for further details.
- `vehicle_id` — the legacy integer primary key of each onboarded
vehicle. Prefer `vehicle_uid`.
When multiple vehicles are onboarded in a single flow, both query
parameters appear once per vehicle in matching order. For example:
`https://your-redirect/?vehicle_id=1&vehicle_id=2&vehicle_uid=vhcl01...&vehicle_uid=vhcl02...`.
security: []
parameters:
- $ref: '#/components/parameters/user_id_onboarding'
- schema:
type: string
example: vmak01J443798BF893ZHFQVCS0FA23
in: query
name: make_id
description: Specify the make of vehicle to be onboarded.
- schema:
type: string
example: vhcl01HNARS42AVJN9QWQF6J52B7MB
in: query
name: model_id
description: Specify the model of vehicle to be onboarded.
- schema:
type: string
example: vhcl01HNARS42AVJN9QWQF6J52B7MB
in: query
name: trim_id
description: Specify the trim of vehicle to be onboarded.
- $ref: '#/components/parameters/client_id'
- schema:
type: string
enum:
- json
in: query
name: response_type
description: >-
When set to `json`, the endpoint returns a JSON payload (200)
instead of a 302 redirect. Used by native mobile clients to choose
between launching a provider SDK and opening a WebView. Requires at
least one of `make_id`, `model_id` or `trim_id`.
- schema:
type: string
format: uri
example: https://drivers.ev.energy/acme
in: query
name: redirect_uri
description: >-
Optional URL to return the user to after onboarding completes. Its
scheme and host must match one of the application's registered
`redirect_uris` or its `onboarding_redirect_url`, otherwise the
endpoint responds with `400`. When omitted, the application's static
`onboarding_redirect_url` is used.
/vehicle_onboarding/complete:
post:
summary: Complete vehicle onboarding
tags:
- Vehicles
responses:
'201':
description: >-
Authorization code exchanged successfully. Returns the list of
created vehicles. Always an array, even when only a single vehicle
was created.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/VehicleOnboardingCompleteResponse'
'400':
$ref: '#/components/responses/Problem400BadRequestCreate'
'404':
description: >-
No `AccountAuthorizationRequest` matches the supplied
`authorization_request_uid`.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/RFC9457ProblemDetail'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'422':
description: >-
Returned when the authorization request has expired, the integration
provider rejected the supplied `auth_code`, or no vehicles could be
retrieved from the provider.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/RFC9457ProblemDetail'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: post-vehicle_onboarding-complete
description: >-
Exchanges a provider `auth_code` for a list of vehicles, completing an
onboarding flow that was initiated via `GET
/v2/vehicle_onboarding/?response_type=json`. Used primarily by native
mobile clients integrating with the Smartcar Connect SDK (the SDK
returns the `auth_code` directly to the app).
No OAuth bearer token is required, mirroring the init endpoint. The
`authorization_request_uid` returned by the init call is what binds this
request to the legitimate onboarding flow — it is treated as a
single-use token.
security: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/VehicleOnboardingCompleteRequest'
/vehicle_onboarding/onboarding_link:
post:
summary: Send vehicle onboarding link
tags:
- Vehicles
operationId: post-vehicle_onboarding-onboarding_link
description: >-
Generates a vehicle onboarding deep link for the authenticated user and
sends a Braze event containing the email, make name and onboarding URL.
Requires an OAuth token with `vehicle:write` scope.
security:
- OAuth2:
- vehicle:write
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- email
- make
properties:
email:
type: string
format: email
description: Email address to send the onboarding link to.
example: user@example.com
make:
type: string
description: UID of the vehicle make to onboard.
responses:
'204':
description: Onboarding link sent successfully.
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
/vehicle_compatibility/check:
get:
summary: Check vehicle model compatibility in a country
description: |-
Returns whether the given vehicle model is supported in the supplied
country. Used by the onboarding flow to tell the user upfront
whether their vehicle will work before any account-linking step.
Public endpoint — callable pre-account, no authentication required.
Country resolution follows this order: explicit `country` query
parameter, then the `Accept-Language` header, then `US`.
When `program_id` is supplied, the check is scoped to that program's
effective supported-models list (inclusion/exclusion lists applied)
and the program's country — the `country` query parameter and
`Accept-Language` header are ignored.
Error responses follow RFC 9457 Problem Details. Problem types
emitted by this endpoint:
- `validation-failed-vehicle-compatibility-check` — missing or
invalid `vehicle_model_id` / `country` query parameter (`400`).
- `vehicle-model-not-found` — `vehicle_model_id` does not resolve
to a vehicle model (`404`).
- `program-not-found-vehicle-compatibility` — `program_id` does
not resolve to a program (`404`).
tags:
- Vehicles
operationId: get-vehicle_compatibility-check
parameters:
- $ref: '#/components/parameters/version-2'
- name: vehicle_model_id
in: query
required: true
description: Vehicle Model id to check compatibility for.
schema:
type: string
pattern: vmod[A-Z\d]{26}
- name: country
in: query
required: false
description: ISO-3166 alpha-2 country code. See description for fallback chain.
schema:
type: string
pattern: ^[A-Za-z]{2}$
minLength: 2
maxLength: 2
- $ref: '#/components/parameters/Accept-Language'
- name: client_id
in: query
required: false
description: |-
OAuth `Application.client_id`. Mirrors the pre-account
onboarding endpoints: when supplied and the application has
sandbox mode enabled, the endpoint returns a canned response
without touching the database.
schema:
type: string
- name: program_id
in: query
required: false
description: |-
Program uid. When supplied, the check is scoped to the
program's effective supported-models list (inclusion / exclusion
lists applied) and the program's country. `country` and
`Accept-Language` are ignored in that case. Omit for the core
app's pre-account flow where the program is not yet known.
schema:
type: string
pattern: prog[A-Z\d]{26}
responses:
'200':
description: Compatibility verdict for the supplied model and country.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/VehicleCompatibilityCheckResult'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'404':
$ref: '#/components/responses/Problem404NotFound'
'405':
$ref: '#/components/responses/Problem405MethodNotAllowed'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
security: []
/vehicle_waitlist:
post:
summary: Add user to the vehicle waitlist
description: >-
Captures a user who hit an `incompatible` result on the vehicle
compatibility check, so we can notify them once their hardware becomes
supported. Pre-account, anonymous endpoint — no OAuth token required.
The request body must identify the device in exactly one of two modes:
- **Picker mode** — supply `vehicle_model_id` (uid of a `CarModel`).
`vehicle_make_name` and `vehicle_model_name` must be omitted / null.
- **Manual entry** — supply both `vehicle_make_name` and
`vehicle_model_name` as free-text strings. `vehicle_model_id` must be
omitted / null.
Any other combination — including all three null — returns `400`.
Country is derived server-side: from `program.country` when `program_id`
is supplied; otherwise from the `Accept-Language` header (defaulting to
`US`).
Error responses follow RFC 9457 Problem Details. Problem types emitted
by this endpoint:
- `validation-failed-vehicle-waitlist` — request body fails validation
(missing required field, mode constraint violation, unknown
`vehicle_model_id` / `program_id`).
tags:
- Vehicles
operationId: post-vehicle_waitlist
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/Accept-Language'
- name: client_id
in: query
required: false
description: >-
OAuth `Application.client_id`. Mirrors the pre-account onboarding
and compatibility-check endpoints: when supplied and the application
has sandbox mode enabled, the endpoint returns a canned `201`
without persisting anything.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/VehicleWaitlistRequest'
responses:
'201':
description: Waitlist entry created. Body echoes the new entry's uid.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/VehicleWaitlistResponse'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'405':
$ref: '#/components/responses/Problem405MethodNotAllowed'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
security: []
/programs/{program_id}/vehicle_compatibility:
parameters:
- $ref: '#/components/parameters/program_id'
get:
summary: List vehicle compatibility for a program
description: >-
List vehicle compatibility records for a specific program.
Returns all active vehicle models that are supported by the given
program.
tags:
- Programs
responses:
'200':
description: Return a list of vehicle compatibility records for the program.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ProgramVehicleCompatibility'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-programs-program_id-vehicle_compatibility
parameters:
- $ref: '#/components/parameters/expand-on-programvehiclecompatibility'
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/user'
security:
- oauth2:
- vehicle:read
/suppliers:
get:
summary: List suppliers, sorted alphabetically by name.
tags:
- Tariffs
responses:
'200':
description: Return a list of Suppliers.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Supplier'
headers:
Link:
$ref: '#/components/headers/link-pages'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-suppliers
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/available_for_user_id'
- $ref: '#/components/parameters/version-2'
description: >-
List all the energy suppliers known by the ev.energy system.
Use the `available_for_user_id` query parameter to narrow the list to
only those relevant to a specific user.
security:
- oauth2:
- tariff:read
/suppliers/{supplier_id}:
parameters:
- $ref: '#/components/parameters/supplier_id'
get:
summary: Retrieve a supplier
tags:
- Tariffs
responses:
'200':
description: Return a single supplier.
content:
application/json:
schema:
$ref: '#/components/schemas/Supplier'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-suppliers-suppler_id
parameters:
- $ref: '#/components/parameters/version-2'
description: Retrieve details for a single, specific energy supplier.
security:
- oauth2:
- tariff:read
/tariffs:
get:
summary: List tariffs, sorted alphabetically by name.
tags:
- Tariffs
responses:
'200':
description: Return a list of Tariffs.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Tariff'
headers:
Link:
$ref: '#/components/headers/link-pages'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-tariffs
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/expand-on-tariff'
- $ref: '#/components/parameters/supplier_id_query'
- $ref: '#/components/parameters/tariff_valid_query'
- $ref: '#/components/parameters/tariff_gsp_group_query'
- $ref: '#/components/parameters/available_for_user_id'
- $ref: '#/components/parameters/include_optional_tariff'
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/user'
description: >-
List all the energy supplier tariffs known by the ev.energy system.
Use the `available_for_user_id` query parameter to narrow the list to
only those relevant to a specific user and `supplier` query parameter to
list only tariffs for a specific supplier.
security:
- oauth2:
- tariff:read
/tariffs/{tariff_id}:
parameters:
- $ref: '#/components/parameters/tariff_id'
get:
summary: Retrieve a tariff
tags:
- Tariffs
responses:
'200':
description: Return a single Tariff.
content:
application/json:
schema:
$ref: '#/components/schemas/TariffDetail'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-tariffs-tariff_id
parameters:
- $ref: '#/components/parameters/expand-on-tariff'
- $ref: '#/components/parameters/available_for_user_id'
- $ref: '#/components/parameters/version-2'
description: Retrieve details for a single, specific tariff.
security:
- oauth2:
- tariff:read
/tariffs/{tariff_id}/prices:
parameters:
- $ref: '#/components/parameters/tariff_id'
get:
summary: List prices for a tariff
tags:
- Tariffs
responses:
'200':
description: Returns a paginated list of prices for the specified tariff.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Price'
headers:
Link:
$ref: '#/components/headers/link-pages'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-tariff-prices
parameters:
- name: started_at__gte
in: query
required: false
schema:
type: string
format: date-time
example: '2024-01-15T10:00:00Z'
description: Filter for prices starting at or after this datetime (ISO 8601).
- name: started_at__lte
in: query
required: false
schema:
type: string
format: date-time
example: '2024-01-15T10:00:00Z'
description: Filter for prices starting at or before this datetime (ISO 8601).
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/version-2'
description: >-
Returns all prices for the specified tariff. Results are ordered by
start time (most recent first).
Use `started_at__gte` and `started_at__lte` to filter by time range.
security:
- oauth2:
- tariff:read
- tariff:prices:read
/carbon_feeds:
get:
summary: List carbon feeds
description: >-
List all carbon feeds visible to the authenticated client. Carbon feeds
represent sources of carbon intensity data for specific regions or
grids.
tags:
- Carbon
responses:
'200':
description: Returns a list of carbon feeds, sorted by name.
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CarbonFeed'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-carbon_feeds
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
security:
- oauth2:
- carbon:read
/carbon_feeds/{carbon_feed_id}:
parameters:
- $ref: '#/components/parameters/carbon_feed_id'
get:
summary: Retrieve a carbon feed
description: >-
Retrieve a specific carbon feed, representing a source of carbon
intensity data for a region or grid.
tags:
- Carbon
responses:
'200':
description: Returns information about a single carbon feed.
content:
application/json:
schema:
$ref: '#/components/schemas/CarbonFeed'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-carbon_feeds-carbon_feed_id
parameters:
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- carbon:read
/carbon_feeds/{carbon_feed_id}/carbon_intensities:
parameters:
- $ref: '#/components/parameters/carbon_feed_id'
get:
summary: List carbon intensity data
description: >-
Returns a paginated list of carbon intensity data points for a specific
carbon feed. Carbon intensity represents the amount of CO2 emissions per
unit of electricity generated, measured in grams of CO2 per
kilowatt-hour (gCO2/kWh).
Use `started_at__gte` and `started_at__lte` to filter by time range.
tags:
- Carbon
responses:
'200':
description: >-
Returns a list of carbon intensity data points, sorted by started_at
descending.
content:
application/json:
schema:
$ref: '#/components/schemas/CarbonIntensities'
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-carbon_feeds-carbon_feed_id-carbon_intensities
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/expand-on-carbonintensity'
- name: started_at__gte
in: query
required: false
schema:
type: string
format: date-time
example: '2024-01-15T10:00:00Z'
description: Filter for entries on or after this datetime (ISO 8601).
- name: started_at__lte
in: query
required: false
schema:
type: string
format: date-time
example: '2024-01-15T12:00:00Z'
description: Filter for entries on or before this datetime (ISO 8601).
security:
- oauth2:
- carbon:read
/grid_feeds:
get:
summary: List grid feeds
description: >-
List all grid feeds visible to the authenticated client. Grid feeds
represent sources of grid signal data used for smart charging decisions.
tags:
- Grid
responses:
'200':
description: Returns a list of grid feeds, sorted by name.
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/GridFeed'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-grid_feeds
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
security:
- oauth2:
- grid:read
/grid_feeds/{grid_feed_id}:
parameters:
- $ref: '#/components/parameters/grid_feed_id'
get:
summary: Retrieve a grid feed
description: Retrieve a specific grid feed used for smart charging decisions.
tags:
- Grid
responses:
'200':
description: Returns information about a single grid feed.
content:
application/json:
schema:
$ref: '#/components/schemas/GridFeed'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-grid_feeds-grid_feed_id
parameters:
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- grid:read
/grid_feeds/{grid_feed_id}/levels:
parameters:
- $ref: '#/components/parameters/grid_feed_id'
get:
summary: List levels for a grid feed
description: >-
Returns all levels for the specified grid feed. Levels represent the
time-varying signal values that influence smart charging decisions. Each
level applies to a specific time interval and has a value between 1 and
100, where values above 50 discourage charging and values below 50
encourage it.
Use `started_at__gte` and `started_at__lte` to filter by time range.
tags:
- Grid
responses:
'200':
description: >-
Returns a paginated list of grid levels for the specified grid feed,
sorted by start time (most recent first).
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/GridLevel'
headers:
Link:
$ref: '#/components/headers/link-pages'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-grid_feeds-grid_feed_id-levels
parameters:
- name: started_at__gte
in: query
required: false
schema:
type: string
format: date-time
example: '2024-01-15T10:00:00Z'
description: Filter for levels starting at or after this datetime (ISO 8601).
- name: started_at__lte
in: query
required: false
schema:
type: string
format: date-time
example: '2024-01-15T12:00:00Z'
description: Filter for levels starting at or before this datetime (ISO 8601).
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- grid:read
/charging_sessions:
get:
summary: List charging sessions
description: >-
List all charging sessions visible to the authenticated client. Each
session represents one physical plug-in episode: its start/end are the
plug-in and unplug times. A session contains one or more charging
sub-sessions — one per contiguous period in a single charging mode.
Charging sessions are recorded from the feature's release (July 2026)
onwards; earlier charging history is not backfilled and is available
only as charging sub-sessions.
See [Understanding charging
data](docs/understanding/charging_sessions.md) for how charging
sessions, sub-sessions and energy usage intervals relate.
tags:
- Charging Sessions
responses:
'200':
description: Returns a list of charging sessions, sorted newest first.
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ChargingSession'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-charging_sessions
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/expand-on-chargingsession'
- $ref: '#/components/parameters/user'
security:
- oauth2:
- charging_session:read
/charging_sessions/{charging_session_id}:
parameters:
- $ref: '#/components/parameters/charging_session_id'
get:
summary: Retrieve a charging session
description: >-
Retrieve a specific charging session representing one physical plug-in
episode: its start/end are the plug-in and unplug times. See
[Understanding charging data](docs/understanding/charging_sessions.md).
tags:
- Charging Sessions
responses:
'200':
description: Returns a single charging session.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/ChargingSession'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-charging_sessions-charging_session_id
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/expand-on-chargingsession'
- $ref: '#/components/parameters/user'
security:
- oauth2:
- charging_session:read
/charging_sessions/{charging_session_id}/boost_start:
parameters:
- $ref: '#/components/parameters/charging_session_id'
post:
summary: Start boost charging
tags:
- Charging Sessions
responses:
'200':
description: Boost charging was started. Returns the charging session resource.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/ChargingSession'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'409':
$ref: '#/components/responses/Problem409Conflict'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
'503':
$ref: '#/components/responses/Problem503ServiceUnavailable'
operationId: post-charging_sessions-charging_session_id-boost_start
description: |-
Start boost charging on this charging session's vehicle. Finishes the
in-progress smart charging sub-session and starts a replacement boost
sub-session, charging the vehicle continuously rather than around the
cheapest/greenest times. The plug-in episode (this resource) continues
unchanged.
Returns `409 Conflict` if smart charging is turned off for the
vehicle, or if this session's current sub-session is not an
in-progress smart charging session that can be boosted.
security:
- oauth2:
- charging_session:write
/charging_sessions/{charging_session_id}/boost_end:
parameters:
- $ref: '#/components/parameters/charging_session_id'
post:
summary: End boost charging
tags:
- Charging Sessions
responses:
'200':
description: Boost charging was ended. Returns the charging session resource.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/ChargingSession'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'409':
$ref: '#/components/responses/Problem409Conflict'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
'503':
$ref: '#/components/responses/Problem503ServiceUnavailable'
operationId: post-charging_sessions-charging_session_id-boost_end
description: |-
End boost charging on this charging session's vehicle. Finishes the
in-progress boost sub-session and starts a replacement smart charging
sub-session, returning the vehicle to charging around the
cheapest/greenest times. The plug-in episode (this resource) continues
unchanged.
Returns `409 Conflict` if smart charging is turned off for the
vehicle, or if this session's current sub-session is not currently
boosting.
security:
- oauth2:
- charging_session:write
/charging_sub_sessions:
get:
summary: List charging sub sessions
description: >-
List all charging sub sessions visible to the authenticated client.
A charging sub-session is a segment of a plug-in episode during which a
single charging mode (SMART, BOOST, etc.) was active. Its start/end mark
when that mode started and stopped being active — they are not
plug-in/plug-out times (see the charging_sessions resource for those),
and they are not the times energy was actually flowing (see the
sub-session's energy_usage endpoint for those).
See [Understanding charging
data](docs/understanding/charging_sessions.md) for how charging
sessions, sub-sessions and energy usage intervals relate.
tags:
- Charging Sessions
responses:
'200':
description: Returns a list of charging sub sessions, sorted newest first.
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ChargingSubSession'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-charging_sub_sessions
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/expand-on-chargingsubsession'
- $ref: '#/components/parameters/evse_id_q'
- $ref: '#/components/parameters/vehicle_id_q'
- $ref: '#/components/parameters/user_id_q'
- $ref: '#/components/parameters/user'
- $ref: '#/components/parameters/energy_delivered_watt_hours__gte'
- $ref: '#/components/parameters/energy_delivered_watt_hours__lte'
- $ref: '#/components/parameters/is_finished'
- $ref: '#/components/parameters/mode'
- schema:
type: string
format: date-time
in: query
name: start__gt
description: Only return sessions that started after the passed date
- schema:
type: string
format: date-time
in: query
name: start__lt
description: Only return sessions that started before the passed date
- schema:
type: string
format: date-time
in: query
name: end__gt
description: Only return sessions that ended after the passed date
- schema:
type: string
format: date-time
in: query
name: end__lt
description: Only return sessions that ended before the passed date
security:
- oauth2:
- charging_session:read
/charging_sub_sessions/{charging_sub_session_id}:
parameters:
- $ref: '#/components/parameters/charging_sub_session_id'
get:
summary: Retrieve a charging sub-session
description: >-
Retrieve a specific charging sub-session, representing a period of a
plug-in episode during which a single charging mode was active. Its
start/end mark when the mode started and stopped being active — not
plug-in/plug-out times, and not when energy was actually flowing. See
[Understanding charging data](docs/understanding/charging_sessions.md).
tags:
- Charging Sessions
responses:
'200':
description: Returns information about a single charging sub-session.
content:
application/json:
schema:
$ref: '#/components/schemas/ChargingSubSession'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-charging_sub_sessions-charging_sub_session_id
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/expand-on-chargingsubsession'
security:
- oauth2:
- charging_session:read
/charging_sub_sessions/{charging_sub_session_id}/energy_usage:
parameters:
- $ref: '#/components/parameters/charging_sub_session_id'
get:
summary: Retrieve periodic energy usage intervals for a charging sub-session
description: >-
Retrieve periodic energy usage intervals for a specific charging
sub-session. This is the endpoint to use to find out when energy was
actually delivered to the vehicle.
A sub-session's start/end only mark when its charging mode was active —
within that window, energy delivery may begin late (e.g. smart charging
waiting for an off-peak period), finish early (e.g. the target charge
level was reached), or occur in several separate bursts. The intervals
returned here report the actual delivery.
By default, intervals are regular fixed-length periods. If you are
looking for intervals that cover the whole time energy is being
delivered (which are therefore of irregular length) — for example to
find the actual charging windows — use the `merge_consecutive_intervals`
query parameter. Gaps where no energy flowed are returned as intervals
with zero energy delivered; filter them out with
`energy_delivered_watt_hours__gt=0` if you only want the charging
windows.
See [Understanding charging
data](docs/understanding/charging_sessions.md) for how charging
sessions, sub-sessions and energy usage intervals relate.
tags:
- Charging Sessions
responses:
'200':
description: >-
Returns information about a single charging sub-session's energy
usage.
content:
application/json:
schema:
$ref: '#/components/schemas/EnergyUsage'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-charging_sub_sessions-charging_sub_session_id-energy_usage
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/expand-on-chargingsubsession-energyusage'
- $ref: '#/components/parameters/energy_delivered_watt_hours__gt'
- schema:
type: boolean
in: query
name: merge_consecutive_intervals
description: >-
Request consecutive intervals of energy delivery (and intervals of
no delivery) to be merged into combined periods of irregular
length.
security:
- oauth2:
- charging_session:read
/charging_sub_sessions/{charging_sub_session_id}/flags:
parameters:
- $ref: '#/components/parameters/charging_sub_session_id'
get:
summary: Retrieve flags for a charging sub-session
description: >-
Retrieve flags associated with a specific charging sub-session.
Flags highlight particular types of issues or anomalies detected during
a charging session, along with their root causes.
tags:
- Charging Sessions
responses:
'200':
description: Returns the flags associated with this charging sub-session.
content:
application/json:
schema:
$ref: '#/components/schemas/ChargingSubSessionFlags'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-charging_sub_sessions-charging_sub_session_id-flags
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/expand-on-chargingsubsession-flags'
security:
- oauth2:
- charging_session:read
/charging_sub_sessions/{charging_sub_session_id}/debug_metadata:
parameters:
- $ref: '#/components/parameters/charging_sub_session_id'
get:
summary: Retrieve debug metadata for a charging sub-session
description: >-
Retrieve debug metadata for a specific charging sub-session.
Debug metadata exposes session-level diagnostic information such as
start/finish reasons, the energy usage calculation and interpolation
methods used, whether energy delivery was capped, and the solar
integration type of the paired EVSE.
tags:
- Charging Sessions
responses:
'200':
description: >-
Returns the debug metadata associated with this charging
sub-session.
content:
application/json:
schema:
$ref: '#/components/schemas/ChargingSubSessionDebugMetadata'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-charging_sub_sessions-charging_sub_session_id-debug_metadata
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/expand-on-chargingsubsession-debug-metadata'
security:
- oauth2:
- debug:read
/notifications:
get:
summary: List notifications
tags:
- Notifications
responses:
'200':
description: Retrieve all current notifications.
headers:
Link:
$ref: '#/components/headers/link-pages'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Notification'
examples:
Example 1:
value:
- id: notf67O36PLTFDB57M0E5L33JZLGM0
url: >-
https://api.ev.energy/notifications/notf67O36PLTFDB57M0E5L33JZLGM0
message_id: ERR0123
category: ACTIONABLE
event_time: '2019-08-24T14:15:22Z'
short_text_title: Your car is disconnected
short_text_body: We need to reconnect to keep smart charging
detail_page_title: Your car is disconnected
detail_page_body: >-
Your car has been disconnected. This happens when your
password is reset.
We need you to re-authorise ev.energy to access your
account in order for us to keep managing your charging.
Blah blah blah.
external_link: https://example.com
external_button_label: More info
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-notifications
parameters:
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/Accept-Language'
- $ref: '#/components/parameters/user'
description: |-
Lists notifications for the user making the request. For each
notification it returns a category (INFO, ERROR etc) and a title
(in the user's language) for display in their inbox.
/notifications/{notification_id}:
parameters:
- $ref: '#/components/parameters/notification_id'
patch:
summary: Update a notification
tags:
- Notifications
responses:
'200':
description: Notification updated successfully.
headers:
EVEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: object
properties:
Notification:
$ref: '#/components/schemas/Notification'
'400':
$ref: '#/components/responses/Problem400BadRequestCreate'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: patch-notifications-notification_id
description: Update a notification.
security:
- oauth2: []
requestBody:
description: Details of Notification to be updated.
content:
application/json:
schema:
type: object
properties:
read_at:
type: string
format: date-time
get:
summary: Retrieve a notification
tags:
- Notifications
responses:
'200':
description: Retrieve a specific notification.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/Notification'
examples:
Example 1:
value:
id: notf67O36PLTFDB57M0E5L33JZLGM0
url: >-
https://api.ev.energy/notifications/notf67O36PLTFDB57M0E5L33JZLGM0
message_id: ERR0123
category: ACTIONABLE
event_time: '2019-08-24T14:15:22Z'
short_text_title: Your car is disconnected
short_text_body: We need to reconnect to keep smart charging
detail_page_title: Your car is disconnected
detail_page_body: >-
Your car has been disconnected. This happens when your
password is reset.
We need you to re-authorise ev.energy to access your
account in order for us to keep managing your charging.
Blah blah blah.
external_link: https://example.com
external_button_label: More info
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-notifications-notification_id
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/Accept-Language'
description: |-
Retrieves the full details of a specified notification. The title,
short_text and long_text fields will be translated into the user's
language.
security:
- oauth2: []
/webhook_portal:
get:
summary: Retrieve access link for webhook portal
tags:
- Webhooks
responses:
'200':
description: Returns a URL that gives access to the Webhook configuration portal.
content:
application/json:
schema:
type: object
properties:
url:
type: string
format: uri
example: https://app.svix.com/login#key=xyz
readOnly: true
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-webhook_portal
description: Generate a one time use link to access the portal to configure webhooks.
security:
- oauth2: []
parameters:
- $ref: '#/components/parameters/version-2'
requestBody:
content: {}
/solar_arrays:
get:
summary: List solar arrays
responses:
'200':
description: Returns a list of solar arrays.
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SolarArray'
examples:
Example 1:
value:
- id: solr01JASZTD3T7N39DTZPBJVXNPKP
url: >-
https://api.ev.energy/v2/solar_arrays/solr01JASZTD3T7N39DTZPBJVXNPKP
capacity_watts: 7000
inverter: >-
https://api.ev.energy/v2/inverters/invtFB08NVS8KADFY6GAQ9C6RMFGUY
forecast:
solar_watt_hours_until_midnight: 19
percent_vehicle_battery_charge_until_midnight: 30
last_updated_at: '2024-10-16T11:26:16'
user: >-
https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-solar-arrays
description: List all the solar arrays that the authorization token has access to.
parameters:
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/expand-on-solararray'
- $ref: '#/components/parameters/user'
- schema:
type: string
example: vhcl01HRFF3SEVSCRAV9B3CHVDFN0H
in: query
name: vehicle_id
description: >-
When provided, populates the
`percent_vehicle_battery_charge_until_midnight` field.
tags:
- Solar
security:
- oauth2:
- solar:read
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/Accept-Language'
post:
description: |
Creates a solar array and associates it with the user.
summary: Create a solar array
operationId: post-solar-arrays
parameters: []
requestBody:
description: Details of Solar Array to be created.
content:
application/json:
schema:
type: object
properties:
capacity_watts:
type: integer
minimum: 0
responses:
'201':
description: Solar Array created.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: object
$ref: '#/components/schemas/SolarArray'
examples:
Example 1:
value:
id: solr01JASZTD3T7N39DTZPBJVXNPKP
url: >-
https://api.ev.energy/solar_arrays/solr01JASZTD3T7N39DTZPBJVXNPKP
capacity_watts: 7000
inverter: >-
https://api.ev.energy/inverters/invtFB08NVS8KADFY6GAQ9C6RMFGUY
forecast:
solar_watt_hours_until_midnight: 19
percent_vehicle_battery_charge_until_midnight: 30
last_updated_at: '2024-10-16T11:26:16'
user: >-
https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735
'400':
$ref: '#/components/responses/Problem400BadRequestCreate'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
tags:
- Solar
security:
- oauth2:
- solar:write
/solar_arrays/{solar_array_id}:
parameters:
- schema:
type: string
example: solr01JASZTD3T7N39DTZPBJVXNPKP
pattern: solr[A-Z\d]{26}
name: solar_array_id
in: path
required: true
description: The ID of the specific Solar Array to retrieve or update.
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/Accept-Language'
get:
description: Retrieve a single, specific solar array's details.
operationId: get-solar-arrays-solar_array_id
summary: Retrieve a solar array
parameters:
- $ref: '#/components/parameters/expand-on-solararray'
- $ref: '#/components/parameters/version-2'
- schema:
type: string
example: vhcl01HRFF3SEVSCRAV9B3CHVDFN0H
in: query
name: vehicle_id
description: >-
When provided, populates the
`percent_vehicle_battery_charge_until_midnight` field.
responses:
'200':
description: Returns a single solar array.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: object
$ref: '#/components/schemas/SolarArray'
examples:
Example 1:
value:
id: solr01JASZTD3T7N39DTZPBJVXNPKP
url: >-
https://api.ev.energy/solar_arrays/solr01JASZTD3T7N39DTZPBJVXNPKP
capacity_watts: 7000
inverter: >-
https://api.ev.energy/inverters/invtFB08NVS8KADFY6GAQ9C6RMFGUY
forecast:
solar_watt_hours_until_midnight: 19
percent_vehicle_battery_charge_until_midnight: 30
last_updated_at: '2024-10-16T11:26:16'
user: >-
https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
tags:
- Solar
security:
- oauth2:
- solar:read
patch:
summary: Update a solar array
tags:
- Solar
responses:
'200':
description: Solar array updated successfully.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: object
$ref: '#/components/schemas/SolarArray'
examples:
Example 1:
value:
id: solr01JASZTD3T7N39DTZPBJVXNPKP
url: >-
https://api.ev.energy/solar_arrays/solr01JASZTD3T7N39DTZPBJVXNPKP
capacity_watts: 7000
inverter: >-
https://api.ev.energy/inverters/invtFB08NVS8KADFY6GAQ9C6RMFGUY
forecast:
solar_watt_hours_until_midnight: 19
percent_vehicle_battery_charge_until_midnight: 30
last_updated_at: '2024-10-16T11:26:16'
user: >-
https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735
'400':
$ref: '#/components/responses/Problem400BadRequestCreate'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: patch-solar_arrays-solar_array_id
description: Update a solar array.
parameters:
- $ref: '#/components/parameters/expand-on-solararray'
- $ref: '#/components/parameters/version-2'
requestBody:
content:
application/json:
schema:
type: object
properties:
capacity_watts:
type: integer
minimum: 0
examples:
Example 1:
value:
capacity_watts: 7000
description: Details of Solar Array to be updated.
security:
- oauth2:
- solar:write
/solar_forecasts:
get:
summary: List solar forecasts
tags:
- Solar Forecasts
responses:
'200':
description: Returns a list of solar forecasts.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SolarForecast'
examples:
Example 1:
value:
- id: solf01JASZTD3T7N39DTZPBJVXNPKP
url: >-
https://api.ev.energy/v2/solar_forecasts/solf01JASZTD3T7N39DTZPBJVXNPKP
location:
latitude: 51.51
longitude: -0.13
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-solar-forecasts
description: List all the solar forecasts that the authorization token has access to.
parameters:
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- solar_forecast:read
parameters:
- $ref: '#/components/parameters/version-2'
/solar_forecasts/{solar_forecast_id}:
parameters:
- $ref: '#/components/parameters/solar_forecast_id'
- $ref: '#/components/parameters/version-2'
get:
summary: Retrieve a solar forecast
tags:
- Solar Forecasts
responses:
'200':
description: Returns a single solar forecast.
content:
application/json:
schema:
$ref: '#/components/schemas/SolarForecast'
examples:
Example 1:
value:
id: solf01JASZTD3T7N39DTZPBJVXNPKP
url: >-
https://api.ev.energy/v2/solar_forecasts/solf01JASZTD3T7N39DTZPBJVXNPKP
location:
latitude: 51.51
longitude: -0.13
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-solar-forecasts-solar_forecast_id
description: Retrieve a single, specific solar forecast's details.
parameters:
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- solar_forecast:read
/solar_forecasts/{solar_forecast_id}/forecast_logs:
parameters:
- $ref: '#/components/parameters/solar_forecast_id'
get:
summary: List forecast logs for a solar forecast
description: >-
List the historical forecast logs for a specific solar forecast. These
logs record predicted solar energy production at specific times.
tags:
- Solar Forecasts
responses:
'200':
description: >-
List all forecast logs for a specific solar forecast, sorted newest
first.
headers:
Link:
$ref: '#/components/headers/link-timestamps'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SolarForecastLog'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-solar-forecasts-solar_forecast_id-forecast_logs
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/started_at__gte'
- $ref: '#/components/parameters/started_at__lte'
- $ref: '#/components/parameters/expand-on-solarforecastlog'
security:
- oauth2:
- solar_forecast:read
/solar_forecasts/{solar_forecast_id}/forecast_logs/{valid_period_start}:
parameters:
- $ref: '#/components/parameters/solar_forecast_id'
- schema:
type: string
format: date-time
name: valid_period_start
in: path
required: true
description: The start of the forecast validity period.
example: '2024-04-17T09:00:00.100000Z'
get:
summary: Retrieve a forecast log for a solar forecast
description: >-
A solar forecast log is uniquely identified by the combination of solar
forecast ID and the valid period start time.
tags:
- Solar Forecasts
responses:
'200':
description: Retrieve a single forecast log for a specific solar forecast.
content:
application/json:
schema:
$ref: '#/components/schemas/SolarForecastLog'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-solar-forecasts-solar_forecast_id-forecast_logs-valid_period_start
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/expand-on-solarforecastlog'
security:
- oauth2:
- solar_forecast:read
/subscriptions:
get:
summary: List subscriptions
responses:
'200':
description: Returns a list of subscriptions.
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Subscription'
examples:
Example 1:
value:
- id: subsB1USP6YGD1VPIDJSHTZARUX11M
url: >-
https://api.ev.energy/subscriptions/subsB1USP6YGD1VPIDJSHTZARUX11M
offering: >-
https://api.ev.energy/v2/subscription_offerings/suboB1USP6YGD1VPIDJSHTZARUX11M
user: >-
https://api.ev.energy/v2/user/user01HN2NJ9NMRZBXT1H6FT9N7735
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-subscriptions
description: >-
List all the valid subscriptions that the authorization token has access
to.
parameters:
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/expand-on-subscription'
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/Accept-Language'
- $ref: '#/components/parameters/user'
tags:
- Subscriptions
security:
- oauth2:
- subscription:read
/subscription_offerings/{offering_id}:
get:
summary: Retrieve a subscription offering
responses:
'200':
description: Returns a single subscription offering.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionOffering'
examples:
Example 1:
value:
id: suboB1USP6YGD1VPIDJSHTZARUX11M
url: >-
https://api.ev.energy/v2/subscription_offerings/suboB1USP6YGD1VPIDJSHTZARUX11M
name: ev.energy Solar Lifetime
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-subscription-offerings-offering_id
description: Retrieve a single, specific subscription offering's details.
parameters:
- $ref: '#/components/parameters/expand-on-subscription'
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/Accept-Language'
tags:
- Subscriptions
security:
- oauth2:
- subscription:read
parameters:
- schema:
type: string
name: offering_id
in: path
required: true
description: The ID of the specific subscription offering to retrieve
/support_tickets:
get:
summary: List support tickets
tags:
- Support Tickets
responses:
'200':
description: Returns a list of support tickets.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SupportTicket'
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-support_tickets
description: >-
List all support tickets that the authorization token has access to.
Access control:
- User-scoped tokens: Returns only tickets belonging to that user
- Organization-scoped tokens: Returns only tickets belonging to users in
that organization
- Tokens with access_all_areas: Returns all tickets including those
without a user
Note: Tickets without a user (null user field) are only accessible to
applications with access_all_areas permission. These tickets represent
inquiries from channels where a user account may not exist (e.g.,
pre-signup inquiries, web forms).
parameters:
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/expand-on-supportticket'
- schema:
type: string
in: query
name: external_ticket_id
description: Filter by external ticket ID from support system
- schema:
type: string
in: query
name: human_verified_category
description: Filter by human verified category
- schema:
type: string
in: query
name: human_verified_subcategory
description: Filter by human verified subcategory
- schema:
type: string
in: query
name: ai_generated_category
description: Filter by AI generated category
- schema:
type: string
in: query
name: ai_generated_subcategory
description: Filter by AI generated subcategory
- schema:
type: boolean
in: query
name: human_verified_category__isnull
description: Filter for tickets with or without human verified category
- schema:
type: boolean
in: query
name: human_verified_subcategory__isnull
description: Filter for tickets with or without human verified subcategory
- schema:
type: boolean
in: query
name: ai_generated_category__isnull
description: Filter for tickets with or without AI generated category
- schema:
type: boolean
in: query
name: ai_generated_subcategory__isnull
description: Filter for tickets with or without AI generated subcategory
- schema:
type: string
in: query
name: status
description: Filter by ticket status (e.g., Open, Resolved, Closed)
- schema:
type: string
in: query
name: status__in
description: Filter by multiple status values (comma-separated)
- schema:
type: string
in: query
name: priority
description: Filter by ticket priority (e.g., Low, Medium, High, Urgent)
- schema:
type: string
in: query
name: priority__in
description: Filter by multiple priority values (comma-separated)
- schema:
type: boolean
in: query
name: priority__isnull
description: Filter for tickets with or without priority
- schema:
type: string
format: date-time
in: query
name: created_at__gte
description: Filter tickets created on or after this date
- schema:
type: string
format: date-time
in: query
name: created_at__lte
description: Filter tickets created on or before this date
- schema:
type: string
in: query
name: created_at__range
description: >-
Filter tickets created within a date range (comma-separated start
and end dates)
- schema:
type: string
format: uri
in: query
name: user
description: Filter tickets by a specific user ID
- schema:
type: boolean
in: query
name: user__isnull
description: Filter for tickets with or without an associated user
- schema:
type: string
in: query
name: tags
description: Filter by tag (checks if the tag exists in the tags array)
- schema:
type: string
in: query
name: source
description: Filter by ticket source (e.g., Email, Phone, Feedback Widget)
- schema:
type: string
in: query
name: source__in
description: Filter by multiple sources (comma-separated)
- schema:
type: string
format: date-time
in: query
name: resolved_at__gte
description: Filter tickets resolved on or after this date
- schema:
type: string
format: date-time
in: query
name: resolved_at__lte
description: Filter tickets resolved on or before this date
- schema:
type: string
in: query
name: resolved_at__range
description: >-
Filter tickets resolved within a date range (comma-separated start
and end dates)
- schema:
type: boolean
in: query
name: resolved_at__isnull
description: Filter for unresolved tickets (true) or resolved tickets (false)
- schema:
type: string
format: date-time
in: query
name: ticket_updated_at__gte
description: Filter tickets updated on or after this date
- schema:
type: string
format: date-time
in: query
name: ticket_updated_at__lte
description: Filter tickets updated on or before this date
- schema:
type: string
in: query
name: ticket_updated_at__range
description: >-
Filter tickets updated within a date range (comma-separated start
and end dates)
- schema:
type: boolean
in: query
name: ticket_updated_at__isnull
description: Filter for tickets with or without an update timestamp
- $ref: '#/components/parameters/user'
security:
- oauth2:
- support:read
/support_tickets/{support_ticket_id}:
parameters:
- $ref: '#/components/parameters/support_ticket_id'
get:
summary: Retrieve support ticket
description: >-
Retrieve information about a single, specific support ticket.
Access control:
- User-scoped tokens: Can only access tickets belonging to that user
- Organization-scoped tokens: Can only access tickets belonging to users
in that organization
- Tokens with access_all_areas: Can access all tickets including those
without a user
Note: Tickets without a user (null user field) will return 404 for
tokens without access_all_areas permission.
tags:
- Support Tickets
responses:
'200':
description: Returns a single support ticket.
content:
application/json:
schema:
$ref: '#/components/schemas/SupportTicket'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-support_tickets-support_ticket_id
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/expand-on-supportticket'
security:
- oauth2:
- support:read
patch:
summary: Update support ticket
tags:
- Support Tickets
responses:
'200':
description: Support ticket updated successfully.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
content:
application/json:
schema:
$ref: '#/components/schemas/SupportTicket'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: patch-support_tickets-support_ticket_id
security:
- oauth2:
- support:write
description: >-
Update support ticket categorization.
Access control follows the same rules as retrieval:
- User-scoped tokens: Can only update tickets belonging to that user
- Organization-scoped tokens: Can only update tickets belonging to users
in that organization
- Tokens with access_all_areas: Can update all tickets including those
without a user
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SupportTicket'
multipart/form-data:
schema:
$ref: '#/components/schemas/SupportTicket'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/SupportTicket'
parameters:
- $ref: '#/components/parameters/version-2'
/support_tickets/{support_ticket_id}/messages:
parameters:
- $ref: '#/components/parameters/support_ticket_id'
get:
summary: List messages for a support ticket
description: >-
List all messages in a support ticket conversation, ordered by position.
Access control follows the same rules as the parent support ticket:
- User-scoped tokens: Can only access messages for tickets belonging to
that user
- Organization-scoped tokens: Can only access messages for tickets
belonging to users in that organization
- Tokens with access_all_areas: Can access messages for all tickets
including those without a user
tags:
- Support Tickets
responses:
'200':
description: Returns a list of messages for the specified support ticket.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SupportTicketMessage'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-support_tickets-support_ticket_id-messages
parameters:
- $ref: '#/components/parameters/version-2'
- schema:
type: string
in: query
name: message_type
description: >-
Filter by message type (e.g., INITIAL_REQUEST, CUSTOMER_RESPONSE,
HUMAN_AGENT_RESPONSE, AI_AGENT_RESPONSE)
- schema:
type: string
in: query
name: message_type__in
description: Filter by multiple message types (comma-separated)
- schema:
type: integer
in: query
name: position
description: Filter by message position in the conversation (0 is first message)
- schema:
type: integer
in: query
name: position__gte
description: Filter for messages at or after this position
- schema:
type: integer
in: query
name: position__lte
description: Filter for messages at or before this position
security:
- oauth2:
- support:read
/support_tickets/{support_ticket_id}/messages/{message_id}:
parameters:
- $ref: '#/components/parameters/support_ticket_id'
- $ref: '#/components/parameters/message_id'
get:
summary: Retrieve a message for a support ticket
description: |-
Retrieve a single message from a support ticket conversation.
Access control follows the same rules as the parent support ticket.
tags:
- Support Tickets
responses:
'200':
description: Returns a single support ticket message.
content:
application/json:
schema:
$ref: '#/components/schemas/SupportTicketMessage'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-support_tickets-support_ticket_id-messages-message_id
parameters:
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- support:read
/support_tickets/categories:
get:
summary: Get support ticket categories
tags:
- Support Tickets
description: Returns all available support ticket categories and subcategories.
operationId: get-support_tickets-categories
responses:
'200':
description: Returns all available categories and subcategories.
content:
application/json:
schema:
type: object
properties:
categories:
type: array
description: >-
List of all available ticket categories. Each category
includes the enum value and its human-readable label.
items:
type: object
required:
- value
- label
properties:
value:
allOf:
- $ref: '#/components/schemas/SupportTicketCategoryEnum'
description: >-
The enum value (ALL_CAPS format) for programmatic
use.
example: CHARGER
label:
type: string
description: Human-readable label for display.
example: Charger
subcategories:
type: array
description: >-
List of all available ticket subcategories. Each
subcategory includes the enum value and its human-readable
label.
items:
type: object
required:
- value
- label
properties:
value:
allOf:
- $ref: >-
#/components/schemas/SupportTicketSubcategoryEnum
description: >-
The enum value (ALL_CAPS format) for programmatic
use.
example: HARDWARE_ISSUE
label:
type: string
description: Human-readable label for display.
example: Hardware Issue
examples:
Example:
value:
categories:
- value: ACCOUNT
label: Account
- value: CHARGER
label: Charger
- value: CHARGING_SESSION
label: Charging Session
- value: MOBILE_APP
label: Mobile App
- value: OTHER
label: Other
- value: SOLAR
label: Solar
- value: USABILITY_UX
label: Usability/UX
- value: VEHICLE
label: Vehicle
subcategories:
- value: ACCESSIBILITY
label: Accessibility
- value: HARDWARE_ISSUE
label: Hardware Issue
- value: APP_CRASH_FREEZE
label: App crash / freeze
- value: TELEMATICS_ISSUE
label: Telematics issue
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
parameters:
- $ref: '#/components/parameters/version-2'
/support-ticket-stats/sankey:
get:
summary: Get support ticket Sankey diagram data
tags:
- Support Tickets
description: >-
Returns aggregated data for visualizing ticket flow from category to
subcategory in a Sankey diagram. Only includes tickets with
human-verified categories.
operationId: get-support_ticket_stats-sankey
responses:
'200':
description: Returns Sankey diagram nodes and links.
content:
application/json:
schema:
type: object
properties:
nodes:
type: array
description: >-
List of nodes in the Sankey diagram (categories and
subcategories).
items:
type: object
required:
- id
- label
properties:
id:
type: string
description: >-
Unique identifier for the node (prefixed with
'category:' or 'subcategory:').
example: category:Charger
label:
type: string
description: Human-readable label for display.
example: Charger
links:
type: array
description: List of links between nodes representing ticket flows.
items:
type: object
required:
- source
- target
- value
properties:
source:
type: string
description: ID of the source node (category).
example: category:Charger
target:
type: string
description: ID of the target node (subcategory).
example: subcategory:Hardware Issue
value:
type: integer
description: Number of tickets flowing from source to target.
example: 42
examples:
Example:
value:
nodes:
- id: category:Charger
label: Charger
- id: subcategory:Hardware Issue
label: Hardware Issue
links:
- source: category:Charger
target: subcategory:Hardware Issue
value: 42
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
parameters:
- $ref: '#/components/parameters/version-2'
/support-ticket-stats/volume:
get:
summary: Get support ticket volume time series
tags:
- Support Tickets
description: >-
Returns time series data showing ticket volume over time. Can be grouped
by day, week, or month.
operationId: get-support_ticket_stats-volume
responses:
'200':
description: Returns time series data for ticket volume.
content:
application/json:
schema:
type: object
properties:
time_series:
type: array
description: List of time periods with ticket counts.
items:
type: object
required:
- date
- count
properties:
date:
type: string
format: date
description: ISO 8601 date string for the time period.
example: '2024-01-15'
count:
type: integer
description: Number of distinct tickets created in this period.
example: 23
examples:
Example:
value:
time_series:
- date: '2024-01-15'
count: 23
- date: '2024-01-16'
count: 31
- date: '2024-01-17'
count: 18
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
parameters:
- $ref: '#/components/parameters/version-2'
- name: group_by
in: query
description: Time period to group by (day, week, or month). Defaults to day.
schema:
type: string
enum:
- day
- week
- month
default: day
/support-ticket-stats/resolution:
get:
summary: Get support ticket resolution metrics
tags:
- Support Tickets
description: >-
Returns metrics about ticket resolution including resolution rate,
average and median resolution times.
operationId: get-support_ticket_stats-resolution
responses:
'200':
description: Returns resolution metrics.
content:
application/json:
schema:
type: object
required:
- resolution_rate
- total_resolved
- total_unresolved
properties:
resolution_rate:
type: number
format: float
description: Percentage of tickets that have been resolved (0-1).
example: 0.85
avg_resolution_time_hours:
type:
- number
- 'null'
format: float
description: >-
Average time to resolve a ticket in hours. Null if no
tickets resolved.
example: 24.5
median_resolution_time_hours:
type:
- number
- 'null'
format: float
description: >-
Median time to resolve a ticket in hours. Null if no
tickets resolved.
example: 18.2
total_resolved:
type: integer
description: Total number of resolved tickets.
example: 170
total_unresolved:
type: integer
description: Total number of unresolved tickets.
example: 30
examples:
Example:
value:
resolution_rate: 0.85
avg_resolution_time_hours: 24.5
median_resolution_time_hours: 18.2
total_resolved: 170
total_unresolved: 30
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
parameters:
- $ref: '#/components/parameters/version-2'
/support-ticket-stats/status:
get:
summary: Get support ticket status breakdown
tags:
- Support Tickets
description: Returns the distribution of tickets across different status values.
operationId: get-support_ticket_stats-status
responses:
'200':
description: Returns ticket breakdown by status.
content:
application/json:
schema:
type: object
properties:
breakdown:
type: array
description: List of status values with counts and percentages.
items:
type: object
required:
- status
- count
- percentage
properties:
status:
type: string
description: Status value.
example: open
count:
type: integer
description: Number of distinct tickets with this status.
example: 45
percentage:
type: number
format: float
description: Percentage of total tickets (0-1).
example: 0.45
examples:
Example:
value:
breakdown:
- status: open
count: 45
percentage: 0.45
- status: closed
count: 55
percentage: 0.55
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
parameters:
- $ref: '#/components/parameters/version-2'
/support-ticket-stats/priority:
get:
summary: Get support ticket priority breakdown
tags:
- Support Tickets
description: Returns the distribution of tickets across different priority values.
operationId: get-support_ticket_stats-priority
responses:
'200':
description: Returns ticket breakdown by priority.
content:
application/json:
schema:
type: object
properties:
breakdown:
type: array
description: List of priority values with counts and percentages.
items:
type: object
required:
- priority
- count
- percentage
properties:
priority:
type: string
description: Priority value.
example: high
count:
type: integer
description: Number of distinct tickets with this priority.
example: 12
percentage:
type: number
format: float
description: Percentage of total tickets (0-1).
example: 0.12
examples:
Example:
value:
breakdown:
- priority: high
count: 12
percentage: 0.12
- priority: medium
count: 58
percentage: 0.58
- priority: low
count: 30
percentage: 0.3
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
parameters:
- $ref: '#/components/parameters/version-2'
/support-ticket-stats/source:
get:
summary: Get support ticket source breakdown
tags:
- Support Tickets
description: Returns the distribution of tickets across different source values.
operationId: get-support_ticket_stats-source
responses:
'200':
description: Returns ticket breakdown by source.
content:
application/json:
schema:
type: object
properties:
breakdown:
type: array
description: List of source values with counts and percentages.
items:
type: object
required:
- source
- count
- percentage
properties:
source:
type: string
description: Source value.
example: mobile_app
count:
type: integer
description: Number of distinct tickets from this source.
example: 67
percentage:
type: number
format: float
description: Percentage of total tickets (0-1).
example: 0.67
examples:
Example:
value:
breakdown:
- source: mobile_app
count: 67
percentage: 0.67
- source: web
count: 33
percentage: 0.33
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
parameters:
- $ref: '#/components/parameters/version-2'
/support-ticket-stats/top-categories:
get:
summary: Get top support ticket categories and subcategories
tags:
- Support Tickets
description: >-
Returns the most common categories and subcategories sorted by ticket
count. Supports a limit parameter to control the number of results.
operationId: get-support_ticket_stats-top-categories
responses:
'200':
description: Returns top categories and subcategories.
content:
application/json:
schema:
type: object
properties:
categories:
type: array
description: List of most common categories.
items:
type: object
required:
- category
- count
- percentage
properties:
category:
allOf:
- $ref: '#/components/schemas/SupportTicketCategoryEnum'
description: Category enum value.
example: CHARGER
count:
type: integer
description: Number of distinct tickets with this category.
example: 145
percentage:
type: number
format: float
description: Percentage of total tickets (0-1).
example: 0.45
subcategories:
type: array
description: >-
List of most common subcategories with their parent
category.
items:
type: object
required:
- subcategory
- category
- count
- percentage
properties:
subcategory:
allOf:
- $ref: >-
#/components/schemas/SupportTicketSubcategoryEnum
description: Subcategory enum value.
example: HARDWARE_ISSUE
category:
allOf:
- $ref: '#/components/schemas/SupportTicketCategoryEnum'
description: Parent category enum value.
example: CHARGER
count:
type: integer
description: Number of distinct tickets with this subcategory.
example: 78
percentage:
type: number
format: float
description: Percentage of total tickets (0-1).
example: 0.24
examples:
Example:
value:
categories:
- category: CHARGER
count: 145
percentage: 0.45
- category: MOBILE_APP
count: 89
percentage: 0.28
subcategories:
- subcategory: HARDWARE_ISSUE
category: CHARGER
count: 78
percentage: 0.24
- subcategory: APP_CRASH_FREEZE
category: MOBILE_APP
count: 45
percentage: 0.14
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
parameters:
- $ref: '#/components/parameters/version-2'
- name: limit
in: query
description: >-
Maximum number of categories/subcategories to return. Defaults to
10.
schema:
type: integer
default: 10
minimum: 1
/inverters:
post:
summary: Create an Inverter
responses:
'201':
description: Inverter created.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/Inverter'
examples:
Example 1:
value:
id: invtFB08NVS8KADFY6GAQ9C6RMFGUY
url: >-
https://api.ev.energy/inverters/invtFB08NVS8KADFY6GAQ9C6RMFGUY
model:
id: imodT4J2GW1IOPAA7FRW53R8P4UXCB
url: >-
https://api.ev.energy/inverters/imodT4J2GW1IOPAA7FRW53R8P4UXCB
name: Envoy-R
make:
id: imakK7XDPL63NNBDQ5DPB6K3TP87JA
url: >-
https://api.ev.energy/inverter_makes/imakK7XDPL63NNBDQ5DPB6K3TP87JA
name: Enphase
user: >-
https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: post-inverters
description: Creates an Inverter and associates it with a user's solar array.
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/user'
security:
- oauth2:
- inverter:write
requestBody:
content:
application/json:
schema:
type: object
x-examples:
Example 1:
model: imod7XL7Q5294J6TUZARBQT2D1EOHY
properties:
model:
type: string
format: uri
example: >-
https://api.ev.energy/v2/inverter_models/imodOTQRGK9OKMPDU63SYGJ9T6FH3A
user:
type: string
format: uri
example: >-
https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735
examples:
Example 1:
value:
model: >-
https://api.ev.energy/inverters/imod7XL7Q5294J6TUZARBQT2D1EOHY
description: Details of the Inverter to be created.
tags:
- Solar
get:
summary: List inverters
responses:
'200':
description: Returns a list of inverters.
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Inverter'
examples:
Example 1:
value:
- id: invtFB08NVS8KADFY6GAQ9C6RMFGUY
url: >-
https://api.ev.energy/inverters/invtFB08NVS8KADFY6GAQ9C6RMFGUY
model: >-
https://api.ev.energy/inverters/imodT4J2GW1IOPAA7FRW53R8P4UXCB
user: >-
https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-inverters
description: List all the inverters that the authorization token has access to.
security:
- oauth2:
- inverter:read
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/expand-on-inverter'
- $ref: '#/components/parameters/Accept-Language'
- $ref: '#/components/parameters/user'
tags:
- Solar
/inverters/{inverter_id}:
parameters:
- schema:
type: string
name: inverter_id
in: path
required: true
description: The ID of the specific Inverter to retrieve or update.
get:
summary: Retrieve an inverter
responses:
'200':
description: Returns a single inverter.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/Inverter'
examples:
Example 1:
value:
id: invtFB08NVS8KADFY6GAQ9C6RMFGUY
url: >-
https://api.ev.energy/inverters/invtFB08NVS8KADFY6GAQ9C6RMFGUY
model:
id: imodT4J2GW1IOPAA7FRW53R8P4UXCB
url: >-
https://api.ev.energy/inverters/imodT4J2GW1IOPAA7FRW53R8P4UXCB
name: Envoy-R
make:
id: imakK7XDPL63NNBDQ5DPB6K3TP87JA
url: >-
https://api.ev.energy/inverter_makes/imakK7XDPL63NNBDQ5DPB6K3TP87JA
name: Enphase
user: >-
https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-inverters-inverter_id
description: Retrieve a single, specific inverter's details.
security:
- oauth2:
- inverter:read
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/expand-on-inverter'
- $ref: '#/components/parameters/Accept-Language'
tags:
- Solar
/inverter_makes:
get:
summary: List inverter makes
tags:
- Solar
responses:
'200':
description: Return a list of Inverter Makes.
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/InverterMake'
examples:
Example 1:
value:
- id: imakK7XDPL63NNBDQ5DPB6K3TP87JA
url: >-
https://api.ev.energy/inverter_makes/imakK7XDPL63NNBDQ5DPB6K3TP87JA
name: Enphase
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-inverter_makes
description: List all the inverter makes known by the ev.energy system.
security:
- oauth2:
- inverter:read
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/available_for_user_id'
- $ref: '#/components/parameters/Accept-Language'
/inverter_makes/{inverter_make_id}:
parameters:
- schema:
type: string
name: inverter_make_id
in: path
required: true
description: The ID of the specific inverter make to retrieve.
get:
summary: Retrieve an inverter make
tags:
- Solar
responses:
'200':
description: Return a single inverter make.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/InverterMake'
examples:
Example 1:
value:
id: imakK7XDPL63NNBDQ5DPB6K3TP87JA
url: >-
https://api.ev.energy/inverter_makes/imakK7XDPL63NNBDQ5DPB6K3TP87JA
name: Enphase
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem404NotFound'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-inverter_makes-inverter_make_id
description: Retrieve details for a single, specific EVSE make.
security:
- oauth2:
- inverter:read
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/Accept-Language'
/inverter_models:
get:
summary: List inverter models
tags:
- Solar
responses:
'200':
description: Returns a list of inverter models.
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/InverterModel'
examples:
Example 1:
value:
- id: imodT4J2GW1IOPAA7FRW53R8P4UXCB
url: >-
https://api.ev.energy/inverters/imodT4J2GW1IOPAA7FRW53R8P4UXCB
name: Envoy-R
make: >-
https://api.ev.energy/inverter_makes/imakK7XDPL63NNBDQ5DPB6K3TP87JA
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-inverter_models
description: List all the inverter models known by the ev.energy system.
security:
- oauth2:
- inverter:read
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/expand-on-invertermodel'
- $ref: '#/components/parameters/Accept-Language'
- $ref: '#/components/parameters/inverter_make_id_q'
/inverter_models/{inverter_model_id}:
parameters:
- schema:
type: string
name: inverter_model_id
in: path
required: true
description: The ID of the specific inverter model to retrieve.
get:
summary: Retrieve an inverter model
tags:
- Solar
responses:
'200':
description: Return a single inverter model.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/InverterModel'
examples:
Example 1:
value:
id: imodT4J2GW1IOPAA7FRW53R8P4UXCB
url: >-
https://api.ev.energy/inverters/imodT4J2GW1IOPAA7FRW53R8P4UXCB
name: Envoy-R
make:
id: imakK7XDPL63NNBDQ5DPB6K3TP87JA
url: >-
https://api.ev.energy/inverter_makes/imakK7XDPL63NNBDQ5DPB6K3TP87JA
name: Enphase
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-inverter_models-inverter_model_id
description: Retrieve details for a single, specific inverter model.
security:
- oauth2:
- inverter:read
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/expand-on-invertermodel'
- $ref: '#/components/parameters/Accept-Language'
/home_battery_makes:
get:
summary: List home battery makes
tags:
- Home Batteries
responses:
'200':
description: Return a list of Home Battery Makes.
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/HomeBatteryMake'
examples:
Example 1:
value:
- id: bmakK7XDPL63NNBDQ5DPB6K3TP87JA
url: >-
https://api.ev.energy/v2/home_battery_makes/bmakK7XDPL63NNBDQ5DPB6K3TP87JA
name: Rivendell
icon: null
onboarding_url: >-
https://api.ev.energy/v2/home_battery_onboarding?make_id=bmakK7XDPL63NNBDQ5DPB6K3TP87JA&client_id=clntK7XDPL63NNBDQ5DPB6K3TP87JA
models: >-
https://api.ev.energy/v2/home_battery_models?make_id=bmakK7XDPL63NNBDQ5DPB6K3TP87JA
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-home_battery_makes
description: List all the home battery makes known by the ev.energy system.
security:
- oauth2:
- home_battery:read
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/Accept-Language'
/home_battery_makes/{home_battery_make_id}:
parameters:
- schema:
type: string
name: home_battery_make_id
in: path
required: true
description: The ID of the specific home battery make to retrieve.
get:
summary: Retrieve a home battery make
tags:
- Home Batteries
responses:
'200':
description: Return a single home battery make.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/HomeBatteryMake'
examples:
Example 1:
value:
id: bmakK7XDPL63NNBDQ5DPB6K3TP87JA
url: >-
https://api.ev.energy/v2/home_battery_makes/bmakK7XDPL63NNBDQ5DPB6K3TP87JA
name: Rivendell
icon: null
onboarding_url: >-
https://api.ev.energy/v2/home_battery_onboarding?make_id=bmakK7XDPL63NNBDQ5DPB6K3TP87JA&client_id=clntK7XDPL63NNBDQ5DPB6K3TP87JA
models: >-
https://api.ev.energy/v2/home_battery_models?make_id=bmakK7XDPL63NNBDQ5DPB6K3TP87JA
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-home_battery_makes-home_battery_make_id
description: Retrieve details for a single, specific home battery make.
security:
- oauth2:
- home_battery:read
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/Accept-Language'
/home_battery_models:
get:
summary: List home battery models
tags:
- Home Batteries
responses:
'200':
description: Returns a list of home battery models.
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/HomeBatteryModel'
examples:
Example 1:
value:
- id: bmod7XL7Q5294J6TUZARBQT2D1EOHY
url: >-
https://api.ev.energy/v2/home_battery_models/bmod7XL7Q5294J6TUZARBQT2D1EOHY
name: Narsil
make: >-
https://api.ev.energy/v2/home_battery_makes/bmakK7XDPL63NNBDQ5DPB6K3TP87JA
onboarding_url: >-
https://api.ev.energy/v2/home_battery_onboarding?model_id=bmod7XL7Q5294J6TUZARBQT2D1EOHY&client_id=clntK7XDPL63NNBDQ5DPB6K3TP87JA
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-home_battery_models
description: List all the home battery models known by the ev.energy system.
security:
- oauth2:
- home_battery:read
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/expand-on-homebatterymodel'
- $ref: '#/components/parameters/Accept-Language'
- $ref: '#/components/parameters/home_battery_make_id_q'
/home_battery_models/{home_battery_model_id}:
parameters:
- schema:
type: string
name: home_battery_model_id
in: path
required: true
description: The ID of the specific home battery model to retrieve.
get:
summary: Retrieve a home battery model
tags:
- Home Batteries
responses:
'200':
description: Return a single home battery model.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/HomeBatteryModel'
examples:
Example 1:
value:
id: bmod7XL7Q5294J6TUZARBQT2D1EOHY
url: >-
https://api.ev.energy/v2/home_battery_models/bmod7XL7Q5294J6TUZARBQT2D1EOHY
name: Narsil
make:
id: bmakK7XDPL63NNBDQ5DPB6K3TP87JA
url: >-
https://api.ev.energy/v2/home_battery_makes/bmakK7XDPL63NNBDQ5DPB6K3TP87JA
name: Rivendell
onboarding_url: >-
https://api.ev.energy/v2/home_battery_onboarding?model_id=bmod7XL7Q5294J6TUZARBQT2D1EOHY&client_id=clntK7XDPL63NNBDQ5DPB6K3TP87JA
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-home_battery_models-home_battery_model_id
description: Retrieve details for a single, specific home battery model.
security:
- oauth2:
- home_battery:read
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/expand-on-homebatterymodel'
- $ref: '#/components/parameters/Accept-Language'
/home_batteries:
get:
summary: List home batteries
tags:
- Home Batteries
responses:
'200':
description: Returns a list of home batteries.
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/HomeBattery'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-home_batteries
description: List all the home batteries that the authorization token has access to.
security:
- oauth2:
- home_battery:read
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/user'
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/expand-on-homebattery'
/home_batteries/{home_battery_id}:
parameters:
- schema:
type: string
name: home_battery_id
in: path
required: true
description: The ID of the specific Home Battery to retrieve.
get:
summary: Retrieve a home battery
tags:
- Home Batteries
responses:
'200':
description: Returns a single home battery.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/HomeBattery'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-home_batteries-home_battery_id
description: Retrieve a single, specific home battery's details.
security:
- oauth2:
- home_battery:read
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/user'
- $ref: '#/components/parameters/expand-on-homebattery'
/home_batteries/{home_battery_id}/status_logs:
parameters:
- schema:
type: string
name: home_battery_id
in: path
required: true
description: The ID of the specific Home Battery to retrieve status logs for.
get:
summary: List status logs for a home battery
description: >-
List the historical status logs for a specific home battery. Used to
find out the state of the battery at each point it reported in to
ev.energy.
tags:
- Home Batteries
responses:
'200':
description: >-
List all status logs for a specific home battery, sorted newest
first.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/HomeBatteryStatusLog'
headers:
Link:
$ref: '#/components/headers/link-timestamps'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-home_batteries-home_battery_id-status_logs
parameters:
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/sampled_at__gte'
- $ref: '#/components/parameters/sampled_at__lte'
- $ref: '#/components/parameters/expand-on-homebatterystatuslog'
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- home_battery:read
/home_batteries/{home_battery_id}/status_logs/{sampled_at}:
parameters:
- schema:
type: string
name: home_battery_id
in: path
required: true
description: The ID of the specific Home Battery.
- schema:
type: string
format: date-time
name: sampled_at
in: path
required: true
description: The time the log's data was recorded on the device.
example: '2024-04-17T09:39:45.984584Z'
get:
summary: Retrieve a status log for a home battery
description: >-
A home battery status log is uniquely identified by the combination of
home battery ID and the time it was sampled at.
tags:
- Home Batteries
responses:
'200':
description: Retrieve a single status log for a specific home battery.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/HomeBatteryStatusLog'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-home_batteries-home_battery_id-status_logs-timestamp
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/expand-on-homebatterystatuslog'
security:
- oauth2:
- home_battery:read
/hem_systems:
get:
summary: List HEM systems
tags:
- HEM Systems
responses:
'200':
description: Returns a list of HEM (Home Energy Management) systems.
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/HEMSystem'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-hem_systems
description: List all the HEM systems that the authorization token has access to.
security:
- oauth2:
- home_energy:read
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/user'
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
/hem_systems/{hem_system_id}:
parameters:
- schema:
type: string
name: hem_system_id
in: path
required: true
description: The ID of the specific HEM system.
get:
summary: Retrieve a HEM system
description: Retrieve a single HEM (Home Energy Management) system by ID.
tags:
- HEM Systems
responses:
'200':
description: Returns a single HEM system.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/HEMSystem'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-hem_systems-hem_system_id
parameters:
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- home_energy:read
/hem_systems/{hem_system_id}/energy_stats:
parameters:
- schema:
type: string
name: hem_system_id
in: path
required: true
description: The ID of the specific HEM system.
get:
summary: Get aggregated energy statistics for a HEM system
description: >-
Returns aggregated energy statistics for the HEM system over a specified
time range and resolution.
Returns 400 Bad Request if query parameters are invalid (missing,
malformed timestamps, unsupported resolution, or misaligned boundaries).
tags:
- HEM Systems
responses:
'200':
description: Returns aggregated energy statistics for the HEM system.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/HEMSystemEnergyStatsResponse'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-hem_systems-hem_system_id-energy_stats
parameters:
- name: start
in: query
required: true
schema:
type: string
format: date-time
example: '2024-06-01T00:00:00Z'
description: >-
Start of time range (ISO 8601 with timezone, e.g.
2024-06-01T00:00:00Z or 2024-05-31T23:00:00+01:00). Must be aligned
to the resolution in the HEM system's timezone: :00 or :30 for
PT30M, midnight for P1D, 1st of month at midnight for P1M.
- name: end
in: query
required: true
schema:
type: string
format: date-time
example: '2024-07-01T00:00:00Z'
description: >-
End of time range (ISO 8601 with timezone, e.g. 2024-07-01T00:00:00Z
or 2024-06-30T23:00:00+01:00). Must be aligned to the resolution in
the HEM system's timezone: :00 or :30 for PT30M, midnight for P1D,
1st of month at midnight for P1M.
- name: resolution
in: query
required: true
schema:
type: string
enum:
- PT30M
- P1D
- P1M
example: P1D
description: >-
Aggregation resolution: PT30M (30 minutes, max 24h window), P1D (1
day, max 31 days), or P1M (1 month, max 366 days).
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- home_energy:read
/hem_systems/{hem_system_id}/live_power:
parameters:
- schema:
type: string
name: hem_system_id
in: path
required: true
description: The ID of the specific HEM system.
get:
summary: Get live power data for a HEM system
description: >-
Returns live power data for the HEM system. Power values (in watts) are
derived from the most recent energy statistics, including raw
measurements and calculated power flows between sources (solar, battery,
grid) and destinations (home, battery, grid).
tags:
- HEM Systems
responses:
'200':
description: Returns live power data for the HEM system.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/HEMSystemLivePower'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-hem_systems-hem_system_id-live_power
parameters:
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- home_energy:read
/boundary_meter_makes:
get:
summary: List boundary meter makes
tags:
- Boundary Meters
responses:
'200':
description: Return a list of Boundary Meter Makes.
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BoundaryMeterMake'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-boundary_meter_makes
description: List all the boundary meter makes known by the ev.energy system.
security:
- oauth2:
- boundary_meter:read
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
/boundary_meter_makes/{boundary_meter_make_id}:
parameters:
- schema:
type: string
name: boundary_meter_make_id
in: path
required: true
description: The ID of the specific boundary meter make to retrieve.
get:
summary: Retrieve a boundary meter make
tags:
- Boundary Meters
responses:
'200':
description: Return a single boundary meter make.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/BoundaryMeterMake'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-boundary_meter_makes-boundary_meter_make_id
description: Retrieve details for a single, specific boundary meter make.
security:
- oauth2:
- boundary_meter:read
parameters:
- $ref: '#/components/parameters/version-2'
/boundary_meter_models:
get:
summary: List boundary meter models
tags:
- Boundary Meters
responses:
'200':
description: Returns a list of boundary meter models.
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BoundaryMeterModel'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-boundary_meter_models
description: List all the boundary meter models known by the ev.energy system.
security:
- oauth2:
- boundary_meter:read
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/expand-on-boundarymetermodel'
- $ref: '#/components/parameters/boundary_meter_make_id_q'
/boundary_meter_models/{boundary_meter_model_id}:
parameters:
- schema:
type: string
name: boundary_meter_model_id
in: path
required: true
description: The ID of the specific boundary meter model to retrieve.
get:
summary: Retrieve a boundary meter model
tags:
- Boundary Meters
responses:
'200':
description: Return a single boundary meter model.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/BoundaryMeterModel'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-boundary_meter_models-boundary_meter_model_id
description: Retrieve details for a single, specific boundary meter model.
security:
- oauth2:
- boundary_meter:read
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/expand-on-boundarymetermodel'
/boundary_meters:
get:
summary: List boundary meters
tags:
- Boundary Meters
responses:
'200':
description: Returns a list of boundary meters.
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BoundaryMeter'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-boundary_meters
description: List all the boundary meters that the authorization token has access to.
security:
- oauth2:
- boundary_meter:read
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/user'
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/expand-on-boundarymeter'
/boundary_meters/{boundary_meter_id}:
parameters:
- schema:
type: string
name: boundary_meter_id
in: path
required: true
description: The ID of the specific Boundary Meter to retrieve.
get:
summary: Retrieve a boundary meter
tags:
- Boundary Meters
responses:
'200':
description: Returns a single boundary meter.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/BoundaryMeter'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-boundary_meters-boundary_meter_id
description: Retrieve a single, specific boundary meter's details.
security:
- oauth2:
- boundary_meter:read
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/user'
- $ref: '#/components/parameters/expand-on-boundarymeter'
/boundary_meters/{boundary_meter_id}/status_logs:
parameters:
- schema:
type: string
name: boundary_meter_id
in: path
required: true
description: The ID of the specific Boundary Meter to retrieve status logs for.
get:
summary: List status logs for a boundary meter
description: >-
List the historical status logs for a specific boundary meter. Used to
find out the state of the meter at each point it reported in to
ev.energy.
tags:
- Boundary Meters
responses:
'200':
description: >-
List all status logs for a specific boundary meter, sorted newest
first.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BoundaryMeterStatusLog'
headers:
Link:
$ref: '#/components/headers/link-timestamps'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-boundary_meters-boundary_meter_id-status_logs
parameters:
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/sampled_at__gte'
- $ref: '#/components/parameters/sampled_at__lte'
- $ref: '#/components/parameters/expand-on-boundarymeterstatuslog'
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- boundary_meter:read
/boundary_meters/{boundary_meter_id}/status_logs/{sampled_at}:
parameters:
- schema:
type: string
name: boundary_meter_id
in: path
required: true
description: The ID of the specific Boundary Meter.
- schema:
type: string
format: date-time
name: sampled_at
in: path
required: true
description: The time the log's data was recorded on the device.
example: '2024-04-17T09:39:45.984584Z'
get:
summary: Retrieve a status log for a boundary meter
description: >-
A boundary meter status log is uniquely identified by the combination of
boundary meter ID and the time it was sampled at.
tags:
- Boundary Meters
responses:
'200':
description: Retrieve a single status log for a specific boundary meter.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/BoundaryMeterStatusLog'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-boundary_meters-boundary_meter_id-status_logs-timestamp
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/expand-on-boundarymeterstatuslog'
security:
- oauth2:
- boundary_meter:read
/inverter_onboarding:
get:
summary: Allows a user to authenticate with their inverter account.
tags:
- Solar
responses:
'302':
description: Found
'400':
description: Bad Request
'404':
description: Not Found
operationId: get-inverter_onboarding
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/Accept-Language'
- $ref: '#/components/parameters/user_id_onboarding'
- schema:
type: string
in: query
name: make_id
description: The make ID for the inverter that is going to be onboarded.
- schema:
type: string
in: query
name: inverter_id
description: The ID for the inverter that is going to be onboarded.
- $ref: '#/components/parameters/client_id'
description: >-
This endpoint will redirect to a web page that a user can use to login
into their inverter account.
This should be visited in a web browser as it contains interactive UI
elements.
/rebate_types:
get:
summary: List Rebate Types
tags:
- Rebates
responses:
'200':
description: Return a list of rebate types.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/RebateType'
examples:
Example 1:
value:
- $ref: '#/components/examples/RebateType'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-rebate_types
x-internal: true
description: Retrieve a list of rebate types available to the user.
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/expand-on-rebatetype'
/rebate_types/{rebate_type_id}:
parameters:
- schema:
type: string
example: rbttB1USP6YGD1VPIDJSHTZARUX11M
pattern: rbtt[A-Z\d]{26}
name: rebate_type_id
in: path
required: true
description: ID of the requested rebate type
get:
summary: Retrieve rebate type
tags:
- Rebates
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
$ref: '#/components/schemas/RebateType'
examples:
Example 1:
$ref: '#/components/examples/RebateType'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-rebate_types-rebate_type_id
x-internal: true
description: Retrieve a specific rebate type by id.
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/Accept-Language'
- $ref: '#/components/parameters/expand-on-rebatetype'
/rebate_evidence_types:
get:
summary: List Rebate Evidence Types
tags:
- Rebates
responses:
'200':
description: Return a list of rebate evidence types.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/RebateEvidenceType'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-rebate_evidence_types
description: Retrieve a list of rebate types available to the user.
parameters:
- $ref: '#/components/parameters/version-2'
/rebate_evidence_types/{rebate_evidence_type_id}:
parameters:
- schema:
type: string
example: rbetB1USP6YGD1VPIDJSHTZARUX11M
pattern: rbet[A-Z\d]{26}
name: rebate_evidence_type_id
in: path
required: true
description: ID of the requested rebate evidence type
get:
summary: Retrieve rebate evidence type
tags:
- Rebates
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
$ref: '#/components/schemas/RebateEvidenceType'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-rebate_types-rebate_evidence_type_id
x-internal: true
description: Retrieve a specific rebate evidence type by id.
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/Accept-Language'
/user_rebates:
post:
summary: Create rebate application
tags:
- Rebates
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/UserRebateCreated'
examples:
Example 1:
value:
id: rbtuB1USP6YGD1VPIDJSHTZARUX11M
url: >-
https://api.ev.energy/v2/user_rebates/rbtuB1USP6YGD1VPIDJSHTZARUX11M
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: post-rebates
x-internal: true
description: Creates a rebate application, returning the application ID.
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/user'
requestBody:
content:
application/json:
schema:
type: object
required:
- rebate_type
properties:
rebate_type:
type: string
description: Rebate type resource uri
example: >-
https://api.ev.energy/v2/rebate_types/rbttB1USP6YGD1VPIDJSHTZARUX11M
get:
summary: List rebate applications
tags:
- Rebates
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/UserRebate'
examples:
Example 1:
value:
- $ref: '#/components/examples/UserRebate'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-rebates
x-internal: true
description: Lists all a user's rebate applications.
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/expand-on-userrebate'
- $ref: '#/components/parameters/user'
/user_rebates/{user_rebate_id}:
parameters:
- $ref: '#/components/parameters/user_rebate_id'
get:
summary: Retrieve rebate application
tags:
- Rebates
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
$ref: '#/components/schemas/UserRebate'
examples:
Example 1:
value:
$ref: '#/components/examples/UserRebate'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-rebates-application_id
description: Retrieve a specific rebate application.
parameters:
- $ref: '#/components/parameters/expand-on-userrebate'
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/user'
patch:
summary: Update rebate application
tags:
- Rebates
responses:
'200':
description: OK
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: object
x-examples:
Example 1:
id: str
url: str
properties:
id:
type: string
description: uid of the user_rebate
url:
type: string
description: url of the user_rebate
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: patch-user_rebates-application_id
description: Attach evidence to a rebate application.
requestBody:
content:
application/json:
schema:
type: object
required:
- rebate_type
- evidence_type
- evidence_data
properties:
rebate_type:
type: string
description: Rebate type resource uri
evidence_type:
type: string
description: Rebate evidence type resource uri
evidence_data:
type: array
items:
type: object
required:
- id
- value
properties:
id:
type: number
description: Rebate evidence supporting data id
value:
type: string
description: Form field value. Should not include currency symbol.
examples:
Example 1:
value:
rebate_type: >-
https://api.ev.energy/v2/user_rebates/rbtuB1USP6YGD1VPIDJSHTZARUX11M
evidence_type: >-
https://api.ev.energy/v2/user_rebates/rbetB1USP6YGD1VPIDJSHTZARUX11M
evidence_data:
- id: 2
value: '1000'
description: ''
parameters:
- $ref: '#/components/parameters/expand-on-userrebate'
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/user'
/user_rebates/{user_rebate_id}:submit:
parameters:
- $ref: '#/components/parameters/user_rebate_id'
post:
summary: Submit a completed rebate form
tags:
- Rebates
responses:
'200':
description: OK
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: post-user_rebates-application_id-:submit
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/user'
description: >-
Once all evidence data and files have been uploaded, this endpoint is
called to submit the rebate application for review by updating the Form
status to "complete" and the application status to "pending_review".
/rebate_evidence_files:start_upload:
parameters:
- schema:
type: string
in: query
name: user_rebate
description: Application ID (uid) of the user_reabte
post:
summary: Start a file upload
tags:
- Rebates
responses:
'201':
description: Created
content:
application/json:
schema:
type: object
x-examples:
Example 1:
url: >-
https://api.ev.energy/v2/user_rebate_evidence_files/rbef1USP6YGD1VPIDJSHTZARUX11M
presigned_url: >-
https://cdn.app.ev.energy/evenergy-development-rebates-evidence-files/user_rebates/rbtuB1USP6YGD1VPIDJSHTZARUX11M/test_file-28a71d30552241a989cced058eaff01b.pdf?AWSAccessKeyId=DummyKeyID&Signature=Vq2tiQhuBb1%2FOEdv9fH9eFyMOw8%3D&Expires=1732224132
properties:
id:
type: string
description: evidence file uid
url:
type: string
description: evidence file resource url
presigned_url:
type: string
description: >-
AWS S3 presigned URL. This URL is required for the client
to send direct PUT or GET requests to S3
examples:
Example 1:
$ref: '#/components/examples/RebateEvidenceUploadStart'
'400':
$ref: '#/components/responses/Problem400BadRequestCreate'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: post-rebate-evidence_files:start_upload
description: >-
This endpoint creates the RebateEvidenceFile record and returns its uid
as well as a presigned URL to use for direct upload to AWS S3.
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/user'
requestBody:
description: Details of the file to be directly uploaded
content:
application/json:
schema:
type: object
properties:
file_name:
type: string
description: Original file name of the incoming file, with extention.
rebate_evidence_type:
type: string
description: Rebate evidence type url
x-examples:
Example 1:
file_name: wiring_invoice.pdf
rebate_evidence_type: >-
https://api.ev.energy/v2/rebate_evidence_type/rbefB1USP6YGD1VPIDJSHTZARUX11M
/rebate_evidence_files/{rebate_evidence_file_id}:finish_upload:
post:
summary: Finalize File Upload
tags:
- Rebates
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: Rebate evidence file uid
url:
type: string
description: Rebate evidence file resource url
x-examples:
Example 1:
id: rbefB1USP6YGD1VPIDJSHTZARUX11M
url: >-
https://api.ev.energy/v2/rebate_evidence_files/rbefB1USP6YGD1VPIDJSHTZARUX11M
examples:
Example 1:
value:
id: rbefB1USP6YGD1VPIDJSHTZARUX11M
url: >-
https://api.ev.energy/v2/rebate_evidence_files/rbefB1USP6YGD1VPIDJSHTZARUX11M
'400':
$ref: '#/components/responses/Problem400BadRequestCreate'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: post-rebate-evidence_files-evidence_file_id-:finish_upload
description: >-
After the file is successfully uploaded to S3 via the presigned URL,
this endpoint is called to set the upload_finished_at timestamp on the
evidence_file record.
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/user'
parameters:
- $ref: '#/components/parameters/rebate_evidence_file_id'
/regions:
get:
summary: List regions
tags:
- Regions
operationId: get-regions
description: >-
List the regions created by your organisation (geometry omitted —
retrieve a single region for its GeoJSON boundary).
security:
- oauth2:
- region:read
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- schema:
type: string
in: query
name: name
description: Exact region name.
- schema:
type: string
in: query
name: name__in
description: Comma-separated list of exact region names.
- schema:
type: string
pattern: rgrp[A-Z\d]{26}
in: query
name: region_group_id
description: Only regions belonging to this region group (uid).
- schema:
type: string
enum:
- OTHER
- ELECTRICITY
in: query
name: type
- schema:
type: string
pattern: >-
^[-+]?([1-8]?\d(\.\d+)?|90(\.0+)?),\s*[-+]?(180(\.0+)?|((1[0-7]\d)|([1-9]?\d))(\.\d+)?)$
example: 42.2793,-71.1631
in: query
name: contains
description: >-
latitude,longitude — only regions strictly containing this point (a
point exactly on a region's boundary does not match).
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Region'
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
post:
summary: Create region
tags:
- Regions
operationId: post-regions
description: >-
Create a single region. The submitted geometries are unioned server-side
into one MultiPolygon. Region names are unique across all organisations:
a name clash returns 409 with the existing region's URL — there is no
upsert, and regions cannot be replaced via the API. The creating
application must be linked to an organisation (creation is attributed to
it, and only that organisation can read the region afterwards) —
otherwise 403. Linked region_groups must belong to your organisation.
security:
- oauth2:
- region:write
parameters:
- $ref: '#/components/parameters/version-2'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RegionCreate'
responses:
'201':
description: Region created.
content:
application/json:
schema:
$ref: '#/components/schemas/RegionDetail'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
'400':
$ref: '#/components/responses/Problem400BadRequestCreate'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'409':
description: >-
A region with this name already exists (problem type
region-name-conflict; extension member `conflicts` lists the
clashing name and existing region URL). Nothing was written.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/RFC9457ProblemDetail'
'413':
description: >-
Request body exceeds the 20 MB limit (problem type
payload-too-large).
content:
application/problem+json:
schema:
$ref: '#/components/schemas/RFC9457ProblemDetail'
'422':
description: >-
Validation failed — malformed GeoJSON, geometry not repairable by
make_valid (problem type invalid-geometry, naming the region), or
field validation errors (problem type validation-failed-regions).
content:
application/problem+json:
schema:
$ref: '#/components/schemas/RFC9457ProblemDetail'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
/regions/{region_id}:
parameters:
- schema:
type: string
pattern: regn[A-Z\d]{26}
name: region_id
in: path
required: true
get:
summary: Retrieve region
tags:
- Regions
operationId: get-regions-region_id
description: >-
Retrieve a single region created by your organisation, including its
full GeoJSON MultiPolygon geometry.
security:
- oauth2:
- region:read
parameters:
- $ref: '#/components/parameters/version-2'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RegionDetail'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
/region_groups:
get:
summary: List region groups
tags:
- Regions
operationId: get-region_groups
description: List the region groups created by your organisation.
security:
- oauth2:
- region:read
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- schema:
type: string
in: query
name: name
description: Exact group name.
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/RegionGroup'
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
post:
summary: Create region group
tags:
- Regions
operationId: post-region_groups
description: >-
Atomically create a region group together with its member regions. Names
are unique across all organisations, and every submitted region name
must be fresh — a clash with an existing region always fails the whole
request with 409; regions are never replaced or linked. Any failure
rolls the whole request back — nothing is partially written. Send the
identical body to POST /region_groups:validate first for a zero-write
preview. The creating application must be linked to an organisation
(creation is attributed to it, and only that organisation can read the
group and regions afterwards) — otherwise 403.
security:
- oauth2:
- region:write
parameters:
- $ref: '#/components/parameters/version-2'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RegionGroupCreate'
responses:
'201':
description: Group and regions created.
content:
application/json:
schema:
$ref: '#/components/schemas/RegionGroup'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
'400':
$ref: '#/components/responses/Problem400BadRequestCreate'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'409':
description: >-
Name conflict — either the group name is taken (problem type
region-group-name-conflict, extension member
`existing_region_group`) or one or more region entries clash with
existing regions (problem type region-name-conflict, extension
member `conflicts`). Includes clashes that appeared between
:validate and this commit. Nothing was written.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/RFC9457ProblemDetail'
'413':
description: >-
Request body exceeds the 20 MB limit (problem type
payload-too-large).
content:
application/problem+json:
schema:
$ref: '#/components/schemas/RFC9457ProblemDetail'
'422':
description: >-
Validation failed — unrepairable geometry (invalid-geometry, naming
the region), duplicate/empty names, more than 500 regions, or an
empty group (validation-failed-regions).
content:
application/problem+json:
schema:
$ref: '#/components/schemas/RFC9457ProblemDetail'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
/region_groups/{region_group_id}:
parameters:
- schema:
type: string
pattern: rgrp[A-Z\d]{26}
name: region_group_id
in: path
required: true
get:
summary: Retrieve region group
tags:
- Regions
operationId: get-region_groups-region_group_id
security:
- oauth2:
- region:read
parameters:
- $ref: '#/components/parameters/version-2'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RegionGroup'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
/region_groups:validate:
post:
summary: Validate a region group upload
tags:
- Regions
operationId: post-region_groups:validate
description: >-
Zero-write dry-run of POST /region_groups with the identical body.
Always returns 200 for content findings (name clashes, invalid geometry,
duplicate names) — the findings ARE the response. Clashing entries
include the existing region's URL; renaming the submitted region is the
only resolution — regions are never replaced or linked.
security:
- oauth2:
- region:write
parameters:
- $ref: '#/components/parameters/version-2'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RegionGroupCreate'
responses:
'200':
description: Validation findings. Zero writes occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/RegionGroupValidationResult'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
'400':
$ref: '#/components/responses/Problem400BadRequestCreate'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'413':
description: >-
Request body exceeds the 20 MB limit (problem type
payload-too-large).
content:
application/problem+json:
schema:
$ref: '#/components/schemas/RFC9457ProblemDetail'
'422':
description: >-
The body itself is malformed (missing name, wrong field types, more
than 500 regions). Content-level findings return 200 instead.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/RFC9457ProblemDetail'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
/rebate_evidence_files:
get:
summary: List rebate evidence files
tags:
- Rebates
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/RebateEvidenceFile'
readOnly: true
examples: {}
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-user_rebates-application_id-evidence_files
description: List all user's rebate evidence files
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/expand-on-rebateevidencefile'
- $ref: '#/components/parameters/user'
parameters:
- schema:
type: string
in: query
name: user_rebate
description: Application ID (uid) of the user_rebate
/rebate_evidence_files/{rebate_evidence_file_id}:
parameters:
- $ref: '#/components/parameters/rebate_evidence_file_id'
get:
summary: Retrieve rebate evidence file details
tags:
- Rebates
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
$ref: '#/components/schemas/RebateEvidenceFile'
examples:
Example 1:
$ref: '#/components/examples/RebateEvidenceFile'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-user_rebates-application_id-evidence_files-evidence_file_id
description: Retrieve the details of a specific rebate evidence file.
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/expand-on-rebateevidencefile'
- $ref: '#/components/parameters/user'
/programs:
get:
summary: List programs
tags:
- Programs
responses:
'200':
description: Returns 0 or more Programs.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Program'
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-programs
parameters:
- schema:
type: string
pattern: >-
^[-+]?([1-8]?\d(\.\d+)?|90(\.0+)?),\s*[-+]?(180(\.0+)?|((1[0-7]\d)|([1-9]?\d))(\.\d+)?)$
example: 50.896453,-1.4037239
in: query
name: coordinates
description: >-
Filter the returned programs to only those available to someone who
primarily charges their vehicles at these coordinates.
- schema:
type: string
example: SW1 1AA
in: query
name: postal_code
description: >-
Filter the returned programs to only those available to someone
someone who primarily charges their vehicles in this postal code
area. The postal code needs to be in the correct format for the
country specified by `country_code`.
- schema:
$ref: '#/components/schemas/CountryCode'
in: query
name: country_code
description: >-
Specify the country the postal code is within. Required if
postal_code is used.
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/user'
description: >
By default, this endpoint returns all programs in our system and does
not require authentication. The `coordinates`, `postal_code` and
`country_code` query parameters can be used to narrow the list down to
just programs eligible for particular locations. Coordinates and postal
code searching are mutually exclusive and mixing the query parameters
will result in a 400 error response.
If the client is authenticated as a specific user (either via
Authorisation Code grant type or the `EvEnergy-User` header) it will
return only programs that user is possibly eligible for, based on the
location information we have for them.
security: []
/programs/{program_id}:
parameters:
- $ref: '#/components/parameters/program_id'
get:
summary: Retrieve a program
tags:
- Programs
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
$ref: '#/components/schemas/Program'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-programs-program_id
description: Retrieve details for a single, specific program.
security: []
parameters:
- $ref: '#/components/parameters/version-2'
/incentive_schemes:
get:
summary: List incentive schemes
tags:
- Programs
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/IncentiveScheme'
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-incentive_schemes
description: >-
Returns a list of Incentive Schemes that the authenticated User is
eligble for.
parameters:
- $ref: '#/components/parameters/evenergy-user-required'
/evse_sites:
get:
summary: List EVSE Sites
tags:
- Sites
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/EVSESite'
readOnly: true
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-evse_sites
description: List all available EVSE Sites
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/user'
security:
- oauth2:
- site:read
/evse_sites/{evse_site_id}:
parameters:
- $ref: '#/components/parameters/evse_site_id'
get:
summary: Retrieve an EVSE Site
tags:
- Sites
responses:
'200':
description: Returns a single EVSE Site.
content:
application/json:
schema:
$ref: '#/components/schemas/EVSESite'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-evse_sites-evse_site_id
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/user'
description: Retrieve a single, specific EVSESite's details.
security:
- oauth2:
- site:read
/vehicles/{vehicle_id}/reconnect:
parameters:
- $ref: '#/components/parameters/vehicle_id'
post:
summary: Create reconnection URL
tags:
- Vehicles
responses:
'201':
description: Returns the newly generated reconnection URL and it's expiry time.
content:
application/json:
schema:
$ref: '#/components/schemas/VehicleReconnectionUrl'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestCreate'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: post-vehicles-vehicle_id-reconnect
description: Create a reconnection request URL for the Vehicle.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/VehicleReconnectionUrl'
/vehicles/{vehicle_id}/disconnect:
parameters:
- $ref: '#/components/parameters/vehicle_id'
post:
summary: Disconnect a vehicle's integration
tags:
- Vehicles
responses:
'200':
description: |-
The disconnection request was processed. Returns the updated
Vehicle resource reflecting its current state — `INACTIVE` if
the vehicle was previously integrated, or `UNINTEGRATED` if it
had no active integration to disconnect.
content:
application/json:
schema:
$ref: '#/components/schemas/Vehicle'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: post-vehicles-vehicle_id-disconnect
description: |-
Disconnect the vehicle's integration. Revokes provider OAuth tokens
and invalidates the underlying account, leaving the vehicle in an
`INACTIVE` state. Any open charging sessions on cars sharing the
account are closed. The vehicle's provider association is retained
so the user can re-link by POSTing to
`/vehicles/{vehicle_id}/reconnect`.
This action is idempotent — calling it on an unintegrated vehicle
is a no-op and still returns 200.
security:
- oauth2:
- vehicle:write
/programs/{program_id}/user_verification:
post:
summary: Verify user
tags:
- Programs
responses:
'201':
description: Created
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestCreate'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: post-programs-user-verification
description: >-
Upload a user's utility account information for verification and account
matching against the utility's customer data.
An endpoint to serve this data will be added in future.
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/user'
requestBody:
content:
application/json:
schema:
type: object
examples:
Account Number Only:
value:
account_number: 12345678-A
Account Number and SAID:
value:
account_number: '0987654321'
said: ABC-12345678
PIN:
value:
pin: abcde-12345
description: >-
The body must be a JSON object containing data required for user
verification. The exact dat requirements differ by program and will be
validated against a dynamic JSON schema, so no specific type is
defined here.
The examples are not exhaustive.
parameters:
- name: program_id
in: path
required: true
schema:
type: string
description: The ID of the specific Program to retrieve.
/programs/{program_id}/join:
post:
summary: Join program
tags:
- Programs
responses:
'201':
description: The user was enrolled in the program's default tier.
content:
application/json:
schema:
$ref: '#/components/schemas/Program'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestCreate'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: post-programs-program_id-join
description: |-
Enrol the authenticated user in this program's default tier.
If the user is already enrolled in a different program they will leave
it before joining this one. Re-joining a program the user is already in
returns the same program unchanged.
Returns `404` if the program does not exist or has no default tier
configured.
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/user'
security:
- oauth2:
- utility_account:write
parameters:
- $ref: '#/components/parameters/program_id'
/programs/{program_id}/tiers:
parameters:
- $ref: '#/components/parameters/program_id'
get:
summary: List program tiers
tags:
- Programs
description: >
List all selectable tiers under the given Program. Public read-only — no
authentication required. When the request is authenticated as a specific
user (Authorization Code grant, or Client Credentials with
`EvEnergy-User`),
each tier's `eligible` field is populated with the user's eligibility
result.
Anonymous or pure client-credentials requests receive `eligible: null`.
responses:
'200':
description: Returns 0 or more Program Tiers.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ProgramTier'
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-programs-program_id-tiers
parameters:
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/user'
security: []
/programs/{program_id}/tiers/{tier_id}:
parameters:
- $ref: '#/components/parameters/program_id'
- $ref: '#/components/parameters/tier_id'
get:
summary: Retrieve a program tier
tags:
- Programs
description: |
Retrieve a single tier nested under a Program. Public read-only. The
`eligible` field is per-user (see the list endpoint description).
responses:
'200':
description: Returns a single Program Tier.
content:
application/json:
schema:
$ref: '#/components/schemas/ProgramTier'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-programs-program_id-tiers-tier_id
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/user'
security: []
/programs/{program_id}/participation_agreement_versions:
parameters:
- $ref: '#/components/parameters/program_id'
get:
summary: List participation agreement versions
tags:
- Programs
description: >
List versions of the Participation Agreement attached to the given
Program.
Public read-only — no authentication required. Fetch the single
currently
active version from the `current` sub-resource.
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
responses:
'200':
description: Returns 0 or more Participation Agreement Versions.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ParticipationAgreementVersion'
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-programs-program_id-participation_agreement_versions
security: []
/programs/{program_id}/participation_agreement_versions/{participation_agreement_version_id}:
parameters:
- $ref: '#/components/parameters/program_id'
- $ref: '#/components/parameters/participation_agreement_version_id'
get:
summary: Retrieve a participation agreement version
tags:
- Programs
description: >
Retrieve a single Participation Agreement Version nested under a
Program.
Public read-only.
responses:
'200':
description: Returns a single Participation Agreement Version.
content:
application/json:
schema:
$ref: '#/components/schemas/ParticipationAgreementVersion'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-programs-program_id-participation_agreement_versions-id
parameters:
- $ref: '#/components/parameters/version-2'
security: []
/programs/{program_id}/participation_agreement_versions/current:
parameters:
- $ref: '#/components/parameters/program_id'
get:
summary: Retrieve the currently active participation agreement version
tags:
- Programs
description: |
Retrieve the currently active Participation Agreement Version — the
highest-numbered published version of the Program's agreement. `current`
is a magic value used in place of a version UID.
Public read-only. Returns `404` if the Program has no published version.
responses:
'200':
description: Returns the currently active Participation Agreement Version.
content:
application/json:
schema:
$ref: '#/components/schemas/ParticipationAgreementVersion'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-programs-program_id-participation_agreement_versions-current
parameters:
- $ref: '#/components/parameters/version-2'
security: []
/programs/{program_id}/participation_agreement_versions/{participation_agreement_version_id}/accept:
parameters:
- $ref: '#/components/parameters/program_id'
- $ref: '#/components/parameters/participation_agreement_version_id'
post:
summary: Accept a participation agreement version
tags:
- Programs
description: |
Record that the authenticated user has accepted the given Participation
Agreement Version, identified by its UID (e.g. the `id` returned by the
`current` sub-resource).
The request body must be an empty JSON object (`{}`). Sending any
additional fields returns `400 Bad Request`. The success response is
`201 Created` with no body. The acceptance is idempotent — repeating the
call for the same (user, version) pair returns 201 without creating a
duplicate acceptance record.
Requires a user-grant access token (Authorization Code or Password). The
endpoint is not exposed to Client Credentials clients because acceptance
is intrinsically a per-user action.
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: false
example: {}
responses:
'201':
description: The acceptance has been recorded.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestCreate'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: post-programs-program_id-participation_agreement_versions-id-accept
parameters:
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- programs:write
/programs/{program_id}/post-enrollment-verification:
post:
summary: Post-enrollment verification
tags:
- Programs
responses:
'201':
description: Created
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestCreate'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: post-programs-post-enrollment-verification
description: >-
Upload a user's post-enrollment verification data for account
verification.
This endpoint validates data against the program's post-enrollment
verification schema.
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/user'
requestBody:
content:
application/json:
schema:
type: object
examples:
Account Number Only:
value:
account_number: 12345678-A
description: >-
The body must be a JSON object containing data required for
post-enrollment verification. The exact data requirements differ by
program and will be validated against a dynamic JSON schema, so no
specific type is defined here.
parameters:
- name: program_id
in: path
required: true
schema:
type: string
description: The ID of the specific Program to retrieve.
/cpms_providers:
get:
summary: List CPMS Providers
description: >-
Get a list of all the ChargePoint Management System Providers that we
integrate with.
tags:
- Sites
responses:
'200':
description: OK
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CPMSProvider'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-cpms_providers
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
/cpms_providers/{cpms_provider_id}:
parameters:
- schema:
type: string
enum:
- CHARGEPOINT
name: cpms_provider_id
in: path
required: true
description: The ID of the specific provider to retrieve.
get:
summary: Retrieve a CPMS Provider
description: Get details on a single CPMS provider.
tags:
- Sites
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CPMSProvider'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-cpms_providers-provider_id
parameters:
- $ref: '#/components/parameters/version-2'
/timezones:
get:
summary: List Timezones
description: Get the list of available IANA timezones.
tags:
- Reference Data
responses:
'200':
description: OK
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Timezone'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-timezones
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
/timezones/{timezone_id}:
parameters:
- $ref: '#/components/parameters/timezone_id'
get:
summary: Retrieve a timezone
description: Retrieve a single timezone by its ID.
tags:
- Reference Data
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Timezone'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-timezones-timezone_id
parameters:
- $ref: '#/components/parameters/version-2'
/charging_sub_sessions/{charging_sub_session_id}/schedules:
parameters:
- $ref: '#/components/parameters/charging_sub_session_id'
get:
summary: Retrieve schedules for a charging sub-session
description: >-
Retrieve schedules for a specific charging sub-session.
Schedules represent charging instructions for a charging session. Each
schedule specifies a current (in milliamps) and a time period during
which that current should be applied.
tags:
- Charging Sessions
responses:
'200':
description: Returns information about a single charging sub-session's schedules.
content:
application/json:
schema:
$ref: '#/components/schemas/Schedules'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-charging_sub_sessions-charging_sub_session_id-schedules
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/expand-on-chargingsubsession-schedules'
- schema:
type: string
format: date-time
in: query
name: started_at__gte
description: >-
Filter schedules with started_at greater than or equal to this
datetime.
- schema:
type: string
format: date-time
in: query
name: started_at__lte
description: >-
Filter schedules with started_at less than or equal to this
datetime.
- schema:
type: string
pattern: scpl[A-Z\d]{26}
example: scpl01HSH04KDEWF6Z4DB2J77J74K5
in: query
name: schedule_plan_id
description: Filter schedules generated from a specific schedule plan.
- schema:
type: boolean
default: true
in: query
required: false
name: only_most_recently_created
description: Only show the most recently created schedule for each time period
security:
- oauth2:
- chargingsession:read
/charging_sub_sessions/{charging_sub_session_id}/schedule_plans:
parameters:
- $ref: '#/components/parameters/charging_sub_session_id'
get:
summary: Retrieve schedule plans for a charging sub-session
description: >-
Retrieve schedule plans for a specific charging sub-session.
Schedule plans represent the charging plan parameters used to generate
schedules for a charging session. Each plan contains information about
the ready-by time, charging requirements, and constraints that were used
to create the charging schedule.
tags:
- Charging Sessions
responses:
'200':
description: Returns schedule plans for a charging sub-session.
content:
application/json:
schema:
$ref: '#/components/schemas/SchedulePlans'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-charging_sub_sessions-charging_sub_session_id-schedule_plans
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/expand-on-chargingsubsession-scheduleplans'
- schema:
type: string
format: date-time
in: query
name: created_at__gte
description: >-
Filter schedule plans with created_at greater than or equal to this
datetime.
- schema:
type: string
format: date-time
in: query
name: created_at__lte
description: >-
Filter schedule plans with created_at less than or equal to this
datetime.
security:
- oauth2:
- debug:read
/charging_sub_sessions/{charging_sub_session_id}/assessment:
parameters:
- $ref: '#/components/parameters/charging_sub_session_id'
get:
summary: Retrieve assessment for a charging sub-session
description: >-
Retrieve the performance assessment for a specific charging sub-session.
The assessment contains performance metrics for completed charging
sessions, including energy delivery ratios, charge rates, and detailed
quality metrics.
tags:
- Charging Sessions
responses:
'200':
description: Returns the assessment for a charging sub-session.
content:
application/json:
schema:
$ref: '#/components/schemas/ChargingSubSessionAssessment'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-charging_sub_sessions-charging_sub_session_id-assessment
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/expand-on-chargingsubsession-assessment'
security:
- oauth2:
- debug:read
x-stoplight:
id: chargingsubsession-assessment-endpoint
/charging_sub_sessions/{charging_sub_session_id}/recalculate_energy_usages:
parameters:
- $ref: '#/components/parameters/charging_sub_session_id'
post:
summary: Recalculate energy usages for a charging sub-session
description: >
Triggers a recalculation of energy usages (and performance assessment)
for a completed
charging sub-session. Use `dry_run` to preview the recalculation without
persisting
changes, and `cap_overages` to control whether energy overages are
capped.
tags:
- Charging Sessions
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
dry_run:
type: boolean
default: false
description: >-
If true, the recalculation is simulated and no changes are
persisted.
cap_overages:
type: boolean
default: true
description: If true, energy overages are capped during recalculation.
responses:
'200':
description: >
Recalculation has been triggered (or simulated if `dry_run` was
true). The
response includes the total energy delivered for the session both
before and
after the recalculation so the caller can see the effect. When
`dry_run` is
true, `new_energy_delivered_watt_hours` reflects the prospective
value that
would result from the recalculation (no persistence).
content:
application/json:
schema:
type: object
required:
- status
- previous_energy_delivered_watt_hours
- new_energy_delivered_watt_hours
properties:
status:
type: string
enum:
- recalculation_triggered
- dry_run_completed
example: recalculation_triggered
previous_energy_delivered_watt_hours:
type: integer
description: >-
Total energy delivered for the session before the
recalculation, in watt-hours.
example: 3500
new_energy_delivered_watt_hours:
type: integer
description: >-
Total energy delivered for the session after the
recalculation, in watt-hours. When `dry_run` is true, this
is the prospective value that would result from
committing.
example: 4250
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: >-
post-charging_sub_sessions-charging_sub_session_id-recalculate_energy_usages
parameters:
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- charging_session:write
x-stoplight:
id: chargingsubsession-recalculate-energy-usages-endpoint
/dispatcher_logs:
get:
summary: List dispatcher logs
description: >-
List all dispatcher logs for a charging session. These logs record
Dispatch Command attempts to EVSEs or Vehicles.
tags:
- Charging Sessions
responses:
'200':
description: Returns a list of dispatcher logs, sorted newest first.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DispatcherLog'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-dispatcher_logs
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/expand-on-dispatcherlog'
- name: charging_sub_session_id
in: query
required: true
schema:
type: string
pattern: csub[A-Z\d]{26}
example: csub01HSH04KDEWF6Z4DB2J77J74K5
description: Filter dispatcher logs to a specific charging sub-session.
- schema:
type: string
format: date-time
in: query
name: logged_at__gte
description: Only return logs that were logged at or after the passed date.
- schema:
type: string
format: date-time
in: query
name: logged_at__lte
description: Only return logs that were logged at or before the passed date.
security:
- oauth2:
- debug:read
/dispatch_coordinators:
get:
summary: List dispatch coordinators
description: List all available dispatch coordinators.
tags:
- VPP
responses:
'200':
description: Returns a list of dispatch coordinators.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DispatchCoordinator'
headers:
Link:
$ref: '#/components/headers/link'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-dispatch_coordinators
parameters:
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/user'
security:
- oauth2:
- dispatch_coordinator:read
/dispatch_coordinators/{dispatch_coordinator_id}:
parameters:
- $ref: '#/components/parameters/dispatch_coordinator_id'
get:
summary: Retrieve a dispatch coordinator
description: Retrieve a single dispatch coordinator's details.
tags:
- VPP
responses:
'200':
description: Returns a single dispatch coordinator.
content:
application/json:
schema:
$ref: '#/components/schemas/DispatchCoordinator'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-dispatch_coordinators-dispatch_coordinator_id
parameters:
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- dispatch_coordinator:read
/dispatch_coordinators/{dispatch_coordinator_id}/dispatch_events:
parameters:
- $ref: '#/components/parameters/dispatch_coordinator_id'
post:
summary: Create a dispatch event
description: >-
Create a dispatch event for a dispatch coordinator. This is a
placeholder endpoint — the event is validated and returned but not
persisted.
tags:
- VPP
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DispatchEventWrite'
responses:
'201':
description: Returns the created dispatch event.
content:
application/json:
schema:
$ref: '#/components/schemas/DispatchEvent'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: post-dispatch_coordinators-dispatch_coordinator_id-dispatch_events
parameters:
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- dispatch_event:write
/dispatch_coordinators/{dispatch_coordinator_id}/dispatch_events/{dispatch_event_id}/cancel:
parameters:
- $ref: '#/components/parameters/dispatch_coordinator_id'
- $ref: '#/components/parameters/dispatch_event_id'
post:
summary: Cancel a dispatch event
description: Cancel a dispatch event to stop an active or scheduled dispatch.
tags:
- VPP
responses:
'200':
description: The dispatch event cancellation was accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/DispatchEventCancelResponse'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: >-
post-dispatch_coordinators-dispatch_coordinator_id-dispatch_events-dispatch_event_id-cancel
parameters:
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- dispatch_event:write
/dispatch_coordinators/{dispatch_coordinator_id}/dispatch_logs:
parameters:
- $ref: '#/components/parameters/dispatch_coordinator_id'
get:
summary: List dispatch logs for a coordinator
description: >-
List the historical dispatch logs for a specific dispatch coordinator.
These logs record aggregate fleet charging power at a point in time.
tags:
- VPP
responses:
'200':
description: >-
List all the dispatch logs for a specific dispatch coordinator,
sorted newest first.
headers:
Link:
$ref: '#/components/headers/link-timestamps'
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DispatchLog'
'400':
$ref: '#/components/responses/Problem400BadRequestList'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: get-dispatch_coordinators-dispatch_coordinator_id-dispatch_logs
parameters:
- $ref: '#/components/parameters/version-2'
- $ref: '#/components/parameters/previous'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/logged_at__gte'
- $ref: '#/components/parameters/logged_at__lte'
security:
- oauth2:
- dispatch_coordinator:read
/dispatch_coordinators/{dispatch_coordinator_id}/dispatch_logs/{logged_at}:
parameters:
- $ref: '#/components/parameters/dispatch_coordinator_id'
- schema:
type: string
format: date-time
name: logged_at
in: path
required: true
description: The time the dispatch log was recorded.
example: '2025-03-01T10:00:00Z'
get:
summary: Retrieve a specific dispatch log for a coordinator
description: >-
A single dispatch log for a particular dispatch coordinator is uniquely
identified by the timestamp it was logged at.
tags:
- VPP
responses:
'200':
description: Returns the dispatch log recorded at a specific time.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
content:
application/json:
schema:
$ref: '#/components/schemas/DispatchLog'
'400':
$ref: '#/components/responses/Problem400BadRequestRetrieve'
'401':
$ref: '#/components/responses/Problem401Unauthorized'
'403':
$ref: '#/components/responses/Problem403Forbidden'
'404':
$ref: '#/components/responses/Problem404NotFound'
'406':
$ref: '#/components/responses/Problem406NotAcceptable'
'429':
$ref: '#/components/responses/Problem429TooManyRequests'
operationId: >-
get-dispatch_coordinators-dispatch_coordinator_id-dispatch_logs-timestamp
parameters:
- $ref: '#/components/parameters/version-2'
security:
- oauth2:
- dispatch_coordinator:read
webhooks:
charging_sub_session.created:
post:
summary: Charging sub-session created
description: >-
A charging sub-session is created, representing a period of charging in
a single mode.
tags:
- Charging Sessions
parameters:
- name: svix-event-type
in: header
required: true
description: >-
The event type for this webhook, always
`charging_sub_session.created` for this endpoint. This matches the
`type` field in the body envelope, so you can route on the header
without parsing the body.
schema:
type: string
enum:
- charging_sub_session.created
- $ref: '#/components/parameters/svix-id'
- $ref: '#/components/parameters/svix-timestamp'
- $ref: '#/components/parameters/svix-signature'
requestBody:
description: >-
A `{type, timestamp, data}` envelope. `data` is the created charging
sub-session resource, in exactly the same format returned by `GET
/v2/charging_sub_sessions/{id}`. The event type is also delivered in
the `svix-event-type` header.
content:
application/json:
schema:
$ref: '#/components/schemas/ChargingSubSessionCreatedWebhook'
responses:
'200':
description: >-
Return a 200 status to indicate that the data was received
successfully.
charging_sub_session.ended:
post:
summary: Charging sub-session ended
description: >-
A charging sub-session has ended, representing a period of charging in a
single mode.
tags:
- Charging Sessions
parameters:
- name: svix-event-type
in: header
required: true
description: >-
The event type for this webhook, always `charging_sub_session.ended`
for this endpoint. This matches the `type` field in the body
envelope, so you can route on the header without parsing the body.
schema:
type: string
enum:
- charging_sub_session.ended
- $ref: '#/components/parameters/svix-id'
- $ref: '#/components/parameters/svix-timestamp'
- $ref: '#/components/parameters/svix-signature'
requestBody:
description: >-
A `{type, timestamp, data}` envelope. `data` is the ended charging
sub-session resource, in exactly the same format returned by `GET
/v2/charging_sub_sessions/{id}`. The event type is also delivered in
the `svix-event-type` header.
content:
application/json:
schema:
$ref: '#/components/schemas/ChargingSubSessionEndedWebhook'
responses:
'200':
description: >-
Return a 200 status to indicate that the data was received
successfully.
components:
schemas:
User:
title: User
description: A resource that represents an individual user in the ev.energy system.
type: object
x-tags:
- Users
required:
- id
- url
properties:
id:
type: string
description: Unique identifier for the given user.
pattern: user[A-Z\d]{26}
example: user01HN2NJ9NMRZBXT1H6FT9N7735
readOnly: true
url:
type: string
example: https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735
format: uri
readOnly: true
email:
type: string
format: email
full_name:
type: string
readOnly: true
description: The user's full name.
example: Frodo Baggins
joined_at:
type: string
format: date-time
readOnly: true
description: The date and time when the user joined the platform.
example: '2023-06-15T10:00:00Z'
terms_consent_datetime:
type:
- string
- 'null'
format: date-time
readOnly: true
description: >-
When the user gave their terms and conditions consent, or null if
they have not.
example: '2023-06-15T10:00:00Z'
default_location:
anyOf:
- $ref: '#/components/schemas/Location'
- $ref: '#/components/schemas/LocationDetail'
description: >-
LocationDetail is served when a single user is requested, otherwise
Location is served for user lists.
vehicles:
type: array
items:
type: string
format: uri
example: https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H
readOnly: true
readOnly: true
evses:
type: array
items:
type: string
format: uri
example: https://api.ev.energy/v2/evses/evse01HSH04XHZCT92RN018F0236ZM
readOnly: true
readOnly: true
VehicleConnectors:
title: VehicleConnectors
description: A vehicle's DC-fast charging connectors (native plug + adapters).
type: object
x-tags:
- Vehicles
required:
- url
- vehicle
- native_connector
- adaptors
- updated_at
properties:
url:
type: string
format: uri
readOnly: true
example: >-
https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H/connectors
vehicle:
type: string
format: uri
readOnly: true
example: https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H
native_connector:
type:
- string
- 'null'
enum:
- CCS
- NACS
- CHADEMO
- null
description: |-
The vehicle's built-in DC-fast plug. A per-vehicle override, falling
back to the model's default connector when unset; null when not yet
known.
adaptors:
type: array
items:
type: string
enum:
- CCS
- NACS
- CHADEMO
description: Additional connectors usable via an adapter. Empty when none.
updated_at:
type:
- string
- 'null'
format: date-time
readOnly: true
VehicleConnectorsUpdate:
title: VehicleConnectorsUpdate
description: Request body for `PATCH /vehicles/{vehicle_id}/connectors`.
type: object
properties:
native_connector:
type:
- string
- 'null'
enum:
- CCS
- NACS
- CHADEMO
- null
adaptors:
type: array
items:
type: string
enum:
- CCS
- NACS
- CHADEMO
VehicleStateOfCharge:
title: VehicleStateOfCharge
description: A vehicle's current battery state of charge.
type: object
x-tags:
- Vehicles
required:
- url
- vehicle
- state_of_charge_percentage
- source
- updated_at
properties:
url:
type: string
format: uri
readOnly: true
example: >-
https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H/state_of_charge
vehicle:
type: string
format: uri
readOnly: true
example: https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H
state_of_charge_percentage:
type:
- integer
- 'null'
minimum: 0
maximum: 100
description: Current battery percentage. Null when unknown.
source:
type:
- string
- 'null'
enum:
- MANUAL
- CONNECTED
- null
readOnly: true
description: |-
Where the current value came from: MANUAL (driver-entered) or
CONNECTED (vehicle telemetry). Null when no value is available.
updated_at:
type:
- string
- 'null'
format: date-time
readOnly: true
VehicleStateOfChargeUpdate:
title: VehicleStateOfChargeUpdate
description: Request body for `PATCH /vehicles/{vehicle_id}/state_of_charge`.
type: object
properties:
state_of_charge_percentage:
type:
- integer
- 'null'
minimum: 0
maximum: 100
UserNotificationPreferences:
title: UserNotificationPreferences
description: |-
The user's notification group opt-in state.
On `GET`, every known group is returned with its current boolean state.
On `PATCH`, only the keys you include are modified; omitted keys are
left untouched. `PATCH {}` and `PATCH {"groups": {}}` are valid no-ops.
Unknown group names produce a `400`.
type: object
x-tags:
- Users
properties:
url:
type: string
format: uri
readOnly: true
example: >-
https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735/notification_preferences
groups:
type: object
description: >-
Map of notification group name to opt-in state. Each group
corresponds to a category of push/email notifications:
- `charging_flow` — session lifecycle updates (plug-in, schedule,
complete).
- `charging_issues` — errors and failures during a charging session.
- `charging_optimisation` — smart-charging schedule and savings
updates.
- `deals_and_offers` — marketing offers (subject to the user's
marketing consent).
- `power_supply_notifications` — grid / power-supply events
(feature-flagged).
additionalProperties: false
properties:
charging_flow:
type: boolean
charging_issues:
type: boolean
charging_optimisation:
type: boolean
deals_and_offers:
type: boolean
power_supply_notifications:
type: boolean
example:
charging_flow: true
charging_issues: true
charging_optimisation: false
deals_and_offers: false
power_supply_notifications: false
RoutePlannerPreferences:
title: RoutePlannerPreferences
description: |-
A user's sticky EV Route Planner preferences, created with defaults on
first access. `PATCH` treats the body as a partial map — only the keys
you include are changed.
type: object
x-tags:
- Users
required:
- url
- preferred_vehicle
- min_charger_power_watts
- arrive_with_min_percent
- updated_at
properties:
url:
type: string
format: uri
readOnly: true
example: >-
https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735/route_planner_preferences
preferred_vehicle:
type:
- string
- 'null'
format: uri
description: Link to the vehicle selected by default, or null if none is set.
example: https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H
min_charger_power_watts:
type:
- integer
- 'null'
enum:
- 22000
- 50000
- 100000
- 150000
- 250000
- null
description: |-
Soft minimum charger power (watts) for en-route charger search. Null
means all chargers.
arrive_with_min_percent:
type: integer
minimum: 0
maximum: 100
description: Default arrival battery floor seeded into new route plans.
updated_at:
type: string
format: date-time
readOnly: true
RoutePlannerPreferencesUpdate:
title: RoutePlannerPreferencesUpdate
description: |-
Request body for `PATCH /users/{user_id}/route_planner_preferences`.
All fields are optional; only those supplied are changed.
type: object
properties:
preferred_vehicle:
type:
- string
- 'null'
format: uri
description: Vehicle URL to set as default, or null to clear.
min_charger_power_watts:
type:
- integer
- 'null'
enum:
- 22000
- 50000
- 100000
- 150000
- 250000
- null
arrive_with_min_percent:
type: integer
minimum: 0
maximum: 100
PasswordResetRequest:
title: PasswordResetRequest
description: Request body for the password-reset endpoint.
type: object
required:
- email
properties:
email:
type: string
format: email
description: The email address of the account to send a reset link to.
PasswordResetResult:
title: PasswordResetResult
description: |-
Acknowledgement that the password reset request was accepted. The
same response is returned whether or not an account exists for the
supplied email.
type: object
required:
- status
properties:
status:
type: string
enum:
- password_reset_email_sent
EVSECompatibilityCheckResult:
title: EVSECompatibilityCheckResult
description: |-
Compatibility verdict for an `(EVSEModel, country)` pair. Returned
by `GET /evse_compatibility/check`.
type: object
required:
- compatible
- beta
- recommendation_rank
properties:
compatible:
type: boolean
description: True if the model is supported in the requested country.
beta:
type: boolean
description: |-
True if support is currently in early-access / beta. Always
present in the response; `false` when `compatible` is `false`.
recommendation_rank:
type:
- integer
- 'null'
minimum: 1
maximum: 10
description: |-
Priority of the EVSE make on the new device-selection screen.
Lower = higher priority (1 = top, 10 = lowest explicit value);
`null` means no rank set and should be treated as lower priority
than any explicit value. Always reflects the make's current
value, independent of `compatible`.
PayoutMethod:
title: PayoutMethod
description: |
The user's preferred payout method. All three fields are nullable when
no payout method has been set up. `receiver_type` and the format of
`receiver` are determined by `receiver_wallet`:
- `PAYPAL` → `receiver` is an email, `receiver_type` is `EMAIL`
- `VENMO` → `receiver` is a phone number, `receiver_type` is `PHONE`
- `BILL_CREDITS` → `receiver` is the user's billing account number
(may be empty), `receiver_type` is `ACCOUNT_NUMBER`
type: object
x-tags:
- Users
required:
- url
- receiver
- receiver_type
- receiver_wallet
properties:
url:
type: string
format: uri
readOnly: true
example: >-
https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735/payout_method
receiver:
type:
- string
- 'null'
description: |
The destination identifier for the payout (email for `PAYPAL`,
phone for `VENMO`, billing account number for `BILL_CREDITS`).
Null when no payout method has been set up.
example: alice@example.com
receiver_type:
type:
- string
- 'null'
enum:
- EMAIL
- PHONE
- ACCOUNT_NUMBER
- null
description: The semantic type of the `receiver` field. Server-derived.
readOnly: true
receiver_wallet:
type:
- string
- 'null'
enum:
- PAYPAL
- VENMO
- BILL_CREDITS
- null
description: Which payout wallet the user has selected. Null when none is set.
PayoutMethodUpdate:
title: PayoutMethodUpdate
description: |
Request body for `PATCH /users/{user_id}/payout_method`.
`receiver_wallet` is always required. For `PAYPAL` and `VENMO` the
client must also supply `receiver` (an email or phone respectively).
For `BILL_CREDITS`, `receiver` must not be supplied — it is derived
server-side from the user's linked billing account.
type: object
required:
- receiver_wallet
properties:
receiver:
type:
- string
- 'null'
maxLength: 254
description: |
Email when `receiver_wallet` is `PAYPAL`, phone when `VENMO`. Must
not be supplied when `receiver_wallet` is `BILL_CREDITS`.
example: alice@example.com
receiver_wallet:
type: string
enum:
- PAYPAL
- VENMO
- BILL_CREDITS
RoutePoint:
title: RoutePoint
type: object
description: A single geographic point on a saved route.
required:
- latitude
- longitude
- name
properties:
latitude:
type: number
format: float
minimum: -90
maximum: 90
longitude:
type: number
format: float
minimum: -180
maximum: 180
name:
type: string
maxLength: 100
SavedRoute:
title: SavedRoute
description: |
A user's saved route-planner route — a reusable origin/destination/
waypoints "recipe" plus planning preferences. It deliberately does not
store the resulting charging plan, projected state of charge, or weather
snapshots; those are recalculated on each re-plan.
type: object
x-tags:
- Users
required:
- id
- url
- user
- name
- favourite
- origin
- destination
- waypoints
- arrive_with_min_percent
- preferred_departure_minutes
- created_at
- last_used_at
properties:
id:
type: string
pattern: savr[A-Z\d]{26}
readOnly: true
example: savr01HRFF3SEVSCRAV9B3CHVDFN0H
url:
type: string
format: uri
readOnly: true
example: >-
https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735/saved_routes/savr01HRFF3SEVSCRAV9B3CHVDFN0H
user:
type: string
format: uri
readOnly: true
example: https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735
description: Link to the user who owns this route.
name:
type: string
maxLength: 200
description: User-supplied name for the route.
favourite:
type: boolean
origin:
$ref: '#/components/schemas/RoutePoint'
destination:
$ref: '#/components/schemas/RoutePoint'
waypoints:
type: array
maxItems: 25
description: Ordered intermediate stops. Empty when the route is direct.
items:
$ref: '#/components/schemas/RoutePoint'
arrive_with_min_percent:
type: integer
minimum: 0
maximum: 100
description: Target battery floor on arrival.
preferred_departure_minutes:
type:
- integer
- 'null'
minimum: 0
maximum: 1439
description: |
Preferred departure hint as an offset in minutes from midnight of
the day the route is re-planned. Null means "leave now".
created_at:
type: string
format: date-time
readOnly: true
last_used_at:
type: string
format: date-time
description: Bumped each time the route is re-planned.
SavedRouteCreate:
title: SavedRouteCreate
description: Request body for `POST /users/{user_id}/saved_routes`.
type: object
required:
- name
- origin
- destination
- arrive_with_min_percent
properties:
name:
type: string
maxLength: 200
favourite:
type: boolean
default: false
origin:
$ref: '#/components/schemas/RoutePoint'
destination:
$ref: '#/components/schemas/RoutePoint'
waypoints:
type: array
maxItems: 25
items:
$ref: '#/components/schemas/RoutePoint'
arrive_with_min_percent:
type: integer
minimum: 0
maximum: 100
preferred_departure_minutes:
type:
- integer
- 'null'
minimum: 0
maximum: 1439
last_used_at:
type: string
format: date-time
SavedRoutePatch:
title: SavedRoutePatch
description: |
Request body for `PATCH /users/{user_id}/saved_routes/{saved_route_id}`.
All fields are optional; only those supplied are changed.
type: object
properties:
name:
type: string
maxLength: 200
favourite:
type: boolean
origin:
$ref: '#/components/schemas/RoutePoint'
destination:
$ref: '#/components/schemas/RoutePoint'
waypoints:
type: array
maxItems: 25
items:
$ref: '#/components/schemas/RoutePoint'
arrive_with_min_percent:
type: integer
minimum: 0
maximum: 100
preferred_departure_minutes:
type:
- integer
- 'null'
minimum: 0
maximum: 1439
last_used_at:
type: string
format: date-time
VehicleModelConnector:
title: VehicleModelConnector
description: |
A vehicle model's DC-fast connector for one charging region. A model's
connector can differ by market, so each row records the connector (and
its provenance) for one region.
type: object
x-tags:
- Vehicles
required:
- url
- vehicle_model
- region
- connector_type
- source
- confidence
- verified_at
- updated_at
properties:
url:
type: string
format: uri
readOnly: true
example: >-
https://api.ev.energy/v2/vehicle_models/vmod01HRFF3SEVSCRAV9B3CHVDFN0H/connectors/NORTH_AMERICA
vehicle_model:
type: string
format: uri
readOnly: true
example: >-
https://api.ev.energy/v2/vehicle_models/vmod01HRFF3SEVSCRAV9B3CHVDFN0H
description: Link to the vehicle model this connector belongs to.
region:
type: string
enum:
- NORTH_AMERICA
- EUROPE
description: The charging region this connector applies in.
connector_type:
type: string
enum:
- CCS
- NACS
- CHADEMO
- GBT
description: The model's native DC-fast connector in this region.
source:
type:
- string
- 'null'
enum:
- EV_ENERGY
- CAR_API
- USER
- DVLA
- PROVIDER
- FLEET
- null
description: Provenance of this regional connector value.
confidence:
type:
- string
- 'null'
enum:
- HIGH
- MEDIUM
- LOW
- null
description: Curator confidence in this value.
verified_at:
type:
- string
- 'null'
format: date-time
description: When this value was last verified.
updated_at:
type: string
format: date-time
readOnly: true
VehicleModelConnectorCreate:
title: VehicleModelConnectorCreate
description: Request body for `POST /vehicle_models/{vehicle_model_id}/connectors`.
type: object
required:
- region
- connector_type
properties:
region:
type: string
enum:
- NORTH_AMERICA
- EUROPE
connector_type:
type: string
enum:
- CCS
- NACS
- CHADEMO
- GBT
source:
type:
- string
- 'null'
enum:
- EV_ENERGY
- CAR_API
- USER
- DVLA
- PROVIDER
- FLEET
- null
confidence:
type:
- string
- 'null'
enum:
- HIGH
- MEDIUM
- LOW
- null
verified_at:
type:
- string
- 'null'
format: date-time
VehicleModelConnectorPatch:
title: VehicleModelConnectorPatch
description: |
Request body for
`PATCH /vehicle_models/{vehicle_model_id}/connectors/{region}`. All
fields are optional; only those supplied are changed. `region` is the
key and cannot be changed.
type: object
properties:
connector_type:
type: string
enum:
- CCS
- NACS
- CHADEMO
- GBT
source:
type:
- string
- 'null'
enum:
- EV_ENERGY
- CAR_API
- USER
- DVLA
- PROVIDER
- FLEET
- null
confidence:
type:
- string
- 'null'
enum:
- HIGH
- MEDIUM
- LOW
- null
verified_at:
type:
- string
- 'null'
format: date-time
EVSE:
title: EVSE
description: >-
A resource that represents a single, physical piece of hardware for
supplying electricity to an electric vehicle.
type: object
x-tags:
- EVSEs
required:
- id
- url
- cpid
properties:
id:
type: string
description: Unique identifier for the given EVSE.
pattern: evse[A-Z\d]{26}
example: evse01HSH04KDEWF6Z4DB2J77J74K5
readOnly: true
url:
type: string
example: https://api.ev.energy/v2/evses/evse01HSH04KDEWF6Z4DB2J77J74K5
format: uri
readOnly: true
cpid:
type: string
description: >-
A unique identifier for the chargepoint. The format varies by
manufacturer and model.
example: SHIR100001
readOnly: true
model:
oneOf:
- type: string
format: uri
example: >-
https://api.ev.energy/v2/evse_models/emod01HS9A004X5TB5JCMHENB5Z446
- $ref: '#/components/schemas/EVSEModel'
readOnly: true
user:
example: https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735
oneOf:
- type: string
example: https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735
format: uri
- $ref: '#/components/schemas/User'
readOnly: true
latest_status_log:
example: >-
https://api.ev.energy/v2/evse/evse01HSH04KDEWF6Z4DB2J77J74K5/status_logs/2024-01-01T11:11:11.1111Z/
oneOf:
- type:
- string
- 'null'
example: >-
https://api.ev.energy/v2/evse/evse01HSH04KDEWF6Z4DB2J77J74K5/status_logs/2024-01-01T11:11:11.1111Z/
format: uri
- $ref: '#/components/schemas/EVSEStatusLog'
description: >-
An expandable reference to the most recent status log for this EVSE.
This can be requested or expanded to get the most accurate
information we have on the device's current status.
**Inferring reachability:** v2 deliberately does not expose a
discrete `online`/`offline` state on the EVSE resource — the
boundary is fuzzy and prone to misuse. To decide whether an EVSE is
currently reachable, expand `latest_status_log` (or fetch it
separately) and compare its `sampled_at` timestamp against your own
staleness threshold (for example: a charger silent for more than 15
minutes is likely unreachable).
readOnly: true
ct_clamp:
oneOf:
- type:
- string
- 'null'
format: uri
example: >-
https://api.ev.energy/v2/ct_clamps/ctcl01HSH04KDEWF6Z4DB2J77J74K5
- $ref: '#/components/schemas/CTClamp'
description: >-
An expandable reference to the CT clamp associated with this EVSE.
Will be null if no CT clamp is installed.
readOnly: true
lock_mode:
type:
- string
- 'null'
enum:
- UNLOCKED
- SMART
- LOCKED
- null
example: UNLOCKED
description: >-
Lock mode of the EVSE. ``UNLOCKED`` allows free charging, ``SMART``
only allows charging within smart-charging hours, ``LOCKED`` blocks
all charging.
readOnly: true
location:
type:
- object
- 'null'
properties:
latitude:
type: number
format: double
example: 51.5074
longitude:
type: number
format: double
example: -0.1278
required:
- latitude
- longitude
example:
latitude: 51.5074
longitude: -0.1278
description: >-
The geographic location of the EVSE as a latitude/longitude point.
**Why smart charging needs it:** the location tells ev.energy which
electricity grid the charger sits on, which drives the core
smart-charging decisions:
- **Carbon optimisation** — selects the local carbon-intensity feed
so charging is shifted to the lowest-carbon periods.
- **Timezone** — resolves the charger's timezone so time-of-day
charging schedules and tariff windows are applied in local time.
- **Programs and solar** — determines the eligible
grid/demand-response programs and the relevant solar forecast.
Without an accurate location the scheduler cannot reliably optimise
charging for cost and carbon.
**When it is set:** during commissioning, where the supplied
postcode/address is geocoded to a latitude/longitude (or, for
app-linked chargers, copied from the owner's home location). It can
be corrected later via `PATCH`. Null when the location has not yet
been determined.
lifecycle_state:
type:
- string
- 'null'
enum:
- CREATED_LINKED
- INSTALLED
- COMMISSIONED
- DECOMMISSIONED
- UNKNOWN
- PROBABLY_INSTALLED
- UNPAIRED
- PENDING
- ENROLLED
- null
example: COMMISSIONED
description: >-
The most recently recorded stage of the EVSE's onboarding lifecycle.
Null when no stage has been recorded for it yet, which is normal for
a charger that has only just been created.
readOnly: true
charging_sub_sessions:
type: string
format: uri
example: >-
https://api.ev.energy/charging_sub_sessions/?evse_id=evse01HSH04KDEWF6Z4DB2J77J74K5
description: >-
Provides a pre-constructed URL to list charging sub-sessions
involving this EVSE.
CTClamp:
title: CTClamp
description: >-
A CT (Current Transformer) clamp used to measure grid current, typically
for solar charging logic.
type: object
x-tags:
- CT Clamps
properties:
id:
type: string
description: Unique identifier for the given CT clamp.
pattern: ctcl[A-Z\d]{26}
example: ctcl01HSH04KDEWF6Z4DB2J77J74K5
readOnly: true
url:
type: string
format: uri
example: https://api.ev.energy/v2/ct_clamps/ctcl01HSH04KDEWF6Z4DB2J77J74K5
readOnly: true
evse:
oneOf:
- type:
- string
- 'null'
format: uri
example: https://api.ev.energy/v2/evses/evse01HSH04KDEWF6Z4DB2J77J74K5
- $ref: '#/components/schemas/EVSE'
description: >-
The EVSE associated with this CT clamp. Will be null if not linked
to an EVSE.
readOnly: true
calibration_factor:
type: integer
description: >-
Calibration multiplier for current readings. A value of -1 indicates
the clamp was fitted the wrong way around.
example: 1
readOnly: true
CTClampLog:
title: CTClampLog
description: >-
Records the current measurement from a CT clamp at a particular point in
time.
type: object
x-tags:
- CT Clamps
properties:
url:
type: string
format: uri
example: >-
https://api.ev.energy/v2/ct_clamps/ctcl01HSH04KDEWF6Z4DB2J77J74K5/logs/2024-04-17T09:39:45.984584Z
readOnly: true
sampled_at:
type: string
format: date-time
description: The date and time the current measurement was taken on the CT clamp.
logged_at:
type: string
format: date-time
description: The date and time when this data was recorded on the server.
ct_clamp:
oneOf:
- type: string
format: uri
example: >-
https://api.ev.energy/v2/ct_clamps/ctcl01HSH04KDEWF6Z4DB2J77J74K5
- $ref: '#/components/schemas/CTClamp'
description: The CT clamp this log entry belongs to.
current_milliamps:
type: integer
description: >-
The current reading in milliamps. Positive values indicate import
from grid, negative values indicate export (e.g. solar generation).
example: 5200
EVSEModel:
title: Model
description: A resource representing a model of EVSEs.
type: object
required:
- id
- url
- name
properties:
id:
type: string
description: Unique identifier for the given EVSE Model.
pattern: emod[A-Z\d]{26}
example: emod01HS9A004X5TB5JCMHENB5Z446
readOnly: true
url:
type: string
format: uri
example: https://api.ev.energy/v2/evse_models/emod01HS9A004X5TB5JCMHENB5Z446
readOnly: true
name:
type: string
example: EVWC2S22
readOnly: true
make:
oneOf:
- type: string
format: uri
example: >-
https://api.ev.energy/v2/evse_makes/emak01HS8FRMXGE3566EDXCMWGW5W4
- $ref: '#/components/schemas/EVSEMake'
display_name:
type:
- string
- 'null'
example: EVWC2S22
description: >-
The EVSE model name for in-app display. May be null if no display
name has been set.
readOnly: true
onboarding_url:
type:
- string
- 'null'
example: >-
https://api.ev.energy/v2/evse_onboarding?model_id=emod01HN2NJHAJJAQD32QJ4QXTDSGW&user_id=user01HN2NJ9NMRZBXT1H6FT9N7735&client_id=your_client_id
format: uri
description: >-
A pre-constructed link to initiate onboarding for an EVSE with this
model. If it is null, then we do not support intergrating with this
EVSE and the user will need an integrated vehicle in order for us to
be able to track their charging.
Your `client_id` and the user's `user_id` are automatically included
based on your authentication token. If you are using client
credentials authentication, the user ID will not be automatically
included unless you set the EvEnergy-User header on your request.
readOnly: true
x-tags:
- EVSEs
EVSEMake:
title: Make
description: A resource representing a manufacturer of EVSEs.
type: object
x-tags:
- EVSEs
required:
- id
- url
- name
properties:
id:
type: string
description: Unique identifier for the given EVSE Make.
pattern: emak[A-Z\d]{26}
example: emak01HS8FRXKJD5JZZ7ZN6W8H21P8
readOnly: true
url:
type: string
format: uri
example: https://api.ev.energy/v2/evse_makes/emak01HS8FRXKJD5JZZ7ZN6W8H21P8
readOnly: true
name:
type: string
example: BG SyncEV
readOnly: true
display_name:
type:
- string
- 'null'
example: BG SyncEV
description: >-
The EVSE make name for in-app display. May be null if no display
name has been set.
readOnly: true
icon:
type:
- string
- 'null'
format: uri
example: https://cdn.example.com/volvo.png
description: A url for an image of the make's logo.
readOnly: true
onboarding_url:
type:
- string
- 'null'
example: >-
https://api.ev.energy/v2/evse_onboarding?make_id=emak01HN2NJQRGDQP0GBE1F7R6PB3D&user_id=user01HN2NJ9NMRZBXT1H6FT9N7735&client_id=your_client_id
description: >-
A pre-constructed link to initiate onboarding for an EVSE of this
make. If it is null, then it cannot be onboarded with model alone.
You should filter the list of [EVSE
models](ev.energy-API-v2.yaml/paths/~1evse_models/get) by this make
and then have the user select their model.
Your `client_id` and the user's `user_id` are automatically included
based on your authentication token. If you are using client
credentials authentication, the user ID will not be automatically
included unless you set the EvEnergy-User header on your request.
readOnly: true
is_beta:
type: boolean
example: false
description: Whether this EVSE make integration is in beta.
readOnly: true
evse_models:
type: string
format: uri
example: >-
https://api.ev.energy/v2/evse_models/?make_id=emak01HN2NJQRGDQP0GBE1F7R6PB3D
description: >-
A pre-constructed link to a list of EVSE models filtered for this
make.
readOnly: true
VehicleOnboardingCompleteRequest:
title: VehicleOnboardingCompleteRequest
description: >-
Request body for `POST /vehicle_onboarding/complete`. Exchanges a
provider `auth_code` (typically returned by the Smartcar Connect native
SDK) for the list of vehicles created on the user's account.
type: object
x-tags:
- Vehicles
required:
- authorization_request_uid
- auth_code
properties:
authorization_request_uid:
type: string
format: uuid
description: >-
UUID of the `AccountAuthorizationRequest` returned by the init
endpoint.
example: 4d4ce3d9-8a16-46a8-99e1-3f3f9b8a3a5b
auth_code:
type: string
description: OAuth `auth_code` returned by the integration provider.
example: SC-AUTH-CODE-EXAMPLE
smartcar_user_id:
type:
- string
- 'null'
writeOnly: true
maxLength: 100
description: >-
SmartCar user UUID (the `userId` returned alongside `auth_code` on
the Connect redirect / native SDK callback). Optional; only set for
the SmartCar provider.
example: a4c82e9f-0b1c-4d2e-8f3a-5b6c7d8e9f01
VehicleOnboardingCompleteResponse:
title: VehicleOnboardingCompleteResponse
description: >-
Response body for `POST /vehicle_onboarding/complete`. Always an array;
the single-vehicle case is returned as a one-element list.
type: object
x-tags:
- Vehicles
required:
- vehicles
properties:
vehicles:
type: array
items:
type: object
required:
- id
- url
properties:
id:
type: string
description: V2 UID of the created vehicle.
example: vhcl01HRFF3SEVSCRAV9B3CHVDFN0H
url:
type: string
format: uri
description: >-
Absolute URL of the vehicle resource (suitable for `GET
/v2/vehicles/{uid}`).
example: >-
https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H/
EVSEImportRequest:
title: EVSEImportRequest
description: >-
Request body for `POST /evse_onboarding/import`. The backend uses the
authenticated user's email (and `secondary_email` if set on the profile)
to look up the device at the provider, so only the provider name and the
device's serial number are required from the client.
type: object
x-tags:
- EVSEs
required:
- provider
- serial_number
properties:
provider:
type: string
description: >-
The integration provider that owns the EVSE. Must be one of the
providers that supports serial-number-based import.
enum:
- ChargePoint
- EO
- SyncEV
- EnelX
- Easee
- Wallbox
- Zaptec
example: Wallbox
serial_number:
type: string
description: >-
The serial number (CPID) of the EVSE as printed on the device or
shown in the provider's app.
example: WBX-12345678
EVSEWaitlistRequest:
title: EVSEWaitlistRequest
description: >-
Request body for `POST /evse_waitlist`. Device identification fields are
mutually constrained: supply exactly one of (`evse_model_id`) or (both
`evse_make_name` and `evse_model_name`). Any other combination returns
`400`. Country is not part of the request body — see endpoint
description for how it is derived.
type: object
x-tags:
- EVSEs
required:
- email
properties:
email:
type: string
format: email
description: Email address to notify when the user's hardware becomes supported.
example: user@example.com
program_id:
type:
- string
- 'null'
pattern: prog[A-Z\d]{26}
description: >-
Optional `ProgramConfig` uid. Captured where known (web signup,
whitelabel microsite) so later notification logic can scope by
program.
example: prog01HRS4TSK26BPBV7127DH7E0HA
evse_model_id:
type:
- string
- 'null'
pattern: emod[A-Z\d]{26}
description: >-
Uid of an `EVSEModel`. Used when the user picked from the EVSE
picker. Mutually exclusive with `evse_make_name` /
`evse_model_name`.
example: emod01HRS4TSK26BPBV7127DH7E0HA
evse_make_name:
type: string
description: >-
Free-text make name from manual entry. Must be supplied together
with `evse_model_name`. Mutually exclusive with `evse_model_id`.
example: Wallbox
evse_model_name:
type: string
description: >-
Free-text model name from manual entry. Must be supplied together
with `evse_make_name`. Mutually exclusive with `evse_model_id`.
example: Pulsar Pro
EVSEWaitlistResponse:
title: EVSEWaitlistResponse
description: >-
Response body for `POST /evse_waitlist`. Echoes just the new entry's
uid; no `url` is returned because the endpoint exposes no retrieve
action (privacy by design — waitlist entries cannot be enumerated or
looked up via the public API).
type: object
x-tags:
- EVSEs
required:
- id
properties:
id:
type: string
pattern: ewlt[A-Z\d]{26}
description: Uid of the created waitlist entry.
example: ewlt01HRS4TSK26BPBV7127DH7E0HA
VehicleWaitlistRequest:
title: VehicleWaitlistRequest
description: >-
Request body for `POST /vehicle_waitlist`. Device identification fields
are mutually constrained: supply exactly one of (`vehicle_model_id`) or
(both `vehicle_make_name` and `vehicle_model_name`). Any other
combination returns `400`. Country is not part of the request body — see
endpoint description for how it is derived.
type: object
x-tags:
- Vehicles
required:
- email
properties:
email:
type: string
format: email
description: Email address to notify when the user's hardware becomes supported.
example: user@example.com
program_id:
type:
- string
- 'null'
pattern: prog[A-Z\d]{26}
description: >-
Optional `ProgramConfig` uid. Captured where known (web signup,
whitelabel microsite) so later notification logic can scope by
program.
example: prog01HRS4TSK26BPBV7127DH7E0HA
vehicle_model_id:
type:
- string
- 'null'
pattern: vmod[A-Z\d]{26}
description: >-
Uid of a `CarModel`. Used when the user picked from the vehicle
picker. Mutually exclusive with `vehicle_make_name` /
`vehicle_model_name`.
example: vmod01HRS4TSK26BPBV7127DH7E0HA
vehicle_make_name:
type: string
description: >-
Free-text make name from manual entry. Must be supplied together
with `vehicle_model_name`. Mutually exclusive with
`vehicle_model_id`.
example: Tesla
vehicle_model_name:
type: string
description: >-
Free-text model name from manual entry. Must be supplied together
with `vehicle_make_name`. Mutually exclusive with
`vehicle_model_id`.
example: Model 3
VehicleWaitlistResponse:
title: VehicleWaitlistResponse
description: >-
Response body for `POST /vehicle_waitlist`. Echoes just the new entry's
uid; no `url` is returned because the endpoint exposes no retrieve
action (privacy by design — waitlist entries cannot be enumerated or
looked up via the public API).
type: object
x-tags:
- Vehicles
required:
- id
properties:
id:
type: string
pattern: vwlt[A-Z\d]{26}
description: Uid of the created waitlist entry.
example: vwlt01HRS4TSK26BPBV7127DH7E0HA
EVSEOnboardingJsonResponse:
title: EVSEOnboardingJsonResponse
description: >-
JSON payload returned by `GET /evse_onboarding?response_type=json`.
Carries the absolute Start-wrapper URL.
type: object
x-tags:
- EVSEs
required:
- url
properties:
url:
type: string
format: uri
description: >-
Absolute URL to the EVSE onboarding wrapper. Open it in a WebView
(mobile) or redirect the browser to it (web). The wrapper view
either redirects to the provider (when a model was supplied) or
shows the make picker.
example: >-
https://api.ev.energy/evse-onboarding/start/abc12345-def6-7890-1234-567890abcdef/
VehicleOnboardingJsonResponse:
title: VehicleOnboardingJsonResponse
description: >-
JSON payload returned by `GET /vehicle_onboarding?response_type=json`.
Used by native mobile clients to launch the onboarding flow.
type: object
x-tags:
- Vehicles
required:
- authorization_request_id
- url
- auth_method
properties:
authorization_request_id:
type: string
format: uuid
readOnly: true
description: >-
UUID identifying the in-flight onboarding request. Echo it back to
`POST /vehicle_onboarding/complete` (as `authorization_request_uid`)
to finish onboarding.
url:
type: string
format: uri
description: >-
The integration provider's authorization URL the client should
navigate to (or pass to the native SDK).
example: >-
https://connect.smartcar.com/oauth/authorize?response_type=code&client_id=...
auth_method:
type: string
enum:
- api
- native
description: >-
Whether the client should open `url` in a WebView (`api`) or launch
the provider's native SDK with the supplied scopes (`native`).
`native` is currently used for Smartcar BMW/MINI when the
`smartcar_native_sdk` waffle flag is enabled.
scopes:
type:
- array
- 'null'
items:
type: string
description: >-
OAuth scopes that the SDK should request when `auth_method=native`.
Null when the field does not apply (for example for
`auth_method=api` providers that do not surface scopes here).
example:
- read_vehicle_info
- read_charge
- control_charge
single_select:
type:
- boolean
- 'null'
description: >-
Whether the SDK should restrict the user to picking a single
vehicle. Null when the field does not apply.
Vehicle:
title: Vehicle
description: A resource representing a single, physical electric vehicle.
type: object
x-tags:
- Vehicles
required:
- id
- url
- integrated
- battery_size_watt_hours
- effective_battery_size_watt_hours
- maximum_charge_limit_percentage
- description
- disabled
- smart_charging_enabled
- vehicle_class
properties:
id:
type: string
description: Unique identifier for the given Vehicle.
pattern: vhcl[A-Z\d]{26}
example: vhcl01HRFF3SEVSCRAV9B3CHVDFN0H
readOnly: true
url:
type: string
format: uri
example: https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H
readOnly: true
trim:
oneOf:
- type: string
format: uri
example: >-
https://api.ev.energy/v2/trim/vehicle_trim01HRFHBCM7VBSWRPVYFBQMH2BR
- $ref: '#/components/schemas/VehicleTrim'
description: >-
Defaults to a url, but can be expanded to the full Trim resource via
the `expand` query parameter.
readOnly: true
user:
example: https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735
oneOf:
- type: string
format: uri
example: https://api.ev.energy/v2/user/user01HN2NJ9NMRZBXT1H6FT9N7735
- $ref: '#/components/schemas/User'
description: >-
Defaults to a url, but can be expanded to the full User resource via
the `expand` query parameter.
latest_status_log:
example: >-
https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H/status_logs/2024-04-17T09:39:45.994584Z/
oneOf:
- type:
- string
- 'null'
example: >-
https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H/status_logs/2024-04-17T09:39:45.994584Z/
format: uri
- $ref: '#/components/schemas/VehicleStatusLog'
description: >-
An expandable reference to the most recent status log for this
Vehicle. This can be requested or expanded to get the most accurate
information we have on the device's current status.
charging_sub_sessions:
type: string
format: uri
example: >-
https://api.ev.energy/charging_sub_sessions/?vehicle_id=vhcl01HRFF3SEVSCRAV9B3CHVDFN0H
description: >-
Provides a pre-constructed URL to list charging sub-sessions
involving this Vehicle.
integrated:
enum:
- UNINTEGRATED
- ACTIVE
- INACTIVE
description: >-
Whether we have an integration with this vehicle.
- `UNINTEGRATED`: This vehicle is not integrated
- `ACTIVE`: This vehicle is integrated and the connection is
working.
- `INACTIVE`: This vehicle has been integrated but the connection
has been severed, usually because the user needs to reconnect it.
readOnly: true
battery_size_watt_hours:
type: integer
minimum: 1000
maximum: 300000
description: >-
The nominal battery capacity of the vehicle in watt-hours according
to the vehicle integration or trim. Editable via PATCH only for
unintegrated vehicles; sending it for an integrated vehicle is
rejected. Setting it flags the battery size as user-provided. Stored
to the nearest 0.01 kWh (10 Wh), so the value read back may be
rounded.
example: 60000
effective_battery_size_watt_hours:
type: integer
description: >-
The effective battery capacity of the vehicle in watt-hours,
accounting for estimated degradation based on odometer reading. This
is the value used by the smart charging scheduler.
readOnly: true
example: 60000
maximum_charge_limit_percentage:
type: integer
minimum: 50
maximum: 100
description: >-
The target state of charge of the car as a percentage between 50 and
100. The car will not be smart charged above this value. Can be null
if target charge level has not been set or we don't know the car's
battery size.
default: 100
description:
type: string
maxLength: 200
description: Human-readable label for the vehicle.
example: My Volvo C40
readOnly: true
disabled:
type: boolean
description: >-
Whether the vehicle has been disabled and can no longer be
smart-charged or controlled. Set when the user unenrolls the
vehicle, when an integrated vehicle is switched to unintegrated
('dumb'), or when the owning account is pending deletion. Disabled
vehicles that have not been permanently deleted are still returned
by this endpoint. This is independent of integrated: a disabled
vehicle can still report integrated=ACTIVE (e.g. pending deletion),
and a healthy never-integrated vehicle is not disabled.
example: false
readOnly: true
smart_charging_enabled:
type: boolean
description: Whether smart (dynamic) charging is enabled for this vehicle.
example: true
vehicle_class:
type:
- string
- 'null'
enum:
- PASSENGER
- COMMERCIAL
- null
description: Class of vehicle, passenger or commercial.
example: PASSENGER
VehicleWrite:
title: Vehicle
description: >-
Fields that can be set when creating an unintegrated Vehicle resource.
The client supplies a `model` (and optional `battery_size_watt_hours`);
the backend resolves or creates a hidden trim under the hood.
type: object
x-tags:
- Vehicles
required:
- model
properties:
model:
type: string
format: uri
example: >-
https://api.ev.energy/v2/vehicle_models/vmod01HN2P436099PEQ20B7TKPGTEJ
readOnly: false
description: >-
UID-based URL of an existing CarModel. The backend resolves or
creates a hidden trim for the given model and (optional) battery
size.
battery_size_watt_hours:
type: integer
minimum: 1000
maximum: 300000
example: 60000
description: Battery size in watt-hours.
description:
type: string
maxLength: 200
example: My Volvo C40
description: >-
Optional human-readable label for the vehicle. Defaults to a string
built from the user's email and the resolved make/model when
omitted.
vehicle_class:
type:
- string
- 'null'
enum:
- PASSENGER
- COMMERCIAL
- null
description: Class of vehicle, passenger or commercial.
example: PASSENGER
user:
example: https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735
type: string
format: uri
readOnly: false
description: Required if using Client Credentials authentication.
VehicleTrim:
title: VehicleTrim
description: >-
A resource representing a "trim level" of a particular vehicle model,
which captures a specific set of features.
type: object
x-tags:
- Vehicles
required:
- id
- url
- name
- onboarding_url
properties:
id:
type: string
description: Unique identifier for the given Vehicle Trim.
pattern: trim[A-Z\d]{26}
example: trim01HRFHBCM7VBSWRPVYFBQMH2BR
readOnly: true
url:
type: string
format: uri
example: https://api.ev.energy/v2/vehicle_trim/trim01HRFHBCM7VBSWRPVYFBQMH2BR
readOnly: true
name:
type: string
example: Recharge Core (69 kWh)
readOnly: true
model:
oneOf:
- type: string
format: uri
- $ref: '#/components/schemas/VehicleModel'
battery_size_watt_hours:
type:
- integer
- 'null'
description: Battery size in watt-hours. null if not known for this trim.
example: 75500
readOnly: true
onboarding_url:
type:
- string
- 'null'
example: >-
https://api.ev.energy/v2/vehicle_onboarding?trim_id=trim01HN2NZ1040Y8E77CQGXADC2TZ&user_id=user01HN2NJ9NMRZBXT1H6FT9N7735&client_id=your_client_id
format: uri
description: >-
A pre-constructed link to initiate onboarding for a vehicle with
this trim. If it is null, then we do not support intergrating with
this vehicle and you should POST the trim to
[/vehicles](ev.energy-API-v2.yaml/paths/~1vehicles/post) to create
an unintegrated vehicle.
Your `client_id` and the user's `user_id` are automatically included
based on your authentication token. If you are using client
credentials authentication, the user ID will not be automatically
included unless you set the EvEnergy-User header on your request.
readOnly: true
VehicleTrimCreate:
title: VehicleTrimCreate
description: Request body for creating a custom vehicle trim.
type: object
x-tags:
- Vehicles
required:
- name
- model
- battery_size_watt_hours
properties:
name:
type: string
description: The name of the vehicle trim.
example: Custom Trim
model:
type: string
format: uri
description: URL reference to the vehicle model this trim belongs to.
example: >-
https://api.ev.energy/v2/vehicle_models/vmod01HSBR8Z36GD7A46K7M4R12VG0
battery_size_watt_hours:
type: integer
description: Battery size in watt hours. Must be between 1000 and 300000.
minimum: 1000
maximum: 300000
example: 75500
VehicleModelWrite:
title: VehicleModelWrite
description: Fields that must be set when creating a VehicleModel resource.
type: object
x-tags:
- Vehicles
required:
- name
- make
properties:
name:
type: string
description: The name of the vehicle model.
example: Model 3
make:
type: string
format: uri
description: URL reference to the vehicle make.
example: >-
https://api.ev.energy/v2/vehicle_makes/vmak01HRFHBCM7VBSWRPVYFBQMH2BR
VehicleModel:
title: VehicleModel
description: A resource representing a model of vehicle.
type: object
x-tags:
- Vehicles
required:
- id
- url
- name
- default_battery_size_watt_hours
- default_connector_type
properties:
id:
type: string
description: Unique identifier for the given Vehicle Model.
pattern: vmod[A-Z\d]{26}
example: vmod01HSBR8Z36GD7A46K7M4R12VG0
readOnly: true
url:
type: string
format: uri
example: https://api.ev.energy/vehicle_models/vmod01HSBR8Z36GD7A46K7M4R12VG0
readOnly: true
name:
type: string
example: C40
readOnly: true
make:
oneOf:
- type: string
format: uri
example: >-
https://api.ev.energy/v2/vehicle_makes/vmak01HRFHBCM7VBSWRPVYFBQMH2BR
- $ref: '#/components/schemas/VehicleMake'
onboarding_url:
type:
- string
- 'null'
format: uri
example: >-
https://api.ev.energy/v2/vehicle_onboarding?model_id=vmod01HN2P436099PEQ20B7TKPGTEJ&user_id=user01HN2NJ9NMRZBXT1H6FT9N7735&client_id=your_client_id
description: >-
A pre-constructed link to initiate onboarding for a vehicle of this
model. If it is null, then it cannot be onboarded with model alone.
You should filter the list of [vehicle
trims](ev.energy-API-v2.yaml/paths/~1vehicle_trims/get) by this
model and then have the user select their trim.
Your `client_id` and the user's `user_id` are automatically included
based on your authentication token. If you are using client
credentials authentication, the user ID will not be automatically
included unless you set the EvEnergy-User header on your request.
vehicle_trims:
type: string
format: uri
example: >-
https://api.ev.energy/v2/vehicle_trims?model_id=vmod01HN2P436099PEQ20B7TKPGTEJ
description: >
A pre-constructed link to a list of vehicle trims filtered for this
model.
readOnly: true
default_battery_size_watt_hours:
type: integer
description: >-
Default battery size in watt-hours for this model, derived from the
most common battery size across trims. Falls back to 45000 Wh if no
trim data exists.
example: 79000
readOnly: true
default_connector_type:
type:
- string
- 'null'
enum:
- CCS
- NACS
- CHADEMO
- null
description: |-
Default charging connector type for this model, used to pre-fill
connector selection during vehicle onboarding. Null when not yet
known. Editable via PATCH with the `vehicle_catalogue:write` scope.
VehicleModelUpdate:
title: VehicleModelUpdate
description: Request body for `PATCH /vehicle_models/{vehicle_model_id}`.
type: object
properties:
default_connector_type:
type:
- string
- 'null'
enum:
- CCS
- NACS
- CHADEMO
- null
VehicleMake:
title: VehicleMake
description: A resource representing a vehicle manufacturer.
type: object
x-tags:
- Vehicles
required:
- id
- url
- name
- icon
- onboarding_url
- models
properties:
id:
type: string
description: Unique identifier for the given Vehicle Make.
pattern: vmak[A-Z\d]{26}
example: vmak01HRFHBCM7VBSWRPVYFBQMH2BR
readOnly: true
url:
type: string
format: uri
example: >-
https://api.ev.energy/v2/vehicle_makes/vmak01HRFHBCM7VBSWRPVYFBQMH2BR
readOnly: true
name:
type: string
example: Volvo
readOnly: true
icon:
type:
- string
- 'null'
format: uri
example: https://cdn.example.com/volvo.png
description: A url for an image of the make's logo.
readOnly: true
onboarding_url:
type:
- string
- 'null'
example: >-
https://api.ev.energy/v2/vehicle_onboarding/?make_id=vmak01HN2P75GBNFRJPCZJXEFVXH5E&user_id=user01HN2NJ9NMRZBXT1H6FT9N7735&client_id=your_client_id
description: >-
A pre-constructed link to initiate onboarding for a vehicle of this
make. If it is null, then it cannot be onboarded with make alone.
You should filter the list of [vehicle
models](ev.energy-API-v2.yaml/paths/~1vehicle_models/get) by this
make and then have the user select their model.
Your `client_id` and the user's `user_id` are automatically included
based on your authentication token. If you are using client
credentials authentication, the user ID will not be automatically
included unless you set the EvEnergy-User header on your request.
readOnly: true
models:
type: string
format: uri
example: >-
https://api.ev.energy/vehicle_models?make_id=vmak01HN2P75GBNFRJPCZJXEFVXH5E
description: >-
A pre-constructed link to a list of vehicle models filtered for this
make.
readOnly: true
subscription_name:
type:
- string
- 'null'
description: >-
Full OEM telematics subscription name required for vehicle
connectivity (e.g. 'Volkswagen We Connect ID'). Null if no
subscription is required.
example: Volkswagen We Connect ID
readOnly: true
subscription_package:
type:
- string
- 'null'
description: >-
Specific OEM subscription package required (e.g. 'We Connect ID').
Null if no subscription is required.
example: We Connect ID
readOnly: true
VehicleCompatibilityCheckResult:
title: VehicleCompatibilityCheckResult
description: |-
Compatibility verdict for a `(vehicle_model, country)` pair.
Returned by `GET /vehicle_compatibility/check`.
type: object
required:
- compatible
- recommendation_rank
properties:
compatible:
type: boolean
description: True if the model is supported in the requested country.
recommendation_rank:
type:
- integer
- 'null'
minimum: 1
maximum: 10
description: |-
Priority of the car make on the new device-selection screen.
Lower = higher priority (1 = top, 10 = lowest explicit value);
`null` means no rank set and should be treated as lower priority
than any explicit value. Always reflects the make's current
value, independent of `compatible`.
ProgramVehicleCompatibility:
title: ProgramVehicleCompatibility
description: >-
A vehicle compatibility record indicating whether a particular vehicle
model is supported for smart charging.
type: object
x-tags:
- Vehicles
properties:
can_control_charge:
type: boolean
description: Whether ev.energy can control charging for this vehicle model.
example: true
readOnly: true
model:
oneOf:
- type: string
format: uri
example: >-
https://api.ev.energy/v2/vehicle_models/vmod01HSBR8Z36GD7A46K7M4R12VG0
- $ref: '#/components/schemas/VehicleModel'
description: >-
Link to the vehicle model by default. Expanded to full object when
?expand=model is used.
readOnly: true
type:
type:
- string
- 'null'
description: >-
The vehicle type: BEV (Battery Electric Vehicle) or PHEV (Plug-in
Hybrid Electric Vehicle).
example: BEV
enum:
- BEV
- PHEV
- null
readOnly: true
supported_countries:
type: array
items:
type: string
minLength: 2
maxLength: 2
description: >-
List of ISO 3166-1 alpha-2 country codes this vehicle is compatible
in.
example:
- US
- CA
readOnly: true
start_year:
type: integer
description: The first model year this compatibility applies to.
example: 2020
readOnly: true
end_year:
type:
- integer
- 'null'
description: >-
The last model year this compatibility applies to. Null if still in
production.
example: 2026
readOnly: true
ScheduleInterval:
title: ScheduleInterval
description: >-
A schedule interval represents a charging instruction for a specific
time period within a charging session. It specifies the charging current
(in milliamps) that should be applied during that period.
type: object
x-tags:
- Schedules
properties:
started_at:
type: string
format: date-time
example: '2024-01-01T02:00:00Z'
description: >-
The start time of the period this schedule applies to. Always
aligned to half-hour boundaries (:00 or :30).
readOnly: true
interval_seconds:
type:
- integer
- 'null'
example: 1800
description: >-
The duration of this schedule in seconds. Currently always 1800
seconds (30 minutes), or null for boost sessions which have no
defined end time.
readOnly: true
current_milliamps:
type: integer
example: 7400
description: >-
The charging current in milliamps that should be applied during this
period. A value of 0 means no charging.
readOnly: true
schedule_type:
type: string
example: SMART
enum:
- INITIAL_CHARGE_TIME
- BATTERY_WARMING
- SMART
- BOOST
- SOLAR_ONLY
- SOLAR_SMART
- V2G_DISCHARGE
- V2G_CHARGEBACK
- LEGACY
description: |-
The type of scheduling that generated this instruction.
- INITIAL_CHARGE_TIME: Initial charge to condition the battery
- BATTERY_WARMING: Pre-warming the hour before the ready-by-time
- SMART: Optimised smart charging
- BOOST: Immediate charging at maximum rate
- SOLAR_ONLY: Charging only from solar generation
- SOLAR_SMART: Combined solar and smart charging
- V2G_DISCHARGE: Vehicle-to-grid discharge
- V2G_CHARGEBACK: Charging back after V2G discharge
- LEGACY: Legacy schedules from before type tracking
readOnly: true
dispatched_at:
type:
- string
- 'null'
format: date-time
example: '2024-01-01T02:00:15Z'
description: >-
When this schedule was last sent to the device. Null if not yet
dispatched.
readOnly: true
created_at:
type: string
format: date-time
example: '2024-01-01T01:55:00Z'
description: When this schedule was created.
readOnly: true
ChargingSession:
title: ChargingSession
type: object
description: >-
Represents a single physical plug-in episode (plug in → unplug). A
session may contain multiple charging sub-sessions if the charging mode
changed while the vehicle was plugged in. Only recorded from the
feature's release (July 2026) onwards — earlier charging history is not
backfilled. See [Understanding charging
data](docs/understanding/charging_sessions.md).
x-tags:
- Charging sessions
required:
- id
- url
- start
properties:
id:
type: string
description: Unique identifier for the charging session.
pattern: cses[A-Z\d]{26}
example: cses01HSH04KDEWF6Z4DB2J77J74K5
readOnly: true
url:
type: string
format: uri
example: >-
https://api.ev.energy/v2/charging_sessions/cses01HSH04KDEWF6Z4DB2J77J74K5
start:
type: string
format: date-time
description: >-
When the plug-in episode began, i.e. when the vehicle was plugged
in.
readOnly: true
end:
type:
- string
- 'null'
format: date-time
description: >-
When the plug-in episode ended, i.e. when the vehicle was unplugged.
Null while the vehicle is still plugged in.
readOnly: true
vehicle:
oneOf:
- type:
- string
- 'null'
format: uri
example: https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H
- $ref: '#/components/schemas/Vehicle'
evse:
oneOf:
- type:
- string
- 'null'
format: uri
example: https://api.ev.energy/v2/evses/evse01HSH04KDEWF6Z4DB2J77J74K5
- $ref: '#/components/schemas/EVSE'
sub_sessions:
oneOf:
- type: array
items:
type: string
format: uri
example:
- >-
https://api.ev.energy/v2/charging_sub_sessions/csub01HSH08F2YWBKZ9NXR7P3QD5VT
- >-
https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5
description: Links to sub-sessions by default.
- type: array
items:
$ref: '#/components/schemas/ChargingSubSession'
description: >-
Expanded sub-sessions when ?expand=sub_sessions is used, ordered
newest first.
description: >-
Links by default, expanded data when ?expand=sub_sessions is used.
Ordered newest first.
ChargingSubSessionCreatedWebhook:
title: Charging Sub Session Created Webhook
description: Webhook payload delivered when a charging sub-session is created.
type: object
required:
- type
- timestamp
- data
properties:
type:
type: string
enum:
- charging_sub_session.created
description: The event type. Also delivered in the `svix-event-type` header.
timestamp:
type: string
format: date-time
description: ISO 8601 UTC timestamp for when the event occurred.
data:
description: >-
The created charging sub-session, in the same format returned by
`GET /v2/charging_sub_sessions/{id}`.
allOf:
- $ref: '#/components/schemas/ChargingSubSession'
examples:
- type: charging_sub_session.created
timestamp: '2022-11-03T20:26:10.344522Z'
data:
id: csub01HSH04KDEWF6Z4DB2J77J74K5
url: >-
https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5
start: '2019-08-24T14:15:22Z'
end: null
mode: SMART
energy_delivered_watt_hours: 0
location:
name: Home
cost: 0
currency: GBP
total_co2_grams: 0
co2_intensity_grams_per_kilowatt_hour: 1
co2_intensity_classification: low
duration_minutes: 0
grid_energy_delivered_watt_hours: 0
solar_energy_delivered_watt_hours: 0
ChargingSubSessionEndedWebhook:
title: Charging Sub Session Ended Webhook
description: Webhook payload delivered when a charging sub-session ends.
type: object
required:
- type
- timestamp
- data
properties:
type:
type: string
enum:
- charging_sub_session.ended
description: The event type. Also delivered in the `svix-event-type` header.
timestamp:
type: string
format: date-time
description: ISO 8601 UTC timestamp for when the event occurred.
data:
description: >-
The ended charging sub-session, in the same format returned by `GET
/v2/charging_sub_sessions/{id}`.
allOf:
- $ref: '#/components/schemas/ChargingSubSession'
examples:
- type: charging_sub_session.ended
timestamp: '2022-11-03T20:26:10.344522Z'
data:
id: csub01HSH04KDEWF6Z4DB2J77J74K5
url: >-
https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5
start: '2019-08-24T14:15:22Z'
end: '2019-08-24T15:15:22Z'
mode: SMART
energy_delivered_watt_hours: 2300
location:
name: Home
cost: 634
currency: GBP
total_co2_grams: 229
co2_intensity_grams_per_kilowatt_hour: 1
co2_intensity_classification: low
duration_minutes: 60
grid_energy_delivered_watt_hours: 1840
solar_energy_delivered_watt_hours: 460
ChargingSubSession:
title: SubSession
type: object
description: >-
Represents a period within a charging session (one plug-in episode) when
the same charging mode was active. Begins either when a vehicle is
plugged in or when it switches mode (eg. from smart to boost) and ends
either when the vehicle is unplugged or the mode switches again. Note
that start/end bound the period the mode was active — not when energy
was actually flowing. Energy may be delivered during only part of the
sub-session, or in several separate bursts (see the energy_usage
endpoint). See [Understanding charging
data](docs/understanding/charging_sessions.md).
x-tags:
- Charging sessions
required:
- id
- url
- start
- end
- mode
- energy_delivered_watt_hours
- location
- cost
- currency
- total_co2_grams
- co2_intensity_grams_per_kilowatt_hour
- co2_intensity_classification
- duration_minutes
- grid_energy_delivered_watt_hours
- solar_energy_delivered_watt_hours
properties:
id:
type: string
description: Unique identifier for the given Charging sub-session.
pattern: csub[A-Z\d]{26}
example: csub01HSH04KDEWF6Z4DB2J77J74K5
readOnly: true
url:
type: string
format: uri
example: >-
https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5
start:
type: string
format: date-time
description: >-
When this sub-session began — either when the vehicle was plugged
in, or when the charging mode changed (e.g. the user activated
boost). Not necessarily when energy started flowing; see the
energy_usage endpoint for actual delivery intervals.
readOnly: true
end:
type:
- string
- 'null'
format: date-time
description: >-
When this sub-session ended — either when the vehicle was unplugged,
or when the charging mode changed again. Null while the sub-session
is ongoing. Energy delivery often finishes well before this time
(e.g. once the target charge level is reached).
readOnly: true
mode:
enum:
- SMART
- BOOST
- UNMANAGED_HOME
- UNMANAGED_OTG
- MANAGED_OTG
description: |-
The type of scheduling applied during this period.
SMART: Actively optimised charging
BOOST: Charge immediately
UNMANAGED_HOME: No optimisation, at a home location
UNMANAGED_OTG: No optimisation, at an on-the-go (public) location
MANAGED_OTG: Optimised charging at an on-the-go (public) location
readOnly: true
vehicle:
oneOf:
- type:
- string
- 'null'
example: https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H
format: uri
- $ref: '#/components/schemas/Vehicle'
evse:
oneOf:
- type:
- string
- 'null'
example: https://api.ev.energy/v2/evses/evse01HSH04KDEWF6Z4DB2J77J74K5
format: uri
- $ref: '#/components/schemas/EVSE'
energy_delivered_watt_hours:
type: integer
example: 2300
description: Net energy delivered to the vehicle during this sub-session in Wh.
readOnly: true
cost:
type:
- integer
- 'null'
example: 634
readOnly: true
location:
type: object
properties:
name:
type: string
example: Home
readOnly: true
coordinates:
type: object
$ref: '#/components/schemas/LatLong'
description: Can be null
postal_code:
type:
- string
- 'null'
maxLength: 10
address_1:
type:
- string
- 'null'
timezone:
type:
- string
- 'null'
example: Europe/London
description: IANA timezone name for the charging location.
percentage_added:
type:
- number
- 'null'
example: 30
readOnly: true
currency:
type: string
example: GBP
readOnly: true
savings_cost:
type:
- integer
- 'null'
description: Cost Savings in Minor Unit of Currency.
readOnly: true
savings_co2_grams:
type:
- integer
- 'null'
description: Savings of Carbon in Grams of CO2.
readOnly: true
incentive_earned:
type:
- integer
- 'null'
example: 99
description: Incentive earned in minor unit of currency.
readOnly: true
total_co2_grams:
type:
- integer
- 'null'
description: Estimated total CO2 emissions of this sub-session in grams
co2_intensity_grams_per_kilowatt_hour:
type:
- integer
- 'null'
description: >-
Estimated CO2 emissions per unit of electricity in grams per
kilowatt hour
co2_intensity_classification:
oneOf:
- enum:
- very low
- low
- moderate
- high
- very high
- type: 'null'
description: Classification of the estimated CO2 intensity value. Can be null.
readOnly: true
cost_per_kilowatt_hour:
type:
- integer
- 'null'
description: >-
Average cost per kilowatt hour of energy delivered during this
charging sub-session
total_points:
type: integer
description: Number of smart points earned during this charging sub-session
total_points_missed:
type:
- integer
- 'null'
description: >-
Difference between the number of smart points earned in this
sub-session and the number that would have been earned by Smart
charging
duration_minutes:
type: integer
description: >-
How long the vehicle was actively charging for, to the nearest
minute. This can be much shorter than the gap between start and end,
and does not tell you when within the sub-session energy was
delivered — use the energy_usage endpoint for that.
grid_energy_delivered_watt_hours:
type:
- integer
- 'null'
description: >-
Grid energy delivered during this charging sub-session in watt hours
(Wh).
readOnly: true
solar_energy_delivered_watt_hours:
type:
- integer
- 'null'
description: >-
Solar energy delivered during this charging sub-session in watt
hours (Wh).
readOnly: true
labels:
type:
- array
- 'null'
items:
type: string
enum:
- OUTSIDE
- OFF_PEAK
- SUMMER_PEAK
- MIXED
- OTHER
- PRIMARY
- AWAY
- CONED
- ORU
description: >-
Labels categorizing this charging sub-session (e.g., service
territory, pricing period).
readOnly: true
energy_usage:
oneOf:
- type: string
format: uri
example: >-
https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5/energy_usage
readOnly: true
- $ref: '#/components/schemas/EnergyUsage'
description: >-
A link to more detailed information about energy usage during the
charging sub-session, including the intervals in which energy was
actually delivered to the vehicle. Can be expanded.
schedules:
oneOf:
- type: string
format: uri
example: >-
https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5/schedules
readOnly: true
- $ref: '#/components/schemas/Schedules'
description: >-
A link to schedule information for the charging sub-session. Can be
expanded.
readOnly: true
assessment:
oneOf:
- type: string
format: uri
example: >-
https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5/assessment
readOnly: true
- $ref: '#/components/schemas/ChargingSubSessionAssessment'
description: >-
A link to the performance assessment for this charging sub-session.
Can be expanded. Requires debug:read scope.
readOnly: true
flags:
oneOf:
- type: string
format: uri
example: >-
https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5/flags
readOnly: true
- $ref: '#/components/schemas/ChargingSubSessionFlags'
description: >-
A link to flags associated with this charging sub-session. Can be
expanded.
readOnly: true
debug_metadata:
oneOf:
- type: string
format: uri
example: >-
https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5/debug_metadata
readOnly: true
- $ref: '#/components/schemas/ChargingSubSessionDebugMetadata'
description: >-
A link to debug metadata for this charging sub-session. Can be
expanded. Requires debug:read scope.
readOnly: true
tariff:
oneOf:
- type: string
format: uri
example: https://api.ev.energy/v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7735
- $ref: '#/components/schemas/Tariff'
- type: 'null'
description: >-
The electricity import tariff. Expandable with ?expand=tariff.
Requires tariff:read scope.
readOnly: true
carbon_feed:
oneOf:
- type: string
format: uri
example: >-
https://api.ev.energy/v2/carbon_feeds/cabf01HN2NJ9NMRZBXT1H6FT9N7735
- $ref: '#/components/schemas/CarbonFeed'
- type: 'null'
description: >-
The carbon feed used to calculate carbon intensity for this
sub-session. Expandable with ?expand=carbon_feed. Requires
carbon:read scope.
readOnly: true
grid_feeds:
oneOf:
- type: array
items:
type: string
format: uri
example: >-
https://api.ev.energy/v2/grid_feeds/grfd01HN2NJ9NMRZBXT1H6FT9N7735
- type: array
items:
$ref: '#/components/schemas/GridFeed'
description: >-
Grid feeds applied to this sub-session. Expandable with
?expand=grid_feeds. Requires grid:read scope.
readOnly: true
solar_mode_type:
type:
- string
- 'null'
enum:
- 'OFF'
- SOLAR_ONLY
- SOLAR_AND_GRID
- SOLAR_SMART
- null
description: >-
The solar charging mode active for this sub-session. Null when solar
charging is not configured.
readOnly: true
grid_energy_delivered:
type: string
format: decimal
deprecated: true
description: Use `grid_energy_delivered_watt_hours` instead
readOnly: true
solar_energy_delivered:
type: string
format: decimal
deprecated: true
description: Use `solar_energy_delivered_watt_hours` instead.
readOnly: true
DispatcherLog:
title: DispatcherLog
type: object
description: Records when a Dispatch Command was sent to an EVSE or Vehicle.
x-tags:
- Charging Sessions
properties:
logged_at:
type: string
format: date-time
description: The date and time when the dispatch command was logged.
readOnly: true
charging_sub_session:
oneOf:
- type: string
format: uri
example: >-
https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5
- $ref: '#/components/schemas/ChargingSubSession'
description: The charging sub-session associated with this dispatch log.
readOnly: true
schedule_valid_period_start:
type: string
format: date-time
description: >-
The start of the validity period for the schedule that generated
this dispatch command.
readOnly: true
schedule_created_at:
type: string
format: date-time
description: When the schedule that generated this dispatch command was created.
readOnly: true
internal_command_id:
type: string
format: uuid
description: Internal identifier for tracking the dispatch command.
example: 12345678-1234-5678-1234-567812345678
readOnly: true
device_type:
type: string
enum:
- EVSE
- VEHICLE
description: The type of device the Dispatch Command was sent to.
readOnly: true
reason_not_sent:
type:
- string
- 'null'
description: If the dispatch command was not sent, provides a reason.
readOnly: true
TariffBase:
title: TariffBase
type: object
description: >-
Core tariff properties shared by Tariff and expanded scheduler_tariff.
Note: daily_prices and type are only available under contract. Please
reach out to your account manager to find out more.
x-tags:
- Tariffs
required:
- id
- url
- supplier
- name
- currency
properties:
id:
type: string
description: Unique identifier for the given user.
pattern: tari[A-Z\d]{26}
example: tari01HN2NJ9NMRZBXT1H6FT9N7735
readOnly: true
url:
type: string
format: uri
example: https://api.ev.energy/v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7735
supplier:
oneOf:
- type: string
format: uri
example: >-
https://api.ev.energy/v2/suppliers/supl01HN2NJ9NMRZBXT1H6FT9N7735
- $ref: '#/components/schemas/Supplier'
description: The energy company that supplies this tariff.
name:
type: string
example: Fangorn Biomass
currency:
type: string
example: GBP
highlighted:
type: boolean
description: A highlighted tariff is one that is often selected by users.
type:
enum:
- FLAT_RATE
- DUAL_RATE
- THREE_RATE
- DYNAMIC
- EXTERNALLY_MANAGED
- OTHER
daily_prices:
$ref: '#/components/schemas/DailyPrices'
description: >-
The times returned here are localised to the timezone the tariff is
in.
The timezone is returned in `timezone_name`.
timezone_name:
type: string
example: Europe/London
price_chart_url:
type:
- string
- 'null'
description: >-
The url of a website which can display a chart of prices for the
tariff. This website is an external resource and is not affiliated
with ev.energy.
example: https://www.example.com/
gsp_group:
type:
- string
- 'null'
description: >-
The GB Grid Supply Point (DNO region) the tariff applies to.
Suppliers publish region-specific rates, so the same named tariff
can appear once per region with differing prices; this field
distinguishes them. `null` for tariffs that are not region-specific.
example: _C
valid_from:
type: string
format: date
description: The date from which this tariff became available to new customers.
example: '2026-03-17'
valid_until:
type:
- string
- 'null'
format: date
description: >-
The date after which this tariff is no longer available to new
customers (it has been superseded). `null` if the tariff is still
open to new sign-ups. Use the `valid` query parameter to filter the
list to only currently-available tariffs.
example: '2027-03-17'
Tariff:
title: Tariff
examples:
- id: tari01HN2NJ9NMRZBXT1H6FT9N7735
url: https://api.ev.energy/v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7735
supplier: https://api.ev.energy/v2/suppliers/supl01HN2NJ9NMRZBXT1H6FT9N7735
name: Fangorn Biomass
currency: GBP
gsp_group: _C
valid_from: '2026-03-17'
valid_until: '2027-03-17'
daily_prices:
peak:
price: '0.30'
times:
- start: '18:00:00'
end: '00:00:00'
mid_peak:
price: '0.20'
times:
- start: '10:00:00'
end: '08:00:00'
off_peak:
price: '0.10'
times:
- start: '08:00:00'
end: '18:00:00'
scheduler_tariff: https://api.ev.energy/v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7835
description: >-
Note: daily_prices and type are only available under contract. Please
reach out to your account manager to find out more.
x-tags:
- Tariffs
allOf:
- $ref: '#/components/schemas/TariffBase'
- type: object
properties:
scheduler_tariff:
oneOf:
- type: string
format: uri
example: >-
https://api.ev.energy/v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7835
- type: object
required:
- id
- url
- supplier
- name
- currency
properties:
id:
type: string
pattern: tari[A-Z\d]{26}
url:
type: string
format: uri
supplier:
type: string
format: uri
name:
type: string
currency:
type: string
additionalProperties: true
- type: 'null'
description: >-
The tariff used by the scheduler for charge optimisation, which
may differ from the billing tariff. Returns a URL by default, or
null if not set. Expandable with ?expand=scheduler_tariff to
return a TariffBase object (additional fields may be present
beyond those listed here).
TariffDetail:
title: TariffDetail
examples:
- id: tari01HN2NJ9NMRZBXT1H6FT9N7735
url: https://api.ev.energy/v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7735
supplier: https://api.ev.energy/v2/suppliers/supl01HN2NJ9NMRZBXT1H6FT9N7735
name: Fangorn Biomass
currency: GBP
daily_prices:
peak:
price: '0.30'
times:
- start: '18:00:00'
end: '00:00:00'
mid_peak:
price: '0.20'
times:
- start: '10:00:00'
end: '08:00:00'
off_peak:
price: '0.10'
times:
- start: '08:00:00'
end: '18:00:00'
scheduler_tariff: https://api.ev.energy/v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7835
current_price: 10
prices: >-
https://api.ev.energy/v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7735/prices
description: >-
Extra fields only included when a single tariff is requested. Note:
prices field requires tariff:prices:read scope and can be expanded with
?expand=prices.
x-tags:
- Tariffs
allOf:
- type: object
properties:
current_price:
type:
- integer
- 'null'
description: >-
The price of the tariff at the current time, given in the
smallest unit of the currency of the tariff. For example, 10
means 10 pence.
example: 10
prices:
oneOf:
- type: string
format: uri
example: >-
https://api.ev.energy/v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7735/prices
- type: array
items:
$ref: '#/components/schemas/Price'
- type: 'null'
description: >-
Link to prices endpoint by default. When expanded with
?expand=prices, returns the past 24 hours of prices. Requires
tariff:prices:read scope.
readOnly: true
- $ref: '#/components/schemas/Tariff'
Supplier:
title: Supplier
type: object
description: An energy company who supplies electricity tariffs.
required:
- id
- url
- name
- icon
properties:
id:
type: string
description: Unique identifier for the given user.
pattern: supl[A-Z\d]{26}
example: supl01HN2NJ9NMRZBXT1H6FT9N7735
readOnly: true
url:
type: string
format: uri
example: https://api.ev.energy/v2/suppliers/supl01HN2NJ9NMRZBXT1H6FT9N7735
name:
type: string
example: Rivendell Renewables
icon:
type:
- string
- 'null'
format: uri
example: https://cdn.example.com/rivendell_renewables.jpg
highlighted:
type: boolean
description: A highlighted supplier is one that is often selected by users.
x-tags:
- Tariffs
DispatchCoordinator:
title: DispatchCoordinator
type: object
description: A resource representing a dispatch coordinator.
properties:
id:
type: string
description: Unique identifier for the dispatch coordinator.
example: dc000000
readOnly: true
url:
type: string
format: uri
example: https://api.ev.energy/v2/dispatch_coordinators/dc000000
readOnly: true
name:
type: string
description: The name of the dispatch coordinator.
example: Acme Energy
readOnly: true
reference_code:
type: string
description: The reference code for the dispatch coordinator.
example: ACME-001
readOnly: true
contract_start:
type:
- string
- 'null'
format: date-time
description: The start date of the contract.
example: '2026-01-01T00:00:00Z'
readOnly: true
contract_end:
type:
- string
- 'null'
format: date-time
description: The end date of the contract.
example: '2027-01-01T00:00:00Z'
readOnly: true
timezone:
type: string
description: The timezone of the dispatch coordinator.
example: America/New_York
readOnly: true
dispatch_logs:
type: string
format: uri
description: Link to the dispatch logs for this coordinator.
example: >-
https://api.ev.energy/v2/dispatch_coordinators/dc000000/dispatch_logs
readOnly: true
x-tags:
- VPP
DispatchLog:
title: DispatchLog
type: object
description: >-
A log entry recording the aggregate fleet charging power for a dispatch
coordinator at a point in time.
properties:
url:
type: string
format: uri
example: >-
https://api.ev.energy/v2/dispatch_coordinators/dc000000/dispatch_logs/2025-03-01T10:00:00Z/
readOnly: true
logged_at:
type: string
format: date-time
description: When this log record was created.
example: '2025-03-01T10:00:00Z'
readOnly: true
total_charge_rate_watts:
type: integer
description: The aggregate charging power of the fleet in watts.
example: 7000
readOnly: true
dispatch_coordinator:
type: string
format: uri
description: Link to the parent dispatch coordinator.
example: https://api.ev.energy/v2/dispatch_coordinators/dc000000
readOnly: true
x-tags:
- VPP
DispatchEvent:
title: DispatchEvent
type: object
description: A dispatch event representing a VPP dispatch operation.
properties:
id:
type: string
description: Unique identifier for the dispatch event.
example: devt01HN2NJ9NMRZBXT1H6FT9N7735
readOnly: true
url:
type: string
format: uri
example: >-
https://api.ev.energy/v2/dispatch_coordinators/dcrd01HN2NJ9NMRZBXT1H6FT9N7735/dispatch_events/devt01HN2NJ9NMRZBXT1H6FT9N7735
readOnly: true
start_time:
type: string
format: date-time
description: Start time of the dispatch event.
example: '2025-06-15T14:00:00Z'
end_time:
type: string
format: date-time
description: End time of the dispatch event.
example: '2025-06-15T18:00:00Z'
import_limit_watts:
type:
- integer
- 'null'
description: Maximum import power in watts.
example: 5000
export_limit_watts:
type:
- integer
- 'null'
description: Maximum export power in watts.
example: null
target_power_watts:
type:
- integer
- 'null'
description: Target power in watts.
example: null
dispatch_coordinator:
type: string
format: uri
description: URL of the parent dispatch coordinator.
example: >-
https://api.ev.energy/v2/dispatch_coordinators/dcrd01HN2NJ9NMRZBXT1H6FT9N7735
readOnly: true
x-tags:
- VPP
DispatchEventCancelResponse:
title: DispatchEventCancelResponse
type: object
description: Response for a dispatch event cancellation request.
properties:
status:
type: string
enum:
- CANCELLED
description: The result of the cancellation request.
example: CANCELLED
x-tags:
- VPP
DispatchEventWrite:
title: DispatchEventWrite
type: object
description: Request body for creating a dispatch event.
required:
- start_time
- end_time
properties:
start_time:
type: string
format: date-time
description: Start time of the dispatch event.
example: '2025-06-15T14:00:00Z'
end_time:
type: string
format: date-time
description: End time of the dispatch event.
example: '2025-06-15T18:00:00Z'
import_limit_watts:
type:
- integer
- 'null'
description: Maximum import power in watts.
example: 5000
export_limit_watts:
type:
- integer
- 'null'
description: Maximum export power in watts.
example: null
target_power_watts:
type:
- integer
- 'null'
description: Target power in watts.
example: null
x-tags:
- VPP
Times:
title: Times
description: Defines a period of time.
type: object
x-tags:
- Tariffs
properties:
start:
type: string
example: '18:00:00'
pattern: \d\d:\d\d:\d\d
end:
type: string
example: '00:00:00'
pattern: \d\d:\d\d:\d\d
PriceSummary:
title: PriceSummary
description: A single price for a certain time range.
type: object
examples:
- price: '0.10'
times:
- start: '18:00:00'
end: '00:00:00'
x-tags:
- Tariffs
properties:
price:
type: string
example: '0.10'
description: The price is in major currency units e.g. 0.10 means £0.10.
times:
type: array
items:
$ref: '#/components/schemas/Times'
DailyPrices:
title: DailyPrices
description: Information about the tariff's prices for different parts of the day.
type: object
additionalProperties: false
minProperties: 1
maxProperties: 3
required:
- peak
properties:
peak:
$ref: '#/components/schemas/PriceSummary'
mid_peak:
$ref: '#/components/schemas/PriceSummary'
off_peak:
$ref: '#/components/schemas/PriceSummary'
x-tags:
- Tariffs
VehicleStatusLog:
title: VehicleStatusLog
description: Records the state of a Vehicle at a particular point in time.
type: object
x-tags:
- Vehicles
properties:
url:
type: string
example: >-
https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H/status_logs/2024-01-01T11:11:11.1111Z/
format: uri
readOnly: true
logged_at:
type: string
description: The date and time this status information was received and stored.
format: date-time
readOnly: true
sampled_at:
type: string
format: date-time
description: >-
The date and time when this data was recorded. Likely to be earlier
than `logged_at`, but how much earlier depends on the integration
and other factors.
vehicle:
oneOf:
- type: string
format: uri
example: https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H
- $ref: '#/components/schemas/Vehicle'
state_of_charge_percentage:
type:
- integer
- 'null'
example: 70
description: >-
How full the vehicle's battery is, as a percentage. Will be null if
we are unable to get this information from the vehicle's telematics.
readOnly: true
is_charging:
type:
- boolean
- 'null'
default: false
description: >-
Is the vehicle currently receiving charge? Will be null if we are
unable to get this information from the vehicle's telematics.
readOnly: true
is_plugged_in:
type:
- boolean
- 'null'
default: false
description: >-
Is the vehicle currently connected to an EVSE? Will be null if we
are unable to get this information from the vehicle's telematics.
readOnly: true
charge_rate_watts:
type:
- integer
- 'null'
description: >-
The current rate of charge being received, in watts. Will be null if
we are unable to get this information from the Vehicle integration.
estimated_charge_rate_watts:
type:
- integer
- 'null'
description: >-
The charge rate in watts estimated from the change in battery charge
level. Useful when the Vehicle integration does not report
charge_rate_watts directly. Will be null if it cannot be estimated.
readOnly: true
charge_level_watt_hours:
type:
- integer
- 'null'
description: >-
The battery charge level in watt hours. Will be null if we are
unable to get this information from the Vehicle integration.
readOnly: true
target_charge_level_percentage:
type:
- integer
- 'null'
description: >-
The target charge level as a percentage. Will be null if we are
unable to get this information from the Vehicle integration.
readOnly: true
target_charge_level_watt_hours:
type:
- integer
- 'null'
description: >-
The target charge level in watt hours. Will be null if we are unable
to get this information from the Vehicle integration.
readOnly: true
charge_energy_added_watt_hours:
type:
- integer
- 'null'
description: >-
The amount of energy added during the most recent charge, as
reported by the vehicle, in watt hours. Will be null if we are
unable to get this information from the Vehicle integration.
readOnly: true
minutes_to_full_charge:
type:
- integer
- 'null'
description: >-
The number of minutes the vehicle predicts until it is fully
charged. Will be null if we are unable to get this information from
the Vehicle integration.
readOnly: true
current_type:
type:
- string
- 'null'
enum:
- AC - Typically home chargers
- DC - Typically OTG chargers
- null
description: >-
The current type of the EVSE the vehicle is connected to (AC or DC).
Will be null if we are unable to get this information from the
Vehicle integration.
readOnly: true
is_complete:
type:
- boolean
- 'null'
description: >-
Whether the vehicle has reached the target charge level. Will be
null if we are unable to get this information from the Vehicle
integration.
readOnly: true
odometer_meters:
type:
- integer
- 'null'
description: >-
The vehicle's odometer reading in meters. Will be null if we are
unable to get this information from the Vehicle integration.
readOnly: true
data_source:
type:
- string
- 'null'
description: The integration that originated this data.
readOnly: true
state:
type:
- string
- 'null'
enum:
- DRIVING
- RECENTLY_FINISHED_DRIVING
- STATIONARY
- IN_SERVICE
- PLUGGED_IN_NOT_CHARGING
- PLUGGED_IN_CHARGING
- PLUGGED_IN_COMPLETE
- PLUGGED_IN_NEAR_READY_BY_TIME
- PLUGGED_IN_ALMOST_COMPLETE
- UNKNOWN
- null
description: >-
The state of the vehicle. Will be null if we are unable to get this
information from the Vehicle integration.
readOnly: true
VehicleAPIErrorLog:
title: VehicleAPIErrorLog
description: >-
Records an error that occurred when attempting to communicate with a
vehicle's telematics API.
type: object
x-tags:
- Vehicles
properties:
url:
type: string
example: >-
https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H/error_logs/2024-04-17T09:39:45.984584Z/
format: uri
readOnly: true
logged_at:
type: string
description: >-
The date and time when this error was logged by the ev.energy
system.
format: date-time
readOnly: true
vehicle:
oneOf:
- type: string
format: uri
example: https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H
- $ref: '#/components/schemas/Vehicle'
status_code:
type: integer
example: 401
description: >-
The HTTP status code of the error response from the vehicle
telematics API.
readOnly: true
controller:
type: string
example: ENODE
description: >-
The vehicle controller/integration that was being used when the
error occurred.
readOnly: true
error_code:
type: string
example: AUTHENTICATION_ERROR
description: >-
The error code received from the provider or determined by the
ev.energy system.
readOnly: true
error_type:
type: string
example: VehicleAPIUnauthorized
description: >-
The error type received from the provider or determined by the
ev.energy system.
readOnly: true
request_id:
type: string
example: 56rst-z2jku-tty9t-0dn2f-qazow
description: >-
The request ID that resulted in this error. Used for tracing and
debugging.
readOnly: true
command:
type: string
example: START_CHARGE
description: The command/method that was being executed when the error occurred.
readOnly: true
error_detail:
type: string
description: Detailed information about the error.
readOnly: true
internal_command_id:
type:
- string
- 'null'
format: uuid
example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
description: >-
Internal UUID to track the command dispatch. This can be used to
correlate errors with commands.
readOnly: true
VehicleLocationLog:
title: VehicleLocationLog
description: >-
Records when location data was sampled for a vehicle. The actual
location coordinates are not exposed through this resource.
type: object
x-tags:
- Vehicles
properties:
url:
type: string
example: >-
https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H/location_logs/2024-04-17T09:39:45.984584Z/
format: uri
readOnly: true
sampled_at:
type: string
description: >-
The date and time when the location data was sampled from the
vehicle (supplied by the API).
format: date-time
readOnly: true
logged_at:
type: string
description: The server time the location event was received at.
format: date-time
readOnly: true
vehicle:
oneOf:
- type: string
format: uri
example: https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H
- $ref: '#/components/schemas/Vehicle'
at_home:
type:
- boolean
- 'null'
description: >-
Whether the vehicle was at the user's home location when this data
was sampled. Will be null if the user has no home location
configured.
readOnly: true
VehicleCommandLog:
title: VehicleCommandLog
description: Records a command that was sent to a vehicle.
type: object
x-tags:
- Vehicles
properties:
url:
type: string
example: >-
https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H/command_logs/2024-04-17T09:39:45.984584Z/
format: uri
readOnly: true
logged_at:
type: string
description: >-
The date and time when this command was logged by the ev.energy
system.
format: date-time
readOnly: true
vehicle:
oneOf:
- type: string
format: uri
example: https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H
- $ref: '#/components/schemas/Vehicle'
command:
type: string
example: START_CHARGE
description: The type of command that was sent to the vehicle.
enum:
- START_CHARGE
- STOP_CHARGE
- WAKE_UP
- SEND_SCHEDULE
readOnly: true
external_command_id:
type:
- string
- 'null'
example: ext-cmd-12345
description: External command ID from the vehicle provider.
readOnly: true
current_milliamps:
type:
- integer
- 'null'
example: 32000
description: >-
If a start/stop command was sent, this is the current level that was
sent in milliamps.
readOnly: true
internal_command_id:
type:
- string
- 'null'
format: uuid
example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
description: >-
Internal UUID to track this command dispatch. This links with device
command logs and error logs.
readOnly: true
EVSECommandLog:
title: EVSECommandLog
description: Records a command that was sent to an EVSE.
type: object
x-tags:
- EVSEs
properties:
url:
type: string
example: >-
https://api.ev.energy/v2/evses/evse01HSH04KDEWF6Z4DB2J77J74K5/command_logs/2024-04-17T09:39:45.984584Z/
format: uri
readOnly: true
logged_at:
type: string
description: >-
The date and time when this command was logged by the ev.energy
system.
format: date-time
readOnly: true
evse:
oneOf:
- type: string
format: uri
example: https://api.ev.energy/v2/evses/evse01HSH04KDEWF6Z4DB2J77J74K5
- $ref: '#/components/schemas/EVSE'
max_load_target_milliamps:
type:
- integer
- 'null'
example: 32000
description: The target maximum load sent to the EVSE, in milliamps.
readOnly: true
is_enabled_target:
type:
- boolean
- 'null'
example: true
description: The target state sent for is_enabled (i.e. free-vend mode).
readOnly: true
always_enabled:
type:
- boolean
- 'null'
example: false
description: >-
Whether the EVSE should always be in is_enabled (i.e. free-vend)
mode.
readOnly: true
reason:
type:
- string
- 'null'
example: SCHEDULED_CHARGING
description: The reason the command was sent to the EVSE.
readOnly: true
enum:
- SCHEDULED_CHARGING
- REFRESH_SCHEDULES
- STOP_CHARGE
- START_CHARGE
- SOLAR_CHARGE_NIGHTTIME_CHARGE_RATE
- API_TRIGGERED_COMMAND
- COMMISSIONING
- CHARGING_SESSION
- VEHICLE_TO_HOME
- FREE_VEND
- MAINTAIN_EVSE_STATE
- CREATE_HOME_CHARGER
- LOCKED_MODE
- SMART_CHARGE_ENABLED_CHANGED
- SMART_CHARGE_ENABLED
- SMART_CHARGE_DISABLED
internal_command_id:
type:
- string
- 'null'
format: uuid
example: d4e5f6a7-b8c9-0123-def0-123456789abc
description: >-
Internal UUID to track this command dispatch. This links with device
command logs.
readOnly: true
EVSEAPIErrorLog:
title: EVSEAPIErrorLog
description: >-
Records an error that occurred when attempting to communicate with an
EVSE's hardware API.
type: object
x-tags:
- EVSEs
properties:
url:
type: string
example: >-
https://api.ev.energy/v2/evses/evse01HSH04KDEWF6Z4DB2J77J74K5/error_logs/2024-04-17T09:39:45.984584Z/
format: uri
readOnly: true
sampled_at:
type: string
description: >-
The date and time when this error was sampled by the ev.energy
system.
format: date-time
readOnly: true
evse:
oneOf:
- type: string
format: uri
example: https://api.ev.energy/v2/evses/evse01HSH04KDEWF6Z4DB2J77J74K5
- $ref: '#/components/schemas/EVSE'
status_code:
type:
- integer
- 'null'
example: 401
description: >-
The HTTP status code of the error response from the EVSE hardware
API.
readOnly: true
controller:
type: string
example: OCPP
description: >-
The EVSE controller/integration that was being used when the error
occurred.
readOnly: true
error_code:
type:
- string
- 'null'
example: AUTHENTICATION_ERROR
description: >-
The error code received from the provider or determined by the
ev.energy system.
readOnly: true
error_type:
type:
- string
- 'null'
example: HardwareAPIUnauthorized
description: >-
The error type received from the provider or determined by the
ev.energy system.
readOnly: true
error_detail:
type:
- string
- 'null'
description: Detailed information about the error.
readOnly: true
external_request_id:
type:
- string
- 'null'
example: req-12345
description: >-
The external request ID that resulted in this error. Used for
tracing and debugging.
readOnly: true
internal_command_id:
type:
- string
- 'null'
format: uuid
example: d4e5f6a7-b8c9-0123-def0-123456789abc
description: >-
Internal UUID to track the command dispatch. This can be used to
correlate errors with commands.
readOnly: true
EVSEOCPPCallResponse:
title: EVSEOCPPCallResponse
description: The response to an OCPP call message.
type: object
properties:
sampled_at:
type: string
format: date-time
description: The date and time when this response was recorded.
readOnly: true
payload:
type: object
description: The OCPP response payload.
readOnly: true
error_code:
type: string
description: The OCPP error code for this response.
readOnly: true
example: NoError
enum:
- NoError
- NotImplemented
- NotSupported
- InternalError
- ProtocolError
- SecurityError
- FormationViolation
- PropertyConstraintViolation
- OccurenceConstraintViolation
- TypeConstraintViolation
- GenericError
- UnknownError
error_description:
type:
- string
- 'null'
description: A human-readable description of the error, if any.
readOnly: true
EVSEOCPPLog:
title: EVSEOCPPLog
description: Records an OCPP message sent to or received from an EVSE.
type: object
x-tags:
- EVSEs
properties:
url:
type: string
example: >-
https://api.ev.energy/v2/evses/evse01HSH04KDEWF6Z4DB2J77J74K5/ocpp_logs/2024-04-17T09:39:45.984584Z/
format: uri
readOnly: true
sampled_at:
type: string
description: The date and time when this OCPP message was recorded.
format: date-time
readOnly: true
evse:
oneOf:
- type: string
format: uri
example: https://api.ev.energy/v2/evses/evse01HSH04KDEWF6Z4DB2J77J74K5
- $ref: '#/components/schemas/EVSE'
direction:
type: string
description: Whether the message was sent to or received from the charger.
readOnly: true
example: Sent
enum:
- Sent
- Received
action:
type: string
description: The OCPP action label for this message.
readOnly: true
example: StatusNotification
enum:
- Authorize
- BootNotification
- CancelReservation
- CertificateSigned
- ChangeAvailability
- ChangeConfiguration
- ClearCache
- ClearChargingProfile
- DataTransfer
- DeleteCertificate
- DiagnosticsStatusNotification
- ExtendedTriggerMessage
- FirmwareStatusNotification
- GetCompositeSchedule
- GetConfiguration
- GetDiagnostics
- GetInstalledCertificateIds
- GetLocalListVersion
- GetLog
- Heartbeat
- InstallCertificate
- LogStatusNotification
- MeterValues
- RemoteStartTransaction
- RemoteStopTransaction
- ReserveNow
- Reset
- SecurityEventNotification
- SendLocalList
- SetChargingProfile
- SignCertificate
- SignedFirmwareStatusNotification
- SignedUpdateFirmware
- StartTransaction
- StatusNotification
- StopTransaction
- TriggerMessage
- UnlockConnector
- UpdateFirmware
payload:
type: object
description: The OCPP message payload.
readOnly: true
message_id:
type: string
description: >-
The unique message ID for this OCPP call. Can be a UUID, integer, or
string.
readOnly: true
example: abc-123
response:
description: The response to this OCPP call, if one has been received.
oneOf:
- $ref: '#/components/schemas/EVSEOCPPCallResponse'
- type: 'null'
RebateType:
x-internal: true
description: A resource representing a rebate a user can apply for.
title: RebateType
type: object
example:
id: rbttB1USP6YGD1VPIDJSHTZARUX11M
url: https://api.ev.energy/v2/rebate_types/rbttB1USP6YGD1VPIDJSHTZARUX11M
title: Vehicle Enrollment
value_description: earn up to $1000
icon: https://example.com
description_long: Rebate for purchasing an eligible vehicle.
description_short: Must be purchased after 11/01/2024
requirements: >-
- Must be eligible for program
- Purchased after
11/01/2024
- Must be connected to ev.energy
required_evidence:
- title: string
description: string
upload_required: true
file:
name: string
url: https://example.com
evidence_data:
- data_type: currency
title: string
description: string
required: true
value: string
properties:
id:
type: string
description: Unique identifier for the RebateType
readOnly: true
url:
type: string
format: uri
readOnly: true
title:
type: string
description: Display name.
readOnly: true
value_description:
type: string
description: Short text describing the rebate value.
example: earn up to $1000
readOnly: true
icon:
type:
- string
- 'null'
format: uri
description: URI for an icon representing this rebate type.
readOnly: true
description_long:
type:
- string
- 'null'
description: Describes the rebate type.
readOnly: true
description_short:
type:
- string
- 'null'
description: >-
One line of text containing important information for the rebate
type.
example: Must be purchased after 11/01/2024
readOnly: true
requirements:
type: string
description: HTML string containing detailed eligibility requirements.
example: >-
- Must be eligible for program
- Purchased after
11/01/2024
- Must be connected to ev.energy
format: html
readOnly: true
required_evidence:
type: array
items:
oneOf:
- $ref: '#/components/schemas/RebateEvidenceType'
- type: string
format: uri
example: >-
https://api.ev.energy/v2/rebate_evidence_types/rbetB1USP6YGD1VPIDJSHTZARUX11M
UserRebate:
type: object
x-examples:
Example 1:
id: rbtuB1USP6YGD1VPIDJSHTZARUX11M
url: https://api.ev.energy/v2/user_rebates/rbtuB1USP6YGD1VPIDJSHTZARUX11M
description: Resource representing a user's rebate application.
x-internal: true
title: UserRebate
examples:
- id: string
url: https://example.com
status: PENDING_IN_PROGRESS
rebate_type:
id: string
url: https://example.com
title: string
value_description: earn up to $1000
icon: https://example.com
description_long: string
description_short: Must be purchased after 11/01/2024
requirements: >-
- Must be eligible for program
- Purchased
after 11/01/2024
- Must be connected to
ev.energy
required_evidence:
- title: string
description: string
upload_required: true
file:
name: string
url: string
evidence_data:
- data_type: currency
title: string
description: string
required: true
value: string
properties:
id:
type: string
readOnly: true
url:
type: string
format: uri
readOnly: true
status:
enum:
- NOT_STARTED
- PENDING_TYPE_SELECTED
- PENDING_IN_PROGRESS
- COMPLETE
description: >-
Status of the user's rebate application form. This does not indicate
if the rebate has been reviewed or approved.
readOnly: true
rebate_type:
oneOf:
- type: string
format: uri
example: >-
https://api.ev.energy/v2/rebate_types/rbttB1USP6YGD1VPIDJSHTZARUX11M
- $ref: '#/components/schemas/RebateType'
RebateEvidenceType:
type: object
description: >-
Resource representing a type of evidence required for a rebate
application.
x-internal: true
required:
- title
- description
- upload_required
- evidence_data
properties:
id:
type: string
example: rbetB1USP6YGD1VPIDJSHTZARUX11M
pattern: rbet[A-Z\d]{26}
readOnly: true
url:
type: string
format: uri
example: >-
https://api.ev.energy/v2/rebate_evidence_types/rbetB1USP6YGD1VPIDJSHTZARUX11M
readOnly: true
title:
type: string
description:
type:
- string
- 'null'
upload_required:
type: boolean
description: Whether we require the user to upload a file.
file:
type:
- object
- 'null'
description: File uploaded by user as evidence.
properties:
name:
type: string
description: File name.
url:
type: string
format: uri
description: Pre-signed AWS URL for viewing the file.
evidence_data:
type: array
items:
$ref: '#/components/schemas/RebateEvidenceSupportingData'
RebateEvidenceSupportingData:
type: object
x-examples:
Example 1:
data_type: currency
title: Total project cost
description: Enter the total amount spent on the project
required: true
value: '1000'
x-internal: true
description: >-
Resource representing data required as evidence for a rebate
application.
title: RebateEvidenceSupportingData
examples:
- data_type: currency
title: string
description: string
required: true
value: string
required:
- data_type
- title
- description
- required
properties:
data_type:
enum:
- currency
- string
title:
type: string
example: Invoice
description:
type: string
example: An invoice for solar panel installation
required:
type: boolean
description: Whether this data is required.
value:
type:
- string
- 'null'
description: Value entered in the user's application.
UserRebateCreated:
title: UserRebateCreated
x-tags:
- Rebates
type: object
properties:
id:
type: string
description: UID of the new UserRebate object.
readOnly: true
url:
type: string
format: uri
readOnly: true
examples:
- id: rbtuB1USP6YGD1VPIDJSHTZARUX11M
url: https://api.ev.energy/v2/user_rebates/rbtuB1USP6YGD1VPIDJSHTZARUX11M
x-internal: true
description: Resource representing a newly created UserRebate object.
RebateEvidenceFile:
title: RebateEvidenceFile
type: object
description: Resource representing a rebate evidence file
examples:
- id: rbefB1USP6YGD1VPIDJSHTZARUX11M
url: >-
https://api.ev.energy/v2/user_rebates/rbtuB1USP6YGD1VPIDJSHTZARUX11M/evidence_files/rbefB1USP6YGD1VPIDJSHTZARUX11M
file_name: test_file.pdf
rebate_evidence_type: >-
https://api.ev.energy/v2/rebate_evidence_type/rbetB1USP6YGD1VPIDJSHTZARUX11M
properties:
id:
type: string
url:
type: string
file_name:
type: string
rebate_evidence_type:
oneOf:
- type: string
format: uri
example: >-
https://api.ev.energy/v2/rebate_evidence_type/rbetB1USP6YGD1VPIDJSHTZARUX11M
- $ref: '#/components/schemas/RebateEvidenceType'
EVSEStatusLog:
title: EVSEStatusLog
description: Records the state of an EVSE at a particular point in time.
type: object
x-tags:
- EVSEs
properties:
url:
type: string
format: uri
example: >-
https://api.ev.energy/v2/evse/evse01HSH04KDEWF6Z4DB2J77J74K5/status_logs/2024-01-01T11:11:11.1111Z/
readOnly: true
sampled_at:
type: string
format: date-time
description: The date and time this status information was sampled on the EVSE.
logged_at:
type: string
format: date-time
description: >-
The date and time when this data was recorded. Likely to be later
than `sampled_at`, but how much later depends on the integration and
other factors.
evse:
oneOf:
- type: string
format: uri
example: https://api.ev.energy/v2/evses/evse01HSH04KDEWF6Z4DB2J77J74K5
- $ref: '#/components/schemas/EVSE'
is_plugged_in:
type:
- boolean
- 'null'
description: >-
Is there currently a vehicle connected to the EVSE? Will be null if
we are unable to get this information from the EVSE integration.
is_charging:
type:
- boolean
- 'null'
description: >-
Is the EVSE currently delivering charge? Will be null if we are
unable to get this information from the EVSE integration.
charge_rate_watts:
type:
- integer
- 'null'
description: >-
The current rate of charge delivery, in watts. Will be null if we
are unable to get this information from the EVSE integration.
export_power_watts:
type:
- integer
- 'null'
description: >-
Power flowing from the vehicle to the grid (V2X), in watts. Will be
null when the EVSE does not report export power or is not
bidirectional.
readOnly: true
control_pilot_status:
type:
- string
- 'null'
enum:
- A
- B
- C
- D
- E
- F
- null
description: >-
The SAE J1772 Control Pilot state of the EVSE. Will be null if we
are unable to get this information from the EVSE integration.
- `A`: Standby (no vehicle connected).
- `B`: Vehicle detected (plugged in, not charging).
- `C`: Ready / charging (drawing power, no ventilation required).
- `D`: Charging with ventilation required.
- `E`: No power (shut off).
- `F`: Error / fault.
readOnly: true
meter_reading_watt_hours:
type:
- integer
- 'null'
description: >-
The meter reading in watt hours. Will be null if we are unable to
get this information from the EVSE integration.
readOnly: true
is_enabled:
type:
- boolean
- 'null'
description: >-
Whether the EVSE is enabled (free-vend mode). Will be null if we are
unable to get this information from the EVSE integration.
readOnly: true
max_current_rating_milliamps:
type:
- integer
- 'null'
description: >-
The maximum current the EVSE will allow the car to draw, in
milliamps. Will be null if we are unable to get this information
from the EVSE integration.
readOnly: true
cable_current_rating_milliamps:
type:
- integer
- 'null'
description: >-
The maximum current the cable is rated for, in milliamps. Will be
null if we are unable to get this information from the EVSE
integration.
readOnly: true
signal_strength_rssi_dbm:
type:
- integer
- 'null'
description: >-
The signal strength (RSSI) the EVSE reported, in dBm. Will be null
if we are unable to get this information from the EVSE integration.
readOnly: true
inlet_power_watts:
type:
- integer
- 'null'
description: >-
Power measured by the EVSE at the property supply inlet, in watts.
Will be null if we are unable to get this information from the EVSE
integration.
readOnly: true
voltage_millivolts:
type:
- integer
- 'null'
description: >-
Voltage measured by the EVSE, in millivolts. Will be null if we are
unable to get this information from the EVSE integration.
readOnly: true
state_of_charge_percentage:
type:
- integer
- 'null'
description: >-
Battery charge level as a percentage, as received via the EVSE. Will
be null if we are unable to get this information from the EVSE
integration.
readOnly: true
mode:
type:
- string
- 'null'
enum:
- null
- Unknown
- Idle
- Delay
- Charge
- Discharge
- FFR
- Load match
- Export match
- Peak time
- Deep sleep
description: >-
Operating mode reported by the EVSE. Will be null if we are unable
to get this information from the EVSE integration.
readOnly: true
InverterStatusLog:
title: InverterStatusLog
type: object
description: Records the state of an Inverter at a particular point in time.
properties:
url:
type: string
format: uri
example: https://api.ev.energy/v2/inverters/invtB1USP6YGD1VPIDJSHTZARUX11M
sampled_at:
type: string
format: date-time
logged_at:
type: string
format: date-time
inverter:
oneOf:
- $ref: '#/components/schemas/Inverter'
- type: string
format: uri
solar_power_watts:
type: integer
example: 1000
minimum: 0
status:
type: string
readOnly: true
description: Derived operating state, inferred from solar_power_watts.
enum:
- PRODUCING
- CONSUMING
- IDLE
- UNKNOWN
example: PRODUCING
InverterMake:
title: InverterMake
type: object
description: A resource representing a manufacturer of inverters.
required:
- id
- url
- name
- icon
properties:
id:
type: string
description: Unique identifier for the given Inverter Make.
pattern: imak[A-Z\d]{26}
example: imakNN2Q3R3TKF9XJQ7851PAUR56UX
readOnly: true
url:
type: string
format: uri
example: >-
https://api.ev.energy/v2/inverter_makes/imakNN2Q3R3TKF9XJQ7851PAUR56UX
readOnly: true
name:
type: string
example: Fronius
readOnly: true
icon:
type:
- string
- 'null'
format: uri
example: https://cdn.example.com/fronius.jpg
readOnly: true
onboarding_url:
type:
- string
- 'null'
example: >-
https://api.ev.energy/v2/inverter_oboarding?user_id=user01HN2NJ9NMRZBXT1H6FT9N7735&make_id=imakWNZ5N0A5D1PR89HJ7STXEWYO58
description: >-
If using Client credentials the URL will not contain a user ID. This
will have to be added by the client so the inverter is created for
the correct user.
inverter_models:
type: string
format: uri
example: >-
https://api.ev.energy/v2/inverter_models/?make_id=imakWNZ5N0A5D1PR89HJ7STXEWYO58
description: >-
A pre-constructed link to a list of inverter models filtered for
this make.
readOnly: true
InverterModel:
title: InverterModel
type: object
description: A resource representing an inverter model.
required:
- id
- url
- name
properties:
id:
type: string
description: Unique identifier for the given Inverter Model.
pattern: imod[A-Z\d]{26}
example: imodOTQRGK9OKMPDU63SYGJ9T6FH3A
readOnly: true
url:
type: string
format: uri
example: >-
https://api.ev.energy/v2/inverter_models/imodOTQRGK9OKMPDU63SYGJ9T6FH3A
readOnly: true
name:
type: string
example: Symo 5.0
readOnly: true
make:
oneOf:
- type: string
format: uri
example: >-
https://api.ev.energy/v2/inverter_makes/imakNN2Q3R3TKF9XJQ7851PAUR56UX
- $ref: '#/components/schemas/InverterMake'
onboarding_url:
type:
- string
- 'null'
example: >-
https://api.ev.energy/v2/inverter_oboarding?user_id=user01HN2NJ9NMRZBXT1H6FT9N7735&model_id=imodWNZ5N0A5D1PR89HJ7STXEWYO58
description: >-
If using Client credentials the URL will not contain a user ID. This
will have to be added by the client so the inverter is created for
the correct user.
HomeBatteryMake:
title: HomeBatteryMake
description: A resource representing a manufacturer of home batteries.
type: object
x-tags:
- Home Batteries
properties:
id:
type: string
description: Unique identifier for the given Home Battery Make.
pattern: bmak[A-Z\d]{26}
example: bmakK7XDPL63NNBDQ5DPB6K3TP87JA
readOnly: true
url:
type: string
format: uri
example: >-
https://api.ev.energy/v2/home_battery_makes/bmakK7XDPL63NNBDQ5DPB6K3TP87JA
readOnly: true
name:
type: string
example: Rivendell
readOnly: true
icon:
type:
- string
- 'null'
format: uri
example: https://cdn.example.com/rivendell.png
description: A url for an image of the make's logo.
readOnly: true
onboarding_url:
type:
- string
- 'null'
example: >-
https://api.ev.energy/v2/home_battery_onboarding?make_id=bmakK7XDPL63NNBDQ5DPB6K3TP87JA&user_id=user01HN2NJ9NMRZBXT1H6FT9N7735&client_id=your_client_id
description: >-
A pre-constructed link to initiate onboarding for a home battery of
this make. If it is null, then it cannot be onboarded with make
alone. You should filter the list of [home battery
models](ev.energy-API-v2.yaml/paths/~1home_battery_models/get) by
this make and then have the user select their model.
Your `client_id` and the user's `user_id` are automatically included
based on your authentication token. If you are using client
credentials authentication, the user ID will not be automatically
included unless you set the EvEnergy-User header on your request.
readOnly: true
models:
type: string
format: uri
example: >-
https://api.ev.energy/v2/home_battery_models?make_id=bmakK7XDPL63NNBDQ5DPB6K3TP87JA
description: >-
A pre-constructed link to a list of home battery models filtered for
this make.
readOnly: true
HomeBatteryModel:
title: HomeBatteryModel
description: A resource representing a home battery model.
type: object
x-tags:
- Home Batteries
properties:
id:
type: string
description: Unique identifier for the given Home Battery Model.
pattern: bmod[A-Z\d]{26}
example: bmod7XL7Q5294J6TUZARBQT2D1EOHY
readOnly: true
url:
type: string
format: uri
example: >-
https://api.ev.energy/v2/home_battery_models/bmod7XL7Q5294J6TUZARBQT2D1EOHY
readOnly: true
name:
type: string
example: Narsil
readOnly: true
make:
oneOf:
- type: string
format: uri
example: >-
https://api.ev.energy/v2/home_battery_makes/bmakK7XDPL63NNBDQ5DPB6K3TP87JA
- $ref: '#/components/schemas/HomeBatteryMake'
onboarding_url:
type:
- string
- 'null'
format: uri
example: >-
https://api.ev.energy/v2/home_battery_onboarding?model_id=bmod7XL7Q5294J6TUZARBQT2D1EOHY&user_id=user01HN2NJ9NMRZBXT1H6FT9N7735&client_id=your_client_id
description: >-
A pre-constructed link to initiate onboarding for a home battery of
this model.
Your `client_id` and the user's `user_id` are automatically included
based on your authentication token. If you are using client
credentials authentication, the user ID will not be automatically
included unless you set the EvEnergy-User header on your request.
readOnly: true
Inverter:
title: Inverter
type: object
description: A resource that represents a single, physical inverter.
required:
- id
- url
properties:
id:
type: string
description: Unique identifier for the given Inverter.
pattern: invt[A-Z\d]{26}
example: invtB1USP6YGD1VPIDJSHTZARUX11M
readOnly: true
url:
type: string
format: uri
example: https://api.ev.energy/v2/inverters/invtB1USP6YGD1VPIDJSHTZARUX11M
readOnly: true
model:
oneOf:
- type: string
format: uri
example: >-
https://api.ev.energy/v2/inverter_models/imodOTQRGK9OKMPDU63SYGJ9T6FH3A
- $ref: '#/components/schemas/InverterModel'
created_at:
type:
- string
- 'null'
format: date-time
description: When this inverter was connected to the platform.
example: '2024-02-10T16:45:00Z'
readOnly: true
latest_status_log:
oneOf:
- $ref: '#/components/schemas/InverterStatusLog'
- type:
- string
- 'null'
example: >-
https://api.ev.energy/v2/inverters/invtB1USP6YGD1VPIDJSHTZARUX11M/status_logs/2024-07-23T16:01:45.994584Z/
onboarding_url:
type:
- string
- 'null'
example: >-
https://api.ev.energy/v2/inverter_oboarding?inverter_id=invtB1USP6YGD1VPIDJSHTZARUX11M
HomeBattery:
title: HomeBattery
type: object
description: A resource that represents a single, physical home battery.
x-tags:
- Home Batteries
required:
- id
- url
properties:
id:
type: string
description: Unique identifier for the given Home Battery.
pattern: hoba[A-Z\d]{26}
example: hoba01J5DCXX8DMJDJYGVR1DW4J7AA
readOnly: true
url:
type: string
format: uri
example: >-
https://api.ev.energy/v2/home_batteries/hoba01J5DCXX8DMJDJYGVR1DW4J7AA
readOnly: true
model:
oneOf:
- type: string
format: uri
example: >-
https://api.ev.energy/v2/home_battery_models/bmod7XL7Q5294J6TUZARBQT2D1EOHY
- $ref: '#/components/schemas/HomeBatteryModel'
created_at:
type:
- string
- 'null'
format: date-time
description: When this home battery was connected to the platform.
example: '2024-03-15T14:22:33.123456Z'
readOnly: true
latest_status_log:
oneOf:
- $ref: '#/components/schemas/HomeBatteryStatusLog'
- type:
- string
- 'null'
example: >-
https://api.ev.energy/v2/home_batteries/hoba01J5DCXX8DMJDJYGVR1DW4J7AA/status_logs/2024-04-17T09:39:45.984584Z/
description: >-
Link by default, expanded data when ?expand=latest_status_log is
used.
HomeBatteryStatusLog:
title: HomeBatteryStatusLog
type: object
description: Records the state of a home battery at a particular point in time.
x-tags:
- Home Batteries
properties:
url:
type: string
format: uri
example: >-
https://api.ev.energy/v2/home_batteries/hoba01J5DCXX8DMJDJYGVR1DW4J7AA/status_logs/2024-04-17T09:39:45.984584Z/
sampled_at:
type: string
format: date-time
home_battery:
oneOf:
- $ref: '#/components/schemas/HomeBattery'
- type: string
format: uri
example: >-
https://api.ev.energy/v2/home_batteries/hoba01J5DCXX8DMJDJYGVR1DW4J7AA
capacity_watt_hours:
type:
- integer
- 'null'
description: The total capacity of the battery in Wh.
example: 13500
state_of_charge_percentage:
type:
- integer
- 'null'
description: Remaining battery charge level as a whole percentage (0-100).
example: 82
charge_rate_watts:
type:
- integer
- 'null'
description: Current charge rate in W. A positive value indicates charging.
example: 2200
discharge_limit_percentage:
type:
- integer
- 'null'
description: Minimum reserve charge level as a whole percentage (0-100).
example: 20
status:
type: string
readOnly: true
description: Derived operating state of the battery.
enum:
- CHARGING
- DISCHARGING
- IDLE
- FAULT
- UNKNOWN
example: CHARGING
operation_mode:
type: string
readOnly: true
description: Current operation mode of the battery.
enum:
- EXPORT_FOCUS
- IMPORT_FOCUS
- TIME_OF_USE
- SELF_RELIANCE
- IDLE
- UNKNOWN
example: SELF_RELIANCE
HEMSystem:
title: HEMSystem
type: object
description: >-
A resource representing a Home Energy Management (HEM) system, which
aggregates boundary meters, home batteries, and inverters.
x-tags:
- HEM Systems
required:
- id
- url
- created_at
properties:
id:
type: string
description: Unique identifier for the given HEM system.
pattern: hems[A-Z\d]{26}
example: hems01J5DCXX8DMJDJYGVR1DW4J7AA
readOnly: true
url:
type: string
format: uri
example: https://api.ev.energy/v2/hem_systems/hems01J5DCXX8DMJDJYGVR1DW4J7AA
readOnly: true
created_at:
type: string
format: date-time
description: The date and time when this HEM system was created.
example: '2024-03-15T14:22:33.123456Z'
readOnly: true
HEMSystemLivePower:
title: HEMSystemLivePower
type: object
description: >-
Live power data for a HEM system, including raw measurements and derived
power flows.
x-tags:
- HEM Systems
required:
- sampled_at
- generation_watts
- consumption_watts
- import_watts
- export_watts
- charge_watts
- discharge_watts
- solar_to_home_watts
- solar_to_battery_watts
- solar_to_grid_watts
- battery_to_home_watts
- battery_to_grid_watts
- grid_to_home_watts
- grid_to_battery_watts
- battery_state_of_charge_percentage
properties:
sampled_at:
type: string
format: date-time
description: The timestamp of the energy statistics period.
example: '2024-06-15T12:00:00Z'
readOnly: true
generation_watts:
type:
- integer
- 'null'
description: Solar generation power in watts. Null if inverter stats unavailable.
example: 3000
readOnly: true
consumption_watts:
type:
- integer
- 'null'
description: >-
Household consumption power in watts. Null if any required stats
unavailable.
example: 2400
readOnly: true
import_watts:
type:
- integer
- 'null'
description: >-
Power imported from the grid in watts. Null if any required stats
unavailable.
example: 1200
readOnly: true
export_watts:
type:
- integer
- 'null'
description: >-
Power exported to the grid in watts. Null if any required stats
unavailable.
example: 600
readOnly: true
charge_watts:
type:
- integer
- 'null'
description: >-
Battery charging power in watts. Null if any required stats
unavailable.
example: 1800
readOnly: true
discharge_watts:
type:
- integer
- 'null'
description: >-
Battery discharging power in watts. Null if any required stats
unavailable.
example: 900
readOnly: true
solar_to_home_watts:
type:
- integer
- 'null'
description: >-
Derived power flow from solar to home in watts. Null if any required
stats unavailable.
example: 1500
readOnly: true
solar_to_battery_watts:
type:
- integer
- 'null'
description: >-
Derived power flow from solar to battery in watts. Null if any
required stats unavailable.
example: 1000
readOnly: true
solar_to_grid_watts:
type:
- integer
- 'null'
description: >-
Derived power flow from solar to grid in watts. Null if any required
stats unavailable.
example: 500
readOnly: true
battery_to_home_watts:
type:
- integer
- 'null'
description: >-
Derived power flow from battery to home in watts. Null if any
required stats unavailable.
example: 700
readOnly: true
battery_to_grid_watts:
type:
- integer
- 'null'
description: >-
Derived power flow from battery to grid in watts. Null if any
required stats unavailable.
example: 200
readOnly: true
grid_to_home_watts:
type:
- integer
- 'null'
description: >-
Derived power flow from grid to home in watts. Null if any required
stats unavailable.
example: 200
readOnly: true
grid_to_battery_watts:
type:
- integer
- 'null'
description: >-
Derived power flow from grid to battery in watts. Null if any
required stats unavailable.
example: 100
readOnly: true
battery_state_of_charge_percentage:
type:
- integer
- 'null'
description: >-
Battery state of charge as a percentage (0-100). Null if
unavailable.
example: 82
readOnly: true
HEMSystemEnergyStatsBucket:
title: HEMSystemEnergyStatsBucket
type: object
description: A single bucket of aggregated energy statistics for a HEM system.
x-tags:
- HEM Systems
required:
- period_start
- period_end
- generation_wh
- consumption_wh
- import_wh
- export_wh
- charge_wh
- discharge_wh
- avg_battery_state_of_charge_percentage
- solar_to_home_wh
- solar_to_battery_wh
- solar_to_grid_wh
- battery_to_home_wh
- battery_to_grid_wh
- grid_to_home_wh
- grid_to_battery_wh
properties:
period_start:
type: string
format: date-time
description: Start of the aggregation period.
example: '2024-06-01T00:00:00Z'
readOnly: true
period_end:
type: string
format: date-time
description: End of the aggregation period.
example: '2024-06-01T00:30:00Z'
readOnly: true
generation_wh:
type:
- integer
- 'null'
description: Solar generation energy in watt-hours. Null if unavailable.
example: 1500
readOnly: true
consumption_wh:
type:
- integer
- 'null'
description: Household consumption energy in watt-hours. Null if unavailable.
example: 1200
readOnly: true
import_wh:
type:
- integer
- 'null'
description: Energy imported from the grid in watt-hours. Null if unavailable.
example: 600
readOnly: true
export_wh:
type:
- integer
- 'null'
description: Energy exported to the grid in watt-hours. Null if unavailable.
example: 300
readOnly: true
charge_wh:
type:
- integer
- 'null'
description: Battery charging energy in watt-hours. Null if unavailable.
example: 900
readOnly: true
discharge_wh:
type:
- integer
- 'null'
description: Battery discharging energy in watt-hours. Null if unavailable.
example: 450
readOnly: true
avg_battery_state_of_charge_percentage:
type:
- integer
- 'null'
description: >-
Average battery state of charge as a percentage (0-100). Null if
unavailable.
example: 75
readOnly: true
solar_to_home_wh:
type:
- integer
- 'null'
description: Energy flow from solar to home in watt-hours. Null if unavailable.
example: 750
readOnly: true
solar_to_battery_wh:
type:
- integer
- 'null'
description: >-
Energy flow from solar to battery in watt-hours. Null if
unavailable.
example: 500
readOnly: true
solar_to_grid_wh:
type:
- integer
- 'null'
description: Energy flow from solar to grid in watt-hours. Null if unavailable.
example: 250
readOnly: true
battery_to_home_wh:
type:
- integer
- 'null'
description: Energy flow from battery to home in watt-hours. Null if unavailable.
example: 350
readOnly: true
battery_to_grid_wh:
type:
- integer
- 'null'
description: Energy flow from battery to grid in watt-hours. Null if unavailable.
example: 100
readOnly: true
grid_to_home_wh:
type:
- integer
- 'null'
description: Energy flow from grid to home in watt-hours. Null if unavailable.
example: 100
readOnly: true
grid_to_battery_wh:
type:
- integer
- 'null'
description: Energy flow from grid to battery in watt-hours. Null if unavailable.
example: 50
readOnly: true
HEMSystemEnergyStatsResponse:
title: HEMSystemEnergyStatsResponse
type: object
description: Aggregated energy statistics response for a HEM system.
x-tags:
- HEM Systems
required:
- resolution
- start
- end
- buckets
properties:
resolution:
type: string
enum:
- PT30M
- P1D
- P1M
description: >-
The aggregation resolution: PT30M (30 minutes), P1D (1 day), or P1M
(1 month).
example: P1D
readOnly: true
start:
type: string
format: date-time
description: Start of the requested time range.
example: '2024-06-01T00:00:00Z'
readOnly: true
end:
type: string
format: date-time
description: End of the requested time range.
example: '2024-06-30T23:59:59Z'
readOnly: true
buckets:
type: array
items:
$ref: '#/components/schemas/HEMSystemEnergyStatsBucket'
description: List of aggregated energy statistics buckets.
readOnly: true
BoundaryMeterMake:
title: BoundaryMeterMake
type: object
description: A resource representing a manufacturer of boundary meters.
x-tags:
- Boundary Meters
required:
- id
- url
- name
properties:
id:
type: string
description: Unique identifier for the given Boundary Meter Make.
pattern: bmma[A-Z\d]{26}
example: bmma01J5DCXX8DMJDJYGVR1DW4M001
readOnly: true
url:
type: string
format: uri
example: >-
https://api.ev.energy/v2/boundary_meter_makes/bmma01J5DCXX8DMJDJYGVR1DW4M001
readOnly: true
name:
type: string
example: Gondor
readOnly: true
BoundaryMeterModel:
title: BoundaryMeterModel
type: object
description: A resource representing a boundary meter model.
x-tags:
- Boundary Meters
required:
- id
- url
- name
properties:
id:
type: string
description: Unique identifier for the given Boundary Meter Model.
pattern: bmmo[A-Z\d]{26}
example: bmmo01J5DCXX8DMJDJYGVR1DW4D001
readOnly: true
url:
type: string
format: uri
example: >-
https://api.ev.energy/v2/boundary_meter_models/bmmo01J5DCXX8DMJDJYGVR1DW4D001
readOnly: true
name:
type: string
example: Anduril
readOnly: true
make:
oneOf:
- type: string
format: uri
example: >-
https://api.ev.energy/v2/boundary_meter_makes/bmma01J5DCXX8DMJDJYGVR1DW4M001
- $ref: '#/components/schemas/BoundaryMeterMake'
BoundaryMeter:
title: BoundaryMeter
type: object
description: A resource that represents a single, physical boundary meter.
x-tags:
- Boundary Meters
required:
- id
- url
properties:
id:
type: string
description: Unique identifier for the given Boundary Meter.
pattern: bmet[A-Z\d]{26}
example: bmet01J5DCXX8DMJDJYGVR1DW4T001
readOnly: true
url:
type: string
format: uri
example: >-
https://api.ev.energy/v2/boundary_meters/bmet01J5DCXX8DMJDJYGVR1DW4T001
readOnly: true
model:
oneOf:
- type: string
format: uri
example: >-
https://api.ev.energy/v2/boundary_meter_models/bmmo01J5DCXX8DMJDJYGVR1DW4D001
- $ref: '#/components/schemas/BoundaryMeterModel'
created_at:
type: string
format: date-time
readOnly: true
description: When the boundary meter was first connected to ev.energy.
example: '2024-01-10T12:00:00Z'
latest_status_log:
oneOf:
- $ref: '#/components/schemas/BoundaryMeterStatusLog'
- type:
- string
- 'null'
example: >-
https://api.ev.energy/v2/boundary_meters/bmet01J5DCXX8DMJDJYGVR1DW4T001/status_logs/2024-04-17T09:39:45.984584Z/
description: >-
Link by default, expanded data when ?expand=latest_status_log is
used.
BoundaryMeterStatusLog:
title: BoundaryMeterStatusLog
type: object
description: Records the state of a boundary meter at a particular point in time.
x-tags:
- Boundary Meters
properties:
url:
type: string
format: uri
example: >-
https://api.ev.energy/v2/boundary_meters/bmet01J5DCXX8DMJDJYGVR1DW4T001/status_logs/2024-04-17T09:39:45.984584Z/
sampled_at:
type: string
format: date-time
boundary_meter:
oneOf:
- $ref: '#/components/schemas/BoundaryMeter'
- type: string
format: uri
example: >-
https://api.ev.energy/v2/boundary_meters/bmet01J5DCXX8DMJDJYGVR1DW4T001
power_watts:
type:
- integer
- 'null'
description: >-
Instantaneous power at the meter in W. Positive = import, negative =
export.
example: 1500
status:
type: string
readOnly: true
description: Derived operating state, inferred from power_watts.
enum:
- IMPORTING
- EXPORTING
- IDLE
- UNKNOWN
example: IMPORTING
SubscriptionOffering:
title: SubscriptionOffering
type: object
description: A resource that represents a subscription offering.
examples:
- id: suboB1USP6YGD1VPIDJSHTZARUX11M
url: >-
https://api.ev.energy/v2/subscription_offerings/suboB1USP6YGD1VPIDJSHTZARUX11M
name: ev.energy Solar Lifetime
properties:
id:
type: string
description: Unique identifier for the given Subscription Offering.
pattern: subo[A-Z\d]{26}
example: suboB1USP6YGD1VPIDJSHTZARUX11M
readOnly: true
url:
type: string
format: uri
example: >-
https://api.ev.energy/v2/subscription_offerings/suboB1USP6YGD1VPIDJSHTZARUX11M
readOnly: true
name:
type: string
example: ev.energy Solar Lifetime
SolarArray:
title: SolarArray
type: object
description: A resource that represents a single solar array.
examples:
- id: solr01JASZTD3T7N39DTZPBJVXNPKP
url: https://api.ev.energy/solar_arrays/solr01JASZTD3T7N39DTZPBJVXNPKP
capacity_watts: 7000
inverter: https://api.ev.energy/inverters/invtFB08NVS8KADFY6GAQ9C6RMFGUY
forecast:
solar_watt_hours_until_midnight: 19
percent_vehicle_battery_charge_until_midnight: 30
last_updated_at: '2024-10-16T11:26:16'
user: https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735
required:
- id
- url
properties:
id:
type: string
description: Unique identifier for the given Solar Array.
pattern: solr[A-Z\d]{26}
example: solr01JASZTD3T7N39DTZPBJVXNPKP
readOnly: true
url:
type: string
format: uri
example: https://api.ev.energy/solar_arrays/solr01JASZTD3T7N39DTZPBJVXNPKP
readOnly: true
capacity_watts:
type: integer
description: Capacity of the solar array in watts.
inverter:
oneOf:
- type:
- string
- 'null'
format: uri
example: >-
https://api.ev.energy/v2/inverters/invtB1USP6YGD1VPIDJSHTZARUX11M
- type: object
$ref: '#/components/schemas/Inverter'
description: Reference of the connected inverter.
forecast:
type:
- object
- 'null'
description: |-
Forecast data if available to the user.
Only available to `internal` users.
properties:
solar_watt_hours_until_midnight:
type:
- integer
- 'null'
description: >-
The forecasted charge in watt hours by midnight for the user
from solar charging alone (approximate value).
readOnly: true
percent_vehicle_battery_charge_until_midnight:
type:
- integer
- 'null'
description: >-
The forecasted percentage point increase in the provided car's
battery level by midnight from solar charging alone.
Only available when `vehicle_id` is provided.
readOnly: true
last_updated_at:
type: string
format: date-time
description: The timestamp of when the forecast results were last calculated.
readOnly: true
user:
oneOf:
- type: string
format: uri
example: https://api.ev.energy/v2/user/user01HN2NJ9NMRZBXT1H6FT9N7735
- type: object
$ref: '#/components/schemas/User'
SolarForecast:
title: SolarForecast
type: object
description: A resource that represents a solar forecast for a specific location.
examples:
- id: solf01JASZTD3T7N39DTZPBJVXNPKP
url: >-
https://api.ev.energy/v2/solar_forecasts/solf01JASZTD3T7N39DTZPBJVXNPKP
location:
latitude: 51.51
longitude: -0.13
required:
- id
- url
- location
properties:
id:
type: string
description: Unique identifier for the given solar forecast.
pattern: solf[A-Z\d]{26}
example: solf01JASZTD3T7N39DTZPBJVXNPKP
readOnly: true
url:
type: string
format: uri
example: >-
https://api.ev.energy/v2/solar_forecasts/solf01JASZTD3T7N39DTZPBJVXNPKP
readOnly: true
location:
type: object
description: The geographic location for this solar forecast.
readOnly: true
properties:
latitude:
type: number
description: The latitude of the location.
example: 51.51
longitude:
type: number
description: The longitude of the location.
example: -0.13
required:
- latitude
- longitude
x-tags:
- Solar Forecasts
SolarForecastLog:
title: SolarForecastLog
type: object
description: >-
A log entry recording a predicted solar energy production value for a
specific time period.
properties:
url:
type: string
format: uri
example: >-
https://api.ev.energy/v2/solar_forecasts/solf01JASZTD3T7N39DTZPBJVXNPKP/forecast_logs/2024-04-17T09:00:00.100000Z/
readOnly: true
started_at:
type: string
format: date-time
description: The start of the time period this forecast applies to.
readOnly: true
sampled_at:
type: string
format: date-time
description: The time when this forecast was generated.
readOnly: true
interval_seconds:
type: integer
description: The duration in seconds of the forecast period.
readOnly: true
forecast_watts_per_kilowatt:
type: integer
description: >-
The forecasted solar power output in watts per kilowatt of installed
capacity.
readOnly: true
solar_forecast:
oneOf:
- type: string
format: uri
example: >-
https://api.ev.energy/v2/solar_forecasts/solf01JASZTD3T7N39DTZPBJVXNPKP
- $ref: '#/components/schemas/SolarForecast'
description: >-
The parent solar forecast resource. A URL by default, expanded when
?expand=solar_forecast is used.
readOnly: true
required:
- url
- started_at
- sampled_at
- interval_seconds
- forecast_watts_per_kilowatt
- solar_forecast
x-tags:
- Solar Forecasts
Subscription:
title: Subscription
type: object
description: A resource that represents a single subscription.
examples:
- id: subsB1USP6YGD1VPIDJSHTZARUX11M
url: https://api.ev.energy/subscriptions/subsB1USP6YGD1VPIDJSHTZARUX11M
offering: >-
https://api.ev.energy/v2/subscription_offerings/suboB1USP6YGD1VPIDJSHTZARUX11M
user: https://api.ev.energy/v2/user/user01HN2NJ9NMRZBXT1H6FT9N7735
required:
- id
- url
properties:
id:
type: string
description: Unique identifier for the given Subscription.
pattern: subs[A-Z\d]{26}
example: subsB1USP6YGD1VPIDJSHTZARUX11M
readOnly: true
url:
type: string
format: uri
example: https://api.ev.energy/subscriptions/subsB1USP6YGD1VPIDJSHTZARUX11M
readOnly: true
offering:
oneOf:
- type:
- string
- 'null'
format: uri
example: >-
https://api.ev.energy/v2/subscription_offerings/suboB1USP6YGD1VPIDJSHTZARUX11M
- $ref: '#/components/schemas/SubscriptionOffering'
description: Reference of the offering.
user:
oneOf:
- type: string
format: uri
example: https://api.ev.energy/v2/user/user01HN2NJ9NMRZBXT1H6FT9N7735
- type: object
$ref: '#/components/schemas/User'
SupportTicket:
title: Support Ticket
type: object
description: >-
A resource that represents a support ticket from a customer support
system.
x-tags:
- Support Tickets
required:
- id
- url
- external_ticket_id
- created_at
properties:
id:
type: string
description: Unique identifier for the given support ticket.
pattern: tick[A-Z\d]{26}
example: tick01HN2NJ9NMRZBXT1H6FT9N7735
readOnly: true
url:
type: string
format: uri
example: >-
https://api.ev.energy/v2/support_tickets/tick01HN2NJ9NMRZBXT1H6FT9N7735
readOnly: true
user:
oneOf:
- type: string
format: uri
example: https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735
- $ref: '#/components/schemas/User'
- type: 'null'
description: >-
Reference to the user who created the ticket. Can be null for
tickets created through channels where a user account may not exist
(e.g., pre-signup inquiries, web forms).
Access control:
- Tickets with a user are accessible based on user/organization
permissions
- Tickets without a user (null) are only accessible to applications
with access_all_areas permission
readOnly: true
external_ticket_id:
type: string
description: External ticket ID from Freshdesk or other support system.
example: '12345'
readOnly: true
subject:
type:
- string
- 'null'
description: The subject or title of the ticket.
example: Unable to connect my vehicle
readOnly: true
status:
type:
- string
- 'null'
description: Status name (e.g., Open, Resolved, Closed).
example: Open
readOnly: true
priority:
type:
- string
- 'null'
description: Priority name (e.g., Low, Medium, High, Urgent).
example: Medium
readOnly: true
source:
type:
- string
- 'null'
description: Source name (e.g., Email, Phone, Feedback Widget).
example: Email
readOnly: true
human_verified_category:
oneOf:
- $ref: '#/components/schemas/SupportTicketCategoryEnum'
- type: 'null'
description: Human verified category for the ticket.
example: VEHICLE
human_verified_subcategory:
oneOf:
- $ref: '#/components/schemas/SupportTicketSubcategoryEnum'
- type: 'null'
description: Human verified subcategory for the ticket.
example: TELEMATICS_ISSUE
ai_generated_category:
oneOf:
- $ref: '#/components/schemas/SupportTicketCategoryEnum'
- type: 'null'
description: AI generated category for the ticket.
example: VEHICLE
ai_generated_subcategory:
oneOf:
- $ref: '#/components/schemas/SupportTicketSubcategoryEnum'
- type: 'null'
description: AI generated subcategory for the ticket.
example: TELEMATICS_ISSUE
type_deprecated:
type:
- string
- 'null'
description: Legacy ticket type (phased out for category/subcategory system).
example: Vehicle API error
readOnly: true
tags:
type: array
description: List of tags (e.g., ['ai-categorised', 'escalated']).
items:
type: string
example:
- ai-categorised
readOnly: true
messages:
oneOf:
- type: array
items:
type: string
format: uri
example: >-
https://api.ev.energy/v2/support_tickets/tick01HN2NJ9NMRZBXT1H6FT9N7735/messages/tmsgA1B2C3D4E5F6G7H8I9J0K1L2M3
- type: array
items:
$ref: '#/components/schemas/SupportTicketMessage'
description: >-
Array of message URLs by default. When expanded with
?expand=messages, returns full message objects.
readOnly: true
conversation_summary:
type:
- string
- 'null'
description: An AI generated summary of the conversation.
example: >-
Customer experiencing issues with Tesla vehicle connection to mobile
app.
readOnly: true
custom_fields:
type: object
description: >-
Additional custom fields from support system (e.g.,
car_manufacturer, mobile_app, legal_country, membership_level).
additionalProperties: true
example:
car_manufacturer: Tesla
mobile_app: iOS
readOnly: true
attributes:
type: object
description: Additional information about the user and their hardware.
additionalProperties: true
example:
evse_model: ChargePoint Home Flex
readOnly: true
created_at:
type: string
format: date-time
description: When the ticket was created in the support system.
example: '2019-08-24T14:15:22Z'
readOnly: true
ticket_updated_at:
type:
- string
- 'null'
format: date-time
description: When the ticket was last updated in the support system.
example: '2019-08-24T15:30:00Z'
readOnly: true
resolved_at:
type:
- string
- 'null'
format: date-time
description: When the ticket was resolved in the support system.
example: '2019-08-25T10:00:00Z'
readOnly: true
SupportTicketMessage:
title: Support Ticket Message
type: object
description: A message within a support ticket conversation.
required:
- id
- position
- message_type
- message
- created_at
properties:
id:
type: string
description: Unique identifier for the message.
pattern: tmsg[A-Z0-9]{26}
example: tmsgA1B2C3D4E5F6G7H8I9J0K1L2M3
readOnly: true
position:
type: integer
description: The position in the conversation history. 0 is the first message.
example: 0
readOnly: true
message_type:
allOf:
- $ref: '#/components/schemas/SupportTicketMessageTypeEnum'
description: The type of message in the ticket conversation.
example: INITIAL_REQUEST
readOnly: true
message:
type: string
description: The message from the agent or customer.
example: I am having trouble connecting my Tesla to the app.
readOnly: true
message_clean:
type:
- string
- 'null'
description: A cleaned version of the message with all unnecessary text removed.
example: Having trouble connecting Tesla to app.
readOnly: true
created_at:
type: string
format: date-time
description: When the message was created in the support system.
example: '2019-08-24T14:15:22Z'
readOnly: true
SupportTicketMessageTypeEnum:
title: Support Ticket Message Type
type: string
description: The type of message in a support ticket conversation.
enum:
- INITIAL_REQUEST
- CUSTOMER_RESPONSE
- HUMAN_AGENT_RESPONSE
- AI_AGENT_RESPONSE
SupportTicketCategoryEnum:
title: Support Ticket Category
type: string
description: Main category for a support ticket.
enum:
- ACCOUNT
- CHARGER
- CHARGING_SESSION
- MOBILE_APP
- OTHER
- SOLAR
- USABILITY_UX
- VEHICLE
SupportTicketSubcategoryEnum:
title: Support Ticket Subcategory
type: string
description: Subcategory for a support ticket.
enum:
- ACCESSIBILITY
- ACCURACY
- ADD_NON_INTEGRATED_VEHICLE
- ADD_NEW_TARIFF
- API_ACCESS_TOKEN
- APP_CRASH_FREEZE
- APP_OR_EMAIL_NOTIFICATIONS
- APP_SETTINGS_CONFUSION
- BOOST_CONFUSION
- BUSINESS_LEAD_NON_SUPPORT
- CAMPAIGN_MARKETING_FEEDBACK
- CARBON_FEED
- CHARGE_LOCATION
- CHARGE_PAST_READY_BY_TIME
- CHARGING_ON_PEAK
- COMMISSIONING
- COMPATIBILITY
- COMPLAINT
- CONFLICTING_SCHEDULE
- DASHBOARD_COSMETIC_ISSUE
- DASHBOARD_UI_ISSUE
- DATA_EXPORT
- DELETION
- DUPLICATE
- ELIGIBILITY
- ENERGY_DELIVERED_CALCULATION
- ERROR_REPORT
- FEATURE_REQUEST_FEEDBACK
- FIRMWARE
- HARDWARE
- HARDWARE_ISSUE
- HIDDEN_INCENTIVES
- INCENTIVES_BILL_CREDITS
- INCOMPLETE_CHARGE
- INCORRECT_CHARGE_TIME_DURATION
- INCORRECT_INCENTIVES_DISPLAYED
- INCORRECT_KWH_DISPLAYED
- INCORRECT_LOCATION_DISPLAYED
- INCORRECT_MESSAGING
- INCORRECT_PRICE_THRESHOLD
- INCORRECT_TRIM
- INVERTER
- LOCALISATION
- LOCATION_INCORRECT
- LOGIN_CREDENTIALS
- MANUAL_UPLOAD
- MAX_CHARGE_LIMIT
- MISSING_SESSIONS
- MISSING_TARIFF
- MOBILE_COMPATIBILITY
- MULTI_VEHICLE
- NETWORK
- NO_CHARGE
- NON_SUPPORT_EXTERNAL
- NOT_COMPATIBLE
- MANGED_TARIFF_INTERFERENCE
- OFFLINE
- OFF_PEAK_HOURS_CONFUSION
- ONBOARDING
- ONLY_CHARGE_OFF_PEAK_OFF
- OTHER
- OUTAGE
- OWNERSHIP_TRANSFER
- PASSWORD
- PLATFORM_OUTAGE
- POOR_UPTIME
- PRIVACY_CONCERNS
- REAUTHENTICATION
- REBATE_REQUEST
- REFERRAL_PROMO_CODE
- REFUNDS
- REFUSING_COMMANDS
- RELIABILITY
- REPLACE_VEHICLE
- REQUEST_TO_DISCONNECT
- REWARDS
- REWARDS_INCENTIVES_UI_ISSUE
- SESSION_RECALCULATION
- SESSION_START_END_TIME
- SESSION_START_END_TIME_CONFUSION
- SMART_CHARGING_CONFUSION
- SMART_TAB_UI_ISSUE
- SOLAR_CHARGING_CONFUSION
- SOLAR_FEED
- SOLAR_PAYMENT
- SPAM
- STATS_COSMETIC_ISSUE
- STATS_UI_ISSUE
- SUBSCRIPTION_ISSUE
- TARIFF_IS_OUTDATED_INCORRECT
- TARIFF_REQUEST
- TELEMATICS_ISSUE
- TIER_SELECTION
- TRIM
- UI_ISSUE
- UNABLE_TO_DETECT_CAR_PLUGGED_IN
- UTILITY_PARTNER_INQUIRY
- VEHICLE_DELETION
- VERIFICATION
- WRONG_COMPANY
LatLong:
title: LatLong
type: object
description: Coordinates model used for locations.
required:
- latitude
- longitude
properties:
latitude:
type: number
format: float
example: 51.52576576674041
longitude:
type: number
format: float
example: -0.08366433371722264
Location:
title: Location
type: object
description: >
Location model for charging locations.
**Address validation:** Address fields are optional as a group, but each
field independently triggers the requirement. If any of `address_1`,
`address_2`, `city`, `state`, `postal_code`, `country_code`, or
`coordinates` is provided with a non-null value, then `address_1`,
`city`, `postal_code`, and `country_code` must all be provided as
non-null values. Sending the keys with explicit `null` values is allowed
and does not trigger the requirement (this is how addresses are cleared
via `PATCH`). Partial addresses are rejected with a 400.
properties:
address_1:
type:
- string
- 'null'
description: First line of address.
address_2:
type:
- string
- 'null'
description: Second line of address.
postal_code:
type:
- string
- 'null'
description: Postal Code.
country_code:
anyOf:
- $ref: '#/components/schemas/CountryCode'
- type: 'null'
$ref: '#/components/schemas/CountryCode'
coordinates:
anyOf:
- $ref: '#/components/schemas/LatLong'
- type: 'null'
tariff:
oneOf:
- format: uri
type:
- string
- 'null'
example: https://api.ev.energy/v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7735
- $ref: '#/components/schemas/Tariff'
city:
type:
- string
- 'null'
state:
type:
- string
- 'null'
evse_site:
oneOf:
- type:
- string
- 'null'
- $ref: '#/components/schemas/EVSESite'
description: >-
If null, the user's location is not an EVSE Site. Otherwise, this
field references the site they are a part of.
dependentSchemas:
address_1:
if:
properties:
address_1:
not:
type: 'null'
then:
required:
- city
- postal_code
- country_code
properties:
city:
not:
type: 'null'
postal_code:
not:
type: 'null'
country_code:
not:
type: 'null'
address_2:
if:
properties:
address_2:
not:
type: 'null'
then:
required:
- address_1
- city
- postal_code
- country_code
properties:
address_1:
not:
type: 'null'
city:
not:
type: 'null'
postal_code:
not:
type: 'null'
country_code:
not:
type: 'null'
city:
if:
properties:
city:
not:
type: 'null'
then:
required:
- address_1
- postal_code
- country_code
properties:
address_1:
not:
type: 'null'
postal_code:
not:
type: 'null'
country_code:
not:
type: 'null'
state:
if:
properties:
state:
not:
type: 'null'
then:
required:
- address_1
- city
- postal_code
- country_code
properties:
address_1:
not:
type: 'null'
city:
not:
type: 'null'
postal_code:
not:
type: 'null'
country_code:
not:
type: 'null'
postal_code:
if:
properties:
postal_code:
not:
type: 'null'
then:
required:
- address_1
- city
- country_code
properties:
address_1:
not:
type: 'null'
city:
not:
type: 'null'
country_code:
not:
type: 'null'
country_code:
if:
properties:
country_code:
not:
type: 'null'
then:
required:
- address_1
- city
- postal_code
properties:
address_1:
not:
type: 'null'
city:
not:
type: 'null'
postal_code:
not:
type: 'null'
coordinates:
if:
properties:
coordinates:
not:
type: 'null'
then:
required:
- address_1
- city
- postal_code
- country_code
properties:
address_1:
not:
type: 'null'
city:
not:
type: 'null'
postal_code:
not:
type: 'null'
country_code:
not:
type: 'null'
LocationDetail:
title: Location
description: >-
Extra fields only included when a single location is requested but
omitted when locations are listed.
allOf:
- type: object
properties:
current_carbon_intensity_grams_per_kilowatt_hour:
type:
- integer
- 'null'
example: 300
description: >-
The current carbon intensity associated with the location in
gCO2/kWh.
- $ref: '#/components/schemas/Location'
Program:
title: Program
type: object
properties:
id:
type: string
example: prog01JCK1HPNAANB8WN253G27SFPC
pattern: prog[A-Z\d]{26}
readOnly: true
url:
type: string
example: https://api.ev.energy/v2/programs/prog01JCK1HPNAANB8WN253G27SFPC
format: uri
readOnly: true
name:
type: string
example: CoolCharge
description: A human-friendly name for the Program.
readOnly: true
description:
type: string
example: >-
A program which incentivises charging when it's coolest to charge
your EV
description: >-
A plain text description of the program's incentives and
requirements.
readOnly: true
logo:
type:
- string
- 'null'
format: uri
description: URL to download a logo image for the Program.
readOnly: true
sponsor_name:
type: string
example: Cool Power
description: >-
The name of the organisation which sponsors the program. Often, but
not always, a utility company.
readOnly: true
external_url:
type: string
format: uri
example: https://www.example.com/coolcharge
description: >-
A publicly accessible URL where individuals can enroll in the
program.
readOnly: true
ProgramTier:
title: ProgramTier
type: object
example:
id: tier01JCK1HPNAANB8WN253G27SFPC
url: >-
https://api.ev.energy/v2/programs/prog01JCK1HPNAANB8WN253G27SFPC/tiers/tier01JCK1HPNAANB8WN253G27SFPC
short_name: standard
name: Standard Tier
logo_svg: https://api.ev.energy/media/program_tiers/standard.svg
description_short: Charge at off-peak times to earn standard rewards.
description_long: >-
Members of the Standard Tier earn rewards for charging during
off-peak hours. No additional eligibility requirements
apply.
smart_charging_enabled: true
disable_changing_tariff: false
visible: true
eligible: true
properties:
id:
type: string
example: tier01JCK1HPNAANB8WN253G27SFPC
pattern: tier[A-Z\d]{26}
readOnly: true
url:
type: string
example: >-
https://api.ev.energy/v2/programs/prog01JCK1HPNAANB8WN253G27SFPC/tiers/tier01JCK1HPNAANB8WN253G27SFPC
format: uri
readOnly: true
short_name:
type: string
example: standard
description: A short slug-style identifier for the tier, unique within a program.
readOnly: true
name:
type:
- string
- 'null'
example: Standard Tier
description: A human-friendly name for the tier.
readOnly: true
logo_svg:
type:
- string
- 'null'
format: uri
description: URL to download an SVG logo for the tier.
readOnly: true
description_short:
type:
- string
- 'null'
description: >-
Short HTML description of the tier. Wrapped in `` tags on both
real and sandbox responses.
readOnly: true
description_long:
type:
- string
- 'null'
description: >-
Longer HTML description of the tier. Wrapped in `` tags on
both real and sandbox responses.
readOnly: true
smart_charging_enabled:
type: boolean
description: Whether smart charging is enabled for users in this tier.
readOnly: true
disable_changing_tariff:
type: boolean
description: Whether users in this tier are blocked from changing their tariff.
readOnly: true
visible:
type: boolean
description: >-
Whether this tier should be shown to users when selecting a tier
within the program.
readOnly: true
eligible:
type:
- boolean
- 'null'
description: >
Whether the authenticated user is eligible to join this tier.
Populated only when
the request is authenticated as a specific user (Authorization Code
/ Password grant,
or Client Credentials with the `EvEnergy-User` header). `null` for
anonymous and
pure client-credentials requests.
readOnly: true
ParticipationAgreementVersion:
title: ParticipationAgreementVersion
type: object
description: |
A version of a Program's Participation Agreement. Programs have a single
Participation Agreement with versioned content; users accept a version
via `POST .../{id}/accept`. The currently active version is the
highest-numbered published one — fetch it from the `current`
sub-resource.
properties:
id:
type: string
example: pagv01JCDYP6Z8MX9XWVAV0A7G3KPN
pattern: pagv[A-Z\d]{26}
readOnly: true
url:
type: string
format: uri
example: >-
https://api.ev.energy/v2/programs/prog01JCK1HPNAANB8WN253G27SFPC/participation_agreement_versions/pagv01JCDYP6Z8MX9XWVAV0A7G3KPN
readOnly: true
version_number:
type: integer
example: 1
description: >-
Monotonically increasing version number scoped to the parent
agreement.
readOnly: true
published:
type: boolean
description: |
Whether this version is the currently active one shown to users.
Only one version per agreement should be published at a time.
readOnly: true
content:
type: string
description: >-
HTML content of the agreement, translated for the requesting user's
language.
readOnly: true
created_at:
type: string
format: date-time
description: When this version was created.
readOnly: true
Region:
title: Region
type: object
description: >-
A named geographic boundary (WGS 84) used to gate program tier
eligibility, tariffs, carbon feeds and reward offers. Names are globally
unique and immutable once created. The list representation omits the
geometry; request a single region for the full GeoJSON MultiPolygon.
properties:
id:
type: string
example: regn01JCK1HPNAANB8WN253G27SFPC
pattern: regn[A-Z\d]{26}
readOnly: true
url:
type: string
format: uri
example: https://api.ev.energy/v2/regions/regn01JCK1HPNAANB8WN253G27SFPC
readOnly: true
name:
type: string
example: WEST ROXBURY
description: Globally unique region name. Immutable after creation.
type:
type:
- string
- 'null'
enum:
- OTHER
- ELECTRICITY
- null
description: Optional classification of the region.
region_groups:
type: array
description: URLs of the region groups this region belongs to.
readOnly: true
items:
type: string
format: uri
created_at:
type: string
format: date-time
readOnly: true
updated_at:
type: string
format: date-time
readOnly: true
RegionDetail:
title: Region
description: >-
Region including its full geometry. Served for single-region requests;
the geometry is omitted from region lists.
allOf:
- $ref: '#/components/schemas/Region'
- type: object
properties:
geometry:
description: >-
The region's boundary as a GeoJSON MultiPolygon, or null if the
region has no geometry.
oneOf:
- $ref: '#/components/schemas/GeoJsonMultiPolygon'
- type: 'null'
RegionCreate:
title: RegionCreate
type: object
required:
- name
- geometries
properties:
name:
type: string
description: >-
Globally unique region name. A clash returns 409
region-name-conflict — there is no upsert on this endpoint.
type:
type:
- string
- 'null'
enum:
- OTHER
- ELECTRICITY
- null
geometries:
type: array
description: >-
One or more GeoJSON Polygon/MultiPolygon geometries. The server
unions them (GEOS unary union, make_valid applied) into a single
MultiPolygon.
minItems: 1
maxItems: 1000
items:
oneOf:
- $ref: '#/components/schemas/GeoJsonPolygon'
- $ref: '#/components/schemas/GeoJsonMultiPolygon'
region_groups:
type: array
description: URLs of existing region groups to link the new region to.
items:
type: string
format: uri
RegionGroupEntry:
title: RegionGroupEntry
type: object
required:
- name
- geometries
properties:
name:
type: string
example: MILTON
description: >-
Must not match any existing region — clashes fail the whole request
with 409.
type:
type:
- string
- 'null'
enum:
- OTHER
- ELECTRICITY
- null
geometries:
type: array
description: >-
One or more GeoJSON Polygon/MultiPolygon geometries, unioned
server-side into a single MultiPolygon.
minItems: 1
maxItems: 1000
items:
oneOf:
- $ref: '#/components/schemas/GeoJsonPolygon'
- $ref: '#/components/schemas/GeoJsonMultiPolygon'
RegionGroupCreate:
title: RegionGroupCreate
type: object
required:
- name
- regions
properties:
name:
type: string
example: Eversource MA Pilot 1A
description: Unique name for the new group.
regions:
type: array
minItems: 1
maxItems: 500
items:
$ref: '#/components/schemas/RegionGroupEntry'
RegionGroup:
title: RegionGroup
type: object
properties:
id:
type: string
example: rgrp01JCK1HPNAANB8WN253G27SFPC
pattern: rgrp[A-Z\d]{26}
readOnly: true
url:
type: string
format: uri
readOnly: true
name:
type: string
example: Eversource MA Pilot 1A
regions:
type: array
description: URLs of the member regions.
readOnly: true
items:
type: string
format: uri
regions_collection:
type: string
format: uri
description: Pre-built link to the regions collection filtered to this group.
readOnly: true
created_at:
type: string
format: date-time
readOnly: true
RegionValidationResult:
title: RegionValidationResult
type: object
properties:
name:
type: string
status:
type: string
enum:
- OK
- NAME_EXISTS
- INVALID_GEOMETRY
- INVALID
problems:
type: array
items:
type: string
computed:
type:
- object
- 'null'
properties:
geometry_count:
type: integer
resulting_polygon_count:
type: integer
area_sq_km:
type: number
existing_region:
type:
- string
- 'null'
format: uri
description: Present when status is NAME_EXISTS — URL of the clashing region.
RegionGroupValidationResult:
title: RegionGroupValidationResult
type: object
properties:
valid:
type: boolean
description: True when committing the identical body would succeed.
group:
type: object
properties:
name:
type: string
status:
type: string
enum:
- AVAILABLE
- NAME_EXISTS
problems:
type: array
items:
type: string
regions:
type: array
items:
$ref: '#/components/schemas/RegionValidationResult'
CountryCode:
description: ISO 3166-1 2 letter Country Codes.
type: string
enum:
- AD
- AE
- AF
- AG
- AI
- AL
- AM
- AO
- AQ
- AR
- AS
- AT
- AU
- AW
- AX
- AZ
- BA
- BB
- BD
- BE
- BF
- BG
- BH
- BI
- BJ
- BL
- BM
- BN
- BO
- BQ
- BR
- BS
- BT
- BV
- BW
- BY
- BZ
- CA
- CC
- CD
- CF
- CG
- CH
- CI
- CK
- CL
- CM
- CN
- CO
- CR
- CU
- CV
- CW
- CX
- CY
- CZ
- DE
- DJ
- DK
- DM
- DO
- DZ
- EC
- EE
- EG
- EH
- ER
- ES
- ET
- FI
- FJ
- FK
- FM
- FO
- FR
- GA
- GB
- GD
- GE
- GF
- GG
- GH
- GI
- GL
- GM
- GN
- GP
- GQ
- GR
- GS
- GT
- GU
- GW
- GY
- HK
- HM
- HN
- HR
- HT
- HU
- ID
- IE
- IL
- IM
- IN
- IO
- IQ
- IR
- IS
- IT
- JE
- JM
- JO
- JP
- KE
- KG
- KH
- KI
- KM
- KN
- KP
- KR
- KW
- KY
- KZ
- LA
- LB
- LC
- LI
- LK
- LR
- LS
- LT
- LU
- LV
- LY
- MA
- MC
- MD
- ME
- MF
- MG
- MH
- MK
- ML
- MM
- MN
- MO
- MP
- MQ
- MR
- MS
- MT
- MU
- MV
- MW
- MX
- MY
- MZ
- NA
- NC
- NE
- NF
- NG
- NI
- NL
- 'NO'
- NP
- NR
- NU
- NZ
- OM
- PA
- PE
- PF
- PG
- PH
- PK
- PL
- PM
- PN
- PR
- PS
- PT
- PW
- PY
- QA
- RE
- RO
- RS
- RU
- RW
- SA
- SB
- SC
- SD
- SE
- SG
- SH
- SI
- SJ
- SK
- SL
- SM
- SN
- SO
- SR
- SS
- ST
- SV
- SX
- SY
- SZ
- TC
- TD
- TF
- TG
- TH
- TJ
- TK
- TL
- TM
- TN
- TO
- TR
- TT
- TV
- TW
- TZ
- UA
- UG
- UM
- US
- UY
- UZ
- VA
- VC
- VE
- VG
- VI
- VN
- VU
- WF
- WS
- YE
- YT
- ZA
- ZM
- ZW
UsageInterval:
title: UsageInterval
type: object
properties:
interval_seconds:
type: integer
description: The number of seconds that this interval lasts for.
readOnly: true
started_at:
type: string
format: date-time
description: When this interval began.
readOnly: true
total_energy_delivered_watt_hours:
type: integer
description: The total number of watt hours delivered during the interval.
readOnly: true
meter_usage_watt_hours:
type: integer
nullable: true
description: >-
An estimate of the supply meter usage in watt hours during the
interval, accounting for charging system losses between the supply
meter and the EVSE/Vehicle. Null when not available.
readOnly: true
alt_usage_watt_hours:
type: integer
nullable: true
description: >-
Counterfactual energy usage in watt hours. Represents the estimated
energy that would have been delivered during this interval if the
vehicle had charged immediately without managed charging. Null when
not available.
readOnly: true
percentage_import:
type: integer
nullable: true
minimum: 0
maximum: 100
description: >-
The percentage of energy imported from the grid during this interval
(0-100). Used for calculating costs with home solar.
readOnly: true
electricity_cost_sub_unit:
type: string
format: decimal
nullable: true
description: >-
The electricity rate for this interval, in the smallest sub-unit of
the currency (e.g. pence/kWh, cents/kWh). For merged intervals with
multiple pricing tiers, this is the sum of the distinct rate values.
readOnly: true
energy_delivered_by_price:
type: object
$ref: '#/components/schemas/EnergyDeliveredByPrice'
description: >-
Energy delivered during the interval, broken down by the price paid
for that energy. For example, if half the period was at peak price
(50p) and half at off-peak price (20p), this field would contain an
entry for 20p and an entry for 50p with the total energy delivered
at each price. Note that prices are always quoted in the smallest
sub-unit of the currency. (Ie. cents for USD, pence for GBP.)
readOnly: true
EnergyDeliveredByPrice:
title: EnergyDeliveredByPrice
type: object
properties:
price:
type: string
description: The price paid for the energy in the smallest unit of the currency.
example: '21.3'
format: decimal
energy_delivered_watt_hours:
type: integer
example: 1800
EnergyUsage:
title: EnergyUsage
type: object
description: >-
Detailed energy usage for a charging sub-session, reported as a list of
intervals recording when energy was actually delivered to the vehicle
and how much. Use this (rather than the sub-session's start/end) to
determine when charging actually happened.
properties:
url:
type: string
format: uri
example: >-
https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5/energy_usage
readOnly: true
currency:
type: string
example: GBP
description: >-
The currency that prices for intervals are quoted in. Note that we
always use the smallest unit of the currency.
readOnly: true
charging_sub_session:
type: string
format: uri
example: >-
https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5
readOnly: true
intervals:
type: array
description: A list of energy usage intervals for this charging sub-session.
items:
$ref: '#/components/schemas/UsageInterval'
readOnly: true
last_updated_at:
type: string
format: date-time
description: The datetime when the energy usages were last updated at.
ChargingSessionFlag:
title: ChargingSessionFlag
type: object
properties:
name:
type: string
description: >-
Name describing the type of issue flagged. New values may be added
over time.
example: ENERGY_OVER_DELIVERY
root_cause:
type: string
description: >-
Category describing the root cause of the issue. New values may be
added over time.
example: CHARGE_MEASUREMENT_OSCILLATION
required:
- name
- root_cause
ChargingSubSessionFlags:
title: ChargingSubSessionFlags
type: object
properties:
url:
type: string
format: uri
example: >-
https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5/flags
readOnly: true
charging_sub_session:
oneOf:
- type: string
format: uri
example: >-
https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5
readOnly: true
- $ref: '#/components/schemas/ChargingSubSession'
description: The charging sub-session these flags belong to. Expandable.
flags:
type: array
description: A list of flags associated with this charging sub-session.
items:
$ref: '#/components/schemas/ChargingSessionFlag'
readOnly: true
required:
- url
- charging_sub_session
- flags
ChargingSubSessionDebugMetadata:
title: ChargingSubSessionDebugMetadata
type: object
description: Session-level diagnostic information for a charging sub-session.
properties:
url:
type: string
format: uri
example: >-
https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5/debug_metadata
readOnly: true
charging_sub_session:
oneOf:
- type: string
format: uri
example: >-
https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5
readOnly: true
- $ref: '#/components/schemas/ChargingSubSession'
description: The charging sub-session this debug metadata belongs to. Expandable.
start_reason:
oneOf:
- type: string
enum:
- BOOST_START
- SMART_CHARGE_ENABLED
- SMART_CHARGE_DISABLED
- SOLAR_SETTINGS
- ADMIN_CREATE_FAKE
- ADMIN_IMPORT_CSV
- REPROCESS_VEHICLEDATALOGS_CMD
- SFTP_IMPORTER
- EVSE_CONNECT
- CP_EVSE_CONNECT
- VEHICLE_LOG_CONNECT
- USER_SETTINGS
- type: 'null'
description: >-
The reason the session was started. New values may be added over
time.
readOnly: true
finish_reason:
oneOf:
- type: string
enum:
- BOOST_START
- SMART_CHARGE_ENABLED
- SMART_CHARGE_DISABLED
- SOLAR_SETTINGS
- ADMIN_ACTION
- FAKE_CURRENT_CHARGING_CMD
- REPROCESS_VEHICLEDATALOGS_CMD
- SFTP_IMPORTER
- INVALIDATE_ACCOUNT
- REMOVE_INTEGRATION
- EVSE_UNPAIR
- EVSE_DISCONNECT
- type: 'null'
description: The reason the session finished. New values may be added over time.
readOnly: true
is_energy_delivered_capped:
type: boolean
description: >-
Indicates whether delivered energy was capped to prevent unrealistic
over-delivery beyond the vehicle's battery capacity.
readOnly: true
uncapped_energy_delivered_watt_hours:
oneOf:
- type: integer
- type: 'null'
description: >-
The recalculated energy in watt-hours that would have been delivered
without capping. Null when energy delivery was not capped or when
recalculation cannot be completed.
readOnly: true
energy_usage_calculation_method:
type: string
enum:
- ESTIMATED_CHARGE_ENERGY_ADDED
- ESTIMATED_CHARGE_LEVEL
- ESTIMATED_CHARGE_RATE
- METERED
- METERED_CHARGE_RATE
- BETA_ESTIMATED_CHARGE_ENERGY_ADDED
- ESTIMATED_CHARGE_LEVEL_WITH_INFERENCE
- MANUAL_ENTRY
description: The method used to calculate energy usage for this session.
readOnly: true
energy_usage_interpolation_method:
type: string
enum:
- LINEAR
- LINEAR_WITH_CHARGE_STEP
description: >-
The method used to interpolate data readings when calculating energy
usage.
readOnly: true
solar_integration_type:
oneOf:
- type: string
enum:
- UNAVAILABLE
- HARDWARE
- SOFTWARE
- SOFTWARE_BETA
- HARDWARE_PASSTHROUGH
- type: 'null'
description: >-
The solar integration type of the EVSE paired with this session.
Null when no EVSE is associated with the session.
readOnly: true
required:
- url
- charging_sub_session
- start_reason
- finish_reason
- is_energy_delivered_capped
- uncapped_energy_delivered_watt_hours
- energy_usage_calculation_method
- energy_usage_interpolation_method
- solar_integration_type
Schedules:
title: Schedules
type: object
properties:
url:
type: string
format: uri
example: >-
https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5/schedules
readOnly: true
charging_sub_session:
oneOf:
- type: string
format: uri
example: >-
https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5
- $ref: '#/components/schemas/ChargingSubSession'
description: >-
The charging sub-session these schedules belong to. Defaults to a
url, but can be expanded to the full ChargingSubSession resource via
the `expand` query parameter.
readOnly: true
schedules:
type: array
description: A list of schedule intervals for this charging sub-session.
items:
$ref: '#/components/schemas/ScheduleInterval'
readOnly: true
SchedulePlans:
title: SchedulePlans
type: object
properties:
url:
type: string
format: uri
example: >-
https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5/schedule_plans
readOnly: true
charging_sub_session:
oneOf:
- type: string
format: uri
example: >-
https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5
- $ref: '#/components/schemas/ChargingSubSession'
description: >-
The charging sub-session these schedule plans belong to. Defaults to
a url, but can be expanded to the full ChargingSubSession resource
via the `expand` query parameter.
readOnly: true
schedule_plans:
type: array
description: A list of schedule plans for this charging sub-session.
items:
$ref: '#/components/schemas/SchedulePlan'
readOnly: true
SchedulePlan:
title: SchedulePlan
type: object
description: >-
A schedule plan containing the parameters used to generate charging
schedules.
properties:
id:
type: string
pattern: scpl[A-Z\d]{26}
example: scpl01HSH04KDEWF6Z4DB2J77J74K5
description: Unique identifier for this schedule plan.
readOnly: true
created_at:
type: string
format: date-time
example: '2024-01-01T02:00:00Z'
description: When this schedule plan was created.
readOnly: true
ready_by_time:
type: string
format: date-time
example: '2024-01-01T08:00:00Z'
description: The target time by which charging should be complete.
readOnly: true
price_threshold_minor_unit:
type:
- integer
- 'null'
example: 1500
description: >-
Price threshold in minor currency units (e.g., cents/pence)
multiplied by 100. For example, 1500 represents 15 pence (£0.15),
and 50 represents 0.5 pence (£0.005). Null if no threshold set.
readOnly: true
power_on_current_milliamps:
type: integer
example: 32000
description: The charging current in milliamps when power is on.
readOnly: true
power_off_current_milliamps:
type: integer
example: 0
description: The current in milliamps when power is off (typically 0).
readOnly: true
seconds_to_charge:
type: integer
example: 10800
description: The number of seconds required to complete charging.
readOnly: true
vehicle_charge_level_watt_hours:
type:
- integer
- 'null'
example: 25000
description: >-
The vehicle's battery level in watt-hours at the time the plan was
created. Null if unknown.
readOnly: true
estimated_charge_rate_watts:
type: integer
example: 7400
description: The estimated charging rate in watts.
readOnly: true
estimated_charge_rate_source:
type:
- string
- 'null'
enum:
- CURRENT_SESSION_EVSE_DATA_LOGS
- CURRENT_SESSION_VEHICLE_DATA_LOGS
- ENERGY_TRANSFER_PERIODS
- DEFAULT_CHARGE_RATE
- MAX_EVSE_CHARGE_RATE
- MAX_VEHICLE_CHARGE_RATE
- null
description: >-
The source of data used for estimating charge rate. Null if not
specified.
readOnly: true
watt_hours_to_charge:
type: integer
example: 22000
description: The total energy required to complete charging in watt-hours.
readOnly: true
min_charge_limit_percent:
type: integer
minimum: 0
maximum: 100
example: 0
description: The minimum charge limit as a percentage (0-100).
readOnly: true
max_charge_limit_percent:
type: integer
minimum: 0
maximum: 100
example: 80
description: The maximum charge limit as a percentage (0-100).
readOnly: true
price_data:
oneOf:
- type: 'null'
- type: array
items:
$ref: '#/components/schemas/Price'
description: >-
Tariff rate intervals active when this schedule plan was created.
Null by default; expand with ?expand=price_data to populate. Returns
null if no tariff is associated with the session.
readOnly: true
ChargingSubSessionAssessment:
title: ChargingSubSessionAssessment
type: object
description: Performance assessment for a completed charging sub-session.
properties:
url:
type: string
format: uri
example: >-
https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5/assessment
readOnly: true
charging_sub_session:
oneOf:
- type: string
format: uri
example: >-
https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5
- $ref: '#/components/schemas/ChargingSubSession'
description: >-
The parent charging sub-session. Defaults to a url, but can be
expanded to the full ChargingSubSession resource via the `expand`
query parameter.
readOnly: true
energy_delivered_to_capacity_percentage:
type:
- integer
- 'null'
description: >-
Energy delivered as a percentage of battery capacity. Values above
100 indicate overdelivery.
example: 85
readOnly: true
energy_delivery_percentage:
type:
- integer
- 'null'
description: Energy delivered as a percentage of energy required.
example: 92
readOnly: true
average_charge_rate_watts:
type:
- integer
- 'null'
description: Average charge rate in watts throughout the session.
example: 7200
readOnly: true
max_charge_rate_watts:
type:
- integer
- 'null'
description: Maximum charge rate in watts throughout the session.
example: 11000
readOnly: true
metrics:
$ref: '#/components/schemas/ChargingSubSessionAssessmentMetrics'
readOnly: true
ratings:
$ref: '#/components/schemas/ChargingSubSessionAssessmentRatings'
readOnly: true
updated_at:
type: string
format: date-time
description: When the assessment was last updated.
readOnly: true
ChargingSubSessionAssessmentMetrics:
title: ChargingSubSessionAssessmentMetrics
type: object
description: >-
Performance quality metrics for a charging session assessment. All
fields are nullable.
properties:
vehicle_data_uptime:
type:
- integer
- 'null'
description: Vehicle data uptime as a percentage (0-100).
example: 95
vehicle_location_uptime:
type:
- integer
- 'null'
description: Vehicle location uptime as a percentage (0-100).
example: 90
vehicle_error_rate:
type:
- integer
- 'null'
description: Vehicle error rate as a percentage (0-100).
example: 2
vehicle_command_adherence:
type:
- integer
- 'null'
description: Vehicle command adherence as a percentage (0-100).
example: 88
evse_data_uptime:
type:
- integer
- 'null'
description: EVSE data uptime as a percentage (0-100).
example: 98
evse_command_adherence:
type:
- integer
- 'null'
description: EVSE command adherence as a percentage (0-100).
example: 92
schedule_quality:
type:
- integer
- 'null'
description: >-
Time that schedule requested charging but no charge occurred as a
percentage (0-100).
example: 85
charge_outside_of_schedule:
type:
- integer
- 'null'
description: Energy usage outside of schedule as a percentage (0-100).
example: 5
session_duration:
type:
- integer
- 'null'
description: Session duration.
example: 28800
energy_delivered_vs_required:
type:
- integer
- 'null'
description: Energy delivered vs required as a percentage (0-100).
example: 95
savings_attainment_rate:
type:
- integer
- 'null'
description: >-
Savings achieved compared to theoretical maximum as a percentage
(0-100).
example: 78
session_savings_range:
type:
- integer
- 'null'
description: >-
Difference between maximum and minimum theoretical session costs
(units of currency).
example: 30
charge_energy_added_meter_reset:
type:
- boolean
- 'null'
description: Whether a charge energy added meter reset was detected.
example: false
charge_energy_added_oscillation_count:
type:
- integer
- 'null'
description: Number of charge energy added oscillations.
example: 0
charge_level_oscillation_count:
type:
- integer
- 'null'
description: Number of charge level oscillations.
example: 1
charge_location_data_at_session_start_minutes:
type:
- integer
- 'null'
description: Age of charge location data at session start, in minutes.
example: 5
last_location_update_implied_velocity_kmh:
type:
- integer
- 'null'
description: Implied velocity from last location update, in km/h.
example: 0
distance_from_home_meters:
type:
- integer
- 'null'
description: Distance from home in meters.
example: 15
missing_location:
type:
- boolean
- 'null'
description: Whether location data is missing.
example: false
vehicle_median_data_gap_duration_minutes:
type:
- integer
- 'null'
description: Median vehicle data gap duration in minutes.
example: 3
vehicle_max_data_gap_duration_minutes:
type:
- integer
- 'null'
description: Maximum vehicle data gap duration in minutes.
example: 12
vehicle_data_frequency_below_threshold:
type:
- integer
- 'null'
description: Vehicle data frequency below threshold as a percentage (0-100).
example: 8
evse_median_data_gap_duration_minutes:
type:
- integer
- 'null'
description: Median EVSE data gap duration in minutes.
example: 2
evse_max_data_gap_duration_minutes:
type:
- integer
- 'null'
description: Maximum EVSE data gap duration in minutes.
example: 8
evse_data_frequency_below_threshold:
type:
- integer
- 'null'
description: EVSE data frequency below threshold as a percentage (0-100).
example: 5
charge_rate_max_mad_score:
type:
- integer
- 'null'
description: Maximum MAD score for charge rate.
example: 3
charge_rate_max_median_ratio:
type:
- integer
- 'null'
description: Charge rate max to median ratio as a percentage (0-100).
example: 140
ChargingSubSessionAssessmentRatings:
title: ChargingSubSessionAssessmentRatings
type: object
description: >-
RAG (Red/Amber/Green) quality ratings for assessment metrics. Includes
an overall quality rating.
additionalProperties:
type: string
enum:
- RED
- AMBER
- GREEN
- NOT_APPLICABLE
example:
overall: RED
energy_delivered_to_capacity_ratio: RED
energy_delivery_ratio: RED
average_charge_rate_watts: AMBER
max_charge_rate_watts: AMBER
vehicle_data_uptime: GREEN
schedule_quality: GREEN
session_duration: GREEN
IncentiveScheme:
title: IncentiveScheme
type: object
description: >-
Incentive Schemes define a set of rules for how an elgible User can earn
monetary Incentives.
examples:
- id: incs01JE3ZY9Z2C0E087C942B9WKBC
name: Off-Peak Charging Incentives
description: Earn $0.10 per kWh when charging off-peak
visible: false
available: true
properties:
id:
type: string
description: 'Prefix: "incs"'
name:
type: string
description: Name to be displayed to the User.
description:
type: string
description: Describes the rules of how the User earns this Incentive.
visible:
type: boolean
default: false
description: Should this Incentive Scheme be visible to the User in the App.
available:
type: boolean
default: true
description: >-
Is this Incentive available for the User to earn.
Some Incentive Schemes can only be earned a limitted number of times
per User or Device.
E.g. A Sign Up Incentive that can only be earned once per Device.
This will also be False if it is outside the active period of the
Incentive Scheme.
EVSESite:
title: EVSESite
type: object
description: >-
Represents a place with one or more EVSEs installed which can be
accessed by multiple users.
required:
- id
- url
- evses
- cpms_connection
properties:
id:
type: string
pattern: site[A-Z\d]{26}
examples:
- site01JX2SZ0WAFTDYVYY0JRAYREY7
readOnly: true
url:
type: string
format: uri
example: https://api.ev.energy/v2/evse_sites/site01JX2SZ0WAFTDYVYY0JRAYREY7
readOnly: true
evses:
type: array
description: A list of all EVSEs that are currently associated with this site.
items:
type: string
format: uri
examples:
- https://api.ev.energy/v2/evses/evse01HSH04KDEWF6Z4DB2J77J74K5
readOnly: true
cpms_connection:
type:
- string
- 'null'
description: >-
The type of ChargePoint Management System that this site is
connected to, if there is one.
enum:
- null
- CHARGEPOINT
- SWTCH
readOnly: true
cpms_connection_display_name:
type:
- string
- 'null'
description: >-
A human-readable name for the Chargepoint Management System that the
site is connected to.
example: ChargePoint
user_connected:
type:
- boolean
- 'null'
description: >-
When authenticated as a specific user (eg. via the Authorisation
Code grant type) or when the EvEnergy-User header is set to a valid
user ID, this field will indicate whether the user is currently
connected to this EVSE Site's CPMS. If the request is not made in
the context of a user, or the site does not have a CPMS connection,
this field will be null.
readOnly: true
VPPModes:
title: VPPModes
type: object
description: >-
VPP (Virtual Power Plant) mode capabilities indicating which control
modes are supported by the resource.
required:
- target_power
- import_max_power
- export_max_power
- charge_mode
properties:
target_power:
type: boolean
description: Whether target power control mode is supported.
readOnly: true
example: true
import_max_power:
type: boolean
description: Whether import maximum power control mode is supported.
readOnly: true
example: true
export_max_power:
type: boolean
description: Whether export maximum power control mode is supported.
readOnly: true
example: false
charge_mode:
type: boolean
description: Whether charge mode control is supported.
readOnly: true
example: true
examples:
- target_power: true
import_max_power: true
export_max_power: false
charge_mode: true
EVSEConnectivity:
title: EVSEConnectivity
type: object
description: >-
Connectivity snapshot for an EVSE including signal strength, SIM data,
firmware version, and connection reliability.
required:
- signal_strength_rssi_dbm
- lowest_signal_strength_rssi_dbm_7d
- highest_signal_strength_rssi_dbm_7d
- connection_reliability_30d
- ip_address
- iccid
- firmware_version
- latest_status_log
properties:
signal_strength_rssi_dbm:
type:
- integer
- 'null'
description: Last known signal strength in RSSI dBm. Null for WiFi EVSEs.
readOnly: true
example: -65
lowest_signal_strength_rssi_dbm_7d:
type:
- integer
- 'null'
description: >-
Lowest signal strength in RSSI dBm over the past 7 days. Null for
WiFi EVSEs.
readOnly: true
example: -89
highest_signal_strength_rssi_dbm_7d:
type:
- integer
- 'null'
description: >-
Highest signal strength in RSSI dBm over the past 7 days. Null for
WiFi EVSEs.
readOnly: true
example: -57
connection_reliability_30d:
type: integer
description: >-
Connection reliability over the past 30 days, from 0 (fully offline)
to 100 (fully online).
readOnly: true
example: 97
ip_address:
type:
- string
- 'null'
description: >-
The IP address assigned to the EVSE's SIM. Null if no SIM data is
available.
readOnly: true
example: 10.193.28.42
iccid:
type:
- string
- 'null'
description: The ICCID of the EVSE's SIM card. Null if no SIM data is available.
readOnly: true
example: '8944110000001234567'
firmware_version:
type:
- string
- 'null'
description: The current firmware version running on the EVSE. Null if not known.
readOnly: true
example: 1.2.3
latest_status_log:
oneOf:
- type:
- string
- 'null'
example: >-
https://api.ev.energy/v2/evses/evse01HSH04KDEWF6Z4DB2J77J74K5/status_logs/2024-04-17T09:39:45.984584Z/
format: uri
- $ref: '#/components/schemas/EVSEStatusLog'
description: >-
An expandable reference to the most recent status log for this EVSE.
URL by default, full object when ?expand=latest_status_log is used.
readOnly: true
EVSEFirmwareVersion:
title: EVSEFirmwareVersion
type: object
description: A specific firmware release available for one or more EVSE models.
required:
- id
- url
- version
- public_version
- change_log
- support_url
properties:
id:
type: string
pattern: evsf[A-Z\d]{26}
example: evsf01HSH04KDEWF6Z4DB2J77J74K5
readOnly: true
url:
type: string
format: uri
example: >-
https://api.ev.energy/v2/evse_firmware_versions/evsf01HSH04KDEWF6Z4DB2J77J74K5/
readOnly: true
version:
type: string
description: The internal firmware version identifier.
example: 1.2.3
readOnly: true
public_version:
type:
- string
- 'null'
description: >-
The publicly displayed version label, if different from the internal
version.
example: '1.2'
readOnly: true
change_log:
type:
- string
- 'null'
description: A summary of the changes in this firmware release.
example: Bug fixes and stability improvements
readOnly: true
support_url:
type:
- string
- 'null'
format: uri
description: A link to documentation describing this firmware version.
example: https://example.com/firmware/1.2
readOnly: true
VehicleReconnectionUrl:
title: VehicleReconnectionUrl
type: object
examples:
- url: >-
https://app.ev.energy/vehicle-onboarding/start/56091b3b-86e9-4e7c-a825-f99e5d131234
expiry: '2022-11-03T20:26:10.344522Z'
description: >-
A URL for a user to re-authenticate their vehicle alongside it's
metadata.
properties:
url:
type: string
format: uri
example: >-
https://app.ev.energy/vehicle-onboarding/start/56091b3b-86e9-4e7c-a825-f99e5d131234
readOnly: true
expires_at:
type: string
format: date-time
example: '2022-11-03T20:26:10.344522Z'
readOnly: true
EVSEReconnectionUrl:
title: EVSEReconnectionUrl
x-stoplight:
id: evse-reconnection-url-schema
type: object
examples:
- url: >-
https://app.ev.energy/evse-onboarding/start/56091b3b-86e9-4e7c-a825-f99e5d131234
description: A URL for a user to re-authenticate their EVSE.
properties:
url:
type: string
x-stoplight:
id: evse-reconnection-url-field
format: uri
example: >-
https://app.ev.energy/evse-onboarding/start/56091b3b-86e9-4e7c-a825-f99e5d131234
readOnly: true
CarbonFeed:
title: CarbonFeed
type: object
description: >-
A carbon feed representing a source of carbon intensity data for a
specific region or grid.
x-tags:
- Carbon
required:
- id
- url
- name
properties:
id:
type: string
description: Unique identifier for the carbon feed.
pattern: cabf[A-Z\d]{26}
example: cabf01HN2NJ9NMRZBXT1H6FT9N7735
readOnly: true
url:
type: string
format: uri
example: https://api.ev.energy/v2/carbon_feeds/cabf01HN2NJ9NMRZBXT1H6FT9N7735
readOnly: true
name:
type: string
description: Human-readable name for the carbon feed.
example: UK National Grid
readOnly: true
GridFeed:
title: GridFeed
type: object
description: >-
A grid feed representing a source of grid signal data used for smart
charging decisions.
x-tags:
- Grid
required:
- id
- url
- name
- reference_code
- priority
properties:
id:
type: string
description: Unique identifier for the grid feed.
pattern: grfd[A-Z\d]{26}
example: grfd01HN2NJ9NMRZBXT1H6FT9N7735
readOnly: true
url:
type: string
format: uri
example: https://api.ev.energy/v2/grid_feeds/grfd01HN2NJ9NMRZBXT1H6FT9N7735
readOnly: true
name:
type: string
description: Human-readable name for the grid feed.
example: CAISO Peak Demand
readOnly: true
reference_code:
type: string
description: >-
Machine-readable reference code for the grid feed, consistent across
environments.
example: CAISO_PEAK
readOnly: true
priority:
type: integer
description: >-
Priority level (1-10) used to resolve conflicts when a user has
multiple overlapping grid feeds.
minimum: 1
maximum: 10
example: 8
readOnly: true
GridLevel:
title: GridLevel
type: object
description: >-
A grid level representing a time-varying signal value within a grid
feed. Values are between 1 and 100; values above 50 discourage charging
during the interval, while values below 50 encourage it. A value of 50
has no effect.
x-tags:
- Grid
required:
- value
- started_at
- interval_seconds
- created_at
properties:
value:
type: integer
description: >-
The grid level value (1-100). 50 is neutral, higher values
discourage charging, lower values encourage it.
minimum: 1
maximum: 100
example: 80
readOnly: true
started_at:
type: string
format: date-time
nullable: true
description: >-
When this grid level interval began (ISO 8601 datetime). Null if the
interval has no lower bound.
example: '2024-01-15T18:00:00Z'
readOnly: true
interval_seconds:
type: integer
nullable: true
description: >-
The duration of this grid level interval in seconds. Null if the
interval has no upper or lower bound.
example: 10800
readOnly: true
created_at:
type: string
format: date-time
description: When this grid level was created (ISO 8601 datetime).
example: '2024-01-14T09:00:00Z'
readOnly: true
CarbonIntensities:
title: CarbonIntensities
type: object
description: A collection of carbon intensity data points for a specific carbon feed.
properties:
url:
type: string
format: uri
example: >-
https://api.ev.energy/v2/carbon_feeds/cabf01HN2NJ9NMRZBXT1H6FT9N7735/carbon_intensities
readOnly: true
carbon_feed:
type: string
format: uri
example: https://api.ev.energy/v2/carbon_feeds/cabf01HN2NJ9NMRZBXT1H6FT9N7735
readOnly: true
carbon_intensities:
type: array
description: A list of carbon intensity data points.
items:
$ref: '#/components/schemas/CarbonIntensity'
readOnly: true
CarbonIntensity:
title: CarbonIntensity
type: object
description: >-
A carbon intensity data point representing CO2 emissions per unit of
electricity generated.
x-tags:
- Carbon
required:
- started_at
- interval_seconds
- co2_intensity_grams_per_kilowatt_hour
- created_at
properties:
started_at:
type: string
format: date-time
description: When this interval began.
example: '2024-01-15T10:00:00Z'
readOnly: true
interval_seconds:
type: integer
description: The number of seconds that this interval lasts for.
example: 1800
readOnly: true
co2_intensity_grams_per_kilowatt_hour:
type: integer
description: Carbon intensity in gCO2/kWh.
example: 245
readOnly: true
created_at:
type: string
format: date-time
description: When this record was created (ISO 8601 datetime).
example: '2024-01-15T09:45:00Z'
readOnly: true
Price:
title: Price
type: object
description: A price for a specific time interval.
x-tags:
- Tariffs
required:
- started_at
- interval_seconds
- price_minor_units
properties:
started_at:
type: string
format: date-time
description: When this price interval began (ISO 8601 datetime).
example: '2024-01-15T10:00:00Z'
readOnly: true
interval_seconds:
type: integer
description: The duration of this price interval in seconds.
example: 1800
readOnly: true
price_minor_units:
type: integer
description: The price in minor currency units (e.g., pence for GBP).
example: 10
readOnly: true
CPMSProvider:
title: CPMSProvider
type: object
description: Represents a ChargePoint Management System provider.
required:
- id
- url
- name
- icon
properties:
id:
enum:
- CHARGEPOINT
- SWTCH
url:
type: string
example: https://api.ev.energy/v2/cpms_providers/CHARGEPOINT/
name:
type: string
icon:
type:
- string
- 'null'
format: uri
Timezone:
title: Timezone
type: object
description: >-
An IANA timezone that can be assigned to user-facing resources such as
smart charging schedules.
required:
- id
- url
- name
properties:
id:
type: string
pattern: tzon[A-Z\d]{26}
example: tzon01HRFHBCM7VBSWRPVYFBQMH2BR
url:
type: string
format: uri
example: https://api.ev.energy/v2/timezones/tzon01HRFHBCM7VBSWRPVYFBQMH2BR
name:
type: string
example: Europe/London
description: IANA timezone name.
Notification:
title: Notification
description: Something that the user should be informed about.
type: object
examples:
- id: notf67O36PLTFDB57M0E5L33JZLGM0
url: https://api.ev.energy/notifications/notf67O36PLTFDB57M0E5L33JZLGM0
message_id: ERR0123
category: ACTIONABLE
event_time: '2019-08-24T14:15:22Z'
short_text_title: Your car is disconnected
short_text_body: We need to reconnect to keep smart charging your car
detail_page_title: Your car is disconnected
detail_page_body: >-
Your car has been disconnected. This happens when your password is
reset. We need you to re-authorise ev.energy to access your account
in order for us to keep managing your charging. Blah blah blah.
external_link: http://example.com
external_button_label: More info
read_at: '2019-08-24T14:20:22Z'
resolved_at: '2019-08-25T14:15:22Z'
required:
- id
- url
- message_id
- category
- event_time
- short_text_title
- short_text_body
- detail_page_title
- detail_page_body
- external_link
- external_button_label
properties:
id:
type: string
pattern: notf[A-Z\d]{26}
example: notf67O36PLTFDB57M0E5L33JZLGM0
description: Unique identifier for the Notification
url:
type: string
format: uri
example: https://api.ev.energy/notifications/notf67O36PLTFDB57M0E5L33JZLGM0
message_id:
type: string
description: Internal identifier for this notification type. E.g. 'ERR0023'
category:
description: Category of this notification type
enum:
- ACTIONABLE
- SERVICE
- RETRY
- MARKETING
- INTERNAL
event_time:
type: string
format: date-time
description: The timestamp of the event described by this notification
short_text_title:
type: string
description: Short title for the notification
maxLength: 33
short_text_body:
type: string
description: Short description of the event being notified
maxLength: 49
detail_page_title:
type: string
description: Title of a help page giving more information about this notification
detail_page_body:
type: string
description: Text of a help page giving more information about this notification
external_link:
type:
- string
- 'null'
description: URL of a web page giving further information about this notification
format: uri
external_button_label:
type: string
description: >-
Text to be displayed on a button leading to the external_link
location
read_at:
type: string
format: date-time
description: When the user examined the contents of this notification
resolved_at:
type: string
format: date-time
description: When the problem associated with this notification was resolved
RFC9457ProblemDetail:
title: RFC 9457 Problem Detail
x-tags:
- problems
type: object
required:
- title
- detail
properties:
type:
type: string
format: uri
example: https://api.ev.energy/v2/problems/example-problem/
status:
type: number
example: 400
title:
type: string
example: Short description
detail:
type: string
example: Long, more specific description.
instance:
type: string
format: uri
example: https://api.ev.energy/v2/users/user01HN2P75GBNFRJPCZJXEFVXH5E
notification:
$ref: '#/components/schemas/Notification'
examples:
- type: https://api.ev.energy/v2/problems/example-problem/
status: 400
title: Short description
detail: Long, more specific description.
instance: https://api.ev.energy/v2/users/user01HN2P75GBNFRJPCZJXEFVXH5E
notification:
id: notf01HTHKTXVB77901324BCQPF1RB
url: https://api.ev.energy/notifications/notf01HTHKTXVB77901324BCQPF1RB
message_id: ERR0123
category: ACTIONABLE
event_time: '2019-08-24T14:15:22Z'
short_text_title: Your car is disconnected
short_text_body: We need to reconnect to keep smart charging your car
detail_page_title: Your car is disconnected
detail_page_body: >-
Your car has been disconnected. This happens when your password is
reset. We need you to re-authorise ev.energy to access your
account in order for us to keep managing your charging. Blah blah
blah.
external_link: http://example.com
external_button_label: More info
read_at: '2019-08-24T14:20:22Z'
resolved_at: '2019-08-25T14:15:22Z'
GeoJsonPolygon:
title: GeoJsonPolygon
type: object
description: >-
RFC 7946 GeoJSON Polygon in WGS 84. Positions are [longitude, latitude]
(note the order — this is the GeoJSON interchange standard, not the
{latitude, longitude} object used elsewhere in this API). The first ring
is the exterior boundary; any further rings are holes.
required:
- type
- coordinates
properties:
type:
type: string
enum:
- Polygon
coordinates:
type: array
description: >-
Array of linear rings; each ring is a closed list of [longitude,
latitude] positions (first position repeated last).
minItems: 1
maxItems: 100
items:
type: array
minItems: 4
maxItems: 25000
items:
type: array
minItems: 2
maxItems: 2
items:
type: number
GeoJsonMultiPolygon:
title: GeoJsonMultiPolygon
type: object
description: >-
RFC 7946 GeoJSON MultiPolygon in WGS 84. Positions are [longitude,
latitude]. Each member is a Polygon coordinate array.
required:
- type
- coordinates
properties:
type:
type: string
enum:
- MultiPolygon
coordinates:
type: array
description: Array of Polygon coordinate arrays.
minItems: 1
maxItems: 500
items:
type: array
minItems: 1
maxItems: 100
items:
type: array
minItems: 4
maxItems: 25000
items:
type: array
minItems: 2
maxItems: 2
items:
type: number
securitySchemes:
oauth2:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://api.ev.energy/o/token/
refreshUrl: https://api.ev.energy/o/token/
scopes:
carbon:read: ''
grid:read: ''
evse:read: ''
evse:write: ''
vehicle:read: ''
user:read: ''
charging_session:read: ''
tariff:read: ''
tariff:prices:read: ''
user:write: ''
inverter:read: ''
inverter:write: ''
home_battery:read: ''
home_energy:read: ''
boundary_meter:read: ''
vehicle:write: ''
vehicle_catalogue:write: >-
Update shared vehicle-catalogue reference data (e.g. a model's
default connector type)
charging_session:write: ''
solar:write: ''
solar:read: ''
subscription:read: ''
debug:read: ''
dispatch_coordinator:read: ''
dispatch_event:write: ''
solar_forecast:read: ''
payout_method:read: Read a user's preferred payout method
payout_method:write: Set, update, or clear a user's preferred payout method
notification_preferences:read: Read a user's notification group opt-in state
notification_preferences:write: Update a user's notification group opt-in state
route_planner_preferences:read: Read a user's EV Route Planner preferences
route_planner_preferences:write: Update a user's EV Route Planner preferences
saved_routes:read: Read a user's saved route-planner routes
saved_routes:write: Create, update, or delete a user's saved routes
region:read: Read region and region group boundary data
region:write: Create regions and region groups
authorizationCode:
authorizationUrl: https://api.ev.energy/o/authorize/
tokenUrl: https://api.ev.energy/o/token/
refreshUrl: https://api.ev.energy/o/token/
scopes: {}
requestBodies: {}
parameters:
previous:
name: page_before
description: Return results from the page after this ID.
in: query
required: false
schema:
type: string
pattern: '[a-z]{4}[A-Z\d]{26}'
example: xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR
next:
name: page_after
description: Return results from the page before this ID.
in: query
required: false
schema:
type: string
pattern: '[a-z]{4}[A-Z\d]{26}'
example: xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR
page:
name: page
description: The page number to return results for.
in: query
required: false
schema:
type: number
example: 2
page_size:
name: page_size
description: Specify the number of results to return per page.
in: query
required: false
schema:
type: integer
default: 25
minimum: 1
maximum: 100
example: 10
expand:
name: expand
in: query
schema:
type: string
example: user
description: Specify a url field to expand into a nested resource.
svix-id:
name: svix-id
in: header
required: true
description: >-
Unique identifier for this webhook message. It remains stable across
delivery retries of the same event, so receivers can use it to
deduplicate.
schema:
type: string
example: msg_2eoqqPZwMlztxZbIXr0eeqYTscI
svix-timestamp:
name: svix-timestamp
in: header
required: true
description: >-
The time at which this webhook message was dispatched, as a Unix epoch
timestamp in seconds.
schema:
type: string
example: '1674087231'
svix-signature:
name: svix-signature
in: header
required: true
description: >-
Space-separated list of HMAC signatures used to verify that the payload
was sent by ev.energy and was not tampered with. See
https://docs.svix.com/receiving/verifying-payloads/how for how to
verify.
schema:
type: string
example: v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=
expand-on-user:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- default_location.tariff
- default_location.tariff.supplier
- default_location.evse_site
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-evse:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- user
- model
- model.make
- latest_status_log
- ct_clamp
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-evse-connectivity:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- latest_status_log
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-ctclamp:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- evse
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-ctclamplog:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- ct_clamp
- ct_clamp.evse
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-dispatcherlog:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- charging_sub_session
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-evsemodel:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- make
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-evsestatuslog:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- evse
- evse.model
- evse.model.make
- evse.user
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-vehicle:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- user
- trim
- trim.model
- trim.model.make
- latest_status_log
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-vehicletrim:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- model
- model.make
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-vehiclemodel:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- make
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-programvehiclecompatibility:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- model
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-vehiclestatuslog:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- vehicle
- vehicle.trim
- vehicle.trim.model
- vehicle.trim.model.make
- vehicle.user
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-vehicleapierrorlog:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- vehicle
- vehicle.trim
- vehicle.trim.model
- vehicle.trim.model.make
- vehicle.user
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-vehiclelocationlog:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- vehicle
- vehicle.trim
- vehicle.trim.model
- vehicle.trim.model.make
- vehicle.user
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-vehiclecommandlog:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- vehicle
- vehicle.trim
- vehicle.trim.model
- vehicle.trim.model.make
- vehicle.user
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-evsecommandlog:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- evse
- evse.model
- evse.model.make
- evse.user
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-evseerrorlog:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- evse
- evse.model
- evse.model.make
- evse.user
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-evseocpplog:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- evse
- evse.model
- evse.model.make
- evse.user
explode: true
description: Specify a url field to expand into a nested resource.
ocpp-action:
name: action
in: query
schema:
type: string
example: Heartbeat
enum:
- Authorize
- BootNotification
- CancelReservation
- CertificateSigned
- ChangeAvailability
- ChangeConfiguration
- ClearCache
- ClearChargingProfile
- DataTransfer
- DeleteCertificate
- DiagnosticsStatusNotification
- ExtendedTriggerMessage
- FirmwareStatusNotification
- GetCompositeSchedule
- GetConfiguration
- GetDiagnostics
- GetInstalledCertificateIds
- GetLocalListVersion
- GetLog
- Heartbeat
- InstallCertificate
- LogStatusNotification
- MeterValues
- RemoteStartTransaction
- RemoteStopTransaction
- ReserveNow
- Reset
- SecurityEventNotification
- SendLocalList
- SetChargingProfile
- SignCertificate
- SignedFirmwareStatusNotification
- SignedUpdateFirmware
- StartTransaction
- StatusNotification
- StopTransaction
- TriggerMessage
- UnlockConnector
- UpdateFirmware
description: Filter by OCPP action label.
ocpp-action__in:
name: action__in
in: query
schema:
type: string
example: Heartbeat,StatusNotification
description: Filter by multiple OCPP action labels (comma-separated).
ocpp-direction:
name: direction
in: query
schema:
type: string
example: SENT
enum:
- SENT
- RECEIVED
description: Filter by message direction (SENT or RECEIVED).
ocpp-error_code:
name: error_code
in: query
schema:
type: string
example: NoError
enum:
- NoError
- NotImplemented
- NotSupported
- InternalError
- ProtocolError
- SecurityError
- FormationViolation
- PropertyConstraintViolation
- OccurenceConstraintViolation
- TypeConstraintViolation
- GenericError
- UnknownError
description: Filter by OCPP response error code.
ocpp-error_code__in:
name: error_code__in
in: query
schema:
type: string
example: InternalError,ProtocolError
description: Filter by multiple OCPP response error codes (comma-separated).
expand-on-tariff:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- supplier
- scheduler_tariff
- prices
explode: true
description: >-
Specify a url field to expand into a nested resource. The prices
expansion requires tariff:prices:read scope.
expand-on-carbonintensity:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- carbon_feed
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-chargingsession:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- vehicle
- evse
- sub_sessions
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-chargingsubsession:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- evse
- evse.latest_status_log
- evse.model
- evse.model.make
- evse.user
- vehicle
- vehicle.latest_status_log
- vehicle.trim
- vehicle.trim.model
- vehicle.trim.model.make
- vehicle.user
- energy_usage
- schedules
- assessment
- flags
- debug_metadata
- tariff
- tariff.supplier
- carbon_feed
- grid_feeds
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-chargingsubsession-flags:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- charging_sub_session
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-chargingsubsession-debug-metadata:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- charging_sub_session
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-chargingsubsession-schedules:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- charging_sub_session
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-chargingsubsession-scheduleplans:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- charging_sub_session
- price_data
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-chargingsubsession-assessment:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- charging_sub_session
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-chargingsubsession-energyusage:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- charging_sub_session
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-solararray:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- user
- inverter
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-solarforecastlog:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- solar_forecast
explode: true
description: Specify a url field to expand into a nested resource.
solar_forecast_id:
name: solar_forecast_id
in: path
required: true
schema:
type: string
pattern: solf[A-Z\d]{26}
example: solf01JASZTD3T7N39DTZPBJVXNPKP
description: The ID of the specific solar forecast.
started_at__gte:
name: started_at__gte
in: query
schema:
type: string
format: date-time
example: '2024-04-17T09:00:00.100000Z'
description: Filters for logs with a valid period start at or after this datetime.
started_at__lte:
name: started_at__lte
in: query
schema:
type: string
format: date-time
example: '2024-04-17T09:00:00.100000Z'
description: Filters for logs with a valid period start at or before this datetime.
expand-on-subscription:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- user
- offering
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-inverter:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- model
- model.make
- latest_status_log
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-invertermodel:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- make
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-homebatterymodel:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- make
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-homebattery:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- model
- model.make
- latest_status_log
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-boundarymetermodel:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- make
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-boundarymeter:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- model
- model.make
- latest_status_log
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-homebatterystatuslog:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- home_battery
- home_battery.model
- home_battery.model.make
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-boundarymeterstatuslog:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- boundary_meter
- boundary_meter.model
- boundary_meter.model.make
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-rebatetype:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- required_evidence
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-userrebate:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- rebate_type
- rebate_type.required_evidence
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-rebateevidencefile:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- rebate_evidence_type
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-supportticket:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- user
- messages
explode: true
description: Specify a url field to expand into a nested resource.
expand-on-schedule:
name: expand
in: query
schema:
type: array
items:
type: string
enum:
- charging_sub_session
explode: true
description: Specify a url field to expand into a nested resource.
vehicle_id:
name: vehicle_id
in: path
required: true
schema:
type: string
pattern: vhcl[A-Z\d]{26}
example: vhcl01HRFF3SEVSCRAV9B3CHVDFN0H
description: The ID of the specific vehicle to retrieve.
evse_id:
name: evse_id
in: path
required: true
schema:
type: string
pattern: evse[A-Z\d]{26}
example: evse01HSH04KDEWF6Z4DB2J77J74K5
description: The ID of the specific EVSE to retrieve.
ct_clamp_id:
name: ct_clamp_id
in: path
required: true
schema:
type: string
pattern: ctcl[A-Z\d]{26}
example: ctcl01HSH04KDEWF6Z4DB2J77J74K5
description: The ID of the specific CT clamp.
evse_firmware_version_id:
name: evse_firmware_version_id
in: path
required: true
schema:
type: string
pattern: evsf[A-Z\d]{26}
example: evsf01HSH04KDEWF6Z4DB2J77J74K5
description: The ID of the specific EVSE firmware version.
email:
name: email
in: query
required: false
schema:
type: string
format: email
example: user@example.com
description: Filter users by email address (case-insensitive exact match).
cpid:
name: cpid
in: query
required: false
schema:
type: string
example: SHIR100001
description: Filter EVSEs by chargepoint ID (exact match).
user_id:
name: user_id
in: path
required: true
schema:
type: string
pattern: ^(user[A-Z\d]{26})$
examples:
- user01HN2NJ9NMRZBXT1H6FT9N7735
- me
description: The ID of the specific user to retrieve.
saved_route_id:
name: saved_route_id
in: path
required: true
schema:
type: string
pattern: savr[A-Z\d]{26}
example: savr01HRFF3SEVSCRAV9B3CHVDFN0H
description: The ID of the specific saved route.
vehicle_trim_id:
name: vehicle_trim_id
in: path
required: true
schema:
type: string
pattern: trim[A-Z\d]{26}
example: trim01HRFHBCM7VBSWRPVYFBQMH2BR
description: The ID of the specific vehicle trim to retrieve.
vehicle_model_id:
name: vehicle_model_id
in: path
required: true
schema:
type: string
pattern: vmod[A-Z\d]{26}
example: vmod01HSBR8Z36GD7A46K7M4R12VG0
description: The ID of the specific vehicle model to retrieve.
region:
name: region
in: path
required: true
schema:
type: string
enum:
- NORTH_AMERICA
- EUROPE
example: NORTH_AMERICA
description: The charging region of the connector.
vehicle_make_id:
name: vehicle_make_id
in: path
required: true
schema:
type: string
pattern: vmak[A-Z\d]{26}
example: vmak01HRFHBCM7VBSWRPVYFBQMH2BR
description: The ID of the specific vehicle make to retrieve.
evse_model_id:
name: evse_model_id
in: path
required: true
schema:
type: string
pattern: emod[A-Z\d]{26}
example: emod01HS9A05HDZKZ5GCW92HH6GJYN
description: The ID of the specific EVSE model to retrieve.
evse_make_id:
name: evse_make_id
in: path
required: true
schema:
type: string
pattern: emak[A-Z\d]{26}
example: emak01HSB50J37V3Q5BKXSXTM64K7K
description: The ID of the specific EVSE make to retrieve.
timezone_id:
name: timezone_id
in: path
required: true
schema:
type: string
pattern: tzon[A-Z\d]{26}
example: tzon01HRFHBCM7VBSWRPVYFBQMH2BR
description: The ID of the specific timezone to retrieve.
dispatch_coordinator_id:
name: dispatch_coordinator_id
in: path
required: true
schema:
type: string
example: dc000000
description: The ID of the specific dispatch coordinator.
dispatch_event_id:
name: dispatch_event_id
in: path
required: true
schema:
type: string
example: devt01HN2NJ9NMRZBXT1H6FT9N7735
description: The ID of the specific dispatch event.
supplier_id:
name: supplier_id
in: path
required: true
schema:
type: string
pattern: supl[A-Z\d]{26}
example: supl01HN2NJ9NMRZBXT1H6FT9N7735
description: The ID of the specific supplier to retrieve.
tariff_id:
name: tariff_id
in: path
schema:
type: string
pattern: tari[A-Z\d]{26}
example: tari01HN2NJ9NMRZBXT1H6FT9N7735
required: true
description: The ID of the specific tariff to retrieve.
supplier_id_query:
name: supplier_id
in: query
required: false
schema:
type: string
description: The ID of the supplier to filter by.
tariff_valid_query:
name: valid
in: query
required: false
schema:
type: boolean
description: >-
Filter by whether the tariff is currently open to new sign-ups
(valid_from on or before today, and valid_until on or after today or
unset). `true` returns only currently-available tariffs; `false` returns
only superseded or not-yet-available ones. Omit to return all tariffs.
tariff_gsp_group_query:
name: gsp_group
in: query
required: false
schema:
type: string
example: _C
description: Filter by GB Grid Supply Point (DNO region) code, e.g. `_C` for London.
available_for_user_id:
name: available_for_user_id
in: query
schema:
type: string
pattern: user[A-Z\d]{26}
example: user01HN2NJ9NMRZBXT1H6FT9N7735
description: >-
Filter to only return resources available in the user's region and
program.
ordering_by_name:
name: ordering
in: query
schema:
type: string
enum:
- name
- '-name'
description: >-
Sort the list alphabetically by `name` (`-name` for reverse). When
omitted, results are returned in their default creation order.
Unrecognised values silently fall back to the default ordering.
include_optional_tariff:
name: include_optional
in: query
schema:
type: string
enum:
- daily_prices
example: daily_prices
allowReserved: false
allowEmptyValue: false
description: Include optional tariffs.
version-2:
name: EvEnergy-Version
description: Specify the version of this endpoint to use.
required: false
in: header
schema:
type: number
enum:
- 2
Accept-Language:
name: Accept-Language
in: header
required: false
schema:
type: string
description: Indicates the natural language and locale that the client prefers.
evse_id_q:
name: evse_id
in: query
schema:
type: string
pattern: evse[A-Z\d]{26}
example: evse01HSH04KDEWF6Z4DB2J77J74K5
description: Filter to only resources related to the given EVSE.
vehicle_id_q:
name: vehicle_id
in: query
schema:
type: string
pattern: vhcl[A-Z\d]{26}
example: vhcl01HRFF3SEVSCRAV9B3CHVDFN0H
description: Filter to only resources related to the given Vehicle.
notification_id:
name: notification_id
description: The ID of the specific notification to retrieve.
in: path
required: true
schema:
type: string
pattern: notf[A-Z\d]{26}
example: notf67O36PLTFDB57M0E5L33JZLGM0
support_ticket_id:
name: support_ticket_id
description: The ID of the specific support ticket to retrieve.
in: path
required: true
schema:
type: string
pattern: tick[A-Z\d]{26}
example: tick01HN2NJ9NMRZBXT1H6FT9N7735
message_id:
name: message_id
description: The ID of the specific support ticket message to retrieve.
in: path
required: true
schema:
type: string
pattern: tmsg[A-Z0-9]{26}
example: tmsgA1B2C3D4E5F6G7H8I9J0K1L2M3
carbon_feed_id:
name: carbon_feed_id
description: Uniquely identify a specific carbon feed.
in: path
schema:
type: string
pattern: cabf[A-Z\d]{26}
example: cabf01HN2NJ9NMRZBXT1H6FT9N7735
required: true
grid_feed_id:
name: grid_feed_id
description: Uniquely identify a specific grid feed.
in: path
schema:
type: string
pattern: grfd[A-Z\d]{26}
example: grfd01HN2NJ9NMRZBXT1H6FT9N7735
required: true
charging_session_id:
name: charging_session_id
description: Uniquely identify a specific charging session.
in: path
schema:
type: string
pattern: cses[A-Z\d]{26}
example: cses01HSH04KDEWF6Z4DB2J77J74K5
required: true
charging_sub_session_id:
name: charging_sub_session_id
description: Uniquely identify a specific charging sub-session.
in: path
schema:
type: string
pattern: csub[A-Z\d]{26}
example: csub01HSH04KDEWF6Z4DB2J77J74K5
required: true
user_id_q:
name: user_id
in: query
required: false
schema:
type: string
example: me
description: Filter collection to only resources owned by a specific user.
sampled_at__gte:
name: sampled_at__gte
in: query
schema:
type: string
format: date-time
example: '2024-04-17T09:39:45.984584Z'
description: Filters for logs sampled at or after this datetime.
sampled_at__lte:
name: sampled_at__lte
in: query
schema:
type: string
format: date-time
example: '2024-04-17T09:39:45.984584Z'
description: Filters for logs sampled at or before this datetime.
logged_at__gte:
name: logged_at__gte
in: query
schema:
type: string
format: date-time
example: '2024-04-17T09:39:45.984584Z'
description: Filters for logs logged at or after this datetime.
logged_at__lte:
name: logged_at__lte
in: query
schema:
type: string
format: date-time
example: '2024-04-17T09:39:45.984584Z'
description: Filters for logs logged at or before this datetime.
energy_delivered_watt_hours__gte:
name: energy_delivered_watt_hours__gte
in: query
schema:
type: integer
example: 500
description: Filters for values greater than or equal to a value.
energy_delivered_watt_hours__lte:
name: energy_delivered_watt_hours__lte
in: query
schema:
type: integer
example: 500
description: Filters for values less than or equal to a value.
energy_delivered_watt_hours__gt:
name: energy_delivered_watt_hours__gt
in: query
schema:
type: integer
example: 0
description: Filters for values greater than a value.
is_finished:
name: is_finished
in: query
required: false
schema:
type: boolean
example: false
description: Filters for sessions that are finished.
mode:
name: mode
in: query
required: false
schema:
type: string
example: SMART
enum:
- SMART
- BOOST
- UNMANAGED_HOME
- UNMANAGED_OTG
- MANAGED_OTG
description: Filters sessions to only return sessions with this mode.
user:
name: EvEnergy-User
description: >-
If the client is authenticated using Client Credentials, setting
EvEnergy-User to a valid user ID allows requests to be made as if you
were directly authenticated as that user.
in: header
required: false
schema:
type: string
pattern: user[A-Z\d]{26}
example: user01HN2NJ9NMRZBXT1H6FT9N7735
inverter_make_id_q:
name: make_id
in: query
required: false
schema:
type: string
example: imakWNZ5N0A5D1PR89HJ7STXEWYO58
description: The ID of an Inverter Make to filter by.
evse_make_id_q:
name: make_id
in: query
required: false
schema:
type: string
example: emak01HS8FRMXGE3566EDXCMWGW5W4
description: The ID of an EVSE Make to filter by.
vehicle_make_id_q:
name: make_id
in: query
required: false
schema:
type: string
example: vmak01HN2NV5DY9C262PQKG75GHN8K
description: The ID of a Vehicle Make to filter by
home_battery_make_id_q:
name: make_id
in: query
required: false
schema:
type: string
example: bmakK7XDPL63NNBDQ5DPB6K3TP87JA
description: The ID of a Home Battery Make to filter by.
boundary_meter_make_id_q:
name: make_id
in: query
required: false
schema:
type: string
example: bmma01J5DCXX8DMJDJYGVR1DW4M001
description: The ID of a Boundary Meter Make to filter by.
vehicle_model_id_q:
name: model_id
in: query
required: false
schema:
type: string
example: vmod01HN2NV5DY9C262PQKG75GHN8K
description: The ID of a Vehicle Model to filter by.
user_id_onboarding:
name: user_id
in: query
required: true
schema:
type: string
pattern: user[A-Z\d]{26}
example: user01HN2NJ9NMRZBXT1H6FT9N7735
description: The ID of a user to onboard a device for.
evenergy-user-required:
name: EvEnergy-User
in: header
required: false
description: >-
This endpoints requires a user ID to be specified via this header when
using Client Credentials authentication.
schema:
type: string
pattern: user[A-Z\d]{26}
example: user01HN2NJ9NMRZBXT1H6FT9N7735
client_id:
name: client_id
in: query
required: true
schema:
type: string
example: sandbox-cc-id
minLength: 1
description: >-
Your OAuth2 application client_id, issued when your ev.energy API
integration was provisioned. This is the same value used when obtaining
tokens via the Authorization Code or Client Credentials flows — not a
user-created value. Passing an unrecognised string will result in an
error. The onboarding endpoints redirect the user's browser through an
OAuth flow to connect their device; the client_id determines which
registered application is initiating the flow, so the correct branding,
redirect URIs, and scopes are applied.
rebate_evidence_file_id:
description: Unique identifier for a Rebate evidence file
name: rebate_evidence_file_id
in: path
required: true
schema:
type: string
pattern: rbef[A-Z\d]{26}
example: rbefB1USP6YGD1VPIDJSHTZARUX11M
user_rebate_id:
description: Unique identifier for a User's rebate application
name: user_rebate_id
in: path
required: true
schema:
type: string
pattern: rbtu[A-Z\d]{26}
example: rbtuB1USP6YGD1VPIDJSHTZARUX11M
evse_site_id:
description: Unique identifier for a single EVSE Site.
name: evse_site_id
in: path
required: true
schema:
type: string
example: site01JX2SZ0WAFTDYVYY0JRAYREY7
pattern: site[A-Z\d]{26}
program_id:
name: program_id
in: path
required: true
schema:
type: string
description: The ID of the specific Program to retrieve.
tier_id:
name: tier_id
in: path
required: true
schema:
type: string
example: tier01JCK1HPNAANB8WN253G27SFPC
pattern: tier[A-Z\d]{26}
description: The ID of the specific Program Tier to retrieve.
participation_agreement_version_id:
name: participation_agreement_version_id
in: path
required: true
schema:
type: string
example: pagv01JCDYP6Z8MX9XWVAV0A7G3KPN
pattern: pagv[A-Z\d]{26}
description: The ID of the specific Participation Agreement Version.
responses:
Problem401Unauthorized:
description: You need to authorise requests to access this resource.
content:
application/problem+json:
schema:
type: object
required:
- title
- detail
properties:
status:
type: number
example: 401
title:
type: string
example: Unauthorized
detail:
type: string
example: Authentication credentials were not provided.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
Problem403Forbidden:
description: You do not have permission to perform this action.
content:
application/problem+json:
schema:
type: object
required:
- title
- detail
properties:
status:
type: number
example: 403
title:
type: string
example: Forbidden
detail:
type: string
example: You do not have permission to perform this action.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
Problem404NotFound:
description: >-
This resource either does not exist or the client is not authorized to
access it.
content:
application/problem+json:
schema:
type: object
required:
- title
- detail
properties:
status:
type: number
example: 404
title:
type: string
example: Not found
detail:
type: string
example: Resource does not exist or cannot be accessed.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
Problem405MethodNotAllowed:
description: Could not satisfy this HTTP method.
content:
application/problem+json:
schema:
type: object
required:
- title
- detail
properties:
status:
type: number
example: 405
title:
type: string
example: Method Not Allowed
detail:
type: string
example: Could not satisfy this HTTP method.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
Problem406NotAcceptable:
description: Could not satisfy the request Accept header.
content:
application/problem+json:
schema:
type: object
required:
- title
- detail
properties:
status:
type: number
example: 406
title:
type: string
example: Not Acceptable
detail:
type: string
example: Could not satisfy the request Accept header.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
Problem409Conflict:
description: The request conflicts with the current state of the resource.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/RFC9457ProblemDetail'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
Problem503ServiceUnavailable:
description: The command could not be delivered to the vehicle or charger.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/RFC9457ProblemDetail'
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
Problem400BadRequestList:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/RFC9457ProblemDetail'
examples:
Invalid Pagination Parameter:
$ref: '#/components/examples/ProblemInvalidPaginationParameter'
Unsupported Version:
$ref: '#/components/examples/ProblemUnsupportedVersion'
description: A problem with the request's parameters prevented it being fulfilled.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
Problem400BadRequestRetrieve:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/RFC9457ProblemDetail'
examples:
Unsupported Version:
$ref: '#/components/examples/ProblemUnsupportedVersion'
description: A problem with the request's parameters prevented it being fulfilled.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
Problem400BadRequestCreate:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/RFC9457ProblemDetail'
examples:
Request failed validation:
$ref: '#/components/examples/ProblemValidationFailedVehicle'
description: A problem with the request's parameters prevented it being fulfilled.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
RetryAfter:
$ref: '#/components/headers/retry-after'
Problem400UpdatePayoutMethodValidationFailed:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/RFC9457ProblemDetail'
examples:
Request failed validation:
value:
type: >-
https://api.ev.energy/v2/problems/validation-failed-update-payout-method/
status: 400
title: Request failed validation.
detail: 'Error on fields: receiver'
field_errors:
receiver:
- Required when receiver_wallet is PAYPAL.
description: The payout method update request body failed validation.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
Problem400UpdateEVSEValidationFailed:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/RFC9457ProblemDetail'
examples:
Request failed validation:
value:
type: >-
https://api.ev.energy/v2/problems/validation-failed-update-evse/
status: 400
title: Request failed validation.
detail: 'Error on fields: location'
field_errors:
location:
- >-
latitude must be between -90 and 90 and longitude must be
between -180 and 180.
description: The EVSE update request body failed validation.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
Problem400UpdateNotificationPreferencesValidationFailed:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/RFC9457ProblemDetail'
examples:
Request failed validation:
value:
type: >-
https://api.ev.energy/v2/problems/validation-failed-update-notification-preferences/
status: 400
title: Request failed validation.
detail: 'Error on fields: groups'
field_errors:
groups:
- 'Unknown notification group: ''charging_flower''.'
description: The notification preferences update request body failed validation.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
Problem400UpdateRoutePlannerPreferencesValidationFailed:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/RFC9457ProblemDetail'
examples:
Request failed validation:
value:
type: >-
https://api.ev.energy/v2/problems/validation-failed-update-route-planner-preferences/
status: 400
title: Request failed validation.
detail: 'Error on fields: min_charger_power_watts'
field_errors:
min_charger_power_watts:
- >-
Must be null or one of: 22000, 50000, 100000, 150000,
250000.
description: The route planner preferences update request body failed validation.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
Problem400SavedRouteValidationFailed:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/RFC9457ProblemDetail'
examples:
Request failed validation:
value:
type: >-
https://api.ev.energy/v2/problems/validation-failed-saved-route/
status: 400
title: Request failed validation.
detail: 'Error on fields: arrive_with_min_percent'
field_errors:
arrive_with_min_percent:
- Ensure this value is less than or equal to 100.
description: The saved route request body failed validation.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
Problem400VehicleModelConnectorValidationFailed:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/RFC9457ProblemDetail'
examples:
Request failed validation:
value:
type: >-
https://api.ev.energy/v2/problems/validation-failed-create-vehicle-model-connector/
status: 400
title: Request failed validation.
detail: 'Error on fields: region'
field_errors:
region:
- A connector for this region already exists.
description: The vehicle model connector request body failed validation.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
Problem400UpdateVehicleConnectorsValidationFailed:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/RFC9457ProblemDetail'
examples:
Request failed validation:
value:
type: >-
https://api.ev.energy/v2/problems/validation-failed-update-vehicle-connectors/
status: 400
title: Request failed validation.
detail: 'Error on fields: adaptors'
field_errors:
adaptors:
- An adaptor cannot match the native connector.
description: The vehicle connectors update request body failed validation.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
Problem400UpdateVehicleStateOfChargeValidationFailed:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/RFC9457ProblemDetail'
examples:
Request failed validation:
value:
type: >-
https://api.ev.energy/v2/problems/validation-failed-update-vehicle-state-of-charge/
status: 400
title: Request failed validation.
detail: 'Error on fields: state_of_charge_percentage'
field_errors:
state_of_charge_percentage:
- Ensure this value is less than or equal to 100.
description: The vehicle state of charge update request body failed validation.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
Problem422PasswordResetValidationFailed:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/RFC9457ProblemDetail'
examples:
Request failed validation:
value:
type: >-
https://api.ev.energy/v2/problems/validation-failed-password-reset/
status: 422
title: Request failed validation.
detail: 'Error on fields: email'
field_errors:
email:
- Enter a valid email address.
description: The password reset request body failed validation.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
Problem429TooManyRequests:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/RFC9457ProblemDetail'
examples:
Example 1:
value:
type: https://api.ev.energy/v2/problems/rate-limit-exceeded/
status: 429
title: Too Many Requests
detail: Request was rate limited. Try again in 42 seconds
description: The client has exceeded its rate limit.
headers:
EvEnergy-Version:
$ref: '#/components/headers/version-2'
Retry-After:
$ref: '#/components/headers/retry-after'
X-RateLimit-Limit:
$ref: '#/components/headers/x-ratelimit-limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/x-ratelimit-remaining'
headers:
link:
description: Provides links to the previous and next pages of data, if they exist.
example: >-
;
rel="previous",
;
rel="next"
schema:
type: string
link-timestamps:
description: Provides links to the previous and next pages of data, if they exist.
example: >-
;
rel="previous",
;
rel="next"
schema:
type: string
link-pages:
description: Provides links to the previous and next pages of data, if they exist.
example: >-
; rel="previous",
; rel="next"
schema:
type: string
version-2:
description: >-
Indicates the version of the API that generated this response. If
EvEnergy-Version was not specified in the request, this will be your
OAuth application's default version.
schema:
type: number
enum:
- 2
x-ratelimit-limit:
description: >-
The maximum number of requests that can be made to this endpoint per
hour. Defaults to 1000 but may vary per client.
schema:
type: number
default: 1000
x-ratelimit-remaining:
description: >-
The number of requests remaining until this client's rate limit is
reached.
schema:
type: number
default: 999
retry-after:
description: >-
The number of seconds until this client's requests will not be rate
limited.
schema:
type: number
default: 3600
examples:
ProblemInvalidPaginationParameter:
value:
type: https://api.ev.energy/v2/problems/pagination-parameters/
status: 400
title: Invalid pagination parameter
detail: 'Invalid value for pagination parameter: page_size'
ProblemUnsupportedVersion:
value:
type: https://api.ev.energy/v2/problems/pagination-parameters/
status: 400
title: Unsupported version
detail: 'Unsupported version requested: 3.0'
ProblemValidationFailedVehicle:
value:
type: https://api.ev.energy/v2/problems/validation-failed-create-vehicle/
status: 400
title: Request failed validation.
detail: 'Error on fields: user, trim'
field_errors:
user:
- This field is required.
trim:
- Invalid hyperlink - Object does not exist.
UserRebate:
value:
id: string
url: https://example.com
rebate_type:
id: string
url: https://example.com
title: string
value_description: earn up to $1000
icon: https://example.com
description_long: string
description_short: Must be purchased after 11/01/2024
requirements: >-
- Must be eligible for program
- Purchased after
11/01/2024
- Must be connected to ev.energy
required_evidence:
- title: string
description: string
upload_required: true
file:
name: string
url: https://example.com
evidence_data:
- data_type: currency
title: string
description: string
required: true
value: string
RebateType:
value:
id: rbttB1USP6YGD1VPIDJSHTZARUX11M
url: https://api.ev.energy/v2/rebate_types/rbttB1USP6YGD1VPIDJSHTZARUX11M
title: Vehicle Enrollment
value_description: earn up to $1000
icon: https://example.com
description_long: Rebate for purchasing an eligible vehicle.
description_short: Must be purchased after 11/01/2024
requirements: >-
- Must be eligible for program
- Purchased after
11/01/2024
- Must be connected to ev.energy
required_evidence:
- title: string
description: string
upload_required: true
file:
name: string
url: https://example.com
evidence_data:
- data_type: currency
title: string
description: string
required: true
value: string
RebateEvidenceFile:
value:
id: rbefB1USP6YGD1VPIDJSHTZARUX11M
url: >-
https://api.ev.energy/v2/rebate_evidence_files/rbefB1USP6YGD1VPIDJSHTZARUX11M
file_name: test_file.pdf
rebate_evidence_type: >-
https://api.ev.energy/v2/rebate_evidence_types/rbetB1USP6YGD1VPIDJSHTZARUX11M
RebateEvidenceUploadStart:
value:
id: rbefB1USP6YGD1VPIDJSHTZARUX11M
url: >-
https://api.ev.energy/v2/rebate_evidence_files/rbefB1USP6YGD1VPIDJSHTZARUX11M
presigned_url: >-
https://cdn.app.ev.energy/evenergy-development-rebates-evidence-files/user_rebates/rbtuB1USP6YGD1VPIDJSHTZARUX11M/test_file-57e02f14d0c64900bfa5c64972799c51.pdf?AWSAccessKeyId=DummyKeyID&Signature=bmLFDDk%2FuEjCB8yqYI%2FojRTZEMc%3D&Expires=1732224896
x-internal: false
security:
- oauth2: []
tags:
- name: Carbon
description: Endpoints for interacting with carbon intensity data.
- name: Charging Sessions
description: >-
Endpoints related to records of charging. See [Understanding charging
data](docs/understanding/charging_sessions.md) for how charging sessions
(plug-in episodes), charging sub-sessions (per-mode segments) and energy
usage intervals (actual energy delivery) relate to each other.
- name: CSV
description: >-
Endpoints that return CSV responses only and are not linkable to other
endpoint data.
- name: EVSEs
description: Endpoints for interacting with EVSEs.
- name: Home Batteries
description: Endpoints for interacting with home batteries.
- name: Notifications
description: Endpoints for communicating notifications.
- name: Programs
description: Endpoints related to incentivised charging programs.
- name: Rebates
description: Endpoints for interacting with rebates.
- name: Regions
description: >-
Geographic regions and region groups used for program eligibility and
tariffs.
- name: Root
description: The root endpoint which lists all the top-level collections.
- name: Schedules
description: Schema definitions for charging schedules.
- name: Sites
description: Endpoints for interacting with sites containing multiple EVSEs.
- name: Solar
description: Endpoints for interacting with solar arrays and inverters.
- name: Solar Forecasts
description: Endpoints for interacting with solar forecasts and their logs.
- name: Subscriptions
description: Endpoints for interacting with user subscriptions.
- name: Support Tickets
description: Endpoints for interacting with customer support tickets.
- name: Tariffs
description: Endpoints related to energy suppliers and their tariffs.
- name: Users
description: Endpoints for interacting with users.
- name: Vehicles
description: Endpoints for interacting with vehicles.
- name: VPP
description: Endpoints for virtual power plant - dispatch coordination and reporting.
- name: Webhooks
description: Endpoints for configuring and managing webhooks.