AI Casesheet REST API Documentation

Version: 1.0.0
Last Updated: November 19, 2025

Overview
Authentication
Patient Management
Visit Management
Casesheet Creation - Text Input
Casesheet Creation - Voice Input
Autopopulation Logic
Response Schemas
Error Handling
Rate Limiting
Example Workflows
Best Practices

Overview

The AI Casesheet API is a REST-based service that enables external systems to integrate AI-powered electronic health record (EHR) casesheet generation capabilities. The service supports multiple input modalities (text and voice) and automatically populates casesheets using data from previous medical records within the same patient visit.

Key Features

Multi-modal Input: Support for both text/JSON and voice (audio file) inputs
AI-Powered Generation: Automatically structures unstructured medical notes into standardized casesheet formats
Smart Autopopulation: Intelligently pulls relevant data from previous casesheets within the same visit
Multiple Casesheet Types: Support for OPD, IPD, and specialized medical documentation
Voice Transcription: Automatic speech-to-text conversion using state-of-the-art models
Structured Output: Returns fully structured JSON responses following medical documentation standards

Base URL

Production: https://api.axone.one/api/v1
Staging: https://staging-api.axone.one/api/v1

API Versioning

This API uses URL path versioning. The current version is v1, included in all endpoint paths:

/api/v1/{resource}

Future versions will be released as /api/v2/, /api/v3/, etc. Previous versions will be maintained for backward compatibility.

General Request Format

Content-Type: application/json (for text endpoints), multipart/form-data (for voice endpoints)
Accept: application/json
Authorization: Bearer {access_token} (required for all endpoints except /auth/token)

General Response Format

All successful responses return JSON with appropriate HTTP status codes:

json
{
  "success": true,
  "data": {
    /* response data */
  },
  "message": "Operation completed successfully"
}

Error responses follow a consistent format (see Error Handling).

Authentication

The API uses OAuth 2.0 Client Credentials Grant for service-to-service authentication.

Obtain Access Token

Endpoint: POST /api/v1/auth/token

Request Headers:

Content-Type: application/x-www-form-urlencoded

Request Body:

grant_type=client_credentials
client_id={your_client_id}
client_secret={your_client_secret}
scope=casesheet.read casesheet.write patient.read patient.write

Response:

json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "casesheet.read casesheet.write patient.read patient.write"
}

Response Fields:

access_token (string): JWT token to use in subsequent API requests
token_type (string): Always "Bearer"
expires_in (integer): Token lifetime in seconds (typically 3600 = 1 hour)
scope (string): Space-separated list of granted permissions

Using the Access Token

Include the access token in the Authorization header for all subsequent requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Token Expiration

When a token expires, you'll receive a 401 Unauthorized response. Request a new token using the same process above. Tokens are valid for 1 hour.

Patient Management

Create Patient

Endpoint: POST /api/v1/patients

Description: Creates a new patient record in the system.

Request Headers:

Authorization: Bearer {access_token}
Content-Type: application/json

Request Body:

json
{
  "salutation": "Dr.",
  "name": "John Doe",
  "dob": "1985-06-15T00:00:00Z",
  "age": 38,
  "phoneNumber": "+1234567890",
  "gender": "male",
  "occupation": "Engineer",
  "address": {
    "street": "123 Main St",
    "city": "New York",
    "state": "NY",
    "zipCode": "10001",
    "country": "USA"
  },
  "emergencyContact": {
    "name": "Jane Doe",
    "relationship": "Spouse",
    "phoneNumber": "+1234567891"
  },
  "insurance": {
    "provider": "Blue Cross",
    "policyNumber": "BC123456789"
  }
}

Required Fields:

name (string): Patient's full name
age (integer): Patient's age
gender (string): One of: "male", "female", "other"
phoneNumber (string): Contact phone number

Optional Fields:

salutation (string): Title (Mr., Mrs., Dr., etc.)
dob (string): Date of birth in ISO 8601 format
occupation (string): Patient's occupation
address (object): Address details
emergencyContact (object): Emergency contact information
insurance (object): Insurance details

Response (201 Created):

json
{
  "success": true,
  "data": {
    "patientId": "clx1234567890abcdef",
    "name": "John Doe",
    "age": 38,
    "gender": "male",
    "phoneNumber": "+1234567890",
    "createdAt": "2025-11-19T10:30:00Z"
  },
  "message": "Patient created successfully"
}

Search Patients

Endpoint: GET /api/v1/patients/search

Description: Search for existing patients by name, phone number, or other criteria.

Request Headers:

Authorization: Bearer {access_token}

Query Parameters:

name (string, optional): Patient name (partial match supported)
phoneNumber (string, optional): Phone number (exact match)
age (integer, optional): Patient age
gender (string, optional): Gender filter
limit (integer, optional): Maximum results to return (default: 50, max: 100)
offset (integer, optional): Pagination offset (default: 0)

Example Request:

GET /api/v1/patients/search?name=John&limit=10

Response (200 OK):

json
{
  "success": true,
  "data": {
    "patients": [
      {
        "patientId": "clx1234567890abcdef",
        "name": "John Doe",
        "age": 38,
        "gender": "male",
        "phoneNumber": "+1234567890",
        "createdAt": "2025-11-19T10:30:00Z"
      }
    ],
    "total": 1,
    "limit": 10,
    "offset": 0
  },
  "message": "Search completed successfully"
}

Visit Management

Create Visit

Endpoint: POST /api/v1/visits

Description: Creates a new visit/timespan for a patient. This visitId is required for all casesheet generation requests and links all documents created during the visit.

Request Headers:

Authorization: Bearer {access_token}
Content-Type: application/json

Request Body:

json
{
  "patientId": "clx1234567890abcdef",
  "visitType": "IPD",
  "appointmentTime": "2025-11-19T14:00:00Z",
  "department": "Cardiology",
  "practitioner": "Dr. Smith",
  "patientStatus": "admitted"
}

Required Fields:

patientId (string): ID of the patient for this visit

Optional Fields:

visitType (string): "OPD" (Outpatient) or "IPD" (Inpatient) - default: "OPD"
appointmentTime (string): Visit date/time in ISO 8601 format
department (string): Department name
practitioner (string): Treating practitioner name
patientStatus (string): Current status (e.g., "admitted", "discharged", "in-progress")

