Particle Cloud API

The Particle Cloud API is a REST API. REST means a lot of things, but first and foremost it means that we use the URL in the way that it's intended: as a "Uniform Resource Locator".

In this case, the unique "resource" in question is your device (Core, Photon, Electron). Every device has a URL, which can be used to GET variables, POST a function call, or PUT new firmware. The variables and functions that you have written in your firmware are exposed as subresources under the device.

All requests to the device come through our API server using TLS security.

PROTOCOL AND HOST
"https://api.particle.io"

Formatting note: When we write something prefixed with a colon :, we mean you should substitute your own information. For example when you see something like /v1/devices/:deviceId you might code something like /v1/devices/55ff8800beefcafe12345678.

Product ID or slug

For product endpoints, you need to specify which product the API call targets. You can use either the product ID or the short alphanumerical product slug. Get either from the Console. In this example, the product ID is 1337 and the product slug is my-product-v1.

Authentication

Just because you've connected your Particle device to the internet doesn't mean anyone else should have access to it. Permissions for controlling and communicating with your Particle device are managed with OAuth2.

# You type in your terminal
curl https://api.particle.io/v1/devices/0123456789abcdef01234567/brew \
     -d access_token=9876987698769876987698769876987698769876
# Response status is 200 OK, which means
# the device says, "Yes ma'am!"

# Sneaky Pete tries the same thing in his terminal
curl https://api.particle.io/v1/devices/0123456789abcdef01234567/brew \
     -d access_token=1234123412341234123412341234123412341234
# Response status is 403 Forbidden, which means
# the device says, "You ain't the boss of me."

# LESSON: Protect your access token.

Your access token can be found in the Particle Build web IDE on the 'Settings' page.

Particle Build >

When you connect your Particle device to the Cloud for the first time, it will be associated with your account, and only you will have permission to control your Particle device—using your access token.

If you need to transfer ownership of the device to another user, the easiest way is to simply log into the Particle build site, click on the 'Devices' drawer on the bottom left, and then click the small 'right arrow' by the device you want to release, then click "Remove Device". This will make it possible for the other person you are transferring the device to, to go through the normal claiming process.

In the future, you will be able to provision access to your Particle device to other accounts and to third-party app developers; however, these features are not yet available.

How to send your access token

There are three ways to send your access token in a request.

  • In an HTTP Authorization header (always works)
  • In the URL query string (only works with GET requests)
  • In the request body (only works for POST & PUT when body is URL-encoded)

In these docs, you'll see example calls written using a terminal program called curl which may already be available on your machine.

Example commands will always start with curl.


To send a custom header using curl, use you the -H flag. The access token is called a "Bearer" token and goes in the standard HTTP Authorization header.

curl -H "Authorization: Bearer 38bb7b318cc6898c80317decb34525844bc9db55" \
  https://...

The query string is the part of the URL after a ? question mark. To send the access token in the query string just add access_token=38bb.... Because your terminal may think the question mark is special, enclose the entire URL in double quotes.

curl "https://api.particle.io/v1/devices?access_token=38bb7b318cc6898c80317decb34525844bc9db55"

The request body is how form contents are submitted on the web. Using curl, each parameter you send, including the access token is preceded by a -d flag. By default, if you add a -d flag, curl assumes that the request is a POST. If you need a different request type, you have to specifically say so with the -X flag, for example -X PUT.

curl -d access_token=38bb7b318cc6898c80317decb34525844bc9db55 \
  https://...

Generate an access token

POST /oauth/token

Creates an access token that gives you access to the Cloud API.

You must give a valid client ID and password in HTTP Basic Auth. For controlling your own developer account, you can use particle:particle. Otherwise use a valid OAuth Client ID and Secret. See OAuth Clients.

  • Authorization REQUIRED String

    Client ID and Secret. Any client id will work, but we suggest particle:particle.

  • grant_type REQUIRED String

    OAuth grant type. Usually password.

  • username REQUIRED String

    Your Particle account username

  • password REQUIRED String

    Your Particle account password

  • expires_in Number

    How many seconds the token will be valid for. 0 means forever. Short lived tokens are better for security.

  • expires_at Date

    When should the token expire? This should be an ISO8601 formatted date string.

$ curl https://api.particle.io/oauth/token \
       -u particle:particle \
       -d grant_type=password \
       -d "username=joe@example.com" \
       -d "password=SuperSecret"
  • access_token String

    The magical token you will use for all the other requests

  • token_type String
  • expires_in String

    The number of seconds this token is valid for. Defaults to 7776000 seconds (90 days) if unspecified in the request. 0 means forever.

  • refresh_token String

    Used to generate a new access token when it has expired.

POST /oauth/token
HTTP/1.1 200 OK
{
  "access_token": "254406f79c1999af65a7df4388971354f85cfee9",
  "token_type": "bearer",
  "expires_in": 7776000,
  "refresh_token": "b5b901e8760164e134199bc2c3dd1d228acf2d90"
}

List Access Tokens

GET /v1/access_tokens

Retrieve a list of all the issued access tokens for your account

  • - Object[]

    List of access tokens

    • token String

      Access token

    • expires_at String

      Date the token expires and is no longer valid

    • client String

      Client program used to create the token

GET /v1/access_tokens
HTTP/1.1 200 OK
[
  {
      "token": "b5b901e8760164e134199bc2c3dd1d228acf2d98",
      "expires_at": "2014-04-27T02:20:36.177Z",
      "client": "particle"
  },
  {
      "token": "ba54b6bb71a43b7612bdc7c972914604a078892b",
      "expires_at": "2014-04-27T06:31:08.991Z",
      "client": "particle"
  }
]

Delete an access token

DELETE /v1/access_tokens/:token

Delete your unused or lost tokens.

  • token REQUIRED String

    Access Token to delete

$ curl -X DELETE https://api.particle.io/v1/access_tokens/123abc \
       -u "joe@example.com:SuperSecret"
  • ok Boolean

    Whether or not the token was deleted

DELETE /v1/access_tokens/123abc
HTTP/1.1 200 OK
{
  "ok": true
}

Delete current access token

DELETE /v1/access_tokens/

Delete your currently used token.

$ curl -X DELETE https://api.particle.io/v1/access_tokens \
       -d access_token=123abc
  • ok Boolean

    Whether or not the token was deleted

DELETE /v1/access_tokens
HTTP/1.1 200 OK
{
  "ok": true
}

OAuth Clients

An OAuth client generally represents an app. The Particle CLI is a client, as are Particle Build, the Particle iOS app, and the Particle Android app. You too can create your own clients. You should create separate clients for each of your web and mobile apps that hit the Particle API.

Some requests, like generating an access token, require you to specify an OAuth client ID and secret using HTTP Basic authentication. Normally, when calling the Particle API as a single developer user to access your own account, you can use particle for both the client ID and secret as in the example above for generating an access token.

curl -u particle:particle https://...

However, especially when you are creating a product on the Particle platform and your web app needs to hit our API on behalf of your customers, you need to create your own client.

NEVER expose the client secret to a browser. If, for example, you have a client that controls all your organization's products, and you use the client secret in front-end JavaScript, then a tech-savvy customer using your website can read the secret in her developer console and hack all your customers' devices.

List clients

GET /v1/clients

Get a list of all existing OAuth clients, either owned by the authenticated user or clients associated with a product.

  • productIdOrSlug

    Product ID or slug. Product endpoint only.

$ curl "https://api.particle.io/v1/clients?access_token=1234"
$ curl "https://api.particle.io/v1/products/:productIdOrSlug/clients?access_token=1234"
  • ok Boolean
  • clients Object[]

    An array of OAuth clients

    • id String
    • name String
    • type String
    • redirect_uri String

      Only for clients with type: "web"

GET /v1/clients
HTTP/1.1 200 OK
{
    "ok":true,
    "clients": [
        {
            "name":"server",
            "type":"installed",
            "id":"server-999"
        },
        {
            "name":"Mobile App",
            "type":"installed",
            "id":"mobile-app-1234"
        }
    ]
}

Create a client

POST /v1/clients

Create an OAuth client that represents an app.

Use type=installed for most web and mobile apps. If you want to have Particle users login to their account on Particle in order to give your app access to their devices, then you can go through the full OAuth authorization code grant flow using type=web. This is the same way you authorize the Particle IFTTT channel, and it is similar to the way you give any app access to your Facebook or Twitter account.

Your client secret will never be displayed again! Save it in a safe place.

If you use type=web then you will also need to pass a redirect_uri parameter in the POST body. This is the URL where users will be redirected after telling Particle they are willing to give your app access to their devices.

If you are building a web or mobile application for your Particle product, you should use the product-specific endpoint for creating a client (POST /v1/products/:productIdOrSlug/clients). This will grant this client (and access tokens generated by this client) access to product-specific behaviors like calling functions and checking variables on product devices, creating customers, and generating customer scoped access tokens.

  • name REQUIRED String

    The name of the OAuth client

  • type REQUIRED String

    web or installed. web is used for the authorization code grant flow similar to IFTTT, Facebook, and Twitter use.

  • redirect_uri String

    Only required for web type. URL that you wish us to redirect to after the OAuth flow.

  • scope String

    Limits the scope of what the access tokens created using the client are allowed to do. Provide a space separated list of scopes. The only current valid scope is create_customer. Leave blank for full control.

  • productIdOrSlug String

    Product ID or slug. Product endpoint only.

$ curl https://api.particle.io/v1/clients \
       -d name=MyApp \
       -d type=installed \
       -d access_token=1234
$ curl https://api.particle.io/v1/products/:productIdOrSlug/clients \
       -d name=MyApp \
       -d type=installed \
       -d access_token=1234
  • ok Boolean
  • client Object
    • name String
    • type String
    • id String
    • secret String

      Save this! It will never be shown again.

    • redirect_uri String

      Only for clients with type: "web"

POST /v1/clients
HTTP/1.1 200 OK
{
    "ok": true,
    "client": {
        "name": "MyApp",
        "type": "installed",
        "id": "myapp-2146",
        "secret": "615c620d647b6e1dab13bef1695c120b0293c342"
    }
}

Update a client

PUT /v1/clients/:clientId

Update the name or scope of an existing OAuth client.

  • clientId REQUIRED

    The client ID to update

  • name String

    Give the OAuth client a new name

  • scope String

    Update the scope of the OAuth client. Pass create_customer to only allow customer creation from the client or pass none to remove all scopes (full permissions)

  • productIdOrSlug

    Product ID or slug. Product endpoint only.

$ curl -X PUT https://api.particle.io/v1/clients/client-123 \
       -d name="My App 2" \
       -d access_token=1234
$ curl -X PUT https://api.particle.io/v1/products/:productIdOrSlug/clients/client-123 \
       -d name="My App 2" \
       -d access_token=1234
  • - Object

    The updated client

PUT /v1/clients/client-123
HTTP/1.1 200 OK
{
    "ok": true,
    "client": {
        "name": "My App 2",
        "type": "installed",
        "id": "myapp-2146",
        "secret": "615c620d647b6e1dab13bef1695c120b0293c342"
    }
}

Delete a client

DELETE /v1/clients/:clientId

Remove an OAuth client

  • clientId REQUIRED

    The client ID to delete

  • productIdOrSlug

    Product ID or slug. Product endpoint only.

$ curl -X DELETE https://api.particle.io/v1/clients/client-123 \
       -d access_token=1234
$ curl -X DELETE https://api.particle.io/v1/products/:productIdOrSlug/clients/client-123 \
       -d access_token=1234
DELETE /v1/clients/:clientId
HTTP/1.1 204 No Content

Errors

The Particle Cloud uses traditional HTTP response codes to provide feedback from the device regarding the validity of the request and its success or failure. As with other HTTP resources, response codes in the 200 range indicate success; codes in the 400 range indicate failure due to the information provided; codes in the 500 range indicate failure within Particle's server infrastructure.

200 OK - API call successfully delivered to the device and executed.

400 Bad Request - Your request is not understood by the device, or the requested subresource (variable/function) has not been exposed.

401 Unauthorized - Your access token is not valid.

403 Forbidden - Your access token is not authorized to interface with this device.

404 Not Found - The device you requested is not currently connected to the cloud.

408 Timed Out - The cloud experienced a significant delay when trying to reach the device.

429 Too Many Requests - You are either making requests too often or too many at the same time. Please slow down.

500 Server errors - Fail whale. Something's wrong on our end.

Versioning

The API endpoints all start with /v1 to represent the first official version of the Particle Cloud API. The existing API is stable, and we may add new endpoints with the /v1 prefix.

