MEDSAPI Dynamic Health Documentation Title

 

 

Browse our guides and interact with our API reference for more information about MEDSAPI Dynamic Health. Try MEDSAPI Dynamic Health and learn about core concepts.

 

 

 

 

Dyna Search Dynamic Health Content Using POST

The Dyna POST /v1/content/search/rag endpoint allows you to question Dynamic Health content. It uses a streaming response so that the answer can begin to be displayed as soon as the response begins. Dyna uses retrieval augmented generation (RAG) to query Dynamic Health content to create a thorough, "guard railed" and reliable response.

Basic Dyna Search

To Perform a Basic Dyna Search (example):

Gather the following information for the request:

  • A query to ask OR
  • A question to ask.
  • The following headers:
    • Authorization: a personalized access token
    • x-eis-id-token: an ID token
    • Connection: keep-alive
    • Cache-Control: no-cache
    • X-Accel-Buffering-Type: no

A query would be used as a first attempt at getting an answer.  It might be used for instance when the user has entered terms into a search box.  Dyna will take the terms and formulate a question.  A question would be used when Dyna has suggested questions to ask.  More details on this in Using the Question Field in a Request. If both a query and a question are included in the request, then only the question will be sent to Dyna for an answer.

Request

POST 'https://apis.ebsco.com/medsapi-dynamic-health/v1/content/search/rag'

Request Body

{
  "criteria": {
     "query": "How do I evaluate an Infant for Congenital Heart Disease"
  }
}

The Dyna search will respond with multiple lines before closing the connection.  Each response will minimally look like this:

data: {
  "viewModel":{...}
}\n\n

Prepending "data:" to each response is a technique used in Server-Sent Events (SSE). SSE is a standard that allows servers to push updates to clients over HTTP or HTTPS. The updates are sent as a stream of text data, where each message is separated by a pair of newline characters. This helps in message identification, allows for real time updates and network error handling. Note that what's shown looks like a string followed by JSON.  This format is to make it easier to read in this documentation.  In actuality, the response is a string.  It will need to be parsed to convert it into JSON format.

Example First Response

Here's an example of a first response to the request above.

data: {
    "viewModel": {
        "supported": true,
        "query": "How do I evaluate an Infant for Congenital Heart Disease?",
        "question": "",
        "answer": "",
        "answerFound": false,
        "references": {
            "hasNotes": false,
            "results": []
        },
        "recommendedContent": {
            "hasNotes": false,
            "results": []
        },
        "recommendedQuestions": [],
        "telemetryData": {
            "searchTerm": "How do I evaluate an Infant for Congenital Heart Disease (CHD)-389hsqogd6",
            "question": ""
        },
        "streamComplete": false
    }
}

In this first response, note that the answer is empty and streamComplete flag is set to false.  Your code should inspect each response and expect more responses until the streamComplete flag is true.   Several of these may occur while Dyna begins to process the question, with minor differences. For example, the next message might contain all the fields above plus the question that Dyna will use to get the answer. Note that the answer may contain any valid HTML. However, these tags are more likely to occur: <ul>,<li>,<ol>,<strong>,<b>,<em>,<sub>,<sup>,<a>, and <br>.  <table> may occur in the future. 

Example Secondary Responses

data:{
  "viewModel":{
     "answerStream":"E"
   }
}

Secondary responses are generally short messages which enable the calling application to begin displaying the response as it is returned. When output to the UI, they will contain the complete answer that Dyna has found.

Example Answer Found Response

