Ingestion

An asset is a single record from an uploaded file — typically one row of a CSV or one feature of a GeoJSON. Uploading a file with 5,000 rows creates one ingestion task containing 5,000 assets.

Each asset carries:

• Its original source data (asset_data) — the raw fields as they appeared in your file, preserved verbatim.
• A processing status — pending, processing, completed, failed, etc. (see Statuses).
• A link to a location — once processed, the asset is geocoded, normalised, and matched to a location entity (a facility, plot, or shed). This is where the asset's raw row becomes a real, queryable location.

In short: a task is the unit of upload, and an asset is the unit of data within it. You inspect tasks to track the lifecycle of an upload, and assets to see what happened to each individual record — including which ones matched a location and which failed validation.

An asset row is an uploaded record, not a location. Re-uploading a supplier list does not edit the earlier records — it adds new ones. So a facility that has appeared in six monthly files has six records, and listing assets returns it six times.

That is right for an audit trail and wrong for a supplier count, so the two questions are answered by two endpoints:

Question	Endpoint	One row per
What did each upload contain, including records a later upload replaced?	List All Ingestion Assets	record
What is the current state of each location?	List Latest Ingestion Assets	location

Neither meta.total is a filtered version of the other: one counts records, the other counts locations. Every deduped row also names what it replaced, and Get Record History returns one location's full lineage with the current record flagged.

Which record counts as current is not simply the newest upload — it follows the same precedence the DDS plot pin uses, so the deduped read, the filing and the roll-up all name the same record. See Record Supersession for the ordering, the audit routes, and the two limitations it does not fix.

• Bulk data import — upload thousands of supply chain locations in a single file rather than creating them individually
• Ongoing data refresh — periodically re-upload updated location files to keep your supply chain map current
• Multi-format support — ingest data from various file formats without manual conversion
• Automated pipeline — combine with webhooks to trigger downstream processing when ingestion completes

1. Upload — submit a file via multipart form upload, which creates an ingestion task
2. Validation — the system validates file structure, column mappings, and data types
3. Processing — rows are geocoded, normalised, and matched to location entities
4. Review — inspect task status, asset-level results, and any validation errors

Group	Description
Assets	Inspect individual files and their processing results
Tasks	Track ingestion task lifecycle and status

Required scope: ingestion:write for uploading, ingestion:read for viewing tasks and assets