Pushbullet API

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

  • HTTP API - Send/receive pushes using the Pushbullet server.

  • Android Extensions - Extensions enable your app to work better with Pushbullet.

  • iPhone - Interact with the iPhone app from your app or webpage.

  • Changelog - Recent changes to the API.

Feedback

If you have any questions, feedback or requests, feel free to contact us at [email protected].

Pushbullet HTTP API

Getting Started

The HTTP API lets you send/receive pushes and do everything else the official Pushbullet clients can do. To access the HTTP 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 over the Pushbullet API:

EXAMPLE REQUEST
curl -u <your_access_token_here>: https://api.pushbullet.com/v2/users/me
EXAMPLE RESPONSE
{
  "iden": "ubdpjxakjjk1G",
  "email": "[email protected]",
  "email_normalized": "[email protected]",
  "created": 1357941753.8287899,
  "modified": 1399325992.1842301,
  ...
}

All of our examples use the curl command line tool already available on most systems. If you don't have it installed you can download it on the curl website.

Talking to the API

All POST requests should be over HTTPS and use a JSON body with the Content-Type header set to "application/json".

Authentication

This API is organized around REST and uses HTTP Basic Auth for authentication.

To authenticate for the API, use your access token as the username in the HTTP Basic Auth header, along with an empty password. 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 Pushbullet API on behalf of another user (for instance, to send push notifications as that user), use OAuth to get an access token for that user.

From an App

EXAMPLE REQUEST
curl -u <your_access_token_here>: https://api.pushbullet.com/v2/users/me

From a Browser

We allow CORS requests, so you can make a request from any browser:

EXAMPLE XMLHTTPREQUEST
  var xhr = new XMLHttpRequest()
  xhr.open("GET", "https://api.pushbullet.com/v2/users/me", false)
  xhr.setRequestHeader("Authorization", "Bearer <your_access_token_here>")
  xhr.send()
  console.log(xhr)

Responses

Responses are always JSON. Keys are either present with a non-null value, or entirely absent from the response. Deleted objects will only have the keys "iden", "active", "created", and "modified".

EXAMPLE RESPONSE
{
  "iden": "ubdpjxxxOK0sKG",
  "email": "[email protected]",
  "email_normalized": "[email protected]",
  "created": 1357941753.8287899,
  "modified": 1399325992.1842301,
  ...
}

HTTP Status Code Meanings

  • 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.
  • 5XX Server Error - Something went wrong on Pushbullet's side.

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
{
  "error": {
      "message": "The resource could not be found.",
      "type": "invalid_request",
      "cat": "~(=^‥^)"
  }
}

Objects

Objects (such as pushes, devices, and contacts) can be created, modified, listed and deleted.

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 a further 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 will be missing from the returned object. Deleted objects show up when listing objects.

API Calls

Objects

Messaging

Utility

Accounts

  • /oauth2 - Get access to other people's Pushbullet accounts with their permission.

Pushes

https://api.pushbullet.com/v2/pushes

Push to a device

POST https://api.pushbullet.com/v2/pushes

Target Parameters

Each push has a target, if you don't specify a target, we will broadcast it to all of the user's devices. Only one target may be specified.

  • device_iden - Send the push to a specific device. Appears as target_device_iden on the push. You can find this using the /v2/devices call.
  • email - Send the push to this email address. If that email address is associated with a Pushbullet user, we will send it directly to that user, otherwise we will fallback to sending an email to the email address (this will also happen if a user exists but has no devices registered).
  • channel_tag - Send the push to all subscribers to your channel that has this tag.
  • client_iden - Send the push to all users who have granted access to your OAuth client that has this iden.

Parameters for different types of pushes

  • Note
    • type - Set to note
    • title - The note's title.
    • body - The note's message.
  • Link
    • type - Set to link
    • title - The link's title.
    • body - A message associated with the link.
    • url - The url to open.
  • Address
    • type - Set to address
    • name - The place's name.
    • address - The place's address or a map search query.
  • Checklist
    • type - Set to list
    • title - The list's title.
    • items - The list items, a list of strings e.g. ["one", "two", "three"].
  • File
    • type - Set to file
    • file_name - The name of the file.
    • file_type - The MIME type of the file.
    • file_url - The url for the file. See pushing files for how to get a file_url
    • body - A message to go with the file.

Optional Parameters

  • source_device_iden - The iden of the device sending the push. This is useful when you need to send a push back to the sending device.