If in the future we make backwards-incompatible changes to the API, the new endpoints will start with something different, probably /v2. If we decide to deprecate any /v1 endpoints, we'll give you lots of notice and a clear upgrade path.

Devices

List Devices

GET /v1/devices

List devices the currently authenticated user has access to. By default, devices will be sorted by last_heard in descending order.

  • - Object[]

    Array of devices

    • id String

      Device ID

    • name String

      Device name

    • last_app String

      Name of the last application that was flashed to the device

    • last_ip_address String

      IP Address that was most recently used by the device

    • last_heard Date

      Date and Time that the cloud last heard from the device in ISO 8601 format

    • product_id Number

      Indicates what product the device belongs to. Common values are 0 for Core, 6 for Photon.

    • connected Boolean

      Indicates whether the device is currently connected to the cloud

    • last_iccid String

      Last SIM card ID number used if an Electron

    • imei String

      IMEI number if an Electron

GET /v1/devices
HTTP/1.1 200 OK
[
  {
    "id": "53ff6f0650723",
    "name": "plumber_laser",
    "last_app": null,
    "last_ip_address": "10.0.0.1",
    "last_heard": null,
    "product_id": 0,
    "connected": false
  },
  {
    "id": "53ff291839887",
    "name": "particle_love",
    "last_app": null,
    "last_ip_address": "10.0.0.1",
    "last_heard": "2014-12-15T20:12:51.974Z",
    "product_id": 6,
    "connected": true
  }
]

List Devices in a product

GET /v1/products/:productIdOrSlug/devices

List all devices that are part of a product. Results are paginated, by default returns 25 device records per page.

  • productIdOrSlug REQUIRED String

    Product ID or Slug

  • deviceId String

    Filter results to devices with this ID (partial matching)

  • deviceName String

    Filter results to devices with this name (partial matching)

  • sortAttr String

    The attribute by which to sort results. Options for sorting are deviceId, firmwareVersion, or lastConnection. By default, if no sortAttr parameter is set, devices will be sorted by last connection, in descending order

  • sortDir String

    The direction of sorting. Pass asc for ascending sorting or desc for descending sorting

  • page Number

    Current page of results

  • perPage Number

    Records per page

$ curl "https://api.particle.io/v1/products/:productIdOrSlug/devices?access_token=1234"
  • devices Object[]

    An array of devices objects

    • id String

      Device ID

    • name String

      Device name

    • product_id Number

      The ID of the associated product

    • last_ip_address String

      IP Address that was most recently used by the device

    • last_landshake_at Date

      Date and time that the device most recently connected to the cloud in ISO 8601 format

    • user_id String

      The ID of the user who has ownership of the device

    • customer_id String

      The ID of the customer who has ownership of the device

    • online String

      Indicates whether the device is currently connected to the cloud

    • firmware_product_id Number

      The product ID that the device reported in its firmware the last time it connected to the cloud. This is the value of PRODUCT_ID() included in firmware

    • development Boolean

      Set to true if a device has been marked as a development device, meaning it will not receive any product firmware updates from the cloud

    • firmware_version Number

      The version number the device reported in its firmware the last time it connected to the cloud. This is the value of PRODUCT_VERSION() included in firmware

    • desired_firmware_version Number

      The version of firmware that the device has been indivudally locked to run. If firmware_version matches desired_firmware_version, the device is currently running this firmware.

    • quarantined Boolean

      If set to true, the device is unrecognized and has lost product privileges until it is manually approved

    • denied Boolean

      If set to true, this is a quarantined device that has been permanently denied access to product privileges

  • customers Object[]

    An array of customer objects

    • id String

      Customer ID

    • username String

      Customer username

    • activation_code String

      An activation code used for device claiming if the product is in "Private Beta" mode

  • meta Object

    Pagination metadata

    • total_pages Number

      Total number of pages of device records

GET /v1/products/:productIdOrSlug/devices
HTTP/1.1 200 OK
{
    "devices": [
         {
             "id":"1d002a000547343232363230",
             "product_id":295,
             "last_ip_address":"199.230.10.194",
             "firmware_version":3,
             "last_handshake_at":"2016-06-10T14:56:27.100Z",
             "user_id":"1230999caf8bad1916000456",
             "online":false,
             "firmware_product_id":295,
             "quarantined":true,
             "denied":true,
             "owner":"jeff@particle.io"
         },
         {
             "id":"32001e000747343337373738",
             "product_id":295,
             "last_ip_address":"199.21.86.18",
             "firmware_version":5,
             "last_handshake_at":"2017-03-09T00:26:46.246Z",
             "customer_id":"1230999caf8bad1916000123",
             "online":false,
             "name":"jeff_test_device",
             "firmware_product_id":295,
             "quarantined":true,
             "denied":false,
             "owner":"customer@gmail.com"
         },
         ...
    ],
    "customers": [
        {
              id:"123abc3456",
             username: "customer@gmail.com",
        }
    ],
    "meta": {
        "total_pages":1
    }
}

Import Devices into product

POST /v1/products/:productIdOrSlug/devices

Import devices into a product. Devices must be of the same platform type as the product in order to be successfully imported. Imported devices may receive an immediate OTA firmware update to the product's released firmware.

  • productIdOrSlug REQUIRED String

    Product ID or Slug

  • id String

    A device ID to import into a product. Pass id if you are trying to import a single device

  • file File

    A .txt file containing a single-column list of device IDs. This is the preferred method of importing many devices into a product at once. Encoded in multipart/form-data format

$ curl "https://api.particle.io/v1/products/:productIdOrSlug/devices?access_token=12345" \
       -F file=@devices.txt
  • updated Number

    The number of devices successfully added to the product

  • nonmemberDeviceIds Array

    Device IDs that already belong to other products that could not be imported

  • invalidDeviceIds Array

    Device IDs that were invalid and could not be imported

POST /v1/products/:productIdOrSlug/devices
HTTP/1.1 200 OK
{
    "updated":20,
    "nonmemberDeviceIds":[],
    "invalidDeviceIds":[]
}

Get device information

GET /v1/devices/:deviceId

Get basic information about the given device, including the custom variables and functions it has exposed.

  • deviceId REQUIRED String

    Device ID

$ curl "https://api.particle.io/v1/devices/0123456789abcdef01234567?access_token=1234"
$ curl "https://api.particle.io/v1/products/:productIdOrSlug/devices/0123456789abcdef01234567?access_token=1234"
  • id String

    Device ID

  • name String

    Device name

  • last_app String

    Name of the last application that was flashed to the device

  • connected Boolean

    Indicates whether the device is currently connected to the cloud

  • variables Object

    List of variable name and types exposed by the device

  • functions String[]

    List of function names exposed by the device

  • cc3000_patch_version String

    What version of the cc3000 firmware the devices is running. Only applies to Cores.

  • product_id Number

    Indicates what product the device belongs to. Common values are 0 for Core, 6 for Photon.

  • last_heard Date

    Date and Time that the cloud last heard from the device in ISO 8601 format

  • requires_deep_update Boolean

    Whether this device requires the "Deep Update". Only applies to Cores.

  • last_iccid String

    Last SIM card ID used if an Electron

  • imei String

    IMEI number if Electron

GET /v1/devices/
HTTP/1.1 200 OK
{
  "id": "0123456789abcdef01234567",
  "name": "gongbot",
  "connected": true,
  "variables": {
    "Gongs": "int32"
  },
  "functions": [
    "gong",
    "goto"
  ],
  "cc3000_patch_version": "1.29",
  "product_id": 0,
  "last_heard": "2015-07-17T22:28:40.907Z"
}

Get a variable value

GET /v1/devices/:deviceId/:varName

Request the current value of a variable exposed by the device. Variables can be read on a device you own, or for any device that is part of a product you are a team member of.

  • deviceId REQUIRED String

    Device ID

  • varName REQUIRED String

    Variable name

  • format "raw"

    Specify raw if you just the value returned

  • productIdOrSlug String

    Product ID or Slug. Product endpoint only.

$ curl "https://api.particle.io/v1/devices/0123456789abcdef01234567/temperature?access_token=1234"
$ curl "https://api.particle.io/v1/products/:productIdOrSlug/devices/0123456789abcdef01234567/temperature?access_token=1234"
  • result String

    The variable value

  • name String

    The variable name

  • coreInfo Object

    The device information

GET /v1/devices/0123456789abcdef01234567/temperature
HTTP/1.1 200 OK
{
  "name": "temperature",
  "result": 46,
  "coreInfo": {
    "name": "weatherman",
    "deviceID": "0123456789abcdef01234567",
    "connected": true,
    "last_handshake_at": "2015-07-17T22:28:40.907Z",
    "last_app": ""
  }
}
GET /v1/devices/0123456789abcdef01234567/temperature?format=raw
HTTP/1.1 200 OK
46

Call a function

POST /v1/devices/:deviceId/:functionName

Call a function exposed by the device, with arguments passed in the request body. Functions can be called on a device you own, or for any device that is part of a product you are a team member of.

  • deviceId REQUIRED String
  • functionName REQUIRED String
  • arg REQUIRED String

    Function argument with a maximum length of 63 characters

  • format "raw"

    Specify if you want the just the function return value returned

  • productIdOrSlug String

    Product ID or Slug. Product endpoint only.

$ curl https://api.particle.io/v1/devices/0123456789abcdef01234567/gong \
       -d arg="ZEN PLEASE" \
       -d access_token=1234
$ curl https://api.particle.io/v1/products/:productIdOrSlug/devices/0123456789abcdef01234567/gong \
       -d arg="ZEN PLEASE" \
       -d access_token=1234
  • id String

    Device ID

  • name String

    Device name

  • last_app String

    Name of last app flashed

  • connected Boolean

    Indicates if the device is currently connected to the cloud

  • return_value Number

    Return value from the called function

POST /v1/devices/0123456789abcdef01234567/gong
{ "arg": "ZEN PLEASE" }
HTTP/1.1 200 OK
{
  "id": "0123456789abcdef01234567",
  "name": "gongbot",
  "last_app": "",
  "connected": true,
  "return_value": 1
}
POST /v1/devices/0123456789abcdef01234567/gong
{ "format": "raw", "arg": "ZEN PLEASE" }
HTTP/1.1 200 OK
1

Rename a device

PUT /v1/devices/:deviceId

Rename a device, either owned by a user or a product

  • deviceId REQUIRED String

    Device ID

  • productIdOrSlug String

    Product ID or slug. Product endpoint only

  • name

    The desired name for the device

$ curl -X PUT https://api.particle.io/v1/devices/0123456789abcdef01234567 \
       -d name=phancy_photon \
       -d access_token=1234
$ curl -X PUT https://api.particle.io/v1/products/:productIdOrSlug/devices/0123456789abcdef01234567 \
       -d name=phancy_photon \
       -d access_token=1234
  • id String

    Device ID

  • name String

    Device name

  • updated_at Date

    Timestamp representing the last time the deivce was updated in ISO8601 format

PUT /v1/devices/0123456789abcdef01234567
HTTP/1.1 200 OK
{
  "id": "0123456789abcdef01234567",
  "name": "phancy_photon"
  "updated_at": "2017-03-10T20:21:49.059Z"
}

Add device notes

PUT /v1/devices/:deviceId
  • deviceId REQUIRED String

    Device ID

  • productIdOrSlug String

    Product ID or slug. Product endpoint only

  • notes String

    Notes that you would like to add to the device

$ curl -X PUT https://api.particle.io/v1/devices/0123456789abcdef01234567 \
       -d notes="A fancy device note" \
       -d access_token=1234
$ curl -X PUT https://api.particle.io/v1/products/:productIdOrSlug/devices/0123456789abcdef01234567 \
       -d notes="A fancy device note" \
       -d access_token=1234
  • id String

    Device ID

  • notes String

    Notes that have been added to the device

  • updated_at Date

    Timestamp representing the last time the deivce was updated in ISO8601 format

PUT /v1/devices/0123456789abcdef01234567
HTTP/1.1 200 OK
{
  "id": "0123456789abcdef01234567",
  "notes": "A fancy device note",
  "updated_at": "2017-03-10T20:21:49.059Z"
}

Create a claim code

POST /v1/device_claims

Generate a device claim code that allows the device to be successfully claimed to a Particle account during the setup process. You can use the product endpoint for creating a claim code to allow customers to successfully claim a product device. Use an access token that was generated by the Particle account you'd like to claim ownership of the device.

