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
GET	`/batch/{id}/manifest`	Get batch upload manifest

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'

import requests

TOKEN = 'YOUR_TOKEN'
endpoint = 'https://api.withleaf.io/services/operations/api/files'
headers = {'Authorization': f'Bearer {TOKEN}'}

response = requests.get(endpoint, headers=headers, params={'leafUserId': 'UUID'})
print(response.json())

const axios = require('axios')
const TOKEN = 'YOUR_TOKEN'

const endpoint = 'https://api.withleaf.io/services/operations/api/files'
const headers = { 'Authorization': `Bearer ${TOKEN}` }

axios.get(endpoint, { headers, params: { leafUserId: 'UUID' } })
  .then(res => console.log(res.data))
  .catch(console.error)

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}'

import requests

TOKEN = 'YOUR_TOKEN'
endpoint = 'https://api.withleaf.io/services/operations/api/files/{id}'
headers = {'Authorization': f'Bearer {TOKEN}'}

response = requests.get(endpoint, headers=headers)
print(response.json())

const axios = require('axios')
const TOKEN = 'YOUR_TOKEN'

const endpoint = 'https://api.withleaf.io/services/operations/api/files/{id}'
const headers = { 'Authorization': `Bearer ${TOKEN}` }

axios.get(endpoint, { headers })
  .then(res => console.log(res.data))
  .catch(console.error)

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'

import requests

TOKEN = 'YOUR_TOKEN'
endpoint = 'https://api.withleaf.io/services/operations/api/files/{id}/summary'
headers = {'Authorization': f'Bearer {TOKEN}'}

response = requests.get(endpoint, headers=headers)
print(response.json())

const axios = require('axios')
const TOKEN = 'YOUR_TOKEN'

const endpoint = 'https://api.withleaf.io/services/operations/api/files/{id}/summary'
const headers = { 'Authorization': `Bearer ${TOKEN}` }

axios.get(endpoint, { headers })
  .then(res => console.log(res.data))
  .catch(console.error)

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'

import requests

TOKEN = 'YOUR_TOKEN'
endpoint = 'https://api.withleaf.io/services/operations/api/files/{id}/standardGeoparquet'
headers = {'Authorization': f'Bearer {TOKEN}'}

response = requests.get(endpoint, headers=headers)
print(response.json())

const axios = require('axios')
const TOKEN = 'YOUR_TOKEN'

const endpoint = 'https://api.withleaf.io/services/operations/api/files/{id}/standardGeoparquet'
const headers = { 'Authorization': `Bearer ${TOKEN}` }

axios.get(endpoint, { headers })
  .then(res => console.log(res.data))
  .catch(console.error)

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'

import requests

TOKEN = 'YOUR_TOKEN'
endpoint = 'https://api.withleaf.io/services/operations/api/files/{id}/polygonGeoparquet'
headers = {'Authorization': f'Bearer {TOKEN}'}

response = requests.get(endpoint, headers=headers)
print(response.json())

const axios = require('axios')
const TOKEN = 'YOUR_TOKEN'

const endpoint = 'https://api.withleaf.io/services/operations/api/files/{id}/polygonGeoparquet'
const headers = { 'Authorization': `Bearer ${TOKEN}` }

axios.get(endpoint, { headers })
  .then(res => console.log(res.data))
  .catch(console.error)

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'

import requests

TOKEN = 'YOUR_TOKEN'
endpoint = 'https://api.withleaf.io/services/operations/api/files/{id}/units'
headers = {'Authorization': f'Bearer {TOKEN}'}

response = requests.get(endpoint, headers=headers)
print(response.json())

const axios = require('axios')
const TOKEN = 'YOUR_TOKEN'

const endpoint = 'https://api.withleaf.io/services/operations/api/files/{id}/units'
const headers = { 'Authorization': `Bearer ${TOKEN}` }

axios.get(endpoint, { headers })
  .then(res => console.log(res.data))
  .catch(console.error)

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'

import requests

TOKEN = 'YOUR_TOKEN'
endpoint = 'https://api.withleaf.io/services/operations/api/files/{id}/status'
headers = {'Authorization': f'Bearer {TOKEN}'}

response = requests.get(endpoint, headers=headers)
print(response.json())

const axios = require('axios')
const TOKEN = 'YOUR_TOKEN'

