Machine Files & Upload - Leaf Documentation

Use the files endpoints to inspect individual machine files after Leaf ingests them from a provider or manual upload. This page also covers batch upload endpoints, processing-status inspection, and helper endpoints for uncovered or outside-field data. For conceptual background, see Machine Data Overview and Uploading Files.

Base URL

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

Endpoints

Machine files

Method	Path	Description
GET	`/files`	Get all machine files
GET	`/files/{id}`	Get a machine file
GET	`/files/{id}/summary`	Get file summary
GET	`/files/{id}/standardGeoparquet`	Get file standardGeoParquet
GET	`/files/{id}/polygonGeoparquet`	Get file polygonGeoParquet
GET	`/files/{id}/units`	Get file units
GET	`/files/{id}/status`	Get file status
GET	`/files/{id}/outsideFieldGeojson`	Get file outsideFieldGeoJSON
GET	`/files/outsideFieldGeojson`	Get all outsideFieldGeoJSON
GET	`/files/uncoveredFiles`	Get uncovered files
POST	`/files/merge`	Merge files

Batch upload

Method	Path	Description
POST	`/batch`	Upload a file
GET	`/batch/{id}`	Get a batch
GET	`/batch`	Get all batches
PUT	`/batch/{id}/retry`	Retry a batch
GET	`/batch/{id}/status`	Get batch files status

To access machine files, you need a Leaf user with valid provider credentials. See the Users and Integrations documentation to set up credentials.

Get all machine files

GET /files Returns a paginated list of machine files for the authenticated API owner.

Parameters

Parameter	Type	Description
`leafUserId`	string	UUID of a Leaf user
`provider`	string	`CNHI`, `JohnDeere`, `Trimble`, `ClimateFieldView`, `AgLeader`, `RavenSlingshot`, `Stara`, or `Leaf`
`status`	string	`processed`, `failed`, or `processing`
`origin`	string	`provider`, `automerged`, `merged`, or `uploaded`
`organizationId`	string	Provider organization ID (John Deere only)
`batchId`	string	UUID of the upload batch
`fileId`	string	Filter by a specific file ID
`fileFormat`	string	Filter by file format (e.g., `SHAPEFILE`, `CN1`, `ISO11783`, `AGDATA`)
`createdTime`	string	ISO 8601 timestamp. Returns files created on or after this time
`startTime`	string	ISO 8601 timestamp. Returns files with operations starting on or after this time
`updatedTime`	string	ISO 8601 timestamp. Returns files updated on or after this time
`endTime`	string	ISO 8601 timestamp. Returns files with operations ending on or before this time
`operationStartTime`	string	ISO 8601 timestamp. Same as `startTime` (alternative parameter name)
`operationEndTime`	string	ISO 8601 timestamp. Same as `endTime` (alternative parameter name)
`operationType`	string	`applied`, `planted`, `harvested`, or `tillage`
`minArea`	number	Minimum operation area in square meters
`providerFileId`	string	The file ID from the original provider
`standard`	boolean	Filter by whether the file has a standardGeojson
`page`	integer	Page number (default `0`)
`size`	integer	Page size (max `100`)
`sort`	string	Sort order. Valid fields: `id`, `fileName`, `createdTime`, `updatedTime`, `origin`, `leafUserId`, `sizeInBytes`, `provider`, `organizationId`, `fileFormat`. 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/operations/api/files?leafUserId=UUID'

Get a machine file

GET /files/{id} Returns a single machine file by its UUID.

Parameters

Parameter	Type	Description
`id`	path	UUID of the file

Request

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

Get file summary

GET /files/{id}/summary Returns the summary for a machine file, containing aggregated statistics for the file’s data points.

Parameters

Parameter	Type	Description
`id`	path	UUID of the file

Request

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

Get file standardGeoParquet

GET /files/{id}/standardGeoparquet Returns a URL to the standard GeoParquet file.

You must enable the enableGeoparquetOutput configuration to use this endpoint.

Parameters

Parameter	Type	Description
`id`	path	UUID of the file

Request

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

Get file polygonGeoParquet

GET /files/{id}/polygonGeoparquet Returns a URL to the polygon GeoParquet file.

You must enable the enableGeoparquetOutput configuration to use this endpoint.

Parameters

Parameter	Type	Description
`id`	path	UUID of the file

Request

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

Get file units

GET /files/{id}/units Returns the property-to-unit mapping for the machine file. Properties vary by operation type but use standardized keys across providers.

Parameters

Parameter	Type	Description
`id`	path	UUID of the file

Request

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

Get file status

GET /files/{id}/status Returns the processing status for each step of Leaf’s pipeline for the specified machine file.

Parameters

Parameter	Type	Description
`id`	path	UUID of the file

Request

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

Response

