Best Practices

Patient Context

Use Patient IDs When Possible

Always include a patientId when available to leverage stored context and enable audit logs:

{
  "message": "What are my medication interactions?",
  "patientId": "patient-uuid-123",
  "conversationHistory": []
}

Benefits:

Richer, more accurate responses based on patient history
Complete audit trails for compliance
Automatic context retrieval from stored patient data

Phone Number Lookup

When you don’t have a patient ID, use phone number lookup in ANY format:

{
  "message": "What should I know about my prescription?",
  "phone": "5551234567"  // Any format works!
}

Phone numbers can be in ANY format - the system automatically normalizes them:

+15551234567, 15551234567, 5551234567
(555) 123-4567, 555-123-4567, etc.

All formats work equally well!

Conversation Management

Provide Compact History

Include the last 5-10 conversation turns for continuity without overwhelming the context:

{
  "message": "Any side effects I should watch for?",
  "patientId": "patient-uuid-123",
  "conversationHistory": [
    {"role": "user", "content": "I was prescribed Lisinopril"},
    {"role": "assistant", "content": "Lisinopril is an ACE inhibitor..."},
    {"role": "user", "content": "What's the typical dosage?"},
    {"role": "assistant", "content": "Typical starting dose is 10mg..."}
  ]
}

Conversation History Format

Each conversation entry should include:

role: Either "user" or "assistant"
content: The message content as a string

Performance Optimization

Client-Side Caching

Cache responses for repeated prompts to reduce latency:

const cache = new Map();

async function getCachedResponse(message, patientId) {
  const cacheKey = `${patientId}-${message}`;
  
  if (cache.has(cacheKey)) {
    return cache.get(cacheKey);
  }
  
  const response = await callCuraAPI(message, patientId);
  cache.set(cacheKey, response);
  
  return response;
}

Request Batching

For multiple related questions, consider the conversation flow rather than making separate requests:

// Instead of multiple separate requests
// Better: Structure as a conversation
{
  "message": "I also wanted to ask about exercise restrictions",
  "patientId": "patient-uuid-123",
  "conversationHistory": [
    {"role": "user", "content": "What side effects should I expect from Lisinopril?"},
    {"role": "assistant", "content": "Common side effects include..."}
  ]
}

Error Handling

Implement Robust Error Handling

async function callCuraAPI(message, options = {}) {
  try {
    const response = await fetch(`${baseUrl}/api/cura/chat`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': apiKey
      },
      body: JSON.stringify({
        message,
        ...options
      })
    });

    if (!response.ok) {
      throw new Error(`API Error ${response.status}: ${await response.text()}`);
    }

    const data = await response.json();
    
    if (!data.success) {
      throw new Error(`Cura API Error: ${data.error || 'Unknown error'}`);
    }

    return data.response;
  } catch (error) {
    console.error('Cura API call failed:', error);
    throw error;
  }
}

Handle Network Errors

Implement retry logic for network failures:

async function callWithRetry(apiCall, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await apiCall();
    } catch (error) {
      if (error.message.includes('network') && attempt < maxRetries) {
        const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
}

Data Management

Patient Data Override

Use patientData to provide or override specific patient information:

{
  "message": "What should I know about this medication?",
  "patientId": "patient-uuid-123",
  "patientData": {
    "medications": [
      {
        "name": "Lisinopril",
        "dosage": "10mg",
        "condition": "Hypertension"
      }
    ],
    "allergies": ["Penicillin"],
    "conditions": ["Hypertension", "Type 2 Diabetes"]
  }
}

Provide Updated Patient Data

Use the patientData parameter to provide the most current information:

// Include updated medications in chat request
await fetch(`${baseUrl}/api/cura/chat`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': apiKey
  },
  body: JSON.stringify({
    message: 'What should I know about my new prescription?',
    patientId: patientId,
    patientData: {
      medications: updatedMedications
    }
  })
});

Security Considerations

API Key Management

Store API keys in environment variables
Use different keys for different environments
Rotate keys regularly
Never expose keys in client-side code

Data Privacy

Only send necessary patient information
Implement proper access controls
Log API usage for audit purposes
Follow healthcare data compliance requirements (HIPAA, etc.)

Monitoring and Logging

Track API Usage

Monitor your API usage patterns:

const apiMetrics = {
  totalCalls: 0,
  errorRate: 0,
  averageResponseTime: 0
};

async function monitoredAPICall(message, options) {
  const startTime = Date.now();
  apiMetrics.totalCalls++;
  
  try {
    const result = await callCuraAPI(message, options);
    const responseTime = Date.now() - startTime;
    apiMetrics.averageResponseTime = 
      (apiMetrics.averageResponseTime + responseTime) / 2;
    return result;
  } catch (error) {
    apiMetrics.errorRate = 
      (apiMetrics.errorRate * (apiMetrics.totalCalls - 1) + 1) / apiMetrics.totalCalls;
    throw error;
  }
}

Log Important Events

// Log successful interactions
console.log('Cura API Response', {
  patientId,
  messageLength: message.length,
  responseTime: Date.now() - startTime,
  timestamp: new Date().toISOString()
});

Be careful not to log sensitive patient information in your application logs.

Getting Started

Core Concepts

Best Practices

Patient Context

Use Patient IDs When Possible

Phone Number Lookup

Conversation Management

Provide Compact History

Conversation History Format

Performance Optimization

Client-Side Caching

Request Batching

Error Handling

Implement Robust Error Handling

Handle Network Errors

Data Management

Patient Data Override

Provide Updated Patient Data

Security Considerations

API Key Management

Data Privacy

Monitoring and Logging

Track API Usage

Log Important Events

​Patient Context

​Use Patient IDs When Possible

​Phone Number Lookup

​Conversation Management

​Provide Compact History

​Conversation History Format

​Performance Optimization

​Client-Side Caching

​Request Batching

​Error Handling

​Implement Robust Error Handling

​Handle Network Errors

​Data Management

​Patient Data Override

​Provide Updated Patient Data

​Security Considerations

​API Key Management

​Data Privacy

​Monitoring and Logging

​Track API Usage

​Log Important Events

Patient Context

Use Patient IDs When Possible

Phone Number Lookup

Conversation Management

Provide Compact History

Conversation History Format

Performance Optimization

Client-Side Caching

Request Batching

Error Handling

Implement Robust Error Handling

Handle Network Errors

Data Management

Patient Data Override

Provide Updated Patient Data

Security Considerations

API Key Management

Data Privacy

Monitoring and Logging

Track API Usage

Log Important Events