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:

RouteUse it forAssessmentsReads linkage_type
Upload a file on the EUDR fast pathEUDR, and any flow you will submitRunYou choose the candidates
POST /discovery/source/{taskId}/ingest (the bridge)Quick staging outside EUDRDo not runYes, 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

  1. 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.

  2. 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"
    }
    
  3. PUT the file to the upload_url in the response. See Asset Upload for the required headers.

  4. Poll GET /ingestions/{id}. When deforestation processing completes, fm-api creates the EUDR audit-trail record. The task then carries audit_trail_task_id: poll it at GET /regulations/eudr/audit-trail/tasks/{taskId}.

create_audit_trail requires metrics to include deforestation. The optional fields have these defaults:

FieldWhen omitted
create_audit_trail_pdftrue: the PDF is rendered when the record is created.
audit_trail_operatorThe organization's default operator.
audit_trail_commodityFields fill from the upload's rows where available; complete missing declaration fields with PATCH before submission.
audit_trail_commodity.hs_codeThe 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

  1. POST /discovery/source — dispatch a sweep, get a task id.
  2. GET /discovery/source/{taskId}/status — poll until completed.
  3. GET /discovery/source/{taskId}/results — read the candidates. Each carries an id.
  4. POST /discovery/source/{taskId}/ingest — stage them.
  5. GET /ingestions/{assetTaskId} — poll until overall_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 answers 422 if 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_precision is EXACT: the point is pinned to a street address. This is map-pin precision, not a confidence that the site is there; and
  • confidence_level is high, medium or absent; and
  • linkage_type is deterministic: one of the node's own sources ties it to the company. An inferred or probabilistic node 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 in filters.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.