Skip to main content

AI API Overview

Create and manage AI Workers, sessions, tasks, knowledge bases, and toolkits through the ByteEngine AI API.

Base URL​

https://api.engine.boolbyte.com

API Components​

The ByteEngine AI API consists of five main components:

Workers​

Create and manage AI Workers with specialized capabilities for healthcare tasks.

  • Create AI Workers with custom instructions and tool configurations
  • Manage worker lifecycle - update, delete, and configure workers
  • Tool integration - connect workers to FHIR servers, knowledge bases, and custom functions
  • Multi-model support - choose the right model for each worker

Quick Example:

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

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

const worker = await client.worker.createWorker({
  name: 'clinical-analyzer',
  defaultModelName: 'medgemma-27b',  // Healthcare model for clinical analysis
  instructions: 'You are a healthcare AI assistant specialized in clinical data analysis.',
  toolConfigs: {
    tools: [
      {
        toolName: 'fhir_access',
        config: { serverId: 'fhir-server-123' }
      }
    ]
  }
});

Sessions & Tasks​

Interact with AI Workers through conversational sessions and task execution.

  • Create sessions for ongoing conversations with workers
  • Execute tasks to send messages and receive AI responses
  • Tool integration - submit tool outputs when workers need external data
  • Task management - cancel, resume, and monitor task execution

Quick Example:

// Create a session
const session = await client.session.createSession({
  workerId: 'worker-456',
  metadata: { patientId: 'patient-123' }
});

// Run a task
const task = await client.task.createTask(session.data.id, {
  instructions: 'Analyze the recent lab results for this patient',
  additionalMessages: [{
    role: 'user',
    content: 'Focus on diabetes-related markers'
  }]
});

Knowledge Bases​

Create searchable knowledge repositories for AI Workers to access during conversations.

  • Upload documents - PDFs, Word files, medical guidelines
  • Search capabilities - semantic search across medical literature
  • Integration - automatically provide context to AI Workers
  • Content management - update and maintain knowledge bases

Quick Example:

// Create knowledge base
const knowledgeBase = await client.knowledgeBase.createKnowledgeBase({
  name: 'clinical-guidelines',
  description: 'Medical treatment protocols and guidelines',
  type: 'text',
  content: 'Medical guidelines content...'
});

// Create knowledge base from file
const fileKB = await client.knowledgeBase.createKnowledgeBaseFromFile(
  medicalGuidelinesFile,
  'Medical Guidelines',
  'Comprehensive medical treatment guidelines'
);

Models​

Access different AI models optimized for various healthcare use cases.

  • GPT-OSS-120b - Powerful general-purpose model for complex reasoning and research
  • MedGemma-27b - Specialized healthcare model for clinical analysis and medical tasks
  • GPT-4 - Advanced model with strong reasoning capabilities
  • GPT-3.5 Turbo - Fast and efficient model for general tasks

Quick Example:

// List available models
const models = await client.model.getModels();

// Create worker with specific model
const worker = await client.worker.createWorker({
  name: 'research-analyst',
  defaultModelName: 'gpt-oss-120b',  // General-purpose model for complex research
  instructions: 'Provide detailed analysis and research insights'
});

// Create healthcare-specific worker
const medicalWorker = await client.worker.createWorker({
  name: 'clinical-analyzer',
  defaultModelName: 'medgemma-27b',  // Healthcare model for clinical tasks
  instructions: 'Provide clinical analysis and medical insights'
});

Toolkits​

Discover and use pre-built tools and toolkits for healthcare AI Workers.

  • Medical Analysis Toolkit - Tools for analyzing medical data and lab results
  • FHIR Integration Toolkit - Tools for interacting with FHIR servers
  • Clinical Documentation Toolkit - Tools for clinical documentation and reporting
  • Patient Communication Toolkit - Tools for patient communication and education

Quick Example:

// Get available toolkits
const toolkits = await client.toolkit.getToolkitsWithTools();

// Get individual tools
const tools = await client.toolkit.getTools();

// Use toolkit in worker configuration
const worker = await client.worker.createWorker({
  name: 'medical-analyzer',
  defaultModelName: 'medgemma-27b',  // Healthcare model for medical analysis
  toolConfigs: {
    toolkits: [
      {
        toolkitName: 'medical-analysis',
        config: {
          includeLabResults: true,
          includeVitalSigns: true
        }
      }
    ]
  }
});

Complete Workflow Example​

Here's how all components work together:

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

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

// 1. Create a knowledge base with medical guidelines
const knowledgeBase = await client.knowledgeBase.createKnowledgeBase({
  name: 'diabetes-guidelines',
  description: 'Diabetes treatment and management protocols',
  type: 'text',
  content: 'Diabetes management guidelines...'
});

// 2. Create an AI Worker with access to tools and toolkits
const worker = await client.worker.createWorker({
  name: 'diabetes-specialist',
  defaultModelName: 'medgemma-27b',  // Healthcare model for clinical analysis
  instructions: 'You are a diabetes specialist AI assistant. Use the clinical guidelines to provide evidence-based recommendations.',
  toolConfigs: {
    tools: [
      {
        toolName: 'fhir_access',
        config: { serverId: 'fhir-server-123' }
      }
    ],
    toolkits: [
      {
        toolkitName: 'medical-analysis',
        config: {
          includeLabResults: true,
          includeVitalSigns: true
        }
      }
    ]
  }
});

// 3. Create a session for patient consultation
const session = await client.session.createSession({
  workerId: worker.data.id,
  metadata: {
    patientId: 'patient-123',
    consultationType: 'diabetes_management'
  }
});

// 4. Execute a task to analyze patient data
const task = await client.task.createTask(session.data.id, {
  instructions: 'Please analyze this patient\'s HbA1c levels and recommend treatment adjustments based on current guidelines.',
  additionalMessages: [{
    role: 'user',
    content: 'Include specific medication dosing recommendations and lifestyle modifications.'
  }],
  model: 'medgemma-27b',  // Healthcare model for clinical analysis
  temperature: 0.7
});

console.log('Analysis complete:', task.data);

Authentication​

All API requests require authentication using your API key:

const client = new EngineClient({
  apiKey: 'YOUR_API_KEY'  // Get from ByteEngine Console
});

Or using the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.engine.boolbyte.com/api/workers

Response Format​

All API responses follow a consistent format:

{
  "success": true,
  "message": "Operation completed successfully",
  "data": { /* Response data */ },
  "firstId": "first-item-id",    // For paginated responses
  "lastId": "last-item-id",      // For paginated responses  
  "hasMore": false               // For paginated responses
}

Error Handling​

Errors are returned in a standardized format:

{
  "success": false,
  "error": {
    "code": "worker_not_found",
    "message": "AI Worker with ID 'worker-456' not found",
    "requestId": "req-12345"
  }
}

Getting Started​

  1. Get your API key from the ByteEngine Console
  2. Create your first worker with basic configuration
  3. Start a session and run your first task
  4. Add knowledge to enhance AI capabilities
  5. Explore toolkits to find pre-built tools
  6. Experiment with models to find the best fit

Next Steps​