Skip to content

api_reference.md

Latest commit

 

History

History
215 lines (166 loc) · 2.9 KB

api_reference.md

File metadata and controls

215 lines (166 loc) · 2.9 KB
Raw

API Reference

Base URL

http://localhost:8000

Endpoints

Health Check

GET /health

Response:

{"status": "ok", "service": "scenesim-api"}

List Scenarios

GET /scenarios

Response: ScenarioSummary[]

[
  {
    "id": "chf_pulmonary_edema_01",
    "title": "CHF Exacerbation – Pulmonary Edema with Chest Pain",
    "tags": ["medical", "cardiac", "respiratory"],
    "difficulty": "intermediate"
  }
]

Get Scenario

GET /scenarios/{scenario_id}

Response: ScenarioDefinition (full scenario JSON)

List Protocols

GET /protocols

Response: ProtocolSummary[]

Get Protocol Pack

GET /protocols/{county_id}

Response: CountyProtocolPack

Create Session

POST /sessions

Request Body:

{
  "scenario_id": "chf_pulmonary_edema_01",
  "county_id": "demo_county",
  "cert_level": "EMT-B",
  "learner_id": "student-001",
  "guardrail_level": "standard"
}

Response: SessionCreateResponse

{
  "session_id": "uuid",
  "scenario_id": "chf_pulmonary_edema_01",
  "dispatch_text": "Unit 42, respond to...",
  "turn_count": 0
}

Get Session

GET /sessions/{session_id}

Response: Session (full session state)

Submit Turn

POST /sessions/{session_id}/turns

Request Body:

{
  "message_mode": "action",
  "action_id": "bsi",
  "user_text": null,
  "metadata": {}
}

Or for speech:

{
  "message_mode": "speak",
  "user_text": "Hello, what happened here?",
  "action_id": null,
  "metadata": {}
}

Response: SimulationResponse

{
  "turn_number": 1,
  "role_messages": [...],
  "state_updates": {},
  "newly_revealed_findings": [],
  "obtained_vitals": null,
  "blocked_actions": [],
  "guardrail_feedback": [],
  "session_summary_snippet": "",
  "is_complete": false
}

End Session

POST /sessions/{session_id}/end

Request Body:

{"reason": "learner_ended"}

Response: EndSessionResponse

{
  "session_id": "uuid",
  "is_complete": true,
  "final_score": 15.0,
  "message": "Session ended. Score: 75.0%"
}

Get Report

GET /sessions/{session_id}/report

Response: ReviewReport

{
  "session_id": "uuid",
  "scenario_id": "chf_pulmonary_edema_01",
  "total_score": 15.0,
  "max_possible": 20.0,
  "percentage": 75.0,
  "domain_scores": [...],
  "critical_actions_hit": ["bsi", "scene_safe", ...],
  "critical_actions_missed": ["radio_handoff"],
  "contraindications_violated": [],
  "debrief_text": "...",
  "strengths": [],
  "areas_for_improvement": []
}

Error Responses

All errors return:

{"detail": "Error message"}
Status Meaning
400 Bad request (e.g., session already complete)
404 Resource not found
422 Validation error
500 Internal server error