Record an equipment event
Records that a piece of equipment was used, calibrated or serviced — from the instrument itself, or from any system that knows. Events are history: there is no update or delete, and a correction is another event.
https://app.xplantpro.com/write:equipment_eventsHonours Idempotency-Keyused records what the equipment was used on; subject_id must be a record in the same workspace. calibration and preventive_maintenance record maintenance with an outcome, and are part of equipment calibration, which not every plan includes.
Recording an event does not move the equipment's calibration or maintenance due dates; those follow the lab's schedules in xPlant.
See also: Equipment events.
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.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | Yes | The record's id. |
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
The body is one of:
A single object
| Field | Type | Required | Description |
|---|---|---|---|
kind | "used" | Yes | The equipment was used. |
subject_type | "sop_log" | "media_batch" | "plant_transfer" | "explant_transfer" | "contamination_log" | Yes | What it was used on: sop_log, media_batch, plant_transfer, explant_transfer, contamination_log. |
subject_id | string (uuid) | Yes | The id of that record. It must belong to the key's workspace. |
subject_label | string | No | A readable name for the record, kept with the event. Up to 200 characters. |
used_at | string (date-time) | No | When it was used, as an ISO 8601 timestamp in UTC (ending in Z). Defaults to now. |
notes | string | No | Up to 2000 characters. |
A single object
| Field | Type | Required | Description |
|---|---|---|---|
kind | "calibration" | "preventive_maintenance" | Yes | calibration, or preventive_maintenance for a service. |
outcome | "pass" | "pass_after_adjustment" | "out_of_tolerance" | "fail" | "not_performed" | No | How it went: pass, pass_after_adjustment, out_of_tolerance, fail, not_performed. out_of_tolerance means the instrument was found outside its specification before any adjustment. Default "pass". |
performed_at | string (date-time) | No | When the work was done, as an ISO 8601 timestamp in UTC (ending in Z). Defaults to now. |
performed_by_name | string | No | Who did the work — a person or a service company. Up to 200 characters. |
result_summary | string | No | Up to 2000 characters. |
notes | string | No | Up to 2000 characters. |
Example
curl -X POST https://app.xplantpro.com/api/v1/equipment/8b0d2f4a-6c8e-4a0b-8d2f-4a6c8e0b2d4f/events \
-H "Authorization: Bearer $XPLANT_API_KEY" \
-H "Idempotency-Key: autoclave-2-cycle-4411" \
-H "Content-Type: application/json" \
-d '{
"kind": "calibration",
"outcome": "pass",
"performed_at": "2026-06-02T08:30:00Z",
"performed_by_name": "Example Calibration Services",
"result_summary": "Temperature and pressure checked at three points."
}'Response
201 with { "ok": true, "data": … }. data holds the result.
| Field | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | Yes | The recorded event's id, as it appears in the equipment's history. |
equipmentId | string (uuid) | Yes | — |
kind | string | Yes | The kind that was recorded. |
recordedAt | string | Yes | When the use or the work happened, as the event records it. ISO 8601 timestamp. |
{
"ok": true,
"data": {
"id": "c5d2e8f1-7a3b-4c69-9e14-0b8a6d4f2e57",
"equipmentId": "8c2f4e61-5a3b-4d7e-9b10-3e6a2c9d4f18",
"kind": "calibration",
"recordedAt": "2026-06-02T08: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. |
402 | FEATURE_NOT_INCLUDED | A calibration or maintenance record was sent, and equipment calibration is not included in your 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_NOT_ACCEPTED | A device token was sent; this operation needs a workspace API key. |
404 | NOT_FOUND | The equipment, or a use's subject_id, is not in the key's 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. error names the first one, for example title: title is required. |
429 | RATE_LIMIT_EXCEEDED | Too many requests for this key, device token or workspace. Wait Retry-After seconds. |
500 | FEATURE_CHECK_FAILED | Your plan could not be checked. Retry later. |
500 | EQUIPMENT_EVENT_CREATE_FAILED | The event could not be saved. Retry with the same Idempotency-Key. |
Branch on code, never on the error text. See Errors.
List equipment events
A piece of equipment's history, newest first: what it was used on, and its calibration and preventive maintenance records. Each event has the fields of its kind; the others are null.
List order lines
Your store's sales, line by line, most recent first: which product sold, the culture line it is matched to, how many, at what unit price, and when. Filter with from and to for a period and product_link_id for one product.