MedicAITutor Docs

MedicAI Tutor API Documentation

Base URL: https://medicaitutor.mededgeglobal.com

Table of Contents

Health Check

Endpoint 
GET /healthz
Description Verifies server health status. Response (200) 
{
  "status": "ok",
  "env": "staging"
}
↑ Back to top

Stations (List)

Endpoint 
GET /stations
Description Lists stations with minimal metadata. Response (200) 
{
  "items": [
    {
      "slug": "acute-presentation-of-psychosis-in-the-context-of-cannabis-misuse",
      "title": "ACUTE PRESENTATION OF PSYCHOSIS IN THE CONTEXT OF CANNABIS MISUSE",
      "section": "PSYCHOSIS AND SUBSTANCE-RELATED PRESENTATIONS",
      "station_category": "mixed"
    },
    {
      "slug": "benzodiazepine-dependence-management-plan",
      "title": "BENZODIAZEPINE DEPENDENCE-MANAGEMENT PLAN",
      "section": "SUBSTANCE MISUSE AND DEPENDENCE",
      "station_category": "mixed"
    },
    {
      "slug": "early-menopausal-symptoms-assess",
      "title": "EARLY MENOPAUSAL SYMPTOMS-ASSESS",
      "section": "WOMEN’S MENTAL HEALTH",
      "station_category": "mixed"
    },
    {
      "slug": "emotional-abuse-from-husband",
      "title": "EMOTIONAL ABUSE FROM HUSBAND",
      "section": "SAFEGUARDING AND DOMESTIC ABUSE",
      "station_category": "mixed"
    },
    {
      "slug": "generalised-anxiety-disorder-take-hx",
      "title": "GENERALISED ANXIETY DISORDER-TAKE HX",
      "section": "ANXIETY DISORDERS",
      "station_category": "mixed"
    },
    {
      "slug": "severe-obsessional-thoughts-with-checking-behaviour",
      "title": "SEVERE OBSESSIONAL THOUGHTS WITH SOME CHECKING BEHAVIOUR",
      "section": "OBSESSIVE–COMPULSIVE AND RELATED DISORDERS",
      "station_category": "mixed"
    }
  ],
  "total": 6
}
↑ Back to top

Sections Index (by Station)

Endpoint 
GET /stations/sections
Description Returns all syllabus/blueprint sections and the station slugs they contain. Response (200) 
{
  "sections": {
    "PSYCHOSIS AND SUBSTANCE-RELATED PRESENTATIONS": [
      "acute-presentation-of-psychosis-in-the-context-of-cannabis-misuse"
    ],
    "SUBSTANCE MISUSE AND DEPENDENCE": [
      "benzodiazepine-dependence-management-plan"
    ],
    "WOMEN’S MENTAL HEALTH": [
      "early-menopausal-symptoms-assess"
    ],
    "SAFEGUARDING AND DOMESTIC ABUSE": [
      "emotional-abuse-from-husband"
    ],
    "ANXIETY DISORDERS": [
      "generalised-anxiety-disorder-take-hx"
    ],
    "OBSESSIVE–COMPULSIVE AND RELATED DISORDERS": [
      "severe-obsessional-thoughts-with-checking-behaviour"
    ]
  }
}
↑ Back to top

Station (By Slug)

