Welcome to Tesla Motors Club
Discuss Tesla's Model S, Model 3, Model X, Model Y, Cybertruck, Roadster and More.
Register

Model S REST API

timdorr

Model S P90D w/AP3.0
Aug 2, 2012
468
75
Atlanta, Georgia, United States
I've created an Apiary.io page and Github repo for tracking the documentation of the API:

http://docs.timdorr.apiary.io/
https://github.com/timdorr/model-s-api

I'd like some help with this. If you'd like to sniff the traffic of the Model S app, you can use Fiddler and your phone on your local wifi network using these instructions: Fiddler Web Debugger - Configuring Google Nexus 7 running Android 4.1 That will work for any Android 4.1 or higher device, with the exception of some manufacturers that have customized the interface very heavily. It may still be possible to install the Fiddler CA cert, but you'll have to figure that out on your own. Same goes for older versions of Android.

I still need to list out the remaining API endpoints and document the return values. The syntax for Apiary is fairly simple, so if you can do Github Markdown, you can handle this system. Feel free to fork and submit pull requests and I'll merge in stuff whenever I can. The biggest thing missing is the authentication flow, which I don't know if that's OAuth or something else (it doesn't look OAuth, though).

My hope is that we can build some cool apps out of this for our smartphones and for the web. For example, we could build a Windows Phone app (which is being worked on) or an Android widget. Or you could build web service to turn on the climate control at set times or after certain triggers. There are tons of possibilities here and I'm really excited to see what people can think up. REST means the API is easy to use and friendly, so there should be lots of us able to produce something against the API.

Update 11/12/13:

Sorry for going silent for a while. I'm going to try and document any new and hidden endpoints that are found, but I'd appreciate some help if you see any missing. The best option is to submit a pull request on Github. You can also PM me here, though I may take a while to respond.

I'm also going to include a nice little HTTParty class for all you Rubyists out there that makes interacting with the API pretty simple. I'll throw that into the API repo on Github.
 
Last edited:

PureAmps

