01 Create Artifact
โถStep 1: Create the artifact
You choose the scope. POST /artifacts with exactly one filters
entry (condition: "eq") and Epoch queues an asynchronous generation
job. The response's data.id is the artifact id โ every later step
addresses it.
โถWhat this step does
It asks Epoch to assemble a point-in-time export of the data under the
scope you name โ the locations, assets, metrics, facility/shed/plot rows,
and assessment slices โ into a single GeoParquet bundle. Generation runs
in the background; this call only enqueues it and hands you back a
handle (data.id) plus a queued status.
โถWhy it's needed
An artifact is not a live query โ it is a materialised snapshot. This
create call is the moment the snapshot's contents are fixed: the scope
filter resolves to a concrete set of locations now, and the bundle
freezes their current metrics/assessments. That is what makes an artifact
defensible for a regulatory pack or reproducible for a warehouse load โ
re-fetching the same artifact later returns the same bytes (same
sha256), even after the underlying data moves on.
โถWhy you'd choose the on-demand path (vs the fast path)
Reach for on-demand when the export is not "the batch I just uploaded":
- You want an arbitrary slice โ everything under one facility, one supplier, or one location name โ spanning many past uploads.
- You want a scheduled / repeatable export (nightly warehouse pull, quarterly compliance pack) decoupled from any ingestion.
- You want to re-export an existing scope after new imagery / model runs have landed, to capture a fresh snapshot.
If instead you just uploaded data and want a bundle of exactly that upload, the Fast Path does this in one call with no filter to author.
โถChoosing the scope filter
Exactly one filter, always condition: "eq". Pick the attribute that
matches the unit you're exporting:
| Attribute | Scopes to |
|---|---|
facility_id | One facility + its sheds + their plots |
supplier_id | A supplier's locations + everything beneath |
location_id | One facility / shed / plot public id + beneath |
name | Locations whose normalised name matches + beneath |
assets.task_id | One upload (the same scope the fast path uses) |
Multiple filters, filterOverrides, or conditions other than eq are
rejected (400) โ see the scope model.
โถRequest
POST /artifacts with Content-Type: application/json
| Field | Required | Notes |
|---|---|---|
type | No | relational_full (default, the only value today) |
format | No | geoparquet (default, the only value today) |
filters | Yes | Exactly one { attribute, condition: "eq", value }. Here facility_id; also assets.task_id, location_id, supplier_id, name. |
idempotencyKey | No | Or send the Idempotency-Key header (preferred). Same key + same body replays the existing artifact. |
โถResponse (202)
data.idโ captured into{{ad_artifact_id}}.data.attributes.statusโqueued.data.attributes.retryAfterSecondsโ suggested poll interval.
See the Examples tab for the 400 scope_filter_required you get when
no filter (or more than one) is supplied.
โถWhy send an idempotency key
Create is not naturally idempotent โ without a key, a retried request
(dropped connection, client retry loop) would queue a second
duplicate artifact and duplicate the generation cost. Send an
Idempotency-Key header (preferred) or idempotencyKey body field and a
replay with the same key + same body returns the existing artifact
(idempotent: true) instead of creating another. Use it whenever the
create runs on an automated / retryable path.
โถNext Step
โ Step 2: Poll Artifact Until Completed. The job is asynchronous, so you cannot download yet โ you must wait for it to finish generating.