const endpoint = 'https://api.withleaf.io/services/operations/api/files/{id}/status'
const headers = { 'Authorization': `Bearer ${TOKEN}` }

axios.get(endpoint, { headers })
  .then(res => console.log(res.data))
  .catch(console.error)

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'

import requests

TOKEN = 'YOUR_TOKEN'
endpoint = 'https://api.withleaf.io/services/operations/api/files/{id}/outsideFieldGeojson'
headers = {'Authorization': f'Bearer {TOKEN}'}

response = requests.get(endpoint, headers=headers)
print(response.json())

const axios = require('axios')
const TOKEN = 'YOUR_TOKEN'

const endpoint = 'https://api.withleaf.io/services/operations/api/files/{id}/outsideFieldGeojson'
const headers = { 'Authorization': `Bearer ${TOKEN}` }

axios.get(endpoint, { headers })
  .then(res => console.log(res.data))
  .catch(console.error)

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'

import requests

TOKEN = 'YOUR_TOKEN'
endpoint = 'https://api.withleaf.io/services/operations/api/files/outsideFieldGeojson'
headers = {'Authorization': f'Bearer {TOKEN}'}

response = requests.get(endpoint, headers=headers, params={'leafUserId': 'UUID'})
print(response.json())

const axios = require('axios')
const TOKEN = 'YOUR_TOKEN'

const endpoint = 'https://api.withleaf.io/services/operations/api/files/outsideFieldGeojson'
const headers = { 'Authorization': `Bearer ${TOKEN}` }

axios.get(endpoint, { headers, params: { leafUserId: 'UUID' } })
  .then(res => console.log(res.data))
  .catch(console.error)

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'

import requests

TOKEN = 'YOUR_TOKEN'
endpoint = 'https://api.withleaf.io/services/operations/api/files/uncoveredFiles'
headers = {'Authorization': f'Bearer {TOKEN}'}

response = requests.get(endpoint, headers=headers, params={'leafUserId': 'UUID'})
print(response.json())

const axios = require('axios')
const TOKEN = 'YOUR_TOKEN'

const endpoint = 'https://api.withleaf.io/services/operations/api/files/uncoveredFiles'
const headers = { 'Authorization': `Bearer ${TOKEN}` }

axios.get(endpoint, { headers, params: { leafUserId: 'UUID' } })
  .then(res => console.log(res.data))
  .catch(console.error)

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'

import requests

TOKEN = 'YOUR_TOKEN'
endpoint = 'https://api.withleaf.io/services/operations/api/files/merge'
headers = {'Authorization': f'Bearer {TOKEN}'}

response = requests.post(endpoint, headers=headers, json={'ids': ['fileId1', 'fileId2']})
print(response.json())

const axios = require('axios')
const TOKEN = 'YOUR_TOKEN'

const endpoint = 'https://api.withleaf.io/services/operations/api/files/merge'
const headers = { 'Authorization': `Bearer ${TOKEN}` }

axios.post(endpoint, { ids: ['fileId1', 'fileId2'] }, { headers })
  .then(res => console.log(res.data))
  .catch(console.error)

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'

import requests

TOKEN = 'YOUR_TOKEN'
endpoint = 'https://api.withleaf.io/services/operations/api/batch'
headers = {'Authorization': f'Bearer {TOKEN}'}

files = {'file': open('data.zip', 'rb')}
params = {'leafUserId': 'UUID', 'provider': 'JohnDeere'}

response = requests.post(endpoint, headers=headers, files=files, params=params)
print(response.json())

const axios = require('axios')
const FormData = require('form-data')
const fs = require('fs')
const TOKEN = 'YOUR_TOKEN'

const endpoint = 'https://api.withleaf.io/services/operations/api/batch'
const headers = { 'Authorization': `Bearer ${TOKEN}` }
const params = { leafUserId: 'UUID', provider: 'JohnDeere' }

const form = new FormData()
form.append('file', fs.createReadStream('data.zip'))

axios.post(endpoint, form, { headers: { ...headers, ...form.getHeaders() }, params })
  .then(res => console.log(res.data))
  .catch(console.error)

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}'

import requests

TOKEN = 'YOUR_TOKEN'
endpoint = 'https://api.withleaf.io/services/operations/api/batch/{id}'
headers = {'Authorization': f'Bearer {TOKEN}'}

