1 Discover Source Locations

Step 1: Discover Source Locations

Kick off a first-mile discovery run for a company. Only company is required โ€” everything else scopes and shapes the sweep. The response is a 202 carrying a discovery task id (captured into {{source_task_id}}) plus the links to poll and fetch results.

What this step does

It hands Epoch a company name and asks it to map that company's first mile: the upstream mills, ports, collection centres, and sourcing regions it likely buys from. Behind the endpoint is a grounded LLM + geocoding + imagery pipeline that reads public evidence, so it is long-running โ€” the API dispatches the job and returns immediately with 202 and a task id rather than holding the request open. Nothing is discovered synchronously; the id this call mints is what Steps 2 and 3 poll and read from.

Why it's needed

This is the entry point of Path A โ€” discovering a company's first mile when all you have is its name. The rest of Path A (poll, results) and the ingest hand-off all address the task id this call mints. It also fixes the search scope: the company, commodities, and countries you send here define the fan-out. (If you already know a specific supplier by name, you don't need this at all โ€” use Path B, POST /discovery/validate, instead.)

Choosing your scope

  • company (required) โ€” the company whose first mile to discover.
  • commodities โ€” raw materials to map (free-text, e.g. timber, rubber โ€” not restricted to the canonical EUDR set). Omit (with no products) to let discovery infer the company's main raw materials.
  • products โ€” product names, each resolved to its upstream commodities. Ignored when commodities is supplied.
  • countries โ€” scope the search (e.g. Indonesia). Omit for a global sweep, where discovery grounds the company's sourcing countries and fans out per country.
  • relationship โ€” supply-ward filter: all (default), operated-by, intermediary, or first-mile.
  • limit โ€” max candidate locations to discover (1โ€“200, default 50).
  • traverse โ€” set true to walk the supply graph upstream to the first mile in one task, instead of one tier. It runs for hours, the organization must be enabled for it, and each sweep counts against the org's daily traversal limit. max_sweeps (1โ€“10, default 10) caps the paid sweeps. See Discover Source Locations for the knobs.

Trace allowance

Each accepted call is one Trace, whatever its depth. An organization gets 10 Traces, and 30 once it has paid for a checkout. Read the Traces left on GET /rate-limits/allowances. With none left this step returns 402 USAGE_LIMIT_REACHED, unless a repeat finds an existing cached result.

Request

POST /discovery/source with Content-Type: application/json

FieldTypeRequiredDescription
companystringYesCompany whose first-mile supply to discover
commoditiesstring[]NoRaw materials to map (free-text; โ‰ค 50, no commas)
productsstring[]NoProduct names resolved to upstream commodities; ignored if commodities set
countriesstring[]NoCountries to scope the sweep; omit for a global grounded sweep
relationshipstringNoall | operated-by | intermediary | first-mile (default all)
limitnumberNo1โ€“200 candidate locations (default 50)
company_addressstringNoAddress of the company itself, to pin a shared name to one entity
company_identifierstringNoRegistry id for the company (TRACES id, VAT/EORI, LEI, domain)
refreshbooleanNoRecompute instead of serving the cached sweep (default false)
traversebooleanNoWalk the supply graph upstream to the first mile (default false)
max_sweepsnumberNo1โ€“10 paid sweeps for a traversal (default 10); needs traverse
max_children_per_sweepnumberNo0โ€“25 children per parent (default 3, 0 = no cap); needs traverse
child_limitnumberNo1โ€“200 candidates per child sweep (default 25); needs traverse

Response (202)

See the Examples tab. Key fields:

  • data.id โ€” your discovery task id, captured into {{source_task_id}}.
  • data.attributes.status โ€” lifecycle status at dispatch (e.g. processing).
  • links.status / links.results โ€” where to poll and then read.

Visualization

Renders a dispatch panel (task id, company, accepted status) so you can see the run was queued at a glance rather than reading the raw 202 envelope.

Next Step

โ†’ Step 2: Poll Source Status (GET /discovery/source/:id/status)