When creating claim codes for Wi-Fi devices like Photons, allow the cloud to generate the claim code for you. This is done by not passing anything to the request body (with the exception of products in private beta, which require an activation code to generate a claim code). Then, this claim code must be sent to the Photon via SoftAP. For more information on how to send claim codes to Particle devices via SoftAP, please check out Particle SoftAP setup for JavaScript.

Conversely, for cellular devices like Electrons, you must create a claim code equal to the iccid or imei of the device. This is because Electrons are not directly connected to by the client during setup. This is done by passing an iccid or imei in the body of the request when creating a claim code.

When an device connects to the cloud, it will immediately publish its claim code (or in the case of Electrons, it will publish its ICCID and IMEI). The cloud will check this code against all valid claim codes, and if there is a match, successfully claim the device to the account used to create the claim code.

  • Authorization REQUIRED String

    Access Token

  • imei String

    IMEI number of the Electron you are generating a claim for. This will be used as the claim code if iccid is not specified.

  • iccid String

    ICCID number (SIM card ID number) of the SIM you are generating a claim for. This will be used as the claim code.

  • activation_code String

    Activation Code. Only required if product is in private beta. Product endpoint only.

  • productIdOrSlug String

    Product ID or Slug. Product endpoint only.

$ curl "https://api.particle.io/v1/device_claims?access_token=1234"
$ curl "https://api.particle.io/v1/products/:productIdOrSlug/device_claims?access_token=1234"
  • claim_code String

    a claim code for use during the device setup process

  • device_ids String[]

    Array of device IDs that already belong to the user

 POST /v1/device_claims
 HTTP/1.1 200 OK
 {
        claim_code: 'rCFr2KAJNgzJ2rR3Jm1ZoUd7G4Sr3ak7MRHdWrM274eYzInP1+psZ0fP2qNehlj',
        device_ids: ['33ff210644893f533e242597']
 }

Claim a Device

POST /v1/devices

Claim a new or unclaimed device to your account.

  • id REQUIRED String

    Device ID

$ curl https://api.particle.io/v1/devices \
       -d id=0123456789abcdef01234567 \
       -d access_token=1234

Request device transfer from another user

POST /v1/devices
  • id REQUIRED String

    Device ID

  • request_transfer REQUIRED true

    Indicates you are requesting a device transfer from another user

$ curl https://api.particle.io/v1/devices \
       -d id=0123456789abcdef01234567 \
       -d request_transfer=true \
       -d access_token=1234
  • transfer_id String

    Unique ID that represents the transfer

Provision a new device ID

POST /v1/devices

Create a new device ID

  • product_id REQUIRED String

    Product that allows self-provisioning

$ curl https://api.particle.io/v1/devices \
       -d product_id=31 \
       -d access_token=1234

Remove device from product

DELETE /v1/products/:productIdOrSlug/devices/:deviceID

Remove a device from a product and re-assign to a generic Particle product. This endpoint will unclaim the device if it is owned by a customer.

  • Authorization REQUIRED String

    Access Token

  • productIdOrSlug REQUIRED String

    Product ID or Slug

  • deviceID REQUIRED String

    ID of the device to be removed

DELETE /v1/products/photon/devices/123abc
HTTP/1.1 204 NO CONTENT

Unclaim device

DELETE /v1/devices/:deviceID

Remove ownership of a device. This will unclaim regardless if the device is owned by a user or a customer, in the case of a product.

When using this endpoint to unclaim a product device, the route looks slightly different:

DELETE /v1/products/:productIdOrSlug/devices/:deviceID/owner

Note the /owner at the end of the route.

  • deviceID REQUIRED String

    ID of the device to be unclaimed

  • productIdOrSlug String

    Product ID or Slug

$ curl -X DELETE https://api.particle.io/v1/devices/12345 \
       -d access_token=123abc
# Note that the product endpoint requires adding "/owner" to the end of the route

$ curl -X DELETE https://api.particle.io/v1/products/:productIdOrSlug/devices/12345/owner \
       -d access_token=123abc
DELETE /v1/devices/12345
HTTP/1.1 200 OK
{
  "ok": true
}

Signal a device

PUT /v1/devices/:deviceID

Make the device conspicuous by causing its LED to flash in rainbow patterns

  • signal REQUIRED Number

    1 to start shouting rainbows, 0 to stop

$ curl -X PUT https://api.particle.io/v1/devices/12345 \
       -d signal=1 \
       -d access_token=123abc
DELETE /v1/devices/12345
HTTP/1.1 200 OK
{
  "id": "12345",
  "connected": true,
  "signaling": true
}

Quarantine

Approve a quarantined device

POST /v1/products/:productIdOrSlug/devices

Approve a quarantined device. This will immediately release the device from quarantine and allow it to publish events, receive firmware updates, etc.

  • Authorization REQUIRED String

    Access Token

  • productIdOrSlug REQUIRED String

    Product ID or Slug

  • id REQUIRED String

    ID of the device to be denied

POST /v1/products/photon/devices
{ "id": "123abc" }
HTTP/1.1 200 OK

Deny a quarantined device

DELETE /v1/products/:productIdOrSlug/devices/:deviceID

Deny a quarantined device

  • Authorization REQUIRED String

    Access Token

  • productIdOrSlug REQUIRED String

    Product ID or Slug

  • deviceID REQUIRED String

    ID of the device to be denied

  • deny REQUIRED true

    Flag indicating you wish to deny this device, instead of removing an already approved device.

DELETE /v1/products/photon/devices/123abc
{ deny: true }
HTTP/1.1 204 NO CONTENT

SIM Cards

List SIM cards

GET /v1/sims

Get a list of the SIM cards owned by an individual or a product. The product endpoint is paginated, by default returns 25 SIM card records per page.

  • iccid String

    Filter results to SIMs with this ICCID (partial matching) Product endpoint only

  • deviceId String

    Filter results to SIMs with this associated device ID (partial matching) Product endpoint only

  • deviceName String

    Filter results to SIMs with this associated device name (partial matching) Product endpoint only

  • page Number

    Current page of results Product endpoint only

  • perPage Number

    Records per page Product endpoint only

  • productIdOrSlug String

    Product ID or slug. Product endpoint only

$ curl "https://api.particle.io/v1/sims?access_token=12345"
$ curl "https://api.particle.io/v1/products/:productIdOrSlug/sims?access_token=12345"
  • sims Object[]

    An array of SIM card objects

    • _id String

      ICCID of the SIM

    • activations_count Number

      Number of times the SIM has been activated

    • base_country_code String

      The ISO Alpha-2 code of the country where the SIM card is based

    • base_monthly_rate Number

      The monthly rate of the 1 MB data plan for this SIM card, in cents

    • deactivations_count Number

      Number of times the SIM has been deactivated

    • first_activated_on Date

      Timestamp of the first activation date of the SIM card

    • last_activated_on Date

      Timestamp of the last activation date of the SIM card

    • last_activated_via String

      The method used to activate the SIM card. Internal use only, will be deprecated

    • last_status_change_action String

      The last state change of the SIM card

    • last_status_change_action_error String

      Whether the last action change resulted in an error. Set to "yes" or "no"

    • mb_limit Number

      The monthly data usage limit of the SIM card, in megabytes

    • msisdn String

      MSISDN number of the Ublox modem

    • overage_monthly_rate Number

      The per-MB overage rate for this SIM card, in cents

    • status String

      The current connectivity status of the SIM card

    • stripe_plan_slug String

      Data plan type. Internal use only, will be deprecated

    • updated_at Date

      Timestamp representing the last time the SIM was updated

    • user_id String

      The ID of the user who owns the SIM card

    • product_id String

      The ID of the product who owns the SIM card

    • carrier String

      The Telefony provider for the SIM card's connectivity

    • last_device_id String

      The device ID of the SIM card's last associated device

    • last_device_name String

      The device name of the SIM card's last associated device

  • meta Object

    An object containing the total number of pages of records Product endpoint only

GET /v1/sims
HTTP/1.1 200 OK
{
    "sims": [
         {

            "_id":"8934076500002589174",
            "activations_count":1,
            "base_country_code":"US",
            "base_monthly_rate":299,
            "deactivations_count":0,
            "first_activated_on":"2017-01-27T23:10:16.994Z",
            "last_activated_on":"2017-01-27T23:10:16.994Z",
            "last_activated_via":"user_setup",
            "last_status_change_action":"activate",
            "last_status_change_action_error":"no",
            "mb_limit":5,
            "msisdn":"345901000485300",
            "overage_monthly_rate":99,
            "status":"active",
            "stripe_plan_slug":"KickstarterElectronPlan",
            "updated_at":"2017-01-27T23:10:22.622Z",
            "user_id":"5580999caf8bad191600019b",
            "carrier":"telefonica",
            "last_device_id":"123abc",
            "last_device_name":"foo_bar_baz"
        },
        ...
    ]
}

Get data usage

GET /v1/sims/:iccid/data_usage

Get SIM card data usage for the current billing period, broken out by day. Note that date usage reports can be delayed by up to 1 hour.

  • iccid REQUIRED String

    The ICCID of the desired SIM

  • productIdOrSlug String

    Product ID or slug. Product endpoint only

$ curl "https://api.particle.io/v1/sims/1234/data_usage?access_token=1234"
$ curl "https://api.particle.io/v1/products/:productIdOrSlug/sims/1234/data_usage?access_token=1234"
  • iccid String

    ICCID of the SIM

  • usage_by_day Object[]

    An array of data usage by day

    • date String

      The date of the usage day

    • mbs_used Number

      Megabytes used in the usage day

    • mbs_used_cumulative Number

      Total megabytes used in the billing period, inclusive of this usage day

GET /v1/sims/:iccid/data_usage
HTTP/1.1 200 OK
{
    "iccid":"8934076500002589174",
    "usage_by_day": [
        {
            "date":"2017-02-24",
            "mbs_used":0.98,
            "mbs_used_cumulative":0.98
        },
        {
            "date":"2017-02-25",
            "mbs_used":0.50,
            "mbs_used_cumulative":1.48
        },
        ...
    ]
}

Get data usage for product fleet

GET /v1/products/:productIdOrSlug/sims/data_usage

Get fleet-wide SIM card data usage for a product in the current billing period, broken out by day. Daily usage totals represent an aggregate of all SIM cards that make up the product. Note that data usage reports can be delayed up to 1 hour.

  • productIdOrSlug REQUIRED String

    Product ID or slug

$ curl "https://api.particle.io/v1/products/:productIdOrSlug/sims/data_usage?access_token=1234"
  • total_mbs_used Number

    The total number of megabytes consumed by the fleet in the current billing period

  • total_active_sim_cards Number

    The total number of active SIM cards in the product fleet. SIM cards that have been paused due to reaching their monthly data limit are included in this total.

  • total_cost Numer

    The total cost of the SIM card data usage in cents. Includes base monthly rate for each SIM plus any overages incurred, see the cellular pricing page for details on how SIM data is billed.

  • usage_by_day Object[]

    An array of data usage by day

    • date String

      The date of the usage day

    • mbs_used Number

      Megabytes used in the usage day

    • mbs_used_cumulative Number

      Total megabytes used in the billing period, inclusive of this usage day

GET /v1/products/:productIdOrSlug/sims/data_usage
HTTP/1.1 200 OK
{
    "total_mbs_used":200.00,
    "total_active_sim_cards":2000,
    "total_cost":999999,
    "usage_by_day": [
        {
            "date":"2017-03-01",
            "mbs_used":100.00,
            "mbs_used_cumulative":100.00
        },
        {
            "date":"2017-03-02",
            "mbs_used":100.00,
            "mbs_used_cumulative":200.00
        },
        ...
    ]
}

Activate SIM

PUT /v1/sims/:iccid

Activates a SIM card for the first time. country and card_token should also be passed when using this option.

Can not be used to activate Product SIM cards. Use the product import endpoint instead.

  • iccid REQUIRED

    The ICCID of the SIM to update

  • country REQUIRED String

    The ISO Alpha-2 code of the country where the SIM card should be based. Required only if activating the SIM card for the first time.

  • card_token REQUIRED String

    A valid Stripe credit card token. See Stripe's documentation for creating a valid card token. Required only if activating the SIM card for the first time.

  • action REQUIRED String

    Set to activate to trigger SIM activation

$ curl -X PUT https://api.particle.io/v1/sims/1234 \
       -d action=activate \
       -d country=US \
       -d card_token=tok_1234 \
       -d access_token=1234
PUT /v1/sims/12345
HTTP/1.1 200 OK

Import and activate product SIMs

POST /v1/products/:productIdOrSlug/sims

