Developer tools
Developer API & JavaScript SDK
Connect external tools, scripts, and lab systems to xPlant through its versioned API. Use the official JavaScript/TypeScript SDK to work with supported Plant, Explant, task, contamination, comment, Media Recipe, Transfer, SOP run, label, device, and sensor workflows.
Packages and repositories
What you can do with the API
Connect devices and sensor data
Register supported devices and submit environmental sensor readings so external hardware can contribute data to your xPlant workspace.
Work with lab records
Read supported plant, explant, task, contamination, and related workflow data from external tools. Supported resources also expose write operations for automations and integrations.
Build lab integrations
Connect xPlant with scripts, dashboards, data pipelines, and other lab systems using the versioned API or the JavaScript/TypeScript SDK.
Quickstart
- 1Install the SDK
npm install @shmaplex/xplant-sdk
- 2Create an API key
xPlant → Settings → Integrations → API Keys → New key
- 3Initialise the client
import { XPlantClient } from "@shmaplex/xplant-sdk"; const client = new XPlantClient({ apiKey: process.env.XPLANT_API_KEY! }); - 4Make your first request
const plants = await client.plants.list(); console.log(plants);
Authentication and scopes
All API requests require a bearer token issued from Settings → Integrations → API Keys. Each key has a set of scopes that controls what it can read or write. Create separate keys for separate integrations and grant only the permissions each integration needs.
| Scope | What it allows |
|---|---|
| read:workspace | Read workspace and lab settings |
| read:plants / write:plants | Read, create, and update Plant records |
| read:explants / write:explants | Read, create, and update Explant records |
| read:contaminations / write:contaminations | Read contamination logs and submit contamination observations |
| read:tasks / write:tasks | Read, create, update, complete, and reopen tasks |
| write:demand | Push genus-level demand signals for task prioritization |
| read:comments / write:comments | Read and add comments on lab records |
| read:assets / write:assets | Read and attach photos or other media |
| read:media_recipes / write:media_recipes | Read, create, and update Media Recipes |
| read:transfers / write:transfers | Read Transfer and Stage history and record Transfers or Stage progression |
| read:sops | Read SOP templates and steps |
| read:sop_runs / write:sop_runs | Read SOP run history and create or advance SOP run sessions |
| read:labels / write:label_scans | Resolve supported QR or barcode labels and submit scan events |
| read:devices / write:devices | List or register devices and send heartbeats |
| read:sensor_readings / write:sensor_readings | Query and submit environmental sensor readings |
| write:device_events | Submit device heartbeat and status events |
| read:pricing | Read culture-line prices, pricing tiers, and price history |
| read:commerce | Read store order lines and sell-through summaries |
| read:events | Read Plant and Explant change history |
Keep API keys secure: Store keys in environment variables or another secure server-side location. Never expose them in client-side code or public repositories.
Available scopes may expand as the API evolves. Check the current SDK and API documentation when configuring an integration.