01 Upload With Create Artifact
โถStep 1: Upload with create_artifact
create_artifactMint a signed upload URL and ship the bytes. The two new flags are
create_artifact: true (auto-generate a bundle of this upload) and
the optional signed_url_ttl_seconds (surface a ready-to-open
dashboard link on the task read once the artifact succeeds).
โถWhat this step does
It is an ordinary asset upload โ the same call you'd make without any artifact intent โ plus a flag that registers a standing instruction: "when this upload finishes processing, generate an artifact of exactly what I uploaded." The upload itself behaves identically; the artifact is strictly additive.
โถWhy it's needed / why this path exists
The on-demand path takes three explicit calls (create โ poll โ mint) and
requires you to author a scope filter that names the upload. The fast path
folds the create into the upload you were already making: no second
call, and no filter to write, because the scope is unambiguous โ it's this
upload (assets.task_id). Choose it when the natural unit of export is
"the batch I just sent" and you don't want to orchestrate a separate
create step.
โถWhy the flags
create_artifact: trueโ opt in. Without it, uploading and exporting are two separate journeys.metrics(โฅ 1, required here) โ the artifact carries metric/assessment slices; with no metric the bundle would be empty, so the API rejectscreate_artifactwithout one (400). Include the metrics you actually want in the export.signed_url_ttl_seconds(optional) โ a convenience: when set, the task read in Step 2 hands back a ready-to-openartifact_dashboard_urlonce the artifact succeeds, so a human can open the result without you making the explicit mint call in Step 4. Omit it if you only need programmatic downloads.
โถRequest
POST /ingestions/assets with Content-Type: application/json
| Field | Required | Notes |
|---|---|---|
location_type | Yes | plot here; any type works |
commodity_type | Yes | e.g. cocoa |
metrics | Yes (here) | At least one metric โ create_artifact 400s without it |
create_artifact | Yes | Opt in to the fast path |
signed_url_ttl_seconds | No | 1โ86400; only valid with create_artifact: true. Surfaces artifact_dashboard_url on the task read. |
โถResponse (201)
data.idโ captured into{{af_task_id}}.meta.client_actions[0]โ the upload descriptor +pollblock.
See the Examples tab for the 400 you get when create_artifact is
set without a metric.
โถNext Step
โ Step 2: Wait For Upload And Capture Artifact.