Response (201 Created):

json
{
  "success": true,
  "data": {
    "visitId": "clx9876543210fedcba",
    "patientId": "clx1234567890abcdef",
    "visitType": "IPD",
    "appointmentTime": "2025-11-19T14:00:00Z",
    "patientStatus": "admitted",
    "createdAt": "2025-11-19T11:00:00Z"
  },
  "message": "Visit created successfully"
}

Get Visit Details

Endpoint: GET /api/v1/visits/{visitId}

Description: Retrieves details of a specific visit and all associated casesheets.

Request Headers:

Authorization: Bearer {access_token}

Response (200 OK):

json
{
  "success": true,
  "data": {
    "visitId": "clx9876543210fedcba",
    "patientId": "clx1234567890abcdef",
    "visitType": "IPD",
    "appointmentTime": "2025-11-19T14:00:00Z",
    "patientStatus": "admitted",
    "casesheets": {
      "admissionNotes": {
        /* casesheet data */
      },
      "progressRecords": [
        /* array of progress records */
      ],
      "doctorsOrders": [
        /* array of orders */
      ]
    },
    "createdAt": "2025-11-19T11:00:00Z",
    "updatedAt": "2025-11-19T15:30:00Z"
  },
  "message": "Visit retrieved successfully"
}

Casesheet Creation - Text Input

Text-based casesheet generation accepts rough, unstructured text or partial JSON and uses AI to extract and structure the information into a complete, standardized casesheet format.

General Text Endpoint Format

Endpoint Pattern: POST /api/v1/casesheets/{type}/text

Request Headers:

Authorization: Bearer {access_token}
Content-Type: application/json

General Request Body:

json
{
  "visitId": "clx9876543210fedcba",
  "notes": "Patient complains of chest pain for 2 days, radiating to left arm. BP 140/90, HR 95. No prior cardiac history. Family history of CAD. Non-smoker."
}

Request Fields:

visitId (string, required): The visit ID for this casesheet
notes (string, required): Rough medical notes or partial structured data
autopopulate (boolean, optional): Whether to include autopopulated data from previous casesheets (default: true)

Supported Casesheet Types

1. OPD Casesheet

Endpoint: POST /api/v1/casesheets/opd-casesheet/text

Description: Generates an Outpatient Department casesheet.

Example Notes Input:

"Patient presents with fever for 3 days, temperature 102F, headache, body ache.
No cough or cold. Medical history: Diabetes for 5 years on Metformin.
Examination: Throat congestion, no lymphadenopathy.
Assessment: Viral fever.
Plan: Paracetamol 500mg TDS, rest, fluids."

Response (200 OK):

json
{
  "success": true,
  "data": {
    "casesheetId": "clxabc123",
    "visitId": "clx9876543210fedcba",
    "chiefComplaints": "Fever for 3 days",
    "historyOfPresentIllness": "Patient presents with fever for 3 days, temperature 102F, accompanied by headache and body ache. No cough or cold symptoms.",
    "pastHistory": "Diabetes mellitus for 5 years, on Metformin",
    "examination": "Throat congestion noted. No lymphadenopathy.",
    "provisionalDiagnosis": ["Viral fever"],
    "finalDiagnosis": "Viral fever",
    "prescription": [
      {
        "drug": "Paracetamol",
        "strength": "500mg",
        "frequency": "TDS",
        "route": "Oral",
        "duration": "3 days",
        "instructions": "After meals"
      }
    ],
    "advice": "Rest, increase fluid intake",
    "createdAt": "2025-11-19T12:00:00Z"
  },
  "message": "OPD casesheet generated successfully"
}

2. Admission Notes

Endpoint: POST /api/v1/casesheets/admission-notes/text

Description: Generates IPD admission notes. Automatically populates from previous OPD casesheet if available.

Autopopulation Source: OPD casesheet examination and clinical notes

Example Notes Input:

"Admitted for acute coronary syndrome. Patient stable, pain controlled.
Plan: Monitoring in ICU, cardiac markers, ECG monitoring.
Surgery planned for tomorrow - CABG."

Response (200 OK):

json
{
  "success": true,
  "data": {
    "casesheetId": "clxdef456",
    "visitId": "clx9876543210fedcba",
    "finalDiagnosis": "Acute coronary syndrome",
    "provisionalDiagnosis": ["Acute coronary syndrome", "Unstable angina"],
    "dateOfSurgery": "2025-11-20",
    "dateOfPlannedDischarge": "2025-11-25",
    "chiefComplaints": "Chest pain radiating to left arm for 2 days",
    "historyOfPresentIllness": "Patient presented with chest pain...",
    "painAssessment": "Pain score 7/10, controlled with medication",
    "allergies": "No known drug allergies",
    "pastHistory": "Hypertension for 10 years",
    "surgicalHistory": "None",
    "obstetricAndGynecologyHistory": "",
    "currentMedications": "Aspirin 75mg OD, Atorvastatin 40mg OD",
    "familyHistory": "Father had MI at age 55",
    "personalHistory": "Non-smoker, occasional alcohol",
    "socialHistory": "Lives with family, works as engineer",
    "generalExamination": "Patient conscious, oriented. Vitals stable.",
    "systemicExamination": "CVS: S1 S2 heard, no murmurs. RS: Clear bilateral air entry.",
    "procedure": "CABG planned",
    "carePlan": "ICU monitoring, cardiac markers, continuous ECG",
    "createdAt": "2025-11-19T13:00:00Z"
  },
  "message": "Admission notes generated successfully"
}

3. Progress Records

Endpoint: POST /api/v1/casesheets/progress-records/text

Description: Generates a progress record entry documenting patient's condition during hospital stay.

Example Notes Input:

"Day 2 post-op. Patient doing well. Pain managed. Ambulated today.
Vitals stable. Wound clean and dry. Continue current medications.
Plan discharge in 2 days."

Response (200 OK):