EXAMPLE REQUEST (NOTE)
curl -u <your_access_token_here>: -X POST https://api.pushbullet.com/v2/pushes --header 'Content-Type: application/json' --data-binary '{"type": "note", "title": "Note Title", "body": "Note Body"}'
EXAMPLE RESPONSE
{
  "iden": "ubdpj29aOK0sKG",
  "type": "note",
  "title": "Note Title",
  "body": "Note Body",
  "created": 1399253701.9744401,
  "modified": 1399253701.9746201,
  "active": true,
  "dismissed": false,
  "sender_iden": "ubd",
  "sender_email": "[email protected]",
  "sender_email_normalized": "[email protected]",
  "receiver_iden": "ubd",
  "receiver_email": "[email protected]",
  "receiver_email_normalized": "[email protected]"
}
EXAMPLE REQUEST (LIST)
curl -u <your_access_token_here>: -X POST https://api.pushbullet.com/v2/pushes --header 'Content-Type: application/json' --data-binary '{"type": "list", "title": "List Title", "items": ["Item One", "Item Two"]}'
EXAMPLE RESPONSE
{
  "iden": "ubdpjAkaGXvUl2",
  "type": "list",
  "title": "List Title",
  "items": [{"checked": false, "text": "Item One"}, {"checked": false, "text": "Item Two"}],
  "created": 1411595195.1267679,
  "modified": 1411595195.1268303,
  "active": true,
  "dismissed": false,
  "sender_iden": "ubd",
  "sender_email": "[email protected]",
  "sender_email_normalized": "[email protected]",
  "receiver_iden": "ubd",
  "receiver_email": "[email protected]",
  "receiver_email_normalized": "[email protected]"
}

Push a file

Pushing files is a two-part process: first the file needs to be uploaded, then a push needs to be sent for that file.

To upload a new file, use the upload request endpoint.

Once the file has been uploaded, set the file_name, file_url, and file_type returned in the response to the upload request as the parameters for a new push with type=file.

Request push history

GET https://api.pushbullet.com/v2/pushes

Parameters

  • modified_after - Request pushes modified after this timestamp.
EXAMPLE REQUEST
curl -u <your_access_token_here>: -X GET https://api.pushbullet.com/v2/pushes?modified_after=0
EXAMPLE RESPONSE
{
  "pushes": [
    {
      "iden": "ubdprOsjAhOzf0XYq",
      "type": "link",
      "title": "Pushbullet",
      "body": "Documenting our API",
      "url": "http://docs.pushbullet.com",
      "created": 1411595135.9685705,
      "modified": 1411595135.9686127,
      "active": true,
      "dismissed": false,
      "sender_iden": "ubd",
      "sender_email": "[email protected]"
      "sender_email_normalized": "[email protected]",
      "receiver_iden": "ubd",
      "receiver_email": "[email protected]",
      "receiver_email_normalized": "[email protected]",
    }
  ]
}

Update a push

POST https://api.pushbullet.com/v2/pushes/<push_iden>

Parameters

  • dismissed - Set to true to mark the push as dismissed. All devices displaying this push should hide it from view.
  • items - Update the items of a list push. The format should be the same as the items property of the push object, e.g. [{"checked": true, "text": "Item One"}, {"checked": true, "text": "Item Two"}]
EXAMPLE REQUEST (DISMISS)
curl -u <your_access_token_here>: -X POST https://api.pushbullet.com/v2/pushes/ubdpj29aOK0sKG --header 'Content-Type: application/json' --data-binary '{"dismissed": true}'
EXAMPLE RESPONSE
{
  "iden": "ubdpj29aOK0sKG",
  "type": "note",
  "title": "Note Title",
  "body": "Note Body",
  "created": 1399253701.9744401,
  "modified": 1399358385.0978525,
  "active": true,
  "dismissed": true,
  "sender_iden": "ubd",
  "sender_email": "[email protected]",
  "sender_email_normalized": "[email protected]",
  "receiver_iden": "ubd",
  "receiver_email": "[email protected]",
  "receiver_email_normalized": "[email protected]"
}
EXAMPLE REQUEST (UPDATE LIST)
curl -u <your_access_token_here>: -X POST https://api.pushbullet.com/v2/pushes/ubdpjAkaGXvUl2 --header 'Content-Type: application/json' --data-binary '{"items": [{"checked": true, "text": "one"}, {"checked": true, "text": "two"}]}'
EXAMPLE RESPONSE
{
  "iden": "ubdpjAkaGXvUl2",
  "type": "list",
  "title": "List Title",
  "items": [{"checked": true, "text": "Item One"}, {"checked": true, "text": "Item Two"}],
  "created": 1411595195.1267679,
  "modified": 1411699878.2501802,
  "active": true,
  "dismissed": false,
  "sender_iden": "ubd",
  "sender_email": "[email protected]",
  "sender_email_normalized": "[email protected]",
  "receiver_iden": "ubd",
  "receiver_email": "[email protected]",
  "receiver_email_normalized": "[email protected]"
}

Deleting a push

DELETE https://api.pushbullet.com/v2/pushes/<push_iden>

Parameters

  • push_iden - The iden of the push to delete.
EXAMPLE REQUEST
curl -u <your_access_token_here>: -X DELETE https://api.pushbullet.com/v2/pushes/ubdpjAkaGXvUl2
EXAMPLE RESPONSE
{}

Devices

https://api.pushbullet.com/v2/devices

Get the devices that can be pushed to

