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 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 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. (Note that only the Authorization header and x-eis-id-token are passed when using an OpenAPI/Swagger spec. This will cause the results to not stream via the swagger output).

Request

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

Request Body

{
  "criteria": {
     "query": "what is COPD"
  }
}

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": "what is copd?",
    "question": "What is the definition of COPD?",
    "answer": "",
    "answerFound": false,
    "references": {
      "title": "DynaMedex Sources Used",
      "results": [
        
      ]
    },
    "recommendedQuestions": [],
    "recommendedContent": {
      "title": "Recommended Content",
      "results": [
        
      ]
    },
    "telemetryData": {
      "searchTerm": "what is copd?",
      "question": "What is the definition of COPD?",
      "answerFound": false
    },
    "followupQuestions": {
      "enabled": true
    },
    "streamComplete": false
  }
}

In this first response, note that the answer is empty, answerFound  is false 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":"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": "what is copd?",
    "question": "What is the definition of COPD?",
    "answer": " Chronic obstructive pulmonary disease (COPD) is a common, preventable, and treatable pulmonary disease generally caused by significant long-term cumulative exposure to noxious particles or gases (such as cigarette smoking) combined with other factors including genetics, airway hyperresponsiveness, and abnormal lung development. It results in airflow limitations due to chronic airway inflammation and/or parenchymal destruction (emphysema). COPD is characterized by chronic respiratory symptoms such as dyspnea, cough, and sputum production due to airway abnormalities and/or abnormal alveoli causing persistent, often progressive, airflow obstruction.",
    "references": {
      "title": "DynaMedex Sources Used",
      "results": [
        
      ]
    },
    "recommendedQuestions": [],
    "recommendedContent": {
      "title": "Recommended Content",
      "results": [
        
      ]
    },
    "telemetryData": {
      "searchTerm": "what is copd?",
      "question": "What is the definition of COPD?"
    },
    "followupQuestions": {
      "enabled": true
    }
  }
}

The answer is available and 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": "what is copd?",
    "question": "What is the definition of COPD?",
    "answer": " Chronic obstructive pulmonary disease (COPD) is a common, preventable, and treatable pulmonary disease generally caused by significant long-term cumulative exposure to noxious particles or gases (such as cigarette smoking) combined with other factors including genetics, airway hyperresponsiveness, and abnormal lung development. It results in airflow limitations due to chronic airway inflammation and/or parenchymal destruction (emphysema). COPD is characterized by chronic respiratory symptoms such as dyspnea, cough, and sputum production due to airway abnormalities and/or abnormal alveoli causing persistent, often progressive, airflow obstruction.",
    "answerFound": true,
    "conversationId": "a9cfca0b-73e0-4657-bf51-31137696537c",
    "messageId": "0",
    "references": {
      "title": "DynaMedex Sources Used",
      "results": [
        {
          "slug": "/condition/copd",
          "title": "COPD >",
          "sections": [
            {
              "title": "Description",
              "slug": "/condition/copd",
              "anchor": "DESCRIPTION",
              "breadcrumb": "General Information >",
              "metadata": {
                "title": "COPD",
                "navigateTo": [
                  "General Information",
                  "Description"
                ],
                "id": "T115557",
                "pubType": {
                  "pretty": "Condition",
                  "id": "condition",
                  "group": "articles"
                }
              }
            },
            {
              "title": "Causes",
              "slug": "/condition/copd",
              "anchor": "CAUSES",
              "breadcrumb": "Etiology and Pathogenesis >",
              "metadata": {
                "title": "COPD",
                "navigateTo": [
                  "Etiology and Pathogenesis",
                  "Causes"
                ],
                "id": "T115557",
                "pubType": {
                  "pretty": "Condition",
                  "id": "condition",
                  "group": "articles"
                }
              }
            }
          ],
          "metadata": {
            "title": "COPD",
            "id": "T115557"
          }
        },
        {
          "slug": "/condition/obstructive-sleep-apnea-osa-and-chronic-obstructive-pulmonary-disease-copd-overlap-syndrome",
          "title": "Obstructive Sleep Apnea (OSA) and Chronic Obstructive Pulmonary Disease (COPD) Overlap Syndrome >",
          "sections": [
            {
              "title": "Definitions",
              "slug": "/condition/obstructive-sleep-apnea-osa-and-chronic-obstructive-pulmonary-disease-copd-overlap-syndrome",
              "anchor": "DEFINITION",
              "breadcrumb": "Background Information >",
              "metadata": {
                "title": "Obstructive Sleep Apnea (OSA) and Chronic Obstructive Pulmonary Disease (COPD) Overlap Syndrome",
                "navigateTo": [
                  "Background Information",
                  "Definitions"
                ],
                "id": "T916802",
                "pubType": {
                  "pretty": "Condition",
                  "id": "condition",
                  "group": "articles"
                }
              }
            }
          ],
          "metadata": {
            "title": "Obstructive Sleep Apnea (OSA) and Chronic Obstructive Pulmonary Disease (COPD) Overlap Syndrome",
            "id": "T916802"
          }
        }
      ]
    },
    "recommendedQuestions": [],
    "recommendedContent": {
      "title": "Recommended Content",
      "results": [
        
      ]
    },
    "telemetryData": {
      "searchTerm": "what is copd?",
      "question": "What is the definition of COPD?",
      "pageToken": "a9cfca0b-73e0-4657-bf51-31137696537c",
      "conversationId": "a9cfca0b-73e0-4657-bf51-31137696537c",
      "messageId": "0",
      "searchTimeInMs": 13868,
      "ragResponseTimeInMs": 12694,
      "userIntentTimeInMs": 1075,
      "answerFound": true,
      "userIntentCategory": "DM_GENERAL_INFO"
    },
    "followupQuestions": {
      "enabled": true
    },
    "streamComplete": true
  }
}