json
{
  "success": true,
  "data": {
    "casesheetId": "clxghi789",
    "visitId": "clx9876543210fedcba",
    "diagnosis": "Post CABG - Day 2",
    "provisionalDiagnosis": [],
    "currentPatientCondition": "Patient doing well, pain managed, ambulated successfully",
    "procedure": "Post-operative care",
    "generalExamination": "Patient conscious, alert, ambulating",
    "systemicExamination": "Wound clean and dry, no signs of infection",
    "plan": "Continue current medications, plan discharge in 2 days",
    "dietAndNutrition": "Regular diet as tolerated",
    "createdAt": "2025-11-19T14:00:00Z"
  },
  "message": "Progress record generated successfully"
}

4. Doctors Orders

Endpoint: POST /api/v1/casesheets/doctors-orders/text

Description: Generates doctor's orders including prescriptions and investigations.

Example Notes Input:

"Continue Aspirin 75mg OD, Clopidogrel 75mg OD.
Add Metoprolol 25mg BD.
Order: CBC, Lipid profile, ECG tomorrow morning.
NPO after midnight for procedure."

Response (200 OK):

json
{
  "success": true,
  "data": {
    "casesheetId": "clxjkl012",
    "visitId": "clx9876543210fedcba",
    "diagnosis": "Post CABG",
    "orders": "NPO after midnight for procedure",
    "prescription": [
      {
        "route": "Oral",
        "form": "Tablet",
        "drug": "Aspirin",
        "genericName": "Acetylsalicylic acid",
        "frequency": "OD",
        "strength": "75mg",
        "duration": "30 days",
        "instructions": "After meals"
      },
      {
        "route": "Oral",
        "form": "Tablet",
        "drug": "Clopidogrel",
        "genericName": "Clopidogrel",
        "frequency": "OD",
        "strength": "75mg",
        "duration": "30 days",
        "instructions": "After meals"
      },
      {
        "route": "Oral",
        "form": "Tablet",
        "drug": "Metoprolol",
        "genericName": "Metoprolol",
        "frequency": "BD",
        "strength": "25mg",
        "duration": "30 days",
        "instructions": "With meals"
      }
    ],
    "investigations": [
      {
        "name": "CBC",
        "frequency": "Once",
        "remarks": "Fasting",
        "time": "Morning",
        "orderDate": "2025-11-20T00:00:00Z"
      },
      {
        "name": "Lipid profile",
        "frequency": "Once",
        "remarks": "Fasting",
        "time": "Morning",
        "orderDate": "2025-11-20T00:00:00Z"
      },
      {
        "name": "ECG",
        "frequency": "Once",
        "remarks": "",
        "time": "Morning",
        "orderDate": "2025-11-20T00:00:00Z"
      }
    ],
    "createdAt": "2025-11-19T15:00:00Z"
  },
  "message": "Doctor's orders generated successfully"
}

5. Cross Referral

Endpoint: POST /api/v1/casesheets/cross-referral/text

Description: Generates a consultation referral to another department or specialist.

Autopopulation Source: Admission notes history + Current medications from doctor's orders

Example Notes Input:

"Refer to Nephrology for rising creatinine (2.5 mg/dL).
Patient post-CABG, on multiple medications.
Please evaluate for acute kidney injury and medication adjustment."

Response (200 OK):

json
{
  "success": true,
  "data": {
    "casesheetId": "clxmno345",
    "visitId": "clx9876543210fedcba",
    "practitionerId": "clxpract001",
    "practitionerName": "Dr. Johnson",
    "departmentId": "clxdept001",
    "primaryReasonForReferral": "Rising creatinine - evaluate for AKI",
    "reasonForReferral": "Post-CABG patient with rising creatinine (2.5 mg/dL). Request evaluation for acute kidney injury and medication adjustment recommendations.",
    "medicalAndSurgicalHistory": "Patient with history of CAD, underwent CABG. Hypertension for 10 years. No prior renal issues.",
    "clinicalFindings": "Creatinine elevated at 2.5 mg/dL",
    "laboratoryDiagnostic": "Serum creatinine: 2.5 mg/dL",
    "imagingStudies": "",
    "assessment": "Post-operative AKI likely",
    "procedurePerformed": "CABG",
    "recommendation": "Evaluate for medication-induced renal injury, adjust doses as needed",
    "consultationDetails": "Urgent nephrology consultation requested",
    "createdAt": "2025-11-19T16:00:00Z"
  },
  "message": "Cross referral generated successfully"
}

6. Doctors Handover Notes

Endpoint: POST /api/v1/casesheets/doctors-handover-notes/text

Description: Generates handover notes when transferring patient care.

Autopopulation Source: Admission notes + Vitals + Progress records + Cross referrals

Example Notes Input:

"Transferring to step-down unit. Patient stable post-CABG day 3.
All vitals within normal limits. Continue cardiac medications.
Watch for any signs of infection or arrhythmia."

Response (200 OK):

json
{
  "success": true,
  "data": {
    "casesheetId": "clxpqr678",
    "visitId": "clx9876543210fedcba",
    "practitionerId": "clxpract002",
    "departmentId": "clxdept002",
    "reasonForTransfer": "Transfer to step-down unit for continued recovery",
    "currentDiagnosis": "Post-CABG day 3",
    "historyOfThePatient": "58-year-old male with CAD, underwent CABG 3 days ago...",
    "currentClinicalStatus": "Patient stable, vitals within normal limits. BP 120/80, HR 75, SpO2 98% on room air.",
    "allergies": "No known drug allergies",
    "recentSignificantEvents": "CABG performed 3 days ago, uneventful recovery",
    "currentTreatmentPlan": "Continue Aspirin 75mg OD, Clopidogrel 75mg OD, Metoprolol 25mg BD",
    "resuscitationAndCriticalCare": "No active resuscitation required, stable condition",
    "laboratoryResults": "Recent labs within normal limits",
    "imagingStudies": "Post-op chest X-ray clear",
    "anyCrossReferralSought": "Nephrology consulted for elevated creatinine - resolved",
    "handoverDetails": "Watch for signs of infection, arrhythmia, or bleeding. Continue wound care.",
    "createdAt": "2025-11-19T17:00:00Z"
  },
  "message": "Doctor's handover notes generated successfully"
}

7. Operation Theater Notes

Endpoint: POST /api/v1/casesheets/operation-theater-notes/text

Description: Generates operation theater documentation.

