04.01.Tesla API Integration

04.01. Tesla API Integration

Overview

Car Pulse Tracker integrates with the Tesla Fleet API to fetch real vehicle data for report generation. This document covers the complete setup, OAuth flow, partner registration, available API endpoints, and the data fields returned by each endpoint.

Related internal architecture documents:

bnc-cpt-api.TESLA-DATA-ARCHITECTURE.md - source-of-truth Tesla data model, token strategy, current-vs-target fetch architecture
bnc-cpt-api.TESLA-REPORT-FIELD-MAPPING.md - report coverage and null-safe rendering targets
Tesla Developer Portal: https://developer.tesla.com/
Tesla Fleet API Docs: https://developer.tesla.com/docs/fleet-api
Fleet API Region (EU): https://fleet-api.prd.eu.vn.cloud.tesla.com

1. App Registration at developer.tesla.com

1.1 Create Application

Go to https://developer.tesla.com/ and sign in
Create a new application:
App Name: Car Pulser Tracker (as registered)
Description: Vehicle report generation service
Purpose: Third-party app for vehicle health reports

1.2 Credentials Obtained

Credential	GCP Secret ID	Description
Client ID	`bnc-cpt-tesla-client-id`	UUID format
Client Secret	`bnc-cpt-tesla-client-secret`	Stored in GCP Secret Manager

Store in GCP Secret Manager per environment. See bnc-cpt-api.SYG.md for secret mapping.

1.3 Redirect URIs Registered

Environment	Redirect URI
dev	`https://dev.api.carpulsetracker.com/api/v1/tesla/oauth/callback`
tst	`https://tst.api.carpulsetracker.com/api/v1/tesla/oauth/callback`
prd	`https://api.carpulsetracker.com/api/v1/tesla/oauth/callback`

Tesla requires HTTPS for all redirect URIs. No localhost allowed.

1.4 Scopes Configured

Three scopes are registered and approved at developer.tesla.com:

Scope	Description	Used For
`vehicle_device_data`	Read vehicle data	Battery, odometer, charging state, climate, config
`vehicle_charging_cmds`	Charging commands	Charging history, invoices
`vehicle_specs`	Vehicle specifications	VIN-based specs lookup (partner token only)

Full scope string for OAuth requests:

openid offline_access vehicle_device_data vehicle_charging_cmds vehicle_specs

1.5 Public Key Hosting

Tesla requires a public key at a well-known URL for partner verification:

https://{domain}/.well-known/appspecific/com.tesla.3p.public-key.pem

The public key is hosted at:

https://dev.api.carpulsetracker.com/.well-known/appspecific/com.tesla.3p.public-key.pem

This is an EC (secp256r1) public key in PEM format. Generated with:

openssl ecparam -name prime256v1 -genkey -noout -out private-key.pem
openssl ec -in private-key.pem -pubout -out public-key.pem

2. Partner Registration (One-Time Setup)

Partner registration is required before any Fleet API calls work. Without it, API calls return HTTP 412 "Account must be registered in the current region".

2.1 Get Partner Token

Exchange client credentials for a partner-level access token:

curl -s -X POST https://auth.tesla.com/oauth2/v3/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "<TESLA_CLIENT_ID>",
    "client_secret": "<TESLA_CLIENT_SECRET>",
    "scope": "openid vehicle_device_data vehicle_charging_cmds vehicle_specs",
    "audience": "https://fleet-api.prd.eu.vn.cloud.tesla.com"
  }'

Returns:

{
  "access_token": "ey...",
  "token_type": "Bearer",
  "expires_in": 28800
}

2.2 Register Partner Account

Call the partner registration endpoint with the partner token:

curl -s -X POST https://fleet-api.prd.eu.vn.cloud.tesla.com/api/1/partner_accounts \
  -H "Authorization: Bearer <PARTNER_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"domain": "dev.api.carpulsetracker.com"}'

Successful response:

{
  "response": {
    "account_id": "...",
    "domain": "dev.api.carpulsetracker.com",
    "name": "Car Pulser Tracker",
    "description": "...",
    "client_id": "<YOUR_CLIENT_ID>",
    "ca": null,
    "created_at": "2026-02-10T...",
    "updated_at": "2026-02-10T...",
    "enterprise_tier": "free",
    "csr": null,
    "public_key": "-----BEGIN PUBLIC KEY-----\n..."
  }
}

2.3 Shell Action for Partner Registration

Use the do_tesla_register_partner shell action to register in any region:

cd \$APP_PATH/\${ORG}-\${APP}-utl

# Register in NA region (credentials from GCP)
REGION=na DOMAIN=api.carpulsetracker.com ENV=dev ./run -a do_tesla_register_partner

# Register in all regions at once
REGION=all DOMAIN=api.carpulsetracker.com ENV=dev ./run -a do_tesla_register_partner

# With explicit credentials (no GCP lookup)
TESLA_CLIENT_ID=<id> TESLA_CLIENT_SECRET=<secret> \
  REGION=na DOMAIN=api.carpulsetracker.com ./run -a do_tesla_register_partner

2.4 Registration Status

Region	Fleet API URL	Status	Date
EU	`fleet-api.prd.eu.vn.cloud.tesla.com`	Registered	2026-02-10
NA	`fleet-api.prd.na.vn.cloud.tesla.com`	PENDING	—
CN	`fleet-api.prd.cn.vn.cloud.tesla.com`	Not needed yet	—

Enterprise Tier: Free
Note: Registration is per-region. The API code auto-retries all registered regions on HTTP 412 (region mismatch). See tesla_fleet.py:_fleet_api_get_with_token().

3. OAuth Flow (User Authorization)

3.1 Flow Overview

User clicks "Connect Tesla"
    │
    ▼
POST /api/v1/tesla/oauth/initiate
    │ Returns authUrl + state
    ▼
Browser redirects to Tesla login (auth.tesla.com)
    │ User logs in + authorizes scopes
    ▼
Tesla redirects to callback with ?code=XXX&state=YYY
    │
    ▼
GET /api/v1/tesla/oauth/callback
    │ Exchanges code for access_token + refresh_token
    ▼
Access token used for Fleet API calls

3.2 Authorization URL Parameters

https://auth.tesla.com/oauth2/v3/authorize
  ?response_type=code
  &client_id=<CLIENT_ID>
  &redirect_uri=<REDIRECT_URI>
  &scope=openid offline_access vehicle_device_data vehicle_charging_cmds vehicle_specs
  &state=<RANDOM_STATE>

3.3 Token Exchange

POST https://auth.tesla.com/oauth2/v3/token
{
  "grant_type": "authorization_code",
  "client_id": "<CLIENT_ID>",
  "client_secret": "<CLIENT_SECRET>",
  "code": "<AUTH_CODE>",
  "redirect_uri": "<REDIRECT_URI>",
  "audience": "https://fleet-api.prd.eu.vn.cloud.tesla.com"
}

Returns:

{
  "access_token": "ey...",
  "refresh_token": "ey...",
  "id_token": "ey...",
  "token_type": "Bearer",
  "expires_in": 28800
}

3.4 Token Notes

Access tokens expire in 8 hours (28800 seconds)
Use refresh_token with grant_type=refresh_token to get new access tokens
offline_access scope is required for refresh tokens
Tokens are user-scoped (one token per Tesla account)

4. Fleet API Endpoints & Response Fields

4.0 Request / Response Contract Summary

This table is the short contract view for the Tesla endpoints currently relevant to Car Pulse Tracker.

