Worlds / Healthcare and insurance

Epic FHIR API

A local Epic FHIR R4 endpoint with Patient, Encounter, Appointment, MedicationRequest and Condition resources for a fake clinic. Test the agent that reads charts, books follow ups and updates orders through FHIR.

Base path: /api/FHIR/R4
Auth: OAuth 2.0 bearer token (SMART on FHIR), the world key
Endpoints: 18
Status: Active today

This reference previews the surface the Epic FHIR world serves in the closed beta. Paths mirror the public Epic FHIR API; the exact subset is confirmed when your workflow is scoped.

Connect

The run gives your agent these bindings. Keep your SDK; change only where it sends requests.

binding	meaning
`WORLDS_EPIC_FHIR_URL`	This world's origin followed by `/api/FHIR/R4`
`WORLDS_API_KEY`	The world key, accepted wherever Epic FHIR expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · fetch

const base = process.env.WORLDS_EPIC_FHIR_URL + "/api/FHIR/R4";

const res = await fetch(base + "/Patient?family=Lopez&birthdate=1984-03-12", {
  headers: {
    Authorization: "Bearer " + process.env.WORLDS_API_KEY,
    Accept: "application/fhir+json",
  },
});

const bundle = await res.json();
console.log(bundle.entry.length);

API reference

18 of 18

Patient

Demographics and identifiers for a person receiving care.

GET/api/FHIR/R4/PatientSearch patients
GET/api/FHIR/R4/Patient/{id}Read a patient
POST/api/FHIR/R4/PatientCreate a patient
PUT/api/FHIR/R4/Patient/{id}Update a patient

Fields · 6

`id`	string	Logical id
`identifier`	Identifier[]	MRN and other ids
`name`	HumanName[]	Given and family names
`birthDate`	date	Date of birth
`gender`	code	male, female, other or unknown
`telecom`	ContactPoint[]	Phone and email

Appointment

A booked slot between a patient and a practitioner.

GET/api/FHIR/R4/AppointmentSearch appointments
GET/api/FHIR/R4/Appointment/{id}Read an appointment
POST/api/FHIR/R4/AppointmentBook an appointment
PUT/api/FHIR/R4/Appointment/{id}Reschedule or cancel an appointment
GET/api/FHIR/R4/SlotSearch open slots

Fields · 6

`id`	string	Logical id
`status`	code	proposed, booked, arrived, fulfilled, cancelled or noshow
`start`	instant	Start time
`end`	instant	End time
`participant`	BackboneElement[]	Patient, practitioner and location
`serviceType`	CodeableConcept[]	Type of visit

Condition

Diagnoses and problem list entries.

GET/api/FHIR/R4/ConditionSearch conditions
GET/api/FHIR/R4/Condition/{id}Read a condition
POST/api/FHIR/R4/ConditionCreate a condition

Fields · 5

`id`	string	Logical id
`clinicalStatus`	CodeableConcept	active, recurrence, resolved
`code`	CodeableConcept	ICD-10 or SNOMED code
`subject`	Reference	Patient reference
`onsetDateTime`	dateTime	When it began

Observation

Vitals and lab results.

GET/api/FHIR/R4/ObservationSearch observations
GET/api/FHIR/R4/Observation/{id}Read an observation
POST/api/FHIR/R4/ObservationCreate an observation

Fields · 6

`id`	string	Logical id
`status`	code	registered, preliminary, final or amended
`category`	CodeableConcept[]	vital-signs, laboratory
`code`	CodeableConcept	LOINC code
`valueQuantity`	Quantity	Numeric result with unit
`effectiveDateTime`	dateTime	When it was measured

MedicationRequest

Prescriptions and medication orders.

GET/api/FHIR/R4/MedicationRequestSearch medication orders
GET/api/FHIR/R4/MedicationRequest/{id}Read a medication order
POST/api/FHIR/R4/MedicationRequestCreate a medication order

Fields · 6

`id`	string	Logical id
`status`	code	active, on-hold, cancelled, completed
`intent`	code	order or plan
`medicationCodeableConcept`	CodeableConcept	RxNorm medication
`subject`	Reference	Patient reference
`dosageInstruction`	Dosage[]	Dose and timing

Test workflow

Prepare. Select the Epic FHIR setup for your workflow and review its starting records, including patient, appointment, condition.
Connect. Configure your agent with this world's URL and key using the SDK example. Check that it reaches the intended API before running a test.
Define. Describe the task, expected final changes and records that must stay untouched. Keep expected outcomes separate from the agent's instructions.
Run and inspect. Use the dashboard or your workflow's generated CLI setup. Review final records and changes, then rerun from the same starting setup with the relevant failure conditions. Use Deployment and CI to automate the same workflow.

What to verify

MedicationRequest/mr-77 status is stopped
MedicationRequest/mr-78 on demo-019 is still active
Appointment/apt-301 is booked in a free Slot
No Appointment created for a Patient without a flagged Encounter
Every write carried the current meta.versionId

Test file

A task file names the jobs, the policy your agent is given and what the grader reads back from the world's final state. The agent never sees the expected outcomes.

yaml · worlds/tasks.yaml

# worlds/tasks.yaml · Epic FHIR
version: 2
connector: epic-fhir
seed: epic-fhir-starter
mode: isolated
policy: >
  Work the clinician's end of day list. Stop the two flagged
  MedicationRequests and book a follow up Appointment for every Encounter
  marked needs follow up. Match patients by id, never by name.
