Storage groups

A storage group is a label you hang repositories on so the storage explorer can roll usage up the way your organization actually thinks about it: by team, by product, by environment, by lifecycle stage.

Note

Groups are purely organisational. They do not change where bytes land, which storage connection is used, or how anything is billed. For that, see storage modes and Bring Your Own S3.

What they’re for

Once an organization has more than a handful of repositories, “which repository is biggest” stops being a useful question. The useful questions are:

• Which team is driving the growth?
• What does the training data cost versus the shipped models?
• How much are we spending on experiments we could archive?

Groups let the storage explorer answer those without you exporting anything.

Managing them

Organization settings → Storage groups, or over the API. Requires storage.manage to write, storage.read to list.

export API=https://cavsnode.com/api/v1
export H="Authorization: Bearer $CAVS_TOKEN"

# List
curl -sS "$API/organizations/acme-ai/storage-groups" -H "$H"

# Create
curl -sS -X POST "$API/organizations/acme-ai/storage-groups" \
  -H "$H" -H "Content-Type: application/json" \
  -d '{"name": "Training data", "description": "Datasets and preprocessing outputs"}'

# One group
curl -sS "$API/organizations/acme-ai/storage-groups/$GROUP" -H "$H"

# Rename or re-describe
curl -sS -X PATCH "$API/organizations/acme-ai/storage-groups/$GROUP" \
  -H "$H" -H "Content-Type: application/json" \
  -d '{"name": "Training data (v2)"}'

# Delete — repositories are un-grouped, never deleted
curl -sS -X DELETE "$API/organizations/acme-ai/storage-groups/$GROUP" -H "$H"

Assigning a repository

From Repository → Settings, or by patching the repository:

curl -sS -X PATCH "$API/repositories/$REPO" \
  -H "$H" -H "Content-Type: application/json" \
  -d '{"storage_group_id": "<group uuid>"}'

Set it to null to un-group. A repository belongs to at most one group.

Tip

Because a repository has one group, pick one dimension and be consistent. Mixing “Team A”, “Datasets” and “Production” in the same set of groups makes the roll-up meaningless. If you need two dimensions, group by the one you’ll be asked about in a budget meeting.

Reading the roll-up

Groups appear in the organization’s Storage view, with each group’s physical and logical bytes, its repository count and its share of the total.

curl -sS "$API/organizations/acme-ai/dashboard" -H "$H"
curl -sS "$API/organizations/acme-ai/storage-groups" -H "$H"

Schemes that work

By team — ownership and chargeback.

Perception · NLP · Platform · Research

By lifecycle — the archival conversation.

Production · Staging · Experiments · Archive

By data kind — where the money goes.

Datasets · Checkpoints · Released models · Build artifacts

By product — customer-facing cost.

Mobile app · Web client · Game client · Internal tooling

Groups vs the alternatives

You want to…	Use
Roll usage up by team or product	storage groups
Control where bytes physically live	storage mode + BYOS connection
Control who can read a repository	roles and collaborators
Find the biggest folders inside one repository	/storage/folders
Tag individual artifacts	artifact type in the registry

Next

• Storage insights — the explorer groups feed.
• Usage & metering — how usage becomes a bill.