Configurations - Leaf Documentation

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

Action	Method	Path
Get API owner’s configuration	GET	`/configs`
Get Leaf user’s configuration	GET	`/configs/{leafUserId}`
Create Leaf user’s configuration	POST	`/configs/{leafUserId}`
Update API owner’s configuration	PATCH	`/configs`
Update Leaf user’s configuration	PATCH	`/configs/{leafUserId}`
Delete Leaf user’s configuration	DELETE	`/configs/{leafUserId}`

Common configuration properties

Property	Type	Description
`apiOwnerUsername`	string	Your API owner username (read-only).
`leafUserId`	string	The Leaf user ID, or empty string for API owner configs.
`operationsImageCreation`	boolean	Generate PNG images for field operation properties.
`fieldsAutoSync`	boolean	Automatically sync field boundaries from providers.
`fieldsMergeIntersection`	float	Minimum intersection ratio to merge overlapping fields.
`fieldsAttachIntersection`	float	Minimum intersection ratio to attach operations to fields.
`cleanupStandardGeojson`	boolean	Apply cleanup rules to standardized GeoJSON output.
`cleanupRules`	object	Rules 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'

import requests

TOKEN = "YOUR_TOKEN"

endpoint = "https://api.withleaf.io/services/config/api/configs"
headers = {"Authorization": f"Bearer {TOKEN}"}

response = requests.get(endpoint, headers=headers)
print(response.json())

const axios = require("axios")
const TOKEN = "YOUR_TOKEN"

const endpoint = "https://api.withleaf.io/services/config/api/configs"
const headers = { Authorization: `Bearer ${TOKEN}` }

axios.get(endpoint, { headers })
    .then(res => console.log(res.data))
    .catch(console.error)

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

Parameter	Type	Description
`leafUserId`	string (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'

import requests

TOKEN = "YOUR_TOKEN"
LEAF_USER_ID = "f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f"

endpoint = f"https://api.withleaf.io/services/config/api/configs/{LEAF_USER_ID}"
headers = {"Authorization": f"Bearer {TOKEN}"}

response = requests.get(endpoint, headers=headers)
print(response.json())

const axios = require("axios")
const TOKEN = "YOUR_TOKEN"
const LEAF_USER_ID = "f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f"

const endpoint = `https://api.withleaf.io/services/config/api/configs/${LEAF_USER_ID}`
const headers = { Authorization: `Bearer ${TOKEN}` }

axios.get(endpoint, { headers })
    .then(res => console.log(res.data))
    .catch(console.error)

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

Parameter	Type	Description
`leafUserId`	string (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'

import requests

TOKEN = "YOUR_TOKEN"
LEAF_USER_ID = "f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f"

endpoint = f"https://api.withleaf.io/services/config/api/configs/{LEAF_USER_ID}"
headers = {"Authorization": f"Bearer {TOKEN}"}

data = {
    "operationsImageCreation": False,
    "fieldsAutoSync": True
}

response = requests.post(endpoint, headers=headers, json=data)
print(response.json())

const axios = require("axios")
const TOKEN = "YOUR_TOKEN"
const LEAF_USER_ID = "f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f"

const endpoint = `https://api.withleaf.io/services/config/api/configs/${LEAF_USER_ID}`
const headers = { Authorization: `Bearer ${TOKEN}` }

const data = {
    operationsImageCreation: false,
    fieldsAutoSync: true
}

axios.post(endpoint, data, { headers })
    .then(res => console.log(res.data))
    .catch(console.error)

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'

import requests

TOKEN = "YOUR_TOKEN"

endpoint = "https://api.withleaf.io/services/config/api/configs"
headers = {"Authorization": f"Bearer {TOKEN}"}

data = {
    "operationsImageCreation": True,
    "fieldsAutoSync": False
}

response = requests.patch(endpoint, headers=headers, json=data)
print(response.json())

const axios = require("axios")
const TOKEN = "YOUR_TOKEN"

const endpoint = "https://api.withleaf.io/services/config/api/configs"
const headers = { Authorization: `Bearer ${TOKEN}` }

const data = {
    operationsImageCreation: true,
    fieldsAutoSync: false
}

axios.patch(endpoint, data, { headers })
    .then(res => console.log(res.data))
    .catch(console.error)

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

Parameter	Type	Description
`leafUserId`	string (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'

import requests

TOKEN = "YOUR_TOKEN"
LEAF_USER_ID = "f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f"

endpoint = f"https://api.withleaf.io/services/config/api/configs/{LEAF_USER_ID}"
headers = {"Authorization": f"Bearer {TOKEN}"}

data = {
    "operationsImageCreation": False,
    "fieldsMergeIntersection": 0.05
}

response = requests.patch(endpoint, headers=headers, json=data)
print(response.json())

const axios = require("axios")
const TOKEN = "YOUR_TOKEN"
const LEAF_USER_ID = "f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f"

const endpoint = `https://api.withleaf.io/services/config/api/configs/${LEAF_USER_ID}`
const headers = { Authorization: `Bearer ${TOKEN}` }

const data = {
    operationsImageCreation: false,
    fieldsMergeIntersection: 0.05
}

axios.patch(endpoint, data, { headers })
    .then(res => console.log(res.data))
    .catch(console.error)

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

Parameter	Type	Description
`leafUserId`	string (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'

import requests

TOKEN = "YOUR_TOKEN"
LEAF_USER_ID = "f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f"

endpoint = f"https://api.withleaf.io/services/config/api/configs/{LEAF_USER_ID}"
headers = {"Authorization": f"Bearer {TOKEN}"}

response = requests.delete(endpoint, headers=headers)
print(response.status_code)

const axios = require("axios")
const TOKEN = "YOUR_TOKEN"
const LEAF_USER_ID = "f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f"

const endpoint = `https://api.withleaf.io/services/config/api/configs/${LEAF_USER_ID}`
const headers = { Authorization: `Bearer ${TOKEN}` }

axios.delete(endpoint, { headers })
    .then(res => console.log(res.status))
    .catch(console.error)

​Base URL

​Endpoints

​Common configuration properties

​Get API owner’s configuration

​Request

​Response

​Get Leaf user’s configuration

​Path parameters

​Request

​Response

​Create Leaf user’s configuration

​Path parameters

​Request body

​Request

​Response

​Update API owner’s configuration

​Request body

​Request

​Response

​Update Leaf user’s configuration

​Path parameters

​Request body

​Request

​Response

​Delete Leaf user’s configuration

​Path parameters

​Request

Base URL

Endpoints

Common configuration properties

Get API owner’s configuration

Request

Response

Get Leaf user’s configuration

Path parameters

Request

Response

Create Leaf user’s configuration

Path parameters

Request body

Request

Response

Update API owner’s configuration

Request body

Request

Response

Update Leaf user’s configuration

Path parameters

Request body

Request

Response

Delete Leaf user’s configuration

Path parameters

Request