Endpoint	Request Shape	Token / Scope	Response Root	Notes
`GET /api/1/vehicles`	no params	third-party token / `vehicle_device_data`	`response[]` + `pagination`	Vehicle inventory root for the account
`GET /api/1/vehicles/{vin}`	path `vin`	third-party token / `vehicle_device_data`	`response`	Cheap per-vehicle root metadata
`GET /api/1/vehicles/{vin}/vehicle_data`	path `vin`, optional `endpoints` query	third-party token / `vehicle_device_data` (+ `vehicle_location` for location fields)	`response`	Expensive live vehicle state
`GET /api/1/vehicles/{vin}/service_data`	path `vin`	third-party token / `vehicle_device_data`	`response`	Often empty object when no service events
`GET /api/1/dx/charging/history`	query: `startTime`, `endTime`, `pageNo`, `pageSize`, `sortBy`, `sortOrder`, `vin`	third-party token / `vehicle_charging_cmds`	`response.data[]`	Charging-history endpoint with explicit VIN/time/paging filters
`GET /api/1/dx/charging/invoice/{id}`	path `id`	third-party token / `vehicle_charging_cmds`	PDF response body	Invoice file endpoint
`GET /api/1/dx/charging/sessions`	no params documented here	business fleet owner context	session payload	Business-only charging endpoint
`GET /api/1/vehicles/{vin}/recent_alerts`	path `vin`	third-party token / `vehicle_device_data`	`response.recent_alerts[]`	Per-vehicle module
`GET /api/1/dx/warranty/details?vin={vin}`	query `vin`	third-party token / `vehicle_device_data`	provider-specific object	VIN is required
`GET /api/1/vehicles/{vin}/specs`	path `vin`	partner token	`response`	Partner-token only and billed
`GET /api/1/dx/vehicles/options?vin={vin}`	query `vin`	third-party token / `vehicle_device_data`	`codes[]`	VIN-query module
`GET /api/1/vehicles/{vin}/release_notes`	path `vin`	third-party token / `vehicle_device_data`	`response.release_notes[]`	Per-vehicle module

4.1 List Vehicles

GET /api/1/vehicles
Authorization: Bearer <USER_TOKEN>

Response fields:

Field	Type	Example	Description
`id`	int	`99999999999999`	Tesla vehicle ID
`vehicle_id`	int	`99999999999999`	Internal vehicle ID
`vin`	string	`LRWXXXXXXXXXXXXX`	Vehicle Identification Number
`display_name`	string	`"MyTesla"`	User-set vehicle name
`state`	string	`"online"`	Vehicle state (online/asleep/offline)
`access_type`	string	`"OWNER"`	User's access level
`in_service`	bool	`false`	Whether vehicle is in service
`color`	string/null	`null`	Vehicle color
`option_codes`	string/null	`null`	Option codes
`granular_access.hide_private`	bool	`false`	Privacy setting
`calendar_enabled`	bool	`true`	Calendar sync enabled
`api_version`	int	`90`	API version supported
`ble_autopair_enrolled`	bool	`false`	BLE auto-pairing

Pagination:

"pagination": {
  "previous": null,
  "next": null,
  "current": 1,
  "per_page": 2,
  "count": 2,
  "pages": 1
}

4.2 Vehicle Root Metadata

GET /api/1/vehicles/{vin}
Authorization: Bearer <USER_TOKEN>

This is the cheap per-vehicle root metadata endpoint and should be treated as the base vehicle object before live-state enrichment.

Scope:

vehicle_device_data

Pricing:

not charged

Path parameter:

Parameter	Location	Description
`vin`	path	Vehicle Identification Number (VIN) of the selected vehicle

Documented request examples:

curl -H "Authorization: Bearer $TESLA_AUTH_TOKEN" \
  -i https://fleet-api.prd.na.vn.cloud.tesla.com/api/1/vehicles/{vin}

import os
import http.client

conn = http.client.HTTPSConnection("fleet-api.prd.na.vn.cloud.tesla.com")