Import a group of SIM cards into a product. SIM cards will be activated upon import. Activated SIM cards will receive a prorated charge for the 1MB data plan for the remainder of the month on your next invoice. Either pass an array of ICCIDs or include a file containing a list of SIM cards.

Import and activation will be queued for processing. You will receive an email with the import results when all SIM cards have been processed.

  • productIdOrSlug REQUIRED String

    Product ID or slug

  • country REQUIRED String

    The ISO Alpha-2 code of the desired base country for the imported SIM cards

  • sims String[]

    An array of SIM ICCIDs to import

  • file File

    A .txt file containing a single-column list of ICCIDs

$ curl https://api.particle.io/v1/products/:productIdOrSlug/sims \
       -d sims=["8934076500002586220"] \
       -d country=US \
       -d access_token=1234
POST /v1/products/:productIdOrSlug/sims
HTTP/1.1 200 OK
{
  ok: true
}

Deactivate SIM

PUT /v1/sims/:iccid

Deactivates a SIM card, disabling its ability to connect to a cell tower. Deactivated SIM cards will not incur future monthly data usage charges.

  • iccid REQUIRED

    The ICCID of the SIM to update

  • action REQUIRED

    Set to deactivate to trigger SIM deactivation

  • productIdOrSlug String

    Product ID or slug. Product endpoint only

$ curl -X PUT https://api.particle.io/v1/sims/1234 \
       -d action=deactivate \
       -d access_token=1234
$ curl -X PUT https://api.particle.io/v1/products/:productIdOrSlug/sims/1234 \
       -d action=deactivate \
       -d access_token=1234
PUT /v1/sims/12345
HTTP/1.1 200 OK

Reactivate SIM

PUT /v1/sims/:iccid

Re-enables a SIM card to connect to a cell tower. Do this if you'd like to reactivate a SIM that you have deactivated, or when unpausing a SIM that has reached its monthly data limit. When unpausing a SIM, you should also pass mb_limit with the request to raise the SIM card's monthly data limit.

  • iccid REQUIRED

    The ICCID of the SIM to update

  • action REQUIRED String

    Set to reactivate to trigger SIM reactivation

  • mb_limit Number

    Optionally also set a new data limit in megabytes. This is useful when unpausing

  • productIdOrSlug String

    Product ID or slug. Product endpoint only a SIM after it has reached its monthly data limit, to raise it's monthly limit for continued usage

$ curl -X PUT https://api.particle.io/v1/sims/1234 \
       -d action=reactivate \
       -d access_token=1234
$ curl -X PUT https://api.particle.io/v1/products/:productIdOrSlug/sims/1234 \
       -d action=reactivate \
       -d access_token=1234
PUT /v1/sims/12345
HTTP/1.1 200 OK

Update SIM data limit

PUT /v1/sims/:iccid

Update the data limit of a SIM card. The data limit represents the maximum data consumption before the SIM is paused until the beginning of the next billing period

  • iccid REQUIRED

    The ICCID of the SIM to update

  • mb_limit REQUIRED Number

    A number representing the desired data limit in megabytes for the SIM card. Data limits can be anywhere between 1-500 MBs

  • productIdOrSlug String

    Product ID or slug. Product endpoint only

$ curl -X PUT https://api.particle.io/v1/sims/1234 \
       -d mb_limit=100 \
       -d access_token=1234
$ curl -X PUT https://api.particle.io/v1/products/:productIdOrSlug/sims/1234 \
       -d mb_limit=100 \
       -d access_token=1234
PUT /v1/sims/12345
HTTP/1.1 200 OK

Release SIM from account

DELETE /v1/sims/:iccid

Remove a SIM card from an account, disassociating the SIM card from a user or a product. The SIM will be immediately deactivated, and the owner will receive charges for any overages incurred in the current billing period.

Once the SIM card has been released, it can be claimed by a different user, or imported into a different product.

  • iccid REQUIRED String

    The ICCID of the desired SIM

  • productIdOrSlug String

    Product ID or slug. Product endpoint only

$ curl -X DELETE https://api.particle.io/v1/sims/1234 \
       -d access_token=1234
$ curl -X DELETE https://api.particle.io/v1/products/:productIdOrSlug/sims/1234 \
       -d access_token=1234
DELETE /v1/sims/1234
HTTP/1.1 204 No Content

Events

Get a stream of events

GET /v1/events/:eventPrefix

Open a stream of Server Sent Events for all public events and private events for your devices.

  • eventPrefix String

    Filters the stream to only events starting with the specified prefix

$ curl "https://api.particle.io/v1/events?access_token=1234"
$ curl "https://api.particle.io/v1/events/temp?access_token=1234"
  • event String

    event name

  • data String

    event data in JSON format

GET /v1/events
HTTP/1.1 200 OK
:ok

event: temperature
data: {"data":"25.34","ttl":"60","published_at":"2015-07-18T00:12:18.174Z","coreid":"0123456789abcdef01234567"}

Get a stream of your events

GET /v1/devices/events/:eventPrefix

Open a stream of Server Sent Events for all public and private events for your devices.

  • eventPrefix String

    Filters the stream to only events starting with the specified prefix

$ curl "https://api.particle.io/v1/devices/events?access_token=1234"
$ curl "https://api.particle.io/v1/devices/events/temp?access_token=1234"
  • event String

    event name

  • data String

    event data in JSON format

GET /v1/devices/events
HTTP/1.1 200 OK
:ok

event: temperature
data: {"data":"25.34","ttl":"60","published_at":"2015-07-18T00:12:18.174Z","coreid":"0123456789abcdef01234567"}

Get a stream of events for a device

GET /v1/devices/:deviceId/events/:eventPrefix

Open a stream of Server Sent Events for all public and private events for the specified device.

  • deviceId REQUIRED String

    Device ID

  • eventPrefix String

    Filters the stream to only events starting with the specified prefix

$ curl "https://api.particle.io/v1/devices/0123456789abcdef01234567/events?access_token=1234"
$ curl "https://api.particle.io/v1/devices/0123456789abcdef01234567/events/temp?access_token=1234"
  • event String

    event name

  • data String

    event data in JSON format

GET /v1/devices/0123456789abcdef01234567/events
HTTP/1.1 200 OK
:ok

event: temperature
data: {"data":"25.34","ttl":"60","published_at":"2015-07-18T00:12:18.174Z","coreid":"0123456789abcdef01234567"}

Product event stream

GET /v1/products/:productIdOrSlug/events/[:eventName]

Open a stream of Server Sent Events for all public and private events for a product.

  • productIdOrSlug REQUIRED String

    Product ID or slug

  • eventName String

    Filters the stream to only events starting with the specified prefix

$ curl "https://api.particle.io/v1/products/photon/events?access_token=1234"
  • event String

    event name

  • data String

    event data in JSON format

GET /v1/products/photon/events
HTTP/1.1 200 OK
:ok

event: temperature
data: {"data":"25.34","ttl":"60","published_at":"2015-07-18T00:12:18.174Z","coreid":"0123456789abcdef01234567"}

Product device event steam

GET /v1/products/:productIdOrSlug/devices/:id/events/[:eventName]

Open a stream of Server Sent Events scoped to a particular device in a product

  • productIdOrSlug REQUIRED String

    Product ID or Slug

  • id REQUIRED String

    ID of the desired device

  • eventName String

    Filters the stream to only events starting with the specified event name prefix

$ curl "https://api.particle.io/v1/products/:productIdOrSlug/devices/123abc/events?access_token=1234"
  • event String

    event name

  • data String

    event data in JSON format

GET /v1/products/:productIdOrSlug/devices/123abc/events
HTTP/1.1 200 OK
:ok

event: temperature
data: {"data":"25.34","ttl":"60","published_at":"2015-07-18T00:12:18.174Z","coreid":"0123456789abcdef01234567"}

Publish an event

POST /v1/devices/events

Publish an event

  • name REQUIRED String

    Event name

  • data String

    Event data

  • private Boolean

    If you wish this event to be publicly visible

  • ttl Number

    How long the event should persist

$ curl https://api.particle.io/v1/devices/events \
       -d "name=myevent" \
       -d "data=Hello World" \
       -d "private=true" \
       -d "ttl=60" \
       -d "access_token=1234"
$ particle publish myevent "Hello World"
POST /v1/devices/events
HTTP/1.1 200 OK
{
  "ok": true
}

Publish a product event

POST /v1/products/:productId/events

Publish an event that is sent to the product's event stream

  • name REQUIRED String

    Event name

  • data String

    Event data

  • private Boolean

    If you wish this event to be publicly visible

  • ttl Number

    How long the event should persist

$ curl "https://api.particle.io/v1/products/:productIdOrSlug/events" \
       -d "name=myevent" \
       -d "data=Hello World" \
       -d "private=true" \
       -d "ttl=60" \
       -d access_token=1234
POST /v1/products/:productIdOrSlug/events
HTTP/1.1 200 OK
{
  "ok": true
}

Integrations [Webhooks]

Create a Webhook

POST /v1/integrations

A webhook is a flexible type of integration that allows you to interact with a wide variety of external tools and services. Create a webhook either for devices you own as a Particle developer, or for your product fleet. For more info, check out the webhooks guide.

  • integration_type REQUIRED String

    Must be set to Webhook

  • event REQUIRED String

    The name of the Particle event that should trigger the webhook

  • url REQUIRED String

    The web address that will be targeted when the webhook is triggered

  • requestType REQUIRED String

    Type of web request triggered by the webhook that can be set to GET, POST, PUT, or DELETE

  • deviceID String

    Limits the webhook triggering to a single device

  • body String

    Send a custom body along with the HTTP request

  • json Object

    Send custom data as JSON with the request. This will change the Content-Type header of the request to application/json

  • form Object

    Send custom data as a form with the request by including key/value pairs. This will change the Content-Type header of the request to application/x-wwww-form-urlencoded

  • query Object

    Send query parameters in the URL of the request by including key/value pairs

  • auth Object

    Add an HTTP basic auth header by including a JSON object with username/password set

  • headers Object

    Add custom HTTP headers by including key/value pairs

  • responseTopic String

    Customize the webhook response event name that your devices can subscribe to

  • errorResponseTopic String

    Customize the webhook error response event name that your devices can subscribe to

  • responseTemplate String

    Customize the webhook response body that your devices can subscribe to

  • noDefaults Boolean

    Set to true to not add the triggering Particle event's data to the webhook request

  • rejectUnauthorized Boolean

    Set to false to skip SSL certificate validation of the target URL

  • productIdOrSlug String

    Product ID or slug. Product endpoint only.

$ curl "https://api.particle.io/v1/integrations?access_token=12345" \ integration_type=Webhook \
       -d event=hello \
       -d url=https://samplesite.com \
       -d requestType=POST
$ curl "https://api.particle.io/v1/products/:productIdOrSlug/integrations?access_token=12345" \
       -d integration_type=Webhook \
       -d event=hello \
       -d url=https://samplesite.com \
       -d requestType=POST
  • ok Boolean
  • id String

    Webhook ID

  • url String

    Web address that will be targeted when the webhook is triggered

  • created_at String

    Timestamp of when the webhook was created

  • integration_type String

    Should be set to Webhook

  • hookUrl String

    Particle API endpoint to GET info on the webhook

 POST /v1/webhooks
 HTTP/1.1 201 Created

 {
      "ok": true
      "id": "12345",
      "url": "https://samplesite.com",
      "event": "hello",
      "created_at": "2016-04-28T17:06:33.123Z",
      "hookUrl": "https://api.particle.io/v1/webhooks/12345"
 }

Enable Azure IoT Hub Integration

POST /v1/integrations

Enable an integration with Azure IoT Hub. For more details, check out the tutorial.

  • integration_type REQUIRED String

    Must be set to AzureIotHub

  • event REQUIRED String

    The name of the Particle event that should trigger the integration

  • hub_name REQUIRED String

    The name of your Azure IoT Hub

  • policy_name REQUIRED String

    The name of the shared access policy used for authentication

  • policy_key REQUIRED String

    The shared access policy key used for authentication

  • deviceID String

    Limits the integration triggering to a single device

  • json Object

    A custom JSON payload to send along with the request

  • productIdOrSlug String

    Product ID or slug. Product endpoint only.

$ curl "https://api.particle.io/v1/integrations?access_token=12345" \
       -d integration_type=AzureIotHub \
       -d event=hello hub_name=myHubName policy_name=particle policy_key=123abc
