Easy RAG logo

SDK

Quick Start

Get started with the SDK in 5 minutes

Get up and running with the EasyRAG SDK in 5 minutes.

Installation

bash
npm install @easyrag/sdk

Step 1: Initialize Client

javascript
import { EasyRAG } from '@easyrag/sdk';

const client = new EasyRAG(process.env.EASYRAG_API_KEY);

⚠️ Keep your API key secure - always use environment variables, never hardcode.

Step 2: Upload Files

javascript
// Single file
const file = new File(['content'], 'document.pdf', { 
  type: 'application/pdf' 
});

const upload = await client.upload('my-dataset', file);
console.log('Uploaded:', upload.files[0].fileId);

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

Step 3: Search

javascript
const results = await client.search('my-dataset', 'What is the refund policy?');

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

Step 4: Query

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

That's It!

You now know the basics:

  • ✅ Upload files
  • ✅ Search for content
  • ✅ Get AI answers

Common Patterns

Upload with Metadata

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

Search with Filters

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

Streaming Responses

javascript
for await (const chunk of client.queryStream('dataset', 'Explain the features')) {
  if (chunk.delta) {
    process.stdout.write(chunk.delta);
  } else if (chunk.done) {
    console.log('\nComplete!');
  }
}

List and Manage Files

javascript
// List files
const { files } = await client.listFiles('dataset');
console.log(`Total: ${files.length} files`);

// Get file details
const { file } = await client.getFile('dataset', fileId);
console.log('Download:', file.permanentUrl);

// Delete file
await client.deleteFile('dataset', fileId);

Error Handling

javascript
import { EasyRAGError } from '@easyrag/sdk';

try {
  await client.upload('dataset', file);
} catch (error) {
  if (error instanceof EasyRAGError) {
    if (error.status === 402) {
      console.log('Out of credits!');
    } else {
      console.log(`Error: ${error.message}`);
    }
  }
}

TypeScript

The SDK has full TypeScript support:

typescript
import { EasyRAG, type SearchResponse } from '@easyrag/sdk';

const client = new EasyRAG(process.env.EASYRAG_API_KEY!);

const results: SearchResponse = await client.search('dataset', 'query');

Frontend Usage

Never expose API keys in the frontend. Use tokens:

Backend (Node.js):

javascript
// Generate token for user's dataset
const { token } = await client.createToken('user-dataset', { 
  ttlSeconds: 3600 
});

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

Frontend (React/Browser):

javascript
// Get token from your backend
const { token } = await fetch('/api/token').then(r => r.json());

// Use token with SDK
const client = new EasyRAG(token);
await client.search('user-dataset', 'query');

Complete Example

javascript
import { EasyRAG } from '@easyrag/sdk';

const client = new EasyRAG(process.env.EASYRAG_API_KEY);

async function main() {
  try {
    // Upload
    const file = new File(['Hello world'], 'test.txt', { 
      type: 'text/plain' 
    });
    
    const upload = await client.upload('test-dataset', file);
    console.log('✅ Uploaded:', upload.files[0].fileId);
    
    // Search
    const results = await client.search('test-dataset', 'hello');
    console.log('✅ Found:', results.data.length, 'results');
    
    // Query
    const answer = await client.query('test-dataset', 'What does it say?');
    console.log('✅ Answer:', answer.data.result);
    
    // Clean up
    await client.deleteDataset('test-dataset');
    console.log('✅ Cleaned up');
    
  } catch (error) {
    console.error('❌ Error:', error.message);
  }
}

main();

Next Steps

Common Issues

Module not found

Make sure you've installed the SDK:

bash
npm install @easyrag/sdk

Invalid API key

Check that your API key:

  • Starts with sk_
  • Is set in environment variables
  • Hasn't been revoked in the dashboard

Insufficient credits

Check your credit balance in the dashboard. Each upload costs 1 credit, queries cost 0.1 credit.

File upload fails

Verify:

  • File size under 100MB (documents) or 2GB (media)
  • Supported format (.pdf, .docx, .xlsx, etc.)
  • datasetId is provided

Getting Help