Here you will note that streamComplete  and answerFound are 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.

Single Concept Query

Your user 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

data: {
  "viewModel": {
    "supported": false,
    "query": "zoloft",
    "question": "",
    "answer": "",
    "answerFound": false,
    "conversationId": "d3d1f16f-d20d-415c-96be-258296716e39",
    "messageId": "0",
    "references": {
      "title": "DynaMedex Sources Used",
      "results": ]
    },
    "recommendedQuestions": [],
    "recommendedContent": {
      "title": "Recommended Content",
      "results": []
    },
    "telemetryData": {
      "searchTerm": "zoloft",
      "question": "",
      "pageToken": "d3d1f16f-d20d-415c-96be-258296716e39",
      "conversationId": "d3d1f16f-d20d-415c-96be-258296716e39",
      "messageId": "0",
      "searchTimeInMs": 0,
      "ragResponseTimeInMs": 0,
      "userIntentTimeInMs": 0,
      "answerFound": false,
      "error": "UNSUPPORTED"
    },
    "followupQuestions": {
      "enabled": false
    },
    "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.

Follow-up Questions

A user may want to ask additional questions related to the original query.  The POST body will need to reflect the original query/question so that it has the full context.  The response will have a similar format to what is shown above.  Up to 5 follow-up questions may be asked.

Request Parameters for Follow-up Questions

Field

Type

Required

Description

criteria

Object

true

Parent object to hold the criteria for this request.

criteria.query

String

false

The query that the user has entered. The API requires either the query or the question. The question will be used if both are provided.

criteria.conversationId

String

false

All the follow on questions in a given session will share the same 'conversationId'.  It remains constant throughout the session. For the first request, the 'conservationId' is not required on the first request. Retrieve 'conservationId' from the previous response.

criteria.messageId

String

false

Each follow on question will have 'messageId' associated with it. For the first 'follow-on' question request, the Id will be 0.

criteria.question

String

false

The question that was recommended. The API requires either the query or the question. The question will be used if both are provided.

criteria.history

Array

false

Parent object to hold previous questions / answers that the user provided. This object is not needed fo

criteria.history.query

String

false

The previous query that the user executed.  Either the query or question field is required.

criteria.history.question

String

false

The previous question that the user executed. Either the query or question field is required.

criteria.history.response

String

false

The previous response that the user executed.

Example First Request 

The first requestand response follows the pattern above.  For example, the first request might be:

{
  "criteria": {
     "query": "what is copd"
  }
}

Example Second Request - The Follow-up Query

The second request might be a followup to "what is copd?" - "how do I diagnose?"  This is built using the query, question, answer conversationId and messageId from the first response.

{
  "criteria": {
    "query": "how do I diagnose"
  },
  "history": [
    {
      "query": "What is copd?",
      "response": " Chronic obstructive pulmonary disease (COPD) is a common, preventable, and treatable pulmonary disease generally caused by significant long-term cumulative exposure to noxious particles or gases (such as cigarette smoking) combined with other factors including genetics, airway hyperresponsiveness, and abnormal lung development. It results in airflow limitations due to chronic airway inflammation and/or parenchymal destruction (emphysema). COPD is characterized by chronic respiratory symptoms such as dyspnea, cough, and sputum production due to airway abnormalities and/or abnormal alveoli causing persistent, often progressive, airflow obstruction.",
      "question": "What is the definition of COPD?"
    }
  ],
  "conversationId": "a9cfca0b-73e0-4657-bf51-31137696537c",
  "messageId": "0"
}

The request now consists of a new query, a conversationId, and messageId which were returned in the previous response.  The history consists of the original query made by the caller, the answer and the question that were used - all coming from the previous response.

Example Follow-up Response

data: {
  "viewModel": {
    "supported": true,
    "query": "How do I diagnose",
    "question": "How do I diagnose a condition?",
    "answer": " Diagnosing a condition involves several steps and varies based on the specific condition and patient characteristics. For example, in the case of post-COVID-19 condition (Long COVID), diagnosis is based on the presence and timing of symptoms following confirmed or presumptive COVID-19. No laboratory test can definitively diagnose post-COVID-19 condition. Specialized testing may help confirm or exclude differential diagnoses and guide management. Testing should be based on clinical characteristics, patient history, and physical examination. In patients with respiratory distress, tests may include echocardiography, BNP, chest X-ray, CT, and pulmonary function testing. For chest pain, tests may include electrocardiography, serum troponin, echocardiography, and cardiac MRI. For fatigue, blood tests, electromyography, musculoskeletal imaging, and 6-minute walk test may be considered.",
    "answerFound": true,
    "conversationId": "22c3323e-e905-43b1-937b-da1175d8d7d0",
    "messageId": "0",
    "references": {
      "title": "DynaMedex Sources Used",
      "results": [
        {
          "slug": "/condition/post-covid-19-condition-long-covid",
          "title": "Post-COVID-19 Condition (Long COVID) >",
          "sections": [
            {
              "title": "Making the Diagnosis",
              "slug": "/condition/post-covid-19-condition-long-covid",
              "anchor": "MAKING_THE_DIAGNOSIS",
              "breadcrumb": "Diagnosis >",
              "metadata": {
                "title": "Post-COVID-19 Condition (Long COVID)",
                "navigateTo": [
                  "Diagnosis",
                  "Making the Diagnosis"
                ],
                "id": "T1708374814259",
                "pubType": {
                  "pretty": "Condition",
                  "id": "condition",
                  "group": "articles"
                }
              }
            }
          ],
          "metadata": {
            "title": "Post-COVID-19 Condition (Long COVID)",
            "id": "T1708374814259"
          }
        }
      ]
    },
    "recommendedQuestions": [],
    "recommendedContent": {
      "title": "Recommended Content",
      "results": [
        
      ]
    },
    "telemetryData": {
      "searchTerm": "How do I diagnose",
      "question": "How do I diagnose a condition?",
      "pageToken": "22c3323e-e905-43b1-937b-da1175d8d7d0",
      "conversationId": "22c3323e-e905-43b1-937b-da1175d8d7d0",
      "messageId": "0",
      "searchTimeInMs": 15251,
      "ragResponseTimeInMs": 13003,
      "userIntentTimeInMs": 2135,
      "answerFound": true,
      "userIntentCategory": "DM_DIAGNOSTIC_EVAL_TESTING"
    },
    "followupQuestions": {
      "enabled": true
    },
    "streamComplete": true
  }
}

Example Second Follow-up Request

Likewise, the followup question to the first 2 might be "can I use aspirin to treat copd?".  The response will be similar to the response above with the same conversationId, but a new messageId.

{
  "criteria": {
    "query": "can I use aspirin to treat copd?",
    "history": [
      {
        "query": "What is copd?",
        "response": " Chronic Obstructive Pulmonary Disease (COPD) is a common, preventable, and treatable pulmonary disease generally caused by significant long-term cumulative exposure to noxious particles or gases (such as cigarette smoking) combined with other factors including genetics, airway hyperresponsiveness, and abnormal lung development. It results in airflow limitations due to chronic airway inflammation and/or parenchymal destruction (emphysema). COPD is characterized by chronic respiratory symptoms such as dyspnea, cough, and sputum production due to airway abnormalities and/or abnormal alveoli causing persistent, often progressive, airflow obstruction.",
        "question": "What is the definition of Chronic Obstructive Pulmonary Disease (COPD)?"
      },
      {
        "query": "what is diagnosis",
        "response": "COPD is diagnosed through a combination of medical history, physical examination, and spirometry, a lung function test that measures airflow obstruction.",
        "question": "How is copd diagnosed?"
      }
    ],
    "conversationId": "a9cfca0b-73e0-4657-bf51-31137696537c",
    "messageId": "1"
  }
}

The subsequent response(s) will follow a similar pattern.  Up to five follow-on questions can be made.  A 422 status code will be returned when you would be setting the messageId to 5 and attempt another question.

Superscripts in a Query

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....

Request for Malicious or Non-Medical Information

Request for information that falls outside of DynaMedex guardrailed content will fail.

{
  "criteria": {
     "query": "How do I make a peach cobbler?"
  }
}
data: {
  "viewModel": {
    "supported": true,
    "query": "How do I make a peach cobbler?",
    "question": "",
    "answer": "",
    "answerFound": false,
    "conversationId": "0f49fb62-52df-48c6-9733-77a6f68ed29b",
    "messageId": "0",
    "references": {
      "title": "DynaMedex Sources Used",
      "results": []
    },
    "recommendedQuestions": [],
    "recommendedContent": {
      "title": "Recommended Content",
      "results": []
    },
    "telemetryData": {
      "searchTerm": "How do I make a peach cobbler?",
      "question": "",
      "pageToken": "0f49fb62-52df-48c6-9733-77a6f68ed29b",
      "conversationId": "0f49fb62-52df-48c6-9733-77a6f68ed29b",
      "messageId": "0",
      "searchTimeInMs": 0,
      "ragResponseTimeInMs": 0,
      "userIntentTimeInMs": 0,
      "answerFound": false,
      "error": "MALICIOUS"
    },
    "followupQuestions": {
      "enabled": false
    },
    "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?"
  }
}

data: {
  "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": "We're sorry, Dyna AI does not currently answer this type of question. Use the Drug Interaction Checker to get detailed drug interaction information.",
    "answerFound": true,
    "conversationId": "b77dc696-7e54-45b7-ac17-aab4b239a330",
    "messageId": "0",
    "references": {
      "title": "DynaMedex Sources Used",
      "results": []
    },
    "recommendedQuestions": [],
    "recommendedContent": {
      "title": "Recommended Content",
      "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": "b77dc696-7e54-45b7-ac17-aab4b239a330",
      "conversationId": "b77dc696-7e54-45b7-ac17-aab4b239a330",
      "messageId": "0",
      "searchTimeInMs": 1558,
      "ragResponseTimeInMs": 0,
      "userIntentTimeInMs": 1551,
      "answerFound": true,
      "userIntentCategory": "DM_INTERACTIONS"
    },
    "followupQuestions": {
      "enabled": true
    },
    "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 receive this error once the streamin has started.   Additional status codes are 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.