TypeScript SDK

npm install caesar-search

Set CAESAR_API_KEY before running the quickstart:

import { Caesar } from "caesar-search";

const caesar = new Caesar(); // reads CAESAR_API_KEY

const results = await caesar.search("postgres 17 logical replication failover", {
  maxResults: 5,
});

for (const result of results.results ?? []) {
  console.log(result.rank, result.title, result.canonical_url);
}

// Read a result as clean markdown — pass a doc_id or a URL
const first = results.results?.[0];
if (!first) throw new Error("No results");

const doc = await caesar.read(first.doc_id, { maxChars: 8000 });
console.log(doc.content?.text ?? "");

The package ships an ESM + CJS dual build with full type definitions. It requires Node >=20 and works in Bun, Deno, and edge runtimes — environment variables are read through a guard, so runtimes without process should pass apiKey explicitly.

Configuration

const caesar = new Caesar({ timeoutMs: 10000, maxRetries: 1 });

Option	Environment variable	Default
`apiKey`	`CAESAR_API_KEY`	required
`baseUrl`	`CAESAR_BASE_URL`	`https://alpha.api.trycaesar.com`
`maxRetries`	—	`3` — retries 429/5xx; `0` disables
`timeoutMs`	—	`30000` — per-request timeout in milliseconds

Methods

async search(query: string, options?: SearchOptions): Promise<SearchResponse>
async read(target?: string, options?: ReadOptions): Promise<DocumentResponse>
async feedback(eventType: string, options?: FeedbackOptions): Promise<FeedbackResponse>

// Files knowledge base
async uploadFile(options: UploadFileOptions): Promise<UploadFileResult>
async presignUpload(filename: string, size: number, options?: PresignUploadOptions): Promise<FilePresignResponse>
async listFiles(): Promise<FileListResponse>
async deleteFile(name: string): Promise<FileDeleteResponse>
async indexFiles(options?: IndexFilesOptions): Promise<FileIndexResponse>
async fileIndexStatus(syncId: string): Promise<FileIndexStatusResponse>

interface SearchOptions {
  maxResults?: number;
  sessionId?: string;
  verbosity?: "ids_only" | "compact" | "standard" | "full";
  maxCharsTotal?: number;   // becomes response.budget.max_chars_total
  extraBody?: Record<string, unknown>;
}

interface ReadOptions {
  docId?: string;
  url?: string;
  query?: string;
  maxChars?: number;
  startChar?: number;       // Continue a truncated read from this character offset.
  include?: string[];
  extraBody?: Record<string, unknown>;
}

interface FeedbackOptions {
  searchId?: string;
  docId?: string;
  passageId?: string;
  query?: string;
  rank?: number;
  notes?: string;
  extraBody?: Record<string, unknown>;
}

How read() resolves its target

The first positional target is auto-detected: a UUID-shaped string is sent as doc_id, anything else as canonical_url. Explicit docId/url options win if both are given. If neither resolves, the SDK throws TypeError("provide a docId or a url"). Default include is ["metadata", "content"]; content selection is full_document; content format is markdown; maxChars is omitted unless you pass it. See documents for the response shape.

Continuation reads

When doc.content?.truncated is true, resume from where the last read ended:

const next = await caesar.read(docId, {
  startChar: (doc.content?.start_char ?? 0) + (doc.content?.char_count ?? 0),
});

A non-zero startChar forces full-document selection and addresses raw document text, so offsets stay contiguous between calls — it will not combine with query-relevant selection.

Response shaping

await caesar.search("query", { verbosity: "compact", maxCharsTotal: 4000 });

verbosity and maxCharsTotal map onto the wire response block — see response shaping.

Uploading files

uploadFile() collapses the presign → upload → index flow into one call. data accepts a Blob, ArrayBuffer, Uint8Array, or string (UTF-8 encoded):

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

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>" } },
});

The file bytes go straight to storage via the presigned URL — the API key is never sent there. Batch several uploads with index: false, then call indexFiles() once. See Files for supported types, limits, and the workspace search scope.

Errors and retries

All error classes are importable from the package root:

import { Caesar, APIStatusError, RateLimitError } from "caesar-search";

try {
  await caesar.search("postgres 17");
} catch (err) {
  if (err instanceof APIStatusError) {
    console.error(err.statusCode, err.code, err.requestId);
  }
}

CaesarError                  base class
├── APIConnectionError       the API could not be reached
│   └── APITimeoutError      request timed out
└── APIStatusError           non-2xx response — .statusCode, .code, .requestId, .response
    ├── AuthenticationError  HTTP 401 or 403
    └── RateLimitError       HTTP 429

.code comes from the API error envelope (error.code), falling back to http_<status>; .requestId carries the server’s request_id. Retry semantics: statuses 429, 500, 502, 503, and 504 are retried up to maxRetries times (default 3 retries, so up to 4 attempts) with exponential backoff of 0.5s doubling per attempt, capped at 8 seconds. Caesar rate limits use X-RateLimit-Reset; if a numeric Retry-After header is present, the client honors it, also capped at 8s. Timeouts and connection failures are not retried — they throw APITimeoutError / APIConnectionError immediately. Each attempt gets its own timeoutMs abort signal.

Raw responses and extra fields

caesar.withResponse.search(...) (also .read, .feedback) takes the same arguments and returns { data, response }, where response is the fetch Response — useful for reading rate-limit headers or status. For request fields the options don’t model yet, pass extraBody; it is merged last and can override any field. All generated request and response types (SearchResponse, DocumentResponse, FeedbackResponse, SearchRequest, FeedbackRequest, and more) are re-exported from the package root.

For agents

timeoutMs is milliseconds (30000 = 30s). The Python SDK uses timeout in seconds — do not transplant values between them.
Response collections and nested objects are typed as optional. Guard with ?? and ?. exactly as the quickstart does (results.results ?? [], doc.content?.text).
Request options are camelCase (maxResults, sessionId, docId); response fields are snake_case as the API returns them (search_id, doc_id, canonical_url, start_char, char_count). Mixing the two directions is the most common bug.

Official SDKs

CLI

TypeScript SDK

Configuration

Methods

How read() resolves its target

Continuation reads

Response shaping

Uploading files

Errors and retries

Raw responses and extra fields

For agents

​Configuration

​Methods

​How read() resolves its target

​Continuation reads

​Response shaping

​Uploading files

​Errors and retries

​Raw responses and extra fields

​For agents

Configuration

Methods

How read() resolves its target

Continuation reads

Response shaping

Uploading files

Errors and retries

Raw responses and extra fields

For agents