How to set up document search with TypeScript in 5 minutes

TL;DR: Install ragex, create a typed client, upload documents, and search — all in five API calls. Ragex handles parsing 16 file types, chunking, embedding, and reranking automatically. The SDK uses native fetch with full TypeScript types and zero external dependencies.

Step 1: Install the SDK

npm install ragex

The SDK ships with full type definitions. It uses native fetch internally — no axios, no node-fetch, no dependencies beyond what Node.js 18+ provides.

Step 2: Initialize the client

import { RagexClient } from 'ragex';

const client = new RagexClient({ apiKey: 'YOUR_API_KEY' });

All methods return typed promises. Your editor gets autocompletion for response fields like KnowledgeBase, Document, and SearchResponse.

Step 3: Create a knowledge base and upload documents

const kb = await client.createKnowledgeBase({ name: 'Support Articles' });

// Upload a file
const file = new File([buffer], 'guide.pdf', { type: 'application/pdf' });
const doc = await client.uploadDocument(kb.id, file);

// Poll until processing completes
let status = doc.status;
while (status !== 'ready' && status !== 'failed') {
  await new Promise(r => setTimeout(r, 2000));
  const updated = await client.getDocument(kb.id, doc.id);
  status = updated.status;
}

You can also ingest raw text without a file:

const textDoc = await client.uploadTextDocument(kb.id, {
  text: 'Your content here...',
  name: 'notes.txt',
});

Documents process asynchronously through pending → parsing → chunking → embedding → ready. A small PDF takes seconds; larger documents take a minute or two.

Step 4: Search

const results = await client.search(kb.id, {
  query: 'How do I reset my password?',
  top_k: 5,
});

for (const result of results.results) {
  console.log(`${result.score.toFixed(3)}: ${result.text.slice(0, 100)}`);
}

Results are ranked by a cross-encoder reranker that runs automatically on every search. You get text chunks, relevance scores, source document names, and page numbers — ready to pass to your LLM as context.

Step 5: Integrate with your LLM

const context = results.results.map(r => r.text).join('\n\n');
const prompt = `Answer based on this context:\n\n${context}\n\nQuestion: How do I reset my password?`;
// Pass to OpenAI, Anthropic, or any LLM

That is the complete setup. Five typed API calls, under 5 minutes, no vector database or embedding model to configure.

How does the TypeScript SDK differ from the Python SDK?

Both SDKs wrap the same REST API and provide the same functionality. The TypeScript SDK adds full type safety — response types for knowledge bases, documents, search results, and errors are all defined in the package. Method names follow the same pattern (createKnowledgeBase, uploadDocument, search) so switching between languages is straightforward.

The TypeScript SDK requires Node.js 18+ for native fetch support. For older Node versions, you can polyfill fetch or use the REST API directly.

FAQ

Does the SDK work in browser environments?

The SDK is designed for server-side Node.js use because it requires an API key that should not be exposed to the client. For browser-based search, set up a thin server endpoint that proxies search requests to the API.

Can I use this in a Next.js API route?

Yes. Import the client in a server-side route handler or API route. Create the client once (outside the handler for connection reuse) and call search inside the handler. The SDK's async methods work naturally with Next.js server functions.

How do I paginate through search results?

The search endpoint returns up to top_k results (max 50) per call. For most search interfaces, 5-10 results per query is sufficient. The API does not support offset-based pagination for search — adjust top_k and score_threshold to control result volume.

---

Last updated: 2026-03-09