GET https://api.pushbullet.com/v2/devices
EXAMPLE REQUEST
curl -u <your_access_token_here>: -X GET https://api.pushbullet.com/v2/devices
EXAMPLE RESPONSE
{
  "devices": [
    {
      "iden": "u1qSJddxeKwOGuGW",
      "push_token": "u1qSJddxeKwOGuGWu1qdxeKwOGuGWu1qSJddxeK",
      "app_version": 74,
      "fingerprint": "<json_string>",
      "active": true,
      "nickname": "Galaxy S4",
      "manufacturer": "samsung",
      "type": "android",
      "created": 1394748080.0139201,
      "modified": 1399008037.8487799,
      "model": "SCH-I545",
      "pushable": true
    }
  ]
}

Create a new device

POST https://api.pushbullet.com/v2/devices
EXAMPLE REQUEST
curl -u <your_access_token_here>: -X POST https://api.pushbullet.com/v2/devices -d nickname=stream_device -d type=stream
EXAMPLE RESPONSE
{
    "iden": "udm0Tdjz5A7bL4NM",
    "nickname": "stream_device",
    "created": 1401840789.2369599,
    "modified": 1401840789.2369699,
    "active": true,
    "type": "stream",
    "pushable": true
}

Any pushes sent to a stream device will cause tickle messages to appear on the websocket.

Update an existing device

POST https://api.pushbullet.com/v2/devices/<device_iden>
EXAMPLE REQUEST
curl -u <your_access_token_here>: -X POST https://api.pushbullet.com/v2/devices/udm0Tdjz5A7bL4NM -d nickname=Brian
EXAMPLE RESPONSE
{
    "iden": "udm0Tdjz5A7bL4NM",
    "nickname": "Brian",
    "created": 1401840789.2369599,
    "modified": 1401841289.2369699,
    "active": true,
    "type": "stream",
    "pushable": true
}

Delete a device

DELETE https://api.pushbullet.com/v2/devices/<device_iden>

Parameters

  • device_iden - The iden of the device to delete.
EXAMPLE REQUEST
curl -u <your_access_token_here>: -X DELETE https://api.pushbullet.com/v2/devices/u1qSJddxeKwOGuGW
EXAMPLE RESPONSE
{}

Contacts

https://api.pushbullet.com/v2/contacts

Get your contacts

GET https://api.pushbullet.com/v2/contacts
EXAMPLE REQUEST
curl -u <your_access_token_here>: -X GET https://api.pushbullet.com/v2/contacts
EXAMPLE RESPONSE
{
  "contacts": [
    {
      "iden": "ubdcjAfszs0Smi",
      "name": "Ryan Oldenburg",
      "created": 1399011660.4298899,
      "modified": 1399011660.42976,
      "email": "[email protected]"
      "email_normalized": "[email protected]",
      "active": true
    }
  ]
}

Create a contact

POST https://api.pushbullet.com/v2/contacts

Parameters

  • name - The name you want associated with the contact.
  • email - The email address of the contact.
EXAMPLE REQUEST
curl -u <your_access_token_here>: -X POST https://api.pushbullet.com/v2/contacts -d "name=Ryan Oldenburg" -d [email protected]
EXAMPLE RESPONSE
{
  "iden": "ubdcjAfszs0Smi",
  "name": "Ryan Oldenburg",
  "created": 1399011660.4298899,
  "modified": 1399011660.42976,
  "email": "[email protected]"
  "email_normalized": "[email protected]",
  "active": true
}

Update a contact

POST https://api.pushbullet.com/v2/contacts/<contact_iden>

Parameters

  • name - The name you want associated with the contact.
EXAMPLE REQUEST
curl -u <your_access_token_here>: -X POST https://api.pushbullet.com/v2/contacts/ubdcjAfszs0Smi -d "name=Andre von Houck"
EXAMPLE RESPONSE
{
  "iden": "ubdcjAfszs0Smi",
  "name": "Andre von Houck",
  "created": 1399011660.4298899,
  "modified": 1399011660.42976,
  "email": "[email protected]"
  "email_normalized": "[email protected]",
  "active": true
}

Delete a contact

DELETE https://api.pushbullet.com/v2/contacts/<contact_iden>

Parameters

  • contact_iden - The iden of the contact to delete.
EXAMPLE REQUEST
curl -u <your_access_token_here>: -X DELETE https://api.pushbullet.com/v2/contacts/ubdcjAfszs0Smi
EXAMPLE RESPONSE
{}

Subscriptions

https://api.pushbullet.com/v2/subscriptions

Subscribe to channels to receive any updates pushed to that channel.

Channels can be created on the website. Each channel has a unique tag to identify it. When you push to a channel, all people subscribed to that channel will receive a push.

To push to a channel, use the channel_tag parameter on /v2/pushes

Subscription Object

  • iden - Iden of the subscription.
  • created - Created timestamp.
  • modified - Modified timestamp.
  • active - True if the subscription has not been deleted.
  • channel - Properties of the channel that is being subscribed to.
    • iden - Iden of the channel.
    • tag - Unique tag for the channel.
    • name - Name of the channel.
    • description - Description of the channel.
    • website_url - Link to a website for the channel.
    • image_url - Image to use for the channel.

