Choosing R4 vs R5

The Huli Public API serves both FHIR releases side by side. Pick the one that matches your integration — you do not have to migrate, and both stay supported. Use the R4 / R5 switch in the API sidebar (or the switch on any resource page) to browse either release.

#Use R4 when

R4 is the stable default and the right choice for the vast majority of integrations:

• You already integrate against /fhir/R4 — there's no reason to change.
• Your client library, middleware, or partner system speaks R4 (the most widely deployed FHIR release).
• You want the surface with the most third-party tooling and examples.

#Use R5 when

R5 advertises the newer R5 wire shapes and one capability R4 cannot express:

• Appointment recurrence. Only R5 supports recurring series via the recurrenceTemplate element (POST with a recurrenceTemplate creates a series; series edits select scope with the _recurrenceScope query parameter — this | this-and-following | all). R4 has no equivalent. See the R5 Appointment reference.
• Encounter redesign. R5 reshapes Encounter: class becomes a list (class[]), the period field is actualPeriod, and subjectStatus replaces the R4 patient-status modelling. See the R5 Encounter reference.
• R5 Observation shape. R5 Observation follows the R5 element model. See the R5 Observation reference.

#What's the same across both

Authentication and access control are identical — there is one auth surface, not two:

• Same SMART Backend Services authentication and POST /auth/token flow.
• Same scopes: a system/Patient.rs token works against both /fhir/R4 and /fhir/R5. The release is chosen by the request path, not the scope.
• Same cursor-based pagination (_count, next).
• The same resources are served on both releases: Patient, Appointment, Encounter, Observation, MedicationRequest, ServiceRequest, Composition, DocumentReference, Practitioner, Organization, HealthcareService, PractitionerRole, Schedule, Slot. Only Subscription, Location, Device, CodeSystem, ValueSet remain R4-only.

Because the auth and scope model is shared, you can call both releases with the same access token — switch by changing /fhir/R4 to /fhir/R5 in the request path.