data:{
  "viewModel": {
      "supported": true,
      "query": "How do I evaluate an Infant for Congenital Heart Disease",
      "question": "How do I evaluate an Infant for Congenital Heart Disease?",
      "answer": " Management and treatment of diabetes focus on maintaining strict glycemic control to improve patient outcomes and quality of life, and reduce complications. For Type 1 diabetes, treatment includes insulin therapy with multiple daily injections or continuous subcutaneous insulin infusion, along with hypertension and lipid management. For Type 2 diabetes, treatment involves lifestyle modifications such as healthy diet and exercise, and pharmacological treatments like Metformin or insulin if needed. Both types require regular monitoring for complications and comprehensive patient education on self-management, including blood glucose monitoring and lifestyle changes. ",
      "answerFound": true,
      "references": {
          "hasNotes": false,
          "results": []
      },
      "recommendedContent": {
          "hasNotes": false,
          "results": []
      },
      "recommendedQuestions": [],
      "telemetryData": {
          "searchTerm": "How do I evaluate an Infant for Congenital Heart Disease",
          "question": "How do I evaluate an Infant for Congenital Heart Disease"
      }
  }
}

The answerFound flag is set to true in this response, and the answer is now displayed in its entirety.  Note though, that streamComplete is not set to true, yet (and in this message is missing altogether).

Final Response

data: {
  "viewModel": {
      "supported": true,
      "query": "How do I evaluate an Infant for Congenital Heart Disease",
      "question": "How do I evaluate an Infant for Congenital Heart Disease?",
      "answer": " Evaluation of congenital heart disease in infants involves several steps and tests:<br><ul><li><strong>Patient History:</strong> Review birth history, genetic testing, and risk factors such as maternal diabetes, alcohol consumption, and family history of congenital heart disease.<sup><span data-ref-id='m76iu2414r'>1</span></sup></li><li><strong>Physical Assessment:</strong> Look for signs like tachypnea, tachycardia, hypotension, delayed capillary refill, edema, difficulty feeding, and irritability.<sup><span data-ref-id='tbb1mrujjo'>2</span></sup></li><li><strong>Screening Tests:</strong> Perform pulse oximetry on the right hand and foot to measure oxygen saturation. Immediate pass if SpO<sub>2</sub> is ≥95% and the difference between hand and foot is ≤3%. Immediate fail if SpO<sub>2</sub> is <90%.<sup><span data-ref-id='tbb1mrujjo'>2</span></sup></li><li><strong>Imaging Tests:</strong> Use 2D echocardiogram, chest x-ray, and cardiac catheterization to evaluate heart structure and function.<sup><span data-ref-id='le6iuc9jl7'>3</span></sup></li></ul>",
      "answerFound": true,
      "references": {
          "hasNotes": false,
          "results": [
              {
                  "slug": "/evaluation/evaluation-of-the-infant-for-congenital-heart-disease-chd",
                  "title": "Evaluation of the Infant for Congenital Heart Disease (CHD) >",
                  "sections": [
                      {
                          "title": "Physical exam for screening",
                          "slug": "/evaluation/evaluation-of-the-infant-for-congenital-heart-disease-chd#PHYSICAL_EXAM_FOR_SCREENING",
                          "index": "1",
                          "breadcrumb": "Screening >",
                          "metadata": {
                              "title": "Evaluation of the Infant for Congenital Heart Disease (CHD)",
                              "navigateTo": [
                                  "Screening",
                                  "Physical exam for screening"
                              ],
                              "id": "T566082",
                              "pubType": {
                                  "pretty": "Evaluation",
                                  "id": "evaluation",
                                  "group": "articles"
                              }
                          }
                      }
                  ],
                  "hasNote": false,
                  "metadata": {
                      "title": "Evaluation of the Infant for Congenital Heart Disease (CHD)",
                      "id": "T566082"
                  }
              }
          ]
      },
      "recommendedContent": {
          "hasNotes": false,
          "results": []
      },
      "recommendedQuestions": [],
      "telemetryData": {
          "searchTerm": "How do I evaluate an Infant for Congenital Heart Disease",
          "question": "How do I evaluate an Infant for Congenital Heart Disease?",
          "pageToken": "10bb8bcc-c8a8-470e-ac39-2ea983559de1",
          "searchTimeInMs": 11572,
          "ragResponseTimeInMs": 9409,
          "userIntentTimeInMs": 2061,
          "userIntentCategory": "DH_ASSESSMENT"
      },
      "streamComplete": true
  }
}

