Beta Input - Leaf Documentation

Use these endpoints to look up agricultural products, varieties, and tank mixes from standardized databases and to match product names from machine files against known products. For conceptual background, see Input Validator.

The Input API is currently in beta. Endpoints, request/response schemas, and behavior may change without notice.

Base URL

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

Endpoints

Products

Endpoint	Method	Path
Get all products	GET	`/products`
Get summarized products	GET	`/users/{leafUserId}/products/summary`
Search for products	GET	`/products/search`
Get a product	GET	`/products/{id}`
Get matching products from an operation	GET	`/products/matching/operations/{operationId}`
Update product matches	PATCH	`/products/matching/operations/{operationId}/matches/{matchId}`
Get product matches historical	GET	`/products/matching/operations/{operationId}/matches/{matchId}/historical`

Varieties

Endpoint	Method	Path
Get all varieties	GET	`/varieties`
Get a variety	GET	`/varieties/{id}`
Get summarized varieties	GET	`/users/{leafUserId}/varieties/summary`
Search for varieties	GET	`/varieties/search`

Tank Mixes

Endpoint	Method	Path
Get all tank mixes	GET	`/tankMixes`
Search for tank mixes	GET	`/tankMixes/search`

Products

Get all products

GET /products Returns a paginated list of products from providers at the Leaf user level. Currently supports John Deere products. This endpoint does not include products from label databases such as Agrian and CDMS — use Search for products for those.

Parameters

Parameter	Type	Description
`leafUserId`	string (UUID)	Filter by Leaf user.
`provider`	string	Filter by provider (`JohnDeere`).
`page`	integer	Page number (default `0`).
`size`	integer	Page size (max `100`).
`sort`	string	Sorting order. Comma-separated fields with optional `,asc` or `,desc` suffix.

Request

curl -X GET \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://api.withleaf.io/services/beta/api/products?leafUserId={leafUserId}'

Response

[
  {
    "id": "07b3f270-8af8-11ee-b9d1-0242ac120002",
    "name": "Propiconazole",
    "registrant": "Tide International USA, Inc.",
    "productType": "Chemical",
    "labelProvider": "JohnDeere",
    "providerId": "020c55f6-8af8-11ee-b9d1-0242ac120002",
    "formulationType": "DRY",
    "leafUserId": "fb6fcda4-8af7-11ee-b9d1-0242ac120002",
    "registration": "0084229-00011-AA-0000000",
    "status": "ACTIVE",
    "carrier": true
  }
]

Get summarized products

GET /users/{leafUserId}/products/summary Returns a summarized list of products extracted from machine files for a Leaf user.

Parameters

Parameter	Type	Description
`name`	string	Filter by partial product name.
`page`	integer	Page number (default `0`).
`size`	integer	Page size (max `100`).
`sort`	string	Sorting order. Comma-separated fields with optional `,asc` or `,desc` suffix.

Request

curl -X GET \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://api.withleaf.io/services/beta/api/users/{leafUserId}/products/summary'

Response

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Default product",
    "leafUserId": "8bbe50a0-992c-11ee-b9d1-0242ac120002"
  }
]

Search for products

GET /products/search Searches for products by name (partial values supported). Includes results from Agrian and CDMS databases available to everyone, plus John Deere products at the Leaf user level.

Parameters

Parameter	Type	Description
`name`	string	Required. Partial product name to search.
`maxResults`	integer	Maximum results to return (default `10`, max `100`).

Request

curl -X GET \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://api.withleaf.io/services/beta/api/products/search?name=Roundup'

Response

[
  {
    "id": "7d85c556-0ac5-4f0b-b7cc-b35ac559af8f",
    "name": "CompostX",
    "registration": "00000-00-00000",
    "registrant": "Leaf Company, LLC",
    "productType": "Dry",
    "physicalState": "dry",
    "formulationType": "Dry Flowable",
    "labelProvider": "CDMS",
    "productPageUrl": "https://www.cdms.net/ldat/",
    "labels": [
      {
        "name": "meE2000.pdf",
        "url": "https://www.cdms.net/ldat/meE2000.pdf"
      }
    ],
    "activeIngredient": [
      "Urea",
      "Calcium"
    ]
  },
  {
    "id": "21f4cb76-07fa-46ca-a8cf-cfbc2f161bdf",
    "name": "Product AB",
    "registration": "0434785-2911",
    "registrant": "Loveland Products, Inc.",
    "productType": "Insecticide Miticide",
    "formulationType": "Emulsifiable Concentrate",
    "labelProvider": "AGRIAN",
    "productPageUrl": "https://www.agrian.com/labelcenter/results.cfm?d=0000",
    "labels": [
      {
        "name": "Label",
        "url": "https://www.agrian.com/pdfs/new/00000.pdf"
      }
    ],
    "activeIngredient": [
      "13.1 - Lambda-cyhalothrin"
    ],
    "physicalState": "liquid",
    "density": {
      "value": "7.17",
      "unit": "lb/ga"
    },
    "activeIngredients": [
      {
        "name": "Lambda-cyhalothrin",
        "value": "13.1",
        "unit": "%"
      }
    ]
  }
]

