docs.pushbullet.comPushbullet API

APPS CHANNELS BLOG API HELP Pushbullet's API enables developers to build on the Pushbullet infrastructure. Our goal is to provide a full API that enables anything to tap into the Pushbullet network. This is important to us because we believe everything, not just smartphones and computers, should be able to exchange information in real time. Here are some of the things you can build with Pushbullet: Have a website and want to offer push notifications? We've built everything you need. Want to build a Pushbullet client for a platform we don't officially support yet? Everything you need is here. Working on a home automation system? Pushbullet can get everything chatting. Working with sensors and want to send messages to another device? Pushbullet is just what you need. Manage IT/servers and want to get updates and alerts no matter where you are or what device you're using? Pushbullet makes it easy. Check out this ProgrammableWeb article for a longer introduction to Pushbullet and this API . Sections API - Send/receive pushes using the Pushbullet server. Changelog - Recent changes to the API. Problems/Feedback If you have questions, feel free to post them to the pushbullet tag on Stack Overflow . We monitor this tag and will reply as quickly as we can. For everything else (including incorrect things or suggested changes to these docs) feel free to contact us at [email protected] . API Quick Start All of our examples use the curl command line tool already available on most systems. If you use Mac, it should already be installed, just open the Terminal app and run it. If you are using Linux, it should already be installed, just open the Console and run it. On Windows you're going to have to download it here or from the curl download page . The lets you send/receive pushes and do everything else the official Pushbullet clients can do. To access the API you'll need an access token so the server knows who you are. You can get one from your Account Settings page. Once you have that access token, you can use it to access your Pushbullet account using the : Example: Get Current User Request curl --header 'Access-Token: <your_access_token_here>' \ https://api.pushbullet.com/v2/users/me Response { "created" : 1381092887.398433 , "email" : " [email protected] " , "email_normalized" : " [email protected] " , "iden" : "ujpah72o0" , "image_url" : "https://static.pushbullet.com/missing-image/55a7dc-45" , "max_upload_size" : 26214400 , "modified" : 1441054560.741007 , "name" : "Elon Musk" } API Overview Requests The API accepts requests over HTTPS at https://api.pushbullet.com . All POST requests must use a JSON body with the Content-Type header set to application/json . Most programming languages have some way to encoded objects to JSON, and using the built-in library is recommended, since it will correctly handle newline characters and quotes. Authentication To authenticate for the API, use your access token in a header like Access-Token: <your_access_token_here> . Your access token can be found on the Account Settings page. Keep in mind that this key has full access to your account, so don't go posting it all over the internets. If you are making an app that uses the on behalf of another user (for instance, to send push notifications as that user), use OAuth to get an access token for that user. Using your own access token while developing though saves you from having to setup OAuth until later. You can make a request from any app, though how you do that may depend on if you are writing a script or using a programming language. If you have a terminal and the curl utility you can perform requests from the command line. Example: Get Current User Request curl --header 'Access-Token: <your_access_token_here>' \ https://api.pushbullet.com/v2/users/me Response { "created" : 1381092887.398433 , "email" : " [email protected] " , "email_normalized" : " [email protected] " , "iden" : "ujpah72o0" , "image_url" : "https://static.pushbullet.com/missing-image/55a7dc-45" , "max_upload_size" : 26214400 , "modified" : 1441054560.741007 , "name" : "Elon Musk" } Because we allow CORS requests, you can make a request from any browser (you can hit the run button or copy and paste this code into your javascript console): Responses Responses are always JSON . Keys are either present with a non-empty value, or entirely absent from the response. Empty values are: null , false , "" , [] , and {} . Deleted objects will only have the keys iden , active , created , and modified because all other properties have been removed and are now empty values. Example: API Response { "created" : 1357941753.82879 , "email" : " [email protected] " , "email_normalized" : " [email protected] " , "iden" : "ujpah72o0sjAoRtnM0jc" , "modified" : 1399325992.18423 } HTTP Status Codes 200 OK - Everything worked as expected. 400 Bad Request - Usually this results from missing a required parameter. 401 Unauthorized - No valid access token provided. 403 Forbidden - The access token is not valid for that request. 404 Not Found - The requested item doesn't exist. 429 Too Many Requests - You have been ratelimited for making too many requests to the server. 5XX Server Error - Something went wrong on Pushbullet's side. If this error is from an intermediate server, it may not be valid JSON. Errors Error responses (any non-200 error code) contain information on the kind of error that happened. The response JSON will have an error property with the following fields: type - A machine-readable code to refer to this type of error. Either invalid_request for client side errors or server for server side errors. message - A (mostly) human-readable error message. param - (OPTIONAL) Appears sometimes during an invalid_request error to say which parameter in the request caused the error. cat - Some sort of ASCII cat to offset the pain of receiving an error message. Example: Error Response { "error" : { "cat" : "~(=^‥^)" , "message" : "The resource could not be found." , "type" : "invalid_request" } } Errors from the Pushbullet server will have this JSON body. Errors from intermediate servers or the hosting infrastructure may not, so you should be able to handle a non-JSON response as a generic error. Objects Objects (such as pushes and devices ) can be created, modified, listed and deleted. All timestamps that appear on objects are floating point seconds since the epoch, also called Unix Time . All calls to list objects (list-*) accept the active , limit , and cursor parameters. Bootstrapping By default, listing objects of any type will return deleted objects (this is useful for syncing). When you are getting the initial list of objects, you may want to only fetch the active ones. To get only active objects, set active to true on the request. Pagination When listing objects, if you receive a cursor in the response, it means the results are on multiple pages. To request the next page of results, use this cursor as the parameter cursor in the next request. Any time you list a collection of objects, they may be multiple pages (objects are always returned with the most recent ones first). You can specify a limit parameter on any calls that return a list of objects to get a smaller number of objects on each page. The default (maximum) limit is 500, including deleted objects. Syncing Changes All calls to list objects accept a modified_after property (a timestamp ). Any objects modified since that time will be returned, most recently modified first. The modified_after parameter should be the most recent modified value from an object returned by the server (don't trust the local machine's timestamp as it usually is not the same value as the server). Deleted Objects When you query with a modified_after timestamp to sync changed objects to a device, you need to know if an object was deleted so you can remove it locally. Deleted objects will have active=false and all properties except for iden , created , modified , and active w...