Beta Assets - Leaf Documentation

Use these endpoints to manage machines, implements, and operators for a Leaf user — whether synced from John Deere, CNHi, Stara, and Trimble or created manually through the API. For conceptual background, see Assets.

The Assets 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

Endpoint	Method	Path
Get all machines	GET	`/users/{leafUserId}/machines`
Get a machine	GET	`/users/{leafUserId}/machines/{machineId}`
Get machine files	GET	`/users/{leafUserId}/machines/{machineId}/files`
Create a machine	POST	`/users/{leafUserId}/machines`
Update a machine	PATCH	`/users/{leafUserId}/machines/{machineId}`
Delete a machine	DELETE	`/users/{leafUserId}/machines/{machineId}`
Get all implements	GET	`/users/{leafUserId}/implements`
Get an implement	GET	`/users/{leafUserId}/implements/{implementId}`
Get all operators	GET	`/users/{leafUserId}/operators`
Get an operator	GET	`/users/{leafUserId}/operators/{operatorId}`

Machines

Get all machines

GET /users/{leafUserId}/machines Returns a paginated list of machines for a Leaf user.

Parameters

Parameter	Type	Description
`name`	string	Filter by machine name.
`provider`	string	Filter by provider (`JohnDeere`, `Stara`, `CNHi`).
`providerOrganizationId`	string	Filter by provider-side organization ID.
`providerMachineId`	string	Filter by provider-side machine ID.
`serialNumber`	string	Filter by machine serial number.
`originType`	string	Origin of the machine: `USER_CREATED`, `FILE_POOLED`, or `PROVIDER_POOLED`.
`createdTime`	string (ISO 8601)	Must match exactly the creation timestamp.
`beforeCreatedTime`	string (ISO 8601)	Records created before this timestamp.
`afterCreatedTime`	string (ISO 8601)	Records created after this timestamp.
`updatedAt`	string (ISO 8601)	Must match exactly the last-updated timestamp.
`beforeUpdatedAt`	string (ISO 8601)	Records updated before this timestamp.
`afterUpdatedAt`	string (ISO 8601)	Records updated after this timestamp.
`vin`	string	Filter by Vehicle Identification Number.
`page`	integer	Page number (default `0`).
`size`	integer	Page size (default `20`, max `100`).
`sort`	string	Sorting order. Valid fields: `id`, `leafUserId`, `name`, `provider`, `providerOrganizationId`, `providerMachineId`, `serialNumber`, `vin`, `model`, `make`, `category`, `modelYear`. Append `,asc` or `,desc`.

The default page size is 20 when page and size are not set.

Request

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

Response

[
  {
    "id": "e89b1861-bdbb-49b9-8e11-74840f7e1ea8",
    "leafUserId": "faa6691a-7bf7-49c2-8934-b5b4c823aef8",
    "name": "TestName",
    "provider": "Leaf",
    "providerMachineId": "08790ae9-d451-4158-9920-09d1ab1ba5e6",
    "providerOrganizationId": "123456",
    "originType": "PROVIDER_POOLED",
    "createdTime": "2022-02-22T20:06:25.411Z",
    "serialNumber": "123456",
    "vin": "1234567890ABC",
    "model": "ModelName",
    "make": "MakerOfMachine",
    "category": "Sprayer",
    "modelYear": 2000
  },
  {
    "id": "82725746-3150-490d-9f3f-a47151ac0669",
    "leafUserId": "325f5ac0-6c57-4b4a-bdea-490ccddb06c4",
    "name": "nameTest",
    "provider": "Leaf",
    "providerMachineId": "75f362b4-8f61-46f9-905b-a357fb239930",
    "providerOrganizationId": "654321",
    "originType": "FILE_POOLED",
    "createdTime": "2022-02-22T20:06:25.411Z",
    "serialNumber": "123456",
    "vin": "1234567890ABC",
    "model": "ModelName",
    "make": "MakerOfMachine",
    "category": "Harvester",
    "modelYear": 2020
  }
]

Get a machine