Autopopulation Source: Progress records diagnosis + Admission notes + Current medications

Example Notes Input:

"CABG performed. 4 vessel grafts - LIMA to LAD, SVG to OM, Diagonal, RCA.
Procedure uneventful. Total bypass time 95 minutes. Patient stable.
Transferred to ICU in stable condition."

Response (200 OK):

json
{
  "success": true,
  "data": {
    "casesheetId": "clxstu901",
    "visitId": "clx9876543210fedcba",
    "surgeon": "Dr. Smith",
    "assistantSurgeon": "Dr. Williams",
    "anesthesiologist": "Dr. Brown",
    "diagnosis": "Coronary artery disease",
    "indicationForSurgery": "Triple vessel disease with unstable angina",
    "preoperativeAssessment": "Patient optimized for surgery, cardiac markers stable",
    "consent": "Written informed consent obtained",
    "labResults": "All pre-op labs within acceptable range",
    "imagingStudies": "Coronary angiography showing triple vessel disease",
    "intraoperativeDetails": "CABG performed with 4 vessel grafts: LIMA to LAD, SVG to OM, Diagonal, and RCA. Cardiopulmonary bypass time: 95 minutes. Cross-clamp time: 68 minutes. Procedure uneventful.",
    "immediatePostoperativeCondition": "Patient stable, transferred to ICU",
    "postoperativeOrders": "Monitor vitals, ECG, drain output. Continue ventilator support.",
    "instructionsForRecovery": "ICU monitoring for 24-48 hours, gradual weaning from ventilator",
    "createdAt": "2025-11-19T18:00:00Z"
  },
  "message": "Operation theater notes generated successfully"
}

8. Discharge Summary

Endpoint: POST /api/v1/casesheets/discharge-summary/text

Description: Generates comprehensive discharge summary.

Autopopulation Source: All visit data (admission notes, progress records, procedures, medications, investigations)

Example Notes Input:

"Patient discharged in stable condition. Post-CABG recovery uneventful.
Wound healing well. Continue medications as prescribed.
Follow-up in cardiology OPD after 1 week."

Response (200 OK):

json
{
  "success": true,
  "data": {
    "casesheetId": "clxvwx234",
    "visitId": "clx9876543210fedcba",
    "finalDiagnosis": "Coronary artery disease - Post CABG",
    "reasonForAdmission": "Acute coronary syndrome",
    "historyOfPresentIllness": "Patient presented with chest pain radiating to left arm...",
    "pastHistory": "Hypertension for 10 years, Diabetes mellitus type 2",
    "familyHistory": "Father had MI at age 55",
    "treatmentHistory": "On antihypertensives and oral hypoglycemics",
    "personalHistory": "Non-smoker, occasional alcohol",
    "socialHistory": "Lives with family, engineer",
    "obstetricAndGynecologyHistory": "",
    "generalExamination": "Patient conscious, alert, vitals stable",
    "systemicExamination": "CVS: S1 S2 heard, wound healing well. RS: Clear breath sounds bilaterally",
    "procedure": "1. 2025-11-19 - CABG (4 vessel grafts)\n2. 2025-11-20 - Chest tube removal",
    "inHospitalCourse": "Patient underwent successful CABG on 2025-11-19. Post-operative recovery was uneventful. Patient was extubated on post-op day 1. Mobilized from post-op day 2. Chest tubes removed on day 3. No complications noted. Wound healing satisfactorily.",
    "administeredMedications": "Aspirin 75mg OD, Clopidogrel 75mg OD, Metoprolol 25mg BD, Atorvastatin 40mg OD",
    "investigationsOrdered": [
      { "name": "CBC", "result": "Within normal limits" },
      { "name": "Lipid profile", "result": "LDL 95 mg/dL" },
      { "name": "ECG", "result": "Sinus rhythm, no acute changes" }
    ],
    "patientConditionAtDischarge": "Stable, wound healing well",
    "generalExaminationAtDischarge": "Afebrile, vitals stable",
    "systemicExaminationAtDischarge": "Sternotomy wound clean and dry, no discharge",
    "advice": "Continue medications, wound care, gradual increase in activity, avoid heavy lifting for 6 weeks",
    "dischargeType": "Routine",
    "followUp": [
      {
        "practitionerId": "clxpract001",
        "date": "2025-11-26T10:00:00Z",
        "remarks": "Cardiology OPD - wound check and medication review"
      }
    ],
    "prescription": [
      {
        "route": "Oral",
        "form": "Tablet",
        "drug": "Aspirin",
        "strength": "75mg",
        "frequency": "OD",
        "duration": "Lifelong",
        "instructions": "After breakfast"
      },
      {
        "route": "Oral",
        "form": "Tablet",
        "drug": "Clopidogrel",
        "strength": "75mg",
        "frequency": "OD",
        "duration": "1 year",
        "instructions": "After breakfast"
      },
      {
        "route": "Oral",
        "form": "Tablet",
        "drug": "Metoprolol",
        "strength": "25mg",
        "frequency": "BD",
        "duration": "Lifelong",
        "instructions": "With meals"
      },
      {
        "route": "Oral",
        "form": "Tablet",
        "drug": "Atorvastatin",
        "strength": "40mg",
        "frequency": "OD",
        "duration": "Lifelong",
        "instructions": "At bedtime"
      }
    ],
    "lims": [],
    "pacsris": [],
    "createdAt": "2025-11-19T19:00:00Z"
  },
  "message": "Discharge summary generated successfully"
}

9. Vitals

Endpoint: POST /api/v1/casesheets/vitals/text

Description: Records patient vital signs.

Example Notes Input:

"BP 120/80, HR 75, Temp 98.6F, SpO2 98%, RR 16"

Response (200 OK):

json
{
  "success": true,
  "data": {
    "casesheetId": "clxyz567",
    "visitId": "clx9876543210fedcba",
    "vitals": [
      {
        "vital": "bloodPressure",
        "unit": "mmHg",
        "value": "120/80"
      },
      {
        "vital": "pulseRate",
        "unit": "bpm",
        "value": "75"
      },
      {
        "vital": "temperature",
        "unit": "°F",
        "value": "98.6"
      },
      {
        "vital": "spo2",
        "unit": "%",
        "value": "98"
      },
      {
        "vital": "respiratoryRate",
        "unit": "breaths/min",
        "value": "16"
      }
    ],
    "createdAt": "2025-11-19T20:00:00Z"
  },
  "message": "Vitals recorded successfully"
}