headers = {
   'Authorization': f"Bearer {os.environ['TESLA_AUTH_TOKEN']}"
}
conn.request("GET", "/api/1/vehicles/{vin}", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

const BASE_URL = 'https://fleet-api.prd.na.vn.cloud.tesla.com';
const vin = 'VIN00000000000001'

const options = {
    method: 'GET',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${process.env.TESLA_AUTH_TOKEN}`
    }
};

fetch(`${BASE_URL}/api/1/vehicles/${vin}`, options)
    .then(res => res.json())
    .then(res => console.log(res))
    .catch(err => console.log('error', err));

Documented response root:

{
  "response": {}
}

Key response fields:

Field	Type	Example	Description
`id`	int	`100021`	Tesla vehicle ID
`vehicle_id`	int	`99999`	Internal vehicle ID
`vin`	string	`TEST00000000VIN01`	VIN
`display_name`	string	`"Owned"`	User-set vehicle name
`access_type`	string	`"OWNER"`	Account access level
`state`	string	`"online"`	Account-visible state
`in_service`	bool	`false`	Service flag
`option_codes`	string	`"TEST0,COUS"`	Tesla option-code string
`granular_access.hide_private`	bool	`false`	Privacy flag
`calendar_enabled`	bool	`true`	Calendar sync enabled

4.3 Vehicle Data (Primary Endpoint)

GET /api/1/vehicles/{vin}/vehicle_data
Authorization: Bearer <USER_TOKEN>

This is the richest endpoint. Returns nested objects:

Documented request examples:

curl -H "Authorization: Bearer $TESLA_AUTH_TOKEN" \
  -i https://fleet-api.prd.na.vn.cloud.tesla.com/api/1/vehicles/{vin}/vehicle_data

import os
import http.client

conn = http.client.HTTPSConnection("fleet-api.prd.na.vn.cloud.tesla.com")

headers = {
   'Authorization': f"Bearer {os.environ['TESLA_AUTH_TOKEN']}"
}
conn.request("GET", "/api/1/vehicles/{vin}/vehicle_data", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Documented response root:

{
  "response": {}
}

4.3.1 charge_state

Field	Type	Example	Description
`battery_level`	int	`74`	Battery percentage (0-100)
`usable_battery_level`	int	`73`	Usable battery %
`battery_range`	float	`243.31`	EPA rated range in miles
`ideal_battery_range`	float	`243.31`	Ideal range in miles
`est_battery_range`	float	`242.74`	Estimated range in miles
`charging_state`	string	`"Disconnected"`	Disconnected/Charging/Complete/Stopped
`charge_limit_soc`	int	`83`	Charge limit set by user (%)
`charge_limit_soc_max`	int	`100`	Max charge limit
`charge_limit_soc_min`	int	`50`	Min charge limit
`charge_limit_soc_std`	int	`80`	Standard (daily) charge limit
`charge_energy_added`	float	`17.74`	kWh added in last charge
`charge_miles_added_rated`	float	`78.5`	Miles added (rated)
`charge_miles_added_ideal`	float	`78.5`	Miles added (ideal)
`charge_rate`	float	`0.0`	Current charge rate (mi/hr)
`charge_amps`	int	`16`	Charge current (amps)
`charge_current_request`	int	`16`	Requested charge current
`charge_current_request_max`	int	`16`	Max requestable current
`charger_actual_current`	int	`0`	Actual charger current
`charger_voltage`	int	`2`	Charger voltage
`charger_power`	int	`0`	Charger power (kW)
`charger_pilot_current`	int	`16`	Pilot signal current
`charger_phases`	int/null	`null`	Number of phases
`charge_port_door_open`	bool	`false`	Charge port open
`charge_port_latch`	string	`"Engaged"`	Latch status
`charge_port_color`	string	`"Off"`	Charge port LED color
`charge_port_cold_weather_mode`	bool	`false`	Cold weather mode
`conn_charge_cable`	string	`"<invalid>"`	Connected cable type
`fast_charger_present`	bool	`false`	Supercharger connected
`fast_charger_brand`	string	`"<invalid>"`	Fast charger brand
`fast_charger_type`	string	`"<invalid>"`	Fast charger type
`battery_heater_on`	bool	`false`	Battery heater active
`charge_enable_request`	bool	`true`	Charging enabled
`minutes_to_full_charge`	int	`0`	Minutes to full
`time_to_full_charge`	float	`0.0`	Hours to full
`max_range_charge_counter`	int	`0`	Max range charge count
`off_peak_charging_enabled`	bool	`false`	Off-peak charging
`off_peak_charging_times`	string	`"all_week"`	Off-peak schedule
`preconditioning_enabled`	bool	`true`	Departure preconditioning
`preconditioning_times`	string	`"weekdays"`	Preconditioning schedule
`scheduled_charging_mode`	string	`"Off"`	Scheduled charging mode
`scheduled_charging_pending`	bool	`false`	Scheduled charge pending
`scheduled_departure_time`	int	`1770787800`	Unix timestamp
`scheduled_departure_time_minutes`	int	`450`	Minutes from midnight
`supercharger_session_trip_planner`	bool	`false`	Trip planner active
`trip_charging`	bool	`false`	Trip charging mode
`timestamp`	int	`1700000000000`	Unix timestamp (ms)

4.3.2 climate_state

Field	Type	Example	Description
`inside_temp`	float	`4.5`	Interior temp (C)
`outside_temp`	float	`-6.5`	Exterior temp (C)
`driver_temp_setting`	float	`21.5`	Driver temp setting (C)
`passenger_temp_setting`	float	`21.5`	Passenger temp setting (C)
`is_climate_on`	bool	`false`	Climate system active
`is_auto_conditioning_on`	bool	`false`	Auto conditioning
`is_preconditioning`	bool	`false`	Preconditioning active
`is_front_defroster_on`	bool	`false`	Front defroster
`is_rear_defroster_on`	bool	`false`	Rear defroster
`fan_status`	int	`0`	Fan speed (0=off)
`hvac_auto_request`	string	`"On"`	HVAC auto mode
`min_avail_temp`	float	`15.0`	Min settable temp
`max_avail_temp`	float	`28.0`	Max settable temp
`cabin_overheat_protection`	string	`"On"`	COP status
`cabin_overheat_protection_actively_cooling`	bool	`false`	COP active
`cop_activation_temperature`	string	`"High"`	COP threshold
`allow_cabin_overheat_protection`	bool	`true`	COP allowed
`climate_keeper_mode`	string	`"off"`	Keep climate mode
`defrost_mode`	int	`0`	Defrost mode
`battery_heater`	bool	`false`	Battery heater
`steering_wheel_heater`	bool	`false`	Steering wheel heater
`steering_wheel_heat_level`	int	`0`	Steering heat level
`seat_heater_left`	int	`0`	Driver seat heater (0-3)
`seat_heater_right`	int	`0`	Passenger seat heater
`seat_heater_rear_left`	int	`0`	Rear left seat heater
`seat_heater_rear_right`	int	`0`	Rear right seat heater
`seat_fan_front_left`	int	`0`	Driver seat fan (cooling)
`seat_fan_front_right`	int	`0`	Passenger seat fan
`side_mirror_heaters`	bool	`false`	Side mirror heaters
`wiper_blade_heater`	bool	`false`	Wiper blade heater
`remote_heater_control_enabled`	bool	`false`	Remote heater
`auto_seat_climate_left`	bool	`false`	Auto seat climate
`auto_seat_climate_right`	bool	`false`	Auto seat climate
`auto_steering_wheel_heat`	bool	`false`	Auto steering heat
`supports_fan_only_cabin_overheat_protection`	bool	`true`	Fan-only COP

4.3.3 vehicle_state

Field	Type	Example	Description
`odometer`	float	`12345.678901`	Odometer reading in miles
`car_version`	string	`"2026.2.3"`	Software version
`vehicle_name`	string	`"MyTesla"`	User-set name
`locked`	bool	`true`	Vehicle locked
`sentry_mode`	bool	`true`	Sentry mode active
`sentry_mode_available`	bool	`true`	Sentry available
`dashcam_state`	string	`"Recording"`	Dashcam status
`dashcam_clip_save_available`	bool	`true`	Dashcam save available
`is_user_present`	bool	`false`	User in vehicle
`valet_mode`	bool	`false`	Valet mode
`valet_pin_needed`	bool	`true`	Valet PIN required
`center_display_state`	int	`0`	Display state (0=off)
`df`	int	`0`	Driver front door (0=closed)
`dr`	int	`0`	Driver rear door
`pf`	int	`0`	Passenger front door
`pr`	int	`0`	Passenger rear door
`ft`	int	`0`	Front trunk (0=closed)
`rt`	int	`0`	Rear trunk
`fd_window`	int	`0`	Front driver window
`fp_window`	int	`0`	Front passenger window
`rd_window`	int	`0`	Rear driver window
`rp_window`	int	`0`	Rear passenger window
`remote_start`	bool	`false`	Remote start active
`remote_start_enabled`	bool	`true`	Remote start allowed
`remote_start_supported`	bool	`true`	Remote start supported
`api_version`	int	`90`	API version
`autopark_state_v2`	string	`"unavailable"`	Autopark state
`calendar_supported`	bool	`true`	Calendar support
`notifications_supported`	bool	`true`	Notifications support
`parsed_calendar_supported`	bool	`true`	Calendar parsing
`service_mode`	bool	`false`	Service mode
`service_mode_plus`	bool	`false`	Service mode plus
`santa_mode`	int	`0`	Santa mode
`webcam_available`	bool	`true`	Webcam available
`feature_bitmask`	string	`"fbdffbff,..."`	Feature flags
`vehicle_self_test_progress`	int	`0`	Self-test progress
`vehicle_self_test_requested`	bool	`false`	Self-test requested

Tire Pressure (TPMS):

Field	Type	Example	Description
`tpms_pressure_fl`	float	`2.75`	Front left pressure (bar)
`tpms_pressure_fr`	float	`2.65`	Front right pressure (bar)
`tpms_pressure_rl`	float	`2.725`	Rear left pressure (bar)
`tpms_pressure_rr`	float	`2.675`	Rear right pressure (bar)
`tpms_rcp_front_value`	float	`2.9`	Recommended front (bar)
`tpms_rcp_rear_value`	float	`2.9`	Recommended rear (bar)
`tpms_soft_warning_fl`	bool	`false`	Soft warning front left
`tpms_soft_warning_fr`	bool	`true`	Soft warning front right
`tpms_soft_warning_rl`	bool	`true`	Soft warning rear left
`tpms_soft_warning_rr`	bool	`true`	Soft warning rear right
`tpms_hard_warning_fl`	bool	`false`	Hard warning front left
`tpms_hard_warning_fr`	bool	`false`	Hard warning front right
`tpms_hard_warning_rl`	bool	`false`	Hard warning rear left
`tpms_hard_warning_rr`	bool	`false`	Hard warning rear right
`tpms_last_seen_pressure_time_fl`	int	`1700000000`	Last reading time
`tpms_last_seen_pressure_time_fr`	int	`1700000000`	Last reading time
`tpms_last_seen_pressure_time_rl`	int	`1700000000`	Last reading time
`tpms_last_seen_pressure_time_rr`	int	`1700000000`	Last reading time

Software Update:

Field	Type	Example	Description
`software_update.download_perc`	int	`0`	Download progress %
`software_update.install_perc`	int	`1`	Install progress %
`software_update.expected_duration_sec`	int	`2700`	Expected duration
`software_update.status`	string	`""`	Update status
`software_update.version`	string	`" "`	Pending version

Speed Limit Mode:

Field	Type	Example	Description
`speed_limit_mode.active`	bool	`false`	Speed limit active
`speed_limit_mode.current_limit_mph`	float	`85.0`	Current limit
`speed_limit_mode.max_limit_mph`	float	`120.0`	Max settable limit
`speed_limit_mode.min_limit_mph`	float	`50.0`	Min settable limit
`speed_limit_mode.pin_code_set`	bool	`false`	PIN code set

Media Info:

Field	Type	Example	Description
`media_info.audio_volume`	float	`2.0`	Volume level
`media_info.audio_volume_max`	float	`10.333`	Max volume
`media_info.media_playback_status`	string	`"Playing"`	Playback status
`media_info.now_playing_artist`	string	`""`	Current artist
`media_info.now_playing_title`	string	`"Hit Music Only!"`	Current title
`media_info.now_playing_station`	string	`"FM NRJ"`	Radio station
`media_info.now_playing_source`	string	`"13"`	Media source
`media_info.a2dp_source_name`	string	`"iPhone (User)"`	Bluetooth source

4.3.4 drive_state

Field	Type	Example	Description
`active_route_latitude`	float	`37.7765494`	Active route latitude
`active_route_longitude`	float	`-122.4195418`	Active route longitude
`active_route_traffic_minutes_delay`	int	`0`	Traffic delay in minutes
`gps_as_of`	int	`1692137422`	GPS timestamp
`heading`	int	`289`	Vehicle heading
`latitude`	float	`37.7765494`	Latitude
`longitude`	float	`-122.4195418`	Longitude
`native_latitude`	float	`37.7765494`	Native latitude
`native_longitude`	float	`-122.4195418`	Native longitude
`native_location_supported`	int	`1`	Native location support
`native_type`	string	`"wgs"`	Native coordinate type
`power`	int	`1`	Power usage / regen state
`shift_state`	string/null	`null`	Shift state
`speed`	number/null	`null`	Speed
`timestamp`	int	`1692141038420`	Timestamp (ms)

4.3.5 gui_settings

Field	Type	Example	Description
`gui_24_hour_time`	bool	`true`	24-hour time format
`gui_charge_rate_units`	string	`"kW"`	Charge rate display
`gui_distance_units`	string	`"km/hr"`	Distance display
`gui_range_display`	string	`"Rated"`	Range display mode
`gui_temperature_units`	string	`"C"`	Temperature display
`gui_tirepressure_units`	string	`"Bar"`	Tire pressure display
`show_range_units`	bool	`false`	Show range units

4.3.6 vehicle_config

Field	Type	Example	Description
`car_type`	string	`"model3"`	Car model
`car_special_type`	string	`"base"`	Special type
`trim_badging`	string	`"74d"`	Trim badge
`exterior_color`	string	`"DeepBlue"`	Paint color
`exterior_trim`	string	`"Black"`	Exterior trim
`interior_trim_type`	string	`"Black2"`	Interior trim
`roof_color`	string	`"RoofColorGlass"`	Roof type
`wheel_type`	string	`"Glider18"`	Wheel type
`charge_port_type`	string	`"CCS"`	Charge port type
`driver_assist`	string	`"TeslaAP4"`	Driver assist package
`efficiency_package`	string	`"M3POPPYSEED2024"`	Efficiency package
`performance_package`	string	`"Base"`	Performance package
`rear_drive_unit`	string	`"PM216MOSFET"`	Rear motor type
`eu_vehicle`	bool	`true`	EU market vehicle
`ece_restrictions`	bool	`true`	ECE regulations
`rhd`	bool	`false`	Right-hand drive
`plg`	bool	`true`	Power liftgate
`pws`	bool	`true`	Pedestrian warning
`has_air_suspension`	bool	`false`	Air suspension
`has_ludicrous_mode`	bool	`false`	Ludicrous mode
`has_seat_cooling`	bool	`true`	Seat cooling
`rear_seat_heaters`	int	`1`	Rear seat heaters
`rear_seat_type`	int	`0`	Rear seat type
`third_row_seats`	string	`"None"`	Third row seats
`spoiler_type`	string	`"None"`	Spoiler type
`headlamp_type`	string	`"Global"`	Headlamp type
`sun_roof_installed`	null	`null`	Sunroof
`can_accept_navigation_requests`	bool	`true`	Nav requests
`can_actuate_trunks`	bool	`true`	Trunk actuation
`motorized_charge_port`	bool	`true`	Motorized charge port
`dashcam_clip_save_supported`	bool	`true`	Dashcam save
`default_charge_to_max`	bool	`false`	Default max charge
`webcam_supported`	bool	`true`	Webcam support
`webcam_selfie_supported`	bool	`true`	Selfie camera
`sentry_preview_supported`	bool	`false`	Sentry preview
`supports_qr_pairing`	bool	`false`	QR pairing
`use_range_badging`	bool	`true`	Range badging
`badge_version`	int	`1`	Badge version
`key_version`	int	`2`	Key version
`utc_offset`	int	`7200`	UTC offset (sec)

4.3.7 Top-level vehicle_data fields

Field	Type	Example	Description
`supercharger_payment_needed`	string	`"false"`	Payment needed
`supercharging_enabled`	bool	`true`	Supercharging enabled

4.4 Service Data

GET /api/1/vehicles/{vin}/service_data
Authorization: Bearer <USER_TOKEN>

Scope:

vehicle_device_data

Pricing:

not charged

Path parameter:

Parameter	Location	Description
`vin`	path	VIN of the selected vehicle

Documented request example:

curl -H "Authorization: Bearer $TESLA_AUTH_TOKEN" \
  -i https://fleet-api.prd.na.vn.cloud.tesla.com/api/1/vehicles/{vin}/service_data

Documented non-empty response shape:

{
  "response": {
    "service_status": "car_in_repair",
    "service_etc": "2023-05-02T17:10:53-10:00",
    "service_visit_number": "SV12345678",
    "status_id": 8
  }
}

Known response fields:

Field	Type	Description
`response.service_status`	string	Service status
`response.service_etc`	string	Estimated completion timestamp
`response.service_visit_number`	string	Service visit number
`response.status_id`	int	Tesla status identifier

Observed empty response shape in practice:

{
  "response": {}
}

So this endpoint must be treated as nullable/sparse even when the request succeeds.

4.5 Charging History

GET /api/1/dx/charging/history
Authorization: Bearer <USER_TOKEN>

Scope:

vehicle_charging_cmds

Pricing:

not charged

Documented query parameters:

Parameter	Location	Description
`startTime`	query	Start time of the window to download charging history for
`endTime`	query	End time of the window to download charging history for
`pageNo`	query	Current page number
`pageSize`	query	Number of records per page
`sortBy`	query	Field to sort by
`sortOrder`	query	Sort order (`ASC` or `DESC`)
`vin`	query	Vehicle Identification Number of the selected vehicle

Documented request example:

curl -H "Authorization: Bearer $TESLA_AUTH_TOKEN" \
  -i https://fleet-api.prd.na.vn.cloud.tesla.com/api/1/dx/charging/history

Documented response root:

{
  "response": {
    "data": []
  }
}

This endpoint returns charging session history as response.data[]. Each session includes its own vin, so charging attribution must still be solved by normalizing and partitioning sessions by VIN after fetch.

Returns array of charging sessions under response.data[]:

Field	Type	Example	Description
`sessionId`	int	`999999999`	Charging session ID
`vin`	string	`"XP7XXXXXXXXXXXXX"`	Vehicle VIN
`siteLocationName`	string	`"Helsinki, Finland"`	Supercharger location
`chargeStartDateTime`	string	`"2026-01-15T10:00:00+02:00"`	Charge start (ISO 8601)
`chargeStopDateTime`	string	`"2026-01-15T10:30:00+02:00"`	Charge stop (ISO 8601)
`unlatchDateTime`	string	`"2026-01-15T10:30:05+02:00"`	Cable unlatch time
`countryCode`	string	`"FI"`	Country
`billingType`	string	`"IMMEDIATE"`	Billing type
`vehicleMakeType`	string	`"TSLA"`	Vehicle make

Fees (nested array fees[]):

Field	Type	Example	Description
`sessionFeeId`	int	`999999999`	Fee ID
`feeType`	string	`"CHARGING"` or `"CONGESTION"`	Fee type
`currencyCode`	string	`"EUR"`	Currency
`pricingType`	string	`"PAYMENT"` or `"NO_CHARGE"`	Pricing type
`rateBase`	float	`0.39`	Rate per unit (EUR/kWh)
`usageBase`	float	`32.5`	Energy used (kWh)
`totalDue`	float	`12.50`	Total due (EUR)
`netDue`	float	`9.96`	Net amount (excl. VAT)
`uom`	string	`"kwh"` or `"min"`	Unit of measure
`isPaid`	bool	`true`	Payment status
`status`	string	`"PAID"`	Payment status

Invoices (nested array invoices[]):

Field	Type	Example	Description
`fileName`	string	`"XXXXXXXXX_FI-FI.pdf"`	Invoice filename
`contentId`	string	`"<UUID>"`	Invoice content UUID
`invoiceType`	string	`"IMMEDIATE"`	Invoice type

Documented response example:

{
  "response": {
    "data": [
      {
        "sessionId": 1234567,
        "vin": "TEST00000000VIN01",
        "siteLocationName": "Truckee, CA - Soaring Way",
        "chargeStartDateTime": "2023-07-27T11:43:45-07:00",
        "chargeStopDateTime": "2023-07-27T12:08:35-07:00",
        "unlatchDateTime": "2023-07-27T12:25:31-07:00",
        "countryCode": "US",
        "fees": [
          {
            "sessionFeeId": 7654321,
            "feeType": "CHARGING",
            "currencyCode": "USD",
            "pricingType": "PAYMENT",
            "rateBase": 0.46,
            "usageBase": 40,
            "usageTier2": 24,
            "totalBase": 18.4,
            "totalDue": 18.4,
            "netDue": 18.4,
            "uom": "kwh",
            "isPaid": true,
            "status": "PAID"
          },
          {
            "sessionFeeId": 87654321,
            "feeType": "PARKING",
            "currencyCode": "USD",
            "pricingType": "NO_CHARGE",
            "rateBase": 0,
            "usageBase": 0,
            "totalBase": 0,
            "totalDue": 0,
            "netDue": 0,
            "uom": "min",
            "isPaid": true,
            "status": "PAID"
          }
        ],
        "billingType": "IMMEDIATE",
        "invoices": [
          {
            "fileName": "ABC-123NN-US.pdf",
            "contentId": "abc-123-efg",
            "invoiceType": "IMMEDIATE"
          }
        ],
        "vehicleMakeType": "TSLA"
      }
    ]
  }
}

4.5.1 Charging Invoice

GET /api/1/dx/charging/invoice/{id}
Authorization: Bearer <USER_TOKEN>

Scope:

vehicle_charging_cmds

Pricing:

not charged

Path parameter:

Parameter	Location	Description
`id`	path	Content ID from `charging_history.response.data[].invoices[].contentId`

Documented request example:

curl -H "Authorization: Bearer $TESLA_AUTH_TOKEN" \
  -i https://fleet-api.prd.na.vn.cloud.tesla.com/api/1/dx/charging/invoice/{id}

Documented response:

{
  "response": "raw .pdf document"
}

Practical contract:

request path parameter: invoice identifier
response body: PDF bytes
content type: expected application/pdf

The Tesla docs explicitly state that {id} is the Content ID obtained from:

charging_history.response.data[].invoices[].contentId

4.5.2 Charging Sessions (Business Fleet Only)

GET /api/1/dx/charging/sessions
Authorization: Bearer <BUSINESS_FLEET_TOKEN>

This endpoint is only available for business accounts that own a fleet of vehicles.

Scope:

no scopes required

Pricing:

not charged

Documented query parameters:

Parameter	Location	Description
`date_from`	query	Start date of the window to download charging sessions
`date_to`	query	End date of the window to download charging sessions
`limit`	query	Number of entities returned
`offset`	query	Offset
`vin`	query	VIN of the selected vehicle

Documented request example:

curl -H "Authorization: Bearer $TESLA_AUTH_TOKEN" \
  -i https://fleet-api.prd.na.vn.cloud.tesla.com/api/1/dx/charging/sessions

Documented response root:

{
  "response": {
    "data": []
  }
}

Documented response fields in response.data[] include:

Field	Type	Description
`id`	string	Charging session identifier
`vin`	string	VIN
`model`	string	Vehicle model
`start_date_time`	string	Session start
`stop_date_time`	string	Session stop
`total_energy`	number	Total energy
`total_time`	number	Total time
`total_cost.excl_vat`	number	Cost excluding VAT
`total_cost.incl_vat`	number	Cost including VAT
`total_cost.vat`	number	VAT amount
`location.country`	string	Country
`location.name`	string	Charging location
`charging_periods[]`	array	Charging period breakdown
`charging_periods[].dimensions[]`	array	Dimension rows such as `ENERGY`
`tariffs.currency`	string	Currency
`tariffs.elements[]`	array	Tariff elements
`tariffs.elements[].price_components[]`	array	Price components

Tesla documents this as a future fleet/business charging endpoint, not part of the current person-account report flow.

4.6 Recent Alerts

GET /api/1/vehicles/{vin}/recent_alerts
Authorization: Bearer <USER_TOKEN>

Scope:

vehicle_device_data

Pricing:

not charged

Path parameter:

Parameter	Location	Description
`vin`	path	Vehicle Identification Number (VIN) of the selected vehicle

Documented request examples:

curl -H "Authorization: Bearer $TESLA_AUTH_TOKEN" \
  -i https://fleet-api.prd.na.vn.cloud.tesla.com/api/1/vehicles/{vin}/recent_alerts

const BASE_URL = 'https://fleet-api.prd.na.vn.cloud.tesla.com';
const vin = 'VIN00000000000001'

const options = {
    method: 'GET',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${process.env.TESLA_AUTH_TOKEN}`
    }
};

