Calypso Calypso

Elephant · Sources

PDFs, screenshots, pages and notes. Read, not just stored.

Save a PDF and Elephant reads its text and its pages, so tables, charts and scans count. Screenshots are read for what they show, web pages stay as living sources. If a file cannot be read, you hear it when you save it, not when you ask.

The example

One call in. One bit to wait for.

Upload a file with one multipart request, or hand Elephant a URL. Either way the result is a source in a bucket, and ready tells you when an agent can cite it.

CALYPSO_API_KEY
curl -X POST "https://api.calypso.so/v1/buckets/support-handbook/files" \
  -H "Authorization: Bearer $CALYPSO_API_KEY" \
  -H "Idempotency-Key: crm-doc-123" \
  -F "file=@refund_policy_2026.pdf" \
  -F "title=Refund policy 2026" \
  -F "tags=policy,returns"

# 202 → { "id": "src_…", "ready": false, "status": "queued", … }

What it reads

The accepted types, and what a citation points at.

Modality decides how a source is read. Where the citation points decides what your users can check.

FamilyTypesModalityCitations point at
PDF.pdfMultimodal: text and page imagesThe page
Images.png .jpg .jpegImage, read for content, not filenameThe image
Documents.docxTextThe document
Text.md .txt and other text/*TextThe document
Data.csv .jsonTextThe document
Code.py .ts .tsx .js .jsx .java .go .rs .sql .html .css .scss .yml .yaml .toml .ini .env .shTextThe document

PDFs are the only document type read visually as well as textually, which is why they are the only ones that can cite a specific page. Excel files are not accepted: export the sheet to CSV before uploading.

A URL

Two doors, one decision.

You have a URL. There are two different things you might be asking Elephant to do with it, and they are different promises.

Import a file by URL

You are asking
Copy this exact document.
Endpoint
POST /v1/buckets//files/import
Identity
Each import creates a new source.
Lifecycle
A snapshot, frozen at import time.

Add a web page

You are asking
Make Elephant know this page.
Endpoint
POST /v1/buckets//pages
Identity
The normalized URL is the identity: one per account.
Lifecycle
A living page source, crawled and analyzed.

Pick the wrong door and the API tells you: a file import that receives HTML returns url_is_web_page, a page ingestion that receives a document returns url_is_file. Both point at the other door; force: true overrides.

How it works

Bucket first, then send, then wait for ready.

  1. 01

    Provision the bucket

    PUT /v1/buckets/ is idempotent: it creates the bucket or returns the one that exists. Scripts can call it on every run.

  2. 02

    Send the source

    One multipart call for a file, a direct-to-storage session for anything large, a JSON body for a URL, or a batch of up to 100 files.

  3. 03

    Wait for ready

    Finalize means durably accepted, not searchable. Poll GET /v1/sources/ until ready is true, then test retrieval.

Readiness

Ready means searchable, not just uploaded.

An accepted upload is not yet an answerable source. The ready bit covers both indexing and bucket sync, so it is the only state a test needs.

  1. 1 / 4

    Accepted

    The bytes are stored and the request is durable. A 202 here is not retrieval readiness.

  2. 2 / 4

    Indexed

    The source has been read for its modality: text extracted, pages rendered, images described.

  3. 3 / 4

    Bucket active

    The bucket store that agents search has the source. bucket_sync_status shows the ladder if you need it.

  4. 4 / 4

    Ready

    ready: true. An agent bound to this bucket can retrieve and cite the source.

From the docs

The numbers that matter.

Max file size25 MB
Files per batch1 to 100, direct-to-storage sessions, one finalize
Rate limit5 create requests per second per account
Metadata8 KB per source, up to 20 tags
Readiness checkGET /v1/sources/{id} → ready: true
Web page identityThe normalized URL, one per account; a duplicate returns 409 with the existing source id
ExcelNot accepted. Export to CSV first.

Questions and answers

Before you upload.

Keep reading

Start today

Save your first PDF today.

Attach it in ChatGPT or Claude, or upload it in the console, and ask a question that cites the page.