API Overview

Complete technical reference for the EasyRAG API.

Base URL

All API requests use:

https://api.easyrag.com/v1

Authentication

Include authentication in every request using one of these headers:

http
Authorization: Bearer YOUR_API_KEY_OR_TOKEN

or

http
x-easyrag-key: YOUR_API_KEY_OR_TOKEN

See Authentication API for details on API keys and frontend tokens.

Request Format

Content-Type

• File uploads: multipart/form-data
• All other requests: application/json

Example POST Request

bash
curl -X POST https://api.easyrag.com/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "datasetId": "my-dataset",
    "question": "What is the refund policy?"
  }'

Response Format

All responses return JSON with this structure:

Success Response

json
{
  "success": true,
  "data": { /* endpoint-specific data */ }
}

or for file operations:

json
{
  "success": true,
  "message": "Operation completed",
  "files": [ /* file objects */ ]
}

Error Response

json
{
  "error": "ERROR_CODE",
  "message": "Human-readable error message"
}

HTTP Status Codes

Common Parameters

datasetId

• Type: string
• Required: Yes (unless using frontend token)
• Description: Unique identifier for the dataset

json
{
  "datasetId": "customer-support"
}

Pagination

Currently not implemented. The /v1/files endpoint returns all files in a dataset.

Filters

Used in search and query endpoints. See Metadata Filtering guide.

json
{
  "filters": [
    {
      "key": "department",
      "match": { "value": "sales" }
    }
  ]
}

Rate Limits

Rate limits apply per customer:

Rate Limit Headers

Responses include rate limit information:

http
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
X-RateLimit-Reset: 1702468800

Rate Limit Exceeded

json
{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests. Please try again later.",
  "retryAfter": 60
}

Idempotency

File uploads are not idempotent. Uploading the same file twice creates two separate entries with different fileId values.

To avoid duplicates:

1. Check existing files with GET /v1/files
2. Track uploaded file IDs in your database

Billing

Operations are charged before execution. If insufficient credits:

json
{
  "error": "INSUFFICIENT_CREDITS",
  "message": "You are out of credits. Please top up to continue.",
  "details": {
    "required": 10,
    "available": 5
  }
}

Credit Costs

API Endpoints

Authentication

File Operations

Search & Query

Data Types

File Object

typescript
interface File {
  fileId: string;              // Unique identifier
  originalName: string;        // Original filename
  datasetId: string;           // Parent dataset
  customerId: string;          // Owner customer ID
  filePath: string;            // Storage path
  mimeType: string | null;     // MIME type
  size: number | null;         // Bytes
  loaderId: string;            // EmbedJS loader ID
  created: string;             // ISO 8601 timestamp
  extension: string;           // File extension
  transcriptionText: string | null;  // For audio/video
  transcriptionSrt: any[] | null;    // SRT subtitles
  extraMeta: object | null;    // Custom metadata
  permanentUrl?: string;       // Signed download URL (cached)
}

Search Result

typescript
interface SearchResult {
  score: number;               // Similarity score (0-1)
  pageContent: string;         // Chunk text
  metadata: {
    fileId: string;
    originalName: string;
    customerId: string;
    datasetId: string;
    [key: string]: any;        // Custom metadata
  };
}

Filter

typescript
interface Filter {
  key: string;                 // Metadata field name
  match: {
    value: string | number | boolean;
  };
}

CORS

The API supports CORS for browser-based applications.

Allowed origins: * (all origins)

Allowed methods: GET, POST, DELETE, OPTIONS

Allowed headers: Authorization, Content-Type, x-easyrag-key

Webhooks

Coming soon: Webhook support for:

• Upload completion notifications
• Transcription completion
• Error notifications

Versioning

The current API version is v1. Breaking changes will be introduced in new versions (e.g., v2).

The version is included in the base URL:

https://api.easyrag.com/v1
https://api.easyrag.com/v2  (future)

We'll maintain support for previous versions for at least 12 months after deprecation notice.

Client Libraries

Official SDKs

Coming soon:

• JavaScript/TypeScript SDK
• Python SDK

Community Libraries

None yet. We'd love to feature yours! Email support@easyrag.com

Testing

Sandbox Environment

Coming soon: Separate sandbox environment for testing without using production credits.

Test Files

For testing, you can use these small files:

• Small PDF: ~50KB
• Small text: ~10KB
• Small audio: ~1MB

Support

• 📧 API Issues: support@easyrag.com
• 📚 User Guides: easyrag.com/docs
• 🏠 Dashboard: easyrag.com

Quick Links

• Authentication API
• Upload API
• File Management API
• Search API
• Query API
• Error Handling