Respiratory AI

Overview

The Respiratory AI API is a powerful tool that allows you to predict a variety of conditions based on cough sounds. It uses advanced machine learning models and signal processing techniques to analyze the sound waves, correlate with symptoms and provide assessments.

Base URL

The base URLs for the Respiratory AI API are

• PROD: https://api.prod.helfie.ai.
• DEV: https://api-dev.helfie.ai.

API Endpoints

Disease Likely Endpoint

• Endpoint: /lung/api/diseaselikely
• Method: POST
• Description: This endpoint allows you to retrieve likely presence information about Respiratory related diseases. It takes a cough sounds and a few demographic parameters and returns Yes or No for likely of each disease.

Request Parameters:

• coughsoundfile (file): Audio file with cough.
• gender (int): 0 for male, 1 for female.
• age (int): User age.
• height (int): User height in cm.
• weight (int): User weight in kg.
• user_id (uuid): User id referenced in database.
• check_variant (str): Lung Check Type [General, COVID, TB]

Example Request:

curl --location --globoff '${BASE_URL}/lung/api/diseaselikely' \
--header 'api-key: ••••••' \
--form 'coughsoundfile=@"path_to_sound_file.wav"' \
--form 'gender="1"' \
--form 'age="66"' \
--form 'assessmentId="••••••"' \
--form 'height="160"' \
--form 'weight="70"' \
--form 'user_id="••••••"'
--form 'check_variant="General"'

Example Response:

{
    "assessmentId": "839450261772429f8925a87c98a4fb3111d11j11g",
    "data": {
        "COPD_likely": "No",
        "asthma_likely": "No",
        "asthma_likely_prob": 0,
        "bronchiectasis_likely": "No",
        "bronchiectasis_likely_prob": 0,
        "copd_likely_prob": 0,
        "cough_pattern": "Normal",
        "covid_likely": "No",
        "covid_likely_prob": 0,
        "ild_likely": "No",
        "ild_likely_prob": 0,
        "patientId": null,
        "pneumonia_likely": "No",
        "pneumonia_likely_prob": 0,
        "risk": "No",
        "status": "SUCCESS",
        "tb_likely": "No",
        "tb_likely_prob": 0,
        "timestamp": "2024-07-08 06:39:48",
        "userId": "newhelfie@swaasa.ai"
    },
    "disease_likely": false,
    "status": "SUCCESS"
}

Response Parameters

• COPD_likely (string): Yes or No for likely presence of COPD.
• copd_likely_prob (int): Likely probability.
• asthma_likely (string): Yes or No for likely presence of Asthma.
• asthma_likely_prob (int): Likely probability.
• bronchiectasis_likely (string): Yes or No for likely presence of Bronchiectasis.
• bronchiectasis_likely_prob (int): Likely probability.
• cough_pattern (string): Cough pattern.
• covid_likely (string): Yes or No for likely presence of Covid.
• covid_likely_prob (int): Likely probability.
• height (int): User height in cm.
• ild_likely (string): Yes or No for likely presence of ILD.
• ild_likely_prob (int): Likely probability.
• pneumonia_likely (string): Yes or No for likely presence of Pneumonia.
• pneumonia_likely_prob (int): Likely probability.
• risk (string): Yes if there is any other disease likely apart from the ones mentioned above, otherwise No.
• tb_likely (string): Yes or No for likely presence of TB.
• tb_likely_prob (int): Likely probability.
• timestamp (string): Timestamp of the assessment.
• userId (uuid): User id referenced in database.
• weight (int): User weight in kg.
• disease_likely (bool): True if any disease is likely, otherwise False.

Risk Score Assessment Endpoint

• Endpoint: /lung/api/riskscore_assessment
• Method: POST
• Description: This is the main endpoint that allows you to generate the risk score for each respiratory disease along with risk level and probability of having the disease. It requires that you have previously sent the cough file in diseaselikely endpoint.

Request Parameters:

• symptoms (dict): A dictionary with the symptoms.
• assessmentId (uuid): Assessment ID previously received from verifycough endpoint.
• user_id (uuid): User id referenced in database.

Example Request:

