> ## 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.

# Configurations

> Manage API owner and Leaf user configurations that control provider data syncing, field operations processing, machine file conversion, and output formats.

For conceptual background, see [Configurations](/configuration/overview).

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.

<Note>
  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`.
</Note>

## Base URL

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

## Endpoints

| Action                                                               | Method                                                             | Path                    |
| -------------------------------------------------------------------- | ------------------------------------------------------------------ | ----------------------- |
| [Get API owner's configuration](#get-api-owners-configuration)       | <span style={{fontWeight: 'bold', color: '#16a34a'}}>GET</span>    | `/configs`              |
| [Get Leaf user's configuration](#get-leaf-users-configuration)       | <span style={{fontWeight: 'bold', color: '#16a34a'}}>GET</span>    | `/configs/{leafUserId}` |
| [Create Leaf user's configuration](#create-leaf-users-configuration) | <span style={{fontWeight: 'bold', color: '#e5a00d'}}>POST</span>   | `/configs/{leafUserId}` |
| [Update API owner's configuration](#update-api-owners-configuration) | <span style={{fontWeight: 'bold', color: '#e5a00d'}}>PATCH</span>  | `/configs`              |
| [Update Leaf user's configuration](#update-leaf-users-configuration) | <span style={{fontWeight: 'bold', color: '#e5a00d'}}>PATCH</span>  | `/configs/{leafUserId}` |
| [Delete Leaf user's configuration](#delete-leaf-users-configuration) | <span style={{fontWeight: 'bold', color: '#dc2626'}}>DELETE</span> | `/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.            |

<Note>
  This table lists common properties only. The full response object includes many more configuration fields.
</Note>

***

## Get API owner's configuration

`GET /configs`

Returns the configuration for your API owner account.

### Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
      -H 'Authorization: Bearer YOUR_TOKEN' \
      'https://api.withleaf.io/services/config/api/configs'
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript JavaScript theme={null}
  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)
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "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

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
      -H 'Authorization: Bearer YOUR_TOKEN' \
      'https://api.withleaf.io/services/config/api/configs/f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f'
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript JavaScript theme={null}
  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)
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "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.

```json theme={null}
{
  "operationsImageCreation": false,
  "fieldsAutoSync": true
}
```

### Request

<CodeGroup>
  ```bash cURL theme={null}
  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'
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript JavaScript theme={null}
  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)
  ```
</CodeGroup>

### Response

The response includes the stored Leaf-user configuration object. Omitted properties are not filled in with inherited values in this response.

```json theme={null}
{
  "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.

<Warning>
  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.
</Warning>

### Request body

All fields are optional.

```json theme={null}
{
  "operationsImageCreation": true,
  "fieldsAutoSync": false
}
```

### Request

<CodeGroup>
  ```bash cURL theme={null}
  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'
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript JavaScript theme={null}
  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)
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "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.

```json theme={null}
{
  "operationsImageCreation": false,
  "fieldsMergeIntersection": 0.05
}
```

### Request

<CodeGroup>
  ```bash cURL theme={null}
  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'
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript JavaScript theme={null}
  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)
  ```
</CodeGroup>

### 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.

```json theme={null}
{
  "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

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE \
      -H 'Authorization: Bearer YOUR_TOKEN' \
      'https://api.withleaf.io/services/config/api/configs/f2a0b4d1-e567-4a8c-9e1f-0c3d5a7b9e2f'
  ```

  ```python Python theme={null}
  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)
  ```

  ```javascript JavaScript theme={null}
  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)
  ```
</CodeGroup>