Tesla Model S JSON API https://owner-api.teslamotors.com

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.

Authentication
Vehicles
Vehicle Commands
https://owner-api.teslamotors.com

Authentication

Tokens /oauth/token

POST /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

Request
Example URI
https://owner-api.teslamotors.com/oauth/token
Request object
grant_typestring

The type of oAuth grant. Always "password"

password
client_idstring

The oAuth client ID

abc
client_secretstring

The oAuth client secret

123
emailstring

The email for my.teslamotors.com

elon@teslamotors.com
passwordstring

The password for my.teslamotors.com

edisonsux
Response 200 OK
Headers
  • Content-Type: application/json
application/json 
{
  "access_token": "abc123",
  "token_type": "bearer",
  "expires_in": 7776000,
  "created_at": 1457385291
}

Vehicles

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.

Vehicle Collection /api/1/vehicles

GET /api/1/vehicles List all Vehicles

Retrieve a list of your owned vehicles (includes vehicles not yet shipped!)

Request
Example URI
https://owner-api.teslamotors.com/api/1/vehicles
Headers
  • Authorization: Bearer {access_token}
Response 200 OK
Headers
  • Content-Type: application/json
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
}

State and Settings /api/1/vehicles/{vehicle_id}

These resources are read-only and determine the state of the vehicle's various sub-systems.

GET /api/1/vehicles/{vehicle_id}/mobile_enabled Mobile Access

Determines if mobile access to the vehicle is enabled.

Request
Example URI
https://owner-api.teslamotors.com/api/1/vehicles/1/mobile_enabled
Headers
  • Authorization: Bearer {access_token}
URI Parameters
vehicle_idnumber required

The id of the Vehicle.

1
Response 200 OK
Headers
  • Content-Type: application/json
application/json 
{
    "response": true
}
GET /api/1/vehicles/{vehicle_id}/data_request/charge_state Charge State

Returns the state of charge in the battery.

Request
Example URI
https://owner-api.teslamotors.com/api/1/vehicles/1/data_request/charge_state
Headers
  • Authorization: Bearer {access_token}
URI Parameters
vehicle_idnumber required

The id of the Vehicle.

1
Response 200 OK
Headers
  • Content-Type: application/json
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
  }
}
GET /api/1/vehicles/{vehicle_id}/data_request/climate_state Climate Settings

Returns the current temperature and climate control state.

Request
Example URI
https://owner-api.teslamotors.com/api/1/vehicles/1/data_request/climate_state
Headers
  • Authorization: Bearer {access_token}
URI Parameters
vehicle_idnumber required

The id of the Vehicle.

1
Response 200 OK
Headers
  • Content-Type: application/json
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
  }
}
GET /api/1/vehicles/{vehicle_id}/data_request/drive_state Driving and Position

Returns the driving and position state of the vehicle.

Request
Example URI
https://owner-api.teslamotors.com/api/1/vehicles/1/data_request/drive_state
Headers
  • Authorization: Bearer {access_token}
URI Parameters
vehicle_idnumber required

The id of the Vehicle.

1
Response 200 OK
Headers
  • Content-Type: application/json
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
  }
}
GET /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.

Request
Example URI
https://owner-api.teslamotors.com/api/1/vehicles/1/data_request/gui_settings
Headers
  • Authorization: Bearer {access_token}
URI Parameters
vehicle_idnumber required

The id of the Vehicle.

1
Response 200 OK
Headers
  • Content-Type: application/json
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"
  }
}
GET /api/1/vehicles/{vehicle_id}/data_request/vehicle_state Vehicle State

Returns the vehicle's physical state, such as which doors are open.

Request
Example URI
https://owner-api.teslamotors.com/api/1/vehicles/1/data_request/vehicle_state
Headers
  • Authorization: Bearer {access_token}
URI Parameters
vehicle_idnumber required

The id of the Vehicle.

1
Response 200 OK
Headers
  • Content-Type: application/json
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"
  }
}

Vehicle Commands

These commands alter the vehicles state, and return result (true/false) to indicate success, and if failure reason contains the cause of failure.

