Send a heartbeat
Tells xPlant the device is alive and stamps its last-seen time. xPlant shows a device as offline once 15 minutes pass without hearing from it, so send a heartbeat every minute or two. The request has no body.
https://app.xplantpro.com/write:devicesAccepts a device tokenA repeated heartbeat does no harm, so a retry needs no Idempotency-Key. A device token may send heartbeats only for its own device.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
deviceId | string (uuid) | Yes | The device's id. |
Example
curl -X POST https://app.xplantpro.com/api/v1/devices/5f7a9c1e-3b5d-4f7a-9c1e-3b5d7f9a1c3e/heartbeat \
-H "Authorization: Bearer $XPLANT_DEVICE_TOKEN"Response
200 with { "ok": true, "data": … }. data holds the result.
| Field | Type | Required | Description |
|---|---|---|---|
received_at | string | Yes | When the heartbeat was recorded, as an ISO 8601 timestamp. |
{
"ok": true,
"data": {
"received_at": "2026-09-25T14:05:00.000Z"
}
}| Response header | Meaning |
|---|---|
X-Request-Id | Identifies this request. Include it when you contact support. |
Errors
| Status | Code | When |
|---|---|---|
401 | UNAUTHORIZED | The key is missing, malformed or revoked, or its owner is no longer a member of the workspace. |
402 | PAID_PLAN_REQUIRED | The workspace has no paid plan. Connecting devices is included with every paid plan. |
403 | FORBIDDEN | The key lacks a scope this operation requires, or its owner's current role in the workspace cannot use it — a key never does more than its owner can in xPlant. error names the scope, and for a role, the role it needs. |
403 | DEVICE_TOKEN_WRONG_DEVICE | A device token was used to write about a device other than its own. |
404 | NOT_FOUND | No device with this id is registered in the key's workspace. |
429 | RATE_LIMIT_EXCEEDED | Too many requests for this key, device token or workspace. Wait Retry-After seconds. |
500 | DEVICE_UPDATE_FAILED | The heartbeat could not be recorded. Retry, or send the next one on schedule. |
Branch on code, never on the error text. See Errors.
Register a device
Adds a sensor, controller or gateway to the workspace so it can send heartbeats, readings and events. Then mint a device token for it and put that token on the device, rather than a workspace key.
List device tokens
Every token minted for the device, active and revoked, newest first. Each carries its prefix, name, status and last use — what you need to tell tokens apart and decide which to revoke. The secret itself is never returned after the token is minted.