Subscribe to a channel

POST https://api.pushbullet.com/v2/subscriptions

Parameters

  • channel_tag - The tag of the channel you wish to subscribe to.
EXAMPLE REQUEST
curl -u <your_access_token_here>: -X POST https://api.pushbullet.com/v2/subscriptions --header "Content-Type: application/json" --data-binary '{"channel_tag": "jblow"}'
EXAMPLE RESPONSE
{
  "iden": "udprOsjAoRtnM0jc",
  "created": 1412047948.579029,
  "modified": 1412047948.5790315,
  "active": true,
  "channel": {
    "iden": "ujxPklLhvyKsjAvkMyTVh6",
    "tag": "jblow",
    "name": "Jonathan Blow",
    "description": "New comments on the web by Jonathan Blow.",
    "image_url": "https://pushbullet.imgix.net/ujxPklLhvyK-6fXf4O2JQ1dBKQedhypIKwPX0lyFfwXW/jonathan-blow.png"
  }
}

List subscriptions

GET https://api.pushbullet.com/v2/subscriptions
EXAMPLE REQUEST
curl -u <your_access_token_here>: -X GET https://api.pushbullet.com/v2/subscriptions
EXAMPLE RESPONSE
{
  "subscriptions": [
    {
      "iden": "udprOsjAsLtNTRAG",
      "created": 1411444346.969855,
      "modified": 1411444346.969857,
      "active": true,
      "channel": {
          "iden": "ujxPklLhvyKsjAvkMyTVh6",
          "tag": "jblow",
          "name": "Jonathan Blow",
          "description": "New comments on the web by Jonathan Blow.",
          "image_url": "https://pushbullet.imgix.net/ujxPklLhvyK-6fXf4O2JQ1dBKQedhypIKwPX0lyFfwXW/jonathan-blow.png"
      }
    }
  ]
}

Unsubscribe from a channel

DELETE https://api.pushbullet.com/v2/subscriptions/<iden>

Parameters

  • iden - The iden of the subscription.
EXAMPLE REQUEST
curl -u <your_access_token_here>: -X DELETE https://api.pushbullet.com/v2/subscriptions/udprOsjAsLtNTRAG
EXAMPLE RESPONSE
{}

Get information about a channel

GET https://api.pushbullet.com/v2/channel-info

Parameters

  • tag - The tag of the channel.
EXAMPLE REQUEST
curl -X GET https://api.pushbullet.com/v2/channel-info?tag=jblow
EXAMPLE RESPONSE
{
  "iden": "ujxPklLhvyKsjAvkMyTVh6",
  "tag": "jblow",
  "name": "Jonathan Blow",
  "description": "New comments on the web by Jonathan Blow.",
  "image_url": "https://pushbullet.imgix.net/ujxPklLhvyK-6fXf4O2JQ1dBKQedhypIKwPX0lyFfwXW/jonathan-blow.png"
}

Users

https://api.pushbullet.com/v2/users/me

Get the current user

GET https://api.pushbullet.com/v2/users/me
EXAMPLE REQUEST
curl -u <your_access_token_here>: https://api.pushbullet.com/v2/users/me
EXAMPLE RESPONSE
{
  "iden": "ubdpjxxxOK0sKG",
  "email": "[email protected]",
  "email_normalized": "[email protected]",
  "created": 1357941753.8287899,
  "modified": 1399325992.1842301,
  "name": "Ryan Oldenburg",
  "image_url": "https://lh4.googleusercontent.com/-YGdcF2MteeI/AAAAAAAAAAI/AAAAAAAADPU/uo9z33FoEYs/photo.jpg",
  "preferences": {
    "onboarding": {
      "app": false,
      "friends": false,
      "extension": false
    },
    "social": false
  }
}

Update the current user

POST https://api.pushbullet.com/v2/users/me

Parameters

  • preferences - The user's preferences (a json object, overwrites existing object).
EXAMPLE REQUEST
curl -u <your_access_token_here>: https://api.pushbullet.com/v2/users/me --data-binary '{"preferences": {"cat": "^. .^"}}'  --header "Content-Type: application/json"
EXAMPLE RESPONSE
{
  "iden": "ubdpjxxxOK0sKG",
  "email": "[email protected]",
  "email_normalized": "[email protected]",
  "created": 1357941753.8287899,
  "modified": 1399325992.1842301,
  "name": "Ryan Oldenburg",
  "image_url": "https://lh4.googleusercontent.com/-YGdcF2MteeI/AAAAAAAAAAI/AAAAAAAADPU/uo9z33FoEYs/photo.jpg",
  "preferences": {
    "cat": "^. .^"
  }
}

Realtime Event Stream

wss://stream.pushbullet.com/websocket

Connect to the stream

WEBSOCKET wss://stream.pushbullet.com/websocket/<your_access_token_here>

Live jsFiddle example

Stream Messages

All messages are JSON objects with a type key.

