Advance a stage
Moves a plant or explant into a new stage in one call: the stage it is in now is marked completed, the new one is recorded, and it becomes the current stage. Send exactly one of plant_id or explant_id.
https://app.xplantpro.com/write:transfersHonours Idempotency-Keystage is checked against your lab's own stage list for plants or for explants, whichever you are moving, the same way xPlant checks it. A stage's older display name is saved as its key, so the response carries the key you should send next time. A name your lab does not use is refused before anything changes.
A key can move the plants and explants its owner created. Moving a teammate's needs the key's owner to be a manager or owner of the lab, as it does in xPlant.
The move is added to the plant's or explant's history: GET /api/v1/events returns it as a stage_change event.
Every successful move answers with meta beside the stage: meta.previous_stage_id names the stage that was closed, so your system can mirror the change without reading the history back. Send an Idempotency-Key when you might retry: a repeated move would otherwise close the stage the first attempt opened.
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 |
|---|---|---|---|
plant_id | string (uuid) | No | The plant this is for. Send exactly one of plant_id or explant_id. |
explant_id | string (uuid) | No | The explant this is for. Send exactly one of plant_id or explant_id. |
stage | string | Yes | The stage to move into, as a key from your lab's stage list. Plants and explants have separate lists — for example multiplication or root_induction for an explant, production for a plant. A stage's older display name, such as Multiplication, is accepted and saved as its key. A name your lab does not use is refused. 1–50 characters. |
entered_on | string | No | When it entered the stage: a date such as 2026-09-24, or a full ISO 8601 timestamp. Defaults to today (UTC). |
room_id | string (uuid) | No | The growing room it is in for this stage. Must be a room in the workspace. |
notes | string | No | Up to 5000 characters. |
Example
curl -X POST https://app.xplantpro.com/api/v1/stages \
-H "Authorization: Bearer $XPLANT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"explant_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"stage": "multiplication",
"entered_on": "2026-09-24",
"notes": "Shoot clusters forming well on the Alocasia line."
}'Response
201 with { "ok": true, "data": … }. data holds the result.
| Field | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | Yes | — |
entity_type | "plant" | "explant" | Yes | Whether the stage belongs to a plant or an explant. |
entity_id | string (uuid) | Yes | The plant's or explant's id. |
stage | string | Yes | The stage, as a key from your lab's stage list such as multiplication. Records made by older tools can carry the stage's display name instead, such as Multiplication. |
status | string | Yes | active for the stage the plant or explant is in now, completed for one it has moved on from. Stages can also be failed or archived. |
entered_on | string | null | Yes | When it entered this stage, as an ISO 8601 timestamp. |
completed_at | string | null | Yes | When it moved on from this stage. Null while the stage is current. |
room_id | string | null (uuid) | Yes | The room it was in for this stage, when one was recorded. |
notes | string | null | Yes | — |
created_at | string | null | Yes | — |
{
"ok": true,
"data": {
"id": "6e5d4c3b-2a19-4807-96a5-b4c3d2e1f0a9",
"entity_type": "explant",
"entity_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"stage": "multiplication",
"status": "active",
"entered_on": "2026-09-24T00:00:00+00:00",
"completed_at": null,
"room_id": null,
"notes": "Shoot clusters forming well on the Alocasia line.",
"created_at": "2026-09-24T08:41:17.000Z"
}
}The envelope can also carry meta:
| Field | Type | Required | Description |
|---|---|---|---|
previous_stage_id | string | null (uuid) | No | The stage this one replaced, which is now completed. Null when there was no current stage. |
warning | string | No | No longer sent. A stage that cannot be made the current one is now withdrawn, and the move answers 500 STAGE_ADVANCE_FAILED with nothing moved. Kept so a client written against it still reads the response. |
| Response header | Meaning |
|---|---|
Idempotent-Replay | true when this response is a replay of an earlier request with the same Idempotency-Key. |
X-RateLimit-Limit | The request budget this answer reports on, per minute: your key's or device token's (1,000) or your workspace's (3,000), whichever has fewer requests left. Left out when the budget could not be read. |
X-RateLimit-Remaining | Requests left in that budget this minute, after this one. 0 on a 429. A workspace's other keys spend its budget too, so this can fall faster than your own requests alone would. |
X-RateLimit-Reset | Whole seconds until that budget's minute ends and it is full again. Never more than 60. |
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 | STAGE_WRITE_FORBIDDEN | The plant or explant was created by someone else, and the key's owner is not a manager or owner of the lab. Nothing was changed. |
404 | NOT_FOUND | The plant or explant, or the growing room named in room_id, is not in this workspace. Nothing was changed. |
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, or neither or both of plant_id and explant_id were sent. error names the first problem, for example stage: stage is required. |
422 | VALIDATION_ERROR | stage is not in your lab's stage list for a plant, or for an explant — whichever you sent. error starts stage: and names the list. Nothing was changed. |
429 | RATE_LIMIT_EXCEEDED | Too many requests for this key, device token or workspace. Wait Retry-After seconds. |
500 | STAGE_ADVANCE_FAILED | The stage could not be saved, or could not be made the current one. Nothing moved: the plant or explant is still in the stage it was in. Retry with the same Idempotency-Key. |
Branch on code, never on the error text. See Errors.
List stages
Every stage one plant or explant has been through, newest first — where it is now and how it got there. Send exactly one of plant_id or explant_id.
List transfers
The transfer history of one plant or explant, newest first: every move onto fresh media, where it went and which subculture it was. Send exactly one of plant_id or explant_id.