Leaf organizes agricultural land data into a three-level hierarchy: Grower → Farm → Field. Fields carry the boundary polygons that drive everything else in Leaf, from field operations to satellite imagery.Documentation Index
Fetch the complete documentation index at: https://docs.withleaf.io/llms.txt
Use this file to discover all available pages before exploring further.
The Grower / Farm / Field hierarchy
Leaf uses a Grower/Farm/Field structure borrowed from how providers like John Deere organize data:- Grower — Represents the data owner. In Leaf, a grower maps to a Leaf user (the entity that holds provider credentials). When you connect a John Deere account, Leaf imports the “Client” entities as growers.
- Farm — A grouping of fields under a grower. Farms are optional in Leaf. You can create fields without assigning them to a farm.
- Field — A single parcel of land, identified by a field ID. Each field has one active boundary at any time. Machine files that Leaf merges into field operations are tied to fields through their boundaries.
How boundaries work
Every field can have zero or more boundaries, but only one is active at a time. The active boundary is the one Leaf uses for spatial operations. When you update a boundary, the previous one is not deleted. It becomes inactive, and Leaf keeps a full history of all boundaries ever associated with a field. Boundaries are GeoJSONMultiPolygon geometries.
Each boundary has a status that tracks its lifecycle:
| Status | Meaning |
|---|---|
ACTIVE | Current boundary in use |
INACTIVE | Replaced by a newer boundary |
OUTDATED_ON_PROVIDER | Was edited on the provider side; Leaf created a new boundary to reflect the change |
DELETED_ON_PROVIDER | Was deleted on the provider; Leaf keeps the historical record |
validity flag indicating the issue. You can enable automaticFixBoundary in your configuration to have Leaf attempt automatic geometry repair.
How fields sync from providers
When you connect a provider to a Leaf user, Leaf automatically pulls the grower, farm, and field structure from that provider. This happens on the first sync and at least every 24 hours afterward. Each synced field carries metadata from the provider:providerName, providerFieldId, providerFieldName, and organizationId. If the same physical field exists in multiple providers, Leaf detects the overlap and creates a merged field that links back to the originals.
Field types:
ORIGINAL— A field that came from a single provider or was manually created.MERGED— A field Leaf created by detecting overlap between two or more original fields.
fieldsAutoSync is enabled (the default), syncing happens automatically. You can disable it and trigger syncs manually via POST /users/{leafUserId}/fields/sync.
If customDataSync is enabled, Leaf initially fetches fields in PREVIEW mode: metadata only, no boundary geometry. You then selectively enable fields for full processing using the enable sync endpoint.
Common use cases
- Import field boundaries from a provider: Connect John Deere Operations Center, Climate FieldView, or CNHi and let Leaf auto-sync field boundaries for each grower.
- Create field boundaries manually: Upload shapefiles, GeoJSON, or KML through the field upload service when growers don’t use a cloud provider.
- Detect field overlaps: Use the intersection endpoint to find which fields overlap a given geometry — useful for matching uploaded data to existing fields.
- Control sync scope: Enable
customDataSyncto preview fields before committing to full boundary processing, keeping billing predictable.
What to do next
- Managing Fields — Create, update, delete, and sync fields.
- Uploading Boundaries — Create field boundaries from shapefiles, GeoJSON, or KML.
- Growers — Manage the grower layer of the hierarchy.
- API Reference: Fields — Full endpoint reference for fields, boundaries, and farms.