Endpoints

About

All HTTP methods should be prepended by this service's endpoint:

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

See below the REST resources and their endpoints available in this service.

Machines (BETA)

Machine Resources

This feature has the following endpoints available:

DescriptionEndpoints
Get all machinesGET /users/{leafUserId}/machines
Create a machinePOST /users/{leafUserId}/machines
Get a machineGET /users/{leafUserId}/machines/{machineId}
Get machine filesPATCH /users/{leafUserId}/machines/{machineId}/files
Delete a machineDELETE /users/{leafUserId}/machines/{machineId}
Update a machinePATCH /users/{leafUserId}/machines/{machineId}

Get all machines

 GET /users/{leafUserId}/machines

Get the list of machines that are related to a given LeafUserId. Some fields can be sent as query parameters to filter the machines, such as:

Parameter (to filter by)Values
nametext
providertext (JohnDeere, CaseIH, Stara, etc)
providerOrganizationIdtext
serialNumbertext
originTypespecify the origin of the machine, must be either USER_CREATED, FILE_POOLED or PROVIDER_POOLED
createdAtmust match exactly the time of the record creation, ISO 8601 without timezone
beforeCreatedAtfilters for records created before the datetime, ISO 8601 without timezone
afterCreatedAtfilters for records created after the datetime, ISO 8601 without timezone
vinfilters machines by Vehicle Identification Number

You can also pass some parameters used exclusively for paging through results. They are:

  • page, an integer specifying the page being fetched (default is 0)
  • size, an integer specifying the size of the page (max is 100)
  • sort, the sorting order of the results; can be multivalue, the former takes precedence over the later; can also specify order as asc or desc with asc being the default. Example: id,desc
    • Valid values for sorting are: id, leafUserId, name, provider, providerOrganizationId, providerMachineId, serialNumber, vin, model, make, category

For more request examples see Leaf Postman collection

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

Response

The response is a JSON array containing machine records.

[
{
"id": "UUID",
"leafUserId": "UUID",
"name": "str",
"provider": null,
"providerMachineId": null,
"providerOrganizationId": null,
"originType": "PROVIDER_POOLED",
"createdAt": "2022-02-22T20:06:25.411Z",
"serialNumber": "123456",
"vin": "1234567890ABC",
"model": "ModelName",
"make": "MakerOfMachine",
"category": "Sprayer",
"modelYear": 2000
},
{
"id": "UUID",
"leafUserId": "UUID",
"name": "str",
"provider": null,
"providerMachineId": null,
"providerOrganizationId": null,
"originType": "FILE_POOLED",
"createdAt": "2022-02-22T20:06:25.411Z",
"serialNumber": "123456",
"vin": "1234567890ABC",
"model": "ModelName",
"make": "MakerOfMachine",
"category": "Harvester",
"modelYear": 2020
}
]

Create a machine

 POST /users/{leafUserId}/machines

Creates a machine for a specific LeafUser.

Request body

{
"name": "str"
}
curl -X POST \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{ "name": "str"}' \
'https://api.withleaf.io/services/beta/api/users/{leafUserId}/machines'

Response

A new machine is assigned to the given LeafUserId.

{
"id": "UUID",
"leafUserId": "UUID",
"name": "str",
"provider": null,
"providerMachineId": null,
"providerOrganizationId": null
}

Get a machine

 GET /api/users/{leafUserId}/machines/{machineId}

Get the details of a given machine by its id.

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

Response

A machine record with more details.

{
"id": "UUID",
"leafUserId": "UUID",
"name": "str",
"provider": null,
"providerMachineId": null,
"providerOrganizationId": null,
"originType": "PROVIDER_POOLED",
"createdAt": "2022-02-22T20:06:25.411Z",
"serialNumber": "123456",
"vin": "1234567890ABC",
"model": "ModelName",
"make": "MakerOfMachine",
"category": "Sprayer",
"modelYear": 2000
}

Get machine files

 GET /api/users/{leafUserId}/machines/{machineId}/files

Get the details of machine operations files given a machine id. Some fields can be sent as query parameters to filter the machine files, such as:

Parameter (to filter by)Values
leafFileIdUUID
originTypespecify the origin of the machine, must be either USER_CREATED, FILE_POOLED or PROVIDER_POOLED
createdAtan ISO 8601 without timezone specifying the operation exact created time
beforeCreatedAtfilters for records created before the datetime, ISO 8601 without timezone
afterCreatedAtfilters for records created after the datetime, ISO 8601 without timezone
startTimemust match exactly the time of the start of the operation, ISO 8601 without timezone
endTimemust match exactly the time of the end of the operation, ISO 8601 without timezone
beforeStartTimean ISO 8601 without timezone, returns all operations that started before the specified time
afterStartTimean ISO 8601 without timezone, returns all operations that started after the specified time
beforeEndTimean ISO 8601 without timezone, returns all operations that ended before the specified time
afterEndtimean ISO 8601 without timezone, returns all operations that ended after the specified time
distanceValuea double value for the distance
greaterThanDistanceValuea double value for the distance, returns all operations that have a distance value greater than the specified distance
lessThanDistanceValuea double value for the distance, returns all operations that have a distance value lesser than the specified distance
distanceUnitmust be "Mile", "mile", "Feet" or "ft"

You can also pass some parameters used exclusively for paging through results. They are:

  • page, an integer specifying the page being fetched (default is 0)
  • size, an integer specifying the size of the page (max is 100)
  • sort, the sorting order of the results; can be multivalue, the former takes precedence over the later; can also specify order as asc or desc with asc being the default. Example: id,desc
    • Valid values for sorting are: id, leafUserId, machineId, startTime, endTime, createdAt, leafFileId

For more request examples see Leaf Postman collection

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

Response

A json array containing the machine operations files details.

[
{
"id": "UUID",
"leafFileId": "UUID",
"machineId": "UUID",
"startTime": "YYYY-mm-ddThh:mm:ssZ",
"endTime": "YYYY-mm-ddThh:mm:ssZ",
"distance": {
"value": float,
"unit": "ft"
},
"fuelConsumption": {
"value": float,
"unit": "US gal"
}
},
{
"id": "UUID",
"leafFileId": "UUID",
"machineId": "UUID",
"startTime": "YYYY-mm-ddThh:mm:ssZ",
"endTime": "YYYY-mm-ddThh:mm:ssZ",
"distance": {
"value": float,
"unit": "ft"
},
"fuelConsumption": {
"value": float,
"unit": "US gal"
}
}
]

Delete a machine

 DELETE /api/users/{leafUserId}/machines/{machineId}

Delete a machine data

Only machines created by the user can be Deleted

Machine data obtained from providers cannot be deleted

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

Update a machine

 PATCH /api/users/{leafUserId}/machines/{machineId}

Update a machine for a specific LeafUser.

Only machines created by the user can be updated

Machine data obtained from providers cannot be updated

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