01 Upload With Create Artifact

Step 1: Upload with create_artifact

Mint 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 rejects create_artifact without 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-open artifact_dashboard_url once 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

FieldRequiredNotes
location_typeYesplot here; any type works
commodity_typeYese.g. cocoa
metricsYes (here)At least one metric โ€” create_artifact 400s without it
create_artifactYesOpt in to the fast path
signed_url_ttl_secondsNo1โ€“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 + poll block.

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.