Managing Knowledge

Organize, update, and maintain your RAG knowledge base.

Overview

Keep your knowledge base up-to-date by listing, updating, and deleting files. All operations are available through both the dashboard and API.

List All Files

Endpoint

text

GET https://superagentstack.orionixtech.com/api/rag/files

TypeScript Example

list-files.ts

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

  const data = await response.json();
  console.log(`Total files: ${data.files.length}`);
  
  data.files.forEach((file: any) => {
    console.log(`- ${file.filename} (${file.size} bytes, ${file.chunks} chunks)`);
  });
  
  return data.files;
}

// Usage
const files = await listFiles();

Response Format

json

{
  "files": [
    {
      "fileId": "file_abc123",
      "filename": "privacy-policy.pdf",
      "size": 245678,
      "chunks": 12,
      "status": "processed",
      "uploadedAt": "2025-11-16T10:30:00Z",
      "metadata": {
        "category": "legal",
        "tags": ["privacy", "gdpr"]
      }
    },
    {
      "fileId": "file_xyz789",
      "filename": "user-guide.md",
      "size": 89012,
      "chunks": 8,
      "status": "processed",
      "uploadedAt": "2025-11-15T14:20:00Z",
      "metadata": {
        "category": "documentation",
        "tags": ["guide", "tutorial"]
      }
    }
  ],
  "totalFiles": 2,
  "totalSize": 334690,
  "totalChunks": 20
}

Filter Files

Filter files by category, tags, or status:

filter-files.ts

async function filterFiles(filters: {
  category?: string;
  tags?: string[];
  status?: string;
}) {
  const params = new URLSearchParams();
  
  if (filters.category) {
    params.append('category', filters.category);
  }
  
  if (filters.tags) {
    filters.tags.forEach(tag => params.append('tags', tag));
  }
  
  if (filters.status) {
    params.append('status', filters.status);
  }

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

  return await response.json();
}

// Get all legal documents
const legalDocs = await filterFiles({ category: 'legal' });

// Get files with specific tags
const privacyDocs = await filterFiles({ tags: ['privacy', 'gdpr'] });

// Get only processed files
const processedFiles = await filterFiles({ status: 'processed' });

Get File Details

Endpoint

text

GET https://superagentstack.orionixtech.com/api/rag/files/{fileId}

Example

get-file.ts

async function getFileDetails(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(`File: ${file.filename}`);
  console.log(`Status: ${file.status}`);
  console.log(`Chunks: ${file.chunks}`);
  console.log(`Uploaded: ${file.uploadedAt}`);
  
  return file;
}

// Usage
const file = await getFileDetails('file_abc123');

Response

json

{
  "fileId": "file_abc123",
  "filename": "privacy-policy.pdf",
  "size": 245678,
  "chunks": 12,
  "status": "processed",
  "uploadedAt": "2025-11-16T10:30:00Z",
  "processedAt": "2025-11-16T10:30:25Z",
  "metadata": {
    "category": "legal",
    "tags": ["privacy", "gdpr"],
    "version": "2.1"
  },
  "chunkDetails": [
    {
      "chunkId": "chunk_001",
      "tokens": 512,
      "position": 0
    },
    {
      "chunkId": "chunk_002",
      "tokens": 498,
      "position": 1
    }
  ]
}

Update File Metadata

Endpoint

text

PATCH https://superagentstack.orionixtech.com/api/rag/files/{fileId}

Example

update-metadata.ts

async function updateFileMetadata(
  fileId: string,
  metadata: Record<string, any>
) {
  const response = await fetch(
    `https://superagentstack.orionixtech.com/api/rag/files/${fileId}`,
    {
      method: 'PATCH',
      headers: {
        'Authorization': `Bearer ${process.env.OPENROUTER_KEY}`,
        'superAgentKey': process.env.SUPER_AGENT_KEY!,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ metadata }),
    }
  );

  return await response.json();
}

// Update metadata
await updateFileMetadata('file_abc123', {
  category: 'legal',
  tags: ['privacy', 'gdpr', 'updated'],
  version: '2.2',
  lastReviewed: '2025-11-16'
});

Delete File

Endpoint

text

DELETE https://superagentstack.orionixtech.com/api/rag/files/{fileId}

Example

delete-file.ts

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

  const result = await response.json();
  console.log(`File deleted: ${result.success}`);
  
  return result;
}

// Delete a file
await deleteFile('file_abc123');

Permanent Deletion

Deleting a file is permanent and cannot be undone. All chunks and embeddings associated with the file will be removed from the knowledge base.

Bulk Operations

Delete Multiple Files

bulk-delete.ts

async function bulkDelete(fileIds: string[]) {
  const results = [];
  
  for (const fileId of fileIds) {
    try {
      const result = await deleteFile(fileId);
      results.push({ fileId, success: true });
      console.log(`✅ Deleted ${fileId}`);
    } catch (error) {
      results.push({ fileId, success: false, error });
      console.error(`❌ Failed to delete ${fileId}`);
    }
  }
  
  return results;
}

