Skip to main content

Health LLMs

Overview​

The Health LLMs API gives you access to various specialists that are able to answer questions about a user's health. If a user ID is not passed, the backend will generate one randomly.

Base URL​

The base URLs for the AI Specialists API are

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

API Endpoints​

Getting a list of available specialists​

  • Endpoint: /aispecialists/api/get-specialist-names
  • Method: GET
  • Description: This endpoint allows you to get a list of available specialist names and you can use in the below POST request

Request Parameters None

Example Request:

curl --location '${BASE_URL}/aispecialists/api/get-specialist-names' \
--header 'Content-Type: application/json' \
--header 'api-key: ••••••' \
--data '''
}'

Example Response

[
    {
        "id": "1",
        "image": "pulmonologist_image.png",
        "medical_specialist": true,
        "name": "Pulmonologist AI"
    },
    {
        "id": "2",
        "image": "haematologist_image.png",
        "medical_specialist": true,
        "name": "Haematologist AI"
    },
    {
        "id": "3",
        "image": "dermatologist_image.png",
        "medical_specialist": true,
        "name": "Dermatologist AI"
    },
    {
        "id": "4",
        "image": "urologist_image.png",
        "medical_specialist": true,
        "name": "Urologist AI"
    }
]

Initialize Specialist Endpoint​

  • Endpoint: /aispecialists/api/init-specialist
  • Method: POST
  • Description: This endpoint builds and cache the knowledge of a user which will be used by the ask-specialist endpoint.

Request Parameters:

  • user (string, optional): The unique UUID identifier of the user.

Example Request:

curl --location '${BASE_URL}/aispecialists/api/init-specialist' \
--header 'Content-Type: application/json' \
--header 'api-key: ••••••' \
--data '{
    "user": "••••••",
}'

Example Response:

{
    "status": "success"
}

Ask Specialist Endpoint​

  • Endpoint: /aispecialists/api/ask-specialist
  • Method: POST
  • Description: This endpoint allows a user to ask a AI health specialist about their health.

Request Parameters:

  • specialist (string): The name of the AI health specialist.
  • message (string): The user's question or request.
  • api_key (string): Secure secret key.
  • user (string, optional): The unique UUID identifier of the user.
  • session_token (string, optional): The session token for maintaining context throughout the conversation.

Example Request:

curl --location '${BASE_URL}/aispecialists/api/ask-specialist' \
--header 'Content-Type: application/json' \
--header 'api-key: ••••••' \
--data '{
    "specialist": "Pulmonologist AI",
    "message": "Can you allow me to check my vitals?",
    "user": "••••••",
    "session_token": "••••••"
}'

Example Response:

{
    "actions_required": [
        "vitals_ai"
    ],
    "answer": "Absolutely, I can assist you with that. Please go ahead and perform the 'vitals_ai' assessment.",
    "next_suggested_queries": [
        "What do my vital signs results mean?",
        "Can I get an interpretation of my vitals?"
    ],
    "session_token": "db07ab1d-6a2f-4941-ae78-0e484edce82a",
    "sources": ""
}

Ask General Health AI Endpoint​

  • Endpoint: /aispecialists/api/ask-general-ai
  • Method: POST
  • Description: This endpoint allows a user to ask the general AI health specialist about their health.

Request Parameters:

  • message (string): The user's question or request.
  • user (string, optional): The unique UUID identifier of the user.
  • api_key (string): Secure secret key.
  • session_token (string, optional): The session token for maintaining context throughout the conversation.

Example Request:

curl --location '${BASE_URL}/aispecialists/api/ask-general-ai' \
--header 'Content-Type: application/json' \
--header 'api-key: ••••••' \
--data '{
    "message": "Can you allow me to check my vitals?",
    "user": "••••••",
    "session_token": "••••••"
}'

Example Response:

{
    "actions_required": [
        "vitals_ai"
    ],
    "answer": "Absolutely, I can assist you with that. Please go ahead and perform the 'vitals_ai' assessment.",
    "next_suggested_queries": [
        "What do my vital signs results mean?",
        "Can I get an interpretation of my vitals?"
    ],
    "session_token": "••••••",
    "sources": ""
}

Response Fields:

  • actions_required (list): A list of actions that the specialist recommends the user to take.
  • answer (string): The answer to the user's question.
  • next_suggested_queries (list): A list of suggested queries for the user to ask.
  • session_token (string): The session token for maintaining context throughout the conversation.
  • sources (string): A list of sources that the specialist used to answer their final question

Check API Health​

  • Endpoint: /aispecialists/api/health
  • Method: GET
  • Description: This endpoint allows a user to check the health status of the API for possible outages.

Request Parameters: None

Example Request:

curl --location '${BASE_URL}/aispecialists/api/health' \
--header 'Content-Type: application/json' \
--data '''

Example Response:

{
    "status": "AI Specialists API healthy"
}

Response Fields:

  • status (str): Status of the API.

Web Socket​

Ask Specialist​

  • Request Channel: ask-specialist
  • Description: This endpoint allows a user to ask AI health specialist about their health.

Request Parameters:

  • specialist_name (string): The name of the AI health specialist.
  • message (string): The user's question or request.
  • api_key (string): Secure secret key.
  • user_id (string, optional): The unique UUID identifier of the user.
  • session_token (string, optional): The session token for maintaining context throughout the conversation.

Response

  1. Channel: response

    • description: LLM Response to users query
    • Example:
    Absolutely, I can assist you with that. Please go ahead and perform the 'vitals_ai' assessment.

  2. Channel: complete_response

    • description: LLM Response including action, sources, suggested queries etc.
    • Example:
    {
        "actions_required": [
            "vitals_ai"
        ],
        "answer": "Absolutely, I can assist you with that. Please go ahead and perform the 'vitals_ai' assessment.",
        "next_suggested_queries": [
            "What do my vital signs results mean?",
            "Can I get an interpretation of my vitals?"
        ],
        "session_token": "db07ab1d-6a2f-4941-ae78-0e484edce82a",
        "sources": ""
    }

Ask General AI​

  • Request Channel: ask-general-ai
  • Description: This endpoint allows a user to ask General AI about their health.

Request Parameters:

  • message (string): The user's question or request.
  • api_key (string): secure secret key.
  • user_id (string, optional): The unique UUID identifier of the user.
  • session_token (string, optional): The session token for maintaining context throughout the conversation.

Response

  1. Channel: response

    • description: LLM Response to users query
    • Example:
    Absolutely, I can assist you with that. Please go ahead and perform the 'vitals_ai' assessment.

  2. Channel: complete_response

    • description: LLM Response including action, sources, suggested queries etc.

    • Example:

    {
        "actions_required": [
            "vitals_ai"
        ],
        "answer": "Absolutely, I can assist you with that. Please go ahead and perform the 'vitals_ai' assessment.",
        "next_suggested_queries": [
            "What do my vital signs results mean?",
            "Can I get an interpretation of my vitals?"
        ],
        "session_token": "db07ab1d-6a2f-4941-ae78-0e484edce82a",
        "sources": ""
    }