GET /users/{leafUserId}/machines/{machineId} Returns details for a single machine by its ID.

Parameters

Parameter	Type	Description
`leafUserId`	string (UUID)	Path param — the Leaf user ID.
`machineId`	string (UUID)	Path param — the machine ID.

Request

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

Response

{
  "id": "e89b1861-bdbb-49b9-8e11-74840f7e1ea8",
  "leafUserId": "faa6691a-7bf7-49c2-8934-b5b4c823aef8",
  "name": "TestName",
  "provider": "Leaf",
  "providerMachineId": "08790ae9-d451-4158-9920-09d1ab1ba5e6",
  "providerOrganizationId": "123456",
  "originType": "PROVIDER_POOLED",
  "createdTime": "2022-02-22T20:06:25.411Z",
  "serialNumber": "123456",
  "vin": "1234567890ABC",
  "model": "ModelName",
  "make": "MakerOfMachine",
  "category": "Sprayer",
  "modelYear": 2000
}

Get machine files

GET /users/{leafUserId}/machines/{machineId}/files Returns operation files associated with a specific machine.

Parameters

Parameter	Type	Description
`leafFileId`	string (UUID)	Filter by Leaf file ID.
`originType`	string	`USER_CREATED`, `FILE_POOLED`, or `PROVIDER_POOLED`.
`createdTime`	string (ISO 8601)	Must match exactly the creation timestamp.
`beforeCreatedTime`	string (ISO 8601)	Records created before this timestamp.
`afterCreatedTime`	string (ISO 8601)	Records created after this timestamp.
`startTime`	string (ISO 8601)	Must match exactly the operation start time.
`endTime`	string (ISO 8601)	Must match exactly the operation end time.
`beforeStartTime`	string (ISO 8601)	Operations that started before this timestamp.
`afterStartTime`	string (ISO 8601)	Operations that started after this timestamp.
`beforeEndTime`	string (ISO 8601)	Operations that ended before this timestamp.
`afterEndTime`	string (ISO 8601)	Operations that ended after this timestamp.
`distanceValue`	double	Exact distance value.
`greaterThanDistanceValue`	double	Distance greater than this value.
`lessThanDistanceValue`	double	Distance less than this value.
`distanceUnit`	string	`Mile`, `mile`, `Feet`, or `ft`.
`page`	integer	Page number (default `0`).
`size`	integer	Page size (default `20`, max `100`).
`sort`	string	Valid fields: `id`, `leafUserId`, `machineId`, `startTime`, `endTime`, `createdTime`, `leafFileId`.

The default page size is 20 when page and size are not set.

Request

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

Response

[
  {
    "id": "e7916d05-97ae-404a-a467-e2512c202a2f",
    "leafFileId": "e0e18a6f-4f88-4801-96e2-f39143f260e1",
    "machineId": "98b244fc-7b2d-4acf-a51a-58d20ae27355",
    "startTime": "2022-02-22T20:06:25.411Z",
    "endTime": "2022-02-22T20:07:25.411Z",
    "distance": {
      "value": 4152.255,
      "unit": "ft"
    },
    "fuelConsumption": {
      "value": 28.89,
      "unit": "US gal"
    }
  }
]

Create a machine

POST /users/{leafUserId}/machines Creates a new machine for a Leaf user.

Request body

Field	Type	Description
`name`	string	Machine name.
`serialNumber`	string	Serial number.
`vin`	string	Vehicle Identification Number.
`model`	string	Model name.
`make`	string	Manufacturer.
`category`	string	Machine category (e.g. `Harvester`, `Sprayer`).
`modelYear`	integer	Model year.

Request

curl -X POST \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "nameTest",
    "serialNumber": "123456",
    "vin": "1234567890ABC",
    "model": "ModelName",
    "make": "MakerOfMachine",
    "category": "Harvester",
    "modelYear": 2020
  }' \
  'https://api.withleaf.io/services/beta/api/users/{leafUserId}/machines'

Response