Wake Up Car /api/1/vehicles/{vehicle_id}/wake_up

POST /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.

Request
Example URI
https://owner-api.teslamotors.com/api/1/vehicles/1/wake_up
Headers
  • Authorization: Bearer {access_token}
URI Parameters
vehicle_idnumber required

The id of the Vehicle.

1
Response 200 OK
Headers
  • Content-Type: application/json
application/json 
{
  "response": {
    "result": true,
    "reason": ""
  }
}

Set Valet Mode /api/1/vehicles/{vehicle_id}/command/set_valet_mode

POST /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.

Request
Example URI
https://owner-api.teslamotors.com/api/1/vehicles/1/command/set_valet_mode
Headers
  • Authorization: Bearer {access_token}
URI Parameters
vehicle_idnumber required

The id of the Vehicle.

1
Request object
onboolean

Whether to enable or disable valet mode.

true
passwordnumber

(optional) A 4 digit PIN code to unlock the car.

1234
Response 200 OK
Headers
  • Content-Type: application/json
application/json 
{
  "response": {
    "result": true,
    "reason": ""
  }
}

Reset Valet PIN /api/1/vehicles/{vehicle_id}/command/reset_valet_pin

POST /api/1/vehicles/{vehicle_id}/command/reset_valet_pin Reset Valet PIN

Resets the PIN set for valet mode, if set.

Request
Example URI
https://owner-api.teslamotors.com/api/1/vehicles/1/command/reset_valet_pin
Headers
  • Authorization: Bearer {access_token}
URI Parameters
vehicle_idnumber required

The id of the Vehicle.

1
Response 200 OK
Headers
  • Content-Type: application/json
application/json 
{
  "response": {
    "result": true,
    "reason": ""
  }
}

Open Charge Port /api/1/vehicles/{vehicle_id}/command/charge_port_door_open

POST /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...)

Request
Example URI
https://owner-api.teslamotors.com/api/1/vehicles/1/command/charge_port_door_open
Headers
  • Authorization: Bearer {access_token}
URI Parameters
vehicle_idnumber required

The id of the Vehicle.

1
Response 200 OK
Headers
  • Content-Type: application/json
application/json 
{
  "response": {
    "result": true,
    "reason": ""
  }
}

Set Charge Limit to Standard /api/1/vehicles/{vehicle_id}/command/charge_standard

POST /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).

Request
Example URI
https://owner-api.teslamotors.com/api/1/vehicles/1/command/charge_standard
Headers
  • Authorization: Bearer {access_token}
URI Parameters
vehicle_idnumber required

The id of the Vehicle.

1
Response 200 OK
Headers
  • Content-Type: application/json
application/json 
{
  "response": {
    "result": false,
    "reason": "already_standard"
  }
}

Set Charge Limit to Max Range /api/1/vehicles/{vehicle_id}/command/charge_max_range

POST /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!

Request
Example URI
https://owner-api.teslamotors.com/api/1/vehicles/1/command/charge_max_range
Headers
  • Authorization: Bearer {access_token}
URI Parameters
vehicle_idnumber required

The id of the Vehicle.

1
Response 200 OK
Headers
  • Content-Type: application/json
application/json 
{
  "response": {
    "result": false,
    "reason": "already_max_range"
  }
}

Set Charge Limit /api/1/vehicles/{vehicle_id}/command/set_charge_limit?percent={limit_value}

POST /api/1/vehicles/{vehicle_id}/command/set_charge_limit?percent={limit_value} Set Charge Limit

Set the charge limit to a custom percentage.

Request
Example URI
https://owner-api.teslamotors.com/api/1/vehicles/1/command/set_charge_limit?percent=75
Headers
  • Authorization: Bearer {access_token}
URI Parameters
vehicle_idnumber required

The id of the Vehicle.

1
limit_valuenumber required

The percentage value

75
Response 200 OK
Headers
  • Content-Type: application/json
application/json 
{
  "response": {
    "result": true,
    "reason": ""
  }
}

Start Charging /api/1/vehicles/{vehicle_id}/command/charge_start

