openapi: 3.1.0
info:
title: Tesla Fleet Energy API
description: |
The energy_sites surface of the Tesla Fleet API. Lets OAuth-authorized partners and owners read
Powerwall, Solar, and Megapack site state — site info, live status, calendar history, programs —
and write backup reserve, operation mode (self_consumption, backup, autonomous), storm mode,
time-of-use settings, and off-grid vehicle charging reserve.
Authentication uses Tesla Fleet API OAuth 2.0 with the energy_device_data (read) and
energy_cmds (write) scopes. Third-party applications must register a partner account on the
Tesla Developer Portal and pair a virtual key with the owner's account.
version: "1.0.0"
contact:
name: Tesla Developer Support
url: https://developer.tesla.com/docs/fleet-api/support/contact
license:
name: Tesla Developer Terms
url: https://developer.tesla.com/teslaplatform/developerterms
servers:
- url: https://fleet-api.prd.na.vn.cloud.tesla.com/api/1
description: North America Production
- url: https://fleet-api.prd.eu.vn.cloud.tesla.com/api/1
description: Europe / Middle East / Africa Production
security:
- BearerAuth:
- energy_device_data
- energy_cmds
tags:
- name: Products
description: Discover energy_sites and other products owned by the authenticated account
- name: Site Info
description: Static configuration of an energy site (components, address, time zone)
- name: Live Status
description: Real-time power, state-of-charge, and grid status for an energy site
- name: History
description: Historical energy production, consumption, and battery flow
- name: Backup
description: Backup reserve threshold for Powerwall sites
- name: Operation
description: Operation mode — self_consumption, backup, or autonomous
- name: Storm Mode
description: Pre-charge Powerwall to 100% ahead of severe weather alerts
- name: Time Of Use
description: Tariff schedule, peak/off-peak rate plans, and TOU optimization
- name: Off Grid Charging
description: Reserve threshold for EV charging when the site is islanded from the grid
- name: Programs
description: Virtual power plant and grid-services program participation
paths:
/products:
get:
summary: Tesla List Products
description: Returns a list of products (vehicles and energy_sites) that the authenticated user has access to. Energy sites are identified by an `energy_site_id` and may include Powerwall, Solar, and Megapack assets.
operationId: listProducts
tags:
- Products
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ProductsResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/RateLimited'
/energy_sites/{site_id}/site_info:
get:
summary: Tesla Get Energy Site Info
description: Returns static configuration of the energy site — components installed (Powerwall, Solar, Megapack), address, time zone, version, asset registration metadata, and gateway identifiers.
operationId: getEnergySiteInfo
tags:
- Site Info
parameters:
- $ref: '#/components/parameters/SiteId'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SiteInfoResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/energy_sites/{site_id}/live_status:
get:
summary: Tesla Get Energy Site Live Status
description: Returns real-time power flow at the energy site — solar production, battery charge/discharge, grid import/export, and home/load consumption — plus state-of-charge, grid status, storm-mode active flag, and timestamp.
operationId: getEnergySiteLiveStatus
tags:
- Live Status
parameters:
- $ref: '#/components/parameters/SiteId'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/LiveStatusResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/energy_sites/{site_id}/calendar_history:
get:
summary: Tesla Get Energy Site Calendar History
description: Returns time-series energy data — production, consumption, grid import/export, battery charge/discharge — aggregated by day, week, month, or year. Supports kind=energy, power, self_consumption, savings, and time_of_use.
operationId: getEnergySiteCalendarHistory
tags:
- History
parameters:
- $ref: '#/components/parameters/SiteId'
- name: kind
in: query
required: true
description: Type of history to retrieve.
schema:
type: string
enum: [energy, power, self_consumption, savings, time_of_use]
- name: period
in: query
required: false
description: Aggregation period.
schema:
type: string
enum: [day, week, month, year, lifetime]
- name: end_date
in: query
required: false
description: ISO-8601 end of the window.
schema:
type: string
format: date-time
- name: time_zone
in: query
required: false
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/CalendarHistoryResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/energy_sites/{site_id}/backup:
post:
summary: Tesla Set Backup Reserve Percent
description: Sets the percent state-of-charge that Powerwall holds in reserve for grid outages. Range 0-100. Requires the energy_cmds scope.
operationId: setBackupReservePercent
tags:
- Backup
parameters:
- $ref: '#/components/parameters/SiteId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [backup_reserve_percent]
properties:
backup_reserve_percent:
type: integer
minimum: 0
maximum: 100
description: Reserve percent to hold for outage backup.
responses:
'200':
$ref: '#/components/responses/CommandResult'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/energy_sites/{site_id}/operation:
post:
summary: Tesla Set Site Operation Mode
description: Sets the Powerwall operation mode. `self_consumption` prioritizes using stored solar on-site; `backup` reserves battery for outages; `autonomous` lets Tesla optimize against rates and grid conditions.
operationId: setSiteOperation
tags:
- Operation
parameters:
- $ref: '#/components/parameters/SiteId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [default_real_mode]
properties:
default_real_mode:
type: string
enum: [self_consumption, backup, autonomous]
description: Operation mode the site should run in.
responses:
'200':
$ref: '#/components/responses/CommandResult'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/energy_sites/{site_id}/storm_mode:
post:
summary: Tesla Set Storm Mode
description: Enables or disables Storm Mode. When enabled, Powerwall automatically pre-charges to 100% ahead of severe weather alerts in the site's region.
operationId: setStormMode
tags:
- Storm Mode
parameters:
- $ref: '#/components/parameters/SiteId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [enabled]
properties:
enabled:
type: boolean
description: Whether Storm Mode is active.
responses:
'200':
$ref: '#/components/responses/CommandResult'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/energy_sites/{site_id}/time_of_use_settings:
post:
summary: Tesla Set Time Of Use Settings
description: Updates the time-of-use tariff schedule for the site, including peak/off-peak windows, seasonal rates, and self-consumption optimization toggles.
operationId: setTimeOfUseSettings
tags:
- Time Of Use
parameters:
- $ref: '#/components/parameters/SiteId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TimeOfUseSettings'
responses:
'200':
$ref: '#/components/responses/CommandResult'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/energy_sites/{site_id}/off_grid_vehicle_charging_reserve:
post:
summary: Tesla Set Off-Grid Vehicle Charging Reserve
description: Sets the percent state-of-charge below which Powerwall will stop powering EV charging during a grid outage. Lets owners protect home loads while still allowing some vehicle charging when islanded.
operationId: setOffGridVehicleChargingReserve
tags:
- Off Grid Charging
parameters:
- $ref: '#/components/parameters/SiteId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [off_grid_vehicle_charging_reserve_percent]
properties:
off_grid_vehicle_charging_reserve_percent:
type: integer
minimum: 0
maximum: 100
responses:
'200':
$ref: '#/components/responses/CommandResult'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/energy_sites/{site_id}/programs:
get:
summary: Tesla Get Energy Site Programs
description: Returns virtual power plant and grid-services programs the site is eligible for and currently enrolled in (e.g., regional VPP, demand response).
operationId: getEnergySitePrograms
tags:
- Programs
parameters:
- $ref: '#/components/parameters/SiteId'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ProgramsResponse'
'401':
$ref: '#/components/responses/Unauthorized'
components:
securitySchemes:
BearerAuth:
type: oauth2
description: Tesla Fleet API OAuth 2.0 with PKCE. Scopes energy_device_data (read) and energy_cmds (write) required for the energy_sites endpoints.
flows:
authorizationCode:
authorizationUrl: https://auth.tesla.com/oauth2/v3/authorize
tokenUrl: https://auth.tesla.com/oauth2/v3/token
scopes:
energy_device_data: Read energy site data
energy_cmds: Send commands to energy sites
offline_access: Refresh tokens
parameters:
SiteId:
name: site_id
in: path
required: true
description: The energy_site_id returned by /products.
schema:
type: string
responses:
Unauthorized:
description: Missing or invalid bearer token.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Forbidden:
description: Token is valid but lacks the required scope (e.g., energy_cmds for writes).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Energy site not found or not accessible by this account.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
RateLimited:
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
CommandResult:
description: Command accepted by the site.
content:
application/json:
schema:
$ref: '#/components/schemas/CommandResult'
schemas:
Error:
type: object
properties:
error:
type: string
error_description:
type: string
CommandResult:
type: object
properties:
response:
type: object
properties:
code:
type: integer
message:
type: string
result:
type: boolean
Product:
type: object
properties:
energy_site_id:
type: integer
format: int64
site_name:
type: string
resource_type:
type: string
enum: [battery, solar]
id:
type: string
asset_site_id:
type: string
gateway_id:
type: string
energy_left:
type: number
total_pack_energy:
type: number
percentage_charged:
type: number
battery_type:
type: string
ProductsResponse:
type: object
properties:
response:
type: array
items:
$ref: '#/components/schemas/Product'
count:
type: integer
SiteComponent:
type: object
properties:
battery:
type: boolean
solar:
type: boolean
solar_type:
type: string
grid:
type: boolean
grid_services:
type: boolean
storm_mode_capable:
type: boolean
backup_time_remaining_enabled:
type: boolean
off_grid_vehicle_charging_reserve_supported:
type: boolean
SiteInfo:
type: object
properties:
id:
type: string
site_name:
type: string
backup_reserve_percent:
type: integer
default_real_mode:
type: string
installation_date:
type: string
format: date-time
installation_time_zone:
type: string
version:
type: string
battery_count:
type: integer
nameplate_power:
type: number
nameplate_energy:
type: number
components:
$ref: '#/components/schemas/SiteComponent'
address:
type: object
properties:
address:
type: string
city:
type: string
state:
type: string
zip:
type: string
country:
type: string
user_settings:
type: object
properties:
storm_mode_enabled:
type: boolean
powerwall_onboarding_settings_set:
type: boolean
sync_grid_alert_enabled:
type: boolean
breaker_alert_enabled:
type: boolean
SiteInfoResponse:
type: object
properties:
response:
$ref: '#/components/schemas/SiteInfo'
LiveStatus:
type: object
properties:
solar_power:
type: number
description: Instantaneous solar generation in watts.
battery_power:
type: number
description: Instantaneous battery power in watts. Positive = discharging.
grid_power:
type: number
description: Instantaneous grid power in watts. Positive = import.
load_power:
type: number
description: Instantaneous home load in watts.
percentage_charged:
type: number
description: Battery state-of-charge as a percent 0-100.
energy_left:
type: number
description: Battery energy remaining in watt-hours.
total_pack_energy:
type: number
description: Total Powerwall pack energy capacity in watt-hours.
grid_status:
type: string
enum: [Active, Inactive, Unknown]
backup_capable:
type: boolean
storm_mode_active:
type: boolean
timestamp:
type: string
format: date-time
LiveStatusResponse:
type: object
properties:
response:
$ref: '#/components/schemas/LiveStatus'
CalendarHistoryBucket:
type: object
properties:
timestamp:
type: string
format: date-time
solar_energy_exported:
type: number
generator_energy_exported:
type: number
grid_energy_imported:
type: number
grid_services_energy_imported:
type: number
grid_services_energy_exported:
type: number
grid_energy_exported_from_solar:
type: number
grid_energy_exported_from_generator:
type: number
grid_energy_exported_from_battery:
type: number
battery_energy_exported:
type: number
battery_energy_imported_from_grid:
type: number
battery_energy_imported_from_solar:
type: number
battery_energy_imported_from_generator:
type: number
consumer_energy_imported_from_grid:
type: number
consumer_energy_imported_from_solar:
type: number
consumer_energy_imported_from_battery:
type: number
consumer_energy_imported_from_generator:
type: number
CalendarHistoryResponse:
type: object
properties:
response:
type: object
properties:
serial_number:
type: string
period:
type: string
installation_time_zone:
type: string
time_series:
type: array
items:
$ref: '#/components/schemas/CalendarHistoryBucket'
TimeOfUseSettings:
type: object
properties:
tou_settings:
type: object
properties:
optimization_strategy:
type: string
enum: [economics, balanced]
schedule:
type: array
items:
type: object
properties:
target:
type: string
enum: [peak, off_peak, partial_peak, super_off_peak]
week_days:
type: array
items:
type: integer
minimum: 0
maximum: 6
start_seconds:
type: integer
end_seconds:
type: integer
Program:
type: object
properties:
name:
type: string
enrolled:
type: boolean
eligibility_status:
type: string
ProgramsResponse:
type: object
properties:
response:
type: array
items:
$ref: '#/components/schemas/Program'