SDK Methods

Complete reference for all EasyRAG SDK methods.

Constructor

new EasyRAG(config)

Initialize the SDK client.

Signature:

typescript
new EasyRAG(apiKey: string): EasyRAG
new EasyRAG(config: EasyRAGConfig): EasyRAG

Parameters:

typescript
interface EasyRAGConfig {
  apiKey: string;      // Required: Your API key or frontend token
  baseUrl?: string;    // Optional: API base URL (default: 'https://api.easyrag.com')
  timeout?: number;    // Optional: Request timeout in ms (default: 30000)
}

Examples:

typescript
// Simple
const client = new EasyRAG('YOUR_API_KEY');

// With config
const client = new EasyRAG({
  apiKey: process.env.EASYRAG_API_KEY,
  timeout: 60000 // 60 seconds
});

---

File Operations

upload()

Upload and index one or more files.

Signature:

typescript
upload(
  datasetId: string,
  files: File | File[],
  options?: UploadOptions
): Promise<UploadResponse>

Parameters:

typescript
interface UploadOptions {
  metadata?: Record<string, Record<string, any>>;  // Per-file metadata
  chunkSize?: number;                               // Default: 300 tokens
  chunkOverlap?: number;                            // Default: 20 tokens
}

Returns:

typescript
interface UploadResponse {
  success: true;
  message: string;
  files: FileMetadata[];
  billed: {
    fileCount: number;
    uploadUnits: number;
  };
}

Examples:

typescript
// Single file
await client.upload('my-dataset', file);

// Multiple files
await client.upload('my-dataset', [file1, file2, file3]);

// With metadata
await client.upload('my-dataset', file, {
  metadata: {
    'document.pdf': {
      userId: 'user_123',
      department: 'legal',
      year: 2024
    }
  }
});

// Custom chunking
await client.upload('my-dataset', file, {
  chunkSize: 500,
  chunkOverlap: 50
});

Cost: 1 credit per file

---

listFiles()

List all files in a dataset.

Signature:

typescript
listFiles(datasetId: string): Promise<ListFilesResponse>

Returns:

typescript
interface ListFilesResponse {
  success: true;
  files: FileMetadata[];
}

Example:

typescript
const { files } = await client.listFiles('my-dataset');

files.forEach(file => {
  console.log(`${file.originalName} (${file.size} bytes)`);
});

Cost: Free

---

getFile()

Get detailed information about a specific file, including download URL.

Signature:

typescript
getFile(
  datasetId: string,
  fileId: string
): Promise<GetFileResponse>

Returns:

typescript
interface GetFileResponse {
  success: true;
  file: FileMetadata & {
    permanentUrl: string;  // Signed download URL
  };
}

Example:

typescript
const { file } = await client.getFile('my-dataset', 'fileId');

console.log('Download:', file.permanentUrl);
console.log('Size:', file.size);
console.log('Created:', file.created);

Cost: Free

---

deleteFile()

Delete a specific file.

Signature:

typescript
deleteFile(
  datasetId: string,
  fileId: string
): Promise<DeleteResponse>

Returns:

typescript
interface DeleteResponse {
  success: true;
}

Example:

typescript
await client.deleteFile('my-dataset', 'fileId');
console.log('File deleted');

Note: Deletion is permanent. Credits are not refunded.

Cost: Free

---

deleteDataset()

Delete all files in a dataset.

Signature:

typescript
deleteDataset(datasetId: string): Promise<DeleteResponse>

Returns:

typescript
interface DeleteResponse {
  success: true;
  deleted: number;  // Number of files removed
}

Example:

typescript
const { deleted } = await client.deleteDataset('my-dataset');
console.log(`Deleted ${deleted} files`);

Warning: This is irreversible and removes ALL files in the dataset.

Cost: Free

---

deleteAll()

Delete all files across all datasets for the authenticated customer.

Signature:

typescript
deleteAll(): Promise<DeleteResponse>

Returns:

typescript
interface DeleteResponse {
  success: true;
  deleted: number;  // Total files removed
}

Example:

typescript
const { deleted } = await client.deleteAll();
console.log(`Deleted ${deleted} total files`);

Warning: Complete wipe. Only works with API keys (not frontend tokens).

Cost: Free

---

Search & Query

search()

Perform semantic search across documents.

Signature:

typescript
search(
  datasetId: string,
  question: string,
  options?: SearchOptions
): Promise<SearchResponse>

Parameters:

typescript
interface SearchOptions {
  filters?: SearchFilter[];
}

interface SearchFilter {
  key: string;
  match: { value: string | number | boolean };
}

Returns:

typescript
interface SearchResponse {
  success: true;
  data: SearchResult[];
}

interface SearchResult {
  score: number;        // 0-1, higher is better
  pageContent: string;  // Text chunk
  metadata: {
    fileId: string;
    originalName: string;
    [key: string]: any;
  };
}

Examples:

typescript
// Basic search
const results = await client.search('my-dataset', 'refund policy');

results.data.forEach(result => {
  console.log(`Score: ${result.score}`);
  console.log(`From: ${result.metadata.originalName}`);
  console.log(`Content: ${result.pageContent}`);
});

