Helna Consultation API Tester

AUTH Authentication

▶

All API calls require authentication via API key in the header.

Required Headers

Header	Value	Description
X-Api-Key	Required	Your API key (starts with hlna_)
X-Clinician-Id	Required	Clinician identifier
Content-Type	application/json	For POST requests with JSON body

Example

curl -X POST "https://consultation.api.helna.tech/api/v1/endpoint" \
  -H "X-Api-Key: hlna_YOUR_API_KEY" \
  -H "X-Clinician-Id: clinician-001" \
  -H "Content-Type: application/json"

POST /api/v1/uploadconsultationaudio

▶

Initiates a consultation audio upload. Returns a secure upload URL and creates the consultation record.

Request Body

Field	Type	Required	Description
consultationId	string	Yes	Unique ID for the consultation
patientId	string	Yes	Patient identifier
clinicId	string	No	Clinic identifier
language	string	No	Language code (e.g., en-US, ar-IQ). Default: en-US
contentType	string	No	Audio MIME type. Default: audio/webm
fileSizeBytes	number	No	File size in bytes

Example Request

{
  "consultationId": "consult-12345",
  "patientId": "patient-001",
  "clinicId": "clinic-main",
  "language": "ar-IQ",
  "contentType": "audio/webm",
  "fileSizeBytes": 125000
}

cURL Example

curl -X POST "https://consultation.api.helna.tech/api/v1/uploadconsultationaudio" \
  -H "X-Api-Key: hlna_YOUR_API_KEY" \
  -H "X-Clinician-Id: clinician-001" \
  -H "Content-Type: application/json" \
  -d '{"consultationId": "consult-12345", "patientId": "patient-001", "language": "ar-IQ"}'

Response

{
  "success": true,
  "recordingId": "uuid-of-recording",
  "uploadUrl": "https://storage.example.com/...",
  "filePath": "clinic/patient/consult/file.webm",
  "expiresInMinutes": 30,
  "message": "Upload the audio file directly to uploadUrl using PUT"
}

Next Step

Upload the audio file to the uploadUrl using PUT method with Content-Type header.

POST /api/v1/confirmaudioupload

▶

Confirms that the audio file has been uploaded successfully. Updates the recording status.

Request Body

Field	Type	Required	Description
recordingId	string	Yes	Recording ID from upload response

Example

{
  "recordingId": "uuid-of-recording"
}

cURL Example

curl -X POST "https://consultation.api.helna.tech/api/v1/confirmaudioupload" \
  -H "X-Api-Key: hlna_YOUR_API_KEY" \
  -H "X-Clinician-Id: clinician-001" \
  -H "Content-Type: application/json" \
  -d '{"recordingId": "uuid-of-recording"}'

POST /api/v1/starttranscription

▶

Starts speech-to-text transcription. Supports 100+ languages including Arabic dialects.

Request Body

Field	Type	Required	Description
recordingId	string	Yes	Recording ID from upload
language	string	No	Override language (e.g., ar-IQ, en-GB)
enableDiarization	boolean	No	Enable speaker diarization. Default: true

Supported Languages

English

en-US en-GB en-AU en-CA en-IN en-IE en-NZ en-ZA

Arabic

ar-IQ ar-SA ar-AE ar-EG ar-KW ar-QA ar-BH ar-OM ar-SY ar-JO ar-LB ar-PS ar-MA ar-DZ ar-TN ar-LY ar-YE ar-SD

European

de-DE de-AT de-CH fr-FR fr-CA fr-BE fr-CH es-ES es-MX es-AR es-CO it-IT nl-NL nl-BE pt-PT pt-BR sv-SE da-DK nb-NO fi-FI pl-PL cs-CZ el-GR ru-RU uk-UA

East Asian

zh-CN zh-TW zh-HK ja-JP ko-KR th-TH vi-VN id-ID ms-MY

South Asian

hi-IN bn-IN ta-IN te-IN mr-IN gu-IN ur-PK

Middle East

tr-TR fa-IR he-IL

African

af-ZA sw-KE sw-TZ am-ET

Example Request

{
  "recordingId": "abc12345-6789-def0-1234-567890abcdef",
  "language": "ar-IQ",
  "enableDiarization": true
}

cURL Example

curl -X POST "https://consultation.api.helna.tech/api/v1/starttranscription" \
  -H "X-Api-Key: hlna_YOUR_API_KEY" \
  -H "X-Clinician-Id: clinician-001" \
  -H "Content-Type: application/json" \
  -d '{"recordingId": "abc12345-6789-def0-1234-567890abcdef", "language": "ar-IQ"}'

Response (Synchronous)

{
  "success": true,
  "recordingId": "uuid",
  "status": "Completed",
  "transcribedText": "The full transcription text...",
  "processingTimeSeconds": 9.5,
  "consultationUpdated": true
}

Credits

Transcription deducts credits from your account. Minimum 1 minute per transcription.

GET /api/v1/CheckTranscriptionStatus/{recordingId}

▶

Get the current status of a transcription job and retrieve the transcribed text.

Path Parameters

Parameter	Type	Description
recordingId	string	The recording ID to check

