---
title: "Calypso Buckets: Retrieval Storage for AI Agents | Calypso"
canonical_url: "https://www.calypso.so/buckets"
last_updated: "2026-06-18T05:57:23.592Z"
meta:
  description: "Use Calypso Buckets to store docs, websites, PDFs, Q&A, and customer context in durable retrieval spaces for source-grounded RAG agents."
  keywords: "Calypso Buckets, RAG buckets, retrieval storage, knowledge buckets, RAG knowledge base, bucket-backed uploads, Calypso RAG API"
  "og:description": "Use Calypso Buckets to store docs, websites, PDFs, Q&A, and customer context in durable retrieval spaces for source-grounded RAG agents."
  "og:title": "Calypso Buckets: Retrieval Storage for AI Agents | Calypso"
  "twitter:description": "Use Calypso Buckets to store docs, websites, PDFs, Q&A, and customer context in durable retrieval spaces for source-grounded RAG agents."
  "twitter:title": "Calypso Buckets: Retrieval Storage for AI Agents | Calypso"
---

Calypso home

Calypso Buckets

# **Retrieval storage built for AI agents. **

Calypso Buckets store docs, websites, PDFs, Q&A, and customer context in durable retrieval spaces. Keep knowledge organized, indexed, and ready for source-grounded answers.

[**Create your first bucket **](https://rag.calypso.so/join) [**Read API docs **](https://docs.calypso.so/knowledge-buckets)

**1-100 **

files per batch

**active **

readiness signal

**scoped **

agent memory

**Bucket live **

## **bucket://support-handbook **

**active **

Indexed members**12 / 12**

**8 **

files

**3 **

websites

**1 **

Q&A

**attached agent **

**calypso-rag-agent:support **

memory scoped to this bucket

## **Buckets are retrieval storage for AI teams**

A Calypso Bucket is a named source layer for RAG. Agents search the buckets you attach instead of scanning an unstructured pile of uploads.

## **Every upload has a destination**

Single-file, batch, UI, and MCP uploads target a bucket id, bucket slug, or bucket name before Calypso accepts the file for indexing.

## **Readiness is visible**

A file can be accepted, queued, indexed, and then bucket-active. Production tests should wait for bucket sync before evaluating answers.

## **Agents get curated memory**

The default hosted agent and named profiles can each point at selected buckets for focused, repeatable retrieval.

**Bucket design **

## **Assemble source collections your agents can trust. **

Pour the right raw material into each bucket: docs, screenshots, websites, FAQs, policies, and customer files. Calypso keeps the retrieval boundary clean so agents answer from the right source set.

`support-handbook`

### **Support**

Sync help center pages, troubleshooting PDFs, screenshots, and escalation notes into one cite-ready support bucket.

`pricing`

### **Pricing**

Keep packaging docs, plan sheets, procurement FAQs, and discount policies separate from broad product knowledge.

`legal`

### **Legal**

Give legal-facing agents a governed source set for terms, policies, compliance PDFs, and data handling documents.

`customer-onboarding`

### **Onboarding**

Assemble setup guides, diagrams, checklists, and customer-specific instructions for onboarding assistants.

**API workflow **

## **List buckets, then sync knowledge into the right one. **

[**Docs **](https://docs.calypso.so/knowledge-buckets)

REST API

```
# List retrieval buckets for this API key
curl https://api.calypso.so/v1/knowledge/buckets \
  -H "Authorization: Bearer sk_..."

{
  "team_id": "team_123",
  "buckets": [
    {
      "id": "bucket_abc",
      "slug": "support-handbook",
      "name": "Support Handbook",
      "status": "active",
      "memberCount": 12,
      "counts": {
        "file": 8,
        "website": 3,
        "qa": 1,
        "retrievable": 12
      },
      "bucketStore": {
        "status": "active",
        "indexed_member_count": 12,
        "pending_member_count": 0
      }
    }
  ]
}
```

**GET**`/v1/knowledge/buckets`

List bucket ids, slugs, source counts, status, and bucket-store readiness for the team behind an API key.

**POST**`/v1/knowledge/files/upload-session`

Create a direct upload session and route one file into bucket_ids, bucket_slugs, bucket, or create_missing_buckets.

**POST**`/v1/knowledge/files:batch/upload-session`

Prepare 1 to 100 files with shared or per-item bucket destinations, then poll readiness.

**Readiness model **

## **Ready means searchable, not just uploaded. **

For reliable RAG tests, wait until each source is indexed and the bucket store reports it as active. That is the point when an agent can retrieve and cite the new knowledge.

**1**

**Accepted**

Part of the durable ingestion path.

**2**

**Queued**

Part of the durable ingestion path.

**3**

**Indexing**

Part of the durable ingestion path.

**4**

**Active source**

Part of the durable ingestion path.

**5**

**Bucket active**

Searchable through the selected bucket.

**Get started with Buckets **

## **Start with buckets, ship grounded answers everywhere. **

Create buckets for each source boundary, attach them to agent profiles, and reuse the same retrieval layer across your website, API, MCP, n8n, and product UI.

[**Get started free **](https://rag.calypso.so/join) [**Bucket docs **](https://docs.calypso.so/knowledge-buckets)