{
  "openapi": "3.1.0",
  "info": {
    "title": "EvidenceMD API",
    "version": "2.1.0",
    "description": "OpenAI-compatible medical AI API for clinical reasoning. EvidenceMD returns evidence-based answers with peer-reviewed citations, transparent chain-of-thought support, JSON mode, specialty-aware responses, and multilingual output for healthcare applications.",
    "contact": {
      "name": "EvidenceMD Inc.",
      "email": "founders@evidencemd.ai",
      "url": "https://evidencemd.ai/developers"
    }
  },
  "servers": [
    {
      "url": "https://evidencemd.ai/api/v1",
      "description": "Production API"
    }
  ],
  "tags": [
    {
      "name": "Chat",
      "description": "OpenAI-compatible medical chat completions"
    },
    {
      "name": "Models",
      "description": "Available EvidenceMD reasoning models"
    }
  ],
  "paths": {
    "/chat/completions": {
      "post": {
        "tags": ["Chat"],
        "operationId": "createMedicalChatCompletion",
        "summary": "Create a medical chat completion",
        "description": "OpenAI-compatible endpoint for evidence-based medical answers with inline citations, optional transparent chain-of-thought, streaming, JSON mode, specialty-aware responses, and multilingual output.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatCompletionRequest"
              },
              "examples": {
                "clinicalQuestion": {
                  "summary": "Clinical question",
                  "value": {
                    "model": "evidencemd-pro",
                    "messages": [
                      {
                        "role": "user",
                        "content": "What is first-line treatment for hypertension?"
                      }
                    ],
                    "stream": true,
                    "specialty": "Cardiology",
                    "language": "English"
                  }
                },
                "jsonMode": {
                  "summary": "Structured JSON response",
                  "value": {
                    "model": "evidencemd-pro",
                    "messages": [
                      {
                        "role": "user",
                        "content": "Summarize guideline-based management for HFrEF."
                      }
                    ],
                    "stream": false,
                    "response_format": {
                      "type": "json_object"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Streaming Server-Sent Events or a non-streaming JSON response, depending on the stream parameter.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatCompletionResponse"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "OpenAI-compatible SSE stream ending with data: [DONE]. Source metadata may be emitted as a chat.completion.sources event."
                }
              }
            },
            "headers": {
              "x-request-id": {
                "description": "Request identifier for tracing and support.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request, unsupported model, missing messages, or invalid parameters."
          },
          "401": {
            "description": "Invalid or missing API key."
          },
          "402": {
            "description": "Insufficient credits."
          },
          "429": {
            "description": "Rate limit exceeded."
          }
        }
      }
    },
    "/models": {
      "get": {
        "tags": ["Models"],
        "operationId": "listModels",
        "summary": "List EvidenceMD models",
        "description": "Returns the available EvidenceMD medical reasoning models.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Available models.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListModelsResponse"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing API key."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "EvidenceMD API key from the developer dashboard."
      }
    },
    "schemas": {
      "ChatCompletionRequest": {
        "type": "object",
        "required": ["model", "messages"],
        "properties": {
          "model": {
            "type": "string",
            "enum": ["evidencemd-fast", "evidencemd-pro", "evidencemd-deep"],
            "description": "EvidenceMD model to use. fast is optimized for quick answers, pro for deep analysis, and deep for complex multi-step clinical reasoning."
          },
          "messages": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "description": "OpenAI-compatible chat messages.",
            "items": {
              "$ref": "#/components/schemas/ChatMessage"
            }
          },
          "stream": {
            "type": "boolean",
            "default": true,
            "description": "Whether to stream the response as Server-Sent Events."
          },
          "specialty": {
            "type": "string",
            "maxLength": 100,
            "description": "Optional specialty or role context, such as Cardiology, Pediatrics, Biomedical Research, or Insurance Broker."
          },
          "language": {
            "type": "string",
            "default": "English",
            "description": "Optional response language. EvidenceMD supports 30 languages including English, Spanish, French, German, Italian, Portuguese, Russian, Japanese, Korean, Chinese, Hindi, Bengali, Turkish, Dutch, Greek, Swedish, Hebrew, Thai, Vietnamese, Indonesian, Malay, Telugu, Marathi, Finnish, Kannada, Polish, Romanian, and Swahili."
          },
          "include_thinking": {
            "type": "boolean",
            "default": false,
            "description": "For supported models, stream transparent clinical reasoning in thinking tags before the answer. English only."
          },
          "response_format": {
            "$ref": "#/components/schemas/ResponseFormat"
          },
          "temperature": {
            "type": "number",
            "minimum": 0,
            "maximum": 2,
            "default": 0.7
          },
          "max_tokens": {
            "type": "integer",
            "minimum": 1,
            "maximum": 32000,
            "default": 4096
          },
          "stream_options": {
            "$ref": "#/components/schemas/StreamOptions"
          }
        },
        "additionalProperties": true
      },
      "ChatMessage": {
        "type": "object",
        "required": ["role", "content"],
        "properties": {
          "role": {
            "type": "string",
            "enum": ["system", "user", "assistant"]
          },
          "content": {
            "type": "string",
            "description": "Message content."
          }
        }
      },
      "ResponseFormat": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": ["text", "json_object"],
            "description": "Set to json_object for structured JSON output with answer and sources fields."
          }
        }
      },
      "StreamOptions": {
        "type": "object",
        "properties": {
          "include_usage": {
            "type": "boolean",
            "description": "When streaming, include a final usage chunk with token counts."
          }
        }
      },
      "ChatCompletionResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "object": {
            "type": "string",
            "examples": ["chat.completion"]
          },
          "choices": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": {
                  "type": "integer"
                },
                "message": {
                  "$ref": "#/components/schemas/ChatMessage"
                },
                "finish_reason": {
                  "type": "string"
                }
              }
            }
          },
          "sources": {
            "type": "array",
            "description": "Peer-reviewed references and clinical guideline sources used in the response.",
            "items": {
              "$ref": "#/components/schemas/Source"
            }
          }
        }
      },
      "Source": {
        "type": "object",
        "properties": {
          "index": {
            "type": "integer"
          },
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "ListModelsResponse": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "examples": ["list"]
          },
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "examples": ["evidencemd-fast"]
                },
                "object": {
                  "type": "string",
                  "examples": ["model"]
                },
                "created": {
                  "type": "integer"
                },
                "description": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  }
}