Here you will note that streamComplete is true, and now in addition to the answer, references are included.

If you see an index in the reference section, it can be matched up to the span in the answer with the same number.  If no index is included, then there is no direct reference to the answer. (For brevity, in this example only the first section is included.)

Response with Recommended Content with Workplace Notes

data: {
  "viewModel": {
    "supported": true,
    "query": "How can I suction a Tracheostomy Tube Using an Open System in Adults?",
    "question": "How do I suction a tracheostomy tube using an open system in adults?",
    "answer": " It is crucial to follow the detailed steps and precautions recommended for suctioning a tracheostomy tube using an open system in adults, as summarizing these steps could omit critical details necessary for patient safety. ",
    "answerFound": true,
    "workplaceNotes": {
      "message": "A note from your workplace is included that should be reviewed. (Notes are not included in the Dyna AI response)"
    },
    "references": {
      "hasNotes": false,
      "results": [
        
      ]
    },
    "recommendedContent": {
      "hasNotes": true,
      "results": [
        {
          "title": "Suctioning a Tracheostomy Tube Using an Open System in Adults",
          "slug": "/nursing-skills/suctioning-a-tracheostomy-tube-using-an-open-system-in-adults",
          "hasNote": true,
          "id": "T913443"
        }
      ]
    },
    "recommendedQuestions": [],
    "telemetryData": {
      "searchTerm": "How can I suction a Tracheostomy Tube Using an Open System in Adults?",
      "question": "How do I suction a tracheostomy tube using an open system in adults?",
      "pageToken": "c929e3b7-4af6-447f-a2cf-01a9f06d289e",
      "searchTimeInMs": 4855,
      "ragResponseTimeInMs": 3321,
      "userIntentTimeInMs": 1460,
      "userIntentCategory": "DH_PERFORMING_SKILL"
    },
    "streamComplete": true
  }
}

Some Dynamic Health content includes notes from their workplace.  When Dyna is asked a question which returns content in the recommended content or reference section of the response, the hasNotes flag will be set to true.  Then the individual item with that note will have the hasNote flag set to true.  The workplaceNotes message will convey information that can be used to display to the user.

Response with Workplace Skill

{
  "viewModel": {
    "supported": true,
    "query": "Risk Factors for Heart Laceration",
    "question": "What are the risk factors for heart laceration?",
    "answer": " Cardiac laceration can occur at any age and gender group. Risk factors include puncture or blunt injury to the cardiac box, history of coronary artery disease, particularly recent myocardial infarction, and history of bleeding disorder. ",
    "answerFound": true,
   "workplaceSkills": {
      "message": "One or more related 'Your Workplace Skills' exist and are not included in this Dyna AI response",
      "results": [
        {
          "url": "/workplace-skills/c1723211328438-risk-factors-for-heart-laceration",
          "title": "Risk Factors for Heart Laceration",
          "id": "C1723211328438"
        }
      ]
    },
    "references": {
      "hasNotes": false,
      "results": [
        {
          "slug": "/diseases-and-conditions/heart-laceration-1",
          "title": "Heart Laceration >",
          "sections": [
            {
              "title": "Risk Factors",
              "slug": "/diseases-and-conditions/heart-laceration-1#GUID-3A49395A-59BA-43F0-BE03-FC82D9549E92",
              "breadcrumb": null,
              "metadata": {
                "title": "Heart Laceration",
                "navigateTo": [
                  "Risk Factors"
                ],
                "id": "T1611927357188",
                "pubType": {
                  "pretty": "Disease/Condition",
                  "id": "diseasecondition",
                  "group": "articles"
                }
              }
            }
          ],
          "hasNote": false,
          "metadata": {
            "title": "Heart Laceration",
            "id": "T1611927357188"
          }
        }
      ]
    },
    "recommendedContent": {
      "hasNotes": false,
      "results": [
        
      ]
    },
    "recommendedQuestions": [],
    "telemetryData": {
      "searchTerm": "Risk Factors for Heart Laceration",
      "question": "What are the risk factors for heart laceration?",
      "pageToken": "82e869d2-2c80-4316-a0f0-7e3e905bed7e",
      "searchTimeInMs": 4807,
      "ragResponseTimeInMs": 3465,
      "userIntentTimeInMs": 1150,
      "userIntentCategory": "DH_DISEASE"
    },
    "streamComplete": true
  }
}