Casesheet Creation - Voice Input

Voice-based casesheet generation accepts audio files, transcribes them using AI speech-to-text, and then structures the content into standardized casesheet formats.

General Voice Endpoint Format

Endpoint Pattern: POST /api/v1/casesheets/{type}/voice

Request Headers:

Authorization: Bearer {access_token}
Content-Type: multipart/form-data

Request Body (multipart/form-data):

visitId (string, required): The visit ID for this casesheet
audioFile (file, required): Audio file containing the medical dictation
autopopulate (boolean, optional): Whether to include autopopulated data (default: true)

Supported Audio Formats:

MP3 (.mp3)
WAV (.wav)
M4A (.m4a)
Maximum file size: 25 MB
Maximum duration: 10 minutes

Voice Processing Flow

Audio File → Transcription (Whisper AI) → Text Processing (GPT-4) → Structured JSON

The voice endpoints perform two AI operations:

Speech-to-Text: Converts audio to text using OpenAI Whisper
Text-to-Structure: Extracts structured data from transcript using GPT-4

Example Voice Request

bash
curl -X POST https://api.axone.one/api/v1/casesheets/admission-notes/voice \
  -H "Authorization: Bearer {access_token}" \
  -F "visitId=clx9876543210fedcba" \
  -F "audioFile=@/path/to/admission-notes.mp3" \
  -F "autopopulate=true"

Supported Voice Casesheet Types

All text-based casesheet types support voice input. Use the same type names:

POST /api/v1/casesheets/opd-casesheet/voice
POST /api/v1/casesheets/admission-notes/voice
POST /api/v1/casesheets/progress-records/voice
POST /api/v1/casesheets/doctors-orders/voice
POST /api/v1/casesheets/cross-referral/voice
POST /api/v1/casesheets/doctors-handover-notes/voice
POST /api/v1/casesheets/operation-theater-notes/voice
POST /api/v1/casesheets/discharge-summary/voice
POST /api/v1/casesheets/vitals/voice

Voice Response Format

Voice endpoints return the same JSON structure as text endpoints, with an additional field:

Response (200 OK):

json
{
  "success": true,
  "data": {
    "transcript": "Patient complains of chest pain for two days...",
    "casesheetId": "clxabc123",
    "visitId": "clx9876543210fedcba"
    /* ... rest of casesheet data ... */
  },
  "message": "Casesheet generated from voice successfully",
  "processingTime": {
    "transcription": "3.2s",
    "structuring": "2.8s",
    "total": "6.0s"
  }
}

Additional Response Fields:

transcript (string): The transcribed text from the audio
processingTime (object): Breakdown of processing times for transparency

Voice Input Best Practices

Audio Quality:
- Use clear, noise-free recordings
- Speak clearly and at moderate pace
- Avoid background noise and interruptions
Medical Terminology:
- Spell out ambiguous terms if necessary
- Use standard medical abbreviations
- Specify dosages clearly (e.g., "seventy-five milligrams")
Structure:
- Follow a logical flow in dictation
- Separate different sections clearly
- State section names when applicable (e.g., "Chief complaints: ...")
File Size:
- Keep recordings under 10 minutes
- For longer dictations, split into multiple requests
- Compressed formats (MP3, M4A) recommended for faster upload

Autopopulation Logic

The API intelligently populates casesheet fields using data from previous casesheets within the same visit. This reduces redundant data entry and ensures consistency across documents.

Autopopulation Flow Chart

Create Visit (visitId)
    ↓
OPD Casesheet
    ↓
Admission Notes ← [Pulls: OPD examination, clinical notes]
    ↓
Progress Records
    ↓
Doctor's Orders
    ↓