{
  "originalFile":      { "status": "processed", "message": "ok" },
  "rawGeojson":        { "status": "processed", "message": "ok" },
  "standardGeojson":   { "status": "processed", "message": "ok" },
  "filteredGeojson":   { "status": "processed", "message": "ok" },
  "propertiesPNGs":    { "status": "processed", "message": "ok" },
  "zippedPNGs":        { "status": "processed", "message": "ok" },
  "summary":           { "status": "processed", "message": "ok" },
  "units":             { "status": "processed", "message": "ok" }
}

Each key represents a pipeline step. The status value is one of:

Status	Meaning
`processed`	Step completed successfully
`failed`	Step failed — see `message` for details
`skipped`	Step was skipped due to an earlier failure or a configuration that prevents execution

Common failure messages

Message	Cause
`no points passed the filter`	All data points were removed during cleanup. The file may have 0 valid points. Toggle the `cleanupStandardGeojson` configuration to control this behavior.
`unsupported operation type: {type}`	The detected operation type is not one of the four supported types (planting, application, harvest, tillage).
`missing required properties: {properties}`	One or more required properties from Leaf’s standard schema were not found in the file.
`Failed to convert file on provider batch processing`	Leaf could not extract valid data from the provider file. Verify the file structure and format.

Get file outsideFieldGeoJSON

GET /files/{id}/outsideFieldGeojson Returns a GeoJSON file containing data points from the machine file that do not fall within any field boundary.

Requires both splitOperationsByField and enableOutsideFieldGeojson configurations to be enabled.

Parameters

Parameter	Type	Description
`id`	path	UUID of the file

Request

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

Response

{
  "fields": ["uuid"],
  "featureCount": 21,
  "outsideFieldGeojson": "URL",
  "downloadOutsideFieldGeojson": "URL"
}

Get all outsideFieldGeoJSON

GET /files/outsideFieldGeojson Returns a list of all machine files that have data points outside field boundaries.

Requires both splitOperationsByField and enableOutsideFieldGeojson configurations to be enabled.

Parameters

Parameter	Type	Description
`leafUserId`	string	UUID of a Leaf user
`page`	integer	Page number (default `0`)
`size`	integer	Page size (max `100`)
`sort`	string	Sort order (e.g., `id,desc`)

Request

curl -X GET \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://api.withleaf.io/services/operations/api/files/outsideFieldGeojson?leafUserId=UUID'

Response

[
  {
    "id": "uuid",
    "fields": ["uuid"],
    "featureCount": 21,
    "outsideFieldGeojson": "URL",
    "downloadOutsideFieldGeojson": "URL"
  }
]

Get uncovered files

GET /files/uncoveredFiles Returns a list of machine file IDs that did not generate field operations because they do not intersect with any field boundary.

Parameters

Parameter	Type	Description
`leafUserId`	string	Required. UUID of a Leaf user

Request

curl -X GET \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://api.withleaf.io/services/operations/api/files/uncoveredFiles?leafUserId=UUID'

Response

{
  "files": [
    "c3ad6c7b-19b8-4cd7-580a-dfab82043465",
    "c3ad6c7b-c472-49e9-aab2-7ad222843465"
  ]
}

Merge files

POST /files/merge Merges two or more machine files into a single file. Processing is asynchronous — poll the returned file ID to check status. All files must belong to the same Leaf user, share the same operation type, and have processed status.

Request body

{
  "ids": ["fileId1", "fileId2"]
}

Request

curl -X POST \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"ids": ["fileId1", "fileId2"]}' \
  'https://api.withleaf.io/services/operations/api/files/merge'

Response

{
  "id": "uuid",
  "status": "SENT_TO_MERGE"
}

Upload a file

POST /batch Uploads a .zip file containing operation data. Leaf detects the files inside the archive, creates machine file entries, and processes them asynchronously.

Parameters

Parameter	Type	Description
`leafUserId`	string	Required. UUID of the Leaf user
`provider`	string	Required. `Other`, `Leaf`, `ClimateFieldView`, `CNHI`, `JohnDeere`, `Trimble`, `AgLeader`, `RavenSlingshot`, or `Stara`
`fileFormat`	string	Optional. Hints at the file format inside the archive

Maximum upload size is 3 GB.

Set provider to Other if you are unsure of the format. Leaf auto-detects files from supported providers.

Request

curl -X POST \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -F 'file=@data.zip' \
  'https://api.withleaf.io/services/operations/api/batch?leafUserId=UUID&provider=JohnDeere'

Response

{
  "id": "996aea67-52bc-4d4b-9b77-028756dc0ee9",
  "leafUserId": "ede8f781-1d55-4b2d-83a1-6785ddab6e1d",
  "fileName": "data.zip",
  "size": 8652951,
  "provider": "JohnDeere",
  "status": "RECEIVED",
  "uploadTimestamp": "2021-03-12T19:50:55.567755Z"
}

Batch status values

Status	Meaning
`RECEIVED`	Default state after upload
`PROCESSED`	All files in the batch were processed and at least one succeeded
`FAILED`	No files in the batch succeeded. Check `statusDetails` for the reason

Get a batch

GET /batch/{id} Returns a single batch upload by its UUID, including the list of generated machine file IDs.

Parameters

