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.",
    "filters": {
      "sources": [
        "scientificArticles",
        "internationalHealthGuidelines"
      ],
      "year_start": 2020,
      "year_end": 2023,
      "only_high_quality": true,
      "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

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
only_high_quality	Boolean	When true, restricts results to high-quality sources (default: false)	Optional
article_types	Array[String]	Types of scientific articles to include when searching (default: all)	Optional

Available Sources

scientificArticlesScientific Articles

Peer-reviewed scientific literature

internationalHealthGuidelinesInt. Health Guidelines

Guidelines from international health organizations

medicineGuidelinesMedicine Guidelines

Guidelines related to drugs, vaccines, etc.

healthlineHealthline

Healthline content

booksBooks

Medical textbooks and reference books

Available Article Types

metaAnalysisMeta-Analysis

Studies that combine results from multiple studies

reviewsReviews

Review articles that summarize existing literature

clinicalTrialsClinical Trials

Research studies involving human participants

otherOther

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",
      "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",
      "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
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

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