API Documentation

These docs provide the input and output data structures that the MediSearch API supports. We provide a streaming API using Server-Sent Events (SSE).

The API is deployed at:

https://api.backend.medisearch.io/sse/medichat

Examples

Check out our examples to quickly integrate the API.

Get Started

Make sure you sign up for the API to obtain your API key.

Official Python Client JavaScript Example Google Colab Demo

Contents

Need Help?

If you have questions or need assistance with the API integration, our team is ready to help.

Contact Support

Overview

The MediSearch API allows you to integrate our medical search capabilities into your applications. Our API uses Server-Sent Events (SSE) for real-time, streaming responses to medical queries.

Below you'll find detailed information about the input structure to send to our API and the output formats you'll receive.

Input Structure

Request Format#

The structure of a request to the MediSearch API.

Data Structure

{
  "conversation": [
    "Is cancer transmissible?"
  ],
  "key": "your_api_key",
  "id": "your_conversation_id",
  "settings": {
    "language": "English",
    "model_type": "standard",
    "system_prompt": "Please use simple language and include safety warnings when appropriate.",
    "followup_count": 3,
    "filters": {
      "sources": [
        "scientificArticles",
        "internationalHealthGuidelines"
      ],
      "year_start": 2020,
      "year_end": 2023,
      "article_types": [
        "metaAnalysis",
        "reviews"
      ]
    }
  }
}

Field	Type	Description	Required
conversation	Array[String]	Conversation history as alternating human and AI messages	Yes
key	String	Your API key for authentication	Yes
id	String	Unique identifier for the conversation	Yes
settings	Object	Configuration options for the request	Optional

Field Details

conversation

An array of strings that contains the conversation history. The messages alternate between human and AI, with the first (and any odd-indexed) messages being from the human, and the even-indexed messages being from the AI.

The last message in the array must always be from the human.

Conversation Structure Rules

The human and bot messages are alternating
There is at least one message in the conversation
The last message is the human query

Valid Examples

["What is diabetes?"]

["What is diabetes?", "Diabetes is...", "What are the symptoms?"]

Invalid Examples

[]

["What is diabetes?", "Diabetes is..."]

key

Your API key for authenticating with the MediSearch API. You can obtain a key by signing up.

id

A unique identifier for the conversation. This should be generated once at the start of a conversation and reused for all follow-up messages in the same conversation.

Using the same ID helps maintain context across multiple interactions. You can use a UUID or any other unique string.

settings

The settings object allows you to configure how MediSearch processes and responds to queries. It includes options for language, model type, and search filters.

Field	Type	Description	Required
language	String	Language for the response (default: "English")	Optional
model_type	String	Model type to use: "standard" or "pro" (default: "standard")	Optional
system_prompt	String	Custom instructions to control the style, format, and constraints of AI responses	Optional
filters	Object	Filters for refining search results	Optional
followup_count	Integer	Number of follow-up questions to generate (1-6)	Optional

Language

You can specify the language for the response. While you can specify any language, we test and evaluate the performance of the model on the following languages:

English

Arabic

German

Mandarin

Hindi

Japanese

French

Spanish

Slovak

Turkish

Portuguese

Polish

Indonesian

Malay

Finnish

Bulgarian

Model Type

standard

Default model suitable for most medical queries. Optimized for balanced performance and response time.

pro

Enhanced model with greater capabilities for complex medical questions and specialized topics.

System Prompt

The system_prompt parameter allows you to customize how the AI structures and presents its responses. This is useful for tailoring outputs to specific audiences or changing the style of the response.

Common Use Cases

Simplifying language: "Please use simple, everyday language and avoid medical jargon when possible."

Adding safety guidance: "If users asks questions that require diagnosis, respond with 'I cannot answer this'. "

Formatting responses: "Present information in a structured format with markdown headings and use bold text for warnings."

Filters Object

Fine-tune search results using the filters object to specify source types, publication dates, and more. All filter fields are optional.

Field	Type	Description	Required
sources	Array[String]	Which source types to include in the search (default: all)	Optional
year_start	Integer	Earliest publication year to include	Optional
year_end	Integer	Latest publication year to include	Optional
article_types	Array[String]	Types of scientific articles to include when searching (default: all)	Optional

Available Sources

internationalHealthGuidelinesInt. Health Guidelines

Guidelines from international health organizations such as WHO, NIH, CDC, NICE, FDA, and professional medical associations (AMA, ACOG, AHA, etc.)

medicineGuidelinesMedicine Guidelines

Guidelines related to pharmaceuticals from reputable sources such as MedlinePlus, drugs.com etc.

scientificArticlesScientific Articles

Scientific literature published in peer-reviewed journals such as NEJM, JAMA, Lancet, BMJ etc.

booksBooks

Medical textbooks and reference books

healthBlogsHealth Blogs

Content from health blogs such as healthline.com

Available Article Types

metaAnalysisMeta-Analysis

Studies that combine results from multiple studies to increase reliability and detect patterns across research

reviewsReviews

Comprehensive syntheses of existing research using methodical or narrative approaches (e.g. systematic reviews, narrative reviews, etc.)

clinicalTrialsClinical Trials

Controlled research studies evaluating the safety and efficacy of medical interventions across various phases and designs (e.g., Phase I, II, III, IV clinical trials, RCTs, etc.)

