# Content Buckets

A **content bucket** is a stable top-level content group inside a workspace. It groups content types together and serves as the top-level filter in API entry queries.

Think of a content bucket as a content silo — entries in different content buckets cannot relate to each other, and API queries always address a specific content bucket.

## When to use a content bucket

Use one content bucket when all content belongs to the same delivery surface and entries may need to relate to each other. Use separate content buckets for clearly separate domains:

| Content Bucket | Content Types | Purpose |
|---|---|---|
| `content` | pages, posts, authors | Website content |
| `catalog` | products, categories, reviews | Product catalog |
| `support` | articles, faqs | Help center |

Separating content buckets keeps relation fields clean — relation fields can only reference entries from content types in the same content bucket.

## Creating a content bucket

Open `/@acme/entries` and add a content bucket. Two fields are required:

| Field | Rules | Example |
|---|---|---|
| **Name** | Alpha-dash, up to 16 characters. Used in API queries. | `content` |
| **Label** | Up to 16 characters. Displayed in the manager. | `Content` |

The name becomes the `contentBucket` query parameter in API requests.

> Warning: Content Bucket names are API contracts. Renaming a content bucket breaks existing API clients. Choose stable names from the start.

## Content Bucket limits

- Maximum 16 characters for both name and label.
- Names must be alpha-dash (letters, digits, hyphens, underscores).
- A workspace can have as many content buckets as needed, but each content bucket operates independently.

## How content buckets relate to content types

A content bucket contains one or more content types. Each content type belongs to exactly one content bucket. The content bucket-content type relationship determines:

- Which content types appear in the entries screen for a content bucket.
- Which entries can be related through relation fields (same content bucket only).
- Which content bucket parameter is required in API queries.

A typical workspace might have one content bucket for website content and another for product catalog content. Content Types and relation fields stay scoped to their own content bucket.

## API usage

The `contentBucket` parameter is required when listing or creating entries through the API. See [API Entries](/docs/api/entries) for endpoint examples.

## Deleting a content bucket

Deleting a content bucket removes all content types and entries inside it. This operation cannot be undone.

## Related pages

- [Content Types](/docs/content-modeling/content-types) — How content types work inside content buckets.
- [Entries](/docs/content/entries) — Creating and managing content entries.
- [API Entries](/docs/api/entries) — Entry CRUD via the API.