Cross Referral ← [Pulls: Admission notes history, Doctor's orders medications]
    ↓
Operation Theater Notes ← [Pulls: Progress records diagnosis, Admission notes, Medications]
    ↓
Doctor's Handover Notes ← [Pulls: Admission notes, Vitals, Progress records, Cross referrals]
    ↓
Discharge Summary ← [Pulls: All visit data]

Detailed Autopopulation Mappings

Admission Notes

Source: OPD Casesheet

opdNotes ← examination + clinicalNotes from OPD casesheet

How it works: When creating admission notes, the API checks if there's an OPD casesheet for the same patient. If found, it includes the examination and clinical notes as reference material.

Cross Referral

Sources:

Admission Notes (chief complaints, history, surgical history, family/social history)
Doctor's Orders (current and previous prescriptions)

Autopopulated Fields:

medicalAndSurgicalHistory ← Formatted string containing:
- Chief complaints from admission notes
- History of present illness from admission notes
- Past history from admission notes
- Surgical history from admission notes
- Family history from admission notes
- Social history from admission notes
- Current medications from latest doctor's orders
- Previous medications from earlier doctor's orders (deduplicated)

Doctor's Handover Notes

Sources:

Admission Notes (patient history, allergies, examination findings)
Vitals (latest vital signs)
Progress Records (recent examination findings)
Doctor's Orders (medications and orders)
Cross Referrals (consultation details)

Autopopulated Fields:

historyOfThePatient ← Formatted string from admission notes containing:
- Chief complaints
- History of present illness
- Past history
- Surgical history
- Obstetric & gynecology history
- Family history
- Personal history
- Social history
currentClinicalStatus ← Combination of:
- Latest vitals with timestamps
- Latest physical examination findings from progress records
allergies ← From admission notes
currentTreatmentPlan ← Formatted string containing:
- Administered medications (from latest doctor's orders)
- Ongoing treatments (from earlier orders, deduplicated)
- Fluid therapy orders
anyCrossReferralSought ← Formatted list of all cross referrals with:
- Timestamp
- Reason for referral
- Clinical findings
- Assessment
- Recommendations

Operation Theater Notes

Sources:

Progress Records (diagnosis)
Admission Notes (medical history, surgical history, allergies)
Doctor's Orders (current medications)

Autopopulated Fields:

diagnosis ← Latest diagnosis from progress records
preoperativeAssessment ← Formatted string containing:
- Medical History (chief complaints, history of present illness, past history, family history, social history)
- Surgical History
- Allergies
- Current Medications (deduplicated from all doctor's orders)

Discharge Summary

Sources: All casesheets from the visit

Autopopulated Fields:

finalDiagnosis ← Latest diagnosis from progress records
reasonForAdmission ← Chief complaints from admission notes
historyOfPresentIllness ← From admission notes
pastHistory ← From admission notes
familyHistory ← From admission notes
personalHistory ← From admission notes
socialHistory ← From admission notes
treatmentHistory ← Current medications from admission notes
obstetricAndGynecologyHistory ← From admission notes
generalExamination ← From admission notes
systemicExamination ← From admission notes
procedure ← Chronological list of all procedures from:
- Progress records (with dates)
- OPD casesheet
administeredMedications ← Deduplicated list of all medications from doctor's orders
investigationsOrdered ← All investigations from doctor's orders
patientConditionAtDischarge ← Latest patient condition from progress records
generalExaminationAtDischarge ← Latest general examination from progress records
systemicExaminationAtDischarge ← Latest systemic examination from progress records
lims ← Laboratory investigation results (if integrated)
pacsris ← Radiology reports (if integrated)

Disabling Autopopulation

To generate a casesheet without autopopulated data, set the autopopulate parameter to false:

json
{
  "visitId": "clx9876543210fedcba",
  "notes": "...",
  "autopopulate": false
}

This will return only the fields extracted from the current input notes, without any data from previous casesheets.

Response Schemas

This section provides detailed schema definitions for each casesheet type.

Common Field Types

Patient Identifiers:

typescript
{
  "patientId": string,           // Unique patient identifier
  "visitId": string              // Unique visit identifier
}

Timestamps:

typescript
{
  "createdAt": string,           // ISO 8601 datetime
  "updatedAt": string            // ISO 8601 datetime
}

Prescription:

typescript
{
  "route": string,               // e.g., "Oral", "IV", "IM"
  "form": string,                // e.g., "Tablet", "Injection", "Syrup"
  "drug": string,                // Drug name
  "genericName": string,         // Generic/chemical name
  "frequency": string,           // e.g., "OD", "BD", "TDS", "QID"
  "strength": string,            // e.g., "500mg", "10ml"
  "duration": string,            // e.g., "5 days", "2 weeks"
  "instructions": string         // e.g., "After meals", "On empty stomach"
}

Investigation:

typescript
{
  "name": string,                // Investigation name
  "frequency": string,           // e.g., "Once", "Daily"
  "remarks": string,             // Additional notes
  "time": string,                // e.g., "Morning", "Fasting"
  "orderDate": string | null     // ISO 8601 datetime
}

Follow-Up:

typescript
{
  "practitionerId": string | null,
  "date": string | null,         // ISO 8601 datetime
  "remarks": string | null
}

OPD Casesheet Schema

typescript
{
  "casesheetId": string,
  "visitId": string,
  "patientId": string,
  "hospitalsPatientId": string | null,
  "provisionalDiagnosis": string[],
  "chiefComplaints": string,
  "historyOfPresentIllness": string,
  "allergies": string,
  "pastHistory": string,
  "surgicalHistory": string,
  "treatmentHistory": string,
  "obstetricAndGynecologyHistory": string,
  "familyHistory": string,
  "personalHistory": string,
  "socialHistory": string,
  "generalExamination": string,
  "systemicExamination": string,
  "examination": string,
  "clinicalNotes": string,
  "investigations": Investigation[],
  "prescription": Prescription[],
  "finalDiagnosis": string,
  "procedure": string,
  "plan": string,
  "advice": string,
  "createdAt": string,
  "updatedAt": string
}

Admission Notes Schema

typescript
{
  "casesheetId": string,
  "visitId": string,
  "patientId": string,
  "finalDiagnosis": string,
  "provisionalDiagnosis": string[],
  "dateOfAdmission": string,             // ISO 8601 date
  "dateOfSurgery": string,               // ISO 8601 date
  "dateOfPlannedDischarge": string,      // ISO 8601 date
  "chiefComplaints": string,
  "historyOfPresentIllness": string,
  "painAssessment": string,
  "allergies": string,
  "pastHistory": string,
  "surgicalHistory": string,
  "obstetricAndGynecologyHistory": string,
  "currentMedications": string,
  "familyHistory": string,
  "personalHistory": string,
  "socialHistory": string,
  "generalExamination": string,
  "systemicExamination": string,
  "procedure": string,
  "carePlan": string,
  "createdAt": string,
  "updatedAt": string
}

Progress Record Schema

typescript
{
  "casesheetId": string,
  "visitId": string,
  "patientId": string,
  "diagnosis": string,
  "provisionalDiagnosis": string[],
  "currentPatientCondition": string,
  "procedure": string,
  "generalExamination": string,
  "systemicExamination": string,
  "plan": string,
  "dietAndNutrition": string,
  "createdAt": string,
  "updatedAt": string
}

Doctor's Orders Schema

typescript
{
  "casesheetId": string,
  "visitId": string,
  "patientId": string,
  "diagnosis": string,
  "orders": string,
  "investigations": Investigation[],
  "prescription": Prescription[],
  "createdAt": string,
  "updatedAt": string
}

Cross Referral Schema

typescript
{
  "casesheetId": string,
  "visitId": string,
  "patientId": string,
  "practitionerId": string,
  "practitionerName": string | null,
  "departmentId": string,
  "date": string | null,                  // ISO 8601 datetime
  "referralDetails": string | null,
  "primaryReasonForReferral": string,
  "reasonForReferral": string,
  "medicalAndSurgicalHistory": string,    // Autopopulated
  "clinicalFindings": string,
  "laboratoryDiagnostic": string,
  "imagingStudies": string,
  "assessment": string,
  "procedurePerformed": string,
  "recommendation": string,
  "consultationDetails": string,
  "createdAt": string,
  "updatedAt": string
}

Doctor's Handover Notes Schema

typescript
{
  "casesheetId": string,
  "visitId": string,
  "patientId": string,
  "practitionerId": string,
  "departmentId": string,
  "reasonForTransfer": string,
  "currentDiagnosis": string,
  "historyOfThePatient": string,          // Autopopulated
  "currentClinicalStatus": string,        // Autopopulated
  "allergies": string,                    // Autopopulated
  "recentSignificantEvents": string,
  "currentTreatmentPlan": string,         // Autopopulated
  "resuscitationAndCriticalCare": string,
  "laboratoryResults": string,
  "imagingStudies": string,
  "anyCrossReferralSought": string,       // Autopopulated
  "handoverDetails": string,
  "followUp": FollowUp[],
  "createdAt": string,
  "updatedAt": string
}

Operation Theater Notes Schema

typescript
{
  "casesheetId": string,
  "visitId": string,
  "patientId": string,
  "surgeon": string,
  "assistantSurgeon": string,
  "anesthesiologist": string,
  "diagnosis": string,                     // Autopopulated
  "indicationForSurgery": string,
  "preoperativeAssessment": string,        // Autopopulated
  "consent": string,
  "labResults": string,
  "imagingStudies": string,
  "intraoperativeDetails": string,
  "immediatePostoperativeCondition": string,
  "postoperativeOrders": string,
  "instructionsForRecovery": string,
  "createdAt": string,
  "updatedAt": string
}

Discharge Summary Schema

typescript
{
  "casesheetId": string,
  "visitId": string,
  "patientId": string,
  "departmentId": string,
  "finalDiagnosis": string,                        // Autopopulated
  "reasonForAdmission": string,                    // Autopopulated
  "historyOfPresentIllness": string,               // Autopopulated
  "pastHistory": string,                           // Autopopulated
  "familyHistory": string,                         // Autopopulated
  "treatmentHistory": string,                      // Autopopulated
  "personalHistory": string,                       // Autopopulated
  "socialHistory": string,                         // Autopopulated
  "obstetricAndGynecologyHistory": string,         // Autopopulated
  "generalExamination": string,                    // Autopopulated
  "systemicExamination": string,                   // Autopopulated
  "procedure": string,                             // Autopopulated
  "inHospitalCourse": string,                      // AI-generated from visit data
  "administeredMedications": string,               // Autopopulated
  "investigationsOrdered": Investigation[],        // Autopopulated
  "radiologicalInvestigations": string,
  "patientConditionAtDischarge": string,           // Autopopulated
  "generalExaminationAtDischarge": string,         // Autopopulated
  "systemicExaminationAtDischarge": string,        // Autopopulated
  "advice": string,
  "dischargeType": string,
  "followUp": FollowUp[],
  "prescription": Prescription[],
  "lims": LimsResult[],                            // Lab results (if integrated)
  "pacsris": PacsrisResult[],                      // Radiology results (if integrated)
  "createdAt": string,
  "updatedAt": string
}

Vitals Schema

typescript
{
  "casesheetId": string,
  "visitId": string,
  "patientId": string,
  "vitals": [
    {
      "vital": "bloodPressure" | "pulseRate" | "spo2" | "hba1c" | "randomBloodSugar" | "temperature" | "respiratoryRate",
      "unit": string,          // e.g., "mmHg", "bpm", "%", "°F", "breaths/min"
      "value": string
    }
  ],
  "createdAt": string,
  "updatedAt": string
}

Error Handling

All error responses follow a consistent JSON structure:

json
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {}
  }
}

HTTP Status Codes

400 Bad Request

When: Invalid input data or malformed request

Example:

json
{
  "success": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Required field 'visitId' is missing",
    "details": {
      "field": "visitId",
      "expectedType": "string"
    }
  }
}

