Quickstart tutorial
The OpenEvidence API provides easy programmatic access to OpenEvidence’s state of the art medical AI.
The Medical Analysis API endpoints allow you to input questions or medical topics and receive full medical analyses in response, complete with in-line citations to high-quality peer-reviewed medical literature and official government sources.
Access to the OpenEvidence API is currently limited. Please reach out via https://www.openevidence.com/product/api to learn about getting access.
What is a Medical Analysis?
A Medical Analysis is a comprehensive analysis of a medical topic or question. It includes a summary of the topic, a discussion of key points, and a references to high-quality peer-reviewed medical literature and official government sources with the original source text. The up-to-date references are used by OpenEvidence AI to generate the analysis.
Here is an example JSON medical analysis response:
Click to open
{
"request_id": "NpOqL8DN4LDyd",
"text": "The treatment of psoriasis is stratified based on disease severity, ranging from mild to severe, and includes topical agents, phototherapy, and systemic medications. For mild psoriasis, topical therapies such as corticosteroids, vitamin D analogues, and retinoids are commonly used.[[1]][[2]][[3]][[4]] The American Academy of Dermatology-National Psoriasis Foundation (AAD-NPF) guidelines recommend topical corticosteroids as a key component in the management of psoriasis, particularly for localized disease.[[4]]\n\nFor moderate to severe psoriasis, systemic treatments including methotrexate, acitretin, cyclosporine, and biologic agents are indicated.[[5]][[1]][[6]][[7]][[3]] The AAD-NPF guidelines also endorse biologics as a first-line treatment option for moderate to severe plaque psoriasis due to their efficacy and safety profiles. These biologics target specific immune pathways involved in psoriasis, such as tumor necrosis factor α (TNF-α), interleukin (IL)-12/23, IL-17, and IL-23.[[3]]\n\nPhototherapy, particularly narrowband UV-B (NB-UVB), is an effective treatment for psoriasis and is most appropriate for patients with more than 10% body surface area involvement who have not responded to topical treatments.[[8]] NB-UVB is often used in combination with topical agents to enhance efficacy.[[8]]\n\nIn all cases, treatment should be individualized, taking into account patient preference, potential side effects, and comorbid conditions.[[6]][[7]][[3]] Regular monitoring and adjustment of therapy may be necessary to maintain disease control and minimize adverse effects.",
"references": [
{
"citation_key": 1,
"reference_text": "Lebwohl M, Ting PT, Koo JY. <a target=\"_blank\" href=\"https://pubmed.ncbi.nlm.nih.gov/15708945\">Psoriasis Treatment: Traditional Therapy</a>. Annals of the Rheumatic Diseases. 2005;64 Suppl 2:ii83-6. doi:10.1136/ard.2004.030791.",
"reference_detail": {
"title": "Psoriasis Treatment: Traditional Therapy",
"authors_string": "Lebwohl M, Ting PT, Koo JY.",
"publication_info_string": "Annals of the Rheumatic Diseases. 2005;64 Suppl 2:ii83-6. doi:10.1136/ard.2004.030791.",
"journal_name": "Annals of the Rheumatic Diseases",
"journal_short_name": "Ann Rheum Dis",
"publication_date": "2005-03-01",
"doi": "10.1136/ard.2004.030791",
"url": "https://pubmed.ncbi.nlm.nih.gov/15708945"
},
"source_texts": [
"Even before the recent development of biological agents, a long list of effective treatments has been available for patients with psoriasis. Topical therapies such as corticosteroids, vitamin D analogues, and retinoids are used for localised disease. Phototherapy including broadband ultraviolet B (UVB), narrowband UVB, PUVA, and climatotherapy are effective for more extensive disease. Systemic therapies such as methotrexate, retinoids, and ciclosporin are effective for patients with refractory or extensive cutaneous disease."
]
},
{
"citation_key": 2,
"reference_text": "Lebwohl M, Ali S. <a target=\"_blank\" href=\"https://pubmed.ncbi.nlm.nih.gov/11568737\">Treatment of Psoriasis. Part 1. Topical Therapy and Phototherapy</a>. Journal of the American Academy of Dermatology. 2001;45(4):487-98; quiz 499-502. doi:10.1067/mjd.2001.117046.",
"reference_detail": {
"title": "Treatment of Psoriasis. Part 1. Topical Therapy and Phototherapy",
"authors_string": "Lebwohl M, Ali S.",
"publication_info_string": "Journal of the American Academy of Dermatology. 2001;45(4):487-98; quiz 499-502. doi:10.1067/mjd.2001.117046.",
"journal_name": "Journal of the American Academy of Dermatology",
"journal_short_name": "J Am Acad Dermatol",
"publication_date": "2001-10-01",
"doi": "10.1067/mjd.2001.117046",
"url": "https://pubmed.ncbi.nlm.nih.gov/11568737"
},
"source_texts": [
"UNLABELLED: New developments in the topical therapy and phototherapy of psoriasis have greatly improved our ability to safely and effectively treat this debilitating disease. Topical corticosteroids remain the most commonly prescribed agents for psoriasis, but they are frequently prescribed with other agents. Investigations of corticosteroids claiming an improved benefit/risk ratio have yielded promising results, but more work is needed. Use of anthralin and tar has declined with the availability of the noncorticosteroids calcipotriene and tazarotene. Other experimental topical therapies are in various stages of development. Broadband ultraviolet B (UVB) remains the most commonly used phototherapy light source, but many patients are being treated with a new form of ultraviolet light, narrowband UVB. Although PUVA remains one of the most effective psoriasis treatments, its use is declining because of its association with cutaneous malignancies. New radiation sources such as lasers have been added to our armamentarium of available therapies and even newer light source-based treatments are being examined. LEARNING OBJECTIVE: At the conclusion of this learning activity, participants should be familiar with the varying topical treatments for psoriasis as well as the different modalities of phototherapy. Participants should also have a better understanding of side effects associated with each treatment, which should help in determining options for therapy."
]
},
{
"citation_key": 3,
"reference_text": "Armstrong AW, Read C. <a target=\"_blank\" href=\"https://pubmed.ncbi.nlm.nih.gov/32427307\">Pathophysiology, Clinical Presentation, and Treatment of Psoriasis: A Review</a>. Jama. 2020;323(19):1945-1960. doi:10.1001/jama.2020.4006.",
"reference_detail": {
"title": "Pathophysiology, Clinical Presentation, and Treatment of Psoriasis: A Review",
"authors_string": "Armstrong AW, Read C.",
"publication_info_string": "Jama. 2020;323(19):1945-1960. doi:10.1001/jama.2020.4006.",
"journal_name": "The Journal of the American Medical Association",
"journal_short_name": "JAMA",
"publication_date": "2020-05-19",
"doi": "10.1001/jama.2020.4006",
"url": "https://pubmed.ncbi.nlm.nih.gov/32427307"
},
"source_texts": [
"IMPORTANCE: Approximately 125 million people worldwide have psoriasis. Patients with psoriasis experience substantial morbidity and increased rates of inflammatory arthritis, cardiometabolic diseases, and mental health disorders. OBSERVATIONS: Plaque psoriasis is the most common variant of psoriasis. The most rapid advancements addressing plaque psoriasis have been in its pathogenesis, genetics, comorbidities, and biologic treatments. Plaque psoriasis is associated with a number of comorbidities including psoriatic arthritis, cardiometabolic diseases, and depression. For patients with mild psoriasis, topical agents remain the mainstay of treatment, and they include topical corticosteroids, vitamin D analogues, calcineurin inhibitors, and keratolytics. The American Academy of Dermatology-National Psoriasis Foundation guidelines recommend biologics as an option for first-line treatment of moderate to severe plaque psoriasis because of their efficacy in treating it and acceptable safety profiles. Specifically, inhibitors to tumor necrosis factor α (TNF-α) include etanercept, adalimumab, certolizumab, and infliximab. Other biologics inhibit cytokines such as the p40 subunit of the cytokines IL-12 and IL-13 (ustekinumab), IL-17 (secukinumab, ixekizumab, bimekizumab, and brodalumab), and the p19 subunit of IL-23 (guselkumab, tildrakizumab, risankizumab, and mirikizumab). Biologics that inhibit TNF-α, p40IL-12/23, and IL-17 are also approved for the treatment of psoriatic arthritis. Oral treatments include traditional agents such as methotrexate, acitretin, cyclosporine, and the advanced small molecule apremilast, which is a phosphodiesterase 4 inhibitor. The most commonly prescribed light therapy used to treat plaque psoriasis is narrowband UV-B phototherapy. CONCLUSIONS AND RELEVANCE: Psoriasis is an inflammatory skin disease that is associated with multiple comorbidities and substantially diminishes patients' quality of life. Topical therapies remain the cornerstone for treating mild psoriasis. Therapeutic advancements for moderate to severe plaque psoriasis include biologics that inhibit TNF-α, p40IL-12/23, IL-17, and p19IL-23, as well as an oral phosphodiesterase 4 inhibitor."
]
},
{
"citation_key": 4,
"reference_text": "Elmets CA, Korman NJ, Prater EF, et al. <a target=\"_blank\" href=\"https://pubmed.ncbi.nlm.nih.gov/32738429\">Joint AAD-NPF Guidelines of Care for the Management and Treatment of Psoriasis With Topical Therapy and Alternative Medicine Modalities for Psoriasis Severity Measures</a>. Journal of the American Academy of Dermatology. 2021;84(2):432-470. doi:10.1016/j.jaad.2020.07.087.",
"reference_detail": {
"title": "Joint AAD-NPF Guidelines of Care for the Management and Treatment of Psoriasis With Topical Therapy and Alternative Medicine Modalities for Psoriasis Severity Measures",
"authors_string": "Elmets CA, Korman NJ, Prater EF, et al.",
"publication_info_string": "Journal of the American Academy of Dermatology. 2021;84(2):432-470. doi:10.1016/j.jaad.2020.07.087.",
"journal_name": "Journal of the American Academy of Dermatology",
"journal_short_name": "J Am Acad Dermatol",
"publication_date": "2021-02-01",
"doi": "10.1016/j.jaad.2020.07.087",
"url": "https://pubmed.ncbi.nlm.nih.gov/32738429"
},
"source_texts": [
"While skin involvement is the most prominent manifestation of this disease, recognition of psoriasis as a chronic, multisystem inflammatory disorder is imperative to optimize management and reduce comorbidities.\nTopical medications are the most common agents used to treat patients with mild to moderate psoriasis. They are frequently used as adjunctive therapies for patients on phototherapy, systemic, or biologic therapy. Alternative medicine (AM) is not typically part of conventional medical care. It may have origins outside of usual Western practice and may be desired by and benefit a subset of patients.\nTopical corticosteroids, which provide high efficacy and good safety, play a key role in the treatment of psoriasis, especially for localized disease. Topical corticosteroids have anti-inflammatory, antiproliferative, immunosuppressive, and vasoconstrictive effects. These effects are exerted via intracellular corticosteroid receptors, which regulate gene transcription, including several that code for proinflammatory mediators. Topical corticosteroids are classified into 7 categories based on their skin vasoconstrictive activity, ranging in strength from ultra-high (class 1) to low (class 6 and 7; Table II)."
]
},
{
"citation_key": 5,
"reference_text": "Lebwohl M. <a target=\"_blank\" href=\"https://pubmed.ncbi.nlm.nih.gov/15968265\">A Clinician's Paradigm in the Treatment of Psoriasis</a>. Journal of the American Academy of Dermatology. 2005;53(1 Suppl 1):S59-69. doi:10.1016/j.jaad.2005.04.031.",
"reference_detail": {
"title": "A Clinician's Paradigm in the Treatment of Psoriasis",
"authors_string": "Lebwohl M.",
"publication_info_string": "Journal of the American Academy of Dermatology. 2005;53(1 Suppl 1):S59-69. doi:10.1016/j.jaad.2005.04.031.",
"journal_name": "Journal of the American Academy of Dermatology",
"journal_short_name": "J Am Acad Dermatol",
"publication_date": "2005-07-01",
"doi": "10.1016/j.jaad.2005.04.031",
"url": "https://pubmed.ncbi.nlm.nih.gov/15968265"
},
"source_texts": [
"Psoriasis is a chronically recurring inflammatory disease that affects the skin, scalp, and joints. It ranges in severity from mild to severe, and patients with moderate to severe disease experience significant deterioration in quality of life. The goals of psoriasis treatment are to gain initial and rapid control of the disease process, decrease the percentage of body surface area involved, decrease plaque lesions, achieve and maintain long-term remission, minimize adverse events, and improve patient quality of life. Therapy varies depending on disease severity and spread and will shift from control of acute flares to long-term maintenance. Topical treatment for mild psoriasis includes the use of topical corticosteroids, calcipotriene, tazarotene, topical tars, anthralin, and keratolytics. Treatment of moderate to severe psoriasis includes systemic therapies, such as methotrexate, acitretin, cyclosporine, and biologic agents. Treatment can be effected using combination, rotational, or sequential regimens. Treatment algorithms developed by a 2002 consensus conference are described. Because some degree of therapy will always be necessary, ranging from maintenance of long-term remission to control of acute psoriasis flares, each patient requires an individualized plan."
]
},
{
"citation_key": 6,
"reference_text": "Smith J, Cline A, Feldman SR. <a target=\"_blank\" href=\"https://pubmed.ncbi.nlm.nih.gov/28052180\">Advances in Psoriasis</a>. Southern Medical Journal. 2017;110(1):65-75. doi:10.14423/SMJ.0000000000000596.",
"reference_detail": {
"title": "Advances in Psoriasis",
"authors_string": "Smith J, Cline A, Feldman SR.",
"publication_info_string": "Southern Medical Journal. 2017;110(1):65-75. doi:10.14423/SMJ.0000000000000596.",
"journal_name": "Southern Medical Journal",
"journal_short_name": "South Med J",
"publication_date": "2017-01-01",
"doi": "10.14423/SMJ.0000000000000596",
"url": "https://pubmed.ncbi.nlm.nih.gov/28052180"
},
"source_texts": [
"Psoriasis treatments range from topical treatments and phototherapy to oral systemic medications and injections. Despite good control of the disease when applying appropriate treatments (according to disease severity, insurance parameters, patient preference, and patients' ability to adhere), continued advancements will allow even better symptomatic control, reduced adverse effects, and patient satisfaction. This review aims to assess traditional and new psoriasis treatments and how to apply them in clinical practice. A literature review on psoriasis treatments and clinical applications was performed using PubMed. Mild-to-moderate psoriasis treatments include topicals, localized phototherapy, and newer therapies combining two types of topicals, phototherapy with topicals, and easy-to-use foam and spray vehicles. Moderate-to-severe psoriasis therapies include monotherapy or various combinations of generalized phototherapy, oral treatments, and biologic agents, with new oral and biologic agents on the horizon. Dermatologists and primary care providers share roles in screening for associated comorbidities (including cardiovascular disorders, chronic kidney disease, Crohn disease, dyslipidemia, diabetes mellitus/insulin resistance, depression, metabolic syndrome, obesity, and psoriatic arthritis), managing patients' treatments, and reevaluating treatment needs as new therapies are approved. Continued advancements in psoriasis treatment and improvement in coordinated care will allow better overall care of patients with psoriasis."
]
},
{
"citation_key": 7,
"reference_text": "Fairhurst DA, Ashcroft DM, Griffiths CE. <a target=\"_blank\" href=\"https://pubmed.ncbi.nlm.nih.gov/16252928\">Optimal Management of Severe Plaque Form of Psoriasis</a>. American Journal of Clinical Dermatology. 2005;6(5):283-94. doi:10.2165/00128071-200506050-00002.",
"reference_detail": {
"title": "Optimal Management of Severe Plaque Form of Psoriasis",
"authors_string": "Fairhurst DA, Ashcroft DM, Griffiths CE.",
"publication_info_string": "American Journal of Clinical Dermatology. 2005;6(5):283-94. doi:10.2165/00128071-200506050-00002.",
"journal_name": "American Journal of Clinical Dermatology",
"journal_short_name": "Am J Clin Dermatol",
"publication_date": "2005-10-29",
"doi": "10.2165/00128071-200506050-00002",
"url": "https://pubmed.ncbi.nlm.nih.gov/16252928"
},
"source_texts": [
"Psoriasis is a chronic, inflammatory, hyperproliferative skin disease that affects 1-2% of the general population in the UK and US. Plaque psoriasis is the most common form, accounting for approximately 90% of cases. The disease is usually chronic and persistent, although up to 50% of patients may enter spontaneous remission for varying periods of time. There is no cure for psoriasis; therefore, the aim of treatment is to minimize the extent and severity of the disease to the point at which it no longer substantially disrupts the patient's quality of life. First-line therapy of psoriasis usually consists of topical agents, such as emollients, tar, dithranol, and vitamin D3 analogs. In cases of severe, extensive psoriasis, where topical therapy is either impractical or not sufficiently effective, systemic treatment may be warranted at the outset. In these circumstances, the therapeutic options include: (i) intensive inpatient or day center topical therapy; (ii) phototherapy; and/or (iii) systemic agents. There are now a number of systemic agents available for the treatment of severe psoriasis, but all have potential adverse effects. We review the current treatment options, which include the use of phototherapy and systemic agents, and provide recommendations on their use in clinical practice. Importantly, treatment should be tailored to each individual patient depending on concurrent medical problems (which might preclude certain agents), patient choice and acceptance of the risk of adverse effects."
]
},
{
"citation_key": 8,
"reference_text": "Mehta D, Lim HW. <a target=\"_blank\" href=\"https://pubmed.ncbi.nlm.nih.gov/26872953\">Ultraviolet B Phototherapy for Psoriasis: Review of Practical Guidelines</a>. American Journal of Clinical Dermatology. 2016;17(2):125-33. doi:10.1007/s40257-016-0176-6.",
"reference_detail": {
"title": "Ultraviolet B Phototherapy for Psoriasis: Review of Practical Guidelines",
"authors_string": "Mehta D, Lim HW.",
"publication_info_string": "American Journal of Clinical Dermatology. 2016;17(2):125-33. doi:10.1007/s40257-016-0176-6.",
"journal_name": "American Journal of Clinical Dermatology",
"journal_short_name": "Am J Clin Dermatol",
"publication_date": "2016-04-01",
"doi": "10.1007/s40257-016-0176-6",
"url": "https://pubmed.ncbi.nlm.nih.gov/26872953"
},
"source_texts": [
"Psoriasis is an inflammatory skin condition that affects approximately 2 % of people worldwide. Topical treatments, systemic treatments, biologic agents, and phototherapy are all treatment options for psoriasis. Ultraviolet (UV) B phototherapy is most appropriate for patients with >10 % affected body surface area who have not responded to topical treatments. This review outlines the use, dosage, safety, and efficacy of narrowband UVB (NB-UVB) and targeted phototherapy. NB-UVB and excimer laser are effective treatment options for psoriasis; they are administered two to three times weekly until clearance followed by maintenance treatment before discontinuation. Long-term data on NB-UVB indicate that it has a good safety profile. NB-UVB is commonly used with adjunctive topical treatments such as emollients, calcipotriene, cortico-steroids, retinoids, and tar. NB-UVB can be used in selected patients with traditional systemic agents such as methotrexate, mycophenolate mofetil, and cyclosporine, although the duration of the combined treatment should be kept to a minimum and patients need to be closely monitored. Acitretin can be safely used with phototherapy, but robust data on the combination use of biologic agents or phosphodiesterase inhibitors with phototherapy are lacking."
]
}
]
}
What are the limitations of a Medical Analysis?
It is not a free-form chat with a general-purpose LLM.
Text is presented in an written prose format and cannot be structured differently using prompt engineering.
A medical analysis pertain to a medical question or topic, off-topic inputs will be rejected.
Set up
Once you have received an API key, add the following environment variable to your system:
export OPENEVIDENCE_API_KEY=<YOUR KEY HERE>
Stream responses
The fastest way to interact with the API is by streaming responses using the createAnalysisStreaming endpoint (/streaming/analysis). Using this endpoint, the OpenEvidence API will stream text and references as they are produced by OpenEvidence AI using server-sent events (SSE).
Using streaming responses, the server will send data messages with JSON payloads containing text and reference keys.
Example text-only event:
data: {"text": "It is important to identify"}
Example text-with-reference event:
data: {"text": "[[1]]", "reference": {"citation_key": 1, "reference_text": "Lebwohl M, Ting PT, Koo JY. <a target=\"_blank\" href=\"https://pubmed.ncbi.nlm.nih.gov/15708945\">Psoriasis Treatment: Traditional Therapy</a>. Annals of the Rheumatic Diseases. 2005;64 Suppl 2:ii83-6. doi:10.1136/ard.2004.030791.", "reference_detail": {"title": "Psoriasis Treatment: Traditional Therapy", "authors_string": "Lebwohl M, Ting PT, Koo JY.", "publication_info_string": "Annals of the Rheumatic Diseases. 2005;64 Suppl 2:ii83-6. doi:10.1136/ard.2004.030791.", "journal_name": "Annals of the Rheumatic Diseases", "journal_short_name": "Ann Rheum Dis", "publication_date": "2005-03-01", "doi": "10.1136/ard.2004.030791", "url": "https://pubmed.ncbi.nlm.nih.gov/15708945"}, "source_texts": ["Even before the recent development of biological agents, a long list of effective treatments has been available for patients with psoriasis. Topical therapies such as corticosteroids, vitamin D analogues, and retinoids are used for localised disease. Phototherapy including broadband ultraviolet B (UVB), narrowband UVB, PUVA, and climatotherapy are effective for more extensive disease. Systemic therapies such as methotrexate, retinoids, and ciclosporin are effective for patients with refractory or extensive cutaneous disease."]}}
Concatenating together the text fields from the data messages will produce the full analysis text, and will match the output of the blocking API response text field.
Using curl
curl \
-X POST \
-H 'Accept: text/event-stream' \
-H 'Content-Type: application/json' \
-H "Authorization: Token $OPENEVIDENCE_API_KEY" \
-d '{"text": "what is the treatment for psoriasis", "model": "oe-v2"}' \
https://api.openevidence.com/streaming/analysis
Using Python
Here is an implementation of streaming the response from the Medical Analysis API using Python and the requests library. In this implementation, we iteratively update the analysis object. At each step, we could render the analysis object to the user interface and it would show the partial responses generated by the AI to that point.
[1]:
import json
import time
import os
import requests
base_url = "https://api.openevidence.com"
api_key = os.environ["OPENEVIDENCE_API_KEY"]
start = time.time()
print("Begin at T=0s")
response = requests.post(
f"{base_url}/streaming/analysis",
json={
"text": "what is the treatment for psoriasis",
"model": "oe-v2",
},
headers={
"Authorization": f"Token {api_key}",
"Accept": "text/event-stream",
},
stream=True,
)
response.raise_for_status()
analysis = {
"text": "",
"references": [],
}
it = response.iter_lines()
for line in it:
line = line.decode()
if line.startswith("data: "):
# we have received some data, which could be text or an in-line citation + reference.
message = line.removeprefix("data: ")
if message:
# end of stream
if message == "[DONE]":
break
data = json.loads(message)
analysis["text"] += data["text"]
reference = data.get("reference")
if reference:
# only add this reference if we haven't seen it before
if reference["citation_key"] not in [
r["citation_key"] for r in analysis["references"]
]:
analysis["references"].append(reference)
print(
"{n} characters received at T={t:0.3f}s".format(
n=len(data["text"]),
t=(time.time() - start),
)
)
elif line.strip() == "":
# a newline delimits messages
continue
elif line == "[done]":
# backwards compatibility for previous end-of-stream messages
break
else:
# not used
break
print("Done at T={:0.3f}s".format(time.time() - start))
Begin at T=0s
29 characters received at T=11.605s
37 characters received at T=11.965s
49 characters received at T=12.330s
40 characters received at T=12.811s
38 characters received at T=13.059s
14 characters received at T=13.060s
35 characters received at T=13.427s
34 characters received at T=13.856s
19 characters received at T=14.162s
4 characters received at T=14.163s
34 characters received at T=14.589s
49 characters received at T=14.903s
34 characters received at T=15.252s
56 characters received at T=15.619s
2 characters received at T=16.056s
32 characters received at T=16.057s
39 characters received at T=16.480s
12 characters received at T=17.003s
23 characters received at T=17.003s
23 characters received at T=17.275s
50 characters received at T=17.691s
21 characters received at T=18.101s
38 characters received at T=18.102s
21 characters received at T=18.583s
21 characters received at T=19.100s
21 characters received at T=19.325s
21 characters received at T=19.738s
30 characters received at T=20.148s
19 characters received at T=20.675s
21 characters received at T=20.965s
37 characters received at T=21.374s
14 characters received at T=21.861s
14 characters received at T=22.270s
31 characters received at T=22.783s
25 characters received at T=22.994s
15 characters received at T=23.402s
18 characters received at T=23.827s
18 characters received at T=24.233s
11 characters received at T=24.727s
7 characters received at T=25.062s
5 characters received at T=25.070s
16 characters received at T=25.070s
29 characters received at T=25.483s
14 characters received at T=25.915s
27 characters received at T=26.439s
38 characters received at T=26.733s
2 characters received at T=27.152s
26 characters received at T=27.153s
51 characters received at T=27.562s
41 characters received at T=28.011s
48 characters received at T=28.399s
8 characters received at T=28.823s
5 characters received at T=28.829s
36 characters received at T=28.829s
47 characters received at T=29.254s
43 characters received at T=29.682s
14 characters received at T=30.117s
Done at T=30.382s
Render responses
You can render Medical Analysis objects in whatever way makes most sense for your application. Here is some helper code in Python that converts the response to markdown and then displays it in a Jupyter notebook.
[2]:
import re
from IPython.display import display, Markdown
def reference_key_to_id(key: int):
return f"reference-{key}"
def citation_to_md(key: int):
return f'<a href={reference_key_to_id(key)}>[{key}]</a>'
def reference_to_md(reference: dict):
key = reference["citation_key"]
reference_text = reference["reference_text"]
return f'<div id="{reference_key_to_id(key)}">[{key}] {reference_text}</div>'
def answer_text_to_md(answer_text: str):
for key in re.findall(r"\[\[(\d+)\]\]", answer_text):
answer_text = answer_text.replace(f"[[{key}]]", citation_to_md(key))
return answer_text
def display_analysis(analysis):
md_lines = [
answer_text_to_md(analysis["text"]),
]
for reference in analysis["references"]:
md_lines += [reference_to_md(reference)]
md = "\n\n".join(md_lines)
display(Markdown(md))
Here is what the Markdown would look like (removing the source texts):
[3]:
display_analysis(analysis)
The treatment of psoriasis is stratified based on disease severity, ranging from mild to moderate and severe forms. For mild to moderate psoriasis, topical agents are the mainstay of treatment. These include topical corticosteroids, vitamin D analogues, calcineurin inhibitors, and keratolytics. The American Academy of Dermatology-National Psoriasis Foundation (AAD-NPF) guidelines recommend topical corticosteroids as a key component, particularly for localized disease
For moderate to severe psoriasis, systemic treatments and biologics are considered. The AAD-NPF guidelines suggest biologics as a first-line treatment option due to their efficacy and safety profiles. These include inhibitors of tumor necrosis factor α (TNF-α) such as etanercept, adalimumab, certolizumab, and infliximab; inhibitors of the p40 subunit of IL-12 and IL-23 such as ustekinumab; IL-17 inhibitors including secukinumab, ixekizumab, bimekizumab, and brodalumab; and inhibitors of the p19 subunit of IL-23 such as guselkumab, tildrakizumab, risankizumab, and mirikizumab.[1] Oral treatments like methotrexate, acitretin, cyclosporine, and the phosphodiesterase 4 inhibitor apremilast are also used
Phototherapy, specifically narrowband UV-B, is commonly prescribed for plaque psoriasis and can be used in combination with topical treatments or traditional systemic agents.[2] It is important to tailor treatment to individual patient needs, considering comorbidities, patient preference, and potential side effects.
[1] Armstrong AW, Read C. Pathophysiology, Clinical Presentation, and Treatment of Psoriasis: A Review. Jama. 2020;323(19):1945-1960. doi:10.1001/jama.2020.4006.
[2] Mehta D, Lim HW. Ultraviolet B Phototherapy for Psoriasis: Review of Practical Guidelines. American Journal of Clinical Dermatology. 2016;17(2):125-33. doi:10.1007/s40257-016-0176-6.
Blocking requests
If you don’t need to render partial responses in a user interface, there is no benefit to using the streaming API. In this case, the blocking createAnalysis endpoint (/analysis) returns the fully formatted Medical Analysis object to you when it is completed.
Using curl
curl \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H "Authorization: Token $OPENEVIDENCE_API_KEY" \
-d '{"text": "what is the treatment for psoriasis", "model": "oe-v2"}' \
https://api.openevidence.com/analysis
Using Python
[6]:
import os
import requests
base_url = "https://api.openevidence.com"
api_key = os.environ["OPENEVIDENCE_API_KEY"]
response = requests.post(
f"{base_url}/analysis",
json={
"text": "what is the dosage of advil for a 5 year old",
"model": "oe-v2",
},
headers={
"Authorization": f"Token {api_key}",
},
)
response.raise_for_status()
print(f"Done in {response.elapsed.total_seconds():0.3f}s")
analysis = response.json()
print("Analysis text begins: ", analysis["text"][:80] + "...")
Done in 21.727s
Analysis text begins: The dosage of ibuprofen (Advil) for a child who is 5 years old can be determined...
Literature search
The Literature Search API complements the Medical Analysis API. A literature search produces a ranked list of biomedical sources that relate to a given medical question or topic.
The API response includes details on the search:
similarity score: semantic similarity between the query and the reference text (embedding-based)
relevance score: relevance of the reference text to addressing the medical question or topic
Typically the search results include the most relevant sources identified (highest relevance scores). However other factors may influence the search result, such as including sources from a diversity of source repositories and publications.
Using curl
curl \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H "Authorization: Token $OPENEVIDENCE_API_KEY" \
-d '{"text": "what is the treatment for psoriasis", "model": "oe-v2"}' \
https://api.openevidence.com/literature-search
Next steps
For more information, check out our full API docs.