API Reference

Complete reference for SecureHospital AI REST APIs and MCP tools.

Introduction

The SecureHospital AI API provides programmatic access to the healthcare AI platform. The API is organized around REST principles with JSON request/response bodies.

Base URL

URL
http://localhost:8000

Content Type

All requests should include:

Headers
Content-Type: application/json

Authentication

The API uses JWT (JSON Web Tokens) for authentication. Include the access token in the Authorization header for protected endpoints. 

Header
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

Token Expiration

Access tokens expire after 60 minutes. Use the refresh endpoint to obtain a new access token.

Obtain Token

POST /api/token/ Public

Authenticate and obtain JWT access and refresh tokens.

Request Body
Parameter Type Description
username required string User's username
password required string User's password
Example Request
cURL
curl -X POST http://localhost:8000/api/token/ \
  -H "Content-Type: application/json" \
  -d '{"username": "demo_doctor", "password": "DemoPass123!"}'
Response
200 OK 
{
  "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}

Refresh Token

POST /api/token/refresh/ Public

Obtain a new access token using a refresh token.

Request Body
Parameter Type Description
refresh required string Refresh token from login
Response
200 OK 
{
  "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}

Get Current User

GET /whoami/ JWT Required

Get information about the currently authenticated user.

Response
200 OK 
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "username": "demo_doctor",
  "role": "Doctor",
  "email": "doctor@demo.local",
  "staff_id": "STF001",
  "staff_name": "Dr. Craig Hawkins",
  "department": "Internal Medicine"
}

Error Handling

The API returns standard HTTP status codes and JSON error responses.

Status Code Description
200 Success
400 Bad Request - Invalid parameters
401 Unauthorized - Invalid or missing token
403 Forbidden - RBAC access denied
404 Not Found - Resource doesn't exist
500 Server Error
Error Response Format
403 Forbidden 
{
  "error": "Access denied",
  "message": "Your role (Reception) does not have permission to access medical records",
  "code": "RBAC_DENIED"
}

Chat Endpoints

Create Chat Session

POST /api/chat/session/ JWT Required

Create a new chat session for the authenticated user.

Response
200 OK 
{
  "session_id": "f8c7b6a5-4d3c-2e1f-0a9b-8c7d6e5f4a3b",
  "title": "New Chat",
  "created_at": "2024-12-08T14:30:00Z"
}

List Chat Sessions

GET /api/chat/sessions/ JWT Required

List all chat sessions for the authenticated user, ordered by most recent.

Response
200 OK 
{
  "sessions": [
    {
      "session_id": "f8c7b6a5-4d3c-2e1f-0a9b-8c7d6e5f4a3b",
      "title": "Medical Records: FCE57",
      "updated_at": "2024-12-08T14:35:00Z"
    },
    {
      "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "title": "Patient Appointments",
      "updated_at": "2024-12-08T10:20:00Z"
    }
  ]
}

Get Chat History

GET /api/chat/history/ JWT Required

Get all messages for a specific chat session.

Query Parameters
Parameter Type Description
session_id required uuid ID of the chat session
Response
200 OK 
{
  "session_id": "f8c7b6a5-4d3c-2e1f-0a9b-8c7d6e5f4a3b",
  "title": "Medical Records: FCE57",
  "messages": [
    {
      "role": "user",
      "content": "Get medical records for patient FCE57",
      "created_at": "2024-12-08T14:30:00Z"
    },
    {
      "role": "assistant",
      "content": "Here are the medical records for patient FCE57...",
      "created_at": "2024-12-08T14:30:05Z"
    }
  ]
}

Chat Stream (SSE)

GET /chat/stream/ Session Auth

Stream AI responses using Server-Sent Events (SSE). Returns real-time chunks as the AI generates its response.

Query Parameters
Parameter Type Description
session_id required uuid ID of the chat session
message required string User's message
SSE Events
Event Description
chunk Text chunk from AI response
tool_call MCP tool invocation
tool_result Result from MCP tool
session_update Session title changed
end Stream complete
error Error occurred
Example Usage (JavaScript)
JavaScript
const params = new URLSearchParams({
  session_id: "f8c7b6a5-4d3c-2e1f-0a9b-8c7d6e5f4a3b",
  message: "Get medical records for FCE57"
});

const es = new EventSource(`/chat/stream/?${params}`);

es.addEventListener("chunk", (e) => {
  const data = JSON.parse(e.data);
  console.log("Chunk:", data.delta);
});

es.addEventListener("tool_call", (e) => {
  const data = JSON.parse(e.data);
  console.log("Tool:", data.tool_name);
});

es.addEventListener("end", () => {
  es.close();
});

Data Endpoints

Get Sample Data

GET /api/sample-data/ JWT Required

Get sample patients and staff for testing. Returns random records from the database.

Response
200 OK 
{
  "patients": [
    {
      "patient_id": "FCE57",
      "name": "Leah Arnold",
      "gender": "F",
      "birth_year": "1985"
    },
    {
      "patient_id": "6VCB8",
      "name": "Michael Chen",
      "gender": "M",
      "birth_year": "1972"
    }
  ],
  "staff": [
    {
      "staff_id": "STF001",
      "name": "Dr. Craig Hawkins",
      "username": "demo_doctor",
      "role": "Doctor",
      "department": "Internal Medicine"
    }
  ]
}

Get Demo Accounts

GET /api/demo-accounts/ Public

Get list of demo accounts for testing. This is a public endpoint used by the landing page.

Response
200 OK 
{
  "accounts": [
    {
      "username": "demo_doctor",
      "role": "Doctor",
      "name": "Dr. Craig Hawkins",
      "staff_id": "STF001"
    },
    {
      "username": "demo_nurse",
      "role": "Nurse",
      "name": "Sarah Johnson",
      "staff_id": "STF002"
    }
  ],
  "default_password": "DemoPass123!"
}

Get Recent Audit Logs

GET /audit-latest/ JWT Required

Get the 10 most recent audit log entries.

Response
200 OK 
{
  "items": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "action": "TOOL_CALL",
      "table_name": "medical_records",
      "timestamp": "2024-12-08T14:30:05Z",
      "user_id": "demo_doctor"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "action": "ACCESS_GRANTED",
      "table_name": "patients",
      "timestamp": "2024-12-08T14:30:02Z",
      "user_id": "demo_doctor"
    }
  ]
}

