Core concepts

Every term below appears throughout the API, the CLI and the dashboard. This is the canonical definition of each.

Identity

User

A person, authenticated by Firebase Authentication. A user has a status (ACTIVE being the only one that can act) and belongs to zero or more organizations. Users are created on first sign-in.

Organization

The billing and ownership boundary. An organization owns repositories, members, API tokens, storage connections, webhooks and a subscription to a plan. Its slug is the first component of every repository reference:

acme-ai/vision-models
└──┬───┘ └─────┬─────┘
 org slug   repo slug

Most API paths accept either the organization’s UUID or its slug.

Membership and role

A user’s link to an organization, carrying one role: OWNER, ADMIN, DEVELOPER, VIEWER or BILLING. The role grants a base set of permissions. See Roles & permissions.

Repository collaborator

A per-repository access override — NONE, READ, WRITE or ADMIN — that takes precedence over the org role for that one repository. Collaborators can be external: someone invited to a single repository does not need to be a member of the organization. See Invitations & collaborators.

Repositories and data

Repository

The unit of storage, access control and usage accounting. Also called a project in the SDKs — they are the same thing. A repository has:

Field	Meaning
`slug`	URL-safe name, unique within the organization
`visibility`	`PRIVATE`, `INTERNAL` or `PUBLIC`
`storage_mode`	`managed` or `byos` — see storage modes
`storage_namespace`	The key prefix all its bytes live under, in object storage
`generation`	A monotonic counter, bumped on every finalized push

Object and `oid`

An object is an immutable blob of bytes. Its oid is the lowercase hex SHA-256 of those bytes — 64 characters — and it is the only name the data plane knows:

9f2c8b0e0a1d4f6b7c3e5a9d8f1b2c4e6a8d0f2b4c6e8a0d2f4b6c8e0a2d4f6b

The storage key is derived from it, sharded two levels deep:

<storage_namespace>/objects/9f/2c/9f2c8b0e…4f6b

Objects carry metadata CAVS records for you: logical size, physical_size (post-dedup, post-compression stored bytes), chunk_count, created_at and a download counter. There are no paths at this layer — see Git index.

Chunk

The unit of dedup. The CAVS engine splits objects with content-defined chunking (FastCDC) and addresses each chunk by its BLAKE3-256 hash. Identical chunks are stored once, across versions, across objects and across pushers. See Deduplication explained.

Generation

A monotonic integer on the repository, incremented every time a push is finalized. It marks a consistent state of the tree — the file-tree index is snapshotted per generation and swapped atomically, so a read never sees a half-written tree.

Logical vs physical bytes

Logical — the sum of your objects’ nominal sizes. What a naive store would need.
Physical — the unique compressed bytes actually stored.

Their ratio is the dedup ratio the dashboard reports. Quotas and overage are billed on physical storage.

Movement

Upload session

The bracket around a batch of uploads. It authorizes objects, tracks which have landed, and on finalize promotes them into the repository, bumps the generation and emits events. Sessions expire after 6 hours. Send an Idempotency-Key when opening one so a retried request doesn’t create a second session. See Upload sessions.

Presigned URL

A short-lived, signed object-storage URL that lets your client PUT or GET bytes directly, without the API in the path. Default lifetime 15 minutes. Treat it as a credential: anyone holding it can perform that one operation until it expires. Never log it.

Transfer event

A measured record of one push or pull, reported by the CAVS transfer agent: duration, logical bytes, stored bytes, chunk counts (new vs reused), files put vs skipped. This is what the dashboard’s Benchmarks tab renders. See Storage insights.

Git-side concepts

Git index

The read-only, Git-semantic layer over the oid-only data plane: commits, branches, tags, the file tree per generation, releases and the activity feed. Populated by cav repo index and by the pre-push hook that cav repo connect installs.

Endpoints that read it return "indexed": false when a repository has never been indexed, rather than erroring.

Artifact

A stored object viewed through the index: an oid plus the paths, commits and releases that reference it. GET /repositories/{id}/artifacts/{oid} returns that view. In the SDKs, “artifact” additionally carries a logical name, kind and version, addressed by a cavs:// URI.

Release

A tag with metadata. Derived automatically from your Git tags during indexing; name and notes are editable afterwards. A release aggregates the LFS files reachable at its tag, with file counts and logical bytes.

Snapshot

A point-in-time capture of a repository’s storage state, queued on demand (cav snapshot, or POST …/snapshots) and captured by the worker. Use them for before/after comparisons and for tracking growth over time.

Lineage graph

A directed graph of relationships between artifacts and repositories, partly inferred from the index and partly declared by you via POST …/graph/edges. See Lineage graph.

Storage

Storage mode

managed — CAVS administers the bucket, credentials, lifecycle, backups, integrity, GC and egress. Runs on Cloudflare R2 in production. Managed bytes count against your plan’s storage and egress quotas.
byos — Bring Your Own S3. Bytes live in your bucket under your credentials. CAVS keeps only metadata and coordination. BYOS bytes are not metered as CAVS storage; you pay your provider directly.

See Managed storage and Bring Your Own S3.

Storage connection

An organization-level record describing a BYOS target: provider, endpoint, region, bucket, prefix, auth method and encrypted credentials, plus a health status the worker probes. Secrets are encrypted at rest with AES-256-GCM and are never returned by the API.

Storage group

A logical container for organising repositories in the storage explorer — by team, product or lifecycle stage. Purely organisational; it does not affect where bytes land. See Storage groups.

Storage namespace

The per-repository key prefix in object storage. Two sub-trees live under it:

<namespace>/objects/<xx>/<yy>/<oid>   whole objects (Git LFS basic, upload sessions)
<namespace>/cas/<relative path>       the CAVS static chunk tree (transfer agent)

Access

Token

A machine credential, Authorization: Bearer <token>. Three families by prefix:

Prefix	Kind	Use
`cavs_pat_`	Personal access token — acts as you, capped by your role	interactive, CLI
`cavs_repo_`	Scoped to one repository	a single deploy target
`cavs_ci_`	Machine token for pipelines	CI/CD

A token’s scope is a hard cap: for a PAT the effective permission is your role ∩ token scope. Only the SHA-256 hash is stored. See API tokens.

Scope

repo:read, repo:write, repo:admin, org:read, usage:read. See Roles & permissions for the full mapping to permissions.

Effective permission

The composition the API evaluates on every guarded request:

organization role
  + repository access override
  + token scope        (hard cap)
  + account status
  + organization status

Any one of them denying is a 403.

Conventions

`cavs://` URI

The SDK-level artifact reference:

cavs://{org}/{project}/{kind}/{name}:{version}        logical, mutable
cavs://{org}/{project}/{kind}/{name}@sha256:{oid}     immutable

Store the immutable form in production pipelines so a rerun resolves to the exact same bytes.

Idempotency key

Idempotency-Key: <stable string> on creating an upload session, finalizing, and creating a snapshot. Resending the same key returns the same resource instead of duplicating work.

Correlation id

Every response carries X-Correlation-Id and X-Request-Id (the same value), and error bodies embed it as request_id. Send your own X-Correlation-Id to thread a client-side trace through the platform. Quote it in support requests.