1 Upload with Metrics

Step 1: Upload with Metrics

Upload a file and include metrics in the same request. The system automatically validates, geocodes, matches locations, and then processes the requested metrics โ€” no separate PUT request needed.

What this step does

It hands Epoch a file and the list of metrics you want computed over it, in a single POST /ingestions/assets. The API mints an ingestion task, ingests the file, geocodes and matches every row to a location, and โ€” because metrics was present at upload โ€” immediately queues those metrics for processing. You get back one thing to hold onto: data.id, the task id that every downstream step polls and filters on.

Why it's needed

This is the entry point of the workflow โ€” nothing exists to poll or query until the task is minted here. The distinctive part is folding the metric request into the upload. In the full ingestion flow, metrics are a separate PUT after a human reviews the staged rows; here, supplying metrics up front tells the system to skip the review pause and carry the task straight through validation into metric processing. Without the metrics field the task would stage and stop, waiting for a decision that never comes โ€” so this field is what makes the flow "quick".

Why you'd choose this

Choose the quick path when you trust the input and don't need a review gate: automated pipelines, known-good data, prototyping, and CI/CD tests where a person isn't going to inspect the staged rows anyway. If you need to see what matched before spending metric-processing time โ€” or want to process only a subset of the staged rows โ€” use the full Facility / Supplier ingestion flow instead, where the metric PUT is a deliberate second step.

Request

POST /ingestions/assets

FieldTypeRequiredDescription
filebinaryYesCSV, Parquet, JSON, GeoJSON, Excel, Shapefile, etc.
location_typestringYesfacility or plot
commodity_typestringYescattle, cocoa, coffee, palm, rubber, soy, timber, shrimp. Aliases palm oil and oil palm are accepted.
metricsstringYesJSON array: ["deforestation"], ["deforestation", "emissions"], etc.
tagsstringNoComma-separated tag names to attach
end_datestringNoEnd date for zonal statistics (YYYY-MM-DD). Defaults to today.

Available Metrics

MetricDescription
deforestationForest loss, non-compliance area, agreement scores
emissionsLUC, non-LUC, removal, SOC, biogenic emissions
biodiversityDiversity scores, canopy height metrics
waterWater stress risk assessment

Frontend Usage

  • Store data.id as the task ID for polling and result retrieval
  • Show upload confirmation with file name and status
  • Begin polling Step 2 immediately โ€” the task will progress through validation and metric processing automatically

Next Step

โ†’ Step 2: Check Status (GET /ingestions/:id/summary)