response = requests.get(endpoint, headers=headers)
print(response.json())

const axios = require('axios')
const TOKEN = 'YOUR_TOKEN'

const endpoint = 'https://api.withleaf.io/services/operations/api/batch/{id}'
const headers = { 'Authorization': `Bearer ${TOKEN}` }

axios.get(endpoint, { headers })
  .then(res => console.log(res.data))
  .catch(console.error)

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'

import requests

TOKEN = 'YOUR_TOKEN'
endpoint = 'https://api.withleaf.io/services/operations/api/batch'
headers = {'Authorization': f'Bearer {TOKEN}'}

response = requests.get(endpoint, headers=headers)
print(response.json())

const axios = require('axios')
const TOKEN = 'YOUR_TOKEN'

const endpoint = 'https://api.withleaf.io/services/operations/api/batch'
const headers = { 'Authorization': `Bearer ${TOKEN}` }

axios.get(endpoint, { headers })
  .then(res => console.log(res.data))
  .catch(console.error)

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'

import requests

TOKEN = 'YOUR_TOKEN'
endpoint = 'https://api.withleaf.io/services/operations/api/batch/{id}/retry'
headers = {'Authorization': f'Bearer {TOKEN}'}

response = requests.put(endpoint, headers=headers)
print(response.json())

const axios = require('axios')
const TOKEN = 'YOUR_TOKEN'

const endpoint = 'https://api.withleaf.io/services/operations/api/batch/{id}/retry'
const headers = { 'Authorization': `Bearer ${TOKEN}` }

axios.put(endpoint, {}, { headers })
  .then(res => console.log(res.data))
  .catch(console.error)

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'

import requests

TOKEN = 'YOUR_TOKEN'
endpoint = 'https://api.withleaf.io/services/operations/api/batch/{id}/status'
headers = {'Authorization': f'Bearer {TOKEN}'}

response = requests.get(endpoint, headers=headers)
print(response.json())

const axios = require('axios')
const TOKEN = 'YOUR_TOKEN'

const endpoint = 'https://api.withleaf.io/services/operations/api/batch/{id}/status'
const headers = { 'Authorization': `Bearer ${TOKEN}` }

axios.get(endpoint, { headers })
  .then(res => console.log(res.data))
  .catch(console.error)

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"
    }
  }
}

Get batch upload manifest

GET /batch/{id}/manifest Returns one row for each file in the uploaded archive, including files inside nested archives. Each row says what Leaf did with the file. /batch/{id}/status lists the machine files a batch produced. This endpoint lists the files you sent, so you can tell an end user which files Leaf used, which it skipped, and why. path and ordinal together identify a row, so two files with the same name in one upload get separate rows.

Leaf writes the manifest when it decompresses the batch. Batches uploaded before this endpoint shipped have no manifest. See Response states.

Parameters

Parameter	Type	Description
`id`	path	UUID of the batch
`disposition`	string	Return only rows with this disposition, for example `ignored`. Case-insensitive
`page`	integer	Page number (default `0`)
`size`	integer	Page size (default `20`)
`sort`	string	Sort field and direction, for example `ordinal,asc`. Valid fields: `path`, `ordinal`, `disposition`, `reason`

The response has an X-Total-Count header. Page with page and size. Without sort, the page order is not guaranteed, so set sort=ordinal,asc to keep archive order across pages.

Request

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

import requests

TOKEN = 'YOUR_TOKEN'
endpoint = 'https://api.withleaf.io/services/operations/api/batch/{id}/manifest'
headers = {'Authorization': f'Bearer {TOKEN}'}

response = requests.get(endpoint, headers=headers)
print(response.json())

const axios = require('axios')
const TOKEN = 'YOUR_TOKEN'

const endpoint = 'https://api.withleaf.io/services/operations/api/batch/{id}/manifest'
const headers = { 'Authorization': `Bearer ${TOKEN}` }

axios.get(endpoint, { headers })
  .then(res => console.log(res.data))
  .catch(console.error)

Response

