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 noproducts) to let discovery infer the company's main raw materials.productsโ product names, each resolved to its upstream commodities. Ignored whencommoditiesis 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, orfirst-mile.limitโ max candidate locations to discover (1โ200, default 50).traverseโ settrueto 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
| Field | Type | Required | Description |
|---|---|---|---|
company | string | Yes | Company whose first-mile supply to discover |
commodities | string[] | No | Raw materials to map (free-text; โค 50, no commas) |
products | string[] | No | Product names resolved to upstream commodities; ignored if commodities set |
countries | string[] | No | Countries to scope the sweep; omit for a global grounded sweep |
relationship | string | No | all | operated-by | intermediary | first-mile (default all) |
limit | number | No | 1โ200 candidate locations (default 50) |
company_address | string | No | Address of the company itself, to pin a shared name to one entity |
company_identifier | string | No | Registry id for the company (TRACES id, VAT/EORI, LEI, domain) |
refresh | boolean | No | Recompute instead of serving the cached sweep (default false) |
traverse | boolean | No | Walk the supply graph upstream to the first mile (default false) |
max_sweeps | number | No | 1โ10 paid sweeps for a traversal (default 10); needs traverse |
max_children_per_sweep | number | No | 0โ25 children per parent (default 3, 0 = no cap); needs traverse |
child_limit | number | No | 1โ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)