API reference
API overview
Every v1 endpoint, the scope it needs, and what it returns.
Base URL: https://app.xplantpro.com/api/v1. Send your key as Authorization: Bearer <key> on every request. Request and response bodies are JSON.
Every response uses the same envelope:
{ "ok": true, "data": { } }
{ "ok": false, "data": null, "error": "Missing scope: write:tasks", "code": "FORBIDDEN" }Read data on success. On failure, branch on code, which is stable; error is for people and its wording can change. See Errors.
The machine-readable spec is openapi.json (OpenAPI 3).
Account
| Endpoint | What it does | Scope |
|---|---|---|
GET /me | Get the calling key | none |
GET /workspaces | Get the workspace | read:workspace |
Plants
| Endpoint | What it does | Scope |
|---|---|---|
GET /plants | List plants | read:plants |
POST /plants | Create a plant | write:plants |
GET /plants/{id} | Get a plant | read:plants |
PATCH /plants/{id} | Update a plant | write:plants |
Explants
| Endpoint | What it does | Scope |
|---|---|---|
GET /explants | List explants | read:explants |
POST /explants | Create an explant | write:explants |
GET /explants/{id} | Get an explant | read:explants |
PATCH /explants/{id} | Update an explant | write:explants |
Transfers and stages
| Endpoint | What it does | Scope |
|---|---|---|
GET /stages | List stages | read:transfers |
POST /stages | Advance a stage | write:transfers |
GET /transfers | List transfers | read:transfers |
POST /transfers | Record a transfer | write:transfers |
Change history
| Endpoint | What it does | Scope |
|---|---|---|
GET /events | List change history | read:events |
Contaminations
| Endpoint | What it does | Scope |
|---|---|---|
GET /contaminations | List contaminations | read:contaminations |
POST /contaminations | Record a contamination | write:contaminations |
GET /contaminations/{id} | Get a contamination | read:contaminations |
Tasks and demand
| Endpoint | What it does | Scope |
|---|---|---|
GET /tasks | List tasks | read:tasks |
POST /tasks | Create a task | write:tasks |
GET /tasks/{id} | Get a task | read:tasks |
PATCH /tasks/{id} | Update a task | write:tasks |
GET /tasks/demand | List demand signals | read:tasks |
POST /tasks/demand | Record a demand signal | write:demand |
Comments
| Endpoint | What it does | Scope |
|---|---|---|
GET /comments | List comments | read:comments |
POST /comments | Add a comment | write:comments |
Media
| Endpoint | What it does | Scope |
|---|---|---|
GET /assets | List media files | read:assets |
POST /assets | Attach a media file | write:assets |
GET /assets/{id} | Get a media file | read:assets |
GET /media-recipes | List media recipes | read:media_recipes |
POST /media-recipes | Create a media recipe | write:media_recipes |
GET /media-recipes/{id} | Get a media recipe | read:media_recipes |
PATCH /media-recipes/{id} | Update a media recipe | write:media_recipes |
SOPs and runs
| Endpoint | What it does | Scope |
|---|---|---|
POST /sop-runs | Start an SOP run | write:sop_runs |
GET /sop-runs/{id} | Get an SOP run | read:sop_runs |
POST /sop-runs/{id}/steps/{stepId}/events | Record step evidence | write:sop_steps |
POST /sop-runs/{id}/steps/{stepId}/measurements | Record a step measurement | write:sop_steps |
GET /sops | List SOPs | read:sops |
GET /sops/{id} | Get an SOP | read:sops |
Labels
| Endpoint | What it does | Scope |
|---|---|---|
POST /label-scans | Record a label scan | write:label_scans |
GET /labels/resolve | Resolve a label | read:labels |
Devices
| Endpoint | What it does | Scope |
|---|---|---|
POST /device-events | Record a device event | write:device_events |
GET /devices | List devices | read:devices |
POST /devices | Register a device | write:devices |
POST /devices/{deviceId}/heartbeat | Send a heartbeat | write:devices |
GET /devices/{deviceId}/tokens | List device tokens | read:devices |
POST /devices/{deviceId}/tokens | Create a device token | write:devices |
DELETE /devices/{deviceId}/tokens/{tokenId} | Revoke a device token | write:devices |
Sensor readings
| Endpoint | What it does | Scope |
|---|---|---|
GET /sensor-readings | List sensor readings | read:sensor_readings |
POST /sensor-readings | Submit sensor readings | write:sensor_readings |
Equipment
| Endpoint | What it does | Scope |
|---|---|---|
GET /equipment | List equipment | read:equipment |
GET /equipment/{id} | Get a piece of equipment | read:equipment |
GET /equipment/{id}/events | List equipment events | read:equipment |
POST /equipment/{id}/events | Record an equipment event | write:equipment_events |
Pricing and sell-through
| Endpoint | What it does | Scope |
|---|---|---|
GET /commerce/order-lines | List order lines | read:commerce |
GET /commerce/sell-through | Get sell-through | read:commerce |
GET /pricing/culture-lines | List culture line prices | read:pricing |
GET /pricing/events | List price changes | read:pricing |
Pull change history
Mirror every plant and explant edit into your own database, incrementally.
Get the calling key
Who the calling key is: its name, the workspace it acts in, the scopes it holds, and which of them it can use right now. Make this the first call an integration makes: it confirms the key works and tells you in one answer what it may do, instead of one 403 at a time.