Record transfers and stages

Scopes: read:transfers, write:transfers (and read:plants / read:explants to look records up). Endpoints: Record a transfer, List transfers, Advance a stage, List stages.

Find the record firstCopy Anchor Link

Transfers and stages belong to a plant or an explant. If your own system knows a batch by its own code, look it up with externalId rather than keeping a separate id mapping:

import { XPlantClient } from "@shmaplex/xplant-sdk";

const client = new XPlantClient({ apiKey: process.env.XPLANT_API_KEY });

const explant = await client.explants.findByExternalId("LINE-0412"); // record or null

A scanner can also resolve a label straight to the record.

Record a transferCopy Anchor Link

A transfer is a subculture onto fresh media. Give exactly one of plant_id or explant_id. The transfer cycle counts up from the record's history unless you set transfer_cycle yourself.

curl -X POST https://app.xplantpro.com/api/v1/transfers \
  -H "Authorization: Bearer $XPLANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "explant_id": "7c1d9e2a-3b4f-4a5c-8d6e-1f2a3b4c5d6e",
    "from_location": "Shelf A2",
    "to_location": "Shelf B1",
    "notes": "Routine subculture"
  }'

Optional fields: transfer_date, from_location, to_location, transfer_cycle, notes.

Advance a stageCopy Anchor Link

One call completes the current stage and makes the new one current. stage is required; give exactly one of plant_id or explant_id.

Send stage as a key from your lab's stage list. Plants and explants have separate lists: an explant might move to multiplication or root_induction, a plant to production. Use the stages your lab has set up in xPlant.

curl -X POST https://app.xplantpro.com/api/v1/stages \
  -H "Authorization: Bearer $XPLANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"explant_id": "7c1d9e2a-3b4f-4a5c-8d6e-1f2a3b4c5d6e", "stage": "multiplication"}'

Optional fields: entered_on, room_id, notes.

Read the historyCopy Anchor Link

Both lists take one of plant_id or explant_id and return the most recent first:

curl "https://app.xplantpro.com/api/v1/transfers?explant_id=$EXPLANT_ID" -H "Authorization: Bearer $XPLANT_API_KEY"
curl "https://app.xplantpro.com/api/v1/stages?plant_id=$PLANT_ID" -H "Authorization: Bearer $XPLANT_API_KEY"

A transfer counter at the benchCopy Anchor Link

A common build is a scanner plus a button: scan the vessel, press "transferred". The scanner resolves the label to a record, and the button posts a transfer for it.

Device tokens can't record transfers, so a station like this needs a workspace key. Give the station its own key holding only read:labels, write:label_scans and write:transfers, so that a lost station exposes as little as possible and can be revoked on its own. See Bench stations and keys.