Host the image somewhere that gives it a stable URL tied to the file's identity rather than its bytes, then upload the new version as a replacement instead of as a new file. In SteadyLink, every file gets a link like https://cdn.steadylink.io/a/ASSET_ID; when you choose Replace and upload new artwork, that same link starts serving the new image, and every page, email, and app that uses it updates without being edited. Caches can show the old image for up to about five minutes after the change.
Replace an image in the dashboard
- Upload the original image once, from Upload in the dashboard or by dragging it onto a bucket in Files.
- Copy its link and use it wherever the image needs to appear: your site, a CMS, an email template, a document.
- When the image changes, open the file in the dashboard and choose Replace.
- Pick the new image. Progress appears in the Activity panel, and when it finishes you see "File replaced. Its link is unchanged."
- Open the link to check the result. If you still see the old image, wait a few minutes or hard-refresh.
The Replace button is also on the file's Version history tab. Uploading an image with the same name into the same folder has the same effect: it becomes the next revision of the existing file rather than a copy.
Replace an image with the API or CLI
The CLI takes the file to replace, either as bucket:key or as its asset ID or link, followed by the new file.
steadylink replace marketing:campaign/hero.webp ./hero-v2.webp
# or by asset ID or link
steadylink replace 3f2a9c1e-8b4d-4e7a-a1c2-5d6e7f809a1b ./hero-v2.webp
With the JavaScript SDK:
import { SteadyLink } from "@steadylink/sdk";
import { fileFromPath } from "@steadylink/sdk/node";
const steadylink = new SteadyLink({ apiKey: process.env.STEADYLINK_API_KEY! });
const result = await steadylink.replace(
{ bucketId, key: "campaign/hero.webp" },
await fileFromPath("./hero-v2.webp"),
);
console.log(result.version, result.url);
The raw API is three calls: ask for a temporary upload URL, PUT the bytes to it, then publish them as the next revision of the existing key.
TEMP=$(curl -s -X POST "https://api.steadylink.io/api/assets/$BUCKET_ID/objects/upload-temp?size=284102&content_type=image/webp" \
-H "X-API-Key: $STEADYLINK_API_KEY")
curl -X PUT "$(echo "$TEMP" | jq -r '.uploadUrl')" \
-H "Content-Type: application/octet-stream" \
--data-binary @hero-v2.webp
curl -X POST "https://api.steadylink.io/api/assets/$BUCKET_ID/objects/replace?key=campaign/hero.webp&upload_temp_key=$(echo "$TEMP" | jq -r '.tempKey')&original_filename=hero-v2.webp" \
-H "X-API-Key: $STEADYLINK_API_KEY"
The replace call returns { "replaced": true, "version": 4 } once the new revision exists and is current. The full walkthrough is in the upload and replace guide.
Why ordinary image URLs become a maintenance problem
A conventional storage URL usually describes where a specific file was written. A new file often produces a new key or filename.
https://storage.example.com/campaign/hero-v1.webp
https://storage.example.com/campaign/hero-v2.webp
Publishing the second URL means finding every use of the first one. Overwriting the bytes at the first URL avoids that work, but browsers and CDNs may keep serving the cached response because the address looks identical.
Teams often work around this by adding a date, version number, or hash to every filename. That suits immutable build output, but it is awkward for an image that needs a durable public address. A stable URL separates the public address from the stored revision: the address identifies the image, and a replacement creates another revision behind it.
Use the image in HTML
The stable URL works like any other image source.
<img
src="https://cdn.steadylink.io/a/ASSET_ID"
alt="Campaign artwork"
width="1200"
height="630"
>
The same address can go in a CMS, database, email template, mobile app, README, or document. None of them need to know which revision is current.
Use the image in Next.js
Allow the SteadyLink delivery hostname in next.config.ts.
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
images: {
remotePatterns: [
{
protocol: "https",
hostname: "cdn.steadylink.io",
pathname: "/a/**",
},
],
},
};
export default nextConfig;
Then render the stable URL with the built-in image component.
import Image from "next/image";
const imageUrl = process.env.NEXT_PUBLIC_STEADYLINK_ASSET_URL!;
export default function CampaignHero() {
return (
<Image
src={imageUrl}
alt="Campaign artwork"
width={1200}
height={630}
priority
unoptimized
/>
);
}
The unoptimized property keeps delivery on the SteadyLink URL instead of placing another image cache in front of it. The component does not change when a new revision is published. A complete project is in the Next.js stable image example, and the Next.js images guide covers the setup in more detail.
Account for caching
Replacing an image does not clear every cache at the same instant. The stable link is cacheable for five minutes, with a short background refresh window after that, so a browser or edge that fetched the old image recently can keep showing it until its copy expires. SteadyLink itself switches to the new revision immediately.
To check that the new image is live without waiting, open the pinned link for the new revision, such as ?v=4. Pinned links are separate cache entries.
There is also a short scan window. A new revision is scanned for malware right after it is published, and until the scan finishes the stable link answers 423 Locked rather than serving unscanned bytes. Scans usually take seconds. If a gap matters for a busy image, schedule the change with a replacement request instead.
Pin a revision when the image must not change
When a consumer needs one exact revision indefinitely, add the revision number to the URL.
https://cdn.steadylink.io/a/ASSET_ID?v=4
Pinned responses are immutable and cached for a year. They keep serving revision 4 for as long as that revision is retained, even after later replacements.
When to use which link
Use the stable URL when:
- A logo or campaign image will change over time
- The URL is stored in systems that are hard to update
- The image appears in emails, documents, or third-party embeds
- You want rollback without republishing links
- Several applications should follow the same current version
Use a pinned ?v= URL when:
- The exact bytes are part of a historical record
- A release must stay reproducible
- A cache should keep the file indefinitely
- A consumer should not follow later replacements
Both forms come from the same revision history, so you do not need separate storage for changing and fixed images.
Roll back a bad replacement
Earlier revisions stay in the file's Version history. If the new image is wrong, open the file, go to Version history, and choose Restore on the previous revision. From the CLI, steadylink rollback ASSET_ID 3 does the same. Restoring moves the current pointer back without changing the link.
Related guides
The same approach works for any file type, not just images. See how to replace a file and keep the same URL, how to update a PDF without changing the link, and how to change the file behind a QR code. The stable links concept page explains the identity and revision model, and private links covers public, private, and signed access.
Questions
- Can I replace an image and keep the same URL?
- Yes. Upload the image to SteadyLink once and use its stable link. When the image changes, open the file and choose Replace, or run steadylink replace from the CLI. The link stays the same and starts serving the new image.
- Why do I still see the old image after replacing it?
- The stable link is cacheable for five minutes, plus a short background refresh window. A browser or CDN that fetched the old image recently can show it until its copy expires. Wait a few minutes or hard-refresh, or open the pinned link for the new revision, such as ?v=4, to check it immediately.
- Can I go back to the previous image?
- Yes. Open the file, go to Version history, and choose Restore on the earlier revision. The link does not change. From the CLI, steadylink rollback ASSET_ID 3 does the same.
- How do I link to one exact version of an image?
- Add the revision number to the link, for example https://cdn.steadylink.io/a/ASSET_ID?v=4. A pinned link keeps serving that revision for as long as it is retained, even after later replacements.