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
| Field | Type | Required | Description |
|---|---|---|---|
file | binary | Yes | CSV, Parquet, JSON, GeoJSON, Excel, Shapefile, etc. |
location_type | string | Yes | facility or plot |
commodity_type | string | Yes | cattle, cocoa, coffee, palm, rubber, soy, timber, shrimp. Aliases palm oil and oil palm are accepted. |
metrics | string | Yes | JSON array: ["deforestation"], ["deforestation", "emissions"], etc. |
tags | string | No | Comma-separated tag names to attach |
end_date | string | No | End date for zonal statistics (YYYY-MM-DD). Defaults to today. |
โถAvailable Metrics
| Metric | Description |
|---|---|
deforestation | Forest loss, non-compliance area, agreement scores |
emissions | LUC, non-LUC, removal, SOC, biogenic emissions |
biodiversity | Diversity scores, canopy height metrics |
water | Water stress risk assessment |
โถFrontend Usage
- Store
data.idas 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)