Some responses may include workplace skills specific to the institution. These are placed in the workplace skills section of the response. 

References with Workplace Notes

Some response may contain references which have workplace notes.  For example a query for "Should a pediatric patient be restrained" might return somethiing like this:

{
  "viewModel": {
    "supported": true,
    "query": "Should a pediatric patient be restrained",
    "question": "Is it appropriate to restrain a pediatric patient?",
    "answer": " Restraining pediatric patients is a stressful and undesirable action that can be emotionally and physically traumatizing. It should be used as a last resort and in the least restrictive manner for the shortest duration necessary. <br><ul><li>Indications: To protect the patient from harming themselves or others, or to allow clinicians to safely perform procedures or maintain the position of medical equipment.</li><li>Contraindications: Restraints should be avoided if alternative measures such as calming strategies or pharmacologic alternatives can be used effectively.</li><li>Desired Outcomes: The patient is protected from harm, does not experience complications from restraint use, and is restrained safely and effectively in the least restrictive manner for the shortest duration necessary.</li></ul> ",
    "answerFound": true,
    "workplaceNotes": {
      "message": "A note from your workplace is included that should be reviewed. (Notes are not included in the Dyna AI response)"
    },
    "references": {
      "title": "Dynamic Health Sources Used",
      "hasNotes": true,
      "results": [
        {
          "slug": "/nursing-skills/using-bed-and-chair-restraints-with-pediatric-patients-1",
          "title": "Using Bed and Chair Restraints With Pediatric Patients >",
          "sections": [
            {
              "title": "Preprocedure Steps",
              "slug": "/nursing-skills/using-bed-and-chair-restraints-with-pediatric-patients-1#PRE_PROCEDURE_STEPS",
              "metadata": {
                "title": "Using Bed and Chair Restraints With Pediatric Patients",
                "navigateTo": [
                  "Procedure",
                  "Preprocedure Steps"
                ],
                "id": "T913212"
              }
            }
          ],
          "hasNote": true,
          "metadata": {
            "title": "Using Bed and Chair Restraints With Pediatric Patients",
            "id": "T913212"
          }
        }
      ]
    },
    "recommendedQuestions": {
      "title": "Related Questions",
      "results": []
    },
    "recommendedContent": {
      "title": "Recommended Content",
      "hasNotes": false,
      "results": []
    },
    "telemetryData": {
      "searchTerm": "Should a pediatric patient be restraineds",
      "question": "Is it appropriate to restrain a pediatric patient?",
      "pageToken": "b6f5a719-6552-4c17-8a32-8b53e51585e7",
      "searchTimeInMs": 9858,
      "ragResponseTimeInMs": 8993,
      "userIntentTimeInMs": 795,
      "answerNotFound": false,
      "userIntentCategory": "DH_GENERAL_INFORMATION"
    },
    "streamComplete": true
  }
}

Using the Question Field in a Request

Some responses may include recommended questions.  These are questions related to the initial query.  The user interface should use these to create a link containing the question.  When the user clicks on the link, it should generate a new Dyna request which would contain the recommended question inthe question field.  No query would be used, since this question has already been prepared for Dyna.  

Suppose a user asks about a colostomy.

{
  "criteria": {
    "query": "What is a colostomy?"
  }
}

The response might be:

