Table of Contents

    API

    Transparent Proxy

    Please sign in and we'll assign you a private URL to trace your traffic and help you implement the API.

Tesla Model S REST API

This is unofficial documentation of the Tesla Model S REST API used by the iOS and Android apps. It features functionality to monitor and control the Model S remotely.

Authentication Flow

These endpoints handle login and session management

GET

/login

Returns the login form. Sets a _s_portal_session cookie for the session

Response

200 (OK)
Set-Cookie: _s_portal_session={cookie}; path=/; secure; HttpOnly
Login Screen HTML

POST

/login

Performs the login. Takes in an plain text email and password, matching the owner's login from http://teslamotors.com/mytesla.

Sets a user_credentials cookie that expires in 3 months, which is passed along with all future requests to authenticate the user.

Redirects back to a dummy welcome page. This page is ignored by the smartphone app and can be ignored by your API client.

Response

302 (Found)
Location: https://portal.vn.teslamotors.com/
Set-Cookie: user_credentials=x; path=/; expires=Fri, 03-May-2013 03:01:54 GMT; secure; HttpOnly
Dummy Welcome Page

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 (OK)
Content-Type: application/json
[{
    "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"
}]

Vehicle Status

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.

GET

/vehicles/{id}/mobile_enabled

Determines if mobile access to the vehicle is enabled.

Parameters
Name Description Details
id

The ID number of the car

number, required

Response

200 (OK)
Content-Type: application/json
{
    "reason":"",
    "result":true
}

GET

/vehicles/{id}/command/charge_state

Returns the state of charge in the battery.

Parameters
Name Description Details
id

The ID number of the car

number, required

Response

200 (OK)
Content-Type: application/json
{
    "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

/vehicles/{id}/command/climate_state

Returns the current temperature and climate control state.

Parameters
Name Description Details
id

The ID number of the car

number, required

Response

200 (OK)
Content-Type: application/json
{
    "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

Returns the driving and position state of the vehicle.

Parameters
Name Description Details
id

The ID number of the car

number, required

Response

200 (OK)
Content-Type: application/json
{
    "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

Returns various information about the GUI settings of the car, such as unit format and range display.

Parameters
Name Description Details
id

The ID number of the car

number, required

Response

200 (OK)
Content-Type: application/json
{
    "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

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

Parameters
Name Description Details
id

The ID number of the car

number, required

Response

200 (OK)
Content-Type: application/json
{
    "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.

Must have a _s_portal_session and user_credentials cookie set for all requests.

GET

/vehicles/{id}/command/charge_port_door_open

Open the charge port.

Parameters
Name Description Details
id

The ID number of the car

number, required

Response

200 (OK)
Content-Type: application/json
{
  "result": false,
  "reason": "failure reason"
}

GET

/vehicles/{id}/command/charge_standard

Set the charge mode to standard (~90% under the new percentage system introduced in 4.5).

Parameters
Name Description Details
id

The ID number of the car

number, required

Response

200 (OK)
Content-Type: application/json
{
  "result": false,
  "reason": "failure 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).

Parameters
Name Description Details
id

The ID number of the car

number, required

Response

200 (OK)
Content-Type: application/json
{
  "result": false,
  "reason": "failure reason"
}

GET

/vehicles/{id}/command/set_charge_limit?percent={limit_value}

Set the charge limit to a custom percentage.

Parameters
Name Description Details
id

The ID number of the car

number, required
limit_value

The percentage value

number, required

Response

200 (OK)
Content-Type: application/json
{
  "result": false,
  "reason": "failure reason"
}

GET

/vehicles/{id}/command/charge_start

Start charging.

Parameters
Name Description Details
id

The ID number of the car

number, required

Response

200 (OK)
Content-Type: application/json
{
  "result": false,
  "reason": "failure reason" // "already started" if a charge is in progress
}

GET

/vehicles/{id}/command/charge_stop

Stop charging.

Parameters
Name Description Details
id

The ID number of the car

number, required

Response

200 (OK)
Content-Type: application/json
{
  "result": false,
  "reason": "failure reason" // "not_charging" if a charge was not in progress
}

GET

/vehicles/{id}/command/flash_lights

Flash the lights once.

Parameters
Name Description Details
id

The ID number of the car

number, required

Response

200 (OK)
Content-Type: application/json
{
  "result": false,
  "reason": "failure reason"
}

GET

/vehicles/{id}/command/honk_horn

Honk the horn once.

Parameters
Name Description Details
id

The ID number of the car

number, required

Response

200 (OK)
Content-Type: application/json
{
  "result": false,
  "reason": "failure reason"
}

GET

/vehicles/{id}/command/door_unlock

Unlock the car's doors.

Parameters
Name Description Details
id

The ID number of the car

number, required

Response

200 (OK)
Content-Type: application/json
{
  "result": false,
  "reason": "failure reason"
}

GET

/vehicles/{id}/command/door_lock

Lock the car's doors.

Parameters
Name Description Details
id

The ID number of the car

number, required

Response

200 (OK)
Content-Type: application/json
{
  "result": false,
  "reason": "failure reason"
}

GET

/vehicles/{id}/command/set_temps?driver_temp={driver_degC}&passenger_temp={pass_degC}

Set the temperature target for the HVAC system.

Parameters
Name Description Details
id

The ID number of the car

number, required
driver_degC

The desired temperature on the driver's side in celcius.

number, required
pass_degC

The desired temperature on the passenger's side in celcius.

number, required

Response

200 (OK)
Content-Type: application/json
{
  "result": false,
  "reason": "failure reason"
}

GET

/vehicles/{id}/command/auto_conditioning_start

Start the HVAC system. Will cool or heat automatically, depending on set temperature.

Parameters
Name Description Details
id

The ID number of the car

number, required

Response

200 (OK)
Content-Type: application/json
{
  "result": false,
  "reason": "failure reason"
}

GET

/vehicles/{id}/command/auto_conditioning_stop

Stop the HVAC system.

Parameters
Name Description Details
id

The ID number of the car

number, required

Response

200 (OK)
Content-Type: application/json
{
  "result": false,
  "reason": "failure reason"
}

GET

/vehicles/{id}/command/sun_roof_control?state={state}

Controls the car's panoramic roof, if installed.

Parameters
Name Description Details
id

The ID number of the car

number, required
state

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%

string, required
Possible values:
  • open
  • close
  • comfort
  • vent

Response

200 (OK)
Content-Type: application/json
{
  "result": false,
  "reason": "failure reason"
}