Buckets

A bucket is a top-level container in a workspace, such as Marketing or Product media. Folders and files live inside it, and its settings decide the default visibility of new files and which uploads it accepts. Use these endpoints to find a bucket ID for uploads, create buckets from a provisioning script, apply an upload policy, or tear a bucket down.

Bucket routes live under /api/assets for historical reasons: in the API, a bucket is an asset of kind bucket, and a file is an asset of kind object. Bucket IDs and file asset IDs are both UUIDs, so keep track of which one you hold.

The JavaScript examples assume const steadylink = new SteadyLink({ apiKey: process.env.STEADYLINK_API_KEY! }) and the Python examples assume client = SteadyLink(api_key=os.environ["STEADYLINK_API_KEY"]).

Endpoints#

Operations#

List buckets#

Returns the workspace's buckets, newest first.

curl "https://api.steadylink.io/api/assets/?limit=100" \
  -H "X-API-Key: $STEADYLINK_API_KEY"

const { items, nextCursor } = await steadylink.listBuckets(100);

// Or look one up by ID, slug, or name (case-insensitive)
const marketing = await steadylink.findBucket("marketing");

page = client.list_buckets(limit=100)
marketing = next(b for b in page["items"] if b.get("slug") == "marketing")

steadylink ls

{
  "items": [
    {
      "id": "7c1e4b2a-5d3f-4e8a-9b61-2f0c8d4a7e15",
      "name": "Marketing",
      "slug": "marketing",
      "kind": "bucket",
      "createdAt": "2026-08-17T18:31:00.412093",
      "isPrivate": false
    },
    {
      "id": "c2a7f0e9-3b14-4d86-8e5a-0f9d1b3c7a42",
      "name": "Product media",
      "slug": null,
      "kind": "bucket",
      "createdAt": "2026-07-02T09:12:45.003118",
      "isPrivate": true
    }
  ],
  "nextCursor": "2026-07-02T09:12:45.003118"
}

nextCursor alone does not tell you that more pages exist. Stop when a page returns fewer buckets than limit, or none.

Create a bucket#

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

const { id } = await steadylink.createBucket("Product media", "acme-product-media");

bucket = client.request("POST", "/api/assets/", {"name": "Product media", "slug": "acme-product-media"})
bucket_id = bucket["id"]

{ "id": "c2a7f0e9-3b14-4d86-8e5a-0f9d1b3c7a42" }

A new bucket starts private or public according to the workspace's default visibility. Workspaces without a stored default start new buckets private, so nothing is published by accident. Change it afterwards with Set a bucket's default privacy or Update bucket settings.

Get a bucket#

Returns the bucket with its settings. A bucket in another workspace returns 403; an unknown ID returns 404 Asset not found.

curl "https://api.steadylink.io/api/assets/7c1e4b2a-5d3f-4e8a-9b61-2f0c8d4a7e15" \
  -H "X-API-Key: $STEADYLINK_API_KEY"

const bucket = await steadylink.getBucket("7c1e4b2a-5d3f-4e8a-9b61-2f0c8d4a7e15");

bucket = client.get_asset("7c1e4b2a-5d3f-4e8a-9b61-2f0c8d4a7e15")

{
  "id": "7c1e4b2a-5d3f-4e8a-9b61-2f0c8d4a7e15",
  "name": "Marketing",
  "slug": "marketing",
  "createdAt": "2026-08-17T18:31:00.412093",
  "isPrivate": false,
  "settings": {
    "default_public": true,
    "max_upload_mb": 50,
    "allowed_mime_prefixes": ["image/", "application/pdf"]
  }
}

settings is null until a setting has been saved. Its keys are described under Update bucket settings.

Set a bucket's default privacy#

curl -X POST "https://api.steadylink.io/api/assets/7c1e4b2a-5d3f-4e8a-9b61-2f0c8d4a7e15/privacy?is_private=true" \
  -H "X-API-Key: $STEADYLINK_API_KEY"

{ "id": "7c1e4b2a-5d3f-4e8a-9b61-2f0c8d4a7e15", "is_private": true }

This changes the bucket's own privacy flag, which governs delivery only for files whose visibility is inherit. Files uploaded through the API and dashboard receive an explicit public or private visibility when they are created, so flipping this flag does not change them. To make every file in a bucket private, set each file's visibility with Set file visibility. To change what new uploads get, set default_public in the bucket settings.

Update bucket settings#

Send a JSON object with the settings to change. Settings you omit keep their current values, and keys not listed below are dropped. Setting keys are snake_case.

curl -X POST "https://api.steadylink.io/api/assets/7c1e4b2a-5d3f-4e8a-9b61-2f0c8d4a7e15/settings" \
  -H "X-API-Key: $STEADYLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "default_public": true,
    "max_upload_mb": 50,
    "allowed_mime_prefixes": ["image/", "application/pdf"]
  }'

client.request(
    "POST",
    "/api/assets/7c1e4b2a-5d3f-4e8a-9b61-2f0c8d4a7e15/settings",
    {"default_public": True, "max_upload_mb": 50, "allowed_mime_prefixes": ["image/", "application/pdf"]},
)

{
  "updated": true,
  "settings": {
    "default_public": true,
    "max_upload_mb": 50,
    "allowed_mime_prefixes": ["image/", "application/pdf"]
  }
}

Upload policies are checked when an upload is finalized, after the bytes have been sent. A file that breaks the policy ends in the blocked state with the error code policy and a message such as File type not allowed by bucket policy. Check types and sizes before uploading if you want to fail faster. See Uploads.

Delete a bucket#

Deletes the bucket, every file in it, every retained revision, cached image variants, and folder markers. Storage used by those revisions is released from the workspace's usage. Every stable link to a file in the bucket stops working.

curl -X DELETE "https://api.steadylink.io/api/assets/c2a7f0e9-3b14-4d86-8e5a-0f9d1b3c7a42" \
  -H "X-API-Key: $STEADYLINK_API_KEY"

await steadylink.deleteBucket("c2a7f0e9-3b14-4d86-8e5a-0f9d1b3c7a42");

client.request("DELETE", "/api/assets/c2a7f0e9-3b14-4d86-8e5a-0f9d1b3c7a42")

{ "deleted": true }

Passing a file's asset ID instead of a bucket ID returns 404 Bucket not found. To delete one file, use Delete a file.

Next steps#