Types

  • type=nop - Sent every 30 seconds confirming the connection is active.
  • type=tickle - Tells you something has changed on the server. The subtype property tells you what has changed.
    • subtype=push - A change to the /v2/pushes resources.
    • subtype=device - A change to the /v2/devices resources.
  • type=push - A new push. The push data is available in an object from the push key. This is only used for pushes that do not appear under /v2/pushes (such as mirrored notifications).
EXAMPLE MESSAGES
{"type": "nop"}
{"type": "tickle", "subtype": "push"}
{"type": "push", "push": {...}}

Push message types

A message with type=push will contain a data object mapped to by the key push. This object is documented here based on its internal type.

  • type=mirror - This push is a notification mirrored from an Android device.
  • type=dismissal - This push is a dismissal message from an Android device.
EXAMPLE MESSAGES
{
  "type": "push",
  "push": {
    "type": "mirror",
    "iden": "pjgzwwn3YPQ",
    "source_device_iden": "ubddjAzSDVLgrI"
    "package_name": "com.pushbullet.android",
    "application_name": "Pushbullet",
    "notification_id": "-8",
    "notification_tag": null,
    "dismissable": true,
    "title": "Mirroring test",
    "body": "If you see this on your computer, mirroring is working!\n",
    "icon": "iVBORw0KGgoAAAANSUhEBgUzC42AAAADNElEQVRo\ng==\n",
    "created": 1399350964.1649699,
    "sender_iden": "ubd",
    "sender_email": "[email protected]",
    "sender_email_normalized": "[email protected]",
    "receiver_iden": "ubd",
    "receiver_email": "[email protected]",
    "receiver_email_normalized": "[email protected]"
  }
}

{
  "type": "push",
  "push":{
    "type": "dismissal",
    "iden": "pjgzwwocCCy",
    "source_device_iden": "ubddjAzSDVLgrI"
    "package_name": "com.pushbullet.android",
    "notification_id": "-8",
    "notification_tag":null,
    "created":1399350966.22458,
    "sender_iden": "ubd",
    "sender_email": "[email protected]"
    "sender_email_normalized": "[email protected]",
    "receiver_iden": "ubd",
    "receiver_email": "[email protected]",
    "receiver_email_normalized": "[email protected]"
  }
}

Reacting to tickles

When you receive a tickle message, it means that a resource of the type subtype has changed. This is your cue to update that resource. Here's an example for the pushes type:

On receiving this message:

{"type": "tickle", "subtype": "push"}

Request the pushes that have changed since the last time we received them:

GET https://api.pushbullet.com/v2/pushes?modified_after=1399008037.849

Then merge these updates into your local copy of the push history.

Note: It's best to use the most recently modified local push's modified timestamp when making requests for updates. This will keep the responses small and fast. Additionally, don't trust the local machine's current timestamp because it is inevitably different from the server's timestamp.

Upload Request

https://api.pushbullet.com/v2/upload-request

Request authorization to upload a file

POST https://api.pushbullet.com/v2/upload-request

Parameters

  • file_name - The name of the file you want to upload.
  • file_type - The MIME type of the file.
EXAMPLE REQUEST
curl -u <your_access_token_here>: -X POST https://api.pushbullet.com/v2/upload-request -d file_name=image.png -d file_type=image/png
EXAMPLE RESPONSE
{
  "file_type": "image/png",
  "file_name": "image.png",
  "file_url": "https://s3.amazonaws.com/pushbullet-uploads/ubd-VWb1dP5XrZzvHReWHCycIwPyuAMp2R9I/image.png",
  "upload_url": "https://s3.amazonaws.com/pushbullet-uploads",
  "data": {
    "awsaccesskeyid": "AKIAJJIUQPUDGPM4GD3W",
    "acl": "public-read",
    "key": "ubd-CWb1dP5XrZzvHReWHCycIwPyuAMp2R9I/image.png",
    "signature": "UX5s1uIy1ov6+xlj58JY7rGFKcs=",
    "policy": "eyKjb25kaXRpb25zIjTE6MzcuMjM0MTMwWiJ9",
    "content-type": "image/png"
  }
}

Upload the file

POST to upload_url from the response to the upload request

Parameters

Copy of all the parameters from the data object in the response to the upload request. In addition to that, the file should be uploaded as the parameter file. This request is more complicated than most of the other API requests and requires multipart/form-data encoding.

After the request completes, the file will be available at file_url from the upload request response.

EXAMPLE REQUEST
curl -i -X POST https://s3.amazonaws.com/pushbullet-uploads \
  -F awsaccesskeyid=AKIAJJIUQPUDGPM4GD3W \
  -F acl=public-read \
  -F key=ubd-CWb1dP5XrZzvHReWHCycIwPyuAMp2R9I/image.png \
  -F signature=UX5s1uIy1ov6+xlj58JY7rGFKcs= \
  -F policy=eyKjb25kaXRpb25z6MzcuMjM0MTMwWiJ9 \
  -F content-type=image/png
  -F [email protected]
EXAMPLE RESPONSE
HTTP/1.1 204 No Content