$ curl "https://api.particle.io/v1/products/:productIdOrSlug/integrations?access_token=12345" \
       -d integration_type=AzureIotHub \
       -d event=hello hub_name=myHubName policy_name=particle policy_key=123abc
  • ok Boolean
  • id String

    Integration ID

  • created_at String

    Timestamp of when the integration was created

  • integration_type String

    Should be set to AzureIotHub

  • integrationUrl String

    URL to fetch information about the integration

  • hub_name String

    The name of your Azure IoT Hub

  • policy_name String

    The name of the shared access policy used for authentication

  • policy_key String

    The shared access policy key used for authentication

POST /v1/integrations
HTTP/1.1 201 Created
{
    "id":"1",
    "event":"foo",
    "created_at":"2017-03-16T19:54:54.570Z",
    "integration_type":"AzureIotHub",
    "hub_name":"your-iot-hub-name",
    "policy_name":"iothubowner",
    "policy_key": "123abc",
    "ok":true,
    "integrationUrl": "https://api.particle.io/v1/integration/1"
}

Enable Google Cloud Platform Integration

POST /v1/integrations

Enable an integration with Google Cloud Platform. For more details, check out the tutorial.

  • integration_type REQUIRED String

    Must be set to GoogleCloudPubSub

  • event REQUIRED String

    The name of the Particle event that should trigger the integration

  • topic REQUIRED String

    The Google Cloud Pub Sub topic name for publishing messages

  • deviceID String

    Limits the integration triggering to a single device

  • productIdOrSlug String

    Product ID or slug. Product endpoint only.

$ curl "https://api.particle.io/v1/integrations?access_token=12345" \
       -d integration_type=GoogleCloudPubSub \
       -d event=hello \
       -d topic=your/topic/name
$ curl "https://api.particle.io/v1/products/:productIdOrSlug/integrations?access_token=12345" \
       -d integration_type=GoogleCloudPubSub \
       -d event=hello \
       -d topic=your/topic/name
  • ok Boolean
  • id String

    Integration ID

  • created_at String

    Timestamp of when the integration was created

  • integration_type String

    Should be set to GoogleCloudPubSub

  • integrationUrl String

    URL to fetch information about the integration

  • topic String

    The Google Cloud Pub Sub topic name for publishing messages

POST /v1/integrations
HTTP/1.1 201 Created
{
    "id":"1",
    "event":"foo",
    "created_at":"2017-03-16T19:54:54.570Z",
    "integration_type":"GoogleCloudPubSub",
    "topic": "your/topic/name",
    "ok":true,
    "integrationUrl": "https://api.particle.io/v1/integration/1"
}

Enable Google Maps Integration

POST /v1/integrations

Enable an integration with Google Maps. For more details, check out the tutorial.

  • integration_type REQUIRED String

    Must be set to GoogleMaps

  • event REQUIRED String

    The name of the Particle event that should trigger the integration

  • api_key REQUIRED String

    Your Google Maps Geolocation API key. Check out these docs for details

  • deviceID String

    Limits the integration triggering to a single device

  • productIdOrSlug String

    Product ID or slug. Product endpoint only.

$ curl "https://api.particle.io/v1/integrations?access_token=12345" \
       -d integration_type=GoogleMaps \
       -d event=hello \
       -d api_key=123abc
$ curl "https://api.particle.io/v1/products/:productIdOrSlug/integrations?access_token=12345" \
       -d integration_type=GoogleMaps \
       -d event=hello \
       -d api_key=123abc
  • ok Boolean
  • id String

    Integration ID

  • created_at String

    Timestamp of when the integration was created

  • api_key String

    Your Google Maps Geolocation API key

  • integration_type String

    Should be set to GoogleCloudPubSub

  • integrationUrl String

    URL to fetch information about the integration

POST /v1/integrations
HTTP/1.1 201 Created
{
    "id":"1",
    "event":"foo",
    "created_at":"2017-03-16T19:54:54.570Z",
    "integration_type":"GoogleMaps",
    "ok":true,
    "api_key": "123abc",
    "integrationUrl": "https://api.particle.io/v1/integration/1"
}

Edit a Webhook

PUT /v1/integrations/:integrationId

Edit a Webhook. Subsequent triggering of this integration will be sent with the new attributes.

  • integrationId REQUIRED String

    The ID of the desired integration

  • event String

    The name of the Particle event that should trigger the webhook

  • deviceID String

    Limits the webhook triggering to a single device

  • url String

    The web address that will be targeted when the webhook is triggered

  • requestType String

    Type of web request triggered by the webhook that can be set to GET, POST, PUT, or DELETE

  • json Object

    Send custom data as JSON with the request. This will change the Content-Type header of the request to application/json

  • form Object

    Send custom data as a form with the request by including key/value pairs. This will change the Content-Type header of the request to application/x-wwww-form-urlencoded

  • query Object

    Send query parameters in the URL of the request by including key/value pairs

  • auth Object

    Add an HTTP basic auth header by including a JSON object with username/password set

  • headers Object

    Add custom HTTP headers by including key/value pairs

  • responseTopic String

    Customize the webhook response event name that your devices can subscribe to

  • errorResponseTopic String

    Customize the webhook error response event name that your devices can subscribe to

  • responseTemplate String

    Customize the webhook response body that your devices can subscribe to

  • noDefaults Boolean

    Set to true to not add the triggering Particle event's data to the webhook request

  • rejectUnauthorized Boolean

    Set to false to skip SSL certificate validation of the target URL

  • productIdOrSlug String

    Product ID or slug. Product endpoint only.

$ curl -X PUT https://api.particle.io/v1/integrations/12345 \
       -d event=foo \
       -d access_token=12345
$ curl -X PUT https://api.particle.io/v1/integrations/12345 \
       -d event=foo \
       -d access_token=12345
  • integration Object

    An integration object.

PUT /v1/integrations/12345
HTTP/1.1 200 OK
{
    "integration": {
        "id":"12345",
        "event":"foo",
        "created_at":"2017-03-14T17:57:46.316Z",
        "integration_type":"Webhook",
        "url":"https://weather.com",
        "requestType":"POST"
    }
}

Edit Azure IoT Hub Integration

PUT /v1/integrations/:integrationId

Edit an Azure IoT Hub integration. Subsequent triggering of this integration will be sent with the new attributes.

  • integrationId REQUIRED String

    The ID of the desired integration

  • event String

    The name of the Particle event that should trigger the integration

  • deviceID String

    Limits the integration triggering to a single device

  • hub_name String

    The name of your Azure IoT Hub

  • policy_name String

    The name of the shared access policy used for authentication

  • policy_key String

    The shared access policy key used for authentication

  • json Object

    A custom JSON payload to send along with the request

$ curl -X PUT https://api.particle.io/v1/integrations/12345 \
       -d event=foo \
       -d access_token=12345
$ curl -X PUT https://api.particle.io/v1/integrations/12345 \
       -d event=foo \
       -d access_token=12345
  • integration Object

    An integration object.

PUT /v1/integrations/12345
HTTP/1.1 200 OK
{
    "integration": {
        "id":"12345",
        "event":"foo",
        "created_at":"2017-03-14T17:57:46.316Z",
        "integration_type":"AzureIotHub",
        "hub_name": "your_iot_hub",
        "policy_name": "policy_name"
        "policy_key": "123abc"
    }
}

Edit Google Cloud Platform Integration

PUT /v1/integrations/:integrationId

Edit a Google Cloud platform integration. Subsequent triggering of this integration will be sent with the new attributes.

  • integrationId REQUIRED String

    The ID of the desired integration

  • event String

    The name of the Particle event that should trigger the integration

  • deviceID String

    Limits the integration triggering to a single device

  • topic String

    The Google Cloud Pub Sub topic name for publishing messages

$ curl -X PUT https://api.particle.io/v1/integrations/12345 \
       -d event=foo \
       -d access_token=12345
$ curl -X PUT https://api.particle.io/v1/integrations/12345 \
       -d event=foo \
       -d access_token=12345
  • integration Object

    An integration object.

PUT /v1/integrations/12345
HTTP/1.1 200 OK
{
    "integration": {
        "id":"12345",
        "event":"foo",
        "created_at":"2017-03-14T17:57:46.316Z",
        "integration_type":"GoogleCloudPubSub",
        "topic": "your/topic/name"
    }
}

List integrations

GET /v1/integrations

List all integrations. Pay special attention to the integration_type attribute of each integration, which will let you know whether the integration is a Webhook, an Azure IoT Hub integration, or a Google Cloud Platform integration.

If you would like to only list webhooks (integrations with type: 'Webhook'), you can use a slightly different endpoint:

GET /v1/webhooks

  • productIdOrSlug String

    Product ID or slug. Product endpoint only.

$ curl "https://api.particle.io/v1/integrations?access_token=12345"
$ curl "https://api.particle.io/v1/integrations?access_token=12345"
$ curl "https://api.particle.io/v1/webhooks?access_token=12345"
$ curl "https://api.particle.io/v1/products/:productIdOrSlug/webhooks?access_token=12345"
  • - Object[]

    An array of integration objects. The object will vary in its attributes depending on integration type. For information on specific integration type response bodies, please see creation docs for Webhooks, Azure IoT Hub, and Google Cloud Platform.

GET /v1/integrations
HTTP/1.1 200 OK
[
    {
        "id":"12345",
        "event":"eventName",
        "created_at":"2017-03-14T17:57:46.316Z",
        "integration_type":"Webhook",
        "url":"https://weather.com",
        "requestType":"POST"
    }
]

Edit Google Maps Integration

PUT /v1/integrations/:integrationId

Edit a Google Maps integration. Subsequent triggering of this integration will be sent with the new attributes.

  • integrationId REQUIRED String

    The ID of the desired integration

  • event String

    The name of the Particle event that should trigger the integration

  • deviceID String

    Limits the integration triggering to a single device

  • api_key String

    Your Google Maps Geolocation API key. Check out these docs for details

$ curl -X PUT https://api.particle.io/v1/integrations/12345 \
       -d api_key=123abc \
       -d access_token=12345
$ curl -X PUT https://api.particle.io/v1/integrations/12345 \
       -d api_key=123abc \
       -d access_token=12345
  • integration Object

    An integration object.

PUT /v1/integrations/12345
HTTP/1.1 200 OK
{
    "integration": {
        "id":"12345",
        "event":"foo",
        "created_at":"2017-03-14T17:57:46.316Z",
        "integration_type":"GoogleMaps",
        "api_key": "123abc"
    }
}

Get integration

GET /v1/integrations/:integrationId

Get a single integration. Pay special attention to the integration_type attribute of each integration, which will let you know whether the integration is a Webhook, an Azure IoT Hub integration, or a Google Cloud Platform integration.

  • integrationId REQUIRED String

    The ID of the desired integration

  • productIdOrSlug String

    Product ID or slug. Product endpoint only.

$ curl "https://api.particle.io/v1/integrations/12345?access_token=12345"
$ curl "https://api.particle.io/v1/integrations/12345?access_token=12345"
  • integration Object

    An integration object. The object will vary in its attributes depending on integration type. For information on specific integration type response bodies, please see creation docs for Webhooks, Azure IoT Hub, and Google Cloud Platform.

    • logs Object[]

      Contains information about the last 10 HTTP request/responses sent from this integration. A useful debugging tool.

GET /v1/integrations/12345
HTTP/1.1 200 OK
{
    "integration": {
        "id":"12345",
        "event":"eventName",
        "created_at":"2017-03-14T17:57:46.316Z",
        "logs": [...],
        "integration_type":"Webhook",
        "url":"https://weather.com",
        "requestType":"POST"
    }
}

Test an integration

POST /v1/integrations/:integrationId/test

Send a test event that triggers the integration. Helps build confidence that an integration is configured properly.

  • integrationId REQUIRED String

    The ID of the desired integration

  • productIdOrSlug String

    Product ID or slug. Product endpoint only.

$ curl https://api.particle.io/v1/integrations/12345/test \
       -d access_token=12345
$ curl https://api.particle.io/v1/integrations/12345/test \
       -d access_token=12345
  • pass Boolean

    Whether or not the integration was able to receive a successful response from the target

  • data String

    The data returned by a successful integration test attempt

  • error String

    If unsuccessful, the error returned from the target

POST /v1/integrations/1234/test
HTTP/1.1 200 OK
{
      pass: true,
      data: null

}

Delete an integration

DELETE /v1/integrations/:integrationId

Delete an integration and immediate stop it from triggering. The integration can belong to a user or to a product.

  • integrationId REQUIRED String

    The ID of the desired integration

  • productIdOrSlug String

    Product ID or slug (only for product webhooks)