observationalStudiesObservational Studies

Studies that collect and analyze data from populations without direct intervention (such as clinical studies, cohort studies, case-control studies, etc.)

otherOther

Other scientific articles that do not fit into the above categories such as case reports, case series, legal cases, commentaries, lectures, etc.

Follow-up Questions

The followup_count parameter lets you specify how many potential follow-up questions to generate based on the conversation context.

Usage Guidelines

Value range: 1-6 (any value above 6 will return 6 questions)

Setting to 0 or not specifying: No follow-up questions will be generated

Example setting: "followup_count": 3 will generate 3 potential follow-up questions

Output Format

Event: llm_response#

Response from our language model that has been generated so far. You will receive multiple events with the response building progressively.

Data Structure

{
  "event": "llm_response",
  "id": "your_conversation_id",
  "data": "Cancer is generally not transmissible between individuals. However, there are a few rare exceptions..."
}

Field	Type	Description
event	String	The event type identifier, always "llm_response" for this event
id	String	The conversation ID that matches your request
data	String	The AI-generated text response

The response is generally markdown formatted, with headings, bold text, bullet points, and lists. To change the formatting please refer to our system prompt documentation in the Settings section.

Event: articles#

Articles that are referenced in the response of MediSearch. This event arrives after the AI has finished generating the response.

Data Structure

{
  "event": "articles",
  "id": "your_conversation_id",
  "data": [
    {
      "title": "Symptoms and diagnosis of type 2 diabetes",
      "url": "https://pubmed.ncbi.nlm.nih.gov/31245782/",
      "authors": ["Johnson", "Smith"],
      "year": "2021",
      "tldr": "This article provides a comprehensive overview of the symptoms and diagnosis of type 2 diabetes.",
      "journal": "Journal of Diabetes Research"
    },
    {
      "title": "Current treatment approaches for type 2 diabetes",
      "url": "https://pubmed.ncbi.nlm.nih.gov/30982651/",
      "authors": ["Chen", "Williams"],
      "year": "2022",
      "tldr": "This article discusses current treatment approaches for type 2 diabetes.",
      "journal": "Diabetes Care"
    }
  ]
}

Field	Type	Description
title	String	The full title of the article or publication
url	String	URL link to the article
authors	Array[String]	List of author names for the article
tldr	String	Short summary of the referenced information
year	String	Publication year of the article
journal	String	The name of the journal where the article was published

The citations in the llm_response correspond to the 1-indexed articles in the returned articles list. In the example below, the first article (index [1]) is Cancer is not transmissible and the second article (index [2]) is Transmissible cancer can actually happen.

Articles Response

Data Structure

{
  "data": [
    {
      "title": "Cancer is not transmissible"
    },
    {
      "title": "Transmissible cancer can actually happen"
    }
  ]
}

LLM Response

Data Structure

{
  "data": "No, cancer is not transmissible [1]. 
  Except for some rare cases [2]."
}

Citation Indexing

In general: the i-th citation in the response coming from llm_response corresponds to the (i-1)st index of the articles list coming from articles.

Event: error#

Error responses from the API.

Data Structure

{
  "event": "error",
  "id": "your_conversation_id",
  "data": "error_not_enough_articles"
}

Error Handling

The MediSearch API may return error events in various situations:

Error Event Codes

Error Code	Description
error_not_enough_articles	Not enough relevant articles found for the query.
error_out_of_tokens	Conversation exceeded maximum allowed length. Start a new conversation or simplify your query.
error_internal	Internal server error that occurred during processing.
error_llm	Error occurred in the language model processing.

HTTP Errors

Other errors (like authentication issues, rate limiting, etc.) are returned as standard HTTP errors over SSE, not as error events. These include:

HTTP Code	Description
403	Unable to authenticate the request.
429	Rate limit exceeded
500	General server error

Note

You should have at least some basic error handling mechanism to show your users a sensible message on your frontend when an error happens.

If you suspect the problem is on our end, do not hesitate to contact us: founders@medisearch.io

Event: followups#

Suggested follow-up questions that the user might want to ask next. This event is sent only when the followup_count setting is specified.

Data Structure

{
  "event": "followups",
  "id": "your_conversation_id",
  "data": [
    "What are the symptoms of type 2 diabetes?",
    "How is diabetes diagnosed?",
    "Can diabetes be prevented through lifestyle changes?"
  ]
}

Field	Type	Description
event	String	The event type identifier, always "followups" for this event
id	String	The conversation ID that matches your request
data	Array[String]	List of suggested follow-up questions the user might want to ask

The follow-up questions are designed to help users continue the conversation in a natural way. The number of questions returned is controlled by the followup_count parameter in the settings.

Implementation Tip

Consider displaying follow-up questions as clickable buttons or chips in your UI to make it easy for users to continue the conversation without typing.

Client Libraries and Examples#

MediSearch provides official client libraries to help you integrate with our API.

We provide client libraries and examples to simplify your integration with the MediSearch API.

Python Client

Our official Python client provides simple, intuitive access to the MediSearch API

pip install medisearch-client

JavaScript Example

Example code for integrating with JavaScript applications

Ready to start building?

Get your API key and start integrating MediSearch into your application.

Get API Key View Examples