---
title: "Buckets: folders of files your AI can ask | Elephant"
canonical_url: "https://www.calypso.so/elephant/buckets"
last_updated: 2026-11-21
meta:
  description: "A bucket is a folder of sources your AI remembers: a thesis, a lease, a shelf of manuals. Save into it from ChatGPT or Claude, then ask one bucket or all."
  keywords: "organise PDFs for ChatGPT, personal knowledge base AI, AI second brain folders, knowledge base for AI agents, RAG knowledge buckets"
  "og:description": "A bucket is a folder of sources your AI remembers: a thesis, a lease, a shelf of manuals. Save into it from ChatGPT or Claude, then ask one bucket or all."
  "og:title": "Buckets: folders of files your AI can ask | Elephant"
  "twitter:description": "A bucket is a folder of sources your AI remembers: a thesis, a lease, a shelf of manuals. Save into it from ChatGPT or Claude, then ask one bucket or all."
  "twitter:title": "Buckets: folders of files your AI can ask | Elephant"
---

Connect your AI

**Elephant · Buckets**

# Folders your AI remembers.

A bucket is a named folder of sources: your thesis papers, your lease and insurance, the manuals for your home. Save into one from the chat, rename it, move files between buckets. Ask every bucket at once, or only the ones you name. The slug is the handle your scripts use; the id is the stable machine handle.

[**Read the buckets docs**](https://docs.calypso.so/context/manage/buckets) [**Start 14-day free trial**](https://elephant.calypso.so/join?targetAppKey=elephant)

## **Uploads arrive with intent**

Every file, page, batch, and MCP upload names its bucket before indexing starts. There is no unsorted pile to clean up later.

## **Readiness is visible**

Each member reports its own ready bit and the bucket reports store readiness, so you know before a test whether retrieval can succeed.

## **Ask one bucket, or all**

Ask everything at once, or point a question at the buckets that should answer it. Your research never quotes your receipts unless you ask it to.

**The example**

## Provision by slug, then inspect.

PUT on the slug is the recommended way for scripts to make sure a destination exists before uploading: explicit, idempotent, and separate from the upload call.

**CALYPSO_API_KEY**

```
curl -X PUT "https://api.calypso.so/v1/buckets/support-handbook" \
  -H "Authorization: Bearer $CALYPSO_API_KEY"

# 201 when created, 200 with "created": false when it already exists.
# { "id": "bucket_abc", "slug": "support-handbook",
#   "status": "active", "created": true }
```

**Buckets by purpose**

## Separate what should never be mixed.

Four parts of a life, four buckets. Each question reads the set it should trust.

bucket://research

### **Research**

Papers, preprints, lecture slides and your own reading notes, ready for a literature review.

bucket://home-and-contracts

### **Home and contracts**

Lease, insurance policy, warranties and the letters you keep, quoted clause by clause.

bucket://manuals

### **Manuals**

User guides for the kettle, the car and the router, so every setup and fix is one question.

bucket://receipts

### **Receipts**

Invoices and receipts as PDFs and photos, so totals and dates are one question away.

**How it works**

## Name it, route into it, bind it.

1. 01 ### **Name the bucket**

   Pick a slug that says what the set is for. Slugs are unique in your account and appear in every citation attribute.
2. 02 ### **Route sources into it**

   The bucket is in the URL of every ingestion call: files, imports, pages, batches, and MCP uploads.
3. 03 ### **Bind it to an agent**

   A named agent lists the buckets it searches. bucket_ids takes precedence over every other source field in its policy.

**From the docs**

## The endpoints and the rules.

| **Handle** | Slug, unique in your account and human-readable; id, stable for machines |
| --- | --- |
| **Provision** | PUT /v1/buckets/{slug} · 201 created, 200 existing |
| **List** | GET /v1/buckets |
| **Members** | GET /v1/buckets/{bucket}/sources |
| **Detach from one bucket** | DELETE /v1/buckets/{bucket}/sources/{id} |
| **Delete a source everywhere** | DELETE /v1/sources/{id} · POST /v1/knowledge/files:delete (≤ 100 ids) |
| **Scope rule** | bucket_ids takes precedence over every other source field: file_mode is forced to selected and file_ids, website_ids, and qa_ids are cleared |
| **Concurrency** | Two callers ensuring the same slug at once is a success case: the loser re-reads and returns the winner with created: false |

**Questions and answers**

## Before you create one.

**Keep reading**

[<h3>**Sources **</h3>PDFs, screenshots, pages and notes. What it reads and how you save it.](https://www.calypso.so/elephant/sources) [<h3>**Agents **</h3>Named assistants with their own buckets and instructions.](https://www.calypso.so/elephant/agents) [<h3>**Citations **</h3>A source on every answer: file, page and passage, with a link to open it.](https://www.calypso.so/elephant/citations) [<h3>**Search **</h3>The exact passage, ranked, without a written answer.](https://www.calypso.so/elephant/search) [<h3>**Privacy **</h3>Private by default: no training on your files, never deletes, you choose what each AI may do.](https://www.calypso.so/elephant/privacy) [<h3>**Buckets in the docs **</h3>The reference this page is written from, with every endpoint and field.](https://docs.calypso.so/context/manage/buckets)

**Start today**

## **Make your first bucket in the chat.**

Ask ChatGPT or Claude to create a bucket and save a PDF into it, then ask it a question a minute later.

[**Start 14-day free trial**](https://elephant.calypso.so/join?targetAppKey=elephant) [**Read the docs**](https://docs.calypso.so/context/manage/buckets)