MEDS API Documentation Title

 

 

Browse our guides and interact with our API reference for more information about MEDSAPI DynaMed/DynaMedex. Try MEDSAPI DynaMed/DynaMedex and learn about core concepts.

 

 

 

 

Dyna Search DynaMed/DynaMedex Content Using POST

The Dyna API POST /v1/content/search/rag endpoint allows you to question DynaMed and DynaMedex 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 to query DynaMed or DynaMedex 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 
  • 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. 

Request

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

Request Body

{
  "criteria": {
     "query": "congenital heart disease evaluation"
  }
}

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 actuallity, 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": "congenital heart disease evaluation",
        "question": "",
        "answer": "",
        "answerFound": false,
        "references": {
            "results": []
        },
        "telemetryData": {
            "searchTerm": "congenital heart disease evaluation",
            "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>,<br>.  <table> may occur in the future.

Example Secondary Responses

data:{
  "viewModel":{
     "answerStream":"I"
   }
}

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

Example Answer Found Response

data:{
  "viewModel": {
      "supported": true,
      "query": "congenital heart disease evaluation",
      "question": "What is the approach to evaluating congenital heart disease?",
      "answer": " In infants, the evaluation of congenital heart disease (CHD) involves several steps. Initially, CHD may present on fetal ultrasound or after birth with symptoms such as an asymptomatic murmur, cyanosis, or heart failure. A thorough physical exam is crucial, including vital signs, skin inspection, cardiovascular examination, and lung and abdominal exams. Pulse oximetry should be performed at both preductal and postductal sites. An experienced pediatric clinician or cardiologist should evaluate any asymptomatic murmur before further testing. Confirmatory diagnosis is typically done via echocardiogram, with MRI, CT, or cardiac catheterization as additional options. Other helpful tests include electrocardiogram, chest x-ray, and hyperoxia test.",
      "answerFound": true,
      "references": {
          "results": []
      },
      "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": "congenital heart disease evaluation",
      "question": "What is the approach to evaluating congenital heart disease?",
      "answer": "In infants, the evaluation of congenital heart disease (CHD) involves several steps. Initially, CHD may present on fetal ultrasound or after birth with symptoms such as an asymptomatic murmur, cyanosis, or heart failure. A thorough physical exam is crucial, including vital signs, skin inspection, cardiovascular examination, and lung and abdominal exams. Pulse oximetry should be performed at both preductal and postductal sites. An experienced pediatric clinician or cardiologist should evaluate any asymptomatic murmur before further testing. Confirmatory diagnosis is typically done via echocardiogram, with MRI, CT, or cardiac catheterization as additional options. Other helpful tests include electrocardiogram, chest x-ray, and hyperoxia test.",
      "answerFound": true,
      "references": {
          "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",
                          "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"
                              }
                          }
                      }
                  ],
                  "metadata": {
                      "title": "Evaluation of the Infant for Congenital Heart Disease (CHD)",
                      "id": "T566082"
                  }
              }
          ]
      },
      "telemetryData": {
          "searchTerm": "congenital heart disease evaluation",
          "question": "What is the approach to evaluating congenital heart disease?",
          "pageToken": "10bb8bcc-c8a8-470e-ac39-2ea983559de1",
          "searchTimeInMs": 11572,
          "ragResponseTimeInMs": 9409,
          "userIntentTimeInMs": 2061,
          "userIntentCategory": "DM_DIAGNOSTIC_EVAL_TESTING"
      },
      "streamComplete": true
  }
}

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

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 "zoloft":

Request

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

Request Body

{
  "criteria": {
     "query": "zoloft"
  }
}

Final Single Query Success Response

{
  "viewModel": {
    "supported": false,
    "query": "zoloft",
    "answer": "We're sorry but we were unable to find the answer in DynaMedex.",
    "answerFound": true,
    "references": {
      "results": []
    },
    "telemetryData": {
      "searchTerm": "zoloft",
      "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 "zoloft dosing" and would get an answer.

Superscripts in a Query

When the user has asked a question that returns a superscripted field in the answer, he will receive a response which has html to show the superscipts.  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....

Request for Non-Medical Information

Request for information that falls outside of DynaMed or DynaMedex guardrailed content 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 DynaMed.",
    "answerFound": false,
    "references": {
      "results": []
    },
    "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.

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": "Is it safe to co-administer methadone and rifampin to a patient?"
  }
}

{
  "viewModel": {
    "supported": true,
    "query": "Is it safe to co-administer methadone and rifampin to a patient?",
    "question": "Is it safe to co-administer methadone and rifampin to a patient?",
    "answer": "Please use the Drug Interaction Checker for detailed drug interaction information.",
    "answerFound": true,
    "references": {
      "results": [
        
      ]
    },
    "telemetryData": {
      "searchTerm": "Is it safe to co-administer methadone and rifampin to a patient?",
      "question": "Is it safe to co-administer methadone and rifampin to a patient?",
      "pageToken": "ba7714c9-5b45-4974-88f0-96829136f449",
      "searchTimeInMs": 2078,
      "ragResponseTimeInMs": 0,
      "userIntentTimeInMs": 1980,
      "userIntentCategory": "DM_INTERACTIONS"
    },
    "streamComplete": true
  }
}

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

  • What is the appropriate dose of caffeine for treating apnea of maturity?
    • "answer":"Please use NeoFax Pediatrics for more detailed information regarding pediatric and neonatal dosing."
    • "userIntentCategory":"DM_DOSE_PEDS"
  • Are meropenem and midazolam IV compatible?
    • "answer":"Please use the IV Compatibility Module for detailed IV compatibility information."
    • "userIntentCategory":"DM_IV_COMPATIBILITY"
  • What are the treatment options for strep throat in a patient with an allergy to amoxicillin?
    • "answer":"We're sorry but we were unable to find the answer in DynaMedex"
    • "userIntentCategory":"DM_ALLERGY"
  • Are any medications in the R-CHOP regimen classified as vesicants?
    • "answer":"We're sorry but we were unable to find the answer in DynaMedex"
    • "userIntentCategory":"DM_CHEMO"

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": "",
    "answerNotFound": true,
    "telemetryData": {
      "error": "System error"
    },
    "streamComplete": true
  }
}

 

The DynaMed/DynaMedex search/rag endpoint can return one of the error response codes.