Collections and portals

A collection is a named, ordered list of files that already live in your workspace. Publishing it gives you a portal at https://steadylink.io/c/{slug} where recipients can preview, search, and download those files without a SteadyLink account. This guide is for anyone assembling a press kit, a brand asset pack, or a hand-off folder for a client. By the end you will have a collection with the right access mode, the files in the right order, and a clear idea of what your recipients see.

How a collection relates to your files#

A collection holds references, not copies. Adding a file does not duplicate its bytes or use more storage, and removing it from the collection (or deleting the whole collection) leaves the file where it was in its bucket.

Each item resolves to one revision of its file at the moment someone opens the portal:

• Following current (the default): the portal always shows the file's current revision. When you replace the file, the portal shows the new version on the next page load, with nothing to update.
• Pinned: the item stays on one specific revision number even after the file is replaced. Use this when the collection documents a fixed release, such as "the logo files we approved for the Q3 campaign."

A portal only lists items whose resolved revision has passed malware scanning. A freshly replaced file that is still being scanned drops out of a following-current portal until the scan finishes clean, and a file that fails scanning never appears.

Create a collection#

1. Start a new collection

   Open Share in the dashboard sidebar, stay on the Collections tab, and choose New collection.

2. Name it and choose access

   Enter a name (up to 200 characters) and an optional description (up to 2,000 characters). The name also seeds the portal address: "Press kit 2026" becomes something like /c/press-kit-2026-4f9a1c. The six-character suffix is random, so two collections with the same name never collide. Pick an access mode, described in the next section.

3. Choose files

   Select the files to include and save. Files are added in the order you select them and new files are always appended to the end.

4. Share the link

   Choose Copy link on the collection row. Anyone you send it to sees the portal according to its access mode.

Choose an access mode#

Every collection has exactly one access mode.

A few behaviors are worth knowing before you choose:

• A correct password grants one hour of access. When a recipient enters the correct password, the portal receives an access token valid for one hour (or until the collection expires, if that is sooner). Changing the password means the old one no longer works, but tokens already issued stay valid until they run out. To cut off access immediately, switch the collection to private.
• Expiration applies to every mode. An expired collection returns 410 Gone with "This collection link has expired" whether it is expiring, public, or password. The dashboard sets the expiration to the end of the day you pick.
• Switching modes keeps the link. You can move a collection from private to public or password at any time without changing its address.
• Search engines are asked not to index portals. New collections have noindex turned on, which sets the portal's robots metadata to noindex, nofollow. Turn it off through the API only for collections you want to appear in search results.

Arrange files#

The dashboard adds and removes files. Ordering and pinning are done through the API or the TypeScript SDK.

• Order: send the complete list of item IDs in the order you want. The request must contain every item in the collection exactly once (up to 1,000 items), otherwise it fails with 422 and "Order must contain every collection item exactly once". Read the collection first to get the current item IDs.
• Pin: set an item's version to a revision number to pin it, or to null to make it follow the current revision again. A revision number that does not exist for that file returns 422 Revision not found.
• Duplicates: a file can appear in a collection only once. Adding it again returns 409 with "This asset is already in the collection".

# Create a password-protected collection
curl -X POST https://api.steadylink.io/api/collections \
  -H "X-API-Key: $STEADYLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Press kit 2026",
    "description": "Logos, product photos, and the fact sheet.",
    "accessMode": "password",
    "password": "launch-week-2026"
  }'

# Add a file that follows its current revision
curl -X POST https://api.steadylink.io/api/collections/8d1e5b72-3c4a-4f0e-9b6d-2a7c1e9f4d30/items \
  -H "X-API-Key: $STEADYLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "assetId": "3f2a9c1e-7b4d-4e8a-9c21-5d6f0a1b2c3d" }'

# Add a file pinned to revision 4
curl -X POST https://api.steadylink.io/api/collections/8d1e5b72-3c4a-4f0e-9b6d-2a7c1e9f4d30/items \
  -H "X-API-Key: $STEADYLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "assetId": "b71c0d2e-1f3a-4c5b-8d9e-0a1b2c3d4e5f", "version": 4 }'

import { SteadyLink } from "@steadylink/sdk";

const steadylink = new SteadyLink({ apiKey: process.env.STEADYLINK_API_KEY! });

const kit = await steadylink.createCollection({
  name: "Press kit 2026",
  description: "Logos, product photos, and the fact sheet.",
  accessMode: "password",
  password: "launch-week-2026",
});

