For Developers
Endpoints

Available Endpoints

Our API provides a suite of endpoints, meticulously designed to cater to diverse health data analysis needs. From general health panels to gender-specific assessments, our endpoints are continuously updated to ensure they meet the highest standards of functionality and user experience. Developers can rely on this documentation for the most up-to-date endpoint information, reflecting our commitment to innovation and regular enhancement.

Authentication

We implement OAuth 2.0 for secure token generation, which necessitates onboarding and the establishment of a verified agent account for each partner organization. Once onboarding is completed, token generation is available via /token.

Confirming Authentication

This endpoint is essential for validating the authentication status of a user. By making a request to /users/me, developers can confirm that the OAuth 2.0 token is valid and the user session is active. It's a quick check to ensure that all subsequent API calls are authenticated and that the system recognizes the user's credentials.

A successful request to this endpoint returns the user's profile information, affirming that they are 'logged in' and that the system's security measures are in place and operational. Utilizing this endpoint is a standard step in maintaining secure user sessions and providing personalized experiences.

A TypeScript snippet example to illustrate how a successful authentication check might be implemented:

checkAuth.ts
const checkAuthentication = async (token: string): Promise<void> => {
  try {
    const response = await fetch('/users/me', {
      headers: {
        'Authorization': `Bearer ${token}`,
      },
    });
 
    if (!response.ok) {
      throw new Error('Authentication check failed');
    }
 
    const userData = await response.json();
    console.log('User is authenticated:', userData);
  } catch (error) {
    console.error('Error during authentication check:', error);
  }
};

GET Endpoints

/get_mensPanel_basic

This endpoint provides developers with essential details on the required parameters for the men's health panel. It outlines the supported units, displayable names and abbreviations for test parameters, and additional features necessary for a comprehensive analysis.

Sample return body:

sample response
{
  "CRP": {
    "is_required": true,
    "display": "c-reactive protein",
    "possible_units": [
      "mg/dL",
      "mg/L"
    ]
  },
  "CK": {
    "is_required": true,
    "display": "creatine kinase",
    "possible_units": [
      "mIU/mL",
      "U/L",
      "IU/L"
    ]
  },
  {
    "additionalData": {
    "and": {
      "many": "more"
    }
  }
}

/get_womensPanel_basic

Similar to the men's health panel, this endpoint offers insight into the women's health panel requirements. Developers can obtain information on parameter requirements, unit support, naming conventions, and further analytical features.

Sample return body:

sample response
{
  "CRP": {
    "is_required": true,
    "display": "c-reactive protein",
    "possible_units": [
      "mg/dL",
      "mg/L"
    ]
  },
  "CK": {
    "is_required": true,
    "display": "creatine kinase",
    "possible_units": [
      "mIU/mL",
      "U/L",
      "IU/L"
    ]
  },
  {
    "additionalData": {
    "and": {
      "many": "more"
    }
  }
}


POST Endpoint for Personalized Health Data Analysis

Tailored Data Ingestion and Analysis: /analyseEpisode

The /analyseEpisode POST endpoint is crucial for processing individual client health data, requiring specific metadata for a personalized approach. This endpoint not only accepts essential information such as age, gender, height, and weight (as defined in the UserMeta data class), but is also capable of incorporating optional health-related details to provide a more customized analysis. By understanding the diverse requirements of different use cases, this endpoint can be adapted to match each client's unique needs — ensuring that the representation of results, as well as the selection and volume of input data, are precisely aligned with their specific objectives.

A sample response for the analytical interpretation using naturopathic terminology could look like the sample response below.

Note: This sample response represents a hypothetical scenario in which the user's results were not indicating good health. Scores range up to 100. The provided confidence intervals indicate possible upper and lower deviations from the computed score.

sample response
  {
    "score": 54,
    "interval": [48, 57],
    "concern_level": "Critical concern",
    "report": {
      "overview": "Based on the provided blood test results, there are indications that your blood parameters are not within the optimal range. It is important to put these findings into context and address any concerns that may arise. Please consult with a professional practitioner to determine the severity of these findings and develop an appropriate treatment plan.",
      "main_findings": [
        "One concerning finding is the decreased white blood cell count (WBC). White blood cells play a crucial role in fighting off infections and diseases. A decrease in WBC count may suggest a weakened immune system or an ongoing infection. It is essential to further investigate the cause of this decrease and consider lifestyle changes or natural remedies to support immune function. Studies have shown that incorporating immune-boosting herbs and foods such as garlic, ginger, and turmeric can help enhance WBC production and function.",
        "Another significant finding is the decrease in your personalized reference ranges for red blood cell count (RBC), hemoglobin (HGB) and  hematocrit (HCT). The parameters of your profile collectively indicate anemia, a condition characterized by a reduced ability of the blood to carry oxygen to the body's tissues. Anemia can lead to fatigue, weakness, and shortness of breath. It is crucial to determine the underlying cause of anemia, which can vary from nutritional deficiencies to chronic diseases. Incorporating iron-rich foods such as leafy greens, legumes, and liver, along with vitamin C-rich foods, can aid in iron absorption and improve RBC production. Additionally, herbal remedies like nettle leaf and yellow dock root can support the body's natural ability to produce healthy red blood cells. It is wise to seek professional nutritional or naturopathic guidance to address the severity of anemia and develop an appropriate treatment plan.",
        "Furthermore, a strong decrease in platelet count (PLT) and mean platelet volume (MPV) has been observed. Platelets are essential for blood clotting and maintaining proper hemostasis. Low platelet count may increase the risk of excessive bleeding and bruising. It is crucial to identify the underlying cause of this decrease and promote platelet production. Certain natural remedies, such as vitamin K-rich foods like kale and spinach, as well as herbs like ginger and ginkgo biloba, are known to support platelet function and production. However, due to the potential seriousness of this finding, it is strongly advised to seek professional help for further evaluation and management of this condition."
      ],
      "recommendations": {
        "dos": {
          "boost_immunity": "To enhance immune function and support WBC production, consider incorporating immune-boosting foods and herbs into your diet. Garlic, ginger, and turmeric are known to have positive effects on immune health. Additionally, ensure you are getting enough rest, managing stress levels, and engaging in regular exercise to support overall immune function. Professional nutritional or naturopathic guidance can help tailor a plan to your specific needs and identify any underlying causes behind the decreased WBC count.",
          "enhance_rbc_production": "To improve RBC production and address anemia, focus on consuming iron-rich foods such as leafy greens, legumes, and liver. Pairing these foods with vitamin C-rich sources, like citrus fruits, can enhance iron absorption. Nettle leaf and yellow dock root are herbal remedies that can support the body's natural ability to produce healthy red blood cells. However, it is essential to seek professional guidance to determine the severity and underlying cause of the anemia and develop an appropriate treatment plan.",
          "support_platelet_function": "To support platelet function and production, include vitamin K-rich foods such as kale and spinach in your diet. Additionally, ginger and ginkgo biloba are herbs known to have positive effects on platelet health. However, due to the potential seriousness of the low platelet count, it is highly recommended to seek professional help for further evaluation and management."
        },
        "donts": {
          "avoid_poor_nutrition": "Avoid a poor diet that lacks essential nutrients for immune function and blood cell production. Processed foods, refined sugars, and excessive caffeine can hinder your body's ability to produce and maintain healthy blood parameters. Opt for whole, nutrient-dense foods instead.",
          "limit_alcohol_consumption": "Excessive alcohol consumption can interfere with the production of blood cells and hinder their function. It is advisable to limit or avoid alcohol to promote optimal blood health.",
          "avoid_smoking": "Smoking is known to have detrimental effects on blood cells and overall health. Quitting smoking or avoiding exposure to smoke can significantly improve your blood parameters. Seek support and resources to aid you in the process of quitting smoking if needed."
        }
      },
      "herbs": [
        {
          "latin": "Rosmarinus officinalis",
          "english": "Rosemary",
          "description": "Rosemary is a powerful herb that has been used for centuries in traditional medicine. It is known for its antioxidant properties, which help protect the body from free radicals. Additionally, rosemary has anti-inflammatory effects that can support overall health. It is often used to improve digestion, boost memory and concentration, and promote hair growth. Incorporating rosemary into your routine can help enhance your health and well-being."
        },
        {
          "latin": "Curcuma longa",
          "english": "Turmeric",
          "description": "Turmeric, commonly known as the golden spice, is a potent herb with incredible healing properties. It contains a compound called curcumin, which has been shown to have powerful anti-inflammatory effects. This can be especially beneficial for reducing inflammation in the body and supporting joint health. Turmeric also has antioxidant properties and can help boost the immune system. Consider adding turmeric to your diet or taking a turmeric supplement to promote overall health and well-being."
        },
        {"and": "many more"}
      ]
    }
  }

References for Data Submission

  • UserMeta Data Class: Detailed information about the user, providing a foundation for personalized health analytics.
  • PathologyReport Data Class: Information on pathology reports, crucial for a comprehensive health analysis.

Sample Required Data:

The required data would look something like:

Post body sample
{
    "date_tested": "2021-07-15",
    "lab_country": "USA",
    "lab_city": "San Francisco",
    "lab_name": "Central SF Pathology",
    "lab_report": {
        "tested_parameters": [
            {
                "name": "CRP",
                "value": 0.17,
                "unit": "mg/dL"
            },
            {
                "name": "CK",
                "value": 34.2,
                "unit": "U/L"
            }
        ]
    }
}

Schema

Below are the TypeScript definitions for the UserMeta and PathologyReport data schemas:

schemas.ts
interface UserMeta {
  gender: string;
  DOB: Date;
  origin_country: string;
  origin_city: string;
  height_cm: number;
  weight_kg: number;
  menopause: boolean;
  // Add additional optional fields as needed
}
 
interface PathologyReportMeasurement {
  parameter: string;
  unit: string;
  value: number;
}
 
interface PathologyReport {
  date_tested: Date;
  lab_country: string;
  lab_city: string;
  lab_name: string;
  measurements: PathologyReportMeasurement[];
  well_rested?: boolean;
  dizzy?: boolean;
  headache?: string;
  mood?: string;
  hair_loss?: string;
  bloating?: number;
  exercise?: number;
  anxiety?: string;
  smoking?: string;
  drinking?: string;
  medication?: string[];
  // Add additional optional fields as needed
}

Additionally, each client receives a thorough and comprehensive list of all available endpoints at the conclusion of the onboarding process, complete with detailed descriptions and usage instructions. This curated documentation is tailored to provide our partners with the knowledge and tools necessary to seamlessly integrate and fully utilize the robust capabilities of our API suite from day one.