openapi: 3.0.1
info:
title: Clinical Intelligence API
description: >-
An API for accessing clinical intelligence, including patient summaries and medical guidelines.
This specification supports the research paper: "Interoperable Clinical Intelligence Systems:
Service-Oriented Design with OpenAPI and Model Context Protocol".
version: "1.0.0"
servers:
- url: http://localhost:3000
paths:
/summary/db/{patientId}:
get:
summary: Get Summary from DB
description: Retrieves an AI-generated summary from a patient's clinical notes in the local MIMIC-III database.
operationId: getSummaryFromDB
parameters:
- name: patientId
in: path
required: true
description: The numeric subject ID for the patient (e.g., '109').
schema:
type: string
responses:
'200':
description: An AI-generated summary of the patient's notes.
content:
application/json:
schema:
$ref: '#/components/schemas/AiSummary'
'404':
description: Patient not found in the database.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
/summary/fhir/{patientId}:
get:
summary: Get Summary from FHIR
description: Retrieves an AI-generated summary from a patient's data on a live, public FHIR server.
operationId: getSummaryFromFHIR
parameters:
- name: patientId
in: path
required: true
description: The patient's resource ID on the FHIR server (e.g., '1282007').
schema:
type: string
responses:
'200':
description: An AI-generated summary of the patient's FHIR data.
content:
application/json:
schema:
$ref: '#/components/schemas/AiSummary'
'404':
description: Patient not found on the FHIR server.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
/guidelines/search:
get:
summary: Search Clinical Guidelines
description: Searches for clinical practice guidelines based on a specific medical topic or condition.
operationId: searchGuidelines
parameters:
- name: topic
in: query
required: true
description: The clinical topic to search for (e.g., "hypertension").
schema:
type: string
responses:
'200':
description: A list of relevant clinical guidelines.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ClinicalGuideline'
'404':
description: No guidelines found for the specified topic.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
components:
schemas:
AiSummary:
type: object
properties:
source:
type: string
example: "SQLite (MIMIC-III)"
patientId:
type: string
example: "109"
ai_summary:
type: string
example: "The patient is a 70-year-old male with hyperlipidemia..."
ClinicalGuideline:
type: object
properties:
guidelineId:
type: string
example: "GUID-HTN-01"
topic:
type: string
example: "Hypertension"
title:
type: string
example: "2024 ACC/AHA Guideline for the Management of Hypertension"
ApiError:
type: object
properties:
code:
type: string
example: "NOT_FOUND"
message:
type: string
example: "The requested resource was not found."
