How to Replace a File and Keep the Same URL

To replace a file and keep the same URL, the URL has to point at the file's identity, not at one stored copy of it. In SteadyLink every file has a stable link, https://cdn.steadylink.io/a/ASSET_ID; replacing the file publishes the new bytes as its next revision, and the same link starts serving them. Older revisions stay available, so you can roll back.

Why replacing usually changes the URL

Most file hosts build a URL from where the file was stored: a bucket path, a filename, or a random key generated at upload time. When you upload a new version, you often get a new key and therefore a new URL. Now every page, email, app config, and document that used the old one is out of date.

Overwriting the file at the old path sounds like the fix, but it has its own problems. Some hosts do not allow it. Others allow it but leave long-lived caches serving the old bytes, because to a cache the address looks unchanged. Teams then add version numbers to filenames to break the cache, which brings back the original problem: a new URL for every change.

SteadyLink keeps the two ideas apart. The file ID, and the link built from it, are assigned once. The bytes live in revisions, and exactly one revision is current at a time.

Replace a file in the dashboard

1. Open the file in the dashboard.
2. Choose Replace. The same button is on the Version history tab.
3. Pick the new file. Progress appears in the Activity panel.
4. When it finishes, you see "File replaced. Its link is unchanged."

Uploading a file with the same name into the same folder has the same effect: it becomes the next revision of the existing file rather than a second copy.

Replace a file from the CLI

steadylink replace marketing:docs/price-list.pdf ./price-list-2026.pdf
# or by asset ID or link
steadylink replace 3f2a9c1e-8b4d-4e7a-a1c2-5d6e7f809a1b ./price-list-2026.pdf

The target is the file being replaced, written as bucket:key, an asset ID, or the link itself. The second argument is the new file on disk. With --json, the command prints the new version number, asset ID, and URL, which is handy in CI.

Replace a file with the API

The HTTP API does it in three steps: request a temporary upload URL in the file's bucket, PUT the new bytes there, and publish them as the next revision of the key.

TEMP=$(curl -s -X POST "https://api.steadylink.io/api/assets/$BUCKET_ID/objects/upload-temp?size=503221&content_type=application/pdf" \
  -H "X-API-Key: $STEADYLINK_API_KEY")

curl -X PUT "$(echo "$TEMP" | jq -r '.uploadUrl')" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @price-list-2026.pdf

curl -X POST "https://api.steadylink.io/api/assets/$BUCKET_ID/objects/replace?key=docs/price-list.pdf&upload_temp_key=$(echo "$TEMP" | jq -r '.tempKey')&original_filename=price-list-2026.pdf" \
  -H "X-API-Key: $STEADYLINK_API_KEY"

The response is { "replaced": true, "version": 4 }. The replace call finishes synchronously, so when it returns, revision 4 exists and is current. The temporary upload URL is valid for 15 minutes. The JavaScript and Python SDKs wrap the same steps in a single replace call; see the upload and replace guide.

What stays the same and what changes

The new file does not have to be the same type as the old one. If you replace a PDF with a PNG, the link starts answering with image/png. That is flexible, but check the type before publishing if other systems expect a particular format.

Timing after a replacement

• Caching: the stable link is cacheable for five minutes, plus a short background refresh window. Anyone who fetched the old version recently may see it until their cached copy expires.
• Scanning: the new revision is scanned for malware right after it is published. Until the scan finishes, usually seconds, the link responds with 423 Locked rather than serving unscanned bytes.
• Verifying: open the pinned link for the new revision, such as ?v=4, to confirm the new bytes are live without waiting for caches.

If a short gap is not acceptable for a busy file, publish on a schedule with a replacement request.

Roll back

Open the file, go to Version history, and choose Restore on the revision you want. From the CLI:

steadylink versions 3f2a9c1e-8b4d-4e7a-a1c2-5d6e7f809a1b
steadylink rollback 3f2a9c1e-8b4d-4e7a-a1c2-5d6e7f809a1b 3

Restoring makes an older revision current again without creating a new revision number, and the link does not change.

When you want the URL to stay fixed to one version

Sometimes the opposite is what you need: a link that keeps serving exactly one version even after the file is replaced. Use a pinned link, https://cdn.steadylink.io/a/ASSET_ID?v=3. It serves revision 3 for as long as that revision is retained.

Related reading

For specific file types, see how to replace an image without changing its URL and how to update a PDF without changing the link. The stable links concept page covers the identity and revision model in full, and pricing shows the plan limits, starting with the Free plan.