$ curl -X DELETE https://api.particle.io/v1/integrations/12345 \
       -d access_token=12345
$ curl -X DELETE https://api.particle.io/v1/products/:productIdOrSlug/integrations/12345 \
       -d access_token=12345
DELETE /v1/webhooks
HTTP/1.1 204 No Content

Special Events

If you watch your event stream, you may notice your devices publishing events that don't appear in your firmware. The cloud will automatically publish events in special situations that would be hard to monitor without an event.

Special Device Events

Connection Status

When your device starts ("online") or stops ("offline") a session with the cloud, you'll see a 'spark/status' event.

# spark/status, online
{"name":"spark/status","data":"online","ttl":"60","published_at":"2015-01-01T14:29:49.787Z","coreid":"0123456789abcdef01234567"}

# spark/status, offline
{"name":"spark/status","data":"offline","ttl":"60","published_at":"2015-01-01T14:31:49.787Z","coreid":"0123456789abcdef01234567"}

If your device is a packaged product, you may see an "auto-update" event from time to time. This is the cloud signaling that a new version of firmware is available for your product from your manufacturer, and an update is about to be delivered over the air.

#  spark/status, auto-update
{"name":"spark/status","data":"auto-update","ttl":"60","published_at":"2015-01-01T14:35:0.000Z","coreid":"0123456789abcdef01234567"}

Safe-Mode

If your device is running an app that needs a particular version of system firmware, your device may come online and report that it's in Safe Mode. In this case, your device is waiting to run your app until it has received an update. Some products can receive system updates automatically while in safe mode, but others like the Electron prevent this to save you costs on bandwidth. If you do get an automatic update, you may see a "spark/safe-mode-updater/updating" event.

#  spark/status/safe-mode
{"name":"spark/status/safe-mode","data":"{ .. a bunch of data from your device about the system parts ...","ttl":"60","published_at":"2016-01-01T14:40:0.000Z","coreid":"0123456789abcdef01234567"}
{"name":"spark/status/safe-mode","data":"{\"f\":[],\"v\":{},\"p\":6,\"m\":[{\"s\":16384,\"l\":\"m\",\"vc\":30,\"vv\":30,\"f\":\"b\",\"n\":\"0\",\"v\":4,\"d\":[]},{\"s\":262144,\"l\":\"m\",\"vc\":30,\"vv\":30,\"f\":\"s\",\"n\":\"1\",\"v\":11,\"d\":[]},{\"s\":262144,\"l\":\"m\",\"vc\":30,\"vv\":30,\"f\":\"s\",\"n\":\"2\",\"v\":7,\"d\":[{\"f\":\"s\",\"n\":\"1\",\"v\":7,\"_\":\"\"}]},{\"s\":131072,\"l\":\"m\",\"vc\":30,\"vv\":26,\"u\":\"F3380CF3018C104BA3BD9438EA921A1ABF315E8063318FDDDCDBE10FED044BEB\",\"f\":\"u\",\"n\":\"1\",\"v\":3,\"d\":[{\"f\":\"s\",\"n\":\"2\",\"v\":11,\"_\":\"\"}]},{\"s\":131072,\"l\":\"f\",\"vc\":30,\"vv\":0,\"d\":[]}]}","ttl":"60","published_at":"2015-01-01T14:40:0.000Z","coreid":"0123456789abcdef01234567"}

#  spark/safe-mode-updater/updating
{"name":"spark/safe-mode-updater/updating","data":"2","ttl":"60","published_at":"2016-01-01T14:41:0.000Z","coreid":"particle-internal"}

Flashing

As updates are being delivered via the cloud to your device, you may see some events published by the cloud to help you monitor the update. These may include an optional file name after the status type if available.

#spark/flash/status, started + [filename]
{"name":"spark/flash/status","data":"started ","ttl":"60","published_at":"2016-02-09T14:43:05.606Z","coreid":"0123456789abcdef01234567"}

#spark/flash/status, success + [filename]
{"name":"spark/flash/status","data":"success ","ttl":"60","published_at":"2016-02-09T14:38:18.978Z","coreid":"0123456789abcdef01234567"}

#spark/flash/status, failed + [filename]
{"name":"spark/flash/status","data":"failed ","ttl":"60","published_at":"2016-02-09T14:43:11.732Z","coreid":"0123456789abcdef01234567"}

app-hash

After you've flashed a new app to your device, you may see an "app-hash" event. This is a unique hash corresponding to that exact app binary. This hash can help confirm a flash succeeded and your new app is running, and also help you track exactly which version of which app is running on your device. This is only published when it is different from the previous session.

#  spark/device/app-hash
{"name":"spark/device/app-hash","data":"2BA4E71E840F596B812003882AAE7CA6496F1590CA4A049310AF76EAF11C943A","ttl":"60","published_at":"2016-02-09T14:43:13.040Z","coreid":"2e0041000447343232363230"}

future reserved events

These events are planned, but not yet available.

If an update is available from the cloud, but isn't sent automatically, the cloud may publish an "flash/available" event to let the firmware know it can ask to have the update delivered.

#  spark/flash/available
{ reserved / not yet implemented}

If the cloud detects than an update is very large, or the update is taking a very long time, it might decide to publish periodic flash progress events. These are meant to help you track the progress of a slow update.

# spark/flash/progress,   sent,total,seconds
{ reserved / not yet implemented }

Special Webhook Events

Webhooks are a powerful way to connect events from your devices to other services online.

When the webhook detects your event, it'll publish back a hook-sent event to let you know it's processing the event and has sent a request to your server.

# hook-sent
{"name":"hook-sent/your_published_event_topic","data":"undefined","ttl":"60","published_at":"2016-02-09T14:42:19.876Z","coreid":"particle-internal"}

If the hook got an error back from your server, it'll publish a hook-error event with the contents of the error. See

# hook-error

{"name":"hook-error/your_published_event_topic/0","data":"Message ...","ttl":"60","published_at":"2016-02-09T15:23:23.047Z","coreid":"particle-internal"}

If the hook got a good response back, it'll break the response into 512 byte chunks and publish up to the first 100KB of the response back to your devices.

# hook-response
{"name":"hook-response/your_published_event_topic/0","data":"your server response...","ttl":"60","published_at":"2016-02-09T15:23:23.047Z","coreid":"particle-internal"}

Special IFTTT Events

Firmware

Update device firmware

PUT /v1/devices/:deviceId

Update the device firmware from source or binary

  • deviceId REQUIRED String

    Device ID

  • build_target_version

    {String} The firmware version to compile against. Defaults to latest

Flash a device with source code

PUT /v1/devices/:deviceId
  • deviceId REQUIRED String

    Device ID

  • build_target_version

    {String} The firmware version to compile against. Defaults to latest

  • file REQUIRED String

    The source code encoded in multipart/form-data format

$ curl -X PUT "https://api.particle.io/v1/devices/0123456789abcdef01234567?access_token=1234" \
       -F "file=@application.cpp;filename=application.cpp" \
       -F "file1=@lib/my_lib.cpp;filename=lib/my_lib.cpp" \
       -F "file2=@lib/my_lib.h;filename=lib/my_lib.h"
PUT /v1/devices/0123456789abcdef01234567
HTTP/1.1 200 OK
{
  "ok": true,
  "message": "Update started"
}

Flash a device with a pre-compiled binary

PUT /v1/devices/:deviceId
  • deviceId REQUIRED String

    Device ID

  • build_target_version

    {String} The firmware version to compile against. Defaults to latest

  • file REQUIRED String

    The pre-compiled binary encoded in multipart/form-data format

  • file_type REQUIRED binary

    Indicates that you are uploading a binary and not source code

$ curl -X PUT "https://api.particle.io/v1/devices/0123456789abcdef01234567?access_token=1234" \
       -F file=@my-firmware-app.bin \
       -F file_type=binary
PUT /v1/devices/0123456789abcdef01234567
HTTP/1.1 200 OK
{
  "id": "0123456789abcdef01234567",
  "status": "Update started"
}

Compile source code

POST /v1/binaries

Compile source code into a binary for a device

  • file REQUIRED String

    The source code encoded in multipart/form-data format

  • device_id String

    The device ID to target the compilation

  • product_id String

    The product to target for compilation

  • build_target_version String

    The firmware version to compile against. Defaults to latest

$ curl -X POST "https://api.particle.io/v1/binaries?access_token=1234" \
       -F product_id=6 \
       -F "file=@application.cpp;filename=application.cpp" \
       -F "file1=@lib/my_lib.cpp;filename=lib/my_lib.cpp" \
       -F "file2=@lib/my_lib.h;filename=lib/my_lib.h"
POST /v1/binaries
HTTP/1.1 200 OK
{
  "ok": true,
  "binary_id": "5734a5d4a71c2601243809e6",
  "binary_url": "/v1/binaries/5734a5d4a71c2601243809e6",
  "expires_at": "2016-05-13T15:48:27.997Z",
  "sizeInfo": "   text\t   data\t    bss\t    dec\t    hex\tfilename\n  91780\t    952\t   9368\t 102100\t  18ed4\t"
}

List firmware build targets

GET /v1/build_targets

Lists the firmware versions for all platforms that can be used as build targets during firmware compilation

  • featured REQUIRED String

    When true, show most relevant (featured) build targets only.

$ curl "https://api.particle.io/v1/build_targets?access_token=1234"
  • targets Array

    Array of build target objects

  • platforms Object

    Name of each platform ID with a build target

PUT /v1/build_targets
HTTP/1.1 200 OK
{
  "targets": [
    {
      "platforms": [
        0,
        10,
        8,
        6
      ],
      "prereleases": [],
      "firmware_vendor": "Particle",
      "version": "0.6.1"
    }
  ],
  "platforms": {
    "Core": 0,
    "Photon": 6,
    "P1": 8,
    "Electron": 10
  }
}

Lock product device

PUT /v1/products/:productIdOrSlug/devices/:deviceId

Locks a product device to a specific version of product firmware. This device will download and run this firmware if it is not already running it the next time it connects to the cloud. You can optionally trigger an immediate update to this firmware for devices that are currently online

  • deviceId REQUIRED String

    Device ID

  • productIdOrSlug REQUIRED String

    Product ID or slug. Product endpoint only

  • desired_firmware_version REQUIRED Number

    The firmware version the device should be locked to

  • flash Boolean

    Set to true to immediately flash to a device. Will only successfully deliver the firmware update if the device is currently online and connected to the cloud.

$ curl https://api.particle.io/products/:productIdOrSlug/devices/12345 \
       -d desired_firmware_version=1 \
       -d flash=true \
       -d access_token=123abc
  • id String

    Device ID

  • desired_firmware_version String

    The newly set firmware version to lock the device to

  • updated_at Date

    Timestamp representing the last time the deivce was updated in ISO8601 format

PUT /v1/devices/12345
HTTP/1.1 200 OK
{
  "id": "0123456789abcdef01234567",
  "desired_firmware_version": 1,
  "updated_at": "2017-03-10T20:21:49.059Z"
}

Unlock product device

PUT /v1/products/:productIdOrSlug/devices/:deviceId

Unlocks a product device from receiving and running a specific version of product firmware. The device will now be eligible to receive released firmware in the product.

  • deviceId REQUIRED String

    Device ID

  • productIdOrSlug REQUIRED String

    Product ID or slug. Product endpoint only

  • desired_firmware_version REQUIRED Number

    Set to null to unlock the device

$ curl https://api.particle.io/products/:productIdOrSlug/devices/12345 \
       -d desired_firmware_version=null \
       -d access_token=123abc
  • id String

    Device ID

  • desired_firmware_version String

    Should now be null signaling that the device is no longer locked to a specific version of firmware

  • updated_at Date

    Timestamp representing the last time the deivce was updated in ISO8601 format

PUT /v1/devices/12345
HTTP/1.1 200 OK
{
  "id": "0123456789abcdef01234567",
  "desired_firmware_version": null
  "updated_at": "2017-03-10T20:21:49.059Z"
}

Mark product development device

PUT /v1/products/:productIdOrSlug/devices/:deviceId

Mark a device in a product fleet as a development device. Once marked as a development device, it will opt-out from receiving automatic product firmware updates. This includes both locked firmware as well as released firmware.

  • deviceId REQUIRED String

    Device ID

  • productIdOrSlug REQUIRED String

    Product ID or slug

  • development REQUIRED Boolean

    Set to true to mark as development device

$ curl https://api.particle.io/products/:productIdOrSlug/devices/12345 \
       -d development=true \
       -d access_token=123abc
  • id String

    Device ID

  • development String

    Should now be true signaling that the device is now a development device

  • updated_at Date

    Timestamp representing the last time the deivce was updated in ISO8601 format

