---
title: 'Choosing R4 vs R5'
description: 'When to target FHIR R4 vs R5 on the Huli Public API — both are supported; pick by wire shape and integration maturity.'
nav: 'API / FHIR versions'
order: 5
version: v1
source: generated
updated: '2026-09-23'
---

# 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.

| | FHIR R4 | FHIR R5 |
|---|---------|---------|
| Base path | `/fhir/R4` | `/fhir/R5` |
| CapabilityStatement | `GET /fhir/R4/metadata` | `GET /fhir/R5/metadata` |
| `fhirVersion` | `4.0.1` | `5.0.0` |
| Resource reference | [R4 resources](/v1/api/resources) | [R5 resources](/v1/api/resources) |
| Maturity | Stable default | Newer wire shapes |

## 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](/v1/api/r5/appointment).
- **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](/v1/api/r5/encounter).
- **R5 Observation shape.** R5 Observation follows the R5 element model. See the
  [R5 Observation reference](/v1/api/r5/observation).

## What's the same across both

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

- Same [SMART Backend Services authentication](/v1/auth) and `POST /auth/token`
  flow.
- Same [scopes](/v1/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](/v1/concepts/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.