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)
| Field | Type | Notes |
|---|---|---|
ttl_seconds | int | 1โ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-levelsigned_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.