{
  "id": "d5efe8a1-98be-40db-b2b2-2da332e8f69c",
  "name": "nameTest",
  "provider": "Leaf",
  "providerMachineId": "24de86ff-e6f0-4f8f-b429-0571c30a7ddf",
  "providerOrganizationId": "654321",
  "leafUserId": "9e081c9d-6185-49e1-8df7-7788d6aa1211",
  "originType": "USER_CREATED",
  "createdTime": "2023-06-12T17:38:09.148Z",
  "serialNumber": "123456",
  "vin": "1234567890ABC",
  "model": "ModelName",
  "make": "MakerOfMachine",
  "category": "Harvester",
  "modelYear": 2020
}

Update a machine

PATCH /users/{leafUserId}/machines/{machineId} Updates an existing machine for a Leaf user.

Only machines with originType of USER_CREATED can be updated. Machine data obtained from providers cannot be modified.

Request body

Field	Type	Description
`name`	string	Updated machine name.
`serialNumber`	string	Updated serial number.
`vin`	string	Updated VIN.
`model`	string	Updated model name.
`make`	string	Updated manufacturer.
`category`	string	Updated category.
`modelYear`	integer	Updated model year.

Request

curl -X PATCH \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "updatedName",
    "serialNumber": "000123",
    "vin": "1234567890EFR",
    "model": "ModelNameUpdated",
    "make": "MakerOfMachineUpdated",
    "category": "Planted",
    "modelYear": 2021
  }' \
  'https://api.withleaf.io/services/beta/api/users/{leafUserId}/machines/{machineId}'

Response

{
  "id": "d5efe8a1-98be-40db-b2b2-2da332e8f69c",
  "name": "updatedName",
  "provider": "Leaf",
  "providerMachineId": "24de86ff-e6f0-4f8f-b429-0571c30a7ddf",
  "providerOrganizationId": "654321",
  "leafUserId": "9e081c9d-6185-49e1-8df7-7788d6aa1211",
  "originType": "USER_CREATED",
  "createdTime": "2023-06-12T17:38:09.148Z",
  "serialNumber": "000123",
  "vin": "1234567890EFR",
  "model": "ModelNameUpdated",
  "make": "MakerOfMachineUpdated",
  "category": "Planted",
  "modelYear": 2021
}

Delete a machine

DELETE /users/{leafUserId}/machines/{machineId} Deletes a machine by its ID.

Only machines with originType of USER_CREATED can be deleted. Machine data obtained from providers cannot be removed.

Parameters

Parameter	Type	Description
`leafUserId`	string (UUID)	Path param — the Leaf user ID.
`machineId`	string (UUID)	Path param — the machine ID.

Request

curl -X DELETE \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://api.withleaf.io/services/beta/api/users/{leafUserId}/machines/{machineId}'

Implements

Get all implements

GET /users/{leafUserId}/implements Returns a paginated list of implements for a Leaf user. Currently supports John Deere and Trimble implements.

Parameters

Parameter	Type	Description
`leafUserId`	string (UUID)	Filter by Leaf user ID.
`provider`	string	Filter by provider (`JohnDeere`, `Trimble`).
`providerImplementId`	string	Filter by provider-side implement ID.
`providerOrganizationId`	string	Filter by provider-side organization ID.
`name`	string	Filter by implement name.
`createdTime`	string (ISO 8601)	Returns records from the given creation time onward.
`beforeCreatedTime`	string (ISO 8601)	Records created before this timestamp.
`afterCreatedTime`	string (ISO 8601)	Records created after this timestamp.
`updatedTime`	string (ISO 8601)	Returns records from the given update time onward.
`beforeUpdatedTime`	string (ISO 8601)	Records updated before this timestamp.
`afterUpdatedTime`	string (ISO 8601)	Records updated after this timestamp.
`page`	integer	Page number (default `0`).
`size`	integer	Page size (default `20`, max `100`).
`sort`	string	Valid fields: `id`, `leafUserId`, `name`, `provider`, `providerOrganizationId`, `providerImplementId`, `serialNumber`, `model`, `make`, `category`.

The default page size is 20 when page and size are not set.

