03 Mint Signed URLs

Step 3: Mint signed URLs

A completed artifact stores files, not URLs. Call POST /artifacts/{{ad_artifact_id}}/signed-urls to mint short-lived download links. Signing is all-or-nothing โ€” every file in storage_objects is signed in one batch sharing a single expires_at.

What this step does

It exchanges the artifact id for time-limited download URLs โ€” one per file in the bundle โ€” plus a dashboard_url deep link. The URLs point straight at object storage, so downloads never pass through the API.

Why it's a separate step (and separate scope)

The bundle is stored privately; it is never publicly reachable. Minting is a deliberate, audited action โ€” every call is recorded (Step 4) and gated by its own artifacts:sign scope, separate from artifacts:write. A key that can create or read artifacts cannot silently hand out download links; you grant signing only to the callers that actually need to pull bytes. Short TTLs mean a leaked URL stops working quickly, and because URLs are never stored server-side, they can't be replayed after expiry โ€” you re-mint instead.

Why you'd choose a particular TTL

  • Short (default 1 h) for an automated download that happens immediately โ€” minimise the window a URL is live.
  • Longer (up to 7 days) when a human needs to open the link later, or you're emailing a dashboard link for review. Never longer than you need.

Request body (optional)

FieldTypeNotes
ttl_secondsint1โ€“604800 (7 days). Defaults to 3600 (1 hour). Omit the body entirely for the default.

Response (200)

  • data.attributes.files[] โ€” one { relative_path, signed_url } per file (always iterate; there is no top-level signed_url). First URL captured into {{ad_signed_url}}.
  • links.dashboard_url โ€” a deep link that opens the artifact in Epoch's dashboard, expiring alongside the file URLs. Captured into {{ad_dashboard_url}}.

Visualize tab. Because signed URLs are long and opaque, this step also renders them as clickable links โ€” open the response Visualize tab to click "Open in Epoch dashboard" or download a file directly, rather than copying a raw string.

Requires the artifacts:sign scope โ€” separate from artifacts:write. Minting before the artifact is completed returns 409 artifact_not_completed (see Examples). Feed {{ad_signed_url}} straight into DuckDB / GeoPandas / QGIS โ€” see the consuming recipes.

Next Step

โ†’ Step 4: List Signed URL Audit.