// Delete multiple files
const fileIds = ['file_abc123', 'file_xyz789', 'file_def456'];
await bulkDelete(fileIds);

Update Multiple Files

bulk-update.ts

async function bulkUpdateMetadata(
  fileIds: string[],
  metadata: Record<string, any>
) {
  const promises = fileIds.map(fileId =>
    updateFileMetadata(fileId, metadata)
  );
  
  const results = await Promise.all(promises);
  console.log(`✅ Updated ${results.length} files`);
  
  return results;
}

// Add a tag to multiple files
const legalFiles = await filterFiles({ category: 'legal' });
const fileIds = legalFiles.files.map((f: any) => f.fileId);

await bulkUpdateMetadata(fileIds, {
  tags: ['reviewed', 'approved']
});

Search Files by Content

Search for files containing specific content:

search-files.ts

async function searchFiles(query: string) {
  const response = await fetch(
    'https://superagentstack.orionixtech.com/api/rag/search',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.OPENROUTER_KEY}`,
        'superAgentKey': process.env.SUPER_AGENT_KEY!,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        query,
        topK: 10,
        minScore: 0.7
      }),
    }
  );

  const results = await response.json();
  
  results.chunks.forEach((chunk: any) => {
    console.log(`File: ${chunk.filename}`);
    console.log(`Score: ${chunk.score}`);
    console.log(`Content: ${chunk.content.substring(0, 100)}...`);
    console.log('---');
  });
  
  return results;
}

// Search for content about GDPR
const results = await searchFiles('GDPR data retention policy');

Storage Management

Check Storage Usage

check-storage.ts

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

  const storage = await response.json();
  
  console.log(`Used: ${storage.used} MB`);
  console.log(`Limit: ${storage.limit} MB`);
  console.log(`Available: ${storage.available} MB`);
  console.log(`Usage: ${storage.percentage}%`);
  
  return storage;
}

// Check storage
const storage = await getStorageInfo();

if (storage.percentage > 90) {
  console.warn('⚠️ Storage almost full! Consider deleting old files.');
}

Clean Up Old Files

cleanup-old-files.ts

async function cleanupOldFiles(daysOld: number = 90) {
  const files = await listFiles();
  const cutoffDate = new Date();
  cutoffDate.setDate(cutoffDate.getDate() - daysOld);
  
  const oldFiles = files.filter((file: any) => {
    const uploadDate = new Date(file.uploadedAt);
    return uploadDate < cutoffDate;
  });
  
  console.log(`Found ${oldFiles.length} files older than ${daysOld} days`);
  
  if (oldFiles.length > 0) {
    const fileIds = oldFiles.map((f: any) => f.fileId);
    await bulkDelete(fileIds);
    console.log(`✅ Cleaned up ${oldFiles.length} old files`);
  }
}

// Delete files older than 90 days
await cleanupOldFiles(90);

Best Practices

Use metadata: Tag and categorize files for easy filtering
Regular cleanup: Remove outdated files to save storage
Version control: Include version numbers in metadata
Monitor storage: Check usage regularly to avoid limits
Organize by category: Group related files together
Update metadata: Keep tags and categories current
Test before deleting: Verify files aren't needed before removal

Python Examples

manage_files.py

import requests
import os

BASE_URL = "https://superagentstack.orionixtech.com/api/rag"
HEADERS = {
    "Authorization": f"Bearer {os.environ.get('OPENROUTER_KEY')}",
    "superAgentKey": os.environ.get("SUPER_AGENT_KEY"),
}

def list_files():
    response = requests.get(f"{BASE_URL}/files", headers=HEADERS)
    return response.json()

def get_file(file_id):
    response = requests.get(f"{BASE_URL}/files/{file_id}", headers=HEADERS)
    return response.json()

def update_metadata(file_id, metadata):
    response = requests.patch(
        f"{BASE_URL}/files/{file_id}",
        headers={**HEADERS, "Content-Type": "application/json"},
        json={"metadata": metadata}
    )
    return response.json()

def delete_file(file_id):
    response = requests.delete(f"{BASE_URL}/files/{file_id}", headers=HEADERS)
    return response.json()

# Usage
files = list_files()
print(f"Total files: {len(files['files'])}")

# Update a file
update_metadata("file_abc123", {
    "category": "legal",
    "tags": ["updated", "reviewed"]
})

# Delete a file
delete_file("file_xyz789")

Managing Knowledge

Overview

List All Files

Endpoint

TypeScript Example

Response Format

Filter Files

Get File Details

Endpoint

Example

Response

Update File Metadata

Endpoint

Example

Delete File

Endpoint

Example

Bulk Operations

Delete Multiple Files

Update Multiple Files

Search Files by Content

Storage Management

Check Storage Usage

Clean Up Old Files

Best Practices

Python Examples

Next Steps