Endpoints

About

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

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

This service has the following endpoints available:

DescriptionEndpoints
Get all operationsGET /operations
Get an operationGET /operations/{id}
Get an operation summaryGET /operations/{id}/summary
Get an operation's imagesGET /operations/{id}/images
Get an operation's images V2GET /operations/{id}/imagesV2
Get an operation's unitsGET /operations/{id}/units
Reprocess an operationPOST /operations/{id}/reprocess

For easily testing these endpoints, we recommend using our Postman collection.

Get all operations

 GET /operations

Gets a paged list of operations that belong to the current logged in user. It is possible to filter the results by passing some query parameters. They are listed below.

Parameter (to filter by)Values
leafUserIduuid of one of your users
providerCNHI, JohnDeere, Trimble, ClimateFieldView, AgLeader or Leaf
startTimeISO 8601 date. Returns operations from the startTime onward
updatedTimeISO 8601 date. Returns operations from the updatedTime onward
endTimeISO 8601 date. Returns operations until the endTime
operationTypeapplied, planted or harvested
fieldIdthe field where the operation happened

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)
the default value for page size is 20

If the parameters page and size are not set, the endpoint will return 20 results.

curl -X GET \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/operations/api/operations'

Response

[
{
"id": "1aa1ce7b-8bb9-4b2d-9421-d7a662cc1bb1",
"apiOwnerUsername": "leaf",
"leafUserId": "97770d44-62c4-48c3-8187-6be80f6de3d2",
"startTime": "2015-04-18T19:31:27Z",
"endTime": "2015-04-18T19:58:50Z",
"updatedTime": "2021-08-24T16:00:15.062Z",
"type": "planted",
"files": [
"8334f4bb-48de-44e2-903b-6dedd6db6683",
"81778f58-8eed-41cc-a025-e653ea85b01e",
"0f606bef-b529-4899-854c-9b698cd08762",
"84fec273-b458-4be7-8feb-44204502f126",
"92b7367b-2ffd-4a82-ba9b-5a40e8b68714"
],
"fields": [
{
"id": "3a90d11a-70d0-4f62-b6d4-32006b1dcb6a"
}
]
}
]

Get an operation

 GET /operations/{id}

Gets a single operation by its id.

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

Response

{
"id": "1aa1ce7b-8bb9-4b2d-9421-d7a662cc1bb1",
"apiOwnerUsername": "leaf",
"leafUserId": "97770d44-62c4-48c3-8187-6be80f6de3d2",
"startTime": "2015-04-18T19:31:27Z",
"endTime": "2015-04-18T19:58:50Z",
"updatedTime": "2021-08-24T16:00:15.062Z",
"type": "planted",
"files": [
"8334f4bb-48de-44e2-903b-6dedd6db6683",
"81778f58-8eed-41cc-a025-e653ea85b01e",
"0f606bef-b529-4899-854c-9b698cd08762",
"84fec273-b458-4be7-8feb-44204502f126",
"92b7367b-2ffd-4a82-ba9b-5a40e8b68714"
],
"fields": [
{
"id": "3a90d11a-70d0-4f62-b6d4-32006b1dcb6a"
}
]
}

Get an operation summary

 GET /operations/{id}/summary

Gets the summary, if available, for the operation id.

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

Response

Here's a link with sample responses for "planted", "applied" and "harvested" operations.


Get an operation's images

 GET /operations/{id}/images

Gets a list of PNG images generated from the operation's properties.

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

Get an operation's images V2

 GET /operations/{id}/imagesV2

Gets a list of PNG images generated from the operation's properties with improvements in the generation process. These images are based on the filteredGeojson.

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

Get an operation's units

 GET /operations/{id}/units

Gets the operations's properties and their units.

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

Crop operation by field

 POST /operations/cropOperationByField

This endpoint can be used to remove points from the operation standardGeojson that are outside of the field geometry.

curl -X POST \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{ "id": "operationId"}' \
'https://api.withleaf.io/services/operations/api/operations/cropOperationByField'

Response

Returns a single JSON object:

{
"id": "163982a0-d4e8-49a0-9572-9079e17f7c7d",
"message": "Sent operation to be processed.",
"leafFileId": "8924ca07-4168-4f15-83ec-37dd344888f6"
}

You could monitor the processing status using the leafFileId by our Alerts Service.

Reprocess an operation

 POST /operations/{id}/reprocess

Allows reprocessing an operation already created, starting from the merge step. The standardGeoJSON, filteredGeoJSON, summary and images will be updated.

curl -X POST \
-H 'Authorization: Bearer YOUR_TOKEN' \
'https://api.withleaf.io/services/operations/api/operations/{id}/reprocess'

You could monitor the processing status by our Alerts Service.


Alerts

With Alerts you can be notified when something happens or changes instead of needing to repeatedly query for changes. Leaf Alerts support events that happen within Leaf and events that happen within supported 3rd party software.

List of Operations Events

Leaf Operations Service can Alert you on these events: list of Operations Events