Configurations control how Leaf pulls data from providers, processes machine files, creates field operations, and generates output formats. You can set configurations at the API owner level (applies to all Leaf users by default) or at the individual Leaf user level for granular control.
How configuration inheritance works
Every API owner starts with a default set of configurations. These defaults can be changed but not deleted or set to null.
When you set a configuration on a specific Leaf user, that user stops inheriting that configuration from the API owner. The Leaf user’s value takes precedence and does not change if you later update the API owner’s configuration.
If a Leaf user has no custom configuration, they inherit everything from the API owner.
Configuration changes are not retroactive. Existing data is not reprocessed when you change a configuration. Use the Reprocess Operation endpoint if you need to apply new settings to existing data.
Endpoints
Base URL: https://api.withleaf.io/services/config/api
| Action | Method | Path |
|---|
| Get API owner configuration | GET | /configs |
| Get Leaf user configuration | GET | /configs/{leafUserId} |
| Create Leaf user configuration | POST | /configs/{leafUserId} |
| Update API owner configuration | PATCH | /configs |
| Update Leaf user configuration | PATCH | /configs/{leafUserId} |
| Delete Leaf user configuration | DELETE | /configs/{leafUserId} |
Configuration categories
Configurations are grouped by what they control. See the Configuration Reference for the full list with defaults and descriptions.
| Category | What it controls | Key configs |
|---|
| Data synchronization | Which data Leaf pulls from providers | fieldsAutoSync, operationsAutoSync, customDataSync, organizationDataSync |
| Field boundary management | How boundaries are validated, linked, and merged | automaticFixBoundary, fieldsAttachIntersection, fieldsAutoMerge |
| Machine file conversion | How raw data is cleaned and output | cleanupStandardGeojson, cleanupRules, unitMeasurement, enableGeoparquetOutput, cropOptional, seedRateOptional |
| Field operations | How files merge into operations | fieldOperationCreation, operationsFilteredGeojson, operationsRemoveOutliers, operationsMergeRange, splitOperationsByField, outOfStandardOperations |
| Image generation | Which images are produced for operations | operationsImageCreation, operationsImageAsGeoTiff |
| Irrigation | How far back to fetch irrigation data | irrigationProcessingRange |
Configurations by use case
The right configuration depends on your use case. Here are recommended starting points.
Crop insurance
Focus on consistent results close to SMS-driven pipelines. Key settings:
cleanupStandardGeojson: true with default rules.operationsRemoveOutliers: true with operationsOutliersLimit at 3.splitOperationsByField: true.operationsImageCreation: true for visual verification.unitMeasurement: IMPERIAL (for US customers).
FMIS
Prioritize processing efficiency and pull only the data you need:
customDataSync: true to selectively process fields.fieldsAutoSync: true.operationsAutoSync: true.enableGeoparquetOutput: true for faster data ingestion.
Managed service provider
Similar to FMIS, with additional attention to multi-organization accounts:
organizationDataSync: SELECTED_ONLY to limit scope.customDataSync: true.- Per-Leaf-user configurations for different growers with different processing needs.
What to do next