OAuth

https://api.pushbullet.com/oauth2

Overview

OAuth lets you access a user's Pushbullet account or have them authenticate with their Pushbullet account using a browser.

OAuth is a standard authentication procedure used by most websites, here's how it works:

  1. You, the app developer, register your app (called an "OAuth client") with Pushbullet
  2. Using a url you generate in your app (you can see an example one on the Create Client page) you send the user to the Pushbullet site. One of the parameters of the url is a redirect url that the user will be sent to when they are done authorizing your app.
  3. The user authorizes your application by clicking the "Allow" button.
  4. The user is redirected to the redirect url you provided earlier, which is generally your site or your app.

Here's roughly how this looks with pictures:

Getting Started

To get started, create a client (register your application) on the Create Client page. For the examples on this page, the client looks like this:

EXAMPLE CLIENT
{
  "iden": "P8NJ4exxMI8",
  "name": "CatPusher",
  "image_url": "http://www.catpusher.com/logo.png",
  "website_url": "http://www.catpusher.com",
  "redirect_uri": "http://www.catpusher.com/auth_complete",
  "client_id": "YW7uItOzxPFx8vJ4",
  "client_secret": "MmA98EDg0pjr4fZw"
}

Getting an Access Token

Once you've created a client, you can send a user to https://www.pushbullet.com/authorize with the following parameters:

  • client_id - client_id from registering your client
  • redirect_uri - The url you want to redirect the user to after authorization is complete. The path portion must match what was provided for the client, the query string may be set dynamically.
  • response_type - Either "code" (if you've got a server) or "token" (if your app is entirely on the client)
EXAMPLE URL
https://www.pushbullet.com/authorize?client_id=YW7uItOzxPFx8vJ4&redirect_uri=http%3A%2F%2Fwww.catpusher.com%2Fauth_complete&response_type=code

NOTE: There's an example url ("oauth test url") on the Create Client page for your app.

When the user is sent to this page, they are able to authorize or deny your application. If they choose deny, they get redirected to the redirect_uri with the parameter "error=access_denied".

If they chose authorize, there are two possible next steps, depending on the value of response_type:

For Client-Side Apps: response_type=token

The user is redirected to the redirect_uri with a url fragment of "access_token=<access_token>". If you have a client side app running an embedded web browser, you can configure your redirect_uri to be "https://www.pushbullet.com/login-success" and then use this redirect_uri in the authorize call.

EXAMPLE URL
https://www.pushbullet.com/authorize?client_id=YW7uItOzxPFx8vJ4&redirect_uri=https%3A%2F%2Fwww.pushbullet.com%2Flogin-success&response_type=token
EXAMPLE REDIRECT
https://www.pushbullet.com/login-success#access_token=o.RUe7IZgC6384GrI1

For Apps with Servers: response_type=code

If you have a server you can use this response_type, it's potentially more secure than the client-side one, since the client never sees the actual access token. In this mode the user is redirected to the redirect_uri with a parameter "code=<code>".

EXAMPLE URL
https://www.pushbullet.com/authorize?client_id=YW7uItOzxPFx8vJ4&redirect_uri=http%3A%2F%2Fwww.catpusher.com%2Fauth_complete&response_type=code
EXAMPLE REDIRECT
http://www.catpusher.com/auth_complete?code=RUe7IZgC6384GrI1

Your server then peforms a request to https://api.pushbullet.com/oauth2/token with the following parameters:

  • grant_type - Set to "authorization_code"
  • client_id - client_id from registering your client
  • client_secret - client_secret from registering your client
  • code - code from the redirect
EXAMPLE REQUEST
curl https://api.pushbullet.com/oauth2/token -d grant_type=authorization_code -d client_id=YW7uItOzxPFx8vJ4 -d client_secret=MmA98EDg0pjr4fZw -d code=RUe7IZgC6384GrI1
EXAMPLE RESPONSE
{
  "token_type": "Bearer",
  "access_token": "a6FJVAA0LVJKrT8k"
}

You can add extra query params to the end of redirect_uri if you need to store extra state for the request. For instance, if you have your client's redirect_uri set to http://www.catpusher.com/auth_complete, then when you build the url to send the user to Pushbullet, you could specify redirect_uri=http://www.catpusher.com/auth_complete?state=zhk2KJ3SAAS3q1. When the user finishes authorizing your app, they would end up at http://www.catpusher.com/auth_complete?state=zhk2KJ3SAAS3q1&code=RUe7IZgC6384GrI1.

Using Your Access Token

Now that you have an access token, you can access Pushbullet as that user. Just include the access_token with your requests as the username in HTTP Basic Auth or set the Authorization header to Bearer <access_token>. Make sure to keep the access_token in a safe place, it allows access to your users accounts!

EXAMPLE REQUEST
curl -u <access_token>: https://api.pushbullet.com/v2/users/me
EXAMPLE RESPONSE
{
  "iden": "uLalKS9SKk",
  "email": "[email protected]",
  ...
}

The access_token does not have a set expiration time, but may be expired at some point in the future. If you delete your client, all existing tokens are invalidated.

Ephemerals

https://api.pushbullet.com/v2/ephemerals

Send arbitrary JSON messages, called "ephemerals", to all devices on your account. Ephemerals are stored for a short period of time (if at all) and are sent directly to android and stream devices (iOS not supported yet). Because they are sent directly, there is no "tickle" message like when creating or updating pushes or other objects, the JSON message appears directly in the stream.

Ephemerals are used by the Pushbullet apps for notification mirroring and universal copy/paste.

Unlike some of the other HTTP endpoints, POST parameters are not supported for ephemerals due to their JSON structure.

Send an ephemeral

POST https://api.pushbullet.com/v2/ephemerals

Parameters

  • type - Must be set to push which is the only type of ephemeral currently.
  • push - An arbitrary JSON object.
EXAMPLE REQUEST
curl -u <your_access_token_here>: -X POST https://api.pushbullet.com/v2/ephemerals --header "Content-Type: application/json" --data-binary '{"type": "push", "push": {}}'
EXAMPLE RESPONSE
{}

Ephemerals respond with an empty JSON object unless there is an error.

Mirrored Notifications

Mirrored notifications are notifications sent from android devices (currently the only source of mirrored notifications) to other devices. To test these out you can go into the android app's settings screen and hit the button "Send a test notification" while listening to the stream.

Notification Ephemeral

  • type - push for mirrored notifications.
  • push - information about the notification
    • type - mirror for mirrored notifications.
    • icon - Base64-encoded JPEG image to use as the icon of the push.
    • title - The title of the notification.
    • body - The body of the notification.
    • source_user_iden - The user iden of the user sending this message.
    • source_device_iden - The iden of the device sending this message.
    • application_name - The name of the application that created the notification.
    • dismissable - True if the notification can be dismissed.
    • package_name - The package that made the notification, used when updating/dismissing an existing notification.
    • notification_id - The id of the notification, used when updating/dismissing an existing notification.
    • notification_tag - The tag of the notification, used when updating/dismissing an existing notification.
    • has_root - The phone is rooted.
    • client_version - The client version of the app sending this message.
EXAMPLE NOTIFICATION EPHEMERAL
{
  "type": "push",
  "push": {
    "type": "mirror",
    "icon": "<base64_encoded_jpeg>",
    "body": "If you see this on your computer, Android-to-PC notifications are working!\n",
    "title": "Mirroring test",
    "source_device_iden": "udprOsjz3CpcAiXs",
    "source_user_iden": "udprO",
    "application_name": "Pushbullet",
    "dismissable": true,
    "package_name": "com.pushbullet.android",
    "notification_id": "-8",
    "notification_tag": null,
    "has_root": false,
    "client_version": 125
  }
}

Dismissal Ephemeral

  • type - push for notification dismissals.
  • push - information about the dismissal.
    • type - dismissal for notification dismissals.
    • package_name - Set to the package_name field from the mirrored notification.
    • notification_id - Set to the notification_id field from the mirrored notification.
    • notification_tag - Set to the notification_tag field from the mirrored notification.
    • source_user_iden - Set to the source_user_iden field from the mirrored notification.
EXAMPLE DISMISSAL MESSAGE
{
  "type": "push",
  "push": {
    "type": "dismissal",
    "package_name": "com.pushbullet.android",
    "notification_id": "-8",
    "notification_tag": null,
    "source_user_iden": "udprO"
  }
}
EXAMPLE REQUEST
curl -u <your_access_token_here>: -X POST https://api.pushbullet.com/v2/ephemerals --header "Content-Type: application/json" --data-binary '{"type": "push", "push": {"type": "dismissal", "package_name": "com.pushbullet.android", "notification_id": "-8", "notification_tag": null, "source_user_iden": "udprO"}}'
EXAMPLE RESPONSE
{}

Universal Copy/Paste

The Pushbullet apps (currently the Android and Windows apps) can monitor the clipboard and send out a message each time the user copies a new text selection, sending it to all the user's devices which can copy it to the clipboard or otherwise make it available to the user.

Copy a String to the Clipboard

Properties

  • type - push for clipboard messages.
  • push - information about the clipboard message.
    • type - clip for clipboard messages.
    • body - The text to copy to the clipboard.
    • source_user_iden - The iden of the user sending this message.
    • source_device_iden - The iden of the device sending this message.
EXAMPLE CLIPBOARD EPHEMERAL
{
  "type":"push",
  "push": {
    "type":"clip",
    "body":"http://www.google.com",
    "source_device_iden":"udprOsjz3CpcAiXs",
    "source_user_iden":"udprO"
  }
}
EXAMPLE REQUEST
curl -u <your_access_token_here>: -X POST https://api.pushbullet.com/v2/ephemerals --header "Content-Type: application/json" --data-binary '{"type": "push", "push": {"type":"clip", "body":"http://www.google.com", "source_device_iden":"udprOsjz3CpcAiXs", "source_user_iden":"udprO"}}'
EXAMPLE RESPONSE
{}

Pushbullet Extensions

Extensions enable your app to work better with Pushbullet.

Extension For Messaging Apps - Add quick-reply support from Pushbullet notifications on PC.

Pushbullet Extension For Messaging Apps

Pushbullet's messaging extension enables any messaging app on Android to offer quick-reply functionality from PC via desktop notifications shown by Pushbullet's notification mirroring service.

By integrating with Pushbullet, you make your app's desktop notifications actionable: when Pushbullet shows a notification from your app on PC, clicking on it will open a window enabling users to quickly reply to the message. This gives your app an incredibly convenient cross-platform experience.

Getting Started Is Easy

To get the Pushbullet extension set up your app:

  1. Add compile 'com.pushbullet:android-extensions:+@aar' or the API jar to your Android project.

  2. Create a new service that extends the MessagingExtension class.

  3. Add the corresponding <service> tag to your AndroidManifest.xml file and add the required <intent-filter> and <meta-data> element.

Once you have your extension set up, you'll be able to mirror messages to PC and receive replies composed on PC.

Implementing Your Extension

The full guide is available here.

Sample Project

A working example is available here on Github.

Notes

Messages are only sent to PC if the user has notification mirroring enabled, protecting their privacy.

Everything is done over secure (https) connections ensuring user privacy.

The use of a conversation identifier means we don't need to know phone numbers for this to work.

Implementing Your Messaging Extension

Once you've got compile 'com.pushbullet:android-extensions:+@aar' or the API jar included in your project, the first thing to do is create a new service that extends the MessagingExtension class.

After creating this new service, add the corresponding <service> tag to your AndroidManifest.xml file and add the required <intent-filter> and <meta-data> element like so:

<service
    android:name=".MyPushbulletExtension"
    android:permission="com.pushbullet.android.permission.READ_MESSAGING_EXTENSION_DATA">
    <intent-filter>
        <action android:name="com.pushbullet.android.extension.MessagingExtension" />
    </intent-filter>
    <meta-data
        android:name="protocolVersion"
        android:value="1" />
</service>

Extending MessagingExtension

When you extend MessagingExtension, there are two methods you'll need to implement:

onMessageReceived(String conversationIden, String message)

onConversationDismissed(String conversationIden)

onMessageReceived

This method will be called when a new reply has been composed on PC and is being forwarded to your app for delivery.

The parameter conversationIden is the value you provided to Pushbullet identifying the contact/group/thread. In this case it tells you where the message should be sent. For an SMS app this may be the thread ID.

The parameter message is the reply the user entered.

onConversationDismissed

This method is called when the notification for a conversation has been dismissed on the PC. You should use this to update or remove the notification shown on the user's phone by your app.

Implementing this correctly means updating your notification representing multiple active conversations (if your app groups conversations into one notification) without necessarily dismissing it.

The parameter conversationIden is described here.

Mirroring Conversations To PC

Once you've implemented (or stubbed out) your service extending MessagingExtension, you'll need to tell Pushbullet to mirror incoming messages to PC.

To do this, all you need to do is call the following static method on MessagingExtension when new messages are received:

mirrorMessage(Context context, String conversationIden, String sender,               String message, Bitmap image, String notificationTag,               int notificationId)

A context is used to confirm Pushbullet is installed and then to call startService, sending this data to Pushbullet for mirroring.

Use conversationIden to identify the contact/group/thread this message is associated with. This value will be returned to you with any reply messages.

The sender should be the name of the contact this message is from.

The message should be the text of the message.

Include the contact's picture as image.

The notificationTag and notificationId should be the tag and id of the notification provided to Android's NotificationManager for the notification for this conversation. Multiple conversations can have the same tag and id if you group conversations into one notification. See this and this. (Use null for notificationTag if you don't specify one when calling notify.)

Note: providing the correct notificationTag and notificationId is important to your extension functioning properly. If these value are incorrect, the notifications will not be synced correctly.

iPhone

Pushbullet URL Handler

The iPhone app has a url handler, pushbullet:// that can be used to compose pushes like so:

  pushbullet://compose?type=note&body=Hello

compose is the only option right now, but a few push types can be constructed (make sure to urlencode any parameters):

  pushbullet://compose?type=link&url=https%3A%2F%2Fwww.pushbullet.com
  pushbullet://compose?type=address&address=850%20Bryant%20St

Only type=note type=link and type=address are supported for now (and their parameters are the same as the /v2/pushes HTTP endpoint), other types and actions will be added in the future.

Open in Pushbullet

If you use a UIDocumentInteractionController to preview a file, when the user selects "Open In..." for most file types, Pushbullet should show up in the list of applications.

If the user selects the Pushbullet app, the app should open with a new compose window for a type=file push with the provided file attached.

Feedback

Let us know what you think at [email protected]

Changelog

February 12, 2015

  • Changed docs to single-page layout

September 29, 2014

September 24, 2014

August 11, 2014

July 21, 2014

July 9, 2014

July 1, 2014

June 28, 2014

June 19, 2014