PUT /v1/devices/12345
HTTP/1.1 200 OK
{
  "id": "0123456789abcdef01234567",
  "development": true
  "updated_at": "2017-03-10T20:21:49.059Z"
}

Unmark product development device

PUT /v1/products/:productIdOrSlug/devices/:deviceId

Unmark a device in a product fleet as a development device. Once unmarked, the device will opt-in to receiving automatic product firmware updates. This includes both locked firmware as well as released firmware.

  • deviceId REQUIRED String

    Device ID

  • productIdOrSlug REQUIRED String

    Product ID or slug

  • development REQUIRED Boolean

    Set to false to unmark as development device

$ curl https://api.particle.io/products/:productIdOrSlug/devices/12345 \
       -d development=false \
       -d access_token=123abc
  • id String

    Device ID

  • development String

    Should now be false signaling that the device is not a development device

  • updated_at Date

    Timestamp representing the last time the deivce was updated in ISO8601 format

PUT /v1/devices/12345
HTTP/1.1 200 OK
{
  "id": "0123456789abcdef01234567",
  "development": false
  "updated_at": "2017-03-10T20:21:49.059Z"
}

Product Firmware

Get Product Firmware

GET /v1/products/:productIdOrSlug/firmware/:version

Get a specific version of product firmware

  • productIdOrSlug REQUIRED String

    Product ID or slug

  • version REQUIRED Number

    Version number of firmware to retrieve

$ curl "https://api.particle.io/v1/products/:productIdOrSlug/firmware/1?access_token=1234"
  • _id String

    The ID of the firmware

  • version Number

    The version number of the firmware

  • title String

    The title of the firmware

  • description String

    A description of the firmware

  • name String

    The firmware's file name

  • size Number

    The size of the firmware in bytes

  • current Boolean

    Whether the firmware is released as the product default

  • uploaded_on Date

    Timestamp of when the firmware was uploaded

  • product_id Number

    The ID of the product that owns the firmware

  • uploaded_by Object

    The user who uploaded the firmware

GET /v1/products/:productIdOrSlug/firmware/1
HTTP/1.1 200 OK
{
    "_id":"58c09bc7df2b9a4d223d9c22",
    "version":1,
    "title":"My Firmware",
    "description":"Sample firmware description",
    "name":"firmware.bin",
    "size":7952,
    "current":false
    "uploaded_on":"2017-03-09T00:03:19.181Z",
    "product_id":295,
    "uploaded_by":{
        "username":"jeff@particle.io",
        ...
    }
}

List all product firmwares

GET /v1/products/:productIdOrSlug/firmware

List all versions of product firmware

  • productIdOrSlug REQUIRED String

    Product ID or slug

$ curl "https://api.particle.io/v1/products/:productIdOrSlug/firmware?access_token=1234"
  • - Object[]

    An array of product firmware objects. See above for details on the firmware object.

GET /v1/products/:productIdOrSlug/firmware
HTTP/1.1 200 OK
[
     {
         "_id":"58c09bc7df2b9a4d223d9c22",
         "version":1,
         "title":"My Firmware",
         "description":"Sample firmware description",
         "name":"firmware.bin",
         "size":7952,
         "current":false
         "uploaded_on":"2017-03-09T00:03:19.181Z",
         "product_id":295,
         "uploaded_by":{
             "username":"jeff@particle.io",
             ...
         }
     },
     ...
]

Upload product firmware

POST /v1/products/:productIdOrSlug/firmware

Upload a new firmware version to a product

  • version REQUIRED Number

    The version number of the firmware binary you are uploading

  • title REQUIRED String

    Title of the firmware version. Handy for quickly identifying the firmware

  • file REQUIRED File

    A binary file encoded in multipart/form-data format containing the contents of the product firmware

  • productIdOrSlug REQUIRED String

    Product ID or slug

  • description String

    Optionally provide a description for the new firmware version

$ curl "https://api.particle.io/v1/products/:productIdOrSlug/firmware?access_token=1234" \
       -F file=@firmware.bin \
       -F version=1 \
       -F title=firmware
  • - Object

    The newly created firmware object. See above for details on the firmware object.

POST /v1/products/:productIdOrSlug/firmware
HTTP/1.1 201 Created
{
    "_id":"58c09bc7df2b9a4d223d9c22",
    "version":1,
    "title":"My Firmware",
    "description":"Sample firmware description",
    "name":"firmware.bin",
    "size":7952,
    "current":false
    "uploaded_on":"2017-03-09T00:03:19.181Z",
    "product_id":295,
    "uploaded_by":{
        "username":"jeff@particle.io",
        ...
    }
}

Edit product firmware

PUT /v1/products/:productIdOrSlug/firmware/:version

Edit a specific product firmware version

  • title String

    Provide a new title for the firmware

  • description String

    Provide a new description for the firmware

  • productIdOrSlug REQUIRED String

    Product ID or slug

$ curl -X PUT https://api.particle.io/v1/products/:productIdOrSlug/firmware/1 \
       -d title="New title" \
       -d description="New description" \
       -d access_token=1234
  • - Object

    The updated firmware object. See above for details on the firmware object.

PUT /v1/products/:productIdOrSlug/firmware/1
HTTP/1.1 200 OK
{
    "_id":"58c09bc7df2b9a4d223d9c22",
    "version":1,
    "title":"New title",
    "description":"New description",
    "name":"firmware.bin",
    "size":7952,
    "current":false
    "uploaded_on":"2017-03-09T00:03:19.181Z",
    "product_id":295,
    "uploaded_by":{
        "username":"jeff@particle.io",
        ...
    }
}

Download firmware binary

GET /v1/products/:productIdOrSlug/firmware/:version/binary

Retrieve and download the original binary of a version of product firmware.

  • productIdOrSlug REQUIRED String

    Product ID or slug

  • version REQUIRED Number

    Version number of firmware to retrieve

$ curl "https://api.particle.io/v1/products/:productIdOrSlug/firmware/1/binary?access_token=1234"
  • - File

    The binary file of the requested product firmware version

Release product firmware

PUT /v1/products/:productIdOrSlug/firmware/release

Release a version of firmware to the fleet of product devices. This will set the firmware as the product default, meaning all devices that are not individually locked to different versions of firmware will automatically download and run this version of firmware the next time they handshake with the cloud.

Note: In order to be released as the product default, the firmware must be running on at least one device in your product fleet.

  • version REQUIRED Number

    firmware version number to release to the fleet. current will be set to true for this version of product firmware.

  • productIdOrSlug REQUIRED String

    Product ID or slug

$ curl -X PUT https://api.particle.io/v1/products/:productIdOrSlug/firmware/release \
       -d version=1 \
       -d access_token=1234
  • - Object

    The released firmware object. See above for details on the firmware object.

PUT /v1/products/:productIdOrSlug/firmware/release
HTTP/1.1 200 OK
{
    "_id":"58c09bc7df2b9a4d223d9c22",
    "version":1,
    "title":"New title",
    "description":"New description",
    "name":"firmware.bin",
    "size":7952,
    "current":true
    "uploaded_on":"2017-03-09T00:03:19.181Z",
    "product_id":295,
    "uploaded_by":{
        "username":"jeff@particle.io",
        ...
    }
}

Libraries

The libraries endpoints are a little different as they follow the JSON API specification.

List libraries

GET /v1/libraries

List firmware libraries. This includes private libraries visibile only to the user.

  • Authorization REQUIRED String

    Access Token

  • filter String

    Search for libraries with this partial name

  • page "1"

    Page number

  • limit "10"

    Items per page (max 100)

  • sort "popularity"

    Sort order for results. Prefix with - for descending order.

    • name
    • installs
    • popularity
    • published
    • updated
    • created
    • official
    • verified
  • scope "all"

    Which subset of libraries to list.

    • all to retrieve public libraries and any private libraries belonging to the user
    • official to retrieve official public libraries
    • public to retrieve public libraries
    • mine to retrieve only public libraries belonging to the current user
    • private to retrieve only private libraries (belonging to the current user).
  • excludeScopes String

    Which subsets of libraries to avoid listing, separated by comma. Same values as scope.

  • architectures String

    Architectures to list, separated by comma. Missing means all architectures.

$ curl https://api.particle.io/v1/libraries?scope=official&sort=name&access_token=1234
GET /v1/libraries?limit=2
HTTP/1.1 200 OK
{
  "data": [
    {
      "type": "libraries",
      "id": "neopixel",
      "links": {
        "download": "https://library-archives.particle.io/libraries/neopixel/neopixel-0.0.10.tar.gz"
      },
      "attributes": {
        "name": "neopixel",
        "version": "0.0.10",
        "installs": 9125,
        "license": "GNU GPLv3",
        "author": "Adafruit, Technobly",
        "sentence": "An Implementation of Adafruit's NeoPixel Library for the Spark Core, Particle Photon, P1, Electron and RedBear Duo",
        "url": "https://github.com/technobly/sparkcore-neopixel",
        "repository": "https://github.com/technobly/sparkcore-neopixel.git",
        "architectures": [],
        "visibility": "public",
        "official": true,
        "mine": false,
        "verified": true
      }
    },
    {
      "type": "libraries",
      "id": "InternetButton",
      "links": {
        "download": "https://library-archives.particle.io/libraries/InternetButton/InternetButton-0.1.10.tar.gz"
      },
      "attributes": {
        "name": "InternetButton",
        "version": "0.1.10",
        "installs": 7660,
        "license": "LGPL",
        "author": "Richard Whitney ",
        "sentence": "Functions to make the Internet Button easy to use! If you have an original SparkButton, make sure to use `begin(1)`",
        "url": "https://github.com/spark/internetbutton",
        "repository": "https://github.com/spark/internetbutton.git",
        "architectures": [],
        "visibility": "public",
        "official": true,
        "mine": false
      }
    }
  ]
}

Get library details

GET /v1/libraries/:libraryName:

Get details for a firmware library.

  • Authorization REQUIRED String

    Access Token

  • libraryName REQUIRED String

    Name of library to retrieve (case insensitive)

  • version "latest"

    Version to retrieve. Defaults to the latest version.

  • scope "all"

    Which subset of versions to get.

    • all
    • public
    • private
  • data object

    The library version in JSON API format

    • id string

      The name of the library

    • links.download string

      The URL to download the files for this library

    • attributes string

      Additional meta data for the library. Not all fields are available for every library.

GET /v1/libraries/internetbutton
HTTP/1.1 200 OK
{
  "data": {
    "type": "libraries",
    "id": "InternetButton",
    "links": {
      "download": "https://library-archives.particle.io/libraries/InternetButton/InternetButton-0.1.10.tar.gz"
    },
    "attributes": {
      "name": "InternetButton",
      "version": "0.1.10",
      "installs": 7660,
      "license": "LGPL",
      "author": "Richard Whitney richard@particle.io",
      "sentence": "Functions to make the Internet Button easy to use! If you have an original SparkButton, make sure to use begin(1)",
      "url": "https://github.com/spark/internetbutton",
      "repository": "https://github.com/spark/internetbutton.git",
      "architectures": [],
      "visibility": "public",
      "official": true,
      "mine": false
    }
  }
}

Get library versions

GET /v1/libraries/:libraryName:/versions

Get details for all versions of a firmware library.

  • Authorization REQUIRED String

    Access Token

  • libraryName REQUIRED String

    Name of library to retrieve (case insensitive)

  • scope "all"

    Which subset of versions to get.

    • all
    • public
    • private
GET /v1/libraries/internetbutton/versions
HTTP/1.1 200 OK
{
  "data": [
    {
      "type": "libraries",
      "id": "InternetButton",
      "links": {
        "download": "https://library-archives.particle.io/libraries/InternetButton/InternetButton-0.1.9.tar.gz"
      },
      "attributes": {
        "name": "InternetButton",
        "version": "0.1.9",
        "installs": 7660,
        "license": "LGPL",
        "author": "Richard Whitney richard@particle.io",
        "sentence": "Functions to make the Internet Button easy to use! If you have an original SparkButton, make sure to use begin(1)",
        "url": "https://github.com/spark/internetbutton",
        "repository": "https://github.com/spark/internetbutton.git",
        "architectures": [],
        "visibility": "public",
        "official": true,
        "mine": false
      }
    },
    {
      "type": "libraries",
      "id": "InternetButton",
      "links": {
        "download": "https://library-archives.particle.io/libraries/InternetButton/InternetButton-0.1.10.tar.gz"
      },
      "attributes": {
        "name": "InternetButton",
        "version": "0.1.10",
        "installs": 7660,
        "license": "LGPL",
        "author": "Richard Whitney richard@particle.io",
        "sentence": "Functions to make the Internet Button easy to use! If you have an original SparkButton, make sure to use begin(1)",
        "url": "https://github.com/spark/internetbutton",
        "repository": "https://github.com/spark/internetbutton.git",
        "architectures": [],
        "visibility": "public",
        "official": true,
        "mine": false
      }
    }
  ]
}