curl --location --globoff '${BASE_URL}/lung/api/riskscore_assessment' \
--header 'api-key: ••••••' \
--form 'symptoms="{\"frequent_cough\":1,\"cough_at_night\":0,\"sputum\":0,\"pain_in_chest\":0,\"wheezing\":0,\"shortness_of_breath\":0,\"fever\":0,\"fatigue\":0,\"sweat_heavy_at_night\":0,\"loss_of_appetite\":0,\"weight_loss\":0,\"cough_with_sputum_and_blood\":0,\"evening_rise_in_temperature\":0,\"known_person_having_active_tb\":0,\"active_tb_past\":0,\"family_history_of_asthma\":0,\"active_asthma_past\":0,\"smoking\":0,\"exposure_to_any_kind_of_smoke\":1,\"temperature_F\":0,\"pulse_rate\":0,\"respiratory_rate\":0,\"oxygen_saturation\":0,\"blood_pressure\":0, \"frequent_cough_duration\": 2}"' \
--form 'assessmentId="••••••"' \
--form 'user_id="••••••"'

Example Response:

{
    "status": "SUCCESS",
    "data": {
        "COPD_Summary": "Seek immediate medical attention.",
        "COPD_risk_score": 7,
        "COPD_severity": "High",
        "asthma_Summary": "Consult a physician. Testing may be required as per your physician’s advice.",
        "asthma_risk_score": 6,
        "asthma_severity": "Medium",
        "bronchiectasis_likely": "No",
        "bronchiectasis_risk_score": 9,
        "cough_pattern": "Obstructive",
        "covid_risk": "Medium",
        "covid_risk_score": 5,
        "covid_summary": "Consult a physician. Testing may be required as per your physician’s advice.",
        "dry_cough_count": 1,
        "height": 160,
        "ild_risk_score": 9,
        "patientId": null,
        "pneumonia_likely": "No",
        "pneumonia_risk_score": 9,
        "recordId": "••••••",
        "risk": "Yes",
        "status": "SUCCESS",
        "tb_Risk": "High",
        "tb_RiskScore": 7,
        "tb_Summary": "Seek immediate medical attention.",
        "timestamp": "2024-05-08 21:43:07",
        "userId": "••••••",
        "wet_cough_count": 5,
        "lhi": 9
    },
    "assessmentId": "testing"
}

Acknowledgement Endpoint

• Endpoint: /lung/api/acknowledge_assessment
• Method: POST
• Description: This endpoint allows you to acknowledge the assessment results in the database.

Request Parameters:

• assessmentId (uuid): Assessment ID previously received from verifycough endpoint.
• user_id (uuid): User id referenced in database.

Example Request:

curl --location --globoff '${BASE_URL}/lung/api/acknowledge_assessment' \
--header 'api-key: ••••••' \
--header 'Content-Type: application/json' \
--data '{
    "assessment_id": "••••••",
    "user_id": "••••••"
}'

Example Response:

{
    "acknowledged": true,
    "app_type": 0,
    "assessment_id": "••••••",
    "asthma_likely": "No",
    "asthma_risk_score": 1,
    "bronchiectasis_likely": "No",
    "bronchiectasis_risk_score": -1,
    "conditions": null,
    "copd_likely": "No",
    "copd_risk_score": 1,
    "cough_pattern": null,
    "covid_likely": "No",
    "covid_risk_score": 4,
    "created": "2024-05-02T15:18:58.405977+00:00",
    "croup_likely": null,
    "croup_risk_score": null,
    "ild_likely": "No",
    "ild_risk_score": -1,
    "lung_health": null,
    "mobile": null,
    "physiology": null,
    "pneumonia_likely": "No",
    "pneumonia_risk_score": -1,
    "risk": null,
    "swaasa_assessment_id": null,
    "symptoms": {
        "active_asthma_past": 0,
        "active_tb_past": 0,
        "blood_pressure": 0,
        "cough_at_night": 0,
        "cough_with_sputum_and_blood": 0,
        "evening_rise_in_temperature": 0,
        "exposure_to_any_kind_of_smoke": 1,
        "family_history_of_asthma": 0,
        "fatigue": 0,
        "fever": 0,
        "frequent_cough": 1,
        "frequent_cough_duration": 2,
        "known_person_having_active_tb": 0,
        "loss_of_appetite": 0,
        "oxygen_saturation": 0,
        "pain_in_chest": 0,
        "pulse_rate": 0,
        "respiratory_rate": 0,
        "shortness_of_breath": 0,
        "smoking": 0,
        "sputum": 0,
        "sweat_heavy_at_night": 0,
        "temperature_F": 0,
        "weight_loss": 0,
        "wheezing": 0
    },
    "tb_likely": "No",
    "tb_risk_score": 2,
    "user_id": "••••••"
}

