Ingestion workflows
Runnable, end-to-end recipes for getting supply-chain locations into
Epoch through /ingestions/assets — uploading a file, validating and
staging it, running metrics, and reading the results back as a table and
a map. Where the Ingestion endpoints
document each call in isolation, these workflows show the full
upload → stage → process → visualise sequence with the polling and
variable capture already wired.
▶The ingestion shape
Every workflow here is a variation on the same lifecycle:
POST /ingestions/assets → upload the file (returns a task id)
GET /ingestions/:id → poll until `staged` (validation done)
PUT /ingestions/assets → run metrics / assessments on the task
GET /ingestions/:id → poll until `completed`
GET /ingestions/assets/:id, /locations/*, /metrics/* → read results
The difference between workflows is what you upload (plots, facilities, sheds) and when metrics run (a separate review step, or folded into the upload).
The lifecycle is split into discrete calls on purpose: uploading, validating, and processing are asynchronous and can each take minutes, so the API hands you a task id and lets you poll rather than blocking a single long request. Splitting stage from process also gives you a natural review point — you can inspect validation confidence and correct data before committing to the (more expensive) metric runs. The Quick Ingestion variant collapses this into one call for data you already trust.
▶Which workflow to use
| Workflow | Upload type | Metrics run | Use it when |
|---|---|---|---|
| Plot Ingestion | Plots | After staging (opt-in) | You ship plot geometry first and decide on assessments/metrics after reviewing the staged plots |
| Facility / Supplier Ingestion | Facilities (with supplier fields) | Separate review step | Onboarding suppliers/facilities — review validation + confidence before committing to metrics |
| Quick Ingestion | Any | Folded into the upload | Known-good data / automated pipelines — one call uploads and processes |
| Shed Ingestion | Supply sheds (sourcing areas) | Separate step | Mapping broad sourcing regions and computing shed-level risk |
▶Prerequisites
- A valid API key in the
x-api-keyheader withingestions:write(and:readfor polling and reading results). - A location file in a supported format (CSV, GeoJSON, Parquet, GeoPackage, Shapefile, Excel).