Buckets and folders

This guide helps you set up a structure that still makes sense in a year: when to create a separate bucket, when a folder is enough, how to rename and move files without breaking a single link, and how default visibility is decided for new files. It also covers deleting, which is the one operation in this area that cannot be undone.

Where structure matters, and where it does not#

A file's link is https://cdn.steadylink.io/a/{asset_id}. The bucket, the folder, and the filename are not part of it. That has two consequences:

• You can reorganize freely. Renaming a file, moving it to another folder, or renaming a folder never changes a link.
• Structure is for people and tools, not for delivery. Pick buckets and folders that make files easy to find, review, and automate against.

The path inside a bucket (for example campaign/launch/hero.webp) is called the file's key. The API, SDKs, and CLI use the key to address a file by location; the CLI writes it as bucket:key, such as marketing:campaign/launch/hero.webp.

Choose between a bucket and a folder#

A bucket is a top-level container with its own settings. A folder is a path inside a bucket.

A good default is one bucket per audience or system (website, client-deliveries, releases) and folders for everything else. You can always move files between folders later; you cannot move a file to another bucket without uploading it again under a new asset ID.

Create a bucket#

In the dashboard, open Files, choose New bucket, and enter a name such as marketing-assets. Your first upload creates a bucket called My files automatically if you have none.

curl -X POST https://api.steadylink.io/api/assets/ \
  -H "X-API-Key: $STEADYLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Marketing assets", "slug": "marketing"}'

const { id } = await steadylink.createBucket("Marketing assets", "marketing");
const bucket = await steadylink.findBucket("marketing"); // ID, slug, or name

bucket = client.request("POST", "/api/assets/", {"name": "Marketing assets", "slug": "marketing"})
print(bucket["id"])

{ "id": "7c1d5e2a-4b8f-4f3a-9e61-2d0c8a5b3f17" }

The slug is optional. It gives scripts and the CLI a readable handle (--bucket marketing) that does not depend on the display name. Buckets cannot be renamed after creation, so pick a name that will last; it never appears in a link. API keys need the assets:write scope to create buckets.

Bucket settings#

Open a bucket's menu in Files and choose Bucket settings:

The same settings, plus allowed file types, can be set with POST /api/assets/{bucket_id}/settings. See the Buckets API.

Work with folders#

Folders appear as soon as a file is uploaded into a path, so you rarely need to create one first. To create an empty folder, open a bucket or folder and choose New folder. Move between levels with the breadcrumb, and switch between List view and Gallery view at any level.

# Create an empty folder
curl -X POST "https://api.steadylink.io/api/assets/$BUCKET_ID/folders?path=campaign/launch" \
  -H "X-API-Key: $STEADYLINK_API_KEY"

# List what is directly inside it
curl "https://api.steadylink.io/api/assets/$BUCKET_ID/objects?prefix=campaign/launch/" \
  -H "X-API-Key: $STEADYLINK_API_KEY"

await steadylink.createFolder(bucketId, "campaign/launch");

const { folders, items } = await steadylink.listFiles(bucketId, { prefix: "campaign/launch/" });
for (const file of items) console.log(file.key, file.objectAssetId);

client.request("POST", f"/api/assets/{bucket_id}/folders?path=campaign/launch")
listing = client.request("GET", f"/api/assets/{bucket_id}/objects?prefix=campaign/launch/")

# The CLI creates folders implicitly when you upload with --folder
steadylink ls marketing:campaign/launch/

A listing returns the folders and files directly inside the prefix, not the whole subtree. To find a file anywhere, use Search files in the dashboard or GET /api/assets/_search?q=hero (add scope=bucket&bucket_id=... to search one bucket).

Rename and move files#

Renaming and moving are the same operation: the file gets a new key in the same bucket. Its asset ID, every revision, its visibility, and its link are unchanged. Only the listing entry moves; no bytes are copied.

In the dashboard, open the file's menu and choose Rename or Move, then pick the Destination folder (or Top level).

curl -X POST "https://api.steadylink.io/api/assets/$BUCKET_ID/objects/rename?from_key=hero.webp&to_key=campaign/launch/hero.webp" \
  -H "X-API-Key: $STEADYLINK_API_KEY"

await steadylink.renameFile(bucketId, "hero.webp", "campaign/launch/hero.webp");

from urllib.parse import urlencode

query = urlencode({"from_key": "hero.webp", "to_key": "campaign/launch/hero.webp"})
client.request("POST", f"/api/assets/{bucket_id}/objects/rename?{query}")

{ "renamed": true }

If a file already exists at to_key, the request fails with 409 and nothing changes; rename or remove the other file first. Two things to keep in mind after a move:

• Scripts that address the file by key (marketing:hero.webp) must use the new key. Anything that uses the asset ID or the link is unaffected.
• A later upload to the old key creates a brand-new file with a new asset ID, because that key is now free.

Rename and move folders#

Renaming a folder changes the key of every file inside it in one step. As with files, asset IDs and links do not change. In the dashboard, open the folder's menu and choose Rename or Move.

curl -X POST "https://api.steadylink.io/api/assets/$BUCKET_ID/folders/rename?from_path=campaign/launch&to_path=campaigns/2026/launch" \
  -H "X-API-Key: $STEADYLINK_API_KEY"

/folders/move accepts the same parameters. A folder cannot be moved into its own subtree (400). The SDKs and CLI do not wrap folder renames; call the route directly.

Control visibility#

Every file is either public (anyone with the link can open it) or private (it opens only with a signed link). How a file gets its visibility:

1. At first upload. A new file takes the bucket's Public by default setting. If the bucket has never had that setting saved, it takes the workspace setting New files start as under Settings > Workspace. A workspace that never chose a default treats new files as private.
2. When you change it. Choose Make public or Make private from the file's menu, or set it with the API. The uploader in the dashboard and the SDK's visibility option set it right after upload.
3. Never implicitly afterwards. Changing a bucket or workspace default later affects only files uploaded after the change. Existing files keep their visibility, and replacing a file keeps its visibility too.

curl -X POST "https://api.steadylink.io/api/assets/$BUCKET_ID/objects/visibility?key=campaign/launch/hero.webp&visibility=private" \
  -H "X-API-Key: $STEADYLINK_API_KEY"

await steadylink.setVisibility(bucketId, "campaign/launch/hero.webp", "private");

client.request("POST", f"/api/assets/{bucket_id}/objects/visibility?key=campaign/launch/hero.webp&visibility=private")

# The CLI sets visibility at upload time
steadylink upload ./hero.webp --bucket marketing --folder campaign/launch --private

The API also accepts visibility=inherit, which clears the file's own setting so it follows the bucket's privacy flag (isPrivate in the bucket listing). Making a file private takes effect at SteadyLink immediately, but a public copy fetched in the last five minutes can still be cached by browsers and edges; see Private links for sharing private files.

Delete files, folders, and buckets#

Browsers and edges that fetched a public file in the last few minutes can keep showing their cached copy until it expires, even after the link starts returning 404.

If you only want to stop serving an old version, delete or replace that revision instead of the file; see Revisions. If you want a file to stop being public but keep it, make it private.

Next steps#