API referencePlants
Update a plant
Changes only the fields you send. Send null to clear an optional one.
PATCH
https://app.xplantpro.com/Scope
write:plantscustom_fields changes only the keys you name: the plant's other values stay as they are, and null clears a field.
A key can change the plants its owner created. Changing a teammate's plant needs the key's owner to be a manager or owner of the lab.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | Yes | The record's id. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
species | string | No | 1–200 characters. |
common_name | string | null | No | Up to 200 characters. |
genus | string | null | No | Up to 100 characters. |
family | string | null | No | Up to 100 characters. |
cultivar | string | null | No | Up to 200 characters. |
source | string | null | No | Up to 200 characters. |
notes | string | null | No | Up to 5000 characters. |
status | "active" | "dormant" | "harvested" | "contaminated" | "failed" | "in_culture" | "ready_for_transfer" | "quarantined" | "archived" | No | Where the plant stands in the lab. New plants default to active. |
external_id | string | null | No | Your own identifier for the plant, such as a line or accession code from your own records. It must be unique in the workspace, ignoring case, and it is how GET /api/v1/plants?externalId= finds the plant again. Send null to clear it. 1–100 characters. |
custom_fields | object | No | Values for the lab's own fields, keyed by each field's key. Only the keys you send change; the plant's other values stay as they are. Send null as a value to clear that field. Each value must fit its field, a key the lab has not set up is refused, and the record's values together may total at most 10,000 bytes. |
Example
curl -X PATCH https://app.xplantpro.com/api/v1/plants/0b8e2f4c-6a1d-4c3e-9f7a-2d5b8c1e4a90 \
-H "Authorization: Bearer $XPLANT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"status": "ready_for_transfer",
"custom_fields": {
"weeks_in_culture": 13
}
}'Response
200 with { "ok": true, "data": … }. data holds the result.
| Field | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | Yes | — |
name | string | Yes | What the lab calls the plant: its common name, or its species when it has none. |
species | string | Yes | — |
status | string | Yes | Where the plant stands in the lab, usually one of active, dormant, harvested, contaminated, failed, in_culture, ready_for_transfer, quarantined, archived. |
workspace_id | string | null | Yes | The workspace the plant belongs to. |
created_at | string | null | Yes | ISO 8601 timestamp. |
external_id | string | null | Yes | Your own identifier for the plant, exactly as it was given, or null when it has none. |
custom_fields | object | Yes | The lab's own fields for this record, keyed by each field's key as set up in the lab's settings. Values are text, numbers, true or false, or dates written as YYYY-MM-DD; a field left blank is absent or null. Empty when the lab has set up no fields. |
{
"ok": true,
"data": {
"id": "8c3f2d1a-6b4e-4f7a-9d2c-1e5b7a9c3f60",
"name": "Zebra Alocasia",
"species": "Alocasia zebrina",
"status": "ready_for_transfer",
"workspace_id": "3a9e7c21-5d4b-4c8f-a1e6-9b2d0f4c7e13",
"created_at": "2026-09-25T09:30:00.000Z",
"external_id": "LINE-0412",
"custom_fields": {
"mother_stock_tray": "B4",
"weeks_in_culture": 13
}
}
}| 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'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. |
403 | PLANT_WRITE_FORBIDDEN | The plant was created by someone else, and the key's owner is not a manager or owner of the lab. |
404 | NOT_FOUND | No record with this id exists in the key's workspace. |
409 | DUPLICATE_ENTRY | Another plant in the workspace already uses this external_id, including one that has been deleted. |
422 | VALIDATION_ERROR | A field failed validation. error names the first one, for example title: title is required. |
422 | VALIDATION_ERROR | custom_fields names a field the lab has not set up, gives a field a value that does not fit it, or totals more than 10,000 bytes. error names the field. |
429 | RATE_LIMIT_EXCEEDED | Too many requests for this key, device token or workspace. Wait Retry-After seconds. |
500 | PLANT_UPDATE_FAILED | The change could not be saved. Retry later. |
Branch on code, never on the error text. See Errors.