apiary.apib

FORMAT: 1A
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

## 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...)

+ 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_degC}&passenger_temp={pass_degC}]
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_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

            {
              "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. 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": ""
              }
            }