Repositories

A repository is the unit of storage, access control and usage accounting. The SDKs call it a project; they are the same object.

Creating one

1. From the organization, choose New repository.

2. Give it a name. The slug is derived from it (lowercased, hyphenated) and must be unique inside the organization.

3. Choose visibility:

   Visibility	Who can read
   PRIVATE	Members with access, and invited collaborators. The default.
   INTERNAL	Any member of the organization.
   PUBLIC	Anyone with the link, read-only.

4. Choose a storage mode. managed is the default. Pick byos and a storage connection if you want the bytes in your own bucket — the option only appears if your plan includes BYOS and you have a healthy connection. See Bring Your Own S3.

From the API

curl -sS -X POST "https://cavsnode.com/api/v1/organizations/acme-ai/repositories" \
  -H "Authorization: Bearer $CAVS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Vision Models",
        "slug": "vision-models",
        "description": "Trained checkpoints for the vision stack",
        "visibility": "PRIVATE",
        "storage_mode": "managed"
      }'

The response includes the repository’s UUID, which is what every repository-scoped API path takes:

/api/v1/repositories/{repoID}/...

Note

Organization paths accept a slug or a UUID. Repository paths take the UUID only. Resolve a slug to an id with GET /organizations/{org}/repositories, or read it from the dashboard URL. cav repo connect stores it in your Git config as cavs.repo-id.

Caution

Repository count is plan-limited: Free allows one repository; Developer, Team and Business are unlimited. Exceeding it returns 402 quota_exceeded.

The repository views

Tab	What it gives you
Overview	Size, dedup ratio, object count, generation, default branch, recent commits and releases.
Files	The indexed file tree at a ref, with per-file size and history.
Commits	Commit history, with the artifacts each commit touched.
Branches	Every branch, with health flags (stale > 30 days, oversized > 2× the default branch).
Releases	Releases derived from tags, with editable name and notes.
Storage	Logical vs physical over time, largest folders, biggest objects.
Benchmarks	Measured push and pull throughput, dedup and wire savings.
Graph	The lineage graph.
Activity	The repository event feed.
Connect	Copy-paste instructions to wire a Git repository up.
Settings	Description, visibility, collaborators, invitations, storage group, deletion.

Files, Commits, Branches and Releases are backed by the Git index. Until a repository has been indexed they show an empty state and the API returns "indexed": false — run cav repo index --full to populate them.

Reading a repository over the API

export API=https://cavsnode.com/api/v1
export REPO=<repository-uuid>
export H="Authorization: Bearer $CAVS_TOKEN"

curl -sS "$API/repositories/$REPO"           -H "$H"   # the record
curl -sS "$API/repositories/$REPO/overview"  -H "$H"   # dashboard payload
curl -sS "$API/repositories/$REPO/usage"     -H "$H"   # logical/physical/egress
curl -sS "$API/repositories/$REPO/health"    -H "$H"   # health checks
curl -sS "$API/repositories/$REPO/connect"   -H "$H"   # setup instructions

Objects, newest first or largest first:

curl -sS "$API/repositories/$REPO/objects?sort=recent&limit=50&skip=0" -H "$H"
curl -sS "$API/repositories/$REPO/objects?sort=size&limit=20"          -H "$H"

Full parameter tables in Repositories API.

Settings you can change

PATCH /repositories/{repoID} accepts the mutable fields — description, visibility, default branch, storage group. Requires repository.update (DEVELOPER and above, or a WRITE collaborator override).

curl -sS -X PATCH "$API/repositories/$REPO" \
  -H "$H" -H "Content-Type: application/json" \
  -d '{"description": "Production checkpoints only", "visibility": "INTERNAL"}'

Storage mode is set at creation

A repository’s storage_mode and storage connection are chosen when it is created. To move a repository’s bytes between managed storage and your own bucket, create a new repository with the target mode and re-push. There is no in-place migration.

Sharing a repository

Two mechanisms, both under Settings:

• Collaborators — grant an existing organization member an access override (READ, WRITE, ADMIN) that wins over their org role for this repository.
• Invitations — invite someone by email who is not in your organization. They get access to this repository only.

Both are covered in Invitations & collaborators.

Health and recommendations

The worker periodically evaluates each repository and records findings:

curl -sS "$API/repositories/$REPO/health" -H "$H"
curl -sS "$API/repositories/$REPO/recommendations?status=open" -H "$H"

Typical findings: stale branches, branches much larger than the default, low dedup ratio suggesting a format that resists chunking, objects that dominate the repository, unindexed refs. Dismiss one with POST /repositories/{repoID}/recommendations/{recID}/dismiss.

Deleting a repository

Requires repository.admin (ADMIN/OWNER, or an ADMIN collaborator).

curl -sS -X DELETE "$API/repositories/$REPO" -H "$H"

Danger

Deletion removes the metadata immediately and queues the bytes for garbage collection. Managed storage objects are unrecoverable once collected. BYOS objects stay in your bucket — CAVS drops only its own metadata, and cleaning up the prefix is yours to do.

Next

• Connect a Git repository — wire Git and LFS up.
• Pushing & pulling large files — the day-to-day loop.
• Storage insights — read the numbers.