Record a label scan
Records that a code was scanned — where, and when. Resolving a label only reads; this writes the visit down.
https://app.xplantpro.com/write:label_scansHonours Idempotency-KeySend plant_id or explant_id when you already know what the code belongs to, for example from resolving it first; the scan is then marked resolved. A scan that matched nothing is still worth recording.
Scans are append-only: a correction is another scan. Send an Idempotency-Key so a scanner retrying on a patchy connection records one visit rather than two.
Send an Idempotency-Key header to make retries safe: a repeat with the same key within 24 hours returns the first response instead of writing twice. See Idempotency.
Headers
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | No | Any unique string you choose per logical write. A retry carrying the same key within 24 hours returns the first result instead of writing again. Scoped to your API key and this operation. 8–255 characters. Must match ^[A-Za-z0-9._:~-]+$. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
barcode | string | Yes | The code exactly as the scanner read it. 1–512 characters. |
plant_id | string (uuid) | No | The plant the code belongs to, when you already know it — for example from resolving the label first. It must be in this workspace. |
explant_id | string (uuid) | No | The explant the code belongs to, when you already know it. It must be in this workspace. |
context | string | No | Where the scan happened, in your own words — a bench, a shelf, a growth room door. Up to 120 characters. |
scanned_at | string (date-time) | No | When the scan happened, in UTC with a trailing Z, such as 2026-09-25T08:30:00Z. A timestamp with an offset is refused. Defaults to when xPlant receives it. |
Example
curl -X POST https://app.xplantpro.com/api/v1/label-scans \
-H "Authorization: Bearer $XPLANT_API_KEY" \
-H "Idempotency-Key: scanner-3-0f2a7c91" \
-H "Content-Type: application/json" \
-d '{
"barcode": "LINE-0412",
"explant_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"context": "Growth room 1, shelf C1",
"scanned_at": "2026-09-25T08:30:00Z"
}'Response
201 with { "ok": true, "data": … }. data holds the result.
| Field | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | Yes | — |
barcode | string | Yes | The code as the scanner read it. |
resolved | boolean | Yes | True when the scan was recorded against a plant or explant — that is, when plant_id or explant_id was sent. |
plantId | string | null (uuid) | Yes | — |
explantId | string | null (uuid) | Yes | — |
context | string | null | Yes | Where the scan happened, as it was described. |
scannedAt | string | Yes | When the scan happened: the scanned_at that was sent, or when xPlant received it. |
{
"ok": true,
"data": {
"id": "d4c3b2a1-f6e5-4d7c-8b9a-0f1e2d3c4b5a",
"barcode": "LINE-0412",
"resolved": true,
"plantId": null,
"explantId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"context": "Growth room 1, shelf C1",
"scannedAt": "2026-09-25T08:30:00+00:00"
}
}| Response header | Meaning |
|---|---|
Idempotent-Replay | true when this response is a replay of an earlier request with the same Idempotency-Key. |
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's plan does not include the API. The full API is included with xPlant+ Teams and Enterprise; on Hobby and Pro Lab, keys can connect devices only. |
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_NOT_ACCEPTED | A device token was sent; this operation needs a workspace API key. |
404 | NOT_FOUND | The plant or explant named in the scan is not in this workspace. |
409 | IDEMPOTENCY_IN_FLIGHT | A request with this Idempotency-Key is still being processed; retry after Retry-After seconds. |
422 | VALIDATION_ERROR | The Idempotency-Key header is malformed. |
422 | VALIDATION_ERROR | A field failed validation, for example a missing barcode or a scanned_at that is not a UTC timestamp. error gives the first problem but does not name the field. |
429 | RATE_LIMIT_EXCEEDED | Too many requests for this key, device token or workspace. Wait Retry-After seconds. |
500 | LABEL_SCAN_CREATE_FAILED | The scan could not be saved. Retry with the same Idempotency-Key. |
Branch on code, never on the error text. See Errors.
Get an SOP
One SOP and the version the lab works from right now, with its steps — what a bench station shows the person at the hood.
Resolve a label
Turns a scanned or typed code into the record it identifies, for scanners and bench hardware. xPlant checks, in order: plant labels, explant labels, container labels, then your own plant and explant identifiers — so a code your lab writes on the jar itself, such as LINE-0412, resolves too.