// With filters
const results = await client.search(
  'my-dataset',
  'contract terms',
  {
    filters: [
      { key: 'department', match: { value: 'legal' } },
      { key: 'year', match: { value: 2024 } }
    ]
  }
);

Score interpretation:

• 0.9+ - Highly relevant
• 0.8-0.9 - Very relevant
• 0.7-0.8 - Relevant
• < 0.7 - Possibly relevant

Cost: 0.1 credit

---

query()

Get AI-generated answers (non-streaming).

Signature:

typescript
query(
  datasetId: string,
  question: string,
  options?: QueryOptions
): Promise<QueryResponse>

Parameters:

typescript
interface QueryOptions {
  filters?: SearchFilter[];
}

Returns:

typescript
interface QueryResponse {
  success: true;
  data: {
    result: string;
    sources?: Array<{
      pageContent: string;
      metadata: Record<string, any>;
    }>;
  };
}

Examples:

typescript
// Basic query
const answer = await client.query('my-dataset', 'Summarize the key points');
console.log(answer.data.result);

// With filters
const answer = await client.query(
  'my-dataset',
  'What is the vacation policy?',
  {
    filters: [
      { key: 'department', match: { value: 'HR' } }
    ]
  }
);

Note: The AI answers based ONLY on your documents - no hallucinations.

Cost: 0.1 credit

---

queryStream()

Get AI-generated answers with streaming.

Signature:

typescript
queryStream(
  datasetId: string,
  question: string,
  options?: QueryOptions
): AsyncGenerator<StreamEvent>

Returns:

typescript
type StreamEvent = StreamDelta | StreamDone | StreamError;

interface StreamDelta {
  delta: string;  // Text chunk
}

interface StreamDone {
  done: true;     // Stream complete
}

interface StreamError {
  error: string;  // Error message
}

Examples:

typescript
// Basic streaming
for await (const chunk of client.queryStream('my-dataset', 'Explain this')) {
  if (chunk.delta) {
    process.stdout.write(chunk.delta);
  } else if (chunk.done) {
    console.log('\nComplete!');
  } else if (chunk.error) {
    console.error('Error:', chunk.error);
  }
}

// With filters
for await (const chunk of client.queryStream(
  'my-dataset',
  'policy details',
  { filters: [{ key: 'type', match: { value: 'policy' } }] }
)) {
  if (chunk.delta) console.log(chunk.delta);
}

Use when:

• Building chat interfaces
• User experience matters
• Long responses expected

Cost: 0.1 credit (same as non-streaming)

---

Authentication

createToken()

Create a frontend token for browser/mobile use.

Signature:

typescript
createToken(
  datasetId: string,
  options?: CreateTokenOptions
): Promise<CreateTokenResponse>

Parameters:

typescript
interface CreateTokenOptions {
  ttlSeconds?: number;  // Default: 3600, Max: 86400 (24 hours)
}

Returns:

typescript
interface CreateTokenResponse {
  token: string;      // JWT token for frontend
  expiresIn: number;  // Seconds until expiration
}

Examples:

typescript
// Default 1 hour
const { token, expiresIn } = await client.createToken('my-dataset');

// Custom expiry
const { token } = await client.createToken('my-dataset', {
  ttlSeconds: 7200  // 2 hours
});

// Send to frontend
res.json({ token });

Recommended TTL:

• Quick upload: 300s (5 min)
• Chat session: 3600s (1 hour)
• Long session: 14400s (4 hours)
• Maximum: 86400s (24 hours)

Security:

• Only call from backend
• Never expose API keys in frontend
• Tokens are dataset-scoped
• Cannot revoke before expiry

Cost: Free

---

Type Definitions

FileMetadata

typescript
interface FileMetadata {
  customerId: string;
  datasetId: string;
  fileId: string;
  filePath: string;
  originalName: string;
  mimeType: string | null;
  size: number | null;
  loaderId: string;
  created: string;              // ISO 8601
  extension: string;
  transcriptionText: string | null;
  transcriptionSrt: SrtEntry[] | null;
  extraMeta: Record<string, any> | null;
  permanentUrl?: string;        // Only in getFile()
}

EasyRAGError

typescript
class EasyRAGError extends Error {
  status?: number;    // HTTP status code
  code?: string;      // Error code from API
  details?: any;      // Additional error details
}

Example:

typescript
try {
  await client.upload('dataset', file);
} catch (error) {
  if (error instanceof EasyRAGError) {
    console.log('Status:', error.status);    // 402
    console.log('Code:', error.code);        // "INSUFFICIENT_CREDITS"
    console.log('Message:', error.message);  // Human-readable
    console.log('Details:', error.details);  // { required: 1, available: 0 }
  }
}

---

Rate Limits

All limits are per customer.

---

Costs

---

Timeout Configuration

Default timeout: 30 seconds

typescript
// Custom timeout
const client = new EasyRAG({
  apiKey: 'YOUR_API_KEY',
  timeout: 60000  // 60 seconds
});

Requests that exceed the timeout will throw a timeout error.