This is unofficial documentation of the Tesla Model S JSON API used by the iOS and Android apps. It features functionality to monitor and control the Model S remotely.
/oauth/token
Get an Access Token
Performs the login. Takes in an plain text email and password, matching the owner's login information for https://my.teslamotors.com/user/login.
Returns a access_token
which is passed along as a header with all future requests to authenticate the user.
You must provide the Authorization: Bearer {access_token}
header in all other requests.
The current client ID and secret are available here
string
() password
The type of oAuth grant. Always "password"
string
() abc
The oAuth client ID
string
() 123
The oAuth client secret
string
() elon@teslamotors.com
The email for my.teslamotors.com
string
() edisonsux
The password for my.teslamotors.com
Content-Type: application/json
{ "access_token": "abc123", "token_type": "bearer", "expires_in": 7776000, "created_at": 1457385291 }
A logged in user can have multiple vehicles under their account. This resource is primarily responsible for listing the vehicles and the basic details about them.
/api/1/vehicles
List all Vehicles
Retrieve a list of your owned vehicles (includes vehicles not yet shipped!)
Authorization: Bearer {access_token}
Content-Type: application/json
{ "response": [{ "color": null, "display_name": null, "id": 321, "option_codes": "MS01,RENA,TM00,DRLH,PF00,BT85,PBCW,RFPO,WT19,IBMB,IDPB,TR00,SU01,SC01,TP01,AU01,CH00,HP00,PA00,PS00,AD02,X020,X025,X001,X003,X007,X011,X013", "user_id": 123, "vehicle_id": 1234567890, "vin": "5YJSA1CN5CFP01657", "tokens": ["x", "x"], "state": "online" }], "count":1 }
/api/1/vehicles/{vehicle_id}/mobile_enabled
Mobile Access
Determines if mobile access to the vehicle is enabled.
Authorization: Bearer {access_token}
number
() 1
The id of the Vehicle.
Content-Type: application/json
{ "response": true }
/api/1/vehicles/{vehicle_id}/data_request/charge_state
Charge State
Returns the state of charge in the battery.
Authorization: Bearer {access_token}
number
() 1
The id of the Vehicle.
Content-Type: application/json
{ "response": { "charging_state": "Complete", // "Charging", ?? "charge_to_max_range": false, // current std/max-range setting "max_range_charge_counter": 0, "fast_charger_present": false, // connected to Supercharger? "battery_range": 239.02, // rated miles "est_battery_range": 155.79, // range estimated from recent driving "ideal_battery_range": 275.09, // ideal miles "battery_level": 91, // integer charge percentage "battery_current": -0.6, // current flowing into battery "charge_starting_range": null, "charge_starting_soc": null, "charger_voltage": 0, // only has value while charging "charger_pilot_current": 40, // max current allowed by charger & adapter "charger_actual_current": 0, // current actually being drawn "charger_power": 0, // kW (rounded down) of charger "time_to_full_charge": null, // valid only while charging "charge_rate": -1.0, // float mi/hr charging or -1 if not charging "charge_port_door_open": true } }
/api/1/vehicles/{vehicle_id}/data_request/climate_state
Climate Settings
Returns the current temperature and climate control state.
Authorization: Bearer {access_token}
number
() 1
The id of the Vehicle.
Content-Type: application/json
{ "response": { "inside_temp": 17.0, // degC inside car "outside_temp": 9.5, // degC outside car or null "driver_temp_setting": 22.6, // degC of driver temperature setpoint "passenger_temp_setting": 22.6, // degC of passenger temperature setpoint "is_auto_conditioning_on": false, // apparently even if on "is_front_defroster_on": null, // null or boolean as integer? "is_rear_defroster_on": false, "fan_status": 0 // fan speed 0-6 or null } }
/api/1/vehicles/{vehicle_id}/data_request/drive_state
Driving and Position
Returns the driving and position state of the vehicle.
Authorization: Bearer {access_token}
number
() 1
The id of the Vehicle.
Content-Type: application/json
{ "response": { "shift_state": null, // "speed": null, // "latitude": 33.794839, // degrees N of equator "longitude": -84.401593, // degrees W of the prime meridian "heading": 4, // integer compass heading, 0-359 "gps_as_of": 1359863204 // Unix timestamp of GPS fix } }
/api/1/vehicles/{vehicle_id}/data_request/gui_settings
GUI Settings
Returns various information about the GUI settings of the car, such as unit format and range display.
Authorization: Bearer {access_token}
number
() 1
The id of the Vehicle.
Content-Type: application/json
{ "response": { "gui_distance_units": "mi/hr", "gui_temperature_units": "F", "gui_charge_rate_units": "mi/hr", "gui_24_hour_time": false, "gui_range_display": "Rated" } }
/api/1/vehicles/{vehicle_id}/data_request/vehicle_state
Vehicle State
Returns the vehicle's physical state, such as which doors are open.
Authorization: Bearer {access_token}
number
() 1
The id of the Vehicle.
Content-Type: application/json
{ "response": { "df": false, // driver's side front door open "dr": false, // driver's side rear door open "pf": false, // passenger's side front door open "pr": false, // passenger's side rear door open "ft": false, // front trunk is open "rt": false, // rear trunk is open "car_verson": "1.19.42", // car firmware version "locked": true, // car is locked "sun_roof_installed": false, // panoramic roof is installed "sun_roof_state": "unknown", "sun_roof_percent_open": 0, // null if not installed "dark_rims": false, // gray rims installed "wheel_type": "Base19", // wheel type installed "has_spoiler": false, // spoiler is installed "roof_color": "Colored", // "None" for panoramic roof "perf_config": "Base" } }
These commands alter the vehicles state, and return result (true/false) to indicate success, and if failure reason contains the cause of failure.
/api/1/vehicles/{vehicle_id}/wake_up
Wake Up Car
Wakes up the car from the sleep state. Necessary to get some data from the car.
Authorization: Bearer {access_token}
number
() 1
The id of the Vehicle.
Content-Type: application/json
{ "response": { "result": true, "reason": "" } }
/api/1/vehicles/{vehicle_id}/command/set_valet_mode
Set Valet Mode
Sets valet mode on or off with a PIN to disable it from within the car. Reuses last PIN from previous valet session. Valet Mode limits the car's top speed to 70MPH and 80kW of acceleration power. It also disables Homelink, Bluetooth and Wifi settings, and the ability to disable mobile access to the car. It also hides your favorites, home, and work locations in navigation.
Authorization: Bearer {access_token}
number
() 1
The id of the Vehicle.
boolean
() 1
Whether to enable or disable valet mode.
number
() 1234
(optional) A 4 digit PIN code to unlock the car.
Content-Type: application/json
{ "response": { "result": true, "reason": "" } }
/api/1/vehicles/{vehicle_id}/command/reset_valet_pin
Reset Valet PIN
Resets the PIN set for valet mode, if set.
Authorization: Bearer {access_token}
number
() 1
The id of the Vehicle.
Content-Type: application/json
{ "response": { "result": true, "reason": "" } }
/api/1/vehicles/{vehicle_id}/command/charge_port_door_open
Open Charge Port
Opens the charge port. Does not close the charge port (for now...)
Authorization: Bearer {access_token}
number
() 1
The id of the Vehicle.
Content-Type: application/json
{ "response": { "result": true, "reason": "" } }
/api/1/vehicles/{vehicle_id}/command/charge_standard
Set Charge Limit to Standard
Set the charge mode to standard (90% under the new percentage system introduced in 4.5).
Authorization: Bearer {access_token}
number
() 1
The id of the Vehicle.
Content-Type: application/json
{ "response": { "result": false, "reason": "already_standard" } }
/api/1/vehicles/{vehicle_id}/command/charge_max_range
Set Charge Limit to Max Range
Set the charge mode to max range (100% under the new percentage system introduced in 4.5). Use sparingly!
Authorization: Bearer {access_token}
number
() 1
The id of the Vehicle.
Content-Type: application/json
{ "response": { "result": false, "reason": "already_max_range" } }
/api/1/vehicles/{vehicle_id}/command/set_charge_limit?percent={limit_value}
Set Charge Limit
Set the charge limit to a custom percentage.
Authorization: Bearer {access_token}
number
() 1
The id of the Vehicle.
number
() 75
The percentage value
Content-Type: application/json
{ "response": { "result": true, "reason": "" } }
/api/1/vehicles/{vehicle_id}/command/charge_start
Start Charging
Start charging. Must be plugged in, have power available, and not have reached your charge limit.
Authorization: Bearer {access_token}
number
() 1
The id of the Vehicle.
Content-Type: application/json
{ "response": { "result": true, "reason": "" // "already_started" if a charge is in progress } }
/api/1/vehicles/{vehicle_id}/command/charge_stop
Stop Charging
Stop charging. Must already be charging.
Authorization: Bearer {access_token}
number
() 1
The id of the Vehicle.
Content-Type: application/json
{ "response": { "result": true, "reason": "" // "not_charging" if a charge was not in progress } }
/api/1/vehicles/{vehicle_id}/command/flash_lights
Flash Lights
Flash the lights once.
Authorization: Bearer {access_token}
number
() 1
The id of the Vehicle.
Content-Type: application/json
{ "response": { "result": true, "reason": "" } }
/api/1/vehicles/{vehicle_id}/command/honk_horn
Honk Horn
Honk the horn once.
Authorization: Bearer {access_token}
number
() 1
The id of the Vehicle.
Content-Type: application/json
{ "response": { "result": true, "reason": "" } }
/api/1/vehicles/{vehicle_id}/command/door_unlock
Unlock Doors
Unlock the car's doors.
Authorization: Bearer {access_token}
number
() 1
The id of the Vehicle.
Content-Type: application/json
{ "response": { "result": true, "reason": "" } }
/api/1/vehicles/{vehicle_id}/command/door_lock
Lock Doors
Lock the car's doors.
Authorization: Bearer {access_token}
number
() 1
The id of the Vehicle.
Content-Type: application/json
{ "response": { "result": true, "reason": "" } }
/api/1/vehicles/{vehicle_id}/command/set_temps?driver_temp={driver_degC}&passenger_temp={pass_degC}
Set Temperature
Set the temperature target for the HVAC system.
Authorization: Bearer {access_token}
number
() 1
The id of the Vehicle.
number
() 23.7
The desired temperature on the driver's side in celcius.
number
() 18.1
The desired temperature on the passenger's side in celcius.
Content-Type: application/json
{ "response": { "result": true, "reason": "" } }
/api/1/vehicles/{vehicle_id}/command/auto_conditioning_start
Start HVAC System
Start the climate control system. Will cool or heat automatically, depending on set temperature.
Authorization: Bearer {access_token}
number
() 1
The id of the Vehicle.
Content-Type: application/json
{ "response": { "result": true, "reason": "" } }
/api/1/vehicles/{vehicle_id}/command/auto_conditioning_stop
Stop HVAC System
Stop the climate control system.
Authorization: Bearer {access_token}
number
() 1
The id of the Vehicle.
Content-Type: application/json
{ "response": { "result": true, "reason": "" } }
/api/1/vehicles/{vehicle_id}/command/sun_roof_control?state={state}&percent={percent}
Move Pano Roof
Controls the car's panoramic roof, if installed.
Authorization: Bearer {access_token}
number
() 1
The id of the Vehicle.
enum
() open|close|comfort|vent|move
The desired state of the panoramic roof. The approximate percent open values for each state are `open` = 100%, `close` = 0%, `comfort` = 80%, and `vent` = ~15%
number
(optional) 50
The percentage to move the roof to.
Content-Type: application/json
{ "response": { "result": true, "reason": "" } }
/api/1/vehicles/{vehicle_id}/command/remote_start_drive?password={password}
Remote Start
Start the car for keyless driving. Must start driving within 2 minutes of issuing this request.
Authorization: Bearer {access_token}
number
() 1
The id of the Vehicle.
string
() edisonsux
The password to the authenticated my.teslamotors.com account.
Content-Type: application/json
{ "response": { "result": true, "reason": "" } }
/api/1/vehicles/{vehicle_id}/command/trunk_open
Open Trunk/Frunk
Open the trunk or frunk. Currently inoperable.
Authorization: Bearer {access_token}
number
() 1
The id of the Vehicle.
string
() rear
The trunk to open. `rear` is the only one known currently.
Content-Type: application/json
{ "response": { "result": true, "reason": "" } }