Model S P85 (#2817)
Oct 22, 2012
359
7
SF Bay Area
Tim, thanks for taking the initiative and setting this up. I'd be happy to contribute once the iOS app is available (of course, at the rate you are going you may be finished by then).

In addition to Fiddler, another commonly used SSL proxy with auto-cert generation is mitmproxy (mitmproxy - home). Their documentation provides info on how to configure for iOS devices as well as Android.

As far as authentication, was there an HTTP Authentication header sent with each request? Maybe they are just using cookies...

I am really hoping for OAuth, as they could eventually extend the "My Tesla" page to support 3rd party web/mobile apps, without requiring the vehicle owner to give out their username/password. Maybe Tesla hasn't thought that far ahead yet...
 

dmetcalf

S258
Jun 2, 2012
132
13
Merritt Island, FL
Thanks Tim. This is cool. Let me know by PM if you need some testers. I am letting some of my programming students have limited access to test Web apps so far and may let them go deeper if promising apps emerge.
 

ahimberg

Member
Aug 8, 2010
349
0
Woodinville, WA
The Auth is in form post format that sets cookies back on the client. I haven't monitored enough to know first login vs subsequent app launch is handled though -- what cookies their client is saving between sessions as its not resending user/pw each time.
 

timdorr

Model S P90D w/AP3.0
Aug 2, 2012
468
75
Atlanta, Georgia, United States
Updated the docs with the authentication flow. Looks like it needs both a _s_portal_session and user_credentials cookie set. I haven't seen if the _s_portal_session is completely necessary, but I'm guessing it will be.

I also added some session logs to the github repo (hid my passwords, of course), if anyone wants to take a look. The root return is interesting because there's a telltale sign of a Rails app (the javascript is in an assets folder). I assume they're up to date on their Rails patches, but I'll make sure they're not susceptible to the YAML bug most recently. Definitely don't want people messing around with our cars or Tesla's systems!
 

markwj

Moderator, Asia Pacific
Apr 10, 2011
4,597
1,207
Hong Kong
I've been interested in the possible use of OVMS Apps to control multiple cars of different types - not necessarily just with OVMS modules. This allows us to extend the manufacturer's offering, and is real nice for those with more than one car in their garage. OVMS has received literally dozens of request for such support.

GM/OnStar now have a published API (although are not permitting this to be used against real cars until late 2013).

The Leaf carwings API has been reverse engineered.

Now, you guys are reverse engineering the Tesla Model S RESTfull API.

Perhaps the neatest way of doing this is by gatewaying at the server - no change to Apps necessary. But, I worry that the providers will rate limit requests from a single IP. Doing it at the server allows for all sorts of cool stuff (e.g.; timed pre-heat).

We could also do this in the Apps themselves.

But, my question is what is the legality of this? I suspect that it would be a contravention of the DMCA? I read that GM/OnStar stopped (or persuaded to stop) the VoltStats guy to stop - and he is now using a very restricted API just for him. What about Nissan? I guess the legalities of doing the reverse engineering vs using fruits of such work are different.

Looking at the Model S API, it would be about an evening's work to do a server gateway. Scarily simple. I don't have the car (yet), but if someone (presumably an OVMS roadster owner who also has a Model S) wants to work with me on a proof-of-concept for this, I'm more than willing to give it a go.
 

AnOutsider

S532 # XS27
Apr 3, 2009
11,957
200
Cool. I now have a charge timer that I wrote in 5 minutes, using curl and cron.

Heh, makes you wonder why it's not in the app. Though, I guess it wouldn't be as reliable (app isn't running to send the commands or car isn't in reception)
 

Jason S

Model S Sig Perf (P85)
Apr 20, 2012
1,590
208
Rocklin, CA
Cool. I now have a charge timer that I wrote in 5 minutes, using curl and cron.
Since charging starts when you plug it in, I imagine you'd have two parts --
When you want it off -- every 5 minutes (15, w/e, just so you aren't spamming the auth) you tell it to start charging.
When you want it on -- tell it to turn on and check once or twice later on the status.

You'll hafta remember to turn off the cron job when away from home, or you make the script location aware if that's available via the API (I think it is).
 

aviators99

Model S - R140
Jan 1, 2010
1,463
10
Weston, Florida, United States
Since charging starts when you plug it in, I imagine you'd have two parts --
When you want it off -- every 5 minutes (15, w/e, just so you aren't spamming the auth) you tell it to start charging.
When you want it on -- tell it to turn on and check once or twice later on the status.

You'll hafta remember to turn off the cron job when away from home, or you make the script location aware if that's available via the API (I think it is).

Well, I haven't actually tested it yet, but if you "stop charging" (either from the app/API or from the car), it won't start up again until it's told to "start charging". So you shouldn't need to do anything every 5 minutes.

- - - Updated - - -

Aviators,

How did you do the auth part?

I did it as described in the documentation linked in the OP. I made use of the '-c' and '--cookie' options for curl.
 

Banahogg

Member
Jan 22, 2013
293
1
San Jose, CA
I don't have my car yet to fully test, but using basic HTTP authentication (curl -u) can distinguish between correct and incorrect passwords and appears to correctly return an empty vehicle list for my account from that endpoint.
 

widodh

Model S 85 and 100D
Jan 23, 2011
6,853
2,771
Venlo, NL
But, my question is what is the legality of this? I suspect that it would be a contravention of the DMCA? I read that GM/OnStar stopped (or persuaded to stop) the VoltStats guy to stop - and he is now using a very restricted API just for him. What about Nissan? I guess the legalities of doing the reverse engineering vs using fruits of such work are different.
Why? We are just doing HTTP requests to the Tesla servers.

They are just the same requests as the App would do. What is not legal about doing those HTTP requests as long as you are not hammering the servers?

Maybe reverse-engineering is forbidden in the US, but is it reverse engineering? You are just looking at the HTTP traffic your phone is doing.

If Tesla would sue somebody I'd be angry at them, then they are showing that they aren't different at all. Then they would be whining about nothing. I just see cool potential for customers to control their car in cool ways.

Log data about the location, energy usage, etc, etc. Super cool stuff! They should even help us with this and give hints. Even better, place the API documentation online at something like "developers.teslamotors.com"
 

brianman

Burrito Founder
Nov 10, 2011
17,519
2,984
Why? We are just doing HTTP requests to the Tesla servers.

They are just the same requests as the App would do. What is not legal about doing those HTTP requests as long as you are not hammering the servers?

Maybe reverse-engineering is forbidden in the US, but is it reverse engineering? You are just looking at the HTTP traffic your phone is doing.

If Tesla would sue somebody I'd be angry at them, then they are showing that they aren't different at all. Then they would be whining about nothing. I just see cool potential for customers to control their car in cool ways.

Log data about the location, energy usage, etc, etc. Super cool stuff! They should even help us with this and give hints. Even better, place the API documentation online at something like "developers.teslamotors.com"
IMO, technically it is reverse engineering. I doubt Tesla will have issue with this particular flavor of it though. Disassembling your car physically and/or electrically is more what they're worried about in the legal sense, I think.
 

PureAmps

Model S P85 (#2817)
Oct 22, 2012
359
7
SF Bay Area
A quick note on using the API. The id to use when issuing vehicle commands is the "id" field from the vehicles JSON response, not the "vehicle_id" field. It took me a bit to figure that out, since I haven't been able to record any traffic from the actual app, it wasn't obvious what the problem was. I have everything working now. :)
 
  • Informative
Reactions: JerryEVall

gg_got_a_tesla

Model S: VIN 65513, Model 3: VIN 1913
Jan 29, 2010
6,533
769
Redwood Shores, CA
Would it be a good idea to put together a simple .war or equivalent with a web frontend? We could distribute the war around here and folks can deploy in a container on their home machines if not host it publicly. My UI/UX skills are rusty but, I'll work on this too.
 

PureAmps

Model S P85 (#2817)
Oct 22, 2012
359
7
SF Bay Area
IMO, technically it is reverse engineering. I doubt Tesla will have issue with this particular flavor of it though. Disassembling your car physically and/or electrically is more what they're worried about in the legal sense, I think.

I agree, I don't think Tesla is that concerned about reverse engineering their mobile app's API. The legal issue here is not so much about reverse engineering, but Tesla's terms of service for their web app that is supporting the mobile apps. I don't have the mobile app yet, so I don't know if there is an accompanying "click wrap" license. But if they state that the API may only be accessed via their application, then you would be in violation of their terms of use. They have a simple remedy, which would be to just disable your account.

Until I hear otherwise, I'm treating this as an "ask forgiveness" opportunity. :) But I hope anyone using the API would be careful to not create headaches for Tesla (for example too many API requests, etc.) that could quickly bring this little "experiment" to an end.
 

About Us

Formed in 2006, Tesla Motors Club (TMC) was the first independent online Tesla community. Today it remains the largest and most dynamic community of Tesla enthusiasts. Learn more.

Do you value your experience at TMC? Consider becoming a Supporting Member of Tesla Motors Club. As a thank you for your contribution, you'll get nearly no ads in the Community and Groups sections. Additional perks are available depending on the level of contribution. Please visit the Account Upgrades page for more details.


SUPPORT TMC
Top