Get a product

GET /products/{id} Returns a single product by its ID. Data is sourced from multiple product databases.

Parameters

Parameter	Type	Description
`id`	string (UUID)	Path param — the product ID.

Request

curl -X GET \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://api.withleaf.io/services/beta/api/products/{id}'

Response

{
  "id": "81ffe756-1fd0-4d97-b2ec-e33b5232f507",
  "name": "GameOn",
  "registration": "62719-724",
  "registrant": "Corteva Agriscience",
  "productType": "Dry",
  "formulationType": "Dry Flowable",
  "labelProvider": "AGRIAN",
  "productPageUrl": "https://www.agrian.com/labelcenter/results.cfm?d=21666",
  "labels": [
    {
      "name": "Label - 03-R0718",
      "url": "https://www.agrian.com/pdfs/current/Badge_X2_FungicideBactericide_Label1p.pdf"
    }
  ]
}

Get matching products from an operation

GET /products/matching/operations/{operationId} Returns the standard products that best match the products found in a field operation. Use the returned productId with the Get a product endpoint to retrieve registration numbers and labels.

Parameters

Parameter	Type	Description
`operationId`	string (UUID)	Path param — the operation ID.

Request

curl -X GET \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://api.withleaf.io/services/beta/api/products/matching/operations/{operationId}'

Response

[
  {
    "id": "37159c45-4c1f-48e4-aa87-90b34cc6e789",
    "name": "ams",
    "productId": "e5b91778-0714-4e1f-850c-b458d1bdc7ed",
    "matchDetails": {
      "status": "PREDICTED",
      "score": 14.354036
    }
  },
  {
    "id": "7fb70242-498b-42c1-92c3-a7d2361d2125",
    "name": "counter",
    "productId": "a85c1d0d-b673-46aa-a3a3-31cb65f57598",
    "matchDetails": {
      "status": "VALIDATED"
    }
  }
]

Update product matches

PATCH /products/matching/operations/{operationId}/matches/{matchId} Approves or updates a product match prediction. Send "status": "VALIDATED" to approve the current prediction, or send a new productId to change the matched product.

Parameters

Parameter	Type	Description
`operationId`	string (UUID)	Path param — the operation ID.
`matchId`	string (UUID)	Path param — the match ID.

Request body

To approve the prediction:

{
  "status": "VALIDATED"
}

To change the matched product:

{
  "productId": "expectedProductID"
}

Request

curl -X PATCH \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "status": "VALIDATED" }' \
  'https://api.withleaf.io/services/beta/api/products/matching/operations/{operationId}/matches/{matchId}'

Response

[
  {
    "id": "uidd-match-0001",
    "name": "Ta35",
    "productId": "uidd-prd-1001",
    "matchDetails": {
      "score": 91,
      "status": "PREDICTED"
    }
  },
  {
    "id": "uidd-match-0002",
    "name": "Talisman",
    "productId": "uidd-prd-1003",
    "matchDetails": {
      "status": "VALIDATED"
    }
  }
]

Get product matches historical

GET /products/matching/operations/{operationId}/matches/{matchId}/historical Returns the change history for a product match.

Parameters

Parameter	Type	Description
`operationId`	string (UUID)	Path param — the operation ID.
`matchId`	string (UUID)	Path param — the match ID.

Request

curl -X GET \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://api.withleaf.io/services/beta/api/products/matching/operations/{operationId}/matches/{matchId}/historical'

Response

[
  {
    "matchId": "uidd-match-0002",
    "name": "Talisman",
    "productId": "uidd-prd-1003",
    "matchDetails": {
      "status": "PREDICTED",
      "score": 8.225217
    },
    "historicalTime": "2023-12-19T13:18:44.709Z"
  }
]

Varieties

Get all varieties

