Discovery ā Ingestion
ā¶Discovery ā ingestion
Discovery finds candidate facilities. Ingestion stages them as locations you can assess. There are two ways to move candidates into ingestion:
| Route | Use it for | Assessments | Reads linkage_type |
|---|---|---|---|
| Upload a file on the EUDR fast path | EUDR, and any flow you will submit | Run | You choose the candidates |
POST /discovery/source/{taskId}/ingest (the bridge) | Quick staging outside EUDR | Do not run | Yes, with lineage and pin checks |
For assessed EUDR work, use the upload fast path. The bridge stages candidates but skips the validation call that produces ingestion assessments, and does not accept the audit-trail fast-path options. Exploratory screening can explicitly accept weaker links; keep those uncertainties visible when reviewing the resulting audit trail.
ā¶Choose the candidates
Discovery does not supply verified plot boundaries. A candidate can have null
geometry or an approximate pin. Review a validate result's tier and comment.
For source candidates, use the server's ingestable, ingest_block_reason
and to_ingest fields alongside linkage, lineage, pin status and imagery.
Confidence alone does not establish a usable supplier site. Wait for the
finished result before ingesting candidates.
Get plots from the supplier. Never upload a discovered point as a plot.
ā¶The EUDR fast path
-
Put every facility you keep into one CSV or GeoJSON file. One row (or one GeoJSON Point feature) is one facility, with its name and coordinates.
-
Request an upload URL:
POST /ingestions/assets Content-Type: application/json { "location_type": "facility", "commodity_type": "palm", "metrics": ["deforestation"], "create_audit_trail": true, "filename": "kept-facilities.csv" } -
PUTthe file to theupload_urlin the response. See Asset Upload for the required headers. -
Poll
GET /ingestions/{id}. When deforestation processing completes, fm-api creates the EUDR audit-trail record. The task then carriesaudit_trail_task_id: poll it atGET /regulations/eudr/audit-trail/tasks/{taskId}.
create_audit_trail requires metrics to include deforestation. The
optional fields have these defaults:
| Field | When omitted |
|---|---|
create_audit_trail_pdf | true: the PDF is rendered when the record is created. |
audit_trail_operator | The organization's default operator. |
audit_trail_commodity | Fields fill from the upload's rows where available; complete missing declaration fields with PATCH before submission. |
audit_trail_commodity.hs_code | The code on the upload's rows, then the upload's top-level hs_code; otherwise blank, which blocks submission. |
Upload the supplier's plots in the same way, with location_type: "plot".
See EUDR Audit Trail for the record itself.
Creating an audit trail does not file a DDS. Complete the record and follow the authorization and submission steps in the audit-trail guide.
ā¶The ingest bridge
The bridge stages selected candidates without rebuilding a file. It applies the linkage, lineage, pin and sourcing-site gate described below, but does not run ingestion assessments. Use it for staging, then reprocess if needed.
ā¶The shape of the flow
POST /discovery/sourceā dispatch a sweep, get a task id.GET /discovery/source/{taskId}/statusā poll untilcompleted.GET /discovery/source/{taskId}/resultsā read the candidates. Each carries anid.POST /discovery/source/{taskId}/ingestā stage them.GET /ingestions/{assetTaskId}ā poll untiloverall_status: staged.
Step 4 returns an ordinary asset_task, the same resource an upload returns, so
nothing downstream needs to know the locations came from discovery.
ā¶Why not build a file
Before this endpoint, staging discovery output meant reading the results,
packing them into a CSV or GeoJSON in the client, and posting that to
POST /ingestions/assets. That worked, and cost three things:
- Provenance. A candidate carries around twenty attributes ā grounding citations, corroboration counts, evidence summaries, confidence reasoning. A CSV has four columns. Everything else was destroyed in transit.
- A round-trip. The client fetched data the server already had, reformatted it, and sent it back.
- Reachability. An agent calling the API could not do it at all without synthesising a file by hand.
The bridge removes all three. It also means the coordinates are never sent back for geocoding, so a staged location sits exactly where discovery found it.
ā¶Naming candidates, or taking everything
candidate_ids is optional, and the two forms answer different questions.
Omit it to stage every candidate the filters admit. This is the usual choice for an agent, or for a "screen everything credible" flow. It removes the fetch-results-then-echo-ids round-trip entirely.
{ "location_type": "facility", "commodity_type": "palm" }
Send ids when a person has chosen specific candidates ā a review screen, or a curated subset.
{ "location_type": "facility", "candidate_ids": ["6c1eā¦", "8f2aā¦"] }
An empty array is rejected with 400. Selecting nothing and selecting
everything must not be spelled the same way, or a client bug that produces an
empty list would silently stage the whole sweep.
ā¶Rejected vs filtered
The distinction matters when reading the response.
- A candidate you named that the gate excludes appears in
meta.rejections, and the call answers422if nothing survives. You made a claim about that candidate, so the response says why it failed. - Under the ingest-all form, an excluded candidate appears in
meta.filtered. No claim was made about it, so its exclusion is information rather than an error.
ā¶What the default gate admits
A candidate is staged when it has a point geometry with coordinates, and:
location_precisionisEXACT: the point is pinned to a street address. This is map-pin precision, not a confidence that the site is there; andconfidence_levelishigh,mediumor absent; andlinkage_typeisdeterministic: one of the node's own sources ties it to the company. Aninferredorprobabilisticnode is a lead, not a confirmed supplier site, so it stays in the results but is not staged. To stage one anyway, list its type infilters.linkage.
A LOCALITY point is a town centroid, so the satellite check at it looks at a
town rather than a site. It is excluded as not_ingestable with the detail
"approximate location (town only): needs a street address", whatever its
confidence. Ask the supplier for the street address, or run
POST /discovery/validate on the name, then ingest the result. To stage town
points anyway, list LOCALITY in filters.location_precision.
Region-level candidates (DISTRICT, REGION, BASIN) are polygons describing
a sourcing area rather than a located facility, so they are not staged.
The gate is not a quality judgement. It decides what is safe to stage, not
whether a location is correct. A candidate that passes may still be wrong; rank
on stable_core, corroboration_count, documented and the evidence fields
before treating any of it as verified.
ā¶Narrowing it
filters narrows the gate:
{
"location_type": "facility",
"filters": { "country": ["MY"], "min_confidence": "high" }
}
min_confidence: "low" and a wider linkage list deliberately widen it,
admitting candidates the default excludes. What no filter can do is admit a
candidate without a point geometry and coordinates ā synthesis would have
nothing to stage.
meta.filters_applied echoes what was used, defaults included, so a response
explains its own candidate count.
ā¶Provenance of a staged discovery row
A discovered location is recorded as not geocoded, and carries no
location_source. That field's vocabulary is customer / geocoded /
re_anchored, and a discovered point is none of them: the operator did not
supply it, no geocoder resolved it on this upload, and it was not re-anchored.
Leaving it unset is deliberate ā labelling it customer would assert something
false about where the point came from.
ā¶Ingesting the same candidates twice
Each call stages a new task. The duplicate-upload check that rejects an identical customer file does not apply here: the collection is server-produced and a second selection of the same candidates is a deliberate action, not an accidental re-upload. Cross-task deduplication still applies at the location level, so an identical point resolves to the same staged location rather than a second copy.
ā¶Assessments do not run on this path
The endpoint accepts assessments for parity with POST /ingestions/assets,
but the field is inert here. The bridge skips validate_locations, which is
the only producer of assessment results, so no assessment runs and none is
billed.
To assess the staged rows, reprocess them with PUT /ingestions/assets
filtered to the task this endpoint returns.
ā¶Results can expire
Most discovery tasks store their results indefinitely. A task served from the response cache is the exception: it has no stored blob of its own, and its cache entry expires.
When that happens, the service first looks for another task that answered the same query and holds a blob, and serves that. Only when no such task exists does the call fail:
404 DISCOVERY_RESULTS_EXPIRED
"discovery results expired; re-submit the query to recompute"
This is distinct from 404 NOT_FOUND, which means the task never existed or
belongs to another organization. The expiry case is recoverable: re-run
discovery and ingest from the new task. The candidates are recomputed, not lost.
A related case is 409 DISCOVERY_IDS_UNAVAILABLE, for a task whose results
predate candidate ids. No candidate can be named, so re-running discovery is
again the remedy. The endpoint never falls back to selecting by position ā an
id that resolved to a different candidate than the caller chose would be worse
than an error.
ā¶Required scope
ingestions:write. This endpoint creates locations, so neither geocode:read
nor discovery:write is sufficient.