Skip to main content
For conceptual background, see Configurations. Configurations control how Leaf syncs data from providers, processes machine files, creates field operations, and generates images. You set configurations at the API owner level (applies to all Leaf users by default) or override them for individual Leaf users.
Leaf uses API owner settings as the runtime defaults for Leaf users. The public GET /configs/{leafUserId} endpoint, however, returns only the stored custom configuration for that Leaf user. If no Leaf-user-specific config exists, that endpoint returns 404.

​
Base URL

https://api.withleaf.io/services/config/api

​
Endpoints

ActionMethodPath
Get API owner’s configurationGET/configs
Get Leaf user’s configurationGET/configs/{leafUserId}
Create Leaf user’s configurationPOST/configs/{leafUserId}
Update API owner’s configurationPATCH/configs
Update Leaf user’s configurationPATCH/configs/{leafUserId}
Delete Leaf user’s configurationDELETE/configs/{leafUserId}

​
Common configuration properties

PropertyTypeDescription
apiOwnerUsernamestringYour API owner username (read-only).
leafUserIdstringThe Leaf user ID, or empty string for API owner configs.
operationsImageCreationbooleanGenerate PNG images for field operation properties.
fieldsAutoSyncbooleanAutomatically sync field boundaries from providers.
fieldsMergeIntersectionfloatMinimum intersection ratio to merge overlapping fields.
fieldsAttachIntersectionfloatMinimum intersection ratio to attach operations to fields.
cleanupStandardGeojsonbooleanApply cleanup rules to standardized GeoJSON output.
cleanupRulesobjectRules for filtering data points during cleanup.
This table lists common properties only. The full response object includes many more configuration fields.

​
Get API owner’s configuration

GET /configs Returns the configuration for your API owner account.

​
Request

curl -X GET \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    'https://api.withleaf.io/services/config/api/configs'

​
Response

{
  "apiOwnerUsername": "api-owner",
  "leafUserId": "",
  "operationsImageCreation": true,
  "fieldsAutoSync": true,
  "fieldsMergeIntersection": 0.01,
  "fieldsAttachIntersection": 0.01,
  "cleanupStandardGeojson": true,
  "cleanupRules": {
    "wetMass": [{"operator": "GT", "value": 0.0}],
    "harvestMoisture": [{"operator": "GT", "value": 0.0}, {"operator": "LT", "value": 100.0}],
    "recordingStatus": [{"operator": "EQ", "value": "On"}]
  }
}

​
Get Leaf user’s configuration

GET /configs/{leafUserId} Returns the stored custom configuration for a specific Leaf user. If the Leaf user has no custom configuration, this endpoint returns 404.

​
Path parameters

ParameterTypeDescription
leafUserIdstring (UUID)The Leaf user ID.

​
Request

curl -X GET \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    'https://api.withleaf.io/services/config/api/configs/f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f'

​
Response

{
  "apiOwnerUsername": "api-owner",
  "leafUserId": "f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f",
  "operationsImageCreation": false,
  "fieldsAutoSync": true
}

​
Create Leaf user’s configuration

POST /configs/{leafUserId} Creates a custom configuration for a Leaf user. Include only the properties you want to override. Omitted properties remain unset on the stored Leaf-user config and continue to resolve from the API owner at runtime.

​
Path parameters

ParameterTypeDescription
leafUserIdstring (UUID)The Leaf user ID.

​
Request body

All fields are optional. Only include the properties you want to set. 
{
  "operationsImageCreation": false,
  "fieldsAutoSync": true
}

​
Request

curl -X POST \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{"operationsImageCreation": false, "fieldsAutoSync": true}' \
    'https://api.withleaf.io/services/config/api/configs/f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f'

​
Response

The response includes the stored Leaf-user configuration object. Omitted properties are not filled in with inherited values in this response. 
{
  "apiOwnerUsername": "api-owner",
  "leafUserId": "f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f",
  "operationsImageCreation": false,
  "fieldsAutoSync": true
}

​
Update API owner’s configuration

PATCH /configs Updates specific fields of the API owner’s configuration. Only include the properties you want to change.
Configuration changes are not retroactive. Existing data is not reprocessed. If you need existing data regenerated, choose the reprocess endpoint that matches the pipeline stage affected by the setting: use file reprocessing for machine-file processing settings, and operation reprocessing for operation-generation settings.

​
Request body

All fields are optional. 
{
  "operationsImageCreation": true,
  "fieldsAutoSync": false
}

​
Request

curl -X PATCH \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{"operationsImageCreation": true, "fieldsAutoSync": false}' \
    'https://api.withleaf.io/services/config/api/configs'

​
Response

{
  "apiOwnerUsername": "api-owner",
  "leafUserId": "",
  "operationsImageCreation": true,
  "fieldsAutoSync": false,
  "fieldsMergeIntersection": 0.01,
  "fieldsAttachIntersection": 0.01,
  "cleanupStandardGeojson": true,
  "cleanupRules": {
    "wetMass": [{"operator": "GT", "value": 0.0}],
    "harvestMoisture": [{"operator": "GT", "value": 0.0}, {"operator": "LT", "value": 100.0}],
    "recordingStatus": [{"operator": "EQ", "value": "On"}]
  }
}

​
Update Leaf user’s configuration

PATCH /configs/{leafUserId} Updates specific fields of a Leaf user’s configuration. Only include the properties you want to change.

​
Path parameters

ParameterTypeDescription
leafUserIdstring (UUID)The Leaf user ID.

​
Request body

All fields are optional. 
{
  "operationsImageCreation": false,
  "fieldsMergeIntersection": 0.05
}

​
Request

curl -X PATCH \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{"operationsImageCreation": false, "fieldsMergeIntersection": 0.05}' \
    'https://api.withleaf.io/services/config/api/configs/f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f'

​
Response

The response includes the stored Leaf-user configuration object after the update. Omitted properties are not filled in with inherited values in this response. 
{
  "apiOwnerUsername": "api-owner",
  "leafUserId": "f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f",
  "operationsImageCreation": false,
  "fieldsMergeIntersection": 0.05
}

​
Delete Leaf user’s configuration

DELETE /configs/{leafUserId} Deletes the custom configuration for a Leaf user. After deletion, the Leaf user inherits all settings from the API owner.

​
Path parameters

ParameterTypeDescription
leafUserIdstring (UUID)The Leaf user ID.

​
Request

curl -X DELETE \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    'https://api.withleaf.io/services/config/api/configs/f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f'
Last modified on March 24, 2026