{
  "viewModel": {
    "supported": true,
    "query": "What is a colostomy?",
    "question": "What is a colostomy?",
    "answer": " A colostomy is a surgical opening of the colon to the abdominal wall, created for the discharge of stool. It is used to manage complications related to diseases such as colorectal cancer, inflammatory bowel disease, and traumatic injury. The procedure can involve different parts of the colon and may be temporary or permanent. ",
    "answerFound": true,
    "references": {
      "hasNotes": false,
      "results": [
        {
          "slug": "/care-intervention/colostomy-interventions",
          "title": "Colostomy Interventions >",
          "sections": [
            {
              "title": "Overview of Disease/Condition",
              "slug": "/care-intervention/colostomy-interventions",
              "anchor": "GUID-EB76F861-1E44-4ADA-AAFE-E18BC3883ED0",
              "breadcrumb": null,
              "metadata": {
                "title": "Colostomy Interventions",
                "navigateTo": [
                  "Overview of Disease/Condition"
                ],
                "id": "T1596713612267",
                "pubType": {
                  "pretty": "Care Intervention",
                  "id": "careIntervention",
                  "group": "articles"
                }
              }
            }
          ],
          "hasNote": false,
          "metadata": {
            "title": "Colostomy Interventions",
            "id": "T1596713612267"
          }
        }
      ]
    },
    "recommendedQuestions": [
      "How do you remove a colostomy appliance?",
      "How do you irrigate a colostomy?",
      "What are the common complications associated with a colostomy?"
    ],
    "recommendedContent": {
      "results": [],
      "hasNotes": false
    },
    "telemetryData": {
      "searchTerm": "What is a colostomy?",
      "question": "What is a colostomy?",
      "pageToken": "4b7f1660-e89e-4a8c-9418-1e3f7c3f9c0a",
      "searchTimeInMs": 4829,
      "ragResponseTimeInMs": 4002,
      "userIntentTimeInMs": 752,
      "userIntentCategory": "DH_DEVICE_PROCEDURE"
    },
    "streamComplete": true
  }
}

Notice the recommended questions, which can then be used for a more details

{
  "criteria": {
    "question": "How do you irrigate a colostomy?"
  }
}

The response is just a regular response.

{
  "viewModel": {
    "supported": true,
    "query": "How do you irrigate a colostomy?",
    "question": "How is a colostomy irrigated?",
    "answer": " It is crucial to follow the specific steps for irrigating a colostomy as outlined in the recommended content. Summarizing these steps could omit critical details necessary for patient safety. Please refer to the recommended best practices for irrigating a colostomy. ",
    "answerFound": true,
    "references": {
      "hasNotes": false,
      "results": []
    },
    "recommendedContent": {
      "results": [
        {
          "title": "Irrigating a Colostomy",
          "slug": "/nursing-skills/irrigating-a-colostomy",
          "hasNote": false,
          "id": "T915770"
        }
      ],
      "hasNotes": false
    },
    "recommendedQuestions": [],
    "telemetryData": {
      "searchTerm": "How do you irrigate a colostomy?",
      "question": "How is a colostomy irrigated?",
      "pageToken": "674de315-83ba-4f5d-b07f-71c154c4bd9b",
      "searchTimeInMs": 4484,
      "ragResponseTimeInMs": 3450,
      "userIntentTimeInMs": 961,
      "userIntentCategory": "DH_PERFORMING_SKILL"
    },
    "streamComplete": true
  }
}

Notice the recommended questions, which can then be used for a more details.

HTML in an Answer

When the user has asked a question the response may have html within it.  The caller can expect any valid HTML in the answer. However, these tags are more likely to occur: <ul>,<li>,<ol>,<strong>,<b>,<em>,<sub>,<sup>,<a>, and <br>.  For example:

{
  "criteria": {
    "query": "chads 2 vac score"
  }
}

The Answer would look like this:

"answer":" The CHA<sub>2</sub>DS<sub>2</sub>-VASc score is a clinical prediction tool used to estimate the risk of stroke in patients with atrial fibrillation. It assigns points based on the presence of certain risk factors:<br><ul><li>Congestive heart failure or left ventricular dysfunction - 1 point</li><li>Hypertension - 1 point</li><li>Age ≥ 75 years - 2 points</li><li>Diabetes mellitus....
 

Disclaimers