Health Check Endpoint

• Endpoint: /lung/api/health
• Method: GET
• Description: This endpoint Provides the status of the API to monitor possible outages.

Request Parameters: None

Example Request:

curl --location --globoff '${BASE_URL}/lung/api/health'

Example Response:

{
    "status": "success"
}

Response Fields:

• status(string): success if everything is ok, otherwise there is an outage in API.

Version Check Endpoint

• Endpoint: /lung/api/version
• Method: GET
• Description: This endpoint provides the version of the API.

Request Parameters: None

Example Request:

curl --location --globoff '${BASE_URL}/lung/api/version'

Example Response:

{
    "version": "client-auth",
    "wavkit": "master"
}

Response Fields:

• version(string): The version of the API.
• wavkit(string): The version of pre-processing sound library.

Disease likely symptoms Endpoint

• Endpoint: /lung/api/symptomslist
• Method: GET
• Description: This endpoint provides symptoms and list of symptoms associated with each respiratory disease which are used for further analysis in prediction of likelihood of disease. Each symptom in response contains key, display name and values it can take.

Request Parameters: None

Example Request:

curl --location --globoff '${BASE_URL}/lung/api/symptomslist' \
--header 'api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \

Example Response:

{
    "status": "Success",
    "accessToken": "•••••••",
    "data": {
        "core_symptoms": [
            {
                "key": "frequent_cough",
                "displayName": "Frequent cough",
                "value": [
                    0,
                    1
                ]
            },
            {
                "key": "cough_at_night",
                "displayName": "Cough during night",
                "value": [
                    0,
                    1
                ]
            },
            {
                "key": "sputum",
                "displayName": "Mucus / Sputum",
                "value": [
                    0,
                    1
                ]
            },
            {
                "key": "pain_in_chest",
                "displayName": "Pain in chest",
                "value": [
                    0,
                    1
                ]
            },
            {
                "key": "wheezing",
                "displayName": "Sound in chest while breathing",
                "value": [
                    0,
                    1
                ]
            },
            {
                "key": "shortness_of_breath",
                "displayName": "Difficulty in breathing",
                "value": [
                    0,
                    1
                ]
            }
        ],
        "covid_likely": [
            {
                "key": "fever",
                "displayName": "Fever",
                "value": [
                    0,
                    1
                ]
            },
            {
                "key": "sore_throat",
                "displayName": "Sore throat",
                "value": [
                    0,
                    1
                ]
            },
            {
                "key": "running_nose",
                "displayName": "Running nose / Sneezing",
                "value": [
                    0,
                    1
                ]
            },
            {
                "key": "loss_of_smell_taste",
                "displayName": "Loss or diminished sense of smell / Taste",
                "value": [
                    0,
                    1
                ]
            },
            {
                "key": "body_pains",
                "displayName": "Body pain / Headache",
                "value": [
                    0,
                    1
                ]
            },
            {
                "key": "diarrhoea",
                "displayName": "Diarrhoea / Vomiting",
                "value": [
                    0,
                    1
                ]
            },
            {
                "key": "fatigue",
                "displayName": "Fatigue / Tiredness",
                "value": [
                    0,
                    1
                ]
            },
            {
                "key": "contact_with_covid_positive",
                "displayName": "Contact with covid positive",
                "value": [
                    0,
                    1
                ]
            },
            {
                "key": "previously_infected_with_covid",
                "displayName": "Previously infected with covid",
                "value": [
                    0,
                    1
                ]
            }
        ],
        "tb_likely": [
            {
                "key": "fever",
                "displayName": "Fever",
                "value": [
                    0,
                    1
                ]
            },
            {
                "key": "cough_with_sputum_and_blood",
                "displayName": "Cough with sputum and blood at times",
                "value": [
                    0,
                    1
                ]
            },
            {
                "key": "fatigue",
                "displayName": "Fatigue / Tiredness",
                "value": [
                    0,
                    1
                ]
            },
            {
                "key": "sweat_heavy_at_night",
                "displayName": "Night sweats / Chills",
                "value": [
                    0,
                    1
                ]
            },
            {
                "key": "loss_of_appetite",
                "displayName": "Loss of appetite",
                "value": [
                    0,
                    1
                ]
            },
            {
                "key": "weight_loss",
                "displayName": "Weight loss",
                "value": [
                    0,
                    1
                ]
            },
            {
                "key": "evening_rise_in_temperature",
                "displayName": "Evening rise in temperature",
                "value": [
                    0,
                    1
                ]
            },
            {
                "key": "known_person_having_active_tb",
                "displayName": "Family / Known person having TB",
                "value": [
                    0,
                    1
                ]
            },
            {
                "key": "active_tb_past",
                "displayName": "Active TB in past",
                "value": [
                    0,
                    1
                ]
            }
        ]
    }
}

