Documentation

Technical reference for file management endpoints.

GET /v1/files

List all files in a dataset.

Authentication

• API Key or Frontend Token

Query Parameters

Request

bash
curl https://api.easyrag.com/v1/files?datasetId=my-dataset \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200)

json
{
  "success": true,
  "files": [
    {
      "customerId": "user_abc123",
      "datasetId": "my-dataset",
      "fileId": "f7a3b2c1-4d5e-6f7g",
      "filePath": "customers/user_abc123/datasets/my-dataset/f7a3b2c1-manual.pdf",
      "originalName": "manual.pdf",
      "mimeType": "application/pdf",
      "size": 245678,
      "loaderId": "pdf_loader_xyz",
      "created": "2024-12-12T10:30:00.000Z",
      "extension": ".pdf",
      "transcriptionText": null,
      "transcriptionSrt": null,
      "extraMeta": {
        "department": "support",
        "version": "2.0"
      }
    }
  ]
}

Empty Dataset

json
{
  "success": true,
  "files": []
}

Error Responses

400 Bad Request

json
{
  "error": "datasetId is required via token or query parameter"
}

401 Unauthorized

json
{
  "error": "Missing API key or token"
}

403 Forbidden

json
{
  "error": "datasetId mismatch between token and query"
}

---

GET /v1/files/:fileId

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

Authentication

• API Key or Frontend Token

Path Parameters

Query Parameters

Request

bash
curl https://api.easyrag.com/v1/files/f7a3b2c1-4d5e?datasetId=my-dataset \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200)

json
{
  "success": true,
  "file": {
    "customerId": "user_abc123",
    "datasetId": "my-dataset",
    "fileId": "f7a3b2c1-4d5e-6f7g",
    "filePath": "customers/user_abc123/datasets/my-dataset/f7a3b2c1-manual.pdf",
    "originalName": "manual.pdf",
    "mimeType": "application/pdf",
    "size": 245678,
    "loaderId": "pdf_loader_xyz",
    "created": "2024-12-12T10:30:00.000Z",
    "extension": ".pdf",
    "transcriptionText": null,
    "transcriptionSrt": null,
    "extraMeta": {
      "department": "support"
    },
    "permanentUrl": "https://storage.googleapis.com/bucket-name/path/to/file?Expires=2491-03-09&..."
  }
}

Response Fields

All fields from file object plus:

Note: The permanentUrl is cached after first access for performance.

Error Responses

404 Not Found

json
{
  "error": "File not found"
}

400 Bad Request

json
{
  "error": "datasetId is required via token or query parameter"
}

403 Forbidden

json
{
  "error": "datasetId mismatch between token and query"
}

---

DELETE /v1/files/:fileId

Delete a specific file from a dataset. Removes:

• File from Cloud Storage
• All vector embeddings from Qdrant
• File metadata from Realtime Database

Authentication

• API Key or Frontend Token

Path Parameters

Query/Body Parameters

Request (Query Parameter)

bash
curl -X DELETE \
  "https://api.easyrag.com/v1/files/f7a3b2c1-4d5e?datasetId=my-dataset" \
  -H "Authorization: Bearer YOUR_API_KEY"

Request (Body Parameter)

bash
curl -X DELETE https://api.easyrag.com/v1/files/f7a3b2c1-4d5e \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"datasetId": "my-dataset"}'

Response (200)

json
{
  "success": true
}

Error Responses

404 Not Found

json
{
  "error": "File not found"
}

400 Bad Request

json
{
  "error": "datasetId is required via token, body or query"
}

403 Forbidden

json
{
  "error": "datasetId mismatch between token and path"
}

---

DELETE /v1/datasets/:datasetId/files

Delete all files in a specific dataset. Bulk operation that:

• Removes all files from Cloud Storage
• Clears all vector embeddings for this dataset
• Deletes all file metadata

Authentication

• API Key or Frontend Token

Path Parameters

Request

bash
curl -X DELETE https://api.easyrag.com/v1/datasets/my-dataset/files \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200)

json
{
  "success": true,
  "deleted": 15
}

Response Fields

Empty Dataset

json
{
  "success": true,
  "deleted": 0
}

Error Responses

400 Bad Request

json
{
  "error": "datasetId is required"
}

403 Forbidden

json
{
  "error": "datasetId mismatch between token and path"
}

---

DELETE /v1/files

Delete all files across all datasets for the authenticated customer. Complete wipe that:

• Removes all files from Cloud Storage
• Clears all vector embeddings
• Deletes all file metadata
• Affects every dataset owned by this customer

⚠️ Warning: Irreversible operation affecting all data.

Authentication

• API Key only (frontend tokens cannot perform this operation)

Request

bash
curl -X DELETE https://api.easyrag.com/v1/files \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200)

json
{
  "success": true,
  "deleted": 127
}

Response Fields

Error Responses

401 Unauthorized

json
{
  "error": "Missing API key"
}

---

File Object Schema

TypeScript Definition