cURL Example

curl -X GET "https://consultation.api.helna.tech/api/v1/CheckTranscriptionStatus/abc12345-6789-def0-1234-567890abcdef" \
  -H "X-Api-Key: hlna_YOUR_API_KEY" \
  -H "X-Clinician-Id: clinician-001"

JavaScript Example

const response = await fetch(
  "https://consultation.api.helna.tech/api/v1/CheckTranscriptionStatus/abc12345-6789-def0-1234-567890abcdef",
  {
    method: "GET",
    headers: {
      "X-Api-Key": "hlna_YOUR_API_KEY",
      "X-Clinician-Id": "clinician-001"
    }
  }
);
const data = await response.json();

Response

{
  "success": true,
  "recording": {
    "id": "uuid",
    "status": "Completed",
    "transcribedText": "The transcription...",
    "language": "ar-IQ",
    "durationSeconds": 45,
    "createdAt": "2026-03-14T12:00:00Z"
  }
}

Status Values

Uploading → Uploaded → Processing → Transcribing → Completed or Failed

POST /api/v1/analyzeconsultation

▶

Runs AI analysis on consultation notes. Provides clinical assessment, differential diagnosis, treatment recommendations, and more.

Request Body

Field	Type	Required	Description
ConsultationNotes	string	Yes	The transcription or consultation notes to analyze
PatientAge	number	No	Patient age for context
PatientGender	string	No	Patient gender for context

Example Request

{
  "ConsultationNotes": "Patient presents with headache and fever..."
}

cURL Example

curl -X POST "https://consultation.api.helna.tech/api/v1/analyzeconsultation" \
  -H "X-Api-Key: hlna_YOUR_API_KEY" \
  -H "X-Clinician-Id: clinician-001" \
  -H "Content-Type: application/json" \
  -d '{"ConsultationNotes": "Patient presents with headache and fever..."}'

Response Fields

Field	Description
chiefComplaint	Main reason for visit
executiveSummary	Brief clinical summary
clinicalAssessment	Symptoms, vitals, findings
differentialDiagnosis	Possible diagnoses ranked by likelihood
treatmentRecommendations	Suggested treatments and medications
redFlags	Warning signs requiring urgent attention
followUpPlan	Recommended follow-up schedule

GET /api/v1/consultations/{consultationId}

▶

Retrieve a consultation by ID with full details including transcription and AI analysis.

Path Parameters

Parameter	Type	Description
consultationId	string	The consultation ID

cURL Example

curl -X GET "https://consultation.api.helna.tech/api/v1/consultations/consult-12345" \
  -H "X-Api-Key: hlna_YOUR_API_KEY" \
  -H "X-Clinician-Id: clinician-001"

JavaScript Example

const response = await fetch(
  "https://consultation.api.helna.tech/api/v1/consultations/consult-12345",
  {
    method: "GET",
    headers: {
      "X-Api-Key": "hlna_YOUR_API_KEY",
      "X-Clinician-Id": "clinician-001"
    }
  }
);
const consultation = await response.json();

POST /api/v1/translateconsultation

▶

Translate consultation content to another language using AI translation.

Request Body

Field	Type	Required	Description
consultationId	string	Yes	Consultation to translate
targetLanguage	string	Yes	Target language code (e.g., en, ar, fr)

Example Request

{
  "consultationId": "consult-12345",
  "targetLanguage": "en"
}

cURL Example

curl -X POST "https://consultation.api.helna.tech/api/v1/translateconsultation" \
  -H "X-Api-Key: hlna_YOUR_API_KEY" \
  -H "X-Clinician-Id: clinician-001" \
  -H "Content-Type: application/json" \
  -d '{"consultationId": "consult-12345", "targetLanguage": "en"}'

FLOW Complete Workflow

▶

Step-by-Step Integration

Initialize Upload: POST /uploadconsultationaudio → Get uploadUrl
Upload Audio: PUT to uploadUrl with audio file
Confirm Upload: POST /confirmaudioupload
Start Transcription: POST /starttranscription → Get transcribedText
AI Analysis: POST /analyzeconsultation → Get clinical analysis
Retrieve: GET /consultations/{id} → Full consultation record

Error Handling

Status	Meaning
200	Success
400	Bad Request - Check required fields
401	Unauthorized - Invalid or missing API key
402	Payment Required - Insufficient credits
404	Not Found - Resource doesn't exist
500	Server Error - Check logs

📚 API Documentation

Required Headers

Example

Request Body

Example Request

cURL Example

Response

Next Step

Request Body

Example

cURL Example

Request Body

Supported Languages

Example Request

cURL Example

Response (Synchronous)

Credits

Path Parameters

cURL Example

JavaScript Example

Response

Status Values

Request Body

Example Request

cURL Example

Response Fields

Path Parameters

cURL Example

JavaScript Example

Request Body

Example Request

cURL Example

Step-by-Step Integration

Error Handling

⚙️ Configuration

1 Record Consultation Audio

2 Consultation Details

3 Process Consultation

📜 Console Logs

📋 Results ⏱️ --

Summary

Symptoms

Suggested Actions