Common Causes:

Missing required fields
Invalid data types
Malformed JSON
Invalid audio file format
Audio file too large (>25MB)

401 Unauthorized

When: Missing or invalid authentication token

Example:

json
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired access token",
    "details": {
      "tokenExpiredAt": "2025-11-19T10:00:00Z"
    }
  }
}

Common Causes:

Missing Authorization header
Expired token
Invalid token format
Revoked token

403 Forbidden

When: Valid token but insufficient permissions

Example:

json
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions to perform this action",
    "details": {
      "required": ["casesheet.write"],
      "provided": ["casesheet.read"]
    }
  }
}

Common Causes:

Trying to access resources outside your scope
Missing required permissions in token
Attempting to modify read-only resources

404 Not Found

When: Requested resource doesn't exist

Example:

json
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Visit with ID 'clx123invalid' not found",
    "details": {
      "resourceType": "visit",
      "resourceId": "clx123invalid"
    }
  }
}

Common Causes:

Invalid visitId or patientId
Deleted or expired resources
Typo in resource ID

429 Too Many Requests

When: Rate limit exceeded

Example:

json
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Maximum 100 requests per minute.",
    "details": {
      "limit": 100,
      "window": "60s",
      "retryAfter": 45
    }
  }
}

Response Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1700482845
Retry-After: 45

500 Internal Server Error

When: Unexpected server error

Example:

json
{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred. Please try again later.",
    "details": {
      "requestId": "req_abc123xyz",
      "timestamp": "2025-11-19T12:30:00Z"
    }
  }
}

Common Causes:

AI service temporarily unavailable
Database connection issues
Transcription service errors
Unexpected data format from AI

Error Recovery Recommendations

400 Errors: Validate your request payload before sending
401 Errors: Refresh your access token and retry
403 Errors: Check your API credentials have the correct scopes
404 Errors: Verify the resource ID exists
429 Errors: Implement exponential backoff and respect the Retry-After header
500 Errors: Retry with exponential backoff (max 3 retries)

Rate Limiting

The API enforces rate limits to ensure fair usage and system stability.

Rate Limit Tiers

Standard Tier:

100 requests per minute per client
Applies to all endpoints equally

Rate Limit Headers

Every API response includes rate limit information:

X-RateLimit-Limit: 100           # Maximum requests per window
X-RateLimit-Remaining: 85        # Requests remaining in current window
X-RateLimit-Reset: 1700482845    # Unix timestamp when limit resets

Exceeding Rate Limits

When you exceed the rate limit:

