Uploading Files

Build your AI's knowledge base by uploading documents and files.

Overview

Upload files to your personal RAG knowledge base through the dashboard or API. Files are automatically processed, chunked, and embedded for semantic search.

Upload via Dashboard

The easiest way to upload files is through the web dashboard:

Log in to your dashboard
Navigate to the "Knowledge Base" section
Click "Upload Files" button
Select one or multiple files
Wait for processing to complete

Processing Time

File processing typically takes 5-30 seconds depending on file size. You'll see a progress indicator during processing.

Upload via API

For programmatic uploads, use the RAG API endpoint:

Endpoint

text

POST https://superagentstack.orionixtech.com/api/rag/upload

TypeScript/JavaScript Example

upload-file.ts

async function uploadFile(filePath: string) {
  const formData = new FormData();
  const fileBuffer = await fs.readFile(filePath);
  const blob = new Blob([fileBuffer]);
  
  formData.append('file', blob, path.basename(filePath));
  formData.append('metadata', JSON.stringify({
    category: 'documentation',
    tags: ['policy', 'legal']
  }));

  const response = await fetch('https://superagentstack.orionixtech.com/api/rag/upload', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.OPENROUTER_KEY}`,
      'superAgentKey': process.env.SUPER_AGENT_KEY!,
    },
    body: formData,
  });

  const result = await response.json();
  console.log('Upload result:', result);
  return result;
}

// Usage
await uploadFile('./documents/privacy-policy.pdf');

Node.js with File System

upload-multiple.ts

import fs from 'fs/promises';
import path from 'path';

async function uploadMultipleFiles(directory: string) {
  const files = await fs.readdir(directory);
  
  for (const file of files) {
    const filePath = path.join(directory, file);
    const stats = await fs.stat(filePath);
    
    if (stats.isFile()) {
      console.log(`Uploading ${file}...`);
      
      const formData = new FormData();
      const fileBuffer = await fs.readFile(filePath);
      const blob = new Blob([fileBuffer]);
      
      formData.append('file', blob, file);
      
      const response = await fetch('https://superagentstack.orionixtech.com/api/rag/upload', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.OPENROUTER_KEY}`,
          'superAgentKey': process.env.SUPER_AGENT_KEY!,
        },
        body: formData,
      });
      
      const result = await response.json();
      console.log(`✅ Uploaded ${file}:`, result.fileId);
    }
  }
}

// Upload all files in a directory
await uploadMultipleFiles('./documents');

Python Example

upload_file.py

import requests
import os

def upload_file(file_path: str):
    url = "https://superagentstack.orionixtech.com/api/rag/upload"
    
    headers = {
        "Authorization": f"Bearer {os.environ.get('OPENROUTER_KEY')}",
        "superAgentKey": os.environ.get("SUPER_AGENT_KEY"),
    }
    
    with open(file_path, 'rb') as f:
        files = {'file': (os.path.basename(file_path), f)}
        data = {
            'metadata': '{"category": "documentation", "tags": ["policy"]}'
        }
        
        response = requests.post(url, headers=headers, files=files, data=data)
        result = response.json()
        
        print(f"Upload result: {result}")
        return result

# Usage
upload_file('./documents/privacy-policy.pdf')

Response Format

Successful upload returns:

json

{
  "success": true,
  "fileId": "file_abc123xyz",
  "filename": "privacy-policy.pdf",
  "size": 245678,
  "chunks": 12,
  "status": "processed",
  "uploadedAt": "2025-11-16T10:30:00Z",
  "metadata": {
    "category": "documentation",
    "tags": ["policy", "legal"]
  }
}

Supported File Types

Category	Extensions	Max Size
Documents	.pdf, .docx, .doc, .txt, .md, .rtf	50 MB
Code	.js, .ts, .py, .java, .cpp, .go, etc.	10 MB
Data	.json, .csv, .xml, .yaml	25 MB
Spreadsheets	.xlsx, .xls, .csv	25 MB

Adding Metadata

Attach metadata to files for better organization and filtering:

upload-with-metadata.ts

const metadata = {
  category: 'legal',           // Category for organization
  tags: ['gdpr', 'privacy'],   // Tags for filtering
  department: 'compliance',    // Custom fields
  version: '2.1',
  lastReviewed: '2025-11-01',
  author: 'Legal Team'
};

formData.append('metadata', JSON.stringify(metadata));

Metadata Benefits

Metadata helps you:

Filter files in the dashboard
Search by category or tags
Track versions and updates
Organize large knowledge bases

Checking Processing Status

Files go through several processing stages:

Uploaded: File received and stored
Processing: Being chunked and embedded
Processed: Ready for RAG queries
Failed: Processing error occurred

Check Status via API

check-status.ts

async function checkFileStatus(fileId: string) {
  const response = await fetch(
    `https://superagentstack.orionixtech.com/api/rag/files/${fileId}`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.OPENROUTER_KEY}`,
        'superAgentKey': process.env.SUPER_AGENT_KEY!,
      },
    }
  );

  const file = await response.json();
  console.log(`Status: ${file.status}`);
  console.log(`Chunks: ${file.chunks}`);
  
  return file;
}

// Usage
const file = await checkFileStatus('file_abc123xyz');

Batch Upload

Upload multiple files efficiently:

batch-upload.ts

async function batchUpload(files: string[]) {
  const results = [];
  
  // Upload in parallel (max 5 concurrent)
  const chunks = [];
  for (let i = 0; i < files.length; i += 5) {
    chunks.push(files.slice(i, i + 5));
  }
  
  for (const chunk of chunks) {
    const promises = chunk.map(file => uploadFile(file));
    const chunkResults = await Promise.all(promises);
    results.push(...chunkResults);
    
    // Small delay between batches
    await new Promise(resolve => setTimeout(resolve, 1000));
  }
  
  console.log(`✅ Uploaded ${results.length} files`);
  return results;
}

// Upload 20 files in batches of 5
const files = [
  './docs/file1.pdf',
  './docs/file2.pdf',
  // ... more files
];

await batchUpload(files);

Error Handling

upload-with-errors.ts

async function uploadFileWithRetry(filePath: string, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const result = await uploadFile(filePath);
      
      if (result.status === 'failed') {
        throw new Error(`Processing failed: ${result.error}`);
      }
      
      return result;
    } catch (error: any) {
      console.error(`Upload attempt ${attempt + 1} failed:`, error.message);
      
      if (attempt === maxRetries - 1) {
        throw error;
      }
      
      // Exponential backoff
      const delay = 1000 * Math.pow(2, attempt);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

Best Practices

Clean file names: Use descriptive names without special characters
Add metadata: Include category, tags, and version information
Batch uploads: Upload multiple files in parallel for efficiency
Check status: Verify processing completed before using in queries
Handle errors: Implement retry logic for failed uploads
Optimize file size: Compress large files before uploading
Use appropriate formats: PDF and Markdown work best for documents

Storage Limits

Storage limits vary by plan:

Free: 100 MB total storage
Pro: 10 GB total storage
Premium: 100 GB total storage
Enterprise: Unlimited storage