swarms/docs/swarms_cloud/mcs_api.md

Medical Coder Swarm API Documentation

Base URL: https://mcs-285321057562.us-central1.run.app

Table of Contents

• Authentication
• Rate Limits
• Endpoints
  • Health Check
  • Run Medical Coder
  • Run Batch Medical Coder
  • Get Patient Data
  • Get All Patients
• Code Examples
• Error Handling

Authentication

Authentication details will be provided by the MCS team. Contact support for API credentials.

Rate Limits

Endpoint	GET Rate Limit Status
GET /rate-limits	Returns current rate limit status for your IP address

Endpoints

Health Check

Check if the API is operational.

Method	Endpoint	Description
GET	/health	Returns 200 OK if service is running

Run Medical Coder

Process a single patient case through the Medical Coder Swarm.

Method	Endpoint	Description
POST	/v1/medical-coder/run	Process a single patient case

Request Body Parameters:

Parameter	Type	Required	Description
patient_id	string	Yes	Unique identifier for the patient
case_description	string	Yes	Medical case details to be processed

Response Schema:

Field	Type	Description
patient_id	string	Patient identifier
case_data	string	Processed case data

Run Batch Medical Coder

Process multiple patient cases in a single request.

Method	Endpoint	Description
POST	/v1/medical-coder/run-batch	Process multiple patient cases

Request Body Parameters:

Parameter	Type	Required	Description
cases	array	Yes	Array of PatientCase objects

Get Patient Data

Retrieve data for a specific patient.

Method	Endpoint	Description
GET	/v1/medical-coder/patient/{patient_id}	Get patient data by ID

Path Parameters:

Parameter	Type	Required	Description
patient_id	string	Yes	Patient identifier

Get All Patients

Retrieve data for all patients.

Method	Endpoint	Description
GET	/v1/medical-coder/patients	Get all patient data

Code Examples

Python

import requests
import json

class MCSClient:
    def __init__(self, base_url="https://mcs.swarms.ai", api_key=None):
        self.base_url = base_url
        self.headers = {
            "Content-Type": "application/json",
            "Authorization": f"Bearer {api_key}" if api_key else None
        }

    def run_medical_coder(self, patient_id, case_description):
        endpoint = f"{self.base_url}/v1/medical-coder/run"
        payload = {
            "patient_id": patient_id,
            "case_description": case_description
        }
        response = requests.post(endpoint, json=payload, headers=self.headers)
        return response.json()

    def run_batch(self, cases):
        endpoint = f"{self.base_url}/v1/medical-coder/run-batch"
        payload = {"cases": cases}
        response = requests.post(endpoint, json=payload, headers=self.headers)
        return response.json()

# Usage example
client = MCSClient(api_key="your_api_key")
result = client.run_medical_coder("P123", "Patient presents with...")

Next.js (TypeScript)

// types.ts
interface PatientCase {
  patient_id: string;
  case_description: string;
}

interface QueryResponse {
  patient_id: string;
  case_data: string;
}

// api.ts
export class MCSApi {
  private baseUrl: string;
  private apiKey: string;

  constructor(apiKey: string, baseUrl = 'https://mcs.swarms.ai') {
    this.baseUrl = baseUrl;
    this.apiKey = apiKey;
  }

