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

This site may earn commission on affiliate links.
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:
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...
 
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.
 
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!
 
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.
 
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).
 
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.
 
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"
 
  • Like
Reactions: Max_G
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.
 
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
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.
 
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.