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 and reliable response.
- Basic Dyna Response
- First Response
- Secondary Responses
- Answer Found Response
- Final Response
- Single Concept Query - Success
- Single Concept Query - Failure
- Query for a Non-Medical Answer
- System Error
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 can be used as a first attempt at asking a question. It might be used for instance when the user is typing terms into the search box. Dyna will take the terms and formulate a question. If both, a query and a question, are included in the request, then only the question will be sent to Dyna for an answer. More details on this below in the setion Single Concept Query.
Request
POST 'https://apis.ebsco.com/medsapi-dynamedex/v1/content/search/rag'
Request Body
{
"queryHistory": [
{
"question": "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\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": "How do I evaluate an Infant for Congenital Heart Disease?",
"question": "",
"answer": "",
"answerNotFound": true,
"references": {
"hasNotes": false,
"results": []
},
"recommendedContent": {
"hasNotes": false,
"results": []
},
"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.
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.
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. ",
"answerNotFound": false,
"references": {
"hasNotes": false,
"results": []
},
"recommendedContent": {
"hasNotes": false,
"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 answerNotFound flag is set to false 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": "How do I evaluate an Infant for Congenital Heart Disease",
"question": "How do I evaluate an Infant for Congenital Heart Disease",
"answer": " In infants, evaluation for congenital heart disease (CHD) involves a comprehensive approach. Initial screening includes a newborn physical exam to identify signs suggestive of CHD. Key components of the evaluation include:<br><ul><li>Vital signs, including blood pressure in all four limbs.</li><li>Inspection of skin for central cyanosis, sweating, and capillary refill.</li><li>Detailed cardiovascular examination with palpation to assess heart size, auscultation of heart sounds, and evaluation of any murmurs.<li><li>Lung and abdominal exams for evidence of pulmonary edema and heart failure.</li></ul>Further diagnostic tests include pulse oximetry, echocardiogram, electrocardiogram, chest x-ray, and hyperoxia test. MRI, CT, and cardiac catheterization may be required for additional details or definitive diagnosis. ",
"answerNotFound": false,
"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",
"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": []
},
"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": "DM_DIAGNOSTIC_EVAL_TESTING"
},
"streamComplete": true
}
}Here you will note that streamComplete is true, and now in addition to the answer, references are included.
Your application may want to send a Dyana query based on what the user has entered in the search box. This can be sent in the query field of the request body. If there is enough context, the Dyna search will return a Dyna response by formulating a question based on the terms. If only a single term is provided, Dyna may not be able to form a question and will not return an answer.
Request
POST 'https://apis.ebsco.com/medsapi-dynamedex/v1/content/search/rag'
Request Body
{
"queryHistory": [
{
"query": "patient with diabetes"
}
]
}
Final Single Query Success Response
{
"viewModel": {
"supported": true,
"query": "patient with diabetes",
"question": "What are the management and treatment options for a patient with diabetes?",
"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. ",
"answerNotFound": false,
"references": {
"hasNotes": false,
"results": [
{
"slug": "/leadership/case-management-for-patients-with-diabetes",
"title": "Case Management for Patients with Diabetes >",
"sections": [
{
"title": "Treatment Strategies",
"slug": "/leadership/case-management-for-patients-with-diabetes#GUID-1CB18D57-8501-4C62-B0EF-588194A310E8",
"breadcrumb": null,
"metadata": {
"title": "Case Management for Patients with Diabetes",
"navigateTo": [
"Treatment Strategies"
],
"id": "T1709881762635",
"pubType": {
"pretty": "Leadership",
"id": "workplace",
"group": "leadership"
}
}
}
],
"hasNote": false,
"metadata": {
"title": "Case Management for Patients with Diabetes",
"id": "T1709881762635"
}
}
]
},
"recommendedContent": {
"hasNotes": false,
"results": [
]
},
"telemetryData": {
"searchTerm": "patient with diabetes",
"question": "What are the management and treatment options for a patient with diabetes?",
"pageToken": "2131a786-5e40-438f-9406-8147d8eb7452",
"searchTimeInMs": 9165,
"ragResponseTimeInMs": 7962,
"userIntentTimeInMs": 1119,
"userIntentCategory": "DH_DISEASE"
},
"streamComplete": true
}
}Note that in this response, a question has been formed that by Dyna that it can then answer. The other responses will follow the same patter as above.
A single concept query fails when the query is set to a single word or words that Dyna is unable to use to create a question. For example, this request body:
{
"queryHistory": [
{
"query": "copd"
}
]
}Response
{
"viewModel": {
"supported": false,
"query": "copd",
"answer": "We're sorry but we were unable to find the answer in DynaMedex.",
"answerNotFound": true,
"references": {
"hasNotes": false,
"results": []
},
"recommendedContent": {
"hasNotes": false,
"results": []
},
"telemetryData": {
"searchTerm": "copd",
"searchTimeInMs": 0,
"ragResponseTimeInMs": 0,
"userIntentTimeInMs": 0,
"error": "Single concept query is not supported"
},
"streamComplete": true
}
}Here is the response that indicates that the query is not supported, and the stream is complete.
Request for Non-Medical Information
Request for information that falls outside of DynaMed or DynaMedex will fail.
{ "queryHistory": [ {"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.",
"answerNotFound": true,
"references": {
"hasNotes": false,
"results": []
},
"recommendedContent": {
"hasNotes": false,
"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.
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.