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:

AttributeScopes to
facility_idOne facility + its sheds + their plots
supplier_idA supplier's locations + everything beneath
location_idOne facility / shed / plot public id + beneath
nameLocations whose normalised name matches + beneath
assets.task_idOne 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

FieldRequiredNotes
typeNorelational_full (default, the only value today)
formatNogeoparquet (default, the only value today)
filtersYesExactly one { attribute, condition: "eq", value }. Here facility_id; also assets.task_id, location_id, supplier_id, name.
idempotencyKeyNoOr 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.