Storage API

The Storage API provides secure file storage and management capabilities for healthcare applications. Upload files, organize them in storage buckets, and integrate them with AI Workers and FHIR resources.

Base URL

https://api.engine.boolbyte.com/api/storage

Create Storage

POST /api/storage/create

Creates a new storage bucket for organizing files.

Using JavaScript SDK:

import { EngineClient } from '@boolbyte/engine';

const client = new EngineClient({ apiKey: 'YOUR_API_KEY' });

const storage = await client.storage.createStorage({
  name: 'patient-documents',
  description: 'Storage for patient documents and medical records'
});

Request Body:

{
  "name": "patient-documents",
  "description": "Storage for patient documents and medical records"
}

Response:

{
  "success": true,
  "message": "Storage created successfully",
  "data": {
    "id": "storage-123",
    "name": "patient-documents",
    "description": "Storage for patient documents and medical records",
    "object": "storage",
    "status": "active",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}

List Storage Buckets

GET /api/storage/list

Retrieves all storage buckets for your team.

Using JavaScript SDK:

const storages = await client.storage.listStorages();

Response:

{
  "success": true,
  "message": "Storage buckets retrieved successfully",
  "data": [
    {
      "id": "storage-123",
      "name": "patient-documents",
      "description": "Storage for patient documents and medical records",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    },
    {
      "id": "storage-456",
      "name": "lab-reports",
      "description": "Storage for laboratory reports and test results",
      "createdAt": "2024-01-15T10:35:00Z",
      "updatedAt": "2024-01-15T10:35:00Z"
    }
  ]
}

List Files in Storage

GET /api/storage/{storageId}/files

Retrieves all files in a specific storage bucket with optional filtering.

Using JavaScript SDK:

const files = await client.storage.listStorageFiles('storage-123', {
  limit: 20,
  category: 'laboratory'
});

Query Parameters:

limit - Number of files to return (default: 20, max: 100)
category - Filter by file category
after - Cursor for pagination (file ID)

Response:

{
  "success": true,
  "message": "Files retrieved successfully",
  "data": [
    {
      "id": "file-abc123",
      "name": "lab-report-patient-123.pdf",
      "originalName": "lab-report.pdf",
      "size": 2048576,
      "contentType": "application/pdf",
      "category": "laboratory",
      "storageId": "storage-123",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ]
}

Upload File to Storage

POST /api/storage/{storageId}/upload

Uploads a file to a specific storage bucket.

Using JavaScript SDK:

const file = await client.storage.uploadFileToStorage(
  'storage-123',
  labReportFile, // File object
  {
    name: 'Lab Report - Patient 123',
    category: 'laboratory',
    metadata: {
      patientId: 'patient-123',
      testDate: '2024-01-15'
    }
  }
);

Request (multipart/form-data):

curl -X POST https://api.engine.boolbyte.com/api/storage/storage-123/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "name=Lab Report - Patient 123" \
  -F "category=laboratory" \
  -F "metadata={\"patientId\":\"patient-123\",\"testDate\":\"2024-01-15\"}"

Response:

{
  "success": true,
  "message": "File uploaded successfully",
  "data": {
    "id": "file-abc123",
    "name": "Lab Report - Patient 123",
    "originalName": "lab-report.pdf",
    "size": 2048576,
    "contentType": "application/pdf",
    "category": "laboratory",
    "storageId": "storage-123",
    "metadata": {
      "patientId": "patient-123",
      "testDate": "2024-01-15"
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

Common Use Cases

Patient Document Storage

// Create storage for patient documents
const patientStorage = await client.storage.createStorage({
  name: 'patient-documents',
  description: 'Storage for patient documents and medical records'
});

// Upload patient documents
const document = await client.storage.uploadFileToStorage(
  patientStorage.data.id,
  patientDocumentFile,
  {
    name: 'Patient Discharge Summary',
    category: 'clinical',
    metadata: {
      patientId: 'patient-123',
      documentType: 'discharge-summary',
      date: '2024-01-15'
    }
  }
);

Laboratory Reports Storage

// Create storage for lab reports
const labStorage = await client.storage.createStorage({
  name: 'laboratory-reports',
  description: 'Storage for laboratory reports and test results'
});

// Upload lab reports
const labReport = await client.storage.uploadFileToStorage(
  labStorage.data.id,
  labReportFile,
  {
    name: 'HbA1c Test Results',
    category: 'laboratory',
    metadata: {
      patientId: 'patient-123',
      testType: 'hba1c',
      testDate: '2024-01-15',
      labId: 'lab-456'
    }
  }
);

Medical Imaging Storage

// Create storage for medical images
const imagingStorage = await client.storage.createStorage({
  name: 'medical-imaging',
  description: 'Storage for medical images and scans'
});

// Upload medical images
const image = await client.storage.uploadFileToStorage(
  imagingStorage.data.id,
  xrayImageFile,
  {
    name: 'Chest X-Ray - Patient 123',
    category: 'imaging',
    metadata: {
      patientId: 'patient-123',
      imageType: 'xray',
      bodyPart: 'chest',
      date: '2024-01-15'
    }
  }
);

Research Data Storage

// Create storage for research data
const researchStorage = await client.storage.createStorage({
  name: 'research-data',
  description: 'Storage for research data and studies'
});

// Upload research files
const researchFile = await client.storage.uploadFileToStorage(
  researchStorage.data.id,
  researchDataFile,
  {
    name: 'Clinical Trial Data - Study 2024',
    category: 'research',
    metadata: {
      studyId: 'study-789',
      dataType: 'clinical-trial',
      version: '1.0'
    }
  }
);

File Categories

Category	Description	Common File Types
`clinical`	General clinical documents	PDF, DOC, TXT
`laboratory`	Lab reports and results	PDF, HL7, CSV
`imaging`	Medical images and scans	DICOM, JPEG, PNG
`administrative`	Forms and admin documents	PDF, DOC, XLS
`research`	Research data and papers	PDF, CSV, JSON
`education`	Training and educational materials	PDF, PPT, VIDEO

Integration with AI Workers

Knowledge Base Integration

// Upload file to storage
const file = await client.storage.uploadFileToStorage(
  'storage-123',
  clinicalGuidelinesFile,
  {
    name: 'Clinical Guidelines 2024',
    category: 'clinical',
    metadata: {
      documentType: 'guidelines',
      version: '2024.1'
    }
  }
);

// Create knowledge base from file
const knowledgeBase = await client.knowledgeBase.createKnowledgeBaseFromFile(
  clinicalGuidelinesFile,
  'Clinical Guidelines 2024',
  'Latest clinical practice guidelines'
);

// Use with AI Worker
const worker = await client.worker.createWorker({
  name: 'clinical-assistant',
  description: 'AI assistant with access to clinical guidelines',
  defaultModelName: 'openai/gpt-4',
  toolConfigs: {
    tools: [
      {
        toolName: 'knowledge_search',
        config: {
          knowledgeBaseId: knowledgeBase.data.id,
          searchThreshold: 0.75,
          maxResults: 5
        }
      }
    ]
  }
});

File Analysis with AI

// Upload file for analysis
const file = await client.storage.uploadFileToStorage(
  'storage-123',
  medicalReportFile,
  {
    name: 'Medical Report Analysis',
    category: 'clinical'
  }
);

// Create AI Worker for document analysis
const analyzerWorker = await client.worker.createWorker({
  name: 'document-analyzer',
  description: 'AI assistant for analyzing medical documents',
  defaultModelName: 'openai/gpt-4',
  instructions: 'Analyze medical documents and extract key information'
});

// Create session and analyze file
const session = await client.session.createSession({
  workerId: analyzerWorker.data.id,
  metadata: {
    fileId: file.data.id,
    analysisType: 'comprehensive'
  }
});

// Send analysis request
const message = await client.session.sendMessage(session.data.id, {
  content: `Please analyze the medical report in file ${file.data.id} and extract key findings, diagnoses, and recommendations.`,
  role: 'user'
});

File Management Best Practices

1. Organize by Category

Create separate storage buckets for different types of files:

// Clinical documents
const clinicalStorage = await client.storage.createStorage({
  name: 'clinical-documents',
  description: 'Clinical documents and reports'
});

// Laboratory data
const labStorage = await client.storage.createStorage({
  name: 'laboratory-data',
  description: 'Laboratory reports and test results'
});

// Research data
const researchStorage = await client.storage.createStorage({
  name: 'research-data',
  description: 'Research studies and data'
});

2. Use Descriptive Metadata

Include relevant metadata for better organization:

const file = await client.storage.uploadFileToStorage(
  'storage-123',
  documentFile,
  {
    name: 'Patient Discharge Summary - John Doe',
    category: 'clinical',
    metadata: {
      patientId: 'patient-123',
      patientName: 'John Doe',
      documentType: 'discharge-summary',
      date: '2024-01-15',
      department: 'cardiology',
      physician: 'dr-smith'
    }
  }
);

3. Implement File Versioning

Upload updated versions with version metadata:

const updatedFile = await client.storage.uploadFileToStorage(
  'storage-123',
  updatedDocumentFile,
  {
    name: 'Patient Discharge Summary - John Doe v2',
    category: 'clinical',
    metadata: {
      patientId: 'patient-123',
      documentType: 'discharge-summary',
      version: '2.0',
      previousVersion: 'file-abc123',
      changes: 'Updated medication list and follow-up instructions'
    }
  }
);

Security Features

Encryption: AES-256 encryption at rest and in transit
Access control: Role-based permissions
Audit logging: Complete access and modification history
HIPAA compliance: Healthcare-grade security controls
Secure URLs: Time-limited access URLs for file downloads

Storage Limits

File size: Up to 50 MB per file
Total storage: Based on subscription plan
Retention: Configurable (30 days to indefinite)
Versions: Automatic versioning with 30-day history

Error Handling

{
  "success": false,
  "message": "File too large",
  "data": null,
  "error": {
    "code": "file_too_large",
    "details": "File size exceeds maximum limit of 50MB"
  }
}

Common Error Codes

storage_not_found: Storage bucket ID doesn't exist
file_too_large: File size exceeds limit
unsupported_file_type: File type is not supported
upload_failed: File upload failed
insufficient_permissions: Missing required permissions

Next Steps

Knowledge Bases - Create knowledge bases from uploaded files
AI Workers - Use files with AI Workers
Health Data Store - Link files to FHIR resources
API Overview - Learn about the complete API

Base URL​

Create Storage​

List Storage Buckets​

List Files in Storage​

Upload File to Storage​

Common Use Cases​

Patient Document Storage​

Laboratory Reports Storage​

Medical Imaging Storage​

Research Data Storage​

File Categories​

Integration with AI Workers​

Knowledge Base Integration​

File Analysis with AI​

File Management Best Practices​

1. Organize by Category​

2. Use Descriptive Metadata​

3. Implement File Versioning​

Security Features​

Storage Limits​

Error Handling​

Common Error Codes​

Next Steps​

Base URL

Create Storage

List Storage Buckets

List Files in Storage

Upload File to Storage

Common Use Cases

Patient Document Storage

Laboratory Reports Storage

Medical Imaging Storage

Research Data Storage

File Categories

Integration with AI Workers

Knowledge Base Integration

File Analysis with AI

File Management Best Practices

1. Organize by Category

2. Use Descriptive Metadata

3. Implement File Versioning

Security Features

Storage Limits

Error Handling

Common Error Codes

Next Steps