Particle API JS

12.0.2 verified Sat Apr 25 auth: no javascript

JavaScript library for the Particle Cloud API, usable in Node.js (v16+) and browser environments. Current stable version is v12.0.2, released via npm. Actively maintained with releases every few months. Written in TypeScript with full type declarations. Covers all Particle IoT device interactions: authentication, device listing, variable/function access, event streaming, firmware management, and more. Differentiates from raw fetch/axios by wrapping the entire Particle REST API with typed request options and responses, handling authentication and pagination internally. Ships both ESM and UMD builds (CDN via jsDelivr). Major v12.0.0 was a TypeScript migration; v11.0.0 removed token list/delete APIs and query access_token support.

Common errors

error Error: Cannot find module 'particle-api-js' ↓

cause Package not installed via npm

fix

Run npm install particle-api-js or yarn add particle-api-js

error TypeError: particle.listDevices is not a function ↓

cause Incorrect import (likely named import instead of default)

fix

Use import Particle from 'particle-api-js' then new Particle()

Warnings

deprecated deleteAccessToken and listAccessTokens methods are deprecated in v11.0.0 and removed from v12? ↓

fix Use Particle Cloud API directly or alternative authentication flow.

breaking Query string access_token parameter is no longer supported. ↓

fix Pass token via Authorization header (handled automatically via constructor auth option).

gotcha In browsers, using the CDN builds (<script> tag) exposes global variable `Particle` but TypeScript types are not available. ↓

fix Use ES module import from npm for typed usage.

Install

npm install particle-api-js

yarn add particle-api-js

pnpm add particle-api-js

Imports

Particle
wrong
```
const { Particle } = require('particle-api-js')
```
correct
```
import Particle from 'particle-api-js'
```
Default export is the Particle class. Named export for class was removed in v12.0.0 TypeScript migration.
DeviceInfo
wrong
```
import { DeviceInfo } from 'particle-api-js'
```
correct
```
import type { DeviceInfo } from 'particle-api-js'
```
Type imports should use `import type` to avoid runtime inclusion. Available since v12.0.0.

LoginResponse

import type { LoginResponse } from 'particle-api-js'

Quickstart

Shows how to instantiate Particle client, authenticate via login, list devices, and fetch a single device with full TypeScript typing.

import Particle from 'particle-api-js';
import type { DeviceInfo, LoginResponse } from 'particle-api-js';

const particle = new Particle({ auth: process.env.PARTICLE_TOKEN ?? '' });

async function listDevices() {
  try {
    const response = await particle.listDevices();
    console.log('Devices:', response.body);
  } catch (error) {
    console.error('Error:', error);
  }
}

async function loginAndCall() {
  const loginResp = await particle.login({
    username: process.env.EMAIL ?? '',
    password: process.env.PASSWORD ?? ''
  });
  console.log('Token:', loginResp.body.access_token);
  // Re-create client with new token
  const particleAuthed = new Particle({ auth: loginResp.body.access_token });
  const device = await particleAuthed.getDevice({ deviceId: 'abc123' });
  console.log('Device name:', device.body.name);
}

listDevices();