GET /varieties Returns a paginated list of varieties from providers. Currently supports John Deere.

Parameters

Parameter	Type	Description
`leafUserId`	string (UUID)	Filter by Leaf user.
`provider`	string	Filter by provider (`JohnDeere`).
`page`	integer	Page number (default `0`).
`size`	integer	Page size (max `100`).
`sort`	string	Sorting order. Comma-separated fields with optional `,asc` or `,desc` suffix.

Request

curl -X GET \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://api.withleaf.io/services/beta/api/varieties?leafUserId={leafUserId}'

Response

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "crops": ["ALFALFA"],
    "name": "Master Piece",
    "companyName": "Simplot",
    "status": "ACTIVE",
    "leafUserId": "028c30fa-6d2a-11ee-b962-0242ac120002",
    "provider": "JohnDeere",
    "providerId": "8e1e0920-1265-4066-8067-8ce2ce5012b2",
    "organizationId": "9999"
  }
]

Get a variety

GET /varieties/{id} Returns a single variety by its ID.

Parameters

Parameter	Type	Description
`id`	string (UUID)	Path param — the variety ID.

Request

curl -X GET \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://api.withleaf.io/services/beta/api/varieties/{id}'

Response

{
  "id": "111120cc-d0c5-40d3-a063-ca09903a0738",
  "crops": ["SOYBEANS"],
  "providerId": "f4c43d25-0000-1000-7fc2-e1e1e1193019",
  "name": "2105 2000 mix",
  "companyName": "CHANNEL",
  "status": "ACTIVE",
  "provider": "JohnDeere",
  "leafUserId": "90a7faf4-33d3-4e35-9f46-1894ae13955d",
  "organizationId": "9999"
}

Get summarized varieties

GET /users/{leafUserId}/varieties/summary Returns a summarized list of varieties extracted from machine files for a Leaf user.

Parameters

Parameter	Type	Description
`name`	string	Filter by partial variety name.
`crops`	string	Filter by crop name.
`page`	integer	Page number (default `0`).
`size`	integer	Page size (max `100`).
`sort`	string	Sorting order. Comma-separated fields with optional `,asc` or `,desc` suffix.

Request

curl -X GET \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://api.withleaf.io/services/beta/api/users/{leafUserId}/varieties/summary'

Response

[
  {
    "id": "680ff073-18d0-4951-ba69-b2ca0b098bc3",
    "name": "corn variety 2",
    "leafUserId": "028c30fa-6d2a-11ee-b962-0242ac120002",
    "crops": ["corn"]
  }
]

Search for varieties

GET /varieties/search Searches for varieties by name (partial values supported). John Deere Operation Center varieties are available at the Leaf user level.

Parameters

Parameter	Type	Description
`name`	string	Required. Partial variety name to search.
`maxResults`	integer	Maximum results to return (default `10`, max `20`).
`crop`	string	Filter by crop name.

Request

curl -X GET \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://api.withleaf.io/services/beta/api/varieties/search?name=Master'

Response

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "crops": ["ALFALFA"],
    "name": "Master Piece",
    "companyName": "Simplot",
    "status": "ACTIVE",
    "leafUserId": "028c30fa-6d2a-11ee-b962-0242ac120002",
    "provider": "JohnDeere",
    "providerId": "8e1e0920-1265-4066-8067-8ce2ce5012b2"
  }
]

Tank Mixes

Get all tank mixes

GET /tankMixes Returns a paginated list of tank mixes from providers. Currently supports John Deere.

Parameters

Parameter	Type	Description
`leafUserId`	string (UUID)	Filter by Leaf user.
`provider`	string	Filter by provider (`JohnDeere`).
`page`	integer	Page number (default `0`).
`size`	integer	Page size (max `100`).
`sort`	string	Sorting order. Comma-separated fields with optional `,asc` or `,desc` suffix.

Request

curl -X GET \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://api.withleaf.io/services/beta/api/tankMixes?leafUserId={leafUserId}'

Response

