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.
Elephant · Buckets
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.
Every file, page, batch, and MCP upload names its bucket before indexing starts. There is no unsorted pile to clean up later.
Each member reports its own ready bit and the bucket reports store readiness, so you know before a test whether retrieval can succeed.
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
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.
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
Four parts of a life, four buckets. Each question reads the set it should trust.
bucket://research
Papers, preprints, lecture slides and your own reading notes, ready for a literature review.
bucket://home-and-contracts
Lease, insurance policy, warranties and the letters you keep, quoted clause by clause.
bucket://manuals
User guides for the kettle, the car and the router, so every setup and fix is one question.
bucket://receipts
Invoices and receipts as PDFs and photos, so totals and dates are one question away.
How it works
Pick a slug that says what the set is for. Slugs are unique in your account and appear in every citation attribute.
The bucket is in the URL of every ingestion call: files, imports, pages, batches, and MCP uploads.
A named agent lists the buckets it searches. bucket_ids takes precedence over every other source field in its policy.
From the docs
| 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
Keep reading
PDFs, screenshots, pages and notes. What it reads and how you save it.
Named assistants with their own buckets and instructions.
A source on every answer: file, page and passage, with a link to open it.
The exact passage, ranked, without a written answer.
Private by default: no training on your files, never deletes, you choose what each AI may do.
The reference this page is written from, with every endpoint and field.
Start today
Ask ChatGPT or Claude to create a bucket and save a PDF into it, then ask it a question a minute later.