Skip to main content

Health Data Store API

The Health Data Store API allows you to create and manage production-ready health data stores with full FHIR R4 support. These servers provide standardized healthcare data storage and can be integrated with AI Workers for intelligent healthcare applications.

FHIR Integration​

ByteEngine's Health Data Stores are built on the FHIR R4 standard, providing:

  • Full FHIR R4 compliance for standardized healthcare data
  • SMART on FHIR support with OAuth2 authorization flows
  • DICOM support for medical imaging pipelines
  • Production-ready infrastructure that scales with your needs

Base URL​

https://api.engine.boolbyte.com

Health Data Store Operations​

Create FHIR Store​

POST /api/fhirserver/create

Creates a new managed health data store instance with FHIR R4 support.

Using JavaScript SDK:

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

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

const server = await client.dataStore.createFhirStore({
  name: 'my-fhir-server',
  region: 'global',
  fhirVersion: 'R4',
  type: 'serverless'
});

Request Body:

{
  "name": "my-fhir-server",
  "region": "global",
  "fhirVersion": "R4",
  "type": "serverless"
}

Response:

{
  "success": true,
  "message": "FHIR server created successfully",
  "data": {
    "id": "fhir-server-123",
    "name": "my-fhir-server",
    "description": null,
    "region": "global",
    "fhirVersion": "R4",
    "status": "running",
    "infrastructure": "serverless",
    "endpoint": "https://fhir-123.byteengine.boolbyte.com",
    "apiKey": "fhir_key_...",
    "teamId": "team-456",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}

List FHIR Stores​

GET /api/fhirserver/list

Retrieves all health data stores for your team.

Using JavaScript SDK:

const servers = await client.dataStore.listFhirStores();

Response:

{
  "success": true,
  "message": "FHIR servers retrieved successfully",
  "data": [
    {
      "id": "fhir-server-123",
      "name": "my-fhir-server",
      "description": null,
      "region": "global",
      "fhirVersion": "R4",
      "status": "running",
      "infrastructure": "serverless",
      "endpoint": "https://fhir-123.byteengine.boolbyte.com",
      "apiKey": "fhir_key_...",
      "teamId": "team-456",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ]
}

Get FHIR Store​

GET /api/fhirserver/{serverId}

Retrieves the configuration and status of a specific health data store.

Using JavaScript SDK:

const server = await client.dataStore.getFhirStore('fhir-server-123');

Response:

{
  "success": true,
  "message": "FHIR server retrieved successfully",
  "data": {
    "id": "fhir-server-123",
    "name": "my-fhir-server",
    "description": null,
    "region": "global",
    "fhirVersion": "R4",
    "status": "running",
    "infrastructure": "serverless",
    "endpoint": "https://fhir-123.byteengine.boolbyte.com",
    "apiKey": "fhir_key_...",
    "teamId": "team-456",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}

Initialize FHIR Client​

Initializes a FHIR client for direct interaction with the health data store.

Using JavaScript SDK:

// Initialize FHIR client
await client.dataStore.initializeFhirStoreClient('fhir-server-123');

// Get the FHIR client instance
const fhirClient = client.dataStore.getFhirStoreClient();

FHIR Operations​

Once you have a health data store, you can use the initialized FHIR client to perform all standard FHIR operations:

Reading Resources​

// Read a specific patient
const patient = await fhirClient.read({
  resourceType: 'Patient',
  id: 'patient-123'
});

// Read an observation
const observation = await fhirClient.read({
  resourceType: 'Observation',
  id: 'obs-456'
});

Searching Resources​

// Search for patients
const patientBundle = await fhirClient.search({
  resourceType: 'Patient',
  searchParams: {
    family: 'Smith',
    gender: 'female'
  }
});

// Search for observations by patient
const observationBundle = await fhirClient.search({
  resourceType: 'Observation',
  searchParams: {
    patient: 'Patient/patient-123',
    category: 'vital-signs'
  }
});

Creating Resources​

// Create a new patient
const newPatient = {
  resourceType: 'Patient',
  name: [{
    family: 'Doe',
    given: ['John']
  }],
  gender: 'male',
  birthDate: '1990-01-01'
};

const createdPatient = await fhirClient.create({
  resource: newPatient
});

// Create an observation
const observation = {
  resourceType: 'Observation',
  status: 'final',
  code: {
    coding: [{
      system: 'http://loinc.org',
      code: '33747-0',
      display: 'Systolic blood pressure'
    }]
  },
  subject: {
    reference: 'Patient/patient-123'
  },
  valueQuantity: {
    value: 120,
    unit: 'mmHg'
  }
};

const createdObservation = await fhirClient.create({
  resource: observation
});

Updating Resources​

// Update a patient
const updatedPatient = await fhirClient.update({
  resource: patient
});

// Update an observation
const updatedObservation = await fhirClient.update({
  resource: observation
});

Deleting Resources​

// Delete a patient
await fhirClient.delete({
  resourceType: 'Patient',
  id: 'patient-123'
});

// Delete an observation
await fhirClient.delete({
  resourceType: 'Observation',
  id: 'obs-456'
});

Server Capabilities​

// Get server capability statement
const capabilities = await fhirClient.capabilityStatement();

Working with Bundles​

// Create a transaction bundle
const bundle = {
  resourceType: 'Bundle',
  type: 'transaction',
  entry: [
    {
      resource: newPatient,
      request: {
        method: 'POST',
        url: 'Patient'
      }
    },
    {
      resource: observation,
      request: {
        method: 'POST',
        url: 'Observation'
      }
    }
  ]
};

const resultBundle = await fhirClient.transaction({
  bundle: bundle
});

Integration with AI Workers​

FHIR-Enabled AI Worker​

// Create AI Worker with FHIR access
const fhirWorker = await client.worker.createWorker({
  name: 'fhir-assistant',
  description: 'AI assistant with FHIR data access',
  defaultModelName: 'openai/gpt-4',
  instructions: 'You are a healthcare AI assistant with access to patient data through FHIR. Help clinicians with patient care and data analysis.',
  toolConfigs: {
    tools: [
      {
        toolName: 'fhir_access',
        config: {
          serverId: 'fhir-server-123',
          permissions: ['read', 'write'],
          resourceTypes: ['Patient', 'Observation', 'Condition', 'MedicationStatement']
        }
      }
    ]
  }
});

// Create session and interact with FHIR data
const session = await client.session.createSession({
  workerId: fhirWorker.data.id,
  metadata: {
    fhirServerId: 'fhir-server-123',
    patientId: 'patient-123'
  }
});

// Send message to analyze patient data
const message = await client.session.sendMessage(session.data.id, {
  content: 'Please analyze the recent lab results for patient-123 and provide clinical insights.',
  role: 'user'
});

Clinical Decision Support​

// Create clinical decision support worker
const clinicalWorker = await client.worker.createWorker({
  name: 'clinical-decision-support',
  description: 'AI assistant for clinical decision support',
  defaultModelName: 'openai/gpt-4',
  instructions: 'Provide evidence-based clinical recommendations based on patient data.',
  toolConfigs: {
    tools: [
      {
        toolName: 'fhir_access',
        config: {
          serverId: 'fhir-server-123',
          permissions: ['read'],
          resourceTypes: ['Patient', 'Observation', 'Condition', 'MedicationStatement', 'AllergyIntolerance']
        }
      }
    ]
  }
});

Common Use Cases​

Patient Data Management​

// Create health data store for patient data
const patientServer = await client.dataStore.createFhirStore({
  name: 'patient-data-server',
  region: 'global',
  fhirVersion: 'R4',
  type: 'serverless'
});

// Initialize client
await client.dataStore.initializeFhirStoreClient(patientServer.data.id);
const fhirClient = client.dataStore.getFhirStoreClient();

// Create patient
const patient = await fhirClient.create({
  resource: {
    resourceType: 'Patient',
    name: [{
      family: 'Smith',
      given: ['Jane']
    }],
    gender: 'female',
    birthDate: '1985-03-15',
    address: [{
      line: ['123 Main St'],
      city: 'Boston',
      state: 'MA',
      postalCode: '02101'
    }]
  }
});

Laboratory Results Management​

// Create lab result observation
const labResult = await fhirClient.create({
  resource: {
    resourceType: 'Observation',
    status: 'final',
    code: {
      coding: [{
        system: 'http://loinc.org',
        code: '33747-0',
        display: 'Glucose [Mass/volume] in Blood'
      }]
    },
    subject: {
      reference: 'Patient/patient-123'
    },
    valueQuantity: {
      value: 145,
      unit: 'mg/dL'
    },
    referenceRange: [{
      low: {
        value: 70,
        unit: 'mg/dL'
      },
      high: {
        value: 100,
        unit: 'mg/dL'
      }
    }]
  }
});

Medication Management​

// Create medication statement
const medication = await fhirClient.create({
  resource: {
    resourceType: 'MedicationStatement',
    status: 'active',
    medicationCodeableConcept: {
      coding: [{
        system: 'http://www.nlm.nih.gov/research/umls/rxnorm',
        code: '860975',
        display: 'Metformin 500 MG Oral Tablet'
      }]
    },
    subject: {
      reference: 'Patient/patient-123'
    },
    dosage: [{
      text: '500mg twice daily with meals'
    }]
  }
});

Server Configuration​

Available Regions​

  • global - Global deployment (Recommended)

FHIR Versions​

  • R4 - FHIR R4 (Supported)

Infrastructure Types​

  • serverless - Serverless deployment (Recommended)
  • dedicated - Dedicated infrastructure for high-volume workloads

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
  • SMART on FHIR: OAuth2 authorization flows
  • API keys: Secure authentication for programmatic access

Error Handling​

{
  "success": false,
  "message": "FHIR server not found",
  "data": null,
  "error": {
    "code": "fhir_server_not_found",
    "details": "FHIR server with ID 'fhir-server-123' not found"
  }
}

Common Error Codes​

  • fhir_server_not_found: Health data store ID doesn't exist
  • invalid_fhir_version: Specified FHIR version is not supported
  • region_not_available: Specified region is not available
  • server_creation_failed: Health data store creation failed
  • insufficient_permissions: Missing required permissions

Next Steps​