Building an AI Agent on OpenEMR: What the Docs Don't Tell You

OpenEMR is one of the most widely deployed open-source EHR systems in the world, but building an AI agent on top of it involves a handful of non-obvious gotchas that will burn you if you go in blind. This is a practical guide based on real production experience. Not a tutorial — just the things I wish were documented. Use FHIR for Clinical Reads, REST for Exceptions OpenEMR exposes two APIs: FHIR R4 at /apis/default/fhir/ Standard REST at /apis/default/api/ The short answer: use FHIR for everything you can. The Standard API mixes numeric pid with UUID puuid depending on the endpoint (medications and vitals use numeric IDs, everything else uses UUIDs). FHIR uses UUIDs consistently. The two exceptions where you'll need the REST API: Insurance/coverage — the FHIR Coverage mapper is incomplete (missing plan_name , group_number , date_end ). Use GET /api/patient/:puuid/insurance instead. Practitioner specialty — FHIR Practitioner doesn't map the specialty field. Use GET /api/practitioner wh