Publishing assets
Publishing separates an asset held in the workspace from an asset released to the world. A published asset gets a permanent URL that needs no login, does not change when a new version is published, and can be revoked. Everything else in the workspace stays private.
This is not the same mechanism as a download URL, which is signed and expires, or a share link, which grants a person access to a collection. A published URL is meant to be pasted into a catalog, a product page or a feed and left there.
Publish an asset
Code
distribution is required, and is either worldwide or restricted. There is no default:
releasing an asset publicly is an explicit decision, and it is recorded as one.
The response carries pub_url, which is the address to keep. It is minted once per asset
and reused for the life of that asset, including across an unpublish and a later republish.
pub_copy_state reports the release itself: the bytes are copied to the delivery store in
the background, and the URL starts answering when that finishes and the copy has been
checksum-verified. Publishing a new version never breaks the URL: the old version keeps
serving until the new one is verified, then the URL moves.
Availability windows
start and end accept timestamps. A start in the future leaves the publication
scheduled and the URL closed until then, when it publishes itself; an end withdraws it
when it passes, exactly as DELETE would. Both edges are walked without anyone watching a
calendar, so a licensing expiry is safe to set months ahead.
Distribution control
With distribution: "restricted", two things narrow where the asset can be fetched from:
deny: country codes (ISO 3166-1 alpha-2) this asset must not be served to.restrictions: ids of the workspace's named geo restrictions, so a country set maintained in one place governs every asset that references it.
A geo restriction can also be marked workspace-wide. Those apply to every published asset
whether or not it names them, and an asset cannot opt out, which is what makes them the
right home for trade compliance rules. GET /files/{id}/publication reports the effective
set, so you never have to reconstruct it.
Rules are enforced at the delivery edge by the address the request comes from, before any bytes are sent, and they apply equally to a cached asset. Edits reach the edge within about a minute.
Renditions
Published image URLs accept transformation parameters: w (a width, snapped up to the
nearest supported size: 160, 320, 640, 1280 or 1920), fmt (webp, avif, jpeg,
png, gif) and wm=1 (the workspace watermark).
Code
A width between sizes answers with the next one up: ?w=800 serves the 1280 rendition.
The fixed sizes are made for srcset, where the browser picks the best fit:
Code
Each variant is generated once and cached, and a source is never upscaled. Unrecognized or unsupported parameters are ignored rather than rejected, so a cache-buster appended by something downstream cannot break a URL. Assets that cannot be transformed serve their original bytes.
Unpublish
Code
The copy is deleted and the URL is retired. It keeps answering 410 Gone rather than
404 Not Found, so anything consuming it can tell a withdrawn asset from an address that
never existed and stop asking.
Status codes on a published URL
| Code | Meaning |
|---|---|
200 | Served. |
206 | A byte range, for seeking within audio and video. |
301 | The URL was written with different capitalization; follow it to the canonical form. |
404 | No asset was ever published at this address. |
410 | Published once, withdrawn since. |
429 | The delivery rate limit for this workspace. |
451 | Refused by distribution rules for the country the request came from. |
503 | The rules could not be read. A rule that cannot be checked is never assumed to permit. |
Every refusal carries a problem+json body with the same shape as the rest of the API, so one error handler covers both.
What the URL is worth on exit
The address is keyed on the asset's own identifier and never reused. A workspace export includes the full mapping of identifier, URL, current version and checksum, and the delivery hostname can be a domain you own, so published links can outlive the arrangement that created them.