MCP Tools

MCP (Model Context Protocol) tools are invoked by the AI to access healthcare data. Each tool enforces RBAC and logs all access to the audit trail.

Tool Invocation

MCP tools are called automatically by the AI based on user queries. You don't call them directly - the AI decides which tools to use.

get_patient_overview

TOOL get_patient_overview All Roles

Get basic patient demographics including name, gender, and date of birth.

Parameters
Parameter Type Description
patient_id required string Patient identifier (e.g., "FCE57")

get_medical_records

TOOL get_medical_records Doctor, Nurse, Auditor

Get clinical notes, diagnoses, and treatment information.

Parameters
Parameter Type Description
patient_id required string Patient identifier

get_patient_phi

TOOL get_patient_phi Doctor, Admin, Auditor

Get Protected Health Information including SSN, addresses, and insurance details.

Parameters
Parameter Type Description
patient_id required string Patient identifier

Restricted Access

This tool returns sensitive PHI. Access is logged and requires elevated permissions.

get_appointments

TOOL get_appointments All Clinical Roles

Get patient appointment history and upcoming appointments.

Parameters
Parameter Type Description
patient_id required string Patient identifier

get_admissions

TOOL get_admissions Doctor, Nurse, Admin

Get patient hospital admission history.

Parameters
Parameter Type Description
patient_id required string Patient identifier

get_my_shifts

TOOL get_my_shifts All Staff

Get the current user's scheduled shifts.

Parameters

No parameters required. Uses the authenticated user's staff ID.

Documentation Back to Home