Submit sensor readings
Stores readings from a device. Send one reading, or up to 500 at once as { "readings": [...] }. Batch them: a gateway that buffers readings and posts every 30 to 60 seconds uses a small fraction of the requests of one that posts each reading as it is taken.
https://app.xplantpro.com/write:sensor_readingsAccepts a device tokenThe response mirrors the request — one reading back for one reading sent, a list for a batch.
To make a retry safe, send external_id and recorded_at on every reading. A reading that repeats one already stored for the same device is skipped rather than stored twice, and is left out of the response — so a skipped single reading returns ok: true with no data.
One bad reading refuses the whole batch: if any reading fails validation, names a device or room outside the workspace, or comes from a device that is paused or retired, nothing in the request is stored.
Readings have a budget of their own on top of the request limit: 5,000 per key or device token and 10,000 per workspace in any five minutes. Over it, the answer is 429 RATE_LIMIT_EXCEEDED with a Retry-After header.
See also: Sensors and devices.
Request body
The body is one of:
A single object
| Field | Type | Required | Description |
|---|---|---|---|
device_id | string (uuid) | Yes | The device that took the reading. |
type | "temperature" | "humidity" | "ph" | "co2" | "light" | "other" | Yes | What was measured. |
value | number | Yes | The measured value. |
unit | string | Yes | The unit the value is in, for example celsius or %. 1–20 characters. |
room_id | string (uuid) | No | The growing room the reading describes. Must be a room in the workspace. |
recorded_at | string (date-time) | No | When the reading was taken, as an ISO 8601 timestamp in UTC ending in Z. Defaults to the time the request arrives. Required when you send external_id. |
notes | string | No | A free-text note. Up to 500 characters. |
external_id | string | No | Your own id for the reading. A reading with the same device, external_id and recorded_at as one already stored is skipped, so a retried batch is not stored twice. 1–200 characters. |
A batch: readings
| Field | Type | Required | Description |
|---|---|---|---|
readings | object[] | Yes | Between 1 and 500 readings. Up to 500 items. |
readings[].device_id | string (uuid) | Yes | The device that took the reading. |
readings[].type | "temperature" | "humidity" | "ph" | "co2" | "light" | "other" | Yes | What was measured. |
readings[].value | number | Yes | The measured value. |
readings[].unit | string | Yes | The unit the value is in, for example celsius or %. 1–20 characters. |
readings[].room_id | string (uuid) | No | The growing room the reading describes. Must be a room in the workspace. |
readings[].recorded_at | string (date-time) | No | When the reading was taken, as an ISO 8601 timestamp in UTC ending in Z. Defaults to the time the request arrives. Required when you send external_id. |
readings[].notes | string | No | A free-text note. Up to 500 characters. |
readings[].external_id | string | No | Your own id for the reading. A reading with the same device, external_id and recorded_at as one already stored is skipped, so a retried batch is not stored twice. 1–200 characters. |
Example
curl -X POST https://app.xplantpro.com/api/v1/sensor-readings \
-H "Authorization: Bearer $XPLANT_DEVICE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"readings": [
{
"device_id": "8e3b1f52-6c0d-4a7e-9b21-5f4d8c2a7e13",
"type": "temperature",
"value": 24.1,
"unit": "°C",
"room_id": "2c6f9a41-7d3e-4b8a-a1c5-9e0d4f7b3a26",
"recorded_at": "2026-09-25T14:00:00.000Z",
"external_id": "shelf3-temperature-20260925T140000Z"
},
{
"device_id": "8e3b1f52-6c0d-4a7e-9b21-5f4d8c2a7e13",
"type": "humidity",
"value": 88,
"unit": "%",
"room_id": "2c6f9a41-7d3e-4b8a-a1c5-9e0d4f7b3a26",
"recorded_at": "2026-09-25T14:00:00.000Z",
"external_id": "shelf3-humidity-20260925T140000Z"
}
]
}'Response
201 with { "ok": true, "data": … }. data holds the result.
{
"ok": true,
"data": [
{
"id": "f1a7c3e9-2b4d-4f6a-8c0e-3d5b7a9c1e24",
"device_id": "8e3b1f52-6c0d-4a7e-9b21-5f4d8c2a7e13",
"team_id": "5d2e8b17-9c4a-4e3f-b6d0-1a7c9e2f4b83",
"room_id": "2c6f9a41-7d3e-4b8a-a1c5-9e0d4f7b3a26",
"type": "temperature",
"value": 24.1,
"unit": "°C",
"recorded_at": "2026-09-25T14:00:00.000Z",
"notes": null,
"created_at": "2026-09-25T14:00:31.000Z"
},
{
"id": "0b9d4e2f-6a8c-4d1e-9f3a-7c5e1b8d2a46",
"device_id": "8e3b1f52-6c0d-4a7e-9b21-5f4d8c2a7e13",
"team_id": "5d2e8b17-9c4a-4e3f-b6d0-1a7c9e2f4b83",
"room_id": "2c6f9a41-7d3e-4b8a-a1c5-9e0d4f7b3a26",
"type": "humidity",
"value": 88,
"unit": "%",
"recorded_at": "2026-09-25T14:00:00.000Z",
"notes": null,
"created_at": "2026-09-25T14:00:31.000Z"
}
]
}| Response header | Meaning |
|---|---|
X-Request-Id | Identifies this request. Include it when you contact support. |
Errors
| Status | Code | When |
|---|---|---|
400 | VALIDATION_ERROR | The request body is not valid JSON. |
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 | A device_id or room_id in the request is not in the workspace. Nothing was stored. |
409 | DEVICE_INGEST_DISABLED | A device in the request is paused or retired, so its readings are refused. error names it; nothing was stored. |
422 | VALIDATION_ERROR | A reading failed validation. error names the first field, for example readings.0.value: Expected number, received string. |
429 | RATE_LIMIT_EXCEEDED | Too many requests for this key, device token or workspace. Wait Retry-After seconds. |
500 | READINGS_CREATE_FAILED | The readings could not be stored. Retry the same request — readings that carry external_id are not stored twice. |
Branch on code, never on the error text. See Errors.
List sensor readings
The workspace's environmental readings, newest first, a page at a time. Narrow them to one device, one growing room or one kind of measurement, and use since and until to fetch only the readings taken within a window.
List equipment
The workspace's equipment library, newest first, with each item's calibration and maintenance due dates. Filter by category and status; with neither you get every item, archived ones included.