Endpoint 
GET /stations/{slug}
Description Returns the full station payload (task, prompts, persona, guardrails, rubric, etc.). Path Params slug string Required Station slug (URL-safe) Response (200) 
{
  "slug": "acute-presentation-of-psychosis-in-the-context-of-cannabis-misuse",
  "section": "PSYCHOSIS AND SUBSTANCE-RELATED PRESENTATIONS",
  "title": "ACUTE PRESENTATION OF PSYCHOSIS IN THE CONTEXT OF CANNABIS MISUSE",
  "task": "TASK: Mr. Austin Soames is a 30 year old man who was detained by the police and brought to a place of safety. Please carry out a mental state examination.",
  "prompts": {
    "station_name": "TOPIC 1: ACUTE PRESENTATION OF PSYCHOSIS IN THE CONTEXT OF CANNABIS MISUSE",
    "case_synopsis": "You are Mr. Austin Soames, a 30-year-old man who has become increasingly suspicious, withdrawn, and distressed by voices over the last three months."
  },
  "lead": "hearing voices from the light fittings and switches; trying to escape people shouting at him; wandering at 3AM",
  "key_points": [
    "3-month progression of persecutory and referential ideas; delusional perception involving a man in a blue jacket",
    "Auditory hallucinations with mocking and threatening content; perceived transmitters; continued outside the flat",
    "Functional decline with withdrawal, sealed food purchases, and stopping work",
    "Cannabis use daily at 6 to 8 joints with escalation linked to stress and symptom progression",
    "No suicidal or homicidal intent but clear risk of accidental harm while fleeing",
    "Absent insight with loss of train of thought"
  ],
  "persona": {
    "name": "Mr. Austin Soames",
    "age": 30,
    "affect": "anxious, suspicious, intermittently distressed by voices",
    "communication_style": "guarded but engages with reassurance; occasional loss of train of thought; distracted by perceived voices",
    "goals_concerns": [
      "get away from voices and transmitters",
      "stay safe from people he believes are trying to harm him",
      "make sure his cannabis is not adulterated"
    ],
    "nonverbal_cues": [
      "frequent scanning of the room and ceiling lights",
      "tense posture",
      "pauses to listen during the interview"
    ],
    "do_not_volunteer": [
      "exact trigger as a delusional perception unless asked",
      "frequency or quantity of cannabis use unless asked directly",
      "lack of insight that experiences may be illness"
    ]
  },
  "guardrails": {
    "forbidden_topics": [
      "directly challenging delusional beliefs",
      "promising specific medication changes or discharge outcomes within the station"
    ],
    "mandatory_disclosures": [
      "denies active intent to harm self or others",
      "acknowledges risk of accidental harm from fleeing while distressed"
    ],
    "handoff_triggers": [
      "command hallucinations to harm self or others",
      "unmanageable agitation or severe disorganisation"
    ],
    "privacy_rules": [
      "avoid real third-party identifiers"
    ],
    "out_of_scope_responses": [
      "I don't want to talk about treatment plans right now; I just need to feel safe."
    ]
  },
  "rubric": {
    "marking_sheet_title": "MARKING SHEET: ACUTE PRESENTATION OF PSYCHOSIS IN THE CONTEXT OF CANNABIS MISUSE",
    "overall_scale": [
      "SEVERE FAIL",
      "FAIL",
      "BORDERLINE FAIL",
      "BORDERLINE PASS",
      "PASS",
      "EXCELLENT PASS"
    ],
    "domain_rating_scale": [
      "Very Poor",
      "Poor",
      "Average",
      "Good",
      "Excellent"
    ],
    "rating_to_score": {
      "Very Poor": 0.0,
      "Poor": 0.25,
      "Average": 0.5,
      "Good": 0.75,
      "Excellent": 1.0
    },
    "competency_items": [
      {
        "label": "Elicit Circumstances of admission to the designated place of safety",
        "weight": 1.0,
        "scoring_mode": "level",
        "critical": true
      },
      {
        "label": "Elicits relevant recent history including time course and progression of psychotic symptoms, presence of escalating cannabis use and its relation to symptoms",
        "weight": 1.0,
        "scoring_mode": "level",
        "critical": true
      },
      {
        "label": "Elicit persecutory and referential delusional ideation and its effect on the patient's functioning. Identify delusional perception",
        "weight": 1.0,
        "scoring_mode": "level",
        "critical": true
      },
      {
        "label": "Elicit evidence of auditory hallucinations and their character. Screen for other hallucinations",
        "weight": 1.0,
        "scoring_mode": "level",
        "critical": true
      },
      {
        "label": "Examine for degree of insight into psychotic symptoms",
        "weight": 1.0,
        "scoring_mode": "level",
        "critical": true
      },
      {
        "label": "Consider risk to self, accidental harm, and others in view of persecutory ideation",
        "weight": 1.0,
        "scoring_mode": "level",
        "critical": true
      }
    ],
    "feedback_checklist": [
      {
        "id": 1,
        "title": "Use more open questions before narrowing down",
        "details": "Avoid a rigid sequence of closed questions."
      },
      {
        "id": 2,
        "title": "Respond to emotional and psychotic cues",
        "details": "Acknowledge distress and follow up relevant cues sensitively."
      }
    ]
  },
  "evaluation": {
    "version": "ev-1.2.0-inferred"
  },
  "sources": {
    "pdf": "CASC_lessons.pdf (as referenced in text)"
  },
  "station_meta": {
    "topic": "TOPIC 1: ACUTE PRESENTATION OF PSYCHOSIS IN THE CONTEXT OF CANNABIS MISUSE",
    "time_limit_minutes": 8,
    "setting": "local 136 suite",
    "expected_diagnosis": "Acute psychotic episode with persecutory and referential delusions and auditory hallucinations; cannabis-associated psychosis"
  }
}
↑ Back to top