fetch(`${BASE_URL}/api/1/vehicles/${vin}/recent_alerts`, options)
    .then(res => res.json())
    .then(res => console.log(res))
    .catch(err => console.log('error', err));

import os
import http.client

conn = http.client.HTTPSConnection("fleet-api.prd.na.vn.cloud.tesla.com")

headers = {
   'Authorization': f"Bearer {os.environ['TESLA_AUTH_TOKEN']}"
}
conn.request("GET", "/api/1/vehicles/{vin}/recent_alerts", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Documented response root:

{
  "response": {
    "recent_alerts": []
  }
}

Returns response.recent_alerts[]:

Field	Type	Example	Description
`name`	string	`"UI_a212_AEBSFaulted"`	Alert code
`time`	string	`"2021-03-19T22:01:15.101+00:00"`	Alert time
`audience`	array	`["service-fix", "customer"]`	Alert audiences
`user_text`	string	`"Automatic Emergency Braking is unavailable"`	Human-readable text

4.7 Warranty Details

GET /api/1/dx/warranty/details?vin=<VIN>
Authorization: Bearer <USER_TOKEN>

Scope:

vehicle_device_data

Pricing:

not charged

Query parameter:

Parameter	Location	Description
`vin`	query	VIN of the selected vehicle

Documented request example:

curl -H "Authorization: Bearer $TESLA_AUTH_TOKEN" \
  -i https://fleet-api.prd.na.vn.cloud.tesla.com/api/1/dx/warranty/details

Documented response:

{
  "response": {
    "activeWarranty": [
      {
        "warrantyType": "NEW_MFG_WARRANTY",
        "warrantyDisplayName": "Basic Vehicle Limited Warranty",
        "expirationDate": "2025-10-21T00:00:00Z",
        "expirationOdometer": 50000,
        "odometerUnit": "MI",
        "warrantyExpiredOn": null,
        "coverageAgeInYears": 4
      }
    ],
    "upcomingWarranty": [],
    "expiredWarranty": []
  }
}

Known response fields:

Field	Type	Description
`response.activeWarranty[]`	array	Active warranties
`response.upcomingWarranty[]`	array	Upcoming warranties
`response.expiredWarranty[]`	array	Expired warranties
`activeWarranty[].warrantyType`	string	Warranty type
`activeWarranty[].warrantyDisplayName`	string	Human-readable warranty name
`activeWarranty[].expirationDate`	string	Expiration date
`activeWarranty[].expirationOdometer`	number	Expiration odometer
`activeWarranty[].odometerUnit`	string	Odometer unit
`activeWarranty[].warrantyExpiredOn`	string/null	Warranty expired date
`activeWarranty[].coverageAgeInYears`	number	Coverage age

Operational note:

VIN is required even though some short examples omit it from the request URL
calling without VIN has previously produced validation/server errors in practice

Known useful response fields in practice:

activeWarranty[]
upcomingWarranty[]
expiredWarranty[]

Each item commonly contains:

warrantyType
warrantyDisplayName
expirationDate
expirationOdometer
odometerUnit
coverageAgeInYears

4.8 Vehicle Specs (Partner Token Required)

GET /api/1/vehicles/{vin}/specs
Authorization: Bearer <PARTNER_TOKEN>

Scope:

vehicle_specs

Pricing category:

vehicle_specs

This endpoint has special pricing: $0.10 per successful result.

This endpoint can only be accessed with Partner Tokens and can be used for any vehicle without owner authorization.

Path parameter:

Parameter	Location	Description
`vin`	path	VIN of the selected vehicle

Documented request example:

curl -H "Authorization: Bearer $TESLA_AUTH_TOKEN" \
  -i https://fleet-api.prd.na.vn.cloud.tesla.com/api/1/vehicles/{vin}/specs

Documented response root:

{
  "response": {}
}

Documented response example:

{
  "response": {
    "vin": "TEST00000000VIN01",
    "batterySoH": "100%",
    "batteryCapacityKwh": "82.3kWh",
    "batterySoHTimestamp": "2024-01-28T00:00:00Z",
    "make": "Tesla",
    "model": "m3",
    "modelYear": 2025,
    "bodyType": "Sedan, Fastback",
    "equipmentPrice": [
      {
        "code": "$APBS",
        "name": "Autopilot",
        "price": 0
      }
    ],
    "trim": "Model 3 Performance Dual Motor All-Wheel Drive",
    "typeOfDrive": "AWD",
    "numberOfSeats": 5,
    "numberOfDoors": 5,
    "paintCode": "Stealth Grey Paint",
    "interiorCode": "Black and White Premium Interior",
    "thirdRowSeatsCode": null,
    "decorCode": null,
    "wheelsCode": "20’’ Warp Wheels",
    "rearSeatsName": null,
    "seatsName": null,
    "towingCode": null,
    "totalPrice": 60990,
    "vehicleType": "Passenger",
    "fuelType": "Electric",
    "transmissionType": "Automatic",
    "numberOfGears": 1,
    "autopilotHardwareCode": null,
    "autopilotSoftwareCode": "Base Autopilot Package",
    "countryOfOrigin": "DE",
    "productionDate": "2025-07-18T02:50:26Z",
    "maxPowerInKw": "158 kW (front); 303 kW (rear)",
    "batteryRangeInKm": "571 km"
  }
}

Known useful response fields:

Field	Type	Description
`response.vin`	string	VIN
`response.batterySoH`	string	Battery state of health
`response.batteryCapacityKwh`	string	Battery capacity
`response.batterySoHTimestamp`	string	SoH timestamp
`response.make`	string	Make
`response.model`	string	Model
`response.modelYear`	int	Model year
`response.bodyType`	string	Body type
`response.equipmentPrice[]`	array	Equipment/price rows
`response.equipmentPrice[].code`	string	Equipment code
`response.equipmentPrice[].name`	string	Equipment name
`response.equipmentPrice[].price`	number	Equipment price
`response.trim`	string	Trim
`response.typeOfDrive`	string	Drive type
`response.numberOfSeats`	int	Seat count
`response.numberOfDoors`	int	Door count
`response.paintCode`	string	Paint
`response.interiorCode`	string	Interior
`response.wheelsCode`	string	Wheels
`response.totalPrice`	number	Total vehicle price
`response.vehicleType`	string	Vehicle type
`response.fuelType`	string	Fuel type
`response.transmissionType`	string	Transmission type
`response.numberOfGears`	int	Number of gears
`response.autopilotSoftwareCode`	string	Autopilot software package
`response.countryOfOrigin`	string	Country of origin
`response.productionDate`	string	Production date
`response.maxPowerInKw`	string	Max power
`response.batteryRangeInKm`	string	Battery range

Known issue in current app flow: returns HTTP 403 with user OAuth token. This is expected because the endpoint requires a partner token, not a user token.

4.9 Vehicle Options

GET /api/1/dx/vehicles/options?vin=<VIN>
Authorization: Bearer <USER_TOKEN>

Scope:

vehicle_device_data

Pricing:

not charged

Query parameter:

Parameter	Location	Description
`vin`	query	VIN

Documented request examples:

curl -H "Authorization: Bearer $TESLA_AUTH_TOKEN" \
  -i https://fleet-api.prd.na.vn.cloud.tesla.com/api/1/dx/vehicles/options?vin={vin}

import os
import http.client

conn = http.client.HTTPSConnection("fleet-api.prd.na.vn.cloud.tesla.com")

headers = {
   'Authorization': f"Bearer {os.environ['TESLA_AUTH_TOKEN']}"
}
conn.request("GET", "/api/1/dx/vehicles/options?vin={vin}", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Documented response root:

{
  "response": {
    "codes": []
  }
}

Returns response.codes[]:

Field	Type	Example	Description
`code`	string	`"$APBS"`	Option code
`displayName`	string	`"Autopilot"`	Human-readable name
`isActive`	bool	`true`	Option active
`colorCode`	string/null	`"PPSB"`	Color code (for paint)

Example options returned: - $APBS - Autopilot - $IPB3 - Black (interior) - $PPSB - Deep Blue Metallic (paint) - $W38A - 18'' Photon Wheels - $MT352 - Premium Long Range All-Wheel Drive - $SC04 - Supercharger Network Access + Pay-as-you-go

Documented response example:

{
  "response": {
    "codes": [
      {
        "code": "$MT315",
        "displayName": "Long Range All-Wheel Drive",
        "isActive": true
      },
      {
        "code": "$PPSW",
        "colorCode": "PPSW",
        "displayName": "Pearl White Multi-Coat",
        "isActive": true
      },
      {
        "code": "$W40B",
        "displayName": "18’’ Aero Wheels",
        "isActive": true
      },
      {
        "code": "$IPB0",
        "displayName": "All Black Premium Interior",
        "isActive": true
      },
      {
        "code": "$APBS",
        "displayName": "Basic Autopilot",
        "isActive": true
      },
      {
        "code": "$APF2",
        "displayName": "Full Self-Driving Capability",
        "isActive": true
      },
      {
        "code": "$SC04",
        "displayName": "Supercharger Network Access + Pay-as-you-go",
        "isActive": true
      }
    ]
  }
}

4.10 Release Notes

GET /api/1/vehicles/{vin}/release_notes
Authorization: Bearer <USER_TOKEN>

Scope:

vehicle_device_data

Pricing:

not charged

Parameters:

Parameter	Location	Description
`vin`	path	Vehicle Identification Number (VIN) of the selected vehicle
`language`	query	Language locale
`staged`	query	Returns upcoming software update release notes when set to `true`

Documented request examples:

curl -H "Authorization: Bearer $TESLA_AUTH_TOKEN" \
  -i https://fleet-api.prd.na.vn.cloud.tesla.com/api/1/vehicles/{vin}/release_notes

const BASE_URL = 'https://fleet-api.prd.na.vn.cloud.tesla.com';
const vin = 'VIN00000000000001'

const options = {
    method: 'GET',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${process.env.TESLA_AUTH_TOKEN}`
    }
};

fetch(`${BASE_URL}/api/1/vehicles/${vin}/release_notes`, options)
    .then(res => res.json())
    .then(res => console.log(res))
    .catch(err => console.log('error', err));

import os
import http.client

conn = http.client.HTTPSConnection("fleet-api.prd.na.vn.cloud.tesla.com")

headers = {
   'Authorization': f"Bearer {os.environ['TESLA_AUTH_TOKEN']}"
}
conn.request("GET", "/api/1/vehicles/{vin}/release_notes", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Documented response example:

{
  "response": {
    "response": {
      "release_notes": [
        {
          "title": "Minor Fixes",
          "subtitle": "Some more info",
          "description": "This release contains minor fixes and improvements",
          "customer_version": "2022.42.0",
          "icon": "release_notes_icon",
          "image_url": "https://vehicle-files.teslamotors.com/release_notes/d0fa3e08a458696e6464a46c938ffc0a",
          "light_image_url": "https://vehicle-files.teslamotors.com/release_notes/9a122cff8916fffcb61cfd65a15c276f"
        }
      ]
    }
  }
}

Tesla documentation example currently shows a nested response.response.release_notes[] shape. Real observed payloads in this project have also been seen in a flatter response.release_notes[] style. The integration should therefore stay tolerant to either wrapper shape.

Returns release-note entries containing:

Field	Type	Example	Description
`title`	string	`"Tesla Photobooth"`	Feature title
`subtitle`	string	`" "`	Subtitle
`description`	string	`"Turn your car into..."`	Feature description
`customer_version`	string	`"2025.44.25.4"`	Software version
`icon`	string	`"tesla_icon"`	Icon identifier
`show_in_history`	bool	`true`	Show in history
`image_url`	string	`"https://vehicle-files.teslamotors.com/..."`	Feature image
`light_image_url`	string	`"https://vehicle-files.teslamotors.com/..."`	Light mode image
`is_fallback`	bool	`false`	Fallback release note

Top-level release notes metadata:

{
  "deployed_version": "2026.2.3",
  "staged_version": null,
  "release_notes_version": "2026.2.3"
}

4.11 Fleet Status

POST /api/1/vehicles/fleet_status
Authorization: Bearer <USER_TOKEN>
Content-Type: application/json

Provides information necessary to determine a vehicle's state as it pertains to the application.

Scope:

vehicle_device_data

Pricing:

not charged

Body parameter:

Parameter	Location	Description
`vins`	body	List of VINs. Tesla recommends passing one VIN at a time.

Documented request example:

curl -H "Authorization: Bearer $TESLA_AUTH_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{
    "vins": [
      "vin1"
    ]
  }' \
  -X POST \
  -i https://fleet-api.prd.na.vn.cloud.tesla.com/api/1/vehicles/fleet_status

Documented response:

{
  "response": {
    "key_paired_vins": [],
    "unpaired_vins": [
      "5YJ3000000NEXUS01"
    ],
    "vehicle_info": {
      "5YJ3000000NEXUS01": {
        "firmware_version": "2024.14.30",
        "vehicle_command_protocol_required": true,
        "discounted_device_data": false,
        "fleet_telemetry_version": "1.0.0",
        "total_number_of_keys": 5
      }
    }
  }
}

Known response fields:

Field	Type	Description
`response.key_paired_vins[]`	array	VINs with paired key present
`response.unpaired_vins[]`	array	VINs without paired key
`response.vehicle_info`	object	VIN-keyed vehicle state object
`vehicle_info[vin].firmware_version`	string	Firmware version
`vehicle_info[vin].vehicle_command_protocol_required`	bool	Whether command protocol is required
`vehicle_info[vin].discounted_device_data`	bool	Whether discounted device-data pricing applies
`vehicle_info[vin].fleet_telemetry_version`	string	Fleet telemetry client version
`vehicle_info[vin].total_number_of_keys`	int	Total number of keys on vehicle

Practical use:

command/telemetry readiness check
key pairing state check
future vehicle-data cost optimization

5. Fleet API Regions

Region	Base URL
EU	`https://fleet-api.prd.eu.vn.cloud.tesla.com`
NA	`https://fleet-api.prd.na.vn.cloud.tesla.com`
CN	`https://fleet-api.prd.cn.vn.cloud.tesla.com`

Currently registered for EU only.

6. User-Context Endpoints

Tesla documents user endpoints separately and explicitly states:

these endpoints require a user context
third-party business tokens are not compatible with these requests

6.1 Feature Config

GET /api/1/users/feature_config
Authorization: Bearer <USER_TOKEN>

Scope:

user_data

Pricing:

not charged

Parameters:

none

Documented request example:

curl -H "Authorization: Bearer $TESLA_AUTH_TOKEN" \
  -i https://fleet-api.prd.na.vn.cloud.tesla.com/api/1/users/feature_config

Documented response:

{
  "response": {
    "signaling": {
      "enabled": true,
      "subscribe_connectivity": false,
      "use_auth_token": false
    }
  }
}

Known response fields:

Field	Type	Description
`response.signaling.enabled`	bool	Whether signaling is enabled
`response.signaling.subscribe_connectivity`	bool	Connectivity subscription flag
`response.signaling.use_auth_token`	bool	Auth token signaling flag

6.2 User Summary

GET /api/1/users/me
Authorization: Bearer <USER_TOKEN>

Scope:

user_data

Pricing:

not charged

Parameters:

none

Documented request example:

curl -H "Authorization: Bearer $TESLA_AUTH_TOKEN" \
  -i https://fleet-api.prd.na.vn.cloud.tesla.com/api/1/users/me

Documented response:

{
  "response": {
    "email": "test-user@tesla.com",
    "full_name": "Testy McTesterson",
    "profile_image_url": "https://vehicle-files.prd.usw2.vn.cloud.tesla.com/profile_images/f98c87cd7bebc06069b89b33f9ec634c195520f75b6e63ea89f0b7c61449c689.jpg",
    "vault_uuid": "b5c443af-a286-49eb-a4ad-35a97963155d"
  }
}

Known response fields:

Field	Type	Description
`response.email`	string	Tesla account email
`response.full_name`	string	Tesla account full name
`response.profile_image_url`	string	Profile image URL
`response.vault_uuid`	string	Tesla vault UUID

6.3 User Orders

GET /api/1/users/orders
Authorization: Bearer <USER_TOKEN>

Scope:

vehicle_device_data

Pricing:

not charged

Parameters:

none

Documented request example:

curl -H "Authorization: Bearer $TESLA_AUTH_TOKEN" \
  -i https://fleet-api.prd.na.vn.cloud.tesla.com/api/1/users/orders

Documented response:

{
  "response": [
    {
      "vehicleMapId": 1234466,
      "referenceNumber": "RN00000001",
      "vin": "5YJ30000000000001",
      "orderStatus": "BOOKED",
      "orderSubstatus": "_Z",
      "modelCode": "m3",
      "countryCode": "US",
      "locale": "en_US",
      "mktOptions": "APBS,DV2W,IBB1,PMNG,PRM30,SC04,MDL3,W41B,MT322,CPF0,RSF1,CW03",
      "isB2b": false
    }
  ],
  "count": 1
}

Known response fields:

Field	Type	Description
`response[].vehicleMapId`	int	Vehicle map ID
`response[].referenceNumber`	string	Order reference number
`response[].vin`	string	VIN
`response[].orderStatus`	string	Order status
`response[].orderSubstatus`	string	Order substatus
`response[].modelCode`	string	Model code
`response[].countryCode`	string	Country code
`response[].locale`	string	Locale
`response[].mktOptions`	string	Market/options code string
`response[].isB2b`	bool	Business-order flag
`count`	int	Number of returned orders

6.4 User Region

GET /api/1/users/region
Authorization: Bearer <USER_TOKEN>

Returns the user's region and the appropriate Fleet API base URL. The response is based on the authentication token subject.

Scopes:

vehicle_device_data
vehicle_location
vehicle_charging_cmds
vehicle_cmds
energy_cmds
energy_device_data
user_data

Pricing:

not charged

Parameters:

none

Documented request example:

curl -H "Authorization: Bearer $TESLA_AUTH_TOKEN" \
  -i https://fleet-api.prd.na.vn.cloud.tesla.com/api/1/users/region

Documented response:

{
  "response": {
    "region": "eu",
    "fleet_api_base_url": "https://fleet-api.prd.eu.vn.cloud.tesla.com"
  }
}

Known response fields:

Field	Type	Description
`response.region`	string	User region
`response.fleet_api_base_url`	string	Fleet API base URL for that user/token

7. Current Code vs Documented Endpoints

This section exists so endpoint drift does not stay hidden in code review or chat only.

Current report fetching happens in:

bnc-cpt-api/src/python/cpt-api/app/services/tesla_fleet.py
method: _build_vehicle_report(...)

6.1 Endpoint Match Table

Module	Current code path	Tesla-documented path	Status	Notes
vehicle_data	`GET /api/1/vehicles/{vehicle_tag}/vehicle_data`	`GET /api/1/vehicles/{vin}/vehicle_data`	needs alignment review	Current code uses `vehicle_tag`; Tesla docs show VIN path.
charging_history	`GET /api/1/dx/charging/history?vehicle_tag=...`	`GET /api/1/dx/charging/history`	mismatch / undocumented param use	Docs do not document `vehicle_tag` here.
recent_alerts	`GET /api/1/vehicles/{vehicle_tag}/recent_alerts`	`GET /api/1/vehicles/{vin}/recent_alerts`	needs alignment review	Current code uses `vehicle_tag`; docs show VIN path.
service_data	`GET /api/1/vehicles/{vehicle_tag}/service_data`	`GET /api/1/vehicles/{vin}/service_data`	needs alignment review	Current code uses `vehicle_tag`; docs show VIN path.
warranty	`GET /api/1/dx/warranty/details?vin={vin}`	`GET /api/1/dx/warranty/details?vin={vin}`	match	VIN query required.
release_notes	`GET /api/1/vehicles/{vehicle_tag}/release_notes`	`GET /api/1/vehicles/{vin}/release_notes`	needs alignment review	Current code uses `vehicle_tag`; docs show VIN path.
options	`GET /api/1/vehicles/{vehicle_tag}/options`	`GET /api/1/dx/vehicles/options?vin={vin}`	mismatch	This is a strong documented mismatch.
vehicle_specs	`GET /api/1/dx/vehicles/fleet_vehicle_specs?vin={vin}`	`GET /api/1/vehicles/{vin}/specs`	mismatch	Docs also state partner token only.

6.2 Architectural Consequence

The current code path should not be treated as automatically correct just because the report renders.

The endpoint match table above must be used during the fetch-architecture refactor so:

documented Tesla request paths are the baseline
token assumptions are explicit
per-vehicle vs shared/account-level fetch scope is explicit

8. Live Test Script

A standalone test script is available for manual testing:

tests/test_tesla_live.py

Usage

cd /opt/bnc/bnc-cpt/bnc-cpt-api/src/python/cpt-api

# Create venv (one-time)
python3 -m venv .venv-test
source .venv-test/bin/activate
pip install requests

# Run with existing token
python3 tests/test_tesla_live.py --token <ACCESS_TOKEN>

# Run full OAuth flow
python3 tests/test_tesla_live.py --client-id <ID> --client-secret <SECRET>

# Specify region
python3 tests/test_tesla_live.py --token <TOKEN> --region na

Output Files (local only, not committed)

File	Description
`tests/tesla_api_responses.json`	Raw API responses from all endpoints
`tests/.tesla_test_token.json`	Saved OAuth token for reuse

These files contain personal data (VINs, user IDs, charging history) and are generated locally only.

9. Known Issues & Next Steps

Known Issues

Issue	Status	Details
NA users get 412 region error (BNC-115)	ACTION NEEDED	Developer account only registered in EU. Run `REGION=na DOMAIN=api.carpulsetracker.com ./run -a do_tesla_register_partner` to fix. Code already has multi-region fallback.
Warranty endpoint needs VIN	FIXED	VIN passed as query parameter in `_build_vehicle_report()`. Working in production.
Specs endpoint returns 403	By design	Requires partner token, not user token. `vehicle_specs` scope added to config. Specs are optional and package-dependent.
Charging history is account-level	FIXED	`GET /api/1/dx/charging/history` can return shared account-level data. The target model is: fetch once per order/request, partition by `vin`, then derive each vehicle report and invoice export from the VIN-root slice.
`drive_state` missing from vehicle_data	Investigating	TypeScript types define it but real API did not include it. May need `endpoints=` parameter or specific scope.
CI test failing	Pre-existing	Container name mismatch in GitHub Actions

Resolved (previously listed)

Issue	Resolution	Date
Tesla router uses mockup data	Replaced with real Tesla Fleet API integration (OAuth + all endpoints)	2026-02-18
Tesla credentials not in GCP	Configured in GCP Secret Manager per environment	2026-02-20
Multi-vehicle support	Implemented — selected VINs are tracked per order/request and reports are generated per vehicle	2026-02-18
Real OAuth flow	Implemented — `POST /tesla/oauth/initiate` + callback with token exchange	2026-02-18
Warranty VIN bug	Fixed — VIN passed explicitly in `generate_reports()` → `_build_vehicle_report()`	2026-02-18

Next Steps

Implement specs with partner token - Use client_credentials grant for the specs endpoint when the selected package requires specs
Token refresh - Implement automatic token refresh using refresh_token when an order/report request is long-lived
Investigate drive_state - Why missing from vehicle_data? Scope, vehicle state, or needs endpoints= param?
Error handling - Handle Tesla API rate limits (429), vehicle asleep (408), and other error states
GCS report storage - Store PDFs + order manifest in GCS bucket for permanent access (Phase 3)
Order/request persistence - Replace in-memory request state with durable order/request storage for persistence across API restarts (Phase 3)

10. Live Test Results Summary (2026-02-10)

First successful live test completed 2026-02-10 with two real vehicles:

Vehicle	Display Name	VIN	Model	Trim	Software
1	MyTesla	LRWXXXXXXX...	model3	74d	2026.2.3
2	MyTesla2	XP7XXXXXXX...	-	-	-

Endpoint Results

Endpoint	HTTP	Result
`/api/1/vehicles`	200	2 vehicles found
`/api/1/vehicles/{id}/vehicle_data`	200	Full data: battery 74%, range 243mi, odometer 12345mi
`/api/1/vehicles/{id}/service_data`	200	Empty (no service appointments)
`/api/1/dx/charging/history`	200	Multiple sessions, Supercharger locations in Finland
`/api/1/vehicles/{id}/recent_alerts`	200	12 recent alerts (AEB, ISA, charging issues)
`/api/1/dx/warranty/details`	500	Needs VIN parameter (bug in test script)
`/api/1/vehicles/{vin}/specs`	403	Needs partner token, not user token
`/api/1/dx/vehicles/options`	200	6 options: Autopilot, LR AWD, Deep Blue, 18" Photon
`/api/1/vehicles/{vin}/release_notes`	200	12 release notes from 2025.44 to 2026.2.3