Upload library version

POST /v1/libraries/:libraryName:

Upload a private version of a firmware library. If the library doesn't exist it is created.

The library will be validated and an error response returned if invalid.

  • Authorization REQUIRED String

    Access Token

  • libraryName REQUIRED String

    Name of library to retrieve (case insensitive)

  • archive REQUIRED File

    A tar-gzip archive of all the files for the library.

    The meta data like name and version is taken from library.properties. See the example library for other files to include.

$ curl -F archive=@library.tar.gz https://api.particle.io/v1/libraries?access_token=1234
POST /v1/libraries
HTTP/1.1 201 Created
{
  "data": {
    "type": "libraries",
    "id": "testlib43",
    "links": {
      "download": "https://library-archives.particle.io/libraries/testlib43/testlib43-1.0.2.tar.gz"
    },
    "attributes": {
      "name": "testlib43",
      "version": "1.0.2",
      "license": "MIT",
      "author": "JV",
      "sentence": "one sentence description of this library",
      "url": "the URL of the project, like https://github.com/mygithub_user/my_repo",
      "repository": "mygithub_user/my_repo",
      "architectures": [],
      "visibility": "private"
    }
  }
}

Make a library version public

PATCH /v1/libraries/:libraryName:

Make the latest private version of a firmware library public. You must do this before others can access your uploaded library.

  • Authorization REQUIRED String

    Access Token

  • libraryName REQUIRED String

    Name of library to retrieve (case insensitive)

  • visibility REQUIRED String

    Must be set to public to publish a library.

$ curl -X PATCH -d visibility=public https://api.particle.io/v1/libraries/testlib43?access_token=1234
PATCH /v1/libraries/testlib43
HTTP/1.1 200 OK
{
  "data": {
    "type": "libraries",
    "id": "testlib43",
    "links": {
      "download": "https://library-archives.particle.io/libraries/testlib43/testlib43-1.0.2.tar.gz"
    },
    "attributes": {
      "name": "testlib43",
      "version": "1.0.2",
      "license": "MIT",
      "author": "JV",
      "sentence": "one sentence description of this library",
      "url": "the URL of the project, like https://github.com/mygithub_user/my_repo",
      "repository": "mygithub_user/my_repo",
      "architectures": [],
      "visibility": "public"
    }
  }
}

Products

List Products

GET /v1/products

List products the currently authenticated user has access to.

  • Authorization REQUIRED String

    Access Token

  • products Object[]

    List of Products

GET /v1/products
HTTP/1.1 200 OK
{
  "products": [{
      "id": "0123456789abcdef01234567",
          "product_id": 6,
          "name": "Photon",
          "slug": "photon",
          "description": "Traveling Light",
          "type": "Consumer",
          "hardware_version": "v1.0.0",
          "config_id": "0123456789abcdef01234567",
          "organization": "0123456789abcdef01234567",
          "platform_id": 6,
          "requires_activation_codes": false
  }]
}

Retrieve a product

GET /v1/products/:productIdOrSlug

Retrieve details for a product.

  • productIdOrSlug REQUIRED String

    Product ID or Slug

  • product Object[]
    • id String

      Product Unique ID

    • product_id Number

      Product Firmware ID

    • name String

      Product Name

    • slug String

      URL compatible version of name

    • description String
    • platform_id Number

      Product Platform ID

    • type String
    • hardware_version String
    • config_id String
    • organization String

      Organization Unique ID

    • requires_activation_codes Boolean
GET /v1/products/photon
HTTP/1.1 200 OK
{
  "product": [
      {
          "id": "0123456789abcdef01234567",
          "product_id": 6,
          "name": "Photon",
          "slug": "photon",
          "description": "Traveling Light",
          "type": "Consumer",
          "hardware_version": "v1.0.0",
          "config_id": "0123456789abcdef01234567",
          "organization": "0123456789abcdef01234567",
          "platform_id": 6,
          "requires_activation_codes": false
      }
  ]
}

List team members

GET /v1/products/:productIdOrSlug/team

List all team members that are part of a given product

  • productIdOrSlug REQUIRED String

    Product ID or slug

$ curl "https://api.particle.io/v1/products/:productIdOrSlug/team?access_token=123abc"
  • - Object[]

    An array of team members

    • _id String

      ID of the team member

    • username String

      Username of the team member

GET /v1/products/:productIdOrSlug/team
HTTP/1.1 200 OK
[
        {
            "_id":"9980222caf8bad191600019b",
            "username":"jeff@particle.io"
        },
        ...
]

Invite team member

POST /v1/products/:productIdOrSlug/team

Invite a new member to a product team. Invitee will receive an email with a link to accept the invitation and join the team.

  • productIdOrSlug REQUIRED String

    Product ID or Slug

  • username REQUIRED String

    Username of the invitee. Must be a valid email associated with an Particle user

$ curl "https://api.particle.io/products/:productIdOrSlug/team" \
       -d username=test@example.com \
       -d access_token=123abc
  • - Object

    The invited user

    • orgInvites Object[]

      An array of pending invitations to product teams

    • orgs Object[]

      An array of product teams a user currently belongs

POST /v1/products/:productIdOrSlug/team
HTTP/1.1 200 OK
{
      "_id":"12351fc561a46af606000abc",
      "created_at":"2014-08-08T19:06:45.000Z",
      "updated_at":"2017-03-14T22:38:40.028Z",
      "username":"jeff.m.eiden@gmail.com",
      "orgInvites": [
          {
             "org":"456bcd",
             "slug":"my-product",
             "product":"3333999",
             "name":"My Product",
             "invitedBy":"jeff@particle.io",
             "invitedOn":"2017-01-18T18:53:00.235Z"
          }
       ],
       "orgs":[]
}

Remove team member

DELETE /v1/products/:productIdOrSlug/team/:username

Remove a current team member.

  • Authorization REQUIRED String

    Access Token

  • productIdOrSlug REQUIRED String

    Product ID or Slug

  • username REQUIRED String

    Username of the team member to be removed

DELETE /v1/products/photon/team/jeff@particle.io
HTTP/1.1 204 NO CONTENT

Customers

Create a customer - Access Token

POST /v1/products/:productIdOrSlug/customers

Create a customer for a product. An access token of a user that belongs to the product is required.

  • productIdOrSlug REQUIRED String

    Product ID or Slug

  • email REQUIRED String

    Email Address

  • password REQUIRED String

    Password

POST /v1/products/photon/customers
HTTP/1.1 201 OK
{
    "token_type": "bearer",
    "access_token": "92b6d13edaab936b016d54266a46134160f087e8",
    "refresh_token": "14b4d13edaab634b019d54265a46132160f017e8",
    "expires_in": 7776000
}

Create a customer - Client Credentials

POST /v1/products/:productIdOrSlug/customers

Create a customer for a product using OAuth client credentials grant type. This is the way you should hit the POST customers endpoint if you are creating customers from your server (two-legged authentication), or from a mobile application. In this case, you may create a customer without a password, by passing the no_password: true flag.

  • productIdOrSlug REQUIRED String

    Product ID or Slug

  • client_id REQUIRED String

    OAuth client ID (HTTP basic auth header)

  • client_secret REQUIRED String

    OAuth client secret (HTTP basic auth header)

  • email REQUIRED String

    Email Address

  • password String

    Password

  • no_password Boolean

    For two-legged authentication, only required if you are creating password-less customers.

POST /v1/products/photon/customers
HTTP/1.1 201 OK
{
    "token_type": "bearer",
    "access_token": "92b6d13edaab936b016d54266a46134160f087e8",
    "refresh_token": "14b4d13edaab634b019d54265a46132160f017e8",
    "expires_in": 7776000
}

Create a customer - Implicit

POST /v1/products/:productIdOrSlug/customers

Create a customer for a product using OAuth implicit grant type. This is the way you should hit the POST customers endpoint if you are creating customers from a web browser. After a successful POST, the customer access token will be appended as a hash to the redirect URI associated with the client credentials provided. For this grant type, you must also pass response_type: token.

  • productIdOrSlug REQUIRED String

    Product ID or Slug

  • client_id REQUIRED String

    OAuth client ID (HTTP basic auth header)

  • email REQUIRED String

    Email Address

  • password REQUIRED String

    Password

  • response_type String

    OAuth response type. Should only be included for implicit grant type and should be set to token.

POST /v1/products/photon/customers
HTTP/1.1 201 OK

List Customers for a Product

GET /v1/products/:productIdOrSlug/customers

List Customers for a product.

  • Authorization REQUIRED String

    Access Token

  • productIdOrSlug REQUIRED String

    Product ID or Slug

  • customers Object[]

    List of Customers

    • id String

      Customer ID

    • full_name String

      Name

    • username String

      Username

    • devices String[]

      List of Device IDs

  • devices Object[]

    List of Devices that belong to those customers

    • id String

      Device ID

    • product_id Number

      Product ID

    • last_ip_address String

      Last known IP Address

    • firmware_version Number

      Firmware Version

    • online Boolean

      Whether the device is currently online or not

GET /v1/products/photon
HTTP/1.1 200 OK
{
  "customers": [
    {
      "id": "01234567890ABCDEF",
      "full_name": "Bob Loblaw",
      "username": "bob@loblaw.net",
      "devices": ["0123456789abcdef01234567"]
    }
  ],
  "devices": [
      {
          "id": "0123456789abcdef01234567",
          "product_id": 6,
          "last_ip_address": "127.0.0.1",
          "firmware_version": 1,
          "online": true
      }
  ],
  "meta": {
      "total_pages": 4
  }
}

Generate a customer scoped access token

POST /oauth/token

Creates a token scoped to a customer for your organization.

You must give a valid product client ID and secret in HTTP Basic Auth.

  • Authorization REQUIRED String

    Client ID and Secret.

  • grant_type REQUIRED String

    OAuth grant type. Must be client_credentials.

  • expires_in Number

    How many seconds the token will be valid for. 0 means forever. Short lived tokens are better for security.

  • expires_at Date

    When should the token expire? This should be an ISO8601 formatted date string.

  • scope String

    The customer to scope this token to. Format of customer=jane@example.com.

$ curl https://api.particle.io/oauth/token \
       -u my-org-client-1234:long-secret \
       -d grant_type=client_credentials \
       -d "scope=customer=jane@example.com"
  • access_token String

    The magical token you will use for all the other requests

  • token_type String
  • expires_in String

    The number of seconds this token is valid for. 0 means forever.

  • refresh_token String

    Used to generate a new access token when it has expired.

POST /oauth/token
HTTP/1.1 200 OK
{
  "access_token": "254406f79c1999af65a7df4388971354f85cfee9",
  "token_type": "bearer",
  "expires_in": 7776000,
  "refresh_token": "b5b901e8760164e134199bc2c3dd1d228acf2d90"
}

Update customer password

PUT /v1/products/:productIdOrSlug/customers/:customerEmail

Update the account password for a customer. Only relevant for non-shadow customers that have a password saved in Particle's system.

  • productIdOrSlug REQUIRED String

    Product ID or Slug

  • customerEmail REQUIRED String

    Email of the customer account that you'd like to remove

  • password REQUIRED String

    The new password for the customer

$ curl -X PUT "https://api.particle.io/v1/products/:productIdOrSlug/customers/test@company.com" \
       -d access_token=123abc \
       -d password=newpassword
PUT /v1/products/:productIdOrSlug/customers/:customerEmail
HTTP/1.1 200 OK

{"ok": true}

Delete a customer

DELETE /v1/product/:productIdOrSlug/customers/:customerEmail

Delete a customer in a product. Will also revoke all of this customer's access tokens, pending device claim codes and activation codes.

  • productIdOrSlug REQUIRED String

    Product ID or Slug

  • customerEmail REQUIRED String

    Email of the customer account that you'd like to remove

$ curl -X DELETE "https://api.particle.io/v1/products/:productIdOrSlug/customers/test@company.com" \
       -d access_token=123abc
DELETE /v1/products/:productIdOrSlug/customers/:customerEmail
HTTP/1.1 200 OK

{"ok": true}