typescript
interface File {
  customerId: string;              // Customer who owns the file
  datasetId: string;               // Dataset containing the file
  fileId: string;                  // Unique file identifier (UUID)
  filePath: string;                // Cloud Storage path
  originalName: string;            // Original filename
  mimeType: string | null;         // MIME type (e.g., "application/pdf")
  size: number | null;             // File size in bytes
  loaderId: string;                // EmbedJS loader ID
  created: string;                 // ISO 8601 timestamp
  extension: string;               // File extension (e.g., ".pdf")
  transcriptionText: string | null;  // Transcription text (media only)
  transcriptionSrt: SrtEntry[] | null;  // SRT subtitles (media only)
  extraMeta: Record<string, any> | null;  // Custom metadata
  permanentUrl?: string;           // Signed download URL (GET only)
}

interface SrtEntry {
  id: string;
  startTime: string;    // Format: "HH:MM:SS,mmm"
  endTime: string;      // Format: "HH:MM:SS,mmm"
  text: string;
}

Example File Object

json
{
  "customerId": "user_abc123",
  "datasetId": "my-dataset",
  "fileId": "f7a3b2c1-4d5e-6f7g-8h9i-0j1k2l3m4n5o",
  "filePath": "customers/user_abc123/datasets/my-dataset/f7a3b2c1-document.pdf",
  "originalName": "document.pdf",
  "mimeType": "application/pdf",
  "size": 245678,
  "loaderId": "pdf_loader_f7a3b2c1",
  "created": "2024-12-12T10:30:00.000Z",
  "extension": ".pdf",
  "transcriptionText": null,
  "transcriptionSrt": null,
  "extraMeta": {
    "userId": "user_123",
    "department": "legal",
    "uploadedAt": "2024-12-12T10:29:45.123Z"
  }
}

Transcription Example

json
{
  "fileId": "a1b2c3d4-5e6f-7g8h",
  "originalName": "podcast.mp3",
  "extension": ".mp3",
  "transcriptionText": "Welcome to episode 47 of the AI podcast. Today we're discussing...",
  "transcriptionSrt": [
    {
      "id": "1",
      "startTime": "00:00:00,000",
      "endTime": "00:00:03,500",
      "text": "Welcome to episode 47 of the AI podcast."
    },
    {
      "id": "2",
      "startTime": "00:00:03,500",
      "endTime": "00:00:07,200",
      "text": "Today we're discussing machine learning."
    }
  ]
}

---

Deletion Behavior

Single File Delete

Deletes in this order:

1. Vector embeddings from Qdrant (by loaderId)
2. File from Cloud Storage
3. Metadata from Realtime Database

Failures are logged but don't stop the process.

Bulk Delete (Dataset)

Processes all files concurrently for efficiency.

Complete Delete (Customer)

Iterates through all datasets, processing files concurrently.

Partial Failures

If some operations fail:

• Successful deletions are kept
• Warnings logged to console
• Response still returns success with deletion count

---

Rate Limits

---

Billing

All file management operations are free:

• Listing files: Free
• Getting file details: Free
• Deleting files: Free

Note: Credits spent on uploads are not refunded when files are deleted.

---

Best Practices

1. Confirm Before Bulk Delete

javascript
if (confirm('Delete ALL files in this dataset?')) {
  await fetch(`https://api.easyrag.com/v1/datasets/${datasetId}/files`, {
    method: 'DELETE',
    headers: { 'Authorization': `Bearer ${apiKey}` }
  });
}

2. Cache File Lists

javascript
// Cache for 5 minutes
const cacheKey = `files-${datasetId}`;
const cached = cache.get(cacheKey);

if (cached && Date.now() - cached.timestamp < 5 * 60 * 1000) {
  return cached.files;
}

const { files } = await listFiles(datasetId);
cache.set(cacheKey, { files, timestamp: Date.now() });

3. Handle 404 Gracefully

javascript
try {
  const { file } = await getFile(fileId, datasetId);
} catch (error) {
  if (error.status === 404) {
    console.log('File not found, may have been deleted');
    return null;
  }
  throw error;
}

4. Update UI After Deletion

javascript
const deleteFile = async (fileId) => {
  await fetch(`https://api.easyrag.com/v1/files/${fileId}?datasetId=${datasetId}`, {
    method: 'DELETE',
    headers: { 'Authorization': `Bearer ${apiKey}` }
  });

  // Remove from UI
  setFiles(files.filter(f => f.fileId !== fileId));
};

---

Notes

• permanentUrl is cached in file metadata for performance
• Signed URLs are valid until year 2491
• Deletions are permanent and cannot be undone
• Frontend tokens can only access their authorized dataset
• File metadata is immutable (delete and re-upload to change)
• loaderId is used internally by EmbedJS for vector cleanup
• Transcription fields are null for non-media files

---

Related Endpoints

• POST /v1/files/upload - Upload files
• POST /v1/search - Search indexed files
• POST /v1/query - Query indexed files