Skip to main content
Leaf’s manual file upload lets you submit machine data files directly instead of pulling them from a provider API. This is useful for growers who export data to USB thumb drives or for testing with local files. Leaf accepts .zip files containing proprietary formats like .dat, .cn1, ISOXML, .agt, .shp, .2020, .ilf, and more, and converts them into a standard canonical format, accessible as either GeoJSON or GeoParquet.

​
Before you start

  • A Leaf account with a valid API token.
  • A Leaf user created.
  • One or more machine data files packaged as .zip. If you have nested zips, Leaf unzips recursively.
  • cURL, Python 3, or Node.js installed.

​
Step 1: Get your Leaf token

curl -X POST "https://api.withleaf.io/api/authenticate" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your-email@example.com",
    "password": "your-password"
  }'

​
Step 2: Upload the file

POST your .zip file to the batch upload endpoint. If you don’t know the file format, set provider to Other and Leaf detects it automatically. 
curl -X POST "https://api.withleaf.io/services/operations/api/batch" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@/path/to/your-data.zip" \
  -F "leafUserId=YOUR_LEAF_USER_ID" \
  -F "provider=Other"
The response includes a batch_id. If the zip contains multiple files, Leaf discovers and processes each one individually.

​
Step 3: Check batch status

Poll the batch endpoint until the status is PROCESSED: 
curl "https://api.withleaf.io/services/operations/api/batch/BATCH_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"
The leafFiles array contains the IDs of all machine files extracted and processed from your upload.

​
Step 4: Retrieve converted files

Use the file IDs to get the standardized data: Get file metadata: 
curl "https://api.withleaf.io/services/operations/api/files/FILE_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"
Get the file summary (aggregated statistics): 
curl "https://api.withleaf.io/services/operations/api/files/FILE_ID/summary" \
  -H "Authorization: Bearer YOUR_TOKEN"
Get processing status (for troubleshooting): 
curl "https://api.withleaf.io/services/operations/api/files/FILE_ID/status" \
  -H "Authorization: Bearer YOUR_TOKEN"
The status endpoint shows the processing state for each pipeline step: standardGeojson, cleanupGeojson, summary, units, etc.

​
Step 5: Troubleshoot failures

If some files fail, check the batch status for details: 
batch_detail = requests.get(
    f"https://api.withleaf.io/services/operations/api/batch/{batch_id}/status",
    headers=headers
).json()

for file_info in batch_detail:
    if file_info.get("status") == "failed":
        print(f"File {file_info['id']}: {file_info.get('message')}")
Common failure reasons: unsupported file format, corrupted zip, or empty data files.

​
What you built

You uploaded machine data files to Leaf and retrieved standardized output (GeoJSON or GeoParquet — same data, your choice of format). These files go through the same conversion pipeline as provider-synced data, so you can use them interchangeably in your application. Once Leaf has both machine files and field boundaries for a Leaf user, it automatically merges overlapping files into field operations. For a no-code upload experience, use Leaf Link or Magic Link. For the full endpoint reference, see the machine files API reference.
Last modified on March 24, 2026