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.
Calypso Context · Buckets
Give every agent the right memory.
A bucket is a named, durable collection of sources. Ingestion writes into buckets, agents search only the buckets they are bound to, and nothing crosses between them unless you bind it. The slug is the handle your scripts use; the id is the stable machine handle.
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.
Agents search curated memory
An agent is bound to the buckets that match its job. Support answers from the handbook; Sales from the catalog; neither sees the other.
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.
One team, four kinds of knowledge, four buckets. Each agent reads the set it is supposed to trust.
bucket://support-handbook
Support
Help center pages, troubleshooting PDFs, screenshots, and escalation notes in one cite-ready set.
bucket://pricing
Pricing
Plan sheets as CSV, packaging docs, procurement FAQs, and discount rules kept apart from broad product knowledge.
bucket://legal
Legal
Terms, policies, compliance PDFs, and data handling documents for a governed, legal-facing agent.
bucket://onboarding
Onboarding
Setup guides, diagrams, checklists, and customer-specific instructions for an onboarding assistant.
How it works
Name it, route into it, bind it.
- 01
Name the bucket
Pick a slug that says what the set is for. Slugs are unique per team and appear in every citation attribute.
- 02
Route sources into it
The bucket is in the URL of every ingestion call: files, imports, pages, batches, and MCP uploads.
- 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 per team 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
Sources
PDFs, images, pages, and data. What it reads and how it gets in.
Agents
One default, any number of named agents with their own scope and policy.
Citations
A source on every answer: annotations by offset, a structured source list, native mode.
Search
Retrieval without generation: the passages an answer would cite, ranked.
Privacy
Yours, isolated: no training on your data, export or delete any time, keys with explicit scopes.
Buckets in the docs
The reference this page is written from, with every endpoint and field.
Start today
Create the source layer your agents can trust.
Provision a bucket, route your first sources into it, and bind it to an agent in the same hour.