Using cURL with Lockitron API


#1

Hello all!

I wanted to post this quick guide to help anyone who has questions to interact with the API using cURL.

From Wikipedia:

cURL is a computer software project providing a library and command-line tool for transferring data using various protocols.

Fortunately, using it is pretty easy! If you’ve got a Mac or Linux system, cURL should already be available at your command line. If not, check out the official download page.


##Steps

  1. Go to http://api.lockitron.com and Login at the top right.

  2. After logging in, scroll down and make note of the Access Token. You will need this later on.

  3. Further down the page, there’s the option to Retrieve All Locks. On the right side, it will have the “Example Request”. Click on that, and it will bring up a page of text listing all current locks on your account.
    It will have a section starting with [{“id”:"9999… Make note of the full Lock ID.

  4. Open your Terminal/Command Line, and when you’re at the prompt, you should be able to enter something like the following:

curl -X PUT -d argument=value https://api.lockitron.com/v2/locks/LOCK_ID_GOES_HERE?access_token=YOUR_ACCESS_TOKEN


##Practical Examples

In the example above, argument is any of the methods described on the Lockitron API Reference.

A practical example, to “toggle” the state of a lock, would be to use:

curl -X PUT -d state=toggle https://api.lockitron.com/v2/locks/LOCK_ID_GOES_HERE?access_token=YOUR_ACCESS_TOKEN

This command would toggle the state of the lock, so if it is locked, it becomes unlocked. If it is unlocked, it becomes locked.

Another argument commonly used is sleep_period, which the reference defines as a value that you can set between 0 and 86400 seconds.
For example, if I wished to set my Lockitron v2 sleep interval to 12 hours, I could use:

curl -X PUT -d sleep_period=43200 https://api.lockitron.com/v2/locks/LOCK_ID_GOES_HERE?access_token=YOUR_ACCESS_TOKEN


##API Features and Compatibility

###Bolt
For Bolt users, you must have Bridge to carry out any of the remote API commands.
As Bridge is powered separately from the lock, any command you execute will run almost instantly, provided it is working correctly.
Even further, for Bolt users, it is not possible to use the API to Update Firmware, or update the Sleep Period (there is none with Bridge). At the time of writing, it is also not possible for you to change handedness remotely.

###Crowdfunded Lockitron/v2
At the time of writing, all API methods are available. Note that your lock must be online for any of them to take effect. For example, you could send an unlock command, but unless your lock is connected to Wi-Fi at that moment, it will not execute.

###Lockitron v1, Lockitron Access
At the time of writing, most API methods are available, with the exception of Sleep Period. Other exceptions are as noted (see reference).


Connectivity issues
#2

@anthonylavado awesome write up, thank you! All the APIs work with the Lockitron v1 and Lockitron Access unless noted in the documentation (i.e. sleep period which doesn’t factor in).


#3

Thank you Anthony!:slight_smile:


#4

Why the lack of control over sleep period? I just executed the command line in bash and the error message said lack of authentication. I have a Crowdfunded lock. Que sera sera?


#5

@Nick: I see you’ve got some communication with @cameron in another thread. Once that’s all updated and squared away, we can look closer at this lack of authentication error.

Best thing I can think of - you might need to allow access with your authentication code. Read and follow this section of the API page: https://api.lockitron.com/#auth_code

Specifically, the last line where it says “visit the Authentication URL”.


#6

Thanks for the quick response!


#7

Adding this to the guide - you can also send the access_token via headers, not only as a param:

http://community.lockitron.com/t/500-error-on-api-v1-locks-oauth-solved/817/3


#8

I’m reviving this older topic…

This is a great guide; thank you @anthonylavado.

Unfortunately, it didn’t quite work for me. I can retreive my ID and access-token just fine. The problem is that when I send the curl command to toggle the state, I get back a result that looks like it worked but the lock never actually locks or unlocks.

Here’s an example of a result I get back. This was issued when the lock was locked.

{"id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name":"xxxxxxx","state":"unlock","connected":true,"button_type":"slider","last_heard_from":null,"last_online":"2017-10-12T21:45:07Z","last_offline":null,"next_wake":null}

If I issue the curl command to toggle the lock again, the result is:

{"id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","name":"xxxxxxx","state":"lock","connected":true,"button_type":"slider","last_heard_from":null,"last_online":"2017-10-12T21:46:16Z","last_offline":null,"next_wake":null}

Note that the state has switched from unlock to lock as if it had done something. However, the lock remains silent.

The same thing happens if I use the lockitron_bash script found in this thread Found Online: Lockitron bash script from @zero_divide_1.

My lock is a Bolt, and yes I have a Bridge which is connected. Using the lockitron android app (from wifi) works fine at the same time.

Does this curl method not work with Bolt/Bridge?

Thanks,

–Jim–


#9

@jjd are you seeing any other issues sending commands to the lock via Bridge (i.e. from your phone)? Does this response come through immediately?


#10

@cameron Oherwise seems to work just fine via Bridge. Phone commands work immediately when not connected via bluetooth.


#11

Ok, I’m slightly embarrassed that I’m an idiot here, though I would argue that the guide above caused me to be confused.

The problem was that I had both the lock id and the access_token incorrect.

I had them incorrect because the guide above said “scroll down and make note of the Access Token. You will need this later.”

I thought this meant that that was my access token. I had reason to believe this because (a) I was required to log into api.lockitron.com with my credentials and (b) other OAuth-type sites that have similar documentation sites do actually provide your personal access token in their site. Facebook has (had?) a api console like this.

So I had been issuing successful commands against some random virtual lock I suppose.

Sorry for my confusion. I have subsequently acquired my actual access token and lock id and the API works fine via curl.


#12

… and now I see that the api.lockitron.com page can, in fact, show my personal access_token and lock id. I’m not sure why it didn’t before – I know I logged in properly – but it wasn’t showing my personal data, just some generic data. So that remains a confusion, but at least I understand why the guide above says what it says.


#13

Thanks for the feedback - I should revise it to be a little clearer.
I forget if signing in automatically generates a Virtual lock for you or not. At any rate, I’ll clarify to look for the correct entry in Step 3.