Verify Cough Endpoint

• Endpoint: /lung/api/verifycough/v1
• Method: POST
• Description: This endpoint simply allows you to check and validate your cough sample. Note: The Audio file configuration must follow the below configurations: Sample Rate: 44100 Hz Encoding: PCM 16Bit Channel: Mono Min Duration: 10 secs.

Request Parameters:

• coughsoundfile (file): Audio file with cough.
• user_id (uuid): User id referenced in database.

Example Request:

curl --location --globoff '${BASE_URL}/lung/api/verifycough/v1' \
--header 'api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
--form 'coughsoundfile=@"path_to_sound_file.wav"' \
--form 'user_id="yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"'

Example Response:

{
    "assessment_id": "d5b827be-73c5-4f40-9fa4-241922af7831",
    "is_valid_cough": true,
    "message": null
}

Assessment Endpoint

• Endpoint: /lung/api/assessment
• Method: POST
• Description: This endpoint allows you to retrieve likely presence information about Respiratory related diseases and corresponding risk score. . It takes a valid cough id, a few demographic parameters, symptoms and returns Yes or No for likely of each disease and the risk scores

Request Parameters:

• assessment_id (string): Assessment Id from the verify cough api.
• age (int): Age.
• gender (str): Gender, must be one of (Male, Female)
• symptoms (json): User symptoms

Example Request:

curl --location '${BASE_URL}/lung/api/assessment' \
--header 'api-key: xxx-xxx-xxx' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ....' \
--data '{
    "assessment_id": "d5b827be-73c5-4f40-9fa4-xxxxxx",
    "age": 55,
    "gender": "Male",
    "symptoms": {
        "frequent_cough": 1,                      // int, range: 0–1
        "cough_at_night": 0,                      // int, range: 0–1
        "sputum": 0,                               // int, range: 0–1
        "pain_in_chest": 0,                        // int, range: 0–1
        "wheezing": 0,                             // int, range: 0–1
        "shortness_of_breath": 0,                  // int, range: 0–1
        "fever": 0,                                // int, range: 0–1
        "fatigue": 0,                              // int, range: 0–1
        "sweat_heavy_at_night": 0,                // int, range: 0–1
        "loss_of_appetite": 0,                     // int, range: 0–1
        "weight_loss": 0,                          // int, range: 0–1
        "cough_with_sputum_and_blood": 0,         // int, range: 0–1
        "evening_rise_in_temperature": 0,          // int, range: 0–1
        "known_person_having_active_tb": 0,        // int, range: 0–1
        "active_tb_past": 0,                       // int, range: 0–1
        "family_history_of_asthma": 0,             // int, range: 0–1
        "active_asthma_past": 0,                   // int, range: 0–1
        "smoking": 0,                              // int, range: 0–1
        "exposure_to_any_kind_of_smoke": 1,         // int, range: 0–1
        "frequent_cough_duration": 2             // int, range: 0–1000  ( Duration in days)

    }
}'

Example Response:

{
    "assessmentId": "767aa38200004c279f837395cc52xxxx",
    "data": {
        "COPD_likely": "No",
        "assessmentId": "767aa38200004c279f837395cc5xxxx",
        "assessment_status": "completed",
        "asthma_likely": "No",
        "asthma_likely_prob": 8,
        "bronchiectasis_likely": "No",
        "bronchiectasis_likely_prob": 32,
        "bronchitis_likely": "No",
        "bronchitis_likely_prob": 0,
        "copd_likely_prob": 19,
        "cough_pattern": "Obstructive",
        "covid_likely": "No",
        "covid_likely_prob": 7,
        "ild_likely": "No",
        "ild_likely_prob": 38,
        "patientId": null,
        "pneumonia_likely": "No",
        "pneumonia_likely_prob": 0,
        "risk": "Yes",
        "status": "SUCCESS",
        "tb_likely": "No",
        "tb_likely_prob": 15,
        "lhi": 3

    },
    "disease_likely": false,
    "status": "SUCCESS"
}