You'll receive a 429 Too Many Requests response
The Retry-After header indicates seconds to wait
Your current window resets after the time specified in X-RateLimit-Reset

Best Practices

Monitor Headers: Track X-RateLimit-Remaining to avoid hitting limits
Implement Backoff: Use exponential backoff when rate limited
Batch Requests: Group related operations where possible
Cache Responses: Cache frequently accessed data
Respect Retry-After: Always wait the specified time before retrying

Example: Handling Rate Limits

python
import time
import requests

def make_api_request(url, headers, data, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json=data)

        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 60))
            print(f"Rate limited. Waiting {retry_after} seconds...")
            time.sleep(retry_after)
            continue

        return response

    raise Exception("Max retries exceeded")

Example Workflows

Workflow 1: Complete OPD Visit with Text Input

Step 1: Authenticate

bash
curl -X POST https://api.axone.one/api/v1/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&scope=casesheet.read casesheet.write patient.read patient.write"

Response:

json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Step 2: Create Patient

bash
curl -X POST https://api.axone.one/api/v1/patients \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "age": 45,
    "gender": "male",
    "phoneNumber": "+1234567890"
  }'

Response:

json
{
  "success": true,
  "data": {
    "patientId": "clx1234567890abcdef"
  }
}

Step 3: Create Visit

bash
curl -X POST https://api.axone.one/api/v1/visits \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "patientId": "clx1234567890abcdef",
    "visitType": "OPD",
    "appointmentTime": "2025-11-19T14:00:00Z"
  }'

Response:

json
{
  "success": true,
  "data": {
    "visitId": "clx9876543210fedcba"
  }
}

Step 4: Generate OPD Casesheet

bash
curl -X POST https://api.axone.one/api/v1/casesheets/opd-casesheet/text \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "visitId": "clx9876543210fedcba",
    "notes": "Patient presents with fever for 3 days, temperature 102F, headache, body ache. No cough or cold. Medical history: Diabetes for 5 years on Metformin. Examination: Throat congestion, no lymphadenopathy. Assessment: Viral fever. Plan: Paracetamol 500mg TDS, rest, fluids."
  }'

Response: Complete OPD casesheet JSON (see OPD Casesheet Schema)

Workflow 2: IPD Admission with Voice Input and Autopopulation

Prerequisites: Patient and OPD visit already exist from previous workflow

Step 1: Create IPD Visit

bash
curl -X POST https://api.axone.one/api/v1/visits \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "patientId": "clx1234567890abcdef",
    "visitType": "IPD",
    "department": "Cardiology",
    "practitioner": "Dr. Smith"
  }'

Response:

json
{
  "success": true,
  "data": {
    "visitId": "clxipd123456789"
  }
}

Step 2: Generate Admission Notes (Voice)

bash
curl -X POST https://api.axone.one/api/v1/casesheets/admission-notes/voice \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "visitId=clxipd123456789" \
  -F "audioFile=@admission-notes-dictation.mp3" \
  -F "autopopulate=true"

Response: Complete admission notes with autopopulated OPD data

Workflow 3: Sequential Casesheet Creation (Demonstrating Autopopulation)

This workflow shows how data flows from one casesheet to another through autopopulation.

Step 1: Create Admission Notes (baseline data)

bash
curl -X POST https://api.axone.one/api/v1/casesheets/admission-notes/text \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "visitId": "clxipd123456789",
    "notes": "45yo male admitted for chest pain. History of hypertension. Allergic to penicillin. Examination shows stable vitals."
  }'

Step 2: Create Progress Record

bash
curl -X POST https://api.axone.one/api/v1/casesheets/progress-records/text \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "visitId": "clxipd123456789",
    "notes": "Day 2 post admission. Patient stable. Chest pain resolved."
  }'

Step 3: Create Doctor's Orders

bash
curl -X POST https://api.axone.one/api/v1/casesheets/doctors-orders/text \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "visitId": "clxipd123456789",
    "notes": "Continue Aspirin 75mg OD, add Atorvastatin 40mg HS. Order ECG and lipid profile."
  }'

Step 4: Create Cross Referral (autopopulates from steps 1 & 3)

bash
curl -X POST https://api.axone.one/api/v1/casesheets/cross-referral/text \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "visitId": "clxipd123456789",
    "notes": "Refer to Cardiology for stress test evaluation."
  }'

Expected: The cross referral will automatically include:

Patient's medical history from admission notes
Current medications from doctor's orders
Past surgical history from admission notes

Step 5: Create Discharge Summary (autopopulates from all previous casesheets)

bash
curl -X POST https://api.axone.one/api/v1/casesheets/discharge-summary/text \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "visitId": "clxipd123456789",
    "notes": "Patient stable for discharge. Continue medications. Follow-up in 1 week."
  }'

Expected: The discharge summary will include:

Complete admission history
All procedures from progress records
All medications (deduplicated)
Latest patient condition
Cross referral details

Best Practices

1. Error Handling

Always handle errors gracefully:

javascript
try {
  const response = await fetch(endpoint, options);
  const data = await response.json();

  if (!response.ok) {
    // Handle HTTP errors
    console.error(`Error ${data.error.code}: ${data.error.message}`);

    if (response.status === 401) {
      // Refresh token and retry
      await refreshAccessToken();
      return retryRequest();
    }

    if (response.status === 429) {
      // Rate limited - wait and retry
      const retryAfter = response.headers.get("Retry-After");
      await sleep(retryAfter * 1000);
      return retryRequest();
    }
  }

  return data;
} catch (error) {
  // Handle network errors
  console.error("Network error:", error);
  throw error;
}

2. Retry Strategy

Implement exponential backoff for retries:

python
import time

def exponential_backoff(attempt, base_delay=1, max_delay=60):
    delay = min(base_delay * (2 ** attempt), max_delay)
    time.sleep(delay)

def make_request_with_retry(url, data, max_attempts=3):
    for attempt in range(max_attempts):
        try:
            response = requests.post(url, json=data)

            if response.status_code in [500, 502, 503, 504]:
                if attempt < max_attempts - 1:
                    exponential_backoff(attempt)
                    continue

            return response

        except requests.exceptions.RequestException as e:
            if attempt < max_attempts - 1:
                exponential_backoff(attempt)
                continue
            raise