Data API
Use an API key to build your own dashboard against hosted Pulsync. The key can read the latest value for each device, subscribe to live updates for specific devices and fields, and send actions. It cannot manage pairing codes, firmware, or other portal settings.
Self-hosted servers do not issue API keys. They use the admin password described below.
Hosted: API keys
Create a key in the portal. It is shown once. Store it immediately. A key looks like psk_ plus 40 hex characters and acts as your workspace. Revoke it in the portal if it leaks. A revoked key stops working immediately.
Send it on every request:
Authorization: Bearer psk_… A key that calls a portal route (anything that is not /api/v1) gets 403.
Current snapshot
online is true when last_seen is within the last 2 minutes. data is the latest telemetry object, or null if the device has not sent any.
curl https://pulsync.dev/api/v1/devices
-H "Authorization: Bearer psk_…" {
"devices": [
{
"id": "DEVICE_ID",
"name": "Kitchen",
"last_seen": "2026-10-12T18:00:00.000Z",
"online": true,
"data": { "temperature": 25.3, "humidity": 60 },
"timestamp": "2026-10-12T18:00:00.000Z"
}
]
} One device:
curl https://pulsync.dev/api/v1/devices/DEVICE_ID
-H "Authorization: Bearer psk_…" The body is that same object, not wrapped in devices. Unknown devices, and devices in another workspace, are 404.
Send an action
curl -X POST https://pulsync.dev/api/v1/devices/DEVICE_ID/actions
-H "Authorization: Bearer psk_…"
-H "Content-Type: application/json"
-d '{"command":"set_led","payload":{"value":true}}' command is a name the sketch registered (set_led, and so on). reboot is built into the library since 0.3.4 and does not need a handler. payload is optional and defaults to {}. The device receives it over MQTT when it is connected.
Live socket
Connect to wss://pulsync.dev/api/v1/live. Nothing is pushed until you subscribe. A browser cannot set Authorization on a WebSocket, so pass the key as a query parameter. A backend can use the header instead.
const ws = new WebSocket(`wss://pulsync.dev/api/v1/live?access_token=${key}`);
ws.onopen = () => {
ws.send(JSON.stringify({
type: "subscribe",
devices: ["DEVICE_ID"],
fields: ["temperature"]
}));
};
ws.onmessage = (msg) => {
const evt = JSON.parse(msg.data);
if (evt.type === "device_data") console.log(evt.data);
}; devices is required. fields is optional. Omit fields to receive the whole telemetry object. A later subscribe replaces the previous one. { "type": "unsubscribe" } clears it and the socket goes quiet again.
The server answers { "type": "subscribed", "devices": […], "fields": […] }. Device ids that are not in your workspace are left out of that list.
type | When |
|---|---|
connected | Once, on connect, before any data |
subscribed | After subscribe or unsubscribe |
device_data | A subscribed device sent telemetry. If you set fields, data contains only those top-level keys. The message is skipped when none of them are present. |
heartbeat | A subscribed device checked in |
error | The subscribe message was not valid |
Rate limits
Counted per key, per 60 seconds. Data pushed down an open socket is not counted.
| Call | Limit | Over the limit |
|---|---|---|
| Snapshot reads | 60 | HTTP 429 and Retry-After |
| Actions | 30 | HTTP 429 and Retry-After |
| Socket opens | 10, and at most 5 open at once | Close code 4429 |
A bad or revoked key is HTTP 401, or socket close code 4401.
Self-hosted: admin gate
The self-hosted server exposes the same telemetry, but device-management routes are mounted under /api/device/ and share the single ADMIN_PASSWORD gate — there are no per-key tokens.
If ADMIN_PASSWORD is unset (the default on a trusted LAN), the endpoints are open and you can call them directly:
curl "http://pulsync.local:3456/api/device/devices/DEVICE_ID/data?limit=100" If ADMIN_PASSWORD is set, log in first to get a session cookie, then send that cookie on later calls:
# 1. Log in — stores the ps_admin cookie in a cookie jar
curl -c jar.txt -X POST http://pulsync.local:3456/api/device/admin/login
-H "Content-Type: application/json"
-d '{"password": "your-admin-password"}'
# 2. Use the cookie to pull data
curl -b jar.txt "http://pulsync.local:3456/api/device/devices/DEVICE_ID/data?limit=100" List devices to find a device ID:
curl -b jar.txt http://pulsync.local:3456/api/device/devices
# → { "devices": [ ... ], "ws_connections": N } No API keys in self-hosted. Auth is one shared admin password plus a session cookie, which is awkward for headless scripts. On a trusted LAN, leaving the gate open is the simplest option. If you expose the server beyond your network, set
ADMIN_PASSWORDand put it behind a TLS proxy.
Query parameters
The self-hosted data endpoint accepts:
| Parameter | Default | Description |
|---|---|---|
limit | 100 | Max number of data points to return (hosted caps this at 1000) |
since | (none) | ISO 8601 timestamp — return only points received after this time |
Example:
?limit=500&since=2026-09-01T00:00:00Z Response shape
The self-hosted telemetry endpoint returns each point newest-first. data is the payload the device sent:
{
"data": [
{
"data": { "temperature": 25.3, "humidity": 60 },
"timestamp": "2026-09-07T10:42:11.000Z"
},
{
"data": { "temperature": 25.1, "humidity": 61 },
"timestamp": "2026-09-07T10:42:06.000Z"
}
]
} Points are newest-first. data is whatever key-value payload the device sent via Pulsync.send().
Live data (WebSocket)
Polling the data endpoint gives you history. On the self-hosted server you can also receive updates the moment a device sends them by connecting to the live WebSocket instead of polling in a loop.
Connect
ws://pulsync.local:3456/api/live On connect the server sends a welcome frame, then pushes an event every time something happens on any device:
const ws = new WebSocket("ws://pulsync.local:3456/api/live");
ws.onmessage = (msg) => {
const evt = JSON.parse(msg.data);
if (evt.type === "device_data" && evt.deviceId === MY_DEVICE_ID) {
console.log("new data:", evt.data, "at", evt.timestamp);
}
}; Event types
type | Fields | Meaning |
|---|---|---|
connected | tenantsScoped | Sent once on connect |
device_data | deviceId, data, timestamp | New telemetry — data is the payload the device sent |
heartbeat | deviceId, status, timestamp | Device checked in |
enrolled | deviceId, pairingCode | A device enrolled |
ota_status | deviceId, status, version | Firmware offered or applied |
command_sent | deviceId, command, payload | A command was dispatched |
Things to know
- It’s a firehose. Every connected client receives events for all devices — there’s no per-device subscription. Filter by
deviceIdin your handler. - No history on connect. The stream only carries events that happen after you connect. For past data, use the REST endpoint above.
- The stream is not gated by
ADMIN_PASSWORD. Unlike the REST management routes,/api/liveaccepts any connection. That’s fine on a trusted LAN, but if you expose the server, anyone who can reach it can read the live stream. Put the server behind a TLS reverse proxy with its own access control if it’s reachable beyond your network.
Other operations
On a self-hosted server the admin session can also drive devices:
| Action | Method + path |
|---|---|
| List devices | GET /devices |
| Device details | GET /devices/:id |
| Query telemetry | GET /devices/:id/data |
| Push config | PUT /devices/:id/config — body { "key": value, ... } |
| Send a command | POST /devices/:id/command — body { "command": "...", "payload": {} } |
Prefix those paths with /api/device. Config changes and commands reach the device over MQTT (on the next heartbeat, or immediately if the device is connected). Hosted dashboards use /api/v1 above instead of these routes.
Keep keys secret
API keys and admin passwords are credentials — treat them like passwords. Don’t commit them to source control or ship them in frontend code; keep them in environment variables on a server you control. Hosted keys are shown once at creation, so store them right away, and revoke any key you suspect is leaked.