Revisions
What SteadyLink keeps for every version of a file, how to label and restore revisions, and exactly what deleting one removes.
On this page
Every time a file's bytes change, SteadyLink keeps the new bytes as a numbered revision and leaves the older ones in place. This page is for anyone who manages file history: you will learn what a revision records, how to make an older one current, and what happens to links and storage when you delete revisions.
What a revision stores#
Revisions are numbered from 1. Each one is an immutable copy of the bytes plus the facts SteadyLink recorded about them:
| Field | Meaning |
|---|---|
versionNumber | The number used in pinned links (?v=3) and revision API routes. |
byteSize | Size of the stored original in bytes. |
mime | Content type, checked against the bytes during upload. |
width, height | Pixel dimensions for images; null for other files. |
hash | SHA-256 checksum of the original bytes. |
scanStatus | Malware scan result: pending, clean, infected, or error. |
metadataStatus | Progress of metadata extraction: pending, processing, complete, or error. |
createdAt, createdBy | When the revision was created, and the user who created it when one was recorded. createdBy is often null, for example for API-key uploads and uploads finalized in the background. |
label, note | Optional team-facing text. See below. |
isCurrent | Whether the stable link serves this revision right now. |
Revision bytes are never edited. To change a file, you add a revision.
In the dashboard, open a file and choose the Version history tab. The current revision is marked Current.
Labels and notes#
A label is a short name, up to 120 characters, such as Spring 2026 price list. A note is longer context, up to 1,000 characters, such as who approved the change. Both are visible to workspace members only; they are never sent with delivered files.
Set either one to an empty string to clear it. In the dashboard, select a revision's name to rename it.
curl -X PATCH "https://api.steadylink.io/api/assets/$ASSET_ID/versions/4" \
-H "X-API-Key: $STEADYLINK_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "label": "Spring 2026 price list", "note": "Approved by finance on 3 March." }'await steadylink.updateVersion(assetId, 4, {
label: "Spring 2026 price list",
note: "Approved by finance on 3 March.",
});client.request("PATCH", f"/api/assets/{asset_id}/versions/4", {
"label": "Spring 2026 price list",
"note": "Approved by finance on 3 March.",
})Make an older revision current#
Restoring a revision (the API calls it promoting) moves the file's current pointer. It does not copy bytes or create a new revision, so the history keeps its numbering and the restored revision keeps its number.
- In the dashboard, open Version history and choose Restore on the revision.
- With the API, send
POST /api/assets/{asset_id}/versions/{version}/promote.
curl -X POST "https://api.steadylink.io/api/assets/$ASSET_ID/versions/3/promote" \
-H "X-API-Key: $STEADYLINK_API_KEY"await steadylink.rollback(assetId, 3);client.request("POST", f"/api/assets/{asset_id}/versions/3/promote")steadylink rollback 3f2a9c1e-7b4d-4e8a-9c61-2d5f0a8b7e13 3Only a revision whose scan result is clean can be restored. Anything else returns 409 Only clean revisions can be promoted. That includes revisions whose scan is still pending, so wait for the scan before restoring a revision you just uploaded.
The stable link serves the restored revision immediately from SteadyLink. Browsers and CDNs that cached the previous response may keep it for up to five minutes; see Caching.
Schedule a change#
You do not have to switch revisions by hand at the right moment. Any retained clean revision can be scheduled to become current at a future time, with an optional later rollback to the revision that was current before. The publish time must be at least ten seconds ahead and no more than one year ahead, and a scheduled job can be cancelled only while it is still queued. See Replacement requests for the workflow and Requests API for the routes.
Delete a revision#
Deleting a revision permanently removes its original bytes and every cached image variant made from it. Its size stops counting toward your storage immediately. There is no undo.
| You delete | What happens |
|---|---|
| A revision that is not current | It is removed. Pinned links to it (?v=N) return 404. The stable link is unaffected. |
| The current revision | Refused with 400 unless you pass force=true. With force=true, the highest-numbered remaining revision becomes current. |
| The only remaining revision | The file itself is deleted: its ID, its place in the bucket, and its stable link, which then returns 404. Because it is also the current revision, this needs force=true. |
curl -X DELETE "https://api.steadylink.io/api/assets/$ASSET_ID/versions/2" \
-H "X-API-Key: $STEADYLINK_API_KEY"await steadylink.deleteVersion(assetId, 2);
// Deleting the current revision needs force:
await steadylink.deleteVersion(assetId, 5, { force: true });client.request("DELETE", f"/api/assets/{asset_id}/versions/2")With force=true, "highest-numbered remaining revision" is chosen by number only. If that revision is not clean, the stable link returns 423 or 404 until you restore a clean one, so check the history before force-deleting the current revision.
Retention#
Each plan lists a revision history window: 30 days on Free, 90 days on Personal, and long-term on Pro and Business. Automatic expiry of old revisions is not active yet. Today every revision stays until someone deletes it, and every retained revision counts toward storage. See Usage and limits.
If storage matters to you, delete revisions you no longer need. GET /api/analytics/storage breaks storage down from each bucket to each file, with the current revision's size next to the total retained size.