Dyna Search 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 Response
- First Response
- Secondary Responses
- Answer Found Response
- Final Response
- Single Concept Query
- HTML in an Answer
- Query for a Non-Medical Answer
- Disclaimers
- System Error
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\nPrepending "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.
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>, and <br>. <table> may occur in the future.
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.
data:{
"viewModel": {
"supported": true,
"query": "congenital heart disease evaluation",
"question": "What is the approach to evaluating 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": {
"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).
data: { "viewModel": { "supported": true, "query": "congenital heart disease evaluation", "question": "What is the approach to evaluating 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": { "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" } } } ], "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. 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.
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.
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 Non-Medical Information
Request for information that falls outside of 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 DynaMedex.",
"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.
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"
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 DynaMedex search/rag endpoint can return one of the error response codes.