Files - Caesar

The Files endpoints give every organization a private knowledge base. Upload documents once and they become searchable through the same POST /v1/search call you already use for the web — scoped to your organization, invisible to everyone else. The flow is always the same four steps:

Presign — POST /v1/files/presign returns a short-lived upload URL bound to your file’s exact size.
Upload — PUT the raw bytes to that URL. The bytes go straight to storage; they never pass through the API.
Index — POST /v1/files/index starts an indexing run; poll GET /v1/files/index/{sync_id} until it completes.
Search — query with scope.indexes: ["workspace"] and your organization id as workspace_id.

The SDKs and CLI collapse steps 1–3 into a single call.

caesar-search files upload ./q3-report.pdf
# uploaded q3-report.pdf (1.8 MB)
# indexing started: 7f3c2a1e-... (queued)

caesar-search files status 7f3c2a1e-...
# 7f3c2a1e-...: completed

from caesar_search import Caesar

client = Caesar()
upload = client.upload_file("q3-report.pdf")           # presign + upload + index
status = client.file_index_status(upload.sync_id)      # poll until "completed"

hits = client.search(
    "q3 revenue",
    extra_body={"scope": {"indexes": ["workspace"], "workspace_id": "<your-org-id>"}},
)

import { readFileSync } from "node:fs"; // works in Node, Bun, and Deno
import { Caesar } from "caesar-search";

const caesar = new Caesar();
const upload = await caesar.uploadFile({
  filename: "q3-report.pdf",
  data: readFileSync("./q3-report.pdf"),
  contentType: "application/pdf",
});
const status = await caesar.fileIndexStatus(upload.sync_id!); // poll until "completed"

const hits = await caesar.search("q3 revenue", {
  extraBody: { scope: { indexes: ["workspace"], workspace_id: "<your-org-id>" } },
});

# 1. Presign (size must be the exact byte count)
curl -s https://alpha.api.trycaesar.com/v1/files/presign \
  -H "Authorization: Bearer $CAESAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "q3-report.pdf", "size": 1895311, "content_type": "application/pdf"}'

# 2. Upload — note: NO Authorization header; the URL's signature authorizes it
curl -s -X PUT "$PRESIGNED_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @q3-report.pdf

# 3. Index, then poll
curl -s -X POST https://alpha.api.trycaesar.com/v1/files/index \
  -H "Authorization: Bearer $CAESAR_API_KEY" -H "Content-Type: application/json" -d '{}'
curl -s https://alpha.api.trycaesar.com/v1/files/index/$SYNC_ID \
  -H "Authorization: Bearer $CAESAR_API_KEY"

Searching your files

Workspace search runs through the ordinary search endpoint with a scope:

{
  "query": "q3 revenue",
  "scope": { "indexes": ["workspace"], "workspace_id": "<your-org-id>" }
}

workspace_id is your organization id; the API verifies it matches the key’s organization, so no other tenant’s files are ever reachable.
Use "indexes": ["web", "workspace"] to blend web and file results in one response; workspace hits are tagged "index": "workspace" and ranked separately from web results.
Workspace results carry the same provenance handles as web results — doc_id, passages, and a source_uri pointing at the stored object — and can be opened with POST /v1/document by doc_id.

Managing files

Operation	Endpoint
List uploads	`GET /v1/files` → `{ files: [{ name, size, last_modified }] }`
Delete by name	`DELETE /v1/files/{name}` — the document drops out of search after the automatic reconciliation run
Re-index everything	`POST /v1/files/index` with `{ "mode": "full" }`

Filenames are the identity: the API deals in the sanitized name echoed by presign, never in storage paths. Uploading the same filename again replaces the file (and re-indexing updates the document in place).

Indexing runs

POST /v1/files/index accepts { "mode": "incremental" } (default — new and changed files only) or { "mode": "full" } (reprocess everything). It answers 202 with a sync_id; poll GET /v1/files/index/{sync_id}:

{
  "sync_id": "7f3c2a1e-...",
  "state": "completed",
  "stats": { "enumerated": 3, "fetched": 1, "indexed": 3, "failed": 0, "skipped_unsupported": 0, "deleted": 0, "bytes": 1895311 },
  "error": null
}

Terminal states are completed and failed. The SDK/CLI upload helpers trigger one incremental run per upload call by default; when uploading many files, batch them (index=False / --no-index) and start one run at the end.

Supported types and limits

Constraint	Value
File types	`pdf`, `html`, `htm`, `txt`, `md`, `docx`, `pptx`, `xlsx`, `doc`, `ppt`, `xls`, `rtf`, `odt`, `odp`, `ods`, `csv`, `tsv`
Max file size	100 MB per file (`max_object_bytes` in the presign response is authoritative)
Presigned URL lifetime	15 minutes (`expires_in_seconds`)

Unsupported types are rejected at presign time with 415 unsupported_file_type; oversized files with 413 file_too_large.

How presigned uploads work

The presign response’s url is a signed storage URL:

It authorizes exactly one PUT of exactly the declared size, for 15 minutes. A body of any other length is rejected by storage with 403.
Send no Authorization header on the PUT — the signature in the URL is the authorization, and your API key must never be sent to storage.
Treat the URL like a short-lived token: anyone holding it can upload that one object until it expires.

​Searching your files

​Managing files

​Indexing runs

​Supported types and limits

​How presigned uploads work

Searching your files

Managing files

Indexing runs

Supported types and limits

How presigned uploads work