POST /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.

Request
Example URI
https://owner-api.teslamotors.com/api/1/vehicles/1/command/charge_start
Headers
  • Authorization: Bearer {access_token}
URI Parameters
vehicle_idnumber required

The id of the Vehicle.

1
Response 200 OK
Headers
  • Content-Type: application/json
application/json 
{
  "response": {
    "result": true,
    "reason": "" // "already_started" if a charge is in progress
  }
}

Stop Charging /api/1/vehicles/{vehicle_id}/command/charge_stop

POST /api/1/vehicles/{vehicle_id}/command/charge_stop Stop Charging

Stop charging. Must already be charging.

Request
Example URI
https://owner-api.teslamotors.com/api/1/vehicles/1/command/charge_stop
Headers
  • Authorization: Bearer {access_token}
URI Parameters
vehicle_idnumber required

The id of the Vehicle.

1
Response 200 OK
Headers
  • Content-Type: application/json
application/json 
{
  "response": {
    "result": true,
    "reason": "" // "not_charging" if a charge was not in progress
  }
}

Flash Lights /api/1/vehicles/{vehicle_id}/command/flash_lights

POST /api/1/vehicles/{vehicle_id}/command/flash_lights Flash Lights

Flash the lights once.

Request
Example URI
https://owner-api.teslamotors.com/api/1/vehicles/1/command/flash_lights
Headers
  • Authorization: Bearer {access_token}
URI Parameters
vehicle_idnumber required

The id of the Vehicle.

1
Response 200 OK
Headers
  • Content-Type: application/json
application/json 
{
  "response": {
    "result": true,
    "reason": ""
  }
}

Honk Horn /api/1/vehicles/{vehicle_id}/command/honk_horn

POST /api/1/vehicles/{vehicle_id}/command/honk_horn Honk Horn

Honk the horn once.

Request
Example URI
https://owner-api.teslamotors.com/api/1/vehicles/1/command/honk_horn
Headers
  • Authorization: Bearer {access_token}
URI Parameters
vehicle_idnumber required

The id of the Vehicle.

1
Response 200 OK
Headers
  • Content-Type: application/json
application/json 
{
  "response": {
    "result": true,
    "reason": ""
  }
}

Unlock Doors /api/1/vehicles/{vehicle_id}/command/door_unlock

POST /api/1/vehicles/{vehicle_id}/command/door_unlock Unlock Doors

Unlock the car's doors.

Request
Example URI
https://owner-api.teslamotors.com/api/1/vehicles/1/command/door_unlock
Headers
  • Authorization: Bearer {access_token}
URI Parameters
vehicle_idnumber required

The id of the Vehicle.

1
Response 200 OK
Headers
  • Content-Type: application/json
application/json 
{
  "response": {
    "result": true,
    "reason": ""
  }
}

Lock Doors /api/1/vehicles/{vehicle_id}/command/door_lock

POST /api/1/vehicles/{vehicle_id}/command/door_lock Lock Doors

Lock the car's doors.

Request
Example URI
https://owner-api.teslamotors.com/api/1/vehicles/1/command/door_lock
Headers
  • Authorization: Bearer {access_token}
URI Parameters
vehicle_idnumber required

The id of the Vehicle.

1
Response 200 OK
Headers
  • Content-Type: application/json
application/json 
{
  "response": {
    "result": true,
    "reason": ""
  }
}

Set Temperature /api/1/vehicles/{vehicle_id}/command/set_temps?driver_temp={driver_degC}&passenger_temp={pass_degC}

POST /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.

Request
Example URI
https://owner-api.teslamotors.com/api/1/vehicles/1/command/set_temps?driver_temp=23.7&passenger_temp=18.1
Headers
  • Authorization: Bearer {access_token}
URI Parameters
vehicle_idnumber required

The id of the Vehicle.

1
driver_degCnumber required

The desired temperature on the driver's side in °C.

23.7
pass_degCnumber required

The desired temperature on the passenger's side in °C.

18.1
Response 200 OK
Headers
  • Content-Type: application/json
