# API overview

> Every v1 endpoint, the scope it needs, and what it returns.

Source: https://docs.xplantpro.com/docs/api

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:

```json
{ "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](https://docs.xplantpro.com/docs/errors.md).

The machine-readable spec is [openapi.json](/openapi.json) (OpenAPI 3).

## Account

| Endpoint | What it does | Scope |
| --- | --- | --- |
| [`GET /me`](https://docs.xplantpro.com/docs/api/account/get-me.md) | Get the calling key | none |
| [`GET /workspaces`](https://docs.xplantpro.com/docs/api/account/list-workspaces.md) | Get the workspace | `read:workspace` |

## Plants

| Endpoint | What it does | Scope |
| --- | --- | --- |
| [`GET /plants`](https://docs.xplantpro.com/docs/api/plants/list-plants.md) | List plants | `read:plants` |
| [`POST /plants`](https://docs.xplantpro.com/docs/api/plants/create-plant.md) | Create a plant | `write:plants` |
| [`GET /plants/{id}`](https://docs.xplantpro.com/docs/api/plants/get-plant.md) | Get a plant | `read:plants` |
| [`PATCH /plants/{id}`](https://docs.xplantpro.com/docs/api/plants/update-plant.md) | Update a plant | `write:plants` |

## Explants

| Endpoint | What it does | Scope |
| --- | --- | --- |
| [`GET /explants`](https://docs.xplantpro.com/docs/api/explants/list-explants.md) | List explants | `read:explants` |
| [`POST /explants`](https://docs.xplantpro.com/docs/api/explants/create-explant.md) | Create an explant | `write:explants` |
| [`GET /explants/{id}`](https://docs.xplantpro.com/docs/api/explants/get-explant.md) | Get an explant | `read:explants` |
| [`PATCH /explants/{id}`](https://docs.xplantpro.com/docs/api/explants/update-explant.md) | Update an explant | `write:explants` |

## Transfers and stages

| Endpoint | What it does | Scope |
| --- | --- | --- |
| [`GET /stages`](https://docs.xplantpro.com/docs/api/transfers-and-stages/list-stages.md) | List stages | `read:transfers` |
| [`POST /stages`](https://docs.xplantpro.com/docs/api/transfers-and-stages/create-stage.md) | Advance a stage | `write:transfers` |
| [`GET /transfers`](https://docs.xplantpro.com/docs/api/transfers-and-stages/list-transfers.md) | List transfers | `read:transfers` |
| [`POST /transfers`](https://docs.xplantpro.com/docs/api/transfers-and-stages/create-transfer.md) | Record a transfer | `write:transfers` |

## Change history

| Endpoint | What it does | Scope |
| --- | --- | --- |
| [`GET /events`](https://docs.xplantpro.com/docs/api/change-history/list-change-events.md) | List change history | `read:events` |

## Contaminations

| Endpoint | What it does | Scope |
| --- | --- | --- |
| [`GET /contaminations`](https://docs.xplantpro.com/docs/api/contaminations/list-contaminations.md) | List contaminations | `read:contaminations` |
| [`POST /contaminations`](https://docs.xplantpro.com/docs/api/contaminations/create-contamination.md) | Record a contamination | `write:contaminations` |
| [`GET /contaminations/{id}`](https://docs.xplantpro.com/docs/api/contaminations/get-contamination.md) | Get a contamination | `read:contaminations` |

## Tasks and demand

| Endpoint | What it does | Scope |
| --- | --- | --- |
| [`GET /tasks`](https://docs.xplantpro.com/docs/api/tasks/list-tasks.md) | List tasks | `read:tasks` |
| [`POST /tasks`](https://docs.xplantpro.com/docs/api/tasks/create-task.md) | Create a task | `write:tasks` |
| [`GET /tasks/{id}`](https://docs.xplantpro.com/docs/api/tasks/get-task.md) | Get a task | `read:tasks` |
| [`PATCH /tasks/{id}`](https://docs.xplantpro.com/docs/api/tasks/update-task.md) | Update a task | `write:tasks` |
| [`GET /tasks/demand`](https://docs.xplantpro.com/docs/api/tasks/list-demand-signals.md) | List demand signals | `read:tasks` |
| [`POST /tasks/demand`](https://docs.xplantpro.com/docs/api/tasks/create-demand-signal.md) | Record a demand signal | `write:demand` |

## Comments

| Endpoint | What it does | Scope |
| --- | --- | --- |
| [`GET /comments`](https://docs.xplantpro.com/docs/api/comments/list-comments.md) | List comments | `read:comments` |
| [`POST /comments`](https://docs.xplantpro.com/docs/api/comments/create-comment.md) | Add a comment | `write:comments` |

## Media

| Endpoint | What it does | Scope |
| --- | --- | --- |
| [`GET /assets`](https://docs.xplantpro.com/docs/api/media/list-assets.md) | List media files | `read:assets` |
| [`POST /assets`](https://docs.xplantpro.com/docs/api/media/create-asset.md) | Attach a media file | `write:assets` |
| [`GET /assets/{id}`](https://docs.xplantpro.com/docs/api/media/get-asset.md) | Get a media file | `read:assets` |
| [`GET /media-recipes`](https://docs.xplantpro.com/docs/api/media/list-media-recipes.md) | List media recipes | `read:media_recipes` |
| [`POST /media-recipes`](https://docs.xplantpro.com/docs/api/media/create-media-recipe.md) | Create a media recipe | `write:media_recipes` |
| [`GET /media-recipes/{id}`](https://docs.xplantpro.com/docs/api/media/get-media-recipe.md) | Get a media recipe | `read:media_recipes` |
| [`PATCH /media-recipes/{id}`](https://docs.xplantpro.com/docs/api/media/update-media-recipe.md) | Update a media recipe | `write:media_recipes` |

## SOPs and runs

| Endpoint | What it does | Scope |
| --- | --- | --- |
| [`POST /sop-runs`](https://docs.xplantpro.com/docs/api/sops/create-sop-run.md) | Start an SOP run | `write:sop_runs` |
| [`GET /sop-runs/{id}`](https://docs.xplantpro.com/docs/api/sops/get-sop-run.md) | Get an SOP run | `read:sop_runs` |
| [`POST /sop-runs/{id}/steps/{stepId}/events`](https://docs.xplantpro.com/docs/api/sops/create-sop-step-event.md) | Record step evidence | `write:sop_steps` |
| [`POST /sop-runs/{id}/steps/{stepId}/measurements`](https://docs.xplantpro.com/docs/api/sops/create-sop-step-measurement.md) | Record a step measurement | `write:sop_steps` |
| [`GET /sops`](https://docs.xplantpro.com/docs/api/sops/list-sops.md) | List SOPs | `read:sops` |
| [`GET /sops/{id}`](https://docs.xplantpro.com/docs/api/sops/get-sop.md) | Get an SOP | `read:sops` |

## Labels

| Endpoint | What it does | Scope |
| --- | --- | --- |
| [`POST /label-scans`](https://docs.xplantpro.com/docs/api/labels/create-label-scan.md) | Record a label scan | `write:label_scans` |
| [`GET /labels/resolve`](https://docs.xplantpro.com/docs/api/labels/resolve-label.md) | Resolve a label | `read:labels` |

## Devices

| Endpoint | What it does | Scope |
| --- | --- | --- |
| [`POST /device-events`](https://docs.xplantpro.com/docs/api/devices/create-device-event.md) | Record a device event | `write:device_events` |
| [`GET /devices`](https://docs.xplantpro.com/docs/api/devices/list-devices.md) | List devices | `read:devices` |
| [`POST /devices`](https://docs.xplantpro.com/docs/api/devices/create-device.md) | Register a device | `write:devices` |
| [`POST /devices/{deviceId}/heartbeat`](https://docs.xplantpro.com/docs/api/devices/send-heartbeat.md) | Send a heartbeat | `write:devices` |
| [`GET /devices/{deviceId}/tokens`](https://docs.xplantpro.com/docs/api/devices/list-device-tokens.md) | List device tokens | `read:devices` |
| [`POST /devices/{deviceId}/tokens`](https://docs.xplantpro.com/docs/api/devices/create-device-token.md) | Create a device token | `write:devices` |
| [`DELETE /devices/{deviceId}/tokens/{tokenId}`](https://docs.xplantpro.com/docs/api/devices/revoke-device-token.md) | Revoke a device token | `write:devices` |

## Sensor readings

| Endpoint | What it does | Scope |
| --- | --- | --- |
| [`GET /sensor-readings`](https://docs.xplantpro.com/docs/api/sensor-readings/list-sensor-readings.md) | List sensor readings | `read:sensor_readings` |
| [`POST /sensor-readings`](https://docs.xplantpro.com/docs/api/sensor-readings/create-sensor-readings.md) | Submit sensor readings | `write:sensor_readings` |

## Equipment

| Endpoint | What it does | Scope |
| --- | --- | --- |
| [`GET /equipment`](https://docs.xplantpro.com/docs/api/equipment/list-equipment.md) | List equipment | `read:equipment` |
| [`GET /equipment/{id}`](https://docs.xplantpro.com/docs/api/equipment/get-equipment.md) | Get a piece of equipment | `read:equipment` |
| [`GET /equipment/{id}/events`](https://docs.xplantpro.com/docs/api/equipment/list-equipment-events.md) | List equipment events | `read:equipment` |
| [`POST /equipment/{id}/events`](https://docs.xplantpro.com/docs/api/equipment/create-equipment-event.md) | Record an equipment event | `write:equipment_events` |

## Pricing and sell-through

| Endpoint | What it does | Scope |
| --- | --- | --- |
| [`GET /commerce/order-lines`](https://docs.xplantpro.com/docs/api/commerce/list-order-lines.md) | List order lines | `read:commerce` |
| [`GET /commerce/sell-through`](https://docs.xplantpro.com/docs/api/commerce/get-sell-through.md) | Get sell-through | `read:commerce` |
| [`GET /pricing/culture-lines`](https://docs.xplantpro.com/docs/api/commerce/list-culture-line-prices.md) | List culture line prices | `read:pricing` |
| [`GET /pricing/events`](https://docs.xplantpro.com/docs/api/commerce/list-price-events.md) | List price changes | `read:pricing` |