Request

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

Response

[
  {
    "id": "38d313fc-e4ce-442b-9147-f469b30aedab",
    "name": "c3po_implement",
    "provider": "JohnDeere",
    "providerImplementId": "110237",
    "providerOrganizationId": "296264",
    "leafUserId": "mbba54fb-3710-4f7d-9aaf-703107930193",
    "originType": "PROVIDER_POOLED",
    "serialNumber": "00000",
    "model": "StMax150",
    "make": "JOHN DEERE",
    "category": "Cotton Harvester Implement"
  }
]

Get an implement

GET /users/{leafUserId}/implements/{implementId} Returns details for a single implement by its ID.

Parameters

Parameter	Type	Description
`leafUserId`	string (UUID)	Path param — the Leaf user ID.
`implementId`	string (UUID)	Path param — the implement ID.

Request

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

Response

{
  "id": "38d313fc-e4ce-442b-9147-f469b30aedab",
  "name": "c3po_implement",
  "provider": "JohnDeere",
  "providerImplementId": "110237",
  "providerOrganizationId": "296264",
  "leafUserId": "mbba54fb-3710-4f7d-9aaf-703107930193",
  "originType": "PROVIDER_POOLED",
  "serialNumber": "00000",
  "model": "StMax150",
  "make": "JOHN DEERE",
  "category": "Cotton Harvester Implement"
}

Operators

Get all operators

GET /users/{leafUserId}/operators Returns a paginated list of operators for a Leaf user. Currently supports John Deere operators.

Parameters

Parameter	Type	Description
`page`	integer	Page number (default `0`).
`size`	integer	Page size (default `20`, max `100`).

The default page size is 20 when page and size are not set.

Request

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

Response

[
  {
    "id": "aa8c917bc-7e9b-47bc-99b8-4a0df818ab07",
    "name": "Brian O.",
    "provider": "JohnDeere",
    "providerOperatorId": "bbd3a3e8-5ac3-4ab8-4619-d582da4568cc",
    "providerOrganizationId": "9999",
    "originType": "PROVIDER_POOLED",
    "license": null,
    "updatedTime": "2023-10-10T10:10:10.000Z",
    "status": "ACTIVE"
  }
]

Get an operator

GET /users/{leafUserId}/operators/{operatorId} Returns details for a single operator by its ID.

Parameters

Parameter	Type	Description
`leafUserId`	string (UUID)	Path param — the Leaf user ID.
`operatorId`	string (UUID)	Path param — the operator ID.

Request

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

Response

{
  "id": "aa8c917bc-7e9b-47bc-99b8-4a0df818ab07",
  "name": "Brian O.",
  "provider": "JohnDeere",
  "providerOperatorId": "bbd3a3e8-5ac3-4ab8-4619-d582da4568cc",
  "providerOrganizationId": "9999",
  "originType": "PROVIDER_POOLED",
  "license": null,
  "updatedTime": "2023-10-10T10:10:10.000Z",
  "status": "ACTIVE"
}

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

​Machines

​Get all machines

​Parameters

​Request

​Response

​Get a machine

​Parameters

​Request

​Response

​Get machine files

​Parameters

​Request

​Response

​Create a machine

​Request body

​Request

​Response

​Update a machine

​Request body

​Request

​Response

​Delete a machine

​Parameters

​Request

​Implements

​Get all implements

​Parameters

​Request

​Response

​Get an implement

​Parameters

​Request

​Response

​Operators

​Get all operators

​Parameters

​Request

​Response

​Get an operator

​Parameters

​Request

​Response

Base URL

Endpoints

Machines

Get all machines

Parameters

Request

Response

Get a machine

Parameters

Request

Response

Get machine files

Parameters

Request

Response

Create a machine

Request body

Request

Response

Update a machine

Request body

Request

Response

Delete a machine

Parameters

Request

Implements

Get all implements

Parameters

Request

Response

Get an implement

Parameters

Request

Response

Operators

Get all operators

Parameters

Request

Response

Get an operator

Parameters

Request

Response