FORMAT: 1A HOST: https://owner-api.teslamotors.com # Tesla Model S JSON API # ⚠️ ⚠️ ⚠️ ⚠️ # This site has moved! [https://tesla-api.timdorr.com/](https://tesla-api.timdorr.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. # Group Authentication ## Tokens [/oauth/token] ### Get an Access Token [POST] Performs the login. Takes in an plain text email and password, matching the owner's login information for [https://my.teslamotors.com/user/login](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](http://pastebin.com/YiLPDggh) + Attributes + grant_type: `password` (string) - The type of oAuth grant. Always "password" + client_id: `abc` (string) - The oAuth client ID + client_secret: `123` (string) - The oAuth client secret + email: `elon@teslamotors.com` (string) - The email for my.teslamotors.com + password: `edisonsux` (string) - The password for my.teslamotors.com + Response 200 (application/json) + Body { "access_token": "abc123", "token_type": "bearer", "expires_in": 7776000, "created_at": 1457385291, "refresh_token" : "cba321" } # Group 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] ### List all Vehicles [GET] Retrieve a list of your owned vehicles (includes vehicles not yet shipped!) + Request + Headers Authorization: Bearer {access_token} + Response 200 (application/json) + Body { "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. + Parameters + vehicle_id: `1` (number) - The id of the Vehicle. ## Mobile Access [GET /api/1/vehicles/{vehicle_id}/mobile_enabled] Determines if mobile access to the vehicle is enabled. + Request + Headers Authorization: Bearer {access_token} + Parameters + vehicle_id: `1` (number) - The id of the Vehicle. + Response 200 (application/json) + Body { "response": true } ## Charge State [GET /api/1/vehicles/{vehicle_id}/data_request/charge_state] Returns the state of charge in the battery. + Request + Headers Authorization: Bearer {access_token} + Parameters + vehicle_id: `1` (number) - The id of the Vehicle. + Response 200 (application/json) + Body { "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 } } ## Climate Settings [GET /api/1/vehicles/{vehicle_id}/data_request/climate_state] Returns the current temperature and climate control state. + Request + Headers Authorization: Bearer {access_token} + Parameters + vehicle_id: `1` (number) - The id of the Vehicle. + Response 200 (application/json) + Body { "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 } } ## Driving and Position [GET /api/1/vehicles/{vehicle_id}/data_request/drive_state] Returns the driving and position state of the vehicle. + Request + Headers Authorization: Bearer {access_token} + Parameters + vehicle_id: `1` (number) - The id of the Vehicle. + Response 200 (application/json) + Body { "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 } } ## GUI Settings [GET /api/1/vehicles/{vehicle_id}/data_request/gui_settings] Returns various information about the GUI settings of the car, such as unit format and range display. + Request + Headers Authorization: Bearer {access_token} + Parameters + vehicle_id: `1` (number) - The id of the Vehicle. + Response 200 (application/json) + Body { "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" } } ## Vehicle State [GET /api/1/vehicles/{vehicle_id}/data_request/vehicle_state] Returns the vehicle's physical state, such as which doors are open. + Request + Headers Authorization: Bearer {access_token} + Parameters + vehicle_id: `1` (number) - The id of the Vehicle. + Response 200 (application/json) + Body { "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" } } # Group 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 [POST /api/1/vehicles/{vehicle_id}/wake_up] Wakes up the car from the sleep state. Necessary to get some data from the car. + Request + Headers Authorization: Bearer {access_token} + Parameters + vehicle_id: `1` (number) - The id of the Vehicle. + Response 200 (application/json) + Body { "response": { "result": true, "reason": "" } } ## Set Valet Mode [POST /api/1/vehicles/{vehicle_id}/command/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 + Headers Authorization: Bearer {access_token} + Parameters + vehicle_id: `1` (number) - The id of the Vehicle. + on: true (boolean) - Whether to enable or disable valet mode. + password: 1234 (number) - (optional) A 4 digit PIN code to unlock the car. + Response 200 (application/json) + Body { "response": { "result": true, "reason": "" } } ## Reset Valet PIN [POST /api/1/vehicles/{vehicle_id}/command/reset_valet_pin] Resets the PIN set for valet mode, if set. + Request + Headers Authorization: Bearer {access_token} + Parameters + vehicle_id: `1` (number) - The id of the Vehicle. + Response 200 (application/json) + Body { "response": { "result": true, "reason": "" } } ## Open Charge Port [POST /api/1/vehicles/{vehicle_id}/command/charge_port_door_open] Opens the charge port. Does not close the charge port (for now...). This endpoint also unlocks the charge port if it's locked. + Request + Headers Authorization: Bearer {access_token} + Parameters + vehicle_id: `1` (number) - The id of the Vehicle. + Response 200 (application/json) + Body { "response": { "result": true, "reason": "" } } ## Set Charge Limit to Standard [POST /api/1/vehicles/{vehicle_id}/command/charge_standard] Set the charge mode to standard (90% under the new percentage system introduced in 4.5). + Request + Headers Authorization: Bearer {access_token} + Parameters + vehicle_id: `1` (number) - The id of the Vehicle. + Response 200 (application/json) + Body { "response": { "result": false, "reason": "already_standard" } } ## Set Charge Limit to Max Range [POST /api/1/vehicles/{vehicle_id}/command/charge_max_range] Set the charge mode to max range (100% under the new percentage system introduced in 4.5). Use sparingly! + Request + Headers Authorization: Bearer {access_token} + Parameters + vehicle_id: `1` (number) - The id of the Vehicle. + Response 200 (application/json) + Body { "response": { "result": false, "reason": "already_max_range" } } ## Set Charge Limit [POST /api/1/vehicles/{vehicle_id}/command/set_charge_limit?percent={limit_value}] Set the charge limit to a custom percentage. + Request + Headers Authorization: Bearer {access_token} + Parameters + vehicle_id: `1` (number) - The id of the Vehicle. + limit_value: `75` (number) - The percentage value + Response 200 (application/json) + Body { "response": { "result": true, "reason": "" } } ## Start Charging [POST /api/1/vehicles/{vehicle_id}/command/charge_start] Start charging. Must be plugged in, have power available, and not have reached your charge limit. + Request + Headers Authorization: Bearer {access_token} + Parameters + vehicle_id: `1` (number) - The id of the Vehicle. + Response 200 (application/json) + Body { "response": { "result": true, "reason": "" // "already_started" if a charge is in progress } } ## Stop Charging [POST /api/1/vehicles/{vehicle_id}/command/charge_stop] Stop charging. Must already be charging. + Request + Headers Authorization: Bearer {access_token} + Parameters + vehicle_id: `1` (number) - The id of the Vehicle. + Response 200 (application/json) + Body { "response": { "result": true, "reason": "" // "not_charging" if a charge was not in progress } } ## Flash Lights [POST /api/1/vehicles/{vehicle_id}/command/flash_lights] Flash the lights once. + Request + Headers Authorization: Bearer {access_token} + Parameters + vehicle_id: `1` (number) - The id of the Vehicle. + Response 200 (application/json) + Body { "response": { "result": true, "reason": "" } } ## Honk Horn [POST /api/1/vehicles/{vehicle_id}/command/honk_horn] Honk the horn once. + Request + Headers Authorization: Bearer {access_token} + Parameters + vehicle_id: `1` (number) - The id of the Vehicle. + Response 200 (application/json) + Body { "response": { "result": true, "reason": "" } } ## Unlock Doors [POST /api/1/vehicles/{vehicle_id}/command/door_unlock] Unlock the car's doors. + Request + Headers Authorization: Bearer {access_token} + Parameters + vehicle_id: `1` (number) - The id of the Vehicle. + Response 200 (application/json) + Body { "response": { "result": true, "reason": "" } } ## Lock Doors [POST /api/1/vehicles/{vehicle_id}/command/door_lock] Lock the car's doors. + Request + Headers Authorization: Bearer {access_token} + Parameters + vehicle_id: `1` (number) - The id of the Vehicle. + Response 200 (application/json) + Body { "response": { "result": true, "reason": "" } } ## Set Temperature [POST /api/1/vehicles/{vehicle_id}/command/set_temps?driver_temp={driver_temp}&passenger_temp={passenger_temp}] Set the temperature target for the HVAC system. + Request + Headers Authorization: Bearer {access_token} + Parameters + vehicle_id: `1` (number) - The id of the Vehicle. + driver_temp: `23.7` (number) - The desired temperature on the driver's side in celcius. + passenger_temp: `18.1` (number) - The desired temperature on the passenger's side in celcius. + Response 200 (application/json) + Body { "response": { "result": true, "reason": "" } } ## Start HVAC System [POST /api/1/vehicles/{vehicle_id}/command/auto_conditioning_start] Start the climate control system. Will cool or heat automatically, depending on set temperature. + Request + Headers Authorization: Bearer {access_token} + Parameters + vehicle_id: `1` (number) - The id of the Vehicle. + Response 200 (application/json) + Body { "response": { "result": true, "reason": "" } } ## Stop HVAC System [POST /api/1/vehicles/{vehicle_id}/command/auto_conditioning_stop] Stop the climate control system. + Request + Headers Authorization: Bearer {access_token} + Parameters + vehicle_id: `1` (number) - The id of the Vehicle. + Response 200 (application/json) + Body { "response": { "result": true, "reason": "" } } ## Move Pano Roof [POST /api/1/vehicles/{vehicle_id}/command/sun_roof_control?state={state}&percent={percent}] Controls the car's panoramic roof, if installed. + Request + Headers Authorization: Bearer {access_token} + Parameters + vehicle_id: `1` (number) - The id of the Vehicle. + state: `open` (enum[string]) 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% + Members + `open` - Open the roof fully + `close` - Close the roof completely + `comfort` - Open to the comfort (80%) setting + `vent` - Open the roof to the vent (~15%) setting + `move` - Indicates you will provide a percentage to move the roof. + percent: `50` (number, optional) - The percentage to move the roof to. + Response 200 (application/json) + Body { "response": { "result": true, "reason": "" } } ## Remote Start [POST /api/1/vehicles/{vehicle_id}/command/remote_start_drive?password={password}] Start the car for keyless driving. Must start driving within 2 minutes of issuing this request. + Request + Headers Authorization: Bearer {access_token} + Parameters + vehicle_id: `1` (number) - The id of the Vehicle. + password: `edisonsux` (string) - The password to the authenticated my.teslamotors.com account. + Response 200 (application/json) + Body { "response": { "result": true, "reason": "" } } ## Open Trunk/Frunk [POST /api/1/vehicles/{vehicle_id}/command/trunk_open] Open the trunk or frunk. Call the endpoint again to close (this only works on rear powered trunks) + Request + Headers Authorization: Bearer {access_token} + Parameters + vehicle_id: `1` (number) - The id of the Vehicle. + which_trunk: `rear` (string) - The trunk to open. `rear` and `front` are the only options + Response 200 (application/json) + Body { "response": { "result": true, "reason": "" } }