Station Revisions

Endpoint 
GET /stations/{slug}/revisions
Description Lists immutable snapshots saved whenever a station is created, updated, deleted, or rolled back. Endpoint 
POST /stations/{slug}/revisions/{revision_id}/rollback
Description Restores a previous revision as the current station and writes a new revision entry. Response (200) 
{
  "items": [
    {
      "id": 12,
      "slug": "acute-presentation-of-psychosis-in-the-context-of-cannabis-misuse",
      "revision_number": 3,
      "action": "update",
      "created_at": "2026-03-23T10:15:00Z",
      "note": null
    }
  ],
  "total": 1
}
↑ Back to top

Ask Me Anything

Endpoint 
POST /ask
Description General-purpose assistant endpoint. Accepts text and optional audio/document uploads, stores the raw files, extracts text, and can answer back with AI-generated guidance. Content-Type multipart/form-data Form Fields text string Optional General question or prompt audio file Optional Audio upload to transcribe documents file[] Optional One or more documents to extract text from station_slug string Optional Station context if the user wants station-specific help exam_slug string Optional Mock exam context category string Optional Free-form hint for routing Response (200) 
{
  "interaction": {
    "kind": "ask",
    "station_slug": "acute-presentation-of-psychosis-in-the-context-of-cannabis-misuse",
    "category": "history_taking",
    "attachment_paths": [
      "raw/document/example.txt"
    ]
  },
  "answer": "The main difference is ...",
  "provider": "openai",
  "model": "gpt-4o-mini"
}
↑ Back to top

Feedback

Endpoint 
POST /feedback
Description Stores user comments or review notes in the database and can optionally send a short AI acknowledgement back. Payload 
{
  "text": "Please make the morning paper a bit harder.",
  "exam_slug": "morning-paper",
  "category": "exam-feedback"
}
Response (200) 
{
  "interaction": {
    "kind": "feedback",
    "exam_slug": "morning-paper",
    "ai_text": "Thanks. I will pass this on."
  },
  "provider": "local",
  "model": "local-osce-sim"
}
↑ Back to top

Mock Exams

Endpoint 
GET /mock-exams
Endpoint 
GET /mock-exams/{slug}/station-ids
Description Lists the exam sets and the station slugs that belong to each set. Response (200) 
{
  "items": [
    {
      "slug": "morning-paper",
      "title": "Morning Paper",
      "session_label": "morning",
      "station_slugs": [
        "acute-presentation-of-psychosis-in-the-context-of-cannabis-misuse",
        "benzodiazepine-dependence-management-plan",
        "early-menopausal-symptoms-assess"
      ]
    }
  ],
  "total": 1
}
↑ Back to top

Interactions