application/json 
{
  "response": {
    "result": true,
    "reason": ""
  }
}

Start HVAC System /api/1/vehicles/{vehicle_id}/command/auto_conditioning_start

POST /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.

Request
Example URI
https://owner-api.teslamotors.com/api/1/vehicles/1/command/auto_conditioning_start
Headers
  • Authorization: Bearer {access_token}
URI Parameters
vehicle_idnumber required

The id of the Vehicle.

1
Response 200 OK
Headers
  • Content-Type: application/json
application/json 
{
  "response": {
    "result": true,
    "reason": ""
  }
}

Stop HVAC System /api/1/vehicles/{vehicle_id}/command/auto_conditioning_stop

POST /api/1/vehicles/{vehicle_id}/command/auto_conditioning_stop Stop HVAC System

Stop the climate control system.

Request
Example URI
https://owner-api.teslamotors.com/api/1/vehicles/1/command/auto_conditioning_stop
Headers
  • Authorization: Bearer {access_token}
URI Parameters
vehicle_idnumber required

The id of the Vehicle.

1
Response 200 OK
Headers
  • Content-Type: application/json
application/json 
{
  "response": {
    "result": true,
    "reason": ""
  }
}

Move Pano Roof /api/1/vehicles/{vehicle_id}/command/sun_roof_control?state={state}&percent={percent}

POST /api/1/vehicles/{vehicle_id}/command/sun_roof_control?state={state}&percent={percent} Move Pano Roof

Controls the car's panoramic roof, if installed.

Request
Example URI
https://owner-api.teslamotors.com/api/1/vehicles/1/command/sun_roof_control?state=%3Cul%20class%3D%22list-group%20mdl-list%22%3E%3Cli%20class%3D%22list-group-item%20mdl-list__item%22%3Eopen%3C%2Fli%3E%3Cli%20class%3D%22list-group-item%20mdl-list__item%22%3Eclose%3C%2Fli%3E%3Cli%20class%3D%22list-group-item%20mdl-list__item%22%3Ecomfort%3C%2Fli%3E%3Cli%20class%3D%22list-group-item%20mdl-list__item%22%3Event%3C%2Fli%3E%3Cli%20class%3D%22list-group-item%20mdl-list__item%22%3Emove%3C%2Fli%3E%3C%2Ful%3E&percent=50
Headers
  • Authorization: Bearer {access_token}
URI Parameters
vehicle_idnumber required

The id of the Vehicle.

1
stateenum required

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%

  • open
  • close
  • comfort
  • vent
  • move
percentnumber optional

The percentage to move the roof to.

50
Response 200 OK
Headers
  • Content-Type: application/json
application/json 
{
  "response": {
    "result": true,
    "reason": ""
  }
}

Remote Start /api/1/vehicles/{vehicle_id}/command/remote_start_drive?password={password}

POST /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.

Request
Example URI
https://owner-api.teslamotors.com/api/1/vehicles/1/command/remote_start_drive?password=edisonsux
Headers
  • Authorization: Bearer {access_token}
URI Parameters
vehicle_idnumber required

The id of the Vehicle.

1
passwordstring required

The password to the authenticated my.teslamotors.com account.

edisonsux
Response 200 OK
Headers
  • Content-Type: application/json
application/json 
{
  "response": {
    "result": true,
    "reason": ""
  }
}

Open Trunk/Frunk /api/1/vehicles/{vehicle_id}/command/trunk_open

POST /api/1/vehicles/{vehicle_id}/command/trunk_open Open Trunk/Frunk

Open the trunk or frunk. Currently inoperable.

Request
Example URI
https://owner-api.teslamotors.com/api/1/vehicles/1/command/trunk_open
Headers
  • Authorization: Bearer {access_token}
URI Parameters
vehicle_idnumber required

The id of the Vehicle.

1
Request object
which_trunkstring

The trunk to open. rear is the only one known currently.

rear
Response 200 OK
Headers
  • Content-Type: application/json
application/json 
{
  "response": {
    "result": true,
    "reason": ""
  }
}