  private async fetchWithAuth(endpoint: string, options: RequestInit = {}) {
    const response = await fetch(`${this.baseUrl}${endpoint}`, {
      ...options,
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${this.apiKey}`,
        ...options.headers,
      },
    });
    return response.json();
  }

  async runMedicalCoder(patientCase: PatientCase): Promise<QueryResponse> {
    return this.fetchWithAuth('/v1/medical-coder/run', {
      method: 'POST',
      body: JSON.stringify(patientCase),
    });
  }

  async getPatientData(patientId: string): Promise<QueryResponse> {
    return this.fetchWithAuth(`/v1/medical-coder/patient/${patientId}`);
  }
}

// Usage in component
const mcsApi = new MCSApi(process.env.MCS_API_KEY);

export async function ProcessPatientCase({ patientId, caseDescription }) {
  const result = await mcsApi.runMedicalCoder({
    patient_id: patientId,
    case_description: caseDescription,
  });
  return result;
}

Go

package mcs

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

type MCSClient struct {
    BaseURL string
    APIKey  string
    Client  *http.Client
}

type PatientCase struct {
    PatientID      string `json:"patient_id"`
    CaseDescription string `json:"case_description"`
}

type QueryResponse struct {
    PatientID string `json:"patient_id"`
    CaseData  string `json:"case_data"`
}

func NewMCSClient(apiKey string) *MCSClient {
    return &MCSClient{
        BaseURL: "https://mcs.swarms.ai",
        APIKey:  apiKey,
        Client:  &http.Client{},
    }
}

func (c *MCSClient) RunMedicalCoder(patientCase PatientCase) (*QueryResponse, error) {
    payload, err := json.Marshal(patientCase)
    if err != nil {
        return nil, err
    }

    req, err := http.NewRequest("POST", 
        fmt.Sprintf("%s/v1/medical-coder/run", c.BaseURL),
        bytes.NewBuffer(payload))
    if err != nil {
        return nil, err
    }

    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", c.APIKey))

    resp, err := c.Client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    var result QueryResponse
    if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
        return nil, err
    }

    return &result, nil
}

// Usage example
func main() {
    client := NewMCSClient("your_api_key")
    
    result, err := client.RunMedicalCoder(PatientCase{
        PatientID:      "P123",
        CaseDescription: "Patient presents with...",
    })
    if err != nil {
        panic(err)
    }
    
    fmt.Printf("Result: %+v\n", result)
}

C Sharp

using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

namespace MedicalCoderSwarm
{
    public class PatientCase
    {
        public string PatientId { get; set; }
        public string CaseDescription { get; set; }
    }

    public class QueryResponse
    {
        public string PatientId { get; set; }
        public string CaseData { get; set; }
    }

    public class MCSClient : IDisposable
    {
        private readonly HttpClient _httpClient;
        private readonly string _baseUrl;
        
        public MCSClient(string apiKey, string baseUrl = "https://mcs-285321057562.us-central1.run.app")
        {
            _baseUrl = baseUrl;
            _httpClient = new HttpClient();
            _httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {apiKey}");
            _httpClient.DefaultRequestHeaders.Add("Content-Type", "application/json");
        }

        public async Task<QueryResponse> RunMedicalCoderAsync(string patientId, string caseDescription)
        {
            var payload = new PatientCase
            {
                PatientId = patientId,
                CaseDescription = caseDescription
            };

            var content = new StringContent(
                JsonSerializer.Serialize(payload),
                Encoding.UTF8,
                "application/json"
            );

            var response = await _httpClient.PostAsync(
                $"{_baseUrl}/v1/medical-coder/run",
                content
            );

            response.EnsureSuccessStatusCode();
            
            var responseContent = await response.Content.ReadAsStringAsync();
            return JsonSerializer.Deserialize<QueryResponse>(responseContent);
        }

        public async Task<QueryResponse> GetPatientDataAsync(string patientId)
        {
            var response = await _httpClient.GetAsync(
                $"{_baseUrl}/v1/medical-coder/patient/{patientId}"
            );

            response.EnsureSuccessStatusCode();
            
            var responseContent = await response.Content.ReadAsStringAsync();
            return JsonSerializer.Deserialize<QueryResponse>(responseContent);
        }

        public async Task<bool> HealthCheckAsync()
        {
            var response = await _httpClient.GetAsync($"{_baseUrl}/health");
            return response.IsSuccessStatusCode;
        }

        public void Dispose()
        {
            _httpClient?.Dispose();
        }
    }

    // Example usage
    public class Program
    {
        public static async Task Main()
        {
            try
            {
                using var client = new MCSClient("your_api_key");

                // Check API health
                var isHealthy = await client.HealthCheckAsync();
                Console.WriteLine($"API Health: {(isHealthy ? "Healthy" : "Unhealthy")}");

                // Process a single case
                var result = await client.RunMedicalCoderAsync(
                    "P123",
                    "Patient presents with acute respiratory symptoms..."
                );
                Console.WriteLine($"Processed case for patient {result.PatientId}");
                Console.WriteLine($"Case data: {result.CaseData}");

                // Get patient data
                var patientData = await client.GetPatientDataAsync("P123");
                Console.WriteLine($"Retrieved data for patient {patientData.PatientId}");
            }
            catch (HttpRequestException ex)
            {
                Console.WriteLine($"API request failed: {ex.Message}");
            }
            catch (Exception ex)
            {
                Console.WriteLine($"An error occurred: {ex.Message}");
            }
        }
    }
}

Error Handling

The API uses standard HTTP status codes and returns detailed error messages in JSON format.

Common Status Codes:

Status Code	Description
200	Success
400	Bad Request - Invalid input
401	Unauthorized - Invalid or missing API key
422	Validation Error - Request validation failed
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Error Response Format:

{
  "detail": [
    {
      "loc": ["body", "patient_id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

MCS Python Client Documentation

Installation

pip install mcs

Quick Start

from mcs import MCSClient, PatientCase

# Using context manager (recommended)
with MCSClient() as client:
    # Process a single case
    response = client.run_medical_coder(
        patient_id="P123",
        case_description="Patient presents with acute respiratory symptoms..."
    )
    print(f"Processed case: {response.case_data}")

    # Process multiple cases
    cases = [
        PatientCase("P124", "Case 1 description..."),
        PatientCase("P125", "Case 2 description...")
    ]
    batch_response = client.run_batch(cases)

Client Configuration

Constructor Arguments

Parameter	Type	Required	Default	Description
api_key	str	Yes	-	Authentication API key
base_url	str	No	"https://mcs.swarms.ai"	API base URL
timeout	int	No	30	Request timeout in seconds
max_retries	int	No	3	Maximum retry attempts
logger_name	str	No	"mcs"	Name for the logger instance

Example Configuration

client = MCSClient(
    base_url="https://custom-url.example.com",
    timeout=45,
    max_retries=5,
    logger_name="custom_logger"
)

Data Models

PatientCase

Field	Type	Required	Description
patient_id	str	Yes	Unique identifier for the patient
case_description	str	Yes	Medical case details

QueryResponse

Field	Type	Description
patient_id	str	Patient identifier
case_data	str	Processed case data

Methods

run_medical_coder

Process a single patient case.

def run_medical_coder(
    self,
    patient_id: str,
    case_description: str
) -> QueryResponse:

Arguments:

Parameter	Type	Required	Description
patient_id	str	Yes	Patient identifier
case_description	str	Yes	Case details

Example:

response = client.run_medical_coder(
    patient_id="P123",
    case_description="Patient presents with..."
)
print(response.case_data)

run_batch

Process multiple patient cases in batch.

def run_batch(
    self,
    cases: List[PatientCase]
) -> List[QueryResponse]:

Arguments:

Parameter	Type	Required	Description
cases	List[PatientCase]	Yes	List of patient cases

Example:

cases = [
    PatientCase("P124", "Case 1 description..."),
    PatientCase("P125", "Case 2 description...")
]
responses = client.run_batch(cases)
for response in responses:
    print(f"Patient {response.patient_id}: {response.case_data}")

get_patient_data

Retrieve data for a specific patient.

def get_patient_data(
    self,
    patient_id: str
) -> QueryResponse:

Example:

patient_data = client.get_patient_data("P123")
print(f"Patient data: {patient_data.case_data}")

get_all_patients

Retrieve data for all patients.

def get_all_patients(self) -> List[QueryResponse]:

Example:

all_patients = client.get_all_patients()
for patient in all_patients:
    print(f"Patient {patient.patient_id}: {patient.case_data}")

get_rate_limits

Get current rate limit status.

def get_rate_limits(self) -> Dict[str, Any]:

Example:

rate_limits = client.get_rate_limits()
print(f"Rate limit status: {rate_limits}")

health_check

Check if the API is operational.

def health_check(self) -> bool:

Example:

is_healthy = client.health_check()
print(f"API health: {'Healthy' if is_healthy else 'Unhealthy'}")

Error Handling

Exception Hierarchy

Exception	Description
MCSClientError	Base exception for all client errors
RateLimitError	Raised when API rate limit is exceeded
AuthenticationError	Raised when API authentication fails
ValidationError	Raised when request validation fails

Example Error Handling

from mcs import MCSClient, MCSClientError, RateLimitError

with MCSClient() as client:
    try:
        response = client.run_medical_coder("P123", "Case description...")
    except RateLimitError:
        print("Rate limit exceeded. Please wait before retrying.")
    except MCSClientError as e:
        print(f"An error occurred: {str(e)}")

Advanced Usage

Retry Configuration

The client implements two levels of retry logic:

1. Connection-level retries (using HTTPAdapter):

client = MCSClient(
    ,
    max_retries=5  # Adjusts connection-level retries
)

2. Application-level retries (using tenacity):

from tenacity import retry, stop_after_attempt

@retry(stop=stop_after_attempt(5))
def process_with_custom_retries():
    with MCSClient() as client:
        return client.run_medical_coder("P123", "Case description...")

Batch Processing with Progress Tracking

from tqdm import tqdm

with MCSClient() as client:
    cases = [
        PatientCase(f"P{i}", f"Case description {i}")
        for i in range(100)
    ]
    
    # Process in smaller batches
    batch_size = 10
    results = []
    
    for i in tqdm(range(0, len(cases), batch_size)):
        batch = cases[i:i + batch_size]
        batch_results = client.run_batch(batch)
        results.extend(batch_results)

Best Practices

1. Always use context managers:

   with MCSClient() as client:
       # Your code here
       pass
   

2. Handle rate limits appropriately:

   from time import sleep
   
   def process_with_rate_limit_handling():
       with MCSClient() as client:
           try:
               return client.run_medical_coder("P123", "Case...")
           except RateLimitError:
               sleep(60)  # Wait before retry
               return client.run_medical_coder("P123", "Case...")
   

3. Implement proper logging:

   from loguru import logger
   
   logger.add("mcs.log", rotation="500 MB")
   
   with MCSClient() as client:
       try:
           response = client.run_medical_coder("P123", "Case...")
       except Exception as e:
           logger.exception(f"Error processing case: {str(e)}")
   

4. Monitor API health:

   def ensure_healthy_api():
       with MCSClient() as client:
           if not client.health_check():
               raise SystemExit("API is not healthy")