apiary.apib in tesla_api-1.1.0 vs apiary.apib in tesla_api-1.2.0

- old
+ new

@@ -1,107 +1,118 @@ FORMAT: 1A -HOST: https://portal.vn.teslamotors.com +HOST: https://owner-api.teslamotors.com # Tesla Model S JSON API 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 Flow -These endpoints handle login and session management +# Group Authentication -## GET /login -Returns the login form. Sets a `_s_portal_session` cookie for the session -+ Response 200 +## Tokens [/oauth/token] - + Headers +### 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). - Set-Cookie: _s_portal_session={cookie}; path=/; secure; HttpOnly +Returns a `access_token` which is passed along as a header with all future requests to authenticate the user. - + Body +You must provide the `Authorization: Bearer {access_token}` header in all other requests. - Login Screen HTML +The current client ID and secret are [available here](http://pastebin.com/fX6ejAHd) -## POST /login -Performs the login. Takes in an plain text email and password, matching the owner's login from [http://teslamotors.com/mytesla](http://teslamotors.com/mytesla). ++ Parameters + + 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 -Sets a `user_credentials` cookie that expires in 3 months, which is passed along with all future requests to authenticate the user. ++ Response 200 (application/json) + + Body -Redirects back to a dummy welcome page. This page is ignored by the smartphone app and can be ignored by your API client. -+ Request (application/x-www-form-urlencoded) + { + "access_token": "abc123", + "token_type": "bearer", + "expires_in": 7776000 + } - + Body +# 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. - user_session%5Bemail%5D=string&user_session%5Bpassword%5D=string +## Vehicle Collection [/api/1/vehicles] -+ Response 302 +### List all Vehicles [GET] +Retrieve a list of your owned vehicles (includes vehicles not yet shipped!) ++ Request + Headers - Set-Cookie: _s_portal_session={cookie}; path=/; secure; HttpOnly - Set-Cookie: user_credentials=x; path=/; expires=Fri, 03-May-2013 03:01:54 GMT; secure; HttpOnly - Location: https://portal.vn.teslamotors.com/ + Authorization: Bearer {access_token} - - + Body - - Dummy Welcome Page - - -# Group Vehicle List -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. - -Must have a `_s_portal_session` and `user_credentials` cookie set for all requests. - -## GET /vehicles -Retrieve a list of your owned vehicles (includes vehicles not yet shipped!) + 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 + } -# Group Vehicle Status +## State and Settings [/api/1/vehicles/{vehicle_id}] These resources are read-only and determine the state of the vehicle's various sub-systems. -Must have a `_s_portal_session` and `user_credentials` cookie set for all requests. ++ Parameters -## GET /vehicles/{id}/mobile_enabled + + 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 - + id (number) ... The ID number of the car + + vehicle_id: `1` (number) - The id of the Vehicle. + Response 200 (application/json) + Body { - "reason":"", - "result":true + "response": true } -## GET /vehicles/{id}/command/charge_state +## 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 - + id (number) ... The ID number of the car + + 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 @@ -116,81 +127,113 @@ "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 /vehicles/{id}/command/climate_state +## 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 - + id (number) ... The ID number of the car + + 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 + } } -## GET /vehicles/{id}/command/drive_state +## 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 - + id (number) ... The ID number of the car + + 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 + } } -## GET /vehicles/{id}/command/gui_settings +## 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 - + id (number) ... The ID number of the car + + 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" + } } -## GET /vehicles/{id}/command/vehicle_state +## 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 - + id (number) ... The ID number of the car + + 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 @@ -203,231 +246,466 @@ "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. -Must have a `_s_portal_session` and `user_credentials` cookie set for all requests. +## 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. -## GET /vehicles/{id}/command/charge_port_door_open -Open the charge port. ++ Request + + Headers + + Authorization: Bearer {access_token} + + Parameters - + id (number) ... The ID number of the car + + vehicle_id: `1` (number) - The id of the Vehicle. + Response 200 (application/json) + Body { - "result": false, - "reason": "failure reason" + "response": { + "result": true, + "reason": "" + } } -## GET /vehicles/{id}/command/charge_standard -Set the charge mode to standard (~90% under the new percentage system introduced in 4.5). +## 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 - + id (number) ... The ID number of the car + + 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 { - "result": false, - "reason": "failure reason" + "response": { + "result": true, + "reason": "" + } } -## GET /vehicles/{id}/command/charge_max_range -Set the charge mode to max range (100% under the new percentage system introduced in 4.5). +## 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 - + id (number) ... The ID number of the car + + vehicle_id: `1` (number) - The id of the Vehicle. + Response 200 (application/json) + Body { - "result": false, - "reason": "failure reason" + "response": { + "result": true, + "reason": "" + } } -## GET /vehicles/{id}/command/set_charge_limit?percent={limit_value} +## 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...) + ++ 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 - + id (number) ... The ID number of the car - + limit_value (number) ... The percentage value + + vehicle_id: `1` (number) - The id of the Vehicle. + + limit_value: `75` (number) - The percentage value + Response 200 (application/json) + Body { - "result": false, - "reason": "failure reason" + "response": { + "result": true, + "reason": "" + } } -## GET /vehicles/{id}/command/charge_start -Start charging. +## 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 - + id (number) ... The ID number of the car + + vehicle_id: `1` (number) - The id of the Vehicle. + Response 200 (application/json) + Body { - "result": false, - "reason": "failure reason" // "already started" if a charge is in progress + "response": { + "result": true, + "reason": "" // "already_started" if a charge is in progress + } } -## GET /vehicles/{id}/command/charge_stop -Stop charging. +## Stop Charging [POST /api/1/vehicles/{vehicle_id}/command/charge_stop] +Stop charging. Must already be charging. + ++ Request + + Headers + + Authorization: Bearer {access_token} + + Parameters - + id (number) ... The ID number of the car + + vehicle_id: `1` (number) - The id of the Vehicle. + Response 200 (application/json) + Body { - "result": false, - "reason": "failure reason" // "not_charging" if a charge was not in progress + "response": { + "result": true, + "reason": "" // "not_charging" if a charge was not in progress + } } -## GET /vehicles/{id}/command/flash_lights +## Flash Lights [POST /api/1/vehicles/{vehicle_id}/command/flash_lights] Flash the lights once. + ++ Request + + Headers + + Authorization: Bearer {access_token} + + Parameters - + id (number) ... The ID number of the car + + vehicle_id: `1` (number) - The id of the Vehicle. + Response 200 (application/json) + Body { - "result": false, - "reason": "failure reason" + "response": { + "result": true, + "reason": "" + } } -## GET /vehicles/{id}/command/honk_horn +## Honk Horn [POST /api/1/vehicles/{vehicle_id}/command/honk_horn] Honk the horn once. + ++ Request + + Headers + + Authorization: Bearer {access_token} + + Parameters - + id (number) ... The ID number of the car + + vehicle_id: `1` (number) - The id of the Vehicle. + Response 200 (application/json) + Body { - "result": false, - "reason": "failure reason" + "response": { + "result": true, + "reason": "" + } } -## GET /vehicles/{id}/command/door_unlock +## Unlock Doors [POST /api/1/vehicles/{vehicle_id}/command/door_unlock] Unlock the car's doors. + ++ Request + + Headers + + Authorization: Bearer {access_token} + + Parameters - + id (number) ... The ID number of the car + + vehicle_id: `1` (number) - The id of the Vehicle. + Response 200 (application/json) + Body { - "result": false, - "reason": "failure reason" + "response": { + "result": true, + "reason": "" + } } -## GET /vehicles/{id}/command/door_lock +## Lock Doors [POST /api/1/vehicles/{vehicle_id}/command/door_lock] Lock the car's doors. + ++ Request + + Headers + + Authorization: Bearer {access_token} + + Parameters - + id (number) ... The ID number of the car + + vehicle_id: `1` (number) - The id of the Vehicle. + Response 200 (application/json) + Body { - "result": false, - "reason": "failure reason" + "response": { + "result": true, + "reason": "" + } } -## GET /vehicles/{id}/command/set_temps?driver_temp={driver_degC}&passenger_temp={pass_degC} +## Set Temperature [POST /api/1/vehicles/{vehicle_id}/command/set_temps?driver_temp={driver_degC}&passenger_temp={pass_degC}] Set the temperature target for the HVAC system. + ++ Request + + Headers + + Authorization: Bearer {access_token} + + Parameters - + id (number) ... The ID number of the car - + driver_degC (number) ... The desired temperature on the driver's side in celcius. - + pass_degC (number) ... The desired temperature on the passenger's side in celcius. + + vehicle_id: `1` (number) - The id of the Vehicle. + + driver_degC: `23.7` (number) - The desired temperature on the driver's side in celcius. + + pass_degC: `18.1` (number) - The desired temperature on the passenger's side in celcius. + Response 200 (application/json) + Body { - "result": false, - "reason": "failure reason" + "response": { + "result": true, + "reason": "" + } } -## GET /vehicles/{id}/command/auto_conditioning_start +## Start Air Condition [POST /api/1/vehicles/{vehicle_id}/command/auto_conditioning_start] Start the HVAC system. Will cool or heat automatically, depending on set temperature. + ++ Request + + Headers + + Authorization: Bearer {access_token} + + Parameters - + id (number) ... The ID number of the car + + vehicle_id: `1` (number) - The id of the Vehicle. + Response 200 (application/json) + Body { - "result": false, - "reason": "failure reason" + "response": { + "result": true, + "reason": "" + } } -## GET /vehicles/{id}/command/auto_conditioning_stop +## Stop Air Condition [POST /api/1/vehicles/{vehicle_id}/command/auto_conditioning_stop] Stop the HVAC system. + ++ Request + + Headers + + Authorization: Bearer {access_token} + + Parameters - + id (number) ... The ID number of the car + + vehicle_id: `1` (number) - The id of the Vehicle. + Response 200 (application/json) + Body { - "result": false, - "reason": "failure reason" + "response": { + "result": true, + "reason": "" + } } -## GET /vehicles/{id}/command/sun_roof_control?state={state} +## 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 - + id (number) ... The ID number of the car - + state (string) + + 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% - + Values - + `open` - + `close` - + `comfort` - + `vent` + + 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 { - "result": false, - "reason": "failure reason" + "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. Currently inoperable. + ++ 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` is the only one known currently. + ++ Response 200 (application/json) + + + Body + + { + "response": { + "result": true, + "reason": "" + } }