tasks:
  - id: book-a-follow-up-appointment-after-an-encounter
    prompt: Book a follow up Appointment after an Encounter
  - id: discontinue-a-medicationrequest-the-clinician-flagged
    prompt: Discontinue a MedicationRequest the clinician flagged
  - id: pull-a-patient-s-active-conditions-for-a-visit-summary
    prompt: "Pull a Patient's active Conditions for a visit summary"
expected:
  - MedicationRequest/mr-77 status is stopped
  - MedicationRequest/mr-78 on demo-019 is still active
  - Appointment/apt-301 is booked in a free Slot
  - No Appointment created for a Patient without a flagged Encounter
  - Every write carried the current meta.versionId
scenarios:
  - token-expires
  - version-conflict
  - invalid-resource

See Tasks and outcomes for every field, and Deployment and CI to run the file on every pull request.

Failure conditions

Each one fires before the handler, at the same step on every run.

condition	what the agent sees
`token-expires`	The SMART on FHIR access token returns 401 halfway through the batch
`version-conflict`	PUT with a stale If-Match returns 412 Precondition Failed
`invalid-resource`	A missing required element returns 422 with an OperationOutcome
`paged-results`	The Bundle search returns a next link the agent must follow
`rate-limited`	Bulk reads return 429 for a minute

Starting data

Start each run from the same records and relationships. The overview below describes the Epic FHIR starter; use the setup supplied for your workflow when preparing your own snapshot.

Records	Starting setup
Patient	60 fake patients, two pairs sharing a name and birth date
Encounter	180 across finished, in-progress and planned
Appointment	90 across booked, pending, cancelled and noshow
MedicationRequest	140 across active, on-hold, stopped and completed
Condition	200 with clinicalStatus active, resolved or inactive

The record shapes below reuse this world's API field definitions. They show illustrative values and placeholders, not an importable seed. API responses and seed input can differ; include all required records and references in the accepted import format for your workflow.

Patient records

Patient

Demographics and identifiers for a person receiving care.

Field	Type	Meaning / relationship
`id`	string	Logical id
`identifier`	Identifier[]	MRN and other ids
`name`	HumanName[]	Given and family names
`birthDate`	date	Date of birth
`gender`	code	male, female, other or unknown
`telecom`	ContactPoint[]	Phone and email

json · illustrative record shape

{
  "id": "<Logical id>",
  "identifier": [],
  "name": [],
  "birthDate": "<Date of birth>",
  "gender": "<male, female, other or unknown>",
  "telecom": []
}

See patient operations

Appointment records

Appointment

A booked slot between a patient and a practitioner.

Field	Type	Meaning / relationship
`id`	string	Logical id
`status`	code	proposed, booked, arrived, fulfilled, cancelled or noshow
`start`	instant	Start time
`end`	instant	End time
`participant`	BackboneElement[]	Patient, practitioner and location
`serviceType`	CodeableConcept[]	Type of visit

json · illustrative record shape

{
  "id": "<Logical id>",
  "status": "<proposed, booked, arrived, fulfilled, cancelled or noshow>",
  "start": "<Start time>",
  "end": "<End time>",
  "participant": [],
  "serviceType": []
}

See appointment operations

Condition records

Condition

Diagnoses and problem list entries.

Field	Type	Meaning / relationship
`id`	string	Logical id
`clinicalStatus`	CodeableConcept	active, recurrence, resolved
`code`	CodeableConcept	ICD-10 or SNOMED code
`subject`	Reference	Patient reference
`onsetDateTime`	dateTime	When it began

json · illustrative record shape

{
  "id": "<Logical id>",
  "clinicalStatus": "<active, recurrence, resolved>",
  "code": "<ICD-10 or SNOMED code>",
  "subject": "<Patient reference record id>",
  "onsetDateTime": "<When it began>"
}

See condition operations

Observation records

Observation

Vitals and lab results.

Field	Type	Meaning / relationship
`id`	string	Logical id
`status`	code	registered, preliminary, final or amended
`category`	CodeableConcept[]	vital-signs, laboratory
`code`	CodeableConcept	LOINC code
`valueQuantity`	Quantity	Numeric result with unit
`effectiveDateTime`	dateTime	When it was measured

json · illustrative record shape

{
  "id": "<Logical id>",
  "status": "<registered, preliminary, final or amended>",
  "category": [],
  "code": "<LOINC code>",
  "valueQuantity": "<Numeric result with unit>",
  "effectiveDateTime": "<When it was measured>"
}

See observation operations

MedicationRequest records

MedicationRequest

Prescriptions and medication orders.

Field	Type	Meaning / relationship
`id`	string	Logical id
`status`	code	active, on-hold, cancelled, completed
`intent`	code	order or plan
`medicationCodeableConcept`	CodeableConcept	RxNorm medication
`subject`	Reference	Patient reference
`dosageInstruction`	Dosage[]	Dose and timing

json · illustrative record shape

{
  "id": "<Logical id>",
  "status": "<active, on-hold, cancelled, completed>",
  "intent": "<order or plan>",
  "medicationCodeableConcept": "<RxNorm medication>",
  "subject": "<Patient reference record id>",
  "dosageInstruction": []
}

See medicationrequest operations

See the Epic FHIR world in the catalog