[
  {
    "id": "abc59ca6-937c-11ee-b9d1-0242ac120002",
    "name": "TankTest1",
    "providerId": "b74878dc-937c-11ee-b9d1-0242ac120002",
    "notes": null,
    "solutionRate": {
      "valueAsDouble": 5,
      "unit": "gal1ac-1",
      "vrDomainId": "vrSolutionRateLiquid"
    },
    "formulationType": "LIQUID",
    "targetCrops": ["PINEAPPLE"],
    "carrier": {
      "id": "c0cb84d0-937c-11ee-b9d1-0242ac120002",
      "name": "Water",
      "labelProvider": "JohnDeere",
      "registrant": "GENERIC",
      "productType": "ADDITIVE",
      "formulationType": "LIQUID",
      "carrier": true,
      "status": "ACTIVE"
    },
    "components": [
      {
        "id": "d1fb3aac-937c-11ee-b9d1-0242ac120002",
        "name": "Brandt Big Foot SS",
        "labelProvider": "JohnDeere",
        "registrant": "Brandt Consolidated, Inc.",
        "productType": "ADDITIVE",
        "formulationType": "DRY",
        "carrier": false,
        "status": "ACTIVE"
      }
    ],
    "status": "ACTIVE",
    "provider": "JohnDeere",
    "leafUserId": "cd06377c-937c-11ee-b9d1-0242ac120002"
  }
]

Search for tank mixes

GET /tankMixes/search Searches for tank mixes by name (partial values supported). John Deere Operation Center tank mixes are available at the Leaf user level.

Parameters

Parameter	Type	Description
`name`	string	Required. Partial tank mix name to search.
`maxResults`	integer	Maximum results to return (default `10`, max `20`).

Request

curl -X GET \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://api.withleaf.io/services/beta/api/tankMixes/search?name=Tank'

Response

[
  {
    "id": "abc59ca6-937c-11ee-b9d1-0242ac120002",
    "name": "TankTest1",
    "providerId": "b74878dc-937c-11ee-b9d1-0242ac120002",
    "notes": null,
    "solutionRate": {
      "valueAsDouble": 5,
      "unit": "gal1ac-1",
      "vrDomainId": "vrSolutionRateLiquid"
    },
    "formulationType": "LIQUID",
    "targetCrops": ["PINEAPPLE"],
    "carrier": {
      "id": "c0cb84d0-937c-11ee-b9d1-0242ac120002",
      "name": "Water",
      "labelProvider": "JohnDeere",
      "registrant": "GENERIC",
      "productType": "ADDITIVE",
      "formulationType": "LIQUID",
      "carrier": true,
      "status": "ACTIVE"
    },
    "components": [
      {
        "id": "d1fb3aac-937c-11ee-b9d1-0242ac120002",
        "name": "Brandt Big Foot SS",
        "labelProvider": "JohnDeere",
        "registrant": "Brandt Consolidated, Inc.",
        "productType": "ADDITIVE",
        "formulationType": "DRY",
        "carrier": false,
        "status": "ACTIVE"
      }
    ],
    "status": "ACTIVE",
    "provider": "JohnDeere",
    "leafUserId": "cd06377c-937c-11ee-b9d1-0242ac120002"
  }
]

Authentication

Configuration

Leaf Users

Alerts

Providers

Data Hierarchy

Machine data

Satellite imagery

Weather

Leaf Lake

UI components

MCP server

Irrigation

Usage tracking

Beta

​Base URL

​Endpoints

​Products

​Varieties

​Tank Mixes

​Products

​Get all products

​Parameters

​Request

​Response

​Get summarized products

​Parameters

​Request

​Response

​Search for products

​Parameters

​Request

​Response

​Get a product

​Parameters

​Request

​Response

​Get matching products from an operation

​Parameters

​Request

​Response

​Update product matches

​Parameters

​Request body

​Request

​Response

​Get product matches historical

​Parameters

​Request

​Response

​Varieties

​Get all varieties

​Parameters

​Request

​Response

​Get a variety

​Parameters

​Request

​Response

​Get summarized varieties

​Parameters

​Request

​Response

​Search for varieties

​Parameters

​Request

​Response

​Tank Mixes

​Get all tank mixes

​Parameters

​Request

​Response

​Search for tank mixes

​Parameters

​Request

​Response

Base URL

Endpoints

Products

Varieties

Tank Mixes

Products

Get all products

Parameters

Request

Response

Get summarized products

Parameters

Request

Response

Search for products

Parameters

Request

Response

Get a product

Parameters

Request

Response

Get matching products from an operation

Parameters

Request

Response

Update product matches

Parameters

Request body

Request

Response

Get product matches historical

Parameters

Request

Response

Varieties

Get all varieties

Parameters

Request

Response

Get a variety

Parameters

Request

Response

Get summarized varieties

Parameters

Request

Response

Search for varieties

Parameters

Request

Response

Tank Mixes

Get all tank mixes

Parameters

Request

Response

Search for tank mixes

Parameters

Request

Response