[
  {
    "path": "southfield/corn.shp",
    "ordinal": 0,
    "disposition": "consumed",
    "reason": null,
    "links": [
      {
        "entryId": "00000000-0000-4000-8000-000000000001",
        "entryStatus": "FINISHED",
        "leafFileIds": ["00000000-0000-4000-8000-000000000002"],
        "originalFileName": "southfield/corn"
      }
    ]
  },
  {
    "path": "northfield/soybeans.shp",
    "ordinal": 4,
    "disposition": "ignored",
    "reason": "incomplete shapefile set, missing .dbf",
    "links": []
  },
  {
    "path": "__MACOSX/._corn.shp",
    "ordinal": 6,
    "disposition": "skipped_system",
    "reason": null,
    "links": []
  }
]

Response fields

Field	Type	Description
`path`	string	Full path of the file in the archive. For a file in a nested archive, the path starts with the nested archive’s path
`ordinal`	integer	Position of the file in the archive. `path` plus `ordinal` is unique in a batch
`disposition`	string	What Leaf did with the file. See Disposition values
`reason`	string	Why Leaf did not use the file, when Leaf knows. Otherwise `null`
`links`	array	For a `consumed` file, the batch entry (fileset) that holds the file. Empty for every other disposition
`links[].entryId`	string	UUID of the batch entry
`links[].entryStatus`	string	Current status of the entry: `PENDING`, `PROCESSING`, `FINISHED`, or `FAILED`
`links[].leafFileIds`	array	IDs of the machine files Leaf generated from the entry. Empty until conversion creates them
`links[].originalFileName`	string	Name of the fileset, built from the names of the uploaded files in it

One file can have more than one link when two formats claim it. For example, Leaf can put one taskdata.xml in both an ISOXML fileset and an FMIS fileset. Leaf reads links[].entryStatus and links[].leafFileIds at request time. They show the current state, including after a retry or reprocess.

Disposition values

Disposition	Meaning
`consumed`	A format detector claimed the file and added it to a batch entry. `links` shows the entry
`ignored`	No format detector used this file. If `reason` is set, it names a missing `.dbf` or `.shx` file. A `null` reason does not mean the format is unsupported
`skipped_system`	An operating-system file or a directory entry, such as `__MACOSX`, `.DS_Store`, or `Thumbs.db`. These are never data files
`expanded`	A nested archive that Leaf opened. Its files have their own rows, and their paths start with this path
`failed_extraction`	A nested archive that Leaf could not open. Leaf did not read the files in it

To list the files Leaf did not use, request ?disposition=ignored. Show those rows and their reason to the end user.

Response states

Leaf writes the manifest once, when decompression finishes. The endpoint returns one of these four responses:

Status	Body	Meaning
`200`	Paginated rows	The manifest exists. An empty page is a valid response. The batch can still be `RECEIVED` while its machine files convert. Read `links[].entryStatus` and `links[].leafFileIds` to track conversion
`202`	`{"status": "PENDING"}`	Leaf is still decompressing the batch. Poll again
`404`	`{"status": "NO_MANIFEST"}`	The batch finished without a manifest. It was uploaded before this endpoint shipped, or decompression failed before Leaf wrote the manifest. Stop polling
`404`	empty	Your API owner has no batch with that ID

Use the response body to tell the two 404 responses apart. NO_MANIFEST is final. That batch will never have a manifest, so do not retry.

Example: a batch where nothing converted

This batch contains only a shapefile without its .dbf. The batch fails with no machine files, and the manifest shows why:

[
  {
    "path": "harvest_soy_2026.shp",
    "ordinal": 0,
    "disposition": "ignored",
    "reason": "incomplete shapefile set, missing .dbf",
    "links": []
  },
  {
    "path": "harvest_soy_2026.shx",
    "ordinal": 1,
    "disposition": "ignored",
    "reason": "incomplete shapefile set, missing .dbf",
    "links": []
  },
  {
    "path": "harvest_soy_2026.prj",
    "ordinal": 2,
    "disposition": "ignored",
    "reason": "incomplete shapefile set, missing .dbf",
    "links": []
  }
]

The batch status is FAILED. The manifest tells you what to fix: add the .dbf file to the upload.

​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

​Get batch upload manifest

​Parameters

​Request

​Response

​Response fields

​Disposition values

​Response states

​Example: a batch where nothing converted

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

Get batch upload manifest

Parameters

Request

Response

Response fields

Disposition values

Response states

Example: a batch where nothing converted