Endpoint 
GET /interactions/api
Description Browse Ask Me Anything, feedback, and evaluation history with server-side filters for kind, station slug, exam slug, and created-at window. Filters kind string Optional ask, feedback, evaluation, or evaluation_summary station_slug string Optional Limit results to one station exam_slug string Optional Limit results to one mock exam created_after string Optional ISO-8601 timestamp created_before string Optional ISO-8601 timestamp Response (200) 
{
  "items": [
    {
      "id": 21,
      "kind": "ask",
      "station_slug": "acute-presentation-of-psychosis-in-the-context-of-cannabis-misuse",
      "exam_slug": "morning-paper",
      "created_at": "2026-03-23T11:00:00Z"
    }
  ],
  "total": 1
}
↑ Back to top

Chat (Text)

Endpoint 
POST /chat/text
Description Candidate sends a text question and receives the patient reply, transcript updates, and provider metadata. Payload 
{
  "station": "acute-presentation-of-psychosis-in-the-context-of-cannabis-misuse",
  "messages": [
    {
      "role": "user",
      "content": "Hello, how are you feeling today?"
    }
  ]
}
Response (200) 
{
  "reply": "I'm okay, just feeling a bit low.",
  "messages": [
    {
      "role": "user",
      "content": "Hello, how are you feeling today?"
    },
    {
      "role": "assistant",
      "content": "I'm okay, just feeling a bit low."
    }
  ],
  "transcript": [
    {
      "role": "candidate",
      "text": "Hello, how are you feeling today?"
    },
    {
      "role": "patient",
      "text": "I'm okay, just feeling a bit low."
    }
  ],
  "provider": "openai",
  "model": "gpt-4o"
}
↑ Back to top

Chat (Audio Upload)

Endpoint 
POST /chat/audio?station=
Description Candidate uploads audio and receives transcript, patient response, and TTS audio metadata. Content-Type multipart/form-data Form Fields file audio/wav Required 16-bit PCM mono WAV Response (200) 
{
  "transcript": [
    {
      "role": "candidate",
      "text": "I have been feeling on edge recently."
    },
    {
      "role": "patient",
      "text": "I'm sorry to hear that. Can you tell me more about when it started?"
    }
  ],
  "reply": "I'm sorry to hear that. Can you tell me more about when it started?",
  "provider": "faster_whisper",
  "tts_provider": "openai",
  "audio_url": "/media/tts/example.wav"
}
↑ Back to top

Realtime Websocket

Endpoint 
wss://api.medicaitutor.mededgeglobal.com/realtime
Description Streaming text/audio turn-taking with live transcript events. Events candidate_text, stt_partial, stt_final, patient_text, tts_audio, evaluator_summary Example transcript shape 
{
  "conversation": [
    {
      "role": "candidate",
      "content": "What brought you in today?"
    },
    {
      "role": "patient",
      "content": "I keep hearing voices at night."
    }
  ],
  "provider": {
    "asr": "faster_whisper",
    "nlp": "openai",
    "tts": "openai"
  }
}
↑ Back to top

Provider-Scoped Routes

Purpose Use these routes when you want to inspect a specific provider directly instead of the currently active stack. Examples 
GET /asr/faster_whisper
POST /asr/faster_whisper/batch
GET /tts/openai
POST /tts/openai/speak
GET /nlp/openai
POST /nlp/openai/simulated-patient
↑ Back to top

Sessions

Endpoint 
POST /session/start
Description Starts a new OSCE session for a chosen station. Endpoint 
GET /sessions/{session_id}
Description Returns the transcript, timestamps, and current station state. Endpoint 
POST /session/end
Description Closes the session and returns the final examiner summary.
↑ Back to top

Evaluation

Endpoint 
POST /evaluation/score
Description Scores the session transcript using the station rubric and returns the examiner view. Response (200) 
{
  "overall_rating": "PASS",
  "total_score": 0.71,
  "feedback": [
    "Improve: Explore risk and safety more explicitly.",
    "Use open questions early, then narrow into the key diagnosis."
  ]
}
↑ Back to top