Record a demand signal
Records how much demand there is for a genus — orders, sales velocity, a forecast — from any source you run. xPlant uses the latest signal per genus when it scores the task queue. Send one whenever your number changes; history is kept.
https://app.xplantpro.com/write:demandHonours Idempotency-KeySee also: Push demand signals.
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 |
|---|---|---|---|
genus | string | Yes | 1–100 characters. |
source_type | string | No | Up to 50 characters. |
demand_score | number | Yes | At least 0. |
source | string | Yes | 1–100 characters. |
observed_at | string (date-time) | No | — |
Example
curl -X POST https://app.xplantpro.com/api/v1/tasks/demand \
-H "Authorization: Bearer $XPLANT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"genus": "Alocasia",
"source_type": "tissue",
"demand_score": 42,
"source": "storefront",
"observed_at": "2026-09-24T00:00:00.000Z"
}'Response
201 with { "ok": true, "data": … }. data holds the result.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The signal's id — or current on the reading current=true returns. |
genus | string | Yes | — |
source_type | string | null | Yes | — |
demand_score | number | Yes | — |
source | string | Yes | — |
observed_at | string | Yes | — |
created_at | string | Yes | — |
{
"ok": true,
"data": {
"id": "c41e8a07-93d2-4b6f-8e15-7a2d0f9b3c58",
"genus": "Alocasia",
"source_type": "tissue",
"demand_score": 42,
"source": "storefront",
"observed_at": "2026-09-24T00:00:00.000Z",
"created_at": "2026-09-24T00:05:11.000Z"
}
}| Response header | Meaning |
|---|---|
Idempotent-Replay | true when this response is a replay of an earlier request with the same Idempotency-Key. |
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. |
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. error names the first one, for example title: title is required. |
429 | RATE_LIMIT_EXCEEDED | Too many requests for this key, device token or workspace. Wait Retry-After seconds. |
500 | DEMAND_CREATE_FAILED | The signal could not be saved. Retry later. |
Branch on code, never on the error text. See Errors.
List demand signals
Demand signals pushed for the workspace, newest first, a page at a time. Add genus to see one genus, and current=true as well to get its current demand as a single reading; that answer is never paged, and meta.next_cursor is always null.
List comments
The discussion on one plant, explant, contamination log, task, media recipe or SOP, oldest first. Replies carry parent_id. A deleted comment keeps its place, with its text removed, so the replies to it still read in order.