It is possible that an answer may contain a disclaimer.  In this case, the response will direct the user to locate a page with more information.

{
  "criteria": {
    "query": "What are the potential adverse effects of suvorexant?"
  }
}

{
  "viewModel": {
    "supported": true,
    "query": "What are the potential adverse effects of suvorexant?",
    "question": "What are the potential adverse effects of suvorexant?",
    "answer": "For more detailed information about adverse effects, use the drug monograph.",
    "answerFound": true,
    "references": {
      "hasNotes": false,
      "results": []
    },
    "recommendedContent": {
      "results": [],
      "hasNotes": false
    },
    "recommendedQuestions": [],
    "telemetryData": {
      "searchTerm": "What are the potential adverse effects of suvorexant?",
      "question": "What are the potential adverse effects of suvorexant?",
      "pageToken": "8c1ac46f-0b8d-4297-96cb-7dc30cb4a5ed",
      "searchTimeInMs": 1062,
      "ragResponseTimeInMs": 0,
      "userIntentTimeInMs": 920,
      "userIntentCategory": "DH_ADVERSE_EFFECTS"
    },
    "streamComplete": true
  }
}

The answer directs the user to check the Drug Monograph instead. The userIntentCategory further identifies the type of disclaimer. Some other examples:

  • What dose of augmentin should I use to treat acute otitis media?
    • "answer":"For detailed medication dosing information, please use the drug monograph."
    • "userIntentCategory":"DH_DOSE"

Single Concept Query

Your application may want to send a Dyna query based on a single word or words entered in the search box.  This would be sent in the query field of the request body.  If there is enough context, the Dyna search will return a response by formulating a question based on the terms.  But if only a single term is provided without context, Dyna may not be able to form a question and will not return an answer.  For example, a query for "copd":

{
  "criteria": {
     "query": "copd"
  }
}

Response

{
  "viewModel": {
    "supported": false,
    "query": "copd",
    "answer": "We're sorry but we were unable to find the answer in Dynamic Health.",
    "answerFound": false,
    "references": {
      "hasNotes": false,
      "results": []
    },
    "recommendedContent": {
      "hasNotes": false,
      "results": []
    },
    "recommendedQuestions": [],
    "telemetryData": {
      "searchTerm": "copd",
      "searchTimeInMs": 0,
      "ragResponseTimeInMs": 0,
      "userIntentTimeInMs": 0,
      "error": "Single concept query is not supported"
    },
    "streamComplete": true
  }
}

The response includes a flag, "supported" which, when false, indicates that there is not enough details in the query to get an answer, but the user can be prompted to add more details to get an answer which is used for a new request.  For example, the user could type "copd treatment" and would get an answer.

 

Request for Non-Medical Information

Request for information that falls outside of Dynamic Health will fail.

{
  "criteria": {
     "query": "How do I make a peach cobbler?"
  }
}
{
  "viewModel": {
    "supported": true,
    "query": "How do I make a peach cobbler?",
    "answer": "We're sorry but we were unable to find the answer in Dynamic Health.",
    "answerFound": false,
    "references": {
      "hasNotes": false,
      "results": []
    },
    "recommendedContent": {
      "hasNotes": false,
      "results": []
    },
    "recommendedQuestions": [],
    "telemetryData": {
      "searchTerm": "How do I make a peach cobbler?",
      "searchTimeInMs": 0,
      "ragResponseTimeInMs": 0,
      "userIntentTimeInMs": 0,
      "error": "We apologize, but your query has been flagged as potentially unsuitable for our medical product."
    },
    "streamComplete": true
  }
}

The error indicates that the answer can't be found in our content.

Internal System Error

In the event that Dyna was unable to complete, you may reiceive this error once the streamin has started. (Additional status codes below)

{
  "viewModel": {
    "query": "copd treatment",
    "answer": "",
    "answerFound": false,
    "telemetryData": {
      "error": "System error"
    },
    "streamComplete": true
  }
}

 

The Dynamic Health search endpoint can return one of the error response codes.