Parameter	Type	Description
`id`	path	UUID of the batch

Request

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

Response

{
  "id": "9b561906-efac-43a3-9378-641e3698da5d",
  "leafUserId": "1481bc9b-cdc7-45c1-9f0e-592da6306dfe",
  "provider": "Other",
  "status": "PROCESSED",
  "leafFiles": [
    "f14203df-4144-43b7-a383-2ed321f395ce",
    "810b1475-cb49-437b-8658-d29038ce2fa4"
  ]
}

Get all batches

GET /batch Returns a paginated list of batch uploads.

Parameters

Parameter	Type	Description
`leafUserId`	string	UUID of a Leaf user
`status`	string	`RECEIVED`, `PROCESSED`, or `FAILED`
`uploadStartTime`	string	ISO 8601 timestamp. Returns batches uploaded on or after this time
`uploadEndTime`	string	ISO 8601 timestamp. Returns batches uploaded on or before this time
`processStartTime`	string	ISO 8601 timestamp. Returns batches processed on or after this time
`processEndTime`	string	ISO 8601 timestamp. Returns batches processed on or before this time
`page`	integer	Page number (default `0`)
`size`	integer	Page size (max `100`)
`sort`	string	Sort order (e.g., `uploadTimestamp,desc`)

Request

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

Response

[
  {
    "id": "9e47ae29-6a84-4a9c-9e5f-01802f6dceea",
    "leafUserId": "5ded9409-c99f-4379-9173-c01b1631f274",
    "provider": "Other",
    "status": "PROCESSED",
    "leafFiles": [
      "74d5aeb6-9a0e-43c6-986c-a5f17eecbddc",
      "475fcad3-b534-409d-8c8b-cec4dabd1b8b"
    ]
  }
]

Retry a batch

PUT /batch/{id}/retry Retries processing for a batch upload. Only reprocesses the files that did not succeed previously — existing converted files are not affected.

Parameters

Parameter	Type	Description
`id`	path	UUID of the batch

Request

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

Response

{
  "id": "36d8551f-409d-41f2-94b4-04c9fe16289b",
  "leafUserId": "089bb77b-2415-43df-a246-6c0a5937c774",
  "fileName": "data.zip",
  "size": 8652951,
  "provider": "Other",
  "status": "RECEIVED",
  "uploadTimestamp": "2021-03-12T19:50:55.567755Z"
}

Get batch files status

GET /batch/{id}/status Returns the processing status of each machine file generated from the batch, grouped by status.

Parameters

Parameter	Type	Description
`id`	path	UUID of the batch
`page`	integer	Page number (default `0`)
`size`	integer	Page size (max `100`)
`sort`	string	Sort order

Request

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

Response

{
  "converted": {
    "leafFiles": [
      "06512392-8d69-4033-8127-4cc62b7176b9",
      "075fd0f6-af1a-433d-ad7a-e3e979179244"
    ]
  },
  "processing": {
    "leafFiles": ["9d22cbca-03ff-47e8-ac66-f6d463d206f4"]
  },
  "failed": {
    "standardGeojson": {
      "leafFiles": ["0abca517-09f2-4d1d-9627-9cd3147e9ec3"],
      "status": "failed",
      "message": "no points passed the filter"
    }
  }
}

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

​Machine files

​Batch upload

​Get all machine files

​Parameters

​Request

​Get a machine file

​Parameters

​Request

​Get file summary

​Parameters

​Request

​Get file standardGeoParquet

​Parameters

​Request

​Get file polygonGeoParquet

​Parameters

​Request

​Get file units

​Parameters

​Request

​Get file status

​Parameters

​Request

​Response

​Common failure messages

​Get file outsideFieldGeoJSON

​Parameters

​Request

​Response

​Get all outsideFieldGeoJSON

​Parameters

​Request

​Response

​Get uncovered files

​Parameters

​Request

​Response

​Merge files

​Request body

​Request

​Response

​Upload a file

​Parameters

​Request

​Response

​Batch status values

​Get a batch

​Parameters

​Request

​Response

​Get all batches

​Parameters

​Request

​Response

​Retry a batch

​Parameters

​Request

​Response

​Get batch files status

​Parameters

​Request

​Response

Base URL

Endpoints

Machine files

Batch upload

Get all machine files

Parameters

Request

Get a machine file

Parameters

Request

Get file summary

Parameters

Request

Get file standardGeoParquet

Parameters

Request

Get file polygonGeoParquet

Parameters

Request

Get file units

Parameters

Request

Get file status

Parameters

Request

Response

Common failure messages

Get file outsideFieldGeoJSON

Parameters

Request

Response

Get all outsideFieldGeoJSON

Parameters

Request

Response

Get uncovered files

Parameters

Request

Response

Merge files

Request body

Request

Response

Upload a file

Parameters

Request

Response

Batch status values

Get a batch

Parameters

Request

Response

Get all batches

Parameters

Request

Response

Retry a batch

Parameters

Request

Response

Get batch files status

Parameters

Request

Response