Schedule a harvest

New

POST/orchards/{orchardId}/harvests

Schedules asynchronous picking work. Send an idempotency key if the request may be retried.

Workflow

Before this operation

Get an orchardGETCheck the orchard and choose a growing block.

Possible next operations

Get a harvestGETAfter a 202 responsePoll the accepted harvest until it reaches a final state.

Callbacks from this operation

Receive harvest statusPOSTharvestStatus · {$request.body#/callbackUrl}Sent when the harvest completes or is canceled.

Events emitted

Harvest readyPOSTEmitted when the harvest completes and inventory is ready.

Request

Available on

ProductionSandbox

Path parameters

Header parameters

Request body

application/json

{}

CreateHarvestRequestCreateHarvestRequest · object · 4 fields

No other properties are allowed.

Request example

Path

/orchards/orc_nightingale/harvests

Headers

{  "Idempotency-Key": "harvest-2026-09-03-north-slope"}

Body

{  "blockId": "blk_north_slope",  "scheduledFor": "2026-09-03",  "targetKilograms": 1800,  "callbackUrl": "https://warehouse.example/hooks/harvests"}

Responses

202Accepted

The harvest was accepted for scheduling.

Headers

Body

application/json

{}

HarvestHarvest · object · 8 fields

Response example

{  "id": "hrv_01J5Y8T3W4",  "orchardId": "orc_nightingale",  "blockId": "blk_north_slope",  "status": "harvest.scheduled",  "scheduledFor": "2026-09-03",  "targetKilograms": 1800,  "createdAt": "2026-08-13T09:42:17Z"}

Callbacks

After this operation, the API may send an HTTP request to a URL supplied by the caller.

harvestStatus

API-initiated request

Destination from the original request{$request.body#/callbackUrl}