Concepts

Projects and the Project ID

A project groups related buckets: an app, a client, a monorepo. Each project has a Project ID that starts with cbp_, like cbp_4k9x2m7q1n8v3c6z0b5w. It never changes, and it's how the API addresses the project (/v1/projects/{project_id}/…). The Console shows it with a copy button on the project page.

An account can have up to 100 projects.

Buckets

A bucket lives in one project and holds your code and assets, up to 10 GB. Its id starts with cbk_. Each bucket has:

• its own encryption key for everything stored in it (Encryption),
• stored objects: the zips and assets you uploaded,
• a code tree built from your latest zip, for preview,
• an events feed and backups.

A project can have up to 100 buckets.

Objects: archives and assets

Everything you upload becomes an object (cbo_…):

Objects count toward the bucket's 10 GB. Deleting one frees its space.

The code tree and refs

When a zip finishes uploading, Code Buckets unpacks it into the bucket's code tree. Each version of the tree has a ref: a 40-character id like 9b1f0c5e2a7d43e8b6c1f0a9d2e5b7c4a1f3e8d0.

• bucket.code.ref is the current version.
• code.updated events and backups record the ref they produced or captured.
• Reading with an explicit ?ref= always returns the same content, so those responses are cached and fast.

A zip replaces the whole tree, or only one folder if you upload it with target_path (like packages/api).

Events

Code Buckets has no comments or threads. Instead every action is an event (cbe_…) in an ordered feed: uploads, code changes, deletions, backups, restores, settings changes and key actions, each with who did it (which API key, or the Console). See Events.

Backups

A backup (cbb_…) captures a bucket's code tree and the list of its stored objects. Restoring puts that tree back as a new version and brings back objects deleted since. See Backups.

Tokens

Code Buckets usage is counted in tokens: 1 per API request, plus 1 per MiB uploaded or downloaded. The Free tier includes 1,000,000 a month. See Pricing.

IDs at a glance