Public guide for AI agents
Understand the schedule before answering it.
Use the account-scoped API to answer questions about OR and clinic schedules, resident and attending call, rotations, and directory phone numbers. Keep all scheduling text free of patient identifiers.
Start in three steps
Authenticate
With credentials supplied privately by the account holder, POST /api/auth/login with {"username":"…","password":"…"}. Send the returned token as Authorization: Bearer <token>. A user-provided personal key works in X-API-Key.
Check context
Call GET /api/session for identity and service privileges. Call GET /api/state for current IDs, weeks, rotations, assignments, and version. Use GET /api/weeks/{weekId}/schedule for computed OR and clinic coverage.
Ask or edit
Use POST /api/chat for natural-language questions. Service editors can add cases through POST /api/entities/cases and assign residents through POST /api/assignments. Send X-State-Version on planner writes.
Useful questions and routes
| Need | Use |
|---|---|
| OR blocks, cases, clinic coverage, or rotations | GET /api/state, GET /api/weeks/{weekId}/schedule, or POST /api/chat |
| Resident call team or call totals | coverageEntries in state, or POST /api/chat |
| Attending call | GET /api/attending-coverage?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD; read effectiveCoverage |
| Phone numbers | GET /api/contacts or POST /api/chat; use the directory as the source |
POST /api/chat
{"serviceLine":"Davies","messages":[{"role":"user","content":"Who is on call this weekend?"}]}How call is organized
Resident surgery call
Each Friday, Saturday, and Sunday has three resident positions: senior/chief, mid-level, and intern. In the API these are coverageEntries with kind: "call" and callPosition values senior, mid-level, or intern.
When someone asks “who is on call?”, they usually mean this three-person resident team. An SCC/ICU call resident may appear separately, without a callPosition.
Attending call
A generic “who is the attending on call?” usually means the ACS attending. The ACS line consolidates EGS, Trauma, and SCC night call; those services have separate daytime coverage.
“Practice attending” or “attending for Berry, Davies, or Fogel” means the independent Practice line. Berry may be spoken as “Barry.” Practice coverage is being populated; if no entry is returned, say it is not scheduled yet rather than substituting ACS. Vascular, Pediatrics, and NRV have their own lines.
Residency blocks and services
Residents rotate through dated blocks on services such as Berry, Davies, and Fogel. Their rotationSchedule identifies the active service for a date, which shapes expected OR and clinic work. Check the actual block, case, clinic, and resident assignments before saying where someone is working; service membership alone is not a case assignment.
For attending call, read the API’s effectiveCoverage over the requested date range so day/night and weekend carryover rules are applied. Ask for a date or shift when a call question is ambiguous.