await steadylink.addToCollection(kit.id, "3f2a9c1e-7b4d-4e8a-9c21-5d6f0a1b2c3d");    // follows current
await steadylink.addToCollection(kit.id, "b71c0d2e-1f3a-4c5b-8d9e-0a1b2c3d4e5f", 4); // pinned to revision 4

// Put the fact sheet first
const { items = [] } = await steadylink.getCollection(kit.id);
const ids = items.map((item) => item.id as string);
await steadylink.reorderCollection(kit.id, [ids[1], ids[0]]);

console.log(kit.url); // https://steadylink.io/c/press-kit-2026-4f9a1c

import os
from steadylink import SteadyLink

client = SteadyLink(api_key=os.environ["STEADYLINK_API_KEY"])

kit = client.request("POST", "/api/collections", {
    "name": "Press kit 2026",
    "description": "Logos, product photos, and the fact sheet.",
    "accessMode": "password",
    "password": "launch-week-2026",
})

client.request("POST", f"/api/collections/{kit['id']}/items", {"assetId": "3f2a9c1e-7b4d-4e8a-9c21-5d6f0a1b2c3d"})
client.request("POST", f"/api/collections/{kit['id']}/items", {"assetId": "b71c0d2e-1f3a-4c5b-8d9e-0a1b2c3d4e5f", "version": 4})

{
  "id": "8d1e5b72-3c4a-4f0e-9b6d-2a7c1e9f4d30",
  "name": "Press kit 2026",
  "description": "Logos, product photos, and the fact sheet.",
  "slug": "press-kit-2026-4f9a1c",
  "accessMode": "password",
  "expiresAt": null,
  "noindex": true,
  "viewCount": 0,
  "downloadCount": 0,
  "itemCount": 0,
  "createdAt": "2026-10-08T14:02:11.402913",
  "updatedAt": "2026-10-08T14:02:11.402913",
  "canCustomizeBranding": false,
  "branding": {
    "name": null,
    "logoUrl": null,
    "url": null,
    "primaryColor": null,
    "accentColor": null,
    "removeSteadyLinkBranding": false
  }
}

The Python package has no collection helpers, so the example uses its generic request method. The TypeScript SDK has one method per operation:

Every collection the SDK returns carries a url built from the client's appUrl option (default https://steadylink.io) and the slug.

What recipients see#

The portal shows the collection name and description, then one card per file with its name, type, and size. Images show a preview that opens full size in a new tab; other files show a type icon. Each file has a Download button. Collections with 12 or more files also get a search box that filters by file name or type.

Behind the scenes:

• Previews and downloads are served through short-lived links (five minutes) generated for each request, so a copied download URL stops working quickly. Encrypted files are decrypted on the server before they are sent.
• Opening a preview does not count as a download. Loading the portal counts as one view.
• Portal previews and downloads count toward your workspace's monthly delivery usage, the same as delivery-link traffic.

Brand the portal#

On Free and Personal plans the portal shows your workspace name, SteadyLink's default colors, and a SteadyLink credit. On Pro, Business, and Enterprise plans with an active subscription you can set these per collection through the API:

Sending any of these fields on another plan returns 403 with "Custom portal branding is available on Pro and Business plans". The canCustomizeBranding field on every collection tells you in advance whether the workspace qualifies. If a subscription lapses, the portal falls back to the workspace name and default colors and shows the SteadyLink credit again; the saved values return when the subscription is active.

curl -X PATCH https://api.steadylink.io/api/collections/8d1e5b72-3c4a-4f0e-9b6d-2a7c1e9f4d30 \
  -H "X-API-Key: $STEADYLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brandName": "Northwind Studio",
    "brandLogoUrl": "https://northwind.example/logo.svg",
    "brandUrl": "https://northwind.example",
    "primaryColor": "#0b2545",
    "accentColor": "#f4a259",
    "removeSteadyLinkBranding": true
  }'

Track views and downloads#

The collection list in the dashboard shows each collection's file and view counts. For download counts and daily history, call GET /api/collections/{collection_id}/analytics. It returns the lifetime viewCount and downloadCount and a days array with views and downloads for each of the most recent 90 days that had activity. API keys need the assets:read scope for this route.

Limits#

Creating a collection beyond the limit returns 409 with the code feature_limit_reached. Deleting a collection frees its slot. Paid limits apply only while the subscription is active; otherwise the workspace uses Free limits.

Creating, updating, and deleting collections or their items requires a workspace role that can edit files (member, admin, or owner) or an API key with assets:write.

Next steps#