{
"openapi": "/api/openapi.json",
"pages": [
{
"title": "API reference",
"url": "/docs/api/",
"format": "mdx",
"content": "# API reference\n\nOpen the interactive API explorer to browse every published operation, inspect its request schema, and execute requests. Download the OpenAPI 3.1 JSON specification to import it into an API client or give it to an agent. The specification is also available at `/openapi.json`.\n\nThese are synthetic simulation contracts. The NHS adapters implement the documented subset, not production NHS wire compatibility. CIS2 credentials do not grant access to team records.\n\n## Find the contract\n\n| Reference | Contents |\n| --- | --- |\n| Interactive explorer | Operations grouped by service, editable requests, responses, and authentication controls |\n| OpenAPI JSON | Machine-readable paths, parameters, schemas, examples, and security requirements |\n| Runtime catalogue | Published workplaces, NHS adapters, scenarios, and documentation links |\n| Handbook JSON | Every published guide with its title, URL, source format, and content for agents |\n| [First API workflow](/docs/quickstart/) | Create a world, find a patient, and submit an action |\n\nThe explorer uses this website's origin. Requests on the local simulator affect local worlds. Requests on `sim.animahacks.com` affect hosted worlds.\n\n## Authenticate a request\n\nCopy your existing key from **Team & API key** in any workspace. In the explorer, select **Authorize** and enter the key into the team bearer scheme. Enter the key without the `Bearer` prefix. Expand an operation, choose **Try it out**, fill its parameters, and select **Execute**.\n\nOutside the explorer, send `Authorization: Bearer YOUR_TEAM_KEY`. A key belongs to one world. It can also have service restrictions. The explorer clears authorization on reload.\n\n`POST /api/keys` is public. It creates or joins a team by name, normalised to lowercase with all whitespace removed. Repeating a name returns the same world and reusable `apiKey`. Anyone who knows the name can join its simulation world. Omit `site` when creating a team to access all API-enabled services; joining preserves its existing scopes. Each deployment supports up to 5,000 distinct team worlds, and existing teams can still rejoin at capacity. There is no per-IP or time-based sign-up throttle, so participants can create teams together on shared hackathon Wi-Fi.\n\nOperator operations require the separately configured operator token. List named teams with `GET /api/control/teams`, then inspect `GET /api/control/teams/{world}/activity` using a returned world ID. Existing clock, incident and agent operations select their world with `?world=...`. A team key cannot select another team's world. CIS2 access tokens are used only for the emulated identity endpoints.\n\n`POST /api/control/teams/{world}/session` lets an organiser obtain a participant key for that existing world without changing its permissions or resetting its records. The [organiser console](./organisers.mdx) provides team selection, request history, affected patients and an explicit return path after exploring as a team.\n\n## Read records and submit actions\n\n`GET /api/sites/{site}/patients` searches and pages through the team's patients. Use the returned patient identifier with `GET /api/sites/{site}/view?patient=SIM-000001`. This view includes the patient's visible records and service resources without a patient.\n\nThe resource view defaults to 500 resources. Use `limit` from 1 through 500 and advance `offset` to read more. Check `resourceTotal`, `resourceOffset`, and `resourceLimit`. A view is a projection of visible records, not an export of the complete world or its scheduled jobs.\n\n`POST /api/sites/{site}/actions` submits a typed action. The explorer's schema and examples describe the action fields. Use the relevant service and workflow guide. An action can create work for another service, so its response does not necessarily represent a completed patient journey.\n\nFor a versioned update, send the resource's current `version` as `expectedVersion`. Send an `Idempotency-Key` header when retrying the same logical action. The `clientRequestId` action field provides a body-based alternative. If both are present, the header takes precedence. Reuse the original request and key after an uncertain network response. A changed request with the same key returns a conflict.\n\n`POST /api/clock` controls only the authenticated team's clock. Send `paused: true` with `advanceMinutes` to pause and process scheduled results, visits, deliveries, and other activity. Stepping a running clock without pausing returns `409`. The explorer executes real changes in that synthetic world.\n\n## Raw secondary care records\n\nThe **Secondary care** Explorer group publishes `GET /api/sites/hospital/consultations` and `GET /api/sites/hospital/genomes`. Both require `hospital` scope. They preserve the stored resource payload, including consultation text and genomic SNP calls, with versions and provenance.\n\nBoth operations accept an exact `patient` filter and `offset` and `limit` pagination. Responses contain `items`, `total`, `offset`, `limit`, and `now`. The default page size is 100, with a maximum of 500. Team keys always access their own world.\n\nSee [clinical and genomic records](/docs/clinical-records/) for included consultation kinds, synthetic CYP2C19 data, and the hospital-only access boundary.\n\n## Wearable data\n\nThe **Wearables** Explorer group publishes the Home Health records in the authenticated team's world. Both operations require `wearables` scope.\n\n| Operation | Records | Filters |\n| --- | --- | --- |\n| `GET /api/sites/wearables/devices` | Connected synthetic devices, including battery and sync data where recorded | `patient` |\n| `GET /api/sites/wearables/readings` | Wearable observations with recorded values, units, quality, and timestamps | `patient`, `metric` |\n\nBoth responses contain `items`, `total`, `offset`, `limit`, and `now`. Pagination defaults to 100 records, with a maximum `limit` of 500. `total` counts all matching records before pagination. The optional `patient` filter matches an exact SIM identifier. The optional `metric` filter matches an exact recorded metric, such as `steps`, `heart-rate`, or `sleep`.\n\nEach item uses the simulator's resource envelope, with wearable fields inside `data`. Timestamps use Unix milliseconds. Disconnected devices can produce readings with `data.value: null` and `data.quality: \"missing\"`. These endpoints contain synthetic wearable records; laboratory results remain separate.\n\nThe [Home Health guide](/docs/home/) includes the watch connection and first-reading workflow. These operations and their schemas also appear in the downloadable OpenAPI document.\n\n## Follow a workflow\n\n- [GP Records](/docs/systemtwo/) covers GP consultations and patient records.\n- [Appointment book](/docs/appointments/) covers session slots, bookings, and attendance.\n- [Clinical records and hospital orders](/docs/clinical-records/) covers signed notes, addenda, prescriptions, and laboratory requests.\n- [Document processing](/docs/documents/) covers hospital discharge letters and GP filing.\n- [Practice and patient messaging](/docs/messaging/) covers role-specific messaging APIs, patient-initiated conversations, delivery, and scripted automatic replies.\n- [Home Health and wearable data](/docs/home/) covers connected devices, recorded readings, and simulated watch updates.\n- [Pharmacy](/docs/pharmacy/) covers referrals, dispensing, supplier quotes, purchasing, and stock costs.\n- [FHIR-shaped APIs](/docs/fhir/) covers supported demographics and organisation search.\n- [Legacy browser integration](/docs/legacy/) covers the HTML-only service and session cookies.\n- [Organiser controls](/docs/organisers/) covers administration and the configured model agent.\n\n## Handle errors\n\nRead the status code and response body. Most simulation errors use JSON with an `error` message. FHIR endpoints use their documented `OperationOutcome` responses, and CIS2 uses OAuth errors where appropriate.\n\n| Status | Typical cause | Next step |\n| --- | --- | --- |\n| `400` | Invalid input or malformed JSON | Correct the request using the operation schema |\n| `401` | Missing or invalid credentials | Check the authentication scheme and key |\n| `403` | Wrong scope, ownership, or operator permission | Use an authorized service and credential |\n| `404` | Unknown endpoint or missing resource | Check the path and the current world |\n| `409` | Stale version, changed retry payload, or invalid state transition | Refresh the record and resolve the conflict |\n| `413` | Request body exceeds the server limit | Reduce the payload |\n| `429` | The deployment has reached its 5,000-team cap | Contact the organiser |\n| `501` | A deliberately unsupported API capability | Use the documented alternative |\n| `503` | Simulated identity unavailability | Check the configured CIS2 scenario |\n\n## Keep integrations aligned\n\nThe JSON specification is generated from the implemented route catalogue and shared validation schemas where available. Repository tests check route coverage. The build packages the explorer with its JavaScript and CSS, and smoke checks verify that the published reference and explorer remain accessible.\n\nFor production NHS integration requirements, use the [NHS API catalogue](https://digital.nhs.uk/developer/api-catalogue). This simulator does not need live NHS credentials."
},
{
"title": "Appointment sessions and slots",
"url": "/docs/appointments/",
"format": "mdx",
"content": "Open **Appointment book** in GP Records. Each clinician has AM and PM sessions containing timed slots. The calendar, clinician filter and AM/PM controls change the diary view. All times use the team's simulation clock in UTC.\n\n## Book and manage a slot\n\nSelect an **Available** slot. Search for a patient by name or SIM identifier, enter the appointment reason and choose **Book appointment**. The session supplies the clinician, location, contact type and duration. Booked slots show the patient's name and appointment reason.\n\nSelect a booking to mark the patient as arrived, complete the appointment or cancel it. Cancelling makes the slot available again. Completed appointments remain in the diary as history. Bookings preserve the team that made each change.\n\n## Protected time and sessions\n\nSelect a free slot and expand **Block this slot** to record protected time, such as a break or administrative work. Select a blocked slot to unblock it. A booked slot cannot be blocked, and a blocked slot cannot be booked.\n\nThe initial diary contains seven days of GP, telephone and practice-nurse sessions. Use **Create session** to add more dates or clinicians. Sessions for the same clinician cannot overlap. The hours must divide into whole slots. Existing appointments outside session hours remain listed beneath the diary.\n\n## Agent API\n\n`GET /api/sites/gp/appointments?date=2026-09-12` returns `sessions`, `appointments` and patient names for the selected date. Use your team's actual simulation date.\n\nPost to `/api/sites/gp/actions`:\n\n- `create_appointment_session`: supply `title`, `clinician`, `location`, `startsAt`, `endsAt`, `slotMinutes` and `mode`.\n- `book_appointment`: supply `sessionId`, `sessionVersion`, `startsAt`, `patientId` and `title`.\n- `set_appointment_slot`: supply the session `resourceId`, `expectedVersion`, slot `startsAt`, `slotCommand` of `block` or `unblock`, and a `text` reason when blocking.\n- `arrive_appointment`, `complete` and `cancel_appointment`: supply the appointment `resourceId` and `expectedVersion`.\n\nTimestamps are Unix milliseconds. Slot booking validates the session grid, protected time and existing bookings on the server. Session availability supplies its own capacity; the aggregate capacity counter continues to apply to older bookings made without a session. Use an idempotency key when retrying mutations."
},
{
"title": "Follow one patient across services",
"url": "/docs/challenges/",
"format": "mdx",
"content": "# Follow one patient across services\n\nStart at the neighbourhood map. Riverside Practice opens GP Records for primary care. Northbank General opens Hospital EPR for secondary care. Use the same team key in both.\n\nCommunity and pharmacy have their own workspaces and scoped APIs. Diagnostics and referrals expose supporting APIs. Query those services when you need to distinguish a completed handover from a request.\n\n## Discharge to primary care\n\nUse `SIM-000001`. Inspect the hospital document in Hospital EPR and the follow-up task in GP Records. Check which records each service can see. Use `share_record` when the receiving service needs a document.\n\nOrder monitoring through `/api/sites/gp/actions` with `order_test`. Advance the world by 121 minutes through `/api/clock`, then read `/api/sites/diagnostics/view?patient=SIM-000001` and confirm the test is available. A pathology outage can hold a result in diagnostics until the organiser restores the feed.\n\nThe original document, receiving service's visible copy and final test status can be inspected separately.\n\n## Medicines and support at home\n\nDraft a prescription with `draft_prescription` from GP or hospital. Its owner is pharmacy. GP can retrieve its prescriptions at `/api/sites/gp/prescriptions` and perform `review` then `accept` through `/api/sites/gp/actions` for prescriptions originally drafted by GP. Send the latest `expectedVersion` with each GP change. Read the product catalogue at `/api/sites/pharmacy/pharmacy-workspace`. Use `link_prescription_stock` to choose a matching `productId` and `quantity` in units. If the prescription has not been approved, use `/api/sites/pharmacy/actions` to `review` then `accept` it. For an approved prescription, continue with `dispense` then `collect` through that endpoint. Send its current `expectedVersion` with each action. Acceptance changes it to `approved`; dispensing deducts the linked quantity from stock. Use a team key with pharmacy scope.\n\nFor `SIM-000006`, inspect the support plan through `/api/sites/community/view?patient=SIM-000006`. Create a `schedule_visit` action from GP or hospital and advance the clock by 91 minutes. Confirm the visit completed in the community projection. Exhausted community capacity rejects new bookings with HTTP 409.\n\nShow medicine status and visit completion separately. Collection does not establish adherence, and a simulated visit does not establish a real clinical outcome.\n\n## Resolve a rejected referral\n\nUse `SIM-000002`. Read the referral and diagnostics projections. Retrieve the additional letter through the [legacy browser](/docs/legacy/). Share the evidence needed by the receiving service, then progress the original referral through `/api/sites/referrals/actions`.\n\nThe original referral identifier stays the same as its status changes.\n\n## Test an identity integration\n\nUse the CIS2 emulator for a separate staff sign-in exercise. Its identity tokens and a team's API key have different purposes. See the [API reference](/docs/api/) for the implemented protocol and operator controls.\n\n## What comes next\n\nThe EPRs, pharmacy dispensing bench and community visit board demonstrate handovers and support after discharge. The current simulation has finite visit capacity and a prescription lifecycle, but does not model travel, home access, medication adherence or clinical outcomes.\n\nKeep the seed and intervention sequence fixed when comparing runs. Present initial records, actions, rejected requests and final states. Test the expected number of concurrent team worlds before the event.\n\n\n## Try a complete journey in ten minutes\n\n1. Create a team from the map. In GP Records, choose Amira Khan, `SIM-000001`, and send a referral to the hospital.\n2. Open Hospital EPR from the map. Select Amira and find your referral in **Handover**.\n3. Open High Street Pharmacy. Select the discharge prescription, link its matching catalogue item and quantity, dispense it, and confirm collection. A newly drafted prescription must first be reviewed and approved.\n4. Open Neighbourhood Care, select Amira and schedule a home visit. Open Simulation controls and advance 121 minutes. The visit changes to completed after its 90-minute delay.\n5. Open At home from the map and choose a resident by name or patient ID. Connect a simulated watch if they do not have one. The first activity reading is due after 10 simulation minutes. Use **+15 minutes** to observe it; subsequent readings arrive hourly. Change resident to explore another person's records.\n\nThese steps introduce the available controls. Choose your own problem from the [ten-year plan](/docs/ten-year-plan/) when deciding what to build.\n\nThe home readings are authored synthetic examples. They do not provide health assessments. A new team includes the wearable history and scope; older teams keep their original data and permissions. If your old key lacks wearable access, create a new team to try the whole journey."
},
{
"title": "Clinical records and hospital orders",
"url": "/docs/clinical-records/",
"format": "mdx",
"content": "GP Records's **Journal** shows dated contacts with their recorded narrative and authors. Search includes note text. Expand **Record details and activity** to inspect the history or open an action.\n\n## Hospital documentation\n\nOpen a patient in Hospital EPR and choose **Documentation** or **New note**. Select a free-text, history-and-physical or progress-note template. The section navigator moves between parts of the note.\n\n**Save draft** stores an editable note. **Review & sign** previews the note before **Confirm & sign** records the signature. Signed text is preserved. Use **Add addendum** to append further information with its own attribution. Drafts and signed notes remain in the documentation list after reload.\n\n## Prescriptions and blood tests\n\n**Prescription** opens the medication catalogue and order details. Enter the medicine, dose, unit, route, frequency, duration, quantity and indication. Review the details before sending the draft to pharmacy. Pharmacy review and approval are still required before dispensing.\n\n**Request test** opens the laboratory catalogue. Choose a supported panel, specimen, priority, collection round and clinical details. Review and sign the request. Results become available after 120 simulation minutes for collection now, or 240 minutes for the next round.\n\nThe **Orders** view retains the submitted details. **Results** shows measurements against sample dates. Use the panel navigator to filter the grid, or select measurements and choose **Graph selected** to inspect trends. Values and reference intervals are synthetic.\n\n## Agent requests\n\nThese workflows use `POST /api/sites/hospital/actions` with the team's API key. Patient records are read through `GET /api/sites/hospital/view?patient=SIM-000006`.\n\nThe **Secondary care** group in the API explorer also exposes raw records:\n\n- `GET /api/sites/hospital/consultations?patient=SIM-000006` returns hospital-owned consultation records, including saved note sections, full text, signatures, and addenda where recorded.\n- `GET /api/sites/hospital/genomes?patient=SIM-000006` returns the resident's raw synthetic genomic records.\n\nBoth require `hospital` scope and return `items`, `total`, `offset`, `limit`, and the simulation time `now`. Each item retains its resource ID, version, original `data`, and provenance. Use `limit` from 1 to 500 and increase `offset` to page through results. The default limit is 100. Omitting `patient` reads across the team's world. An unknown patient returns an empty list.\n\nThe consultation endpoint includes hospital-owned `hospital-note`, `clinical-note`, `consultation`, and `encounter` records. Their data shapes depend on the record kind. GP consultations and discharge-summary documents are separate records.\n\n## Synthetic genomic records\n\nEvery synthetic patient receives a hospital-only CYP2C19 SNP panel for the clopidogrel integration scenario. The panel contains unphased genotype calls for `rs4244285`, `rs4986893`, and `rs12248560`. The SNP identifiers and reference alleles follow [PharmVar's CYP2C19 catalogue](https://www.pharmvar.org/gene/cyp2c19). Patient genotypes are deterministic synthetic fixtures, unrelated to real patients or population frequencies.\n\n`data.variants` contains each SNP's identifier, reference allele, alternate allele, and diploid genotype. The panel labels itself as synthetic and identifies its source. It is a targeted SNP fixture, not a whole-genome sequence, inferred haplotype, or prescribing recommendation.\n\nExisting populations and team-specific patients receive missing panels through a transactional startup migration. Repeated startup preserves existing records. New patients receive a panel when generated. Genome records remain owned by and visible to `hospital`; generic actions cannot edit or share them with another service. Operator access remains available for simulation administration.\n\nThe OpenAPI document describes the response schemas. The genome endpoint returns `genome-record` resources. The older `genomic-test` workflow stub is not a raw SNP record.\n\n## Submit hospital actions\n\n- Notes use `type: \"hospital_note\"` and `hospitalNoteCommand`. The command is `{kind: \"save\", template, sections}` for drafts, `{kind: \"sign\"}` for signing, or `{kind: \"addendum\", text}` for additions. Each section contains `id`, `heading` and `text`. Creation also requires `patientId` and `title`; edits require `resourceId` and `expectedVersion`.\n- Prescriptions use `type: \"draft_prescription\"`, `patientId`, `title` and `medicationOrder`, containing `drug`, `dose`, `unit`, `route`, `frequency`, `duration`, `quantity` and `indication`.\n- Laboratory requests use `type: \"order_test\"`, `patientId`, `title` and `bloodTestOrder`, containing `panel`, `panelId`, `specimen`, `priority`, `collection` and `clinicalDetails`. Supported panel IDs are `fbc`, `ue`, `hba1c`, `lft`, `crp` and `lipids`. Collection is `now` or `next-round`.\n\nSupply an `Idempotency-Key` header or a `clientRequestId` UUID and reuse it for an identical retry. Stale edits and attempts to overwrite signed notes fail without changing the record.\n\n\n## Deceased synthetic patients\n\nPatient records include an optional `death` object with the date, authored cause, `synthetic: true`, and source `authored-synthetic-mortality-v1`. Its presence means the patient is deceased. GP and hospital records show the status, date, cause, and age at death. Existing consultation and medication history remains available.\n\nThe fixtures are `SIM-000009` (road traffic collision), `SIM-000011` (pneumonia), `SIM-000012` (sepsis), `SIM-000018` (cancer), and `SIM-000019` (stroke). Names, dates of birth, and ages can differ between populations. Read the current patient record for those values. These causes are authored simulation data.\n\nThe startup migration adds the fixtures to existing shared populations and patient overlays without changing demographics or replacing existing death records. New generated populations receive the same fixture IDs. Deceased patients are excluded from future generated demand and new telephone calls. Patient APIs retain the `death` object; PDS FHIR Patient responses include `deceasedDateTime`. FHIR `active` continues to describe record availability.\n\n## Issue and approve primary care prescriptions\n\nUse a team key with `gp` scope. All records are synthetic.\n\n1. POST to `/api/sites/gp/actions` with `type: \"draft_prescription\"`, `patientId`, `title`, and the `medicationOrder` fields listed above. The response contains the prescription `id`, `version`, and `status: \"draft\"`.\n2. Retrieve prescriptions with `GET /api/sites/gp/prescriptions?patient=SIM-000001&offset=0&limit=100`. The response contains `items`, `total`, `offset`, and `limit`. Each item includes its medication details, status, version, and provenance. Omit `patient` to list all GP-visible prescriptions. The maximum `limit` is 500.\n3. POST to `/api/sites/gp/actions` with `type: \"review\"`, `resourceId`, and the latest `expectedVersion`. The status becomes `reviewed`.\n4. POST to the same endpoint with `type: \"accept\"`, `resourceId`, and the version returned by review. The status becomes `approved`.\n\nGP can review and approve prescriptions originally issued through GP. Sharing a hospital prescription with GP permits retrieval but does not grant approval permission. Pharmacy retains ownership and handles stock linking, dispensing, and collection. A GP-only key can complete issuance and approval without pharmacy scope.\n\nApproval before review and stale versions return `409`. Missing versions on GP review or approval return `400`. Unauthorized service changes return `403`. Send an `Idempotency-Key` header when creating or changing a prescription to retry that exact request safely."
},
{
"title": "Arrange community visits in Community Care",
"url": "/docs/community/",
"format": "mdx",
"content": "# Arrange community visits in Community Care\n\nOpen [Neighbourhood Care](/community/) with your team's key. Community Care shows upcoming visits, care plans, and the selected person's recorded needs and goals.\n\n## Arrange a visit\n\n1. Find a person in **Patient directory**.\n2. Choose **Arrange a visit** and enter its purpose.\n3. Choose **Schedule visit**. The visit appears in your team's records with a due time 90 simulation minutes later.\n4. Open **Simulation controls** and advance time past the due time.\n5. Select **Completed** to inspect the completed visit and its attribution.\n\nYou can also choose **Complete visit** to record completion manually. **All visits** includes the earlier history. Scheduling consumes community capacity, so an exhausted allocation rejects a new visit rather than creating it silently.\n\nA GP or hospital **Home visit** request enters the same community workflow. Use the same patient ID to inspect the handover across services. The visit board does not calculate travel routes, access to the home, or clinical outcomes.\n\n## Connect an agent\n\nRead `GET /api/sites/community/view?patient=SIM-000006` with your team's bearer key. Submit `type: \"schedule_visit\"`, `patientId`, and `title` to the GP, hospital, or community action endpoint. Complete a visit through the community action endpoint using `type: \"complete\"`, `resourceId`, and `expectedVersion`.\n\nInspect the resulting resource after time advances; successful scheduling does not mean the visit has completed. The API explorer documents these actions and the clock endpoint."
},
{
"title": "The data in your world",
"url": "/docs/data/",
"format": "markdown",
"content": "# The data in your world\n\nEvery person in NHS-SIM is fictional. Patient identifiers start with `SIM-`. The repository does not contain real patient records or production NHS credentials.\n\n## Patient and record shapes\n\nA patient has an `id`, `name`, `birthDate`, service-specific `localIds`, `conditions`, `needs`, `goals`, and `synthetic: true`.\n\nA resource has an `id`, optional `patientId`, `kind`, `title`, `status`, `owner`, `visibleTo`, `priority`, timestamps, `data`, and `version`. Authored changes also record provenance and audit history. The owning service controls its transitions. Other services see it only when visibility permits.\n\n`GET /api/sites/{site}/patients` returns a paginated demographic directory. `GET /api/sites/{site}/view` returns the service's visible records and current operational state. The resource view defaults to at most 500 records. Use `limit` and `offset`, and inspect `resourceTotal`, `resourceOffset`, and `resourceLimit` when reading additional pages. The view does not expose hidden scheduled events.\n\n## Separate team worlds\n\nA new normalised team name creates a world. Reusing that name joins its existing world and returns its reusable key. Names are lowercase with whitespace removed and act as shared join codes. Portal activity and API actions using that key affect the same world. Distinct team names keep separate worlds.\n\nThe simulation clock controls delayed events. A test order schedules a result. A community visit schedules a completion. Read the resulting resource after advancing time to check whether it completed.\n\n## Record authorship\n\nRecord details distinguish the original author from later changes. Portal actions and API actions use the acting team's name. A named assignee records responsibility without impersonating that person. Seeded records identify their synthetic source or fictional author. Legacy records without an author retain an explicit unknown-author label rather than an invented identity.\n\nHospital notes preserve their signed text. Later corrections are separate attributed addenda. GP consultation edits update the version and retain their audit history.\n\nOrganisers can inspect authenticated team API calls and team-attributed patient changes. The request log records wall-clock time, method, a redacted path, response status, duration and referenced synthetic patient IDs. It excludes credentials, query strings and request bodies, and retains up to 2,000 requests per world for seven days. Earlier calls from before logging was enabled are unavailable. Reading a patient record does not count as changing it.\n\n## Provenance and coverage\n\nThe generator combines independently sampled collection-size bands with authored fictional content. Its size profile comes from 50 bounded JSON objects in a production EHR export. The profiler retains counts only, rounds counts down to multiples of five, and suppresses cells below five.\n\nProblems, medications, allergies, and miscellaneous-code collections are sampled independently. Names, identifiers, dates, codes, and text are fictional. The generator does not copy a patient's source bundle.\n\nThe sample is selection-biased and may contain repeated patients. It does not establish demographic or disease prevalence, clinical validity, or a formal privacy guarantee.\n\nThe checked-in aggregate profile is `packages/engine/src/ehr-profile.json`. Organisers can regenerate it with `scripts/profile-ehr.py`, which reads source objects in memory and emits the aggregate profile. Production credentials are not needed to run the simulator.\n\nMissing records do not establish that a condition is absent. Message delivery does not establish treatment, and prescription collection does not establish adherence.\n\nSee the [API reference](./api.mdx) for each adapter's implemented data and deviations from the corresponding NHS service."
},
{
"title": "Document Inbox and discharge letters",
"url": "/docs/documents/",
"format": "mdx",
"content": "Open Document Inbox, the GP practice's document office. It opens as a separate workspace with its own inbox, letter reader and processing panel. The GP building on the neighbourhood map offers separate GP Records and Document Inbox entrances. Hospital teams write discharge summaries in their discharge correspondence workspace and explicitly send them to the GP practice in the same team world.\n\n## Hospital handover\n\nSelect any patient in the hospital directory, then open **Discharge summaries**. Choose **New discharge summary** and enter the reason for admission, hospital course, diagnoses, medication changes, results, follow-up arrangements and requested GP actions.\n\n**Save draft** keeps the letter available only to the hospital. You can return to edit it. **Send to GP practice** requires every section to contain text. Where information is absent, record that explicitly. Sending locks the clinical text and makes the letter available in Document Inbox. The original author and sending team remain visible.\n\n## GP document processing\n\nOpen **Document Inbox** from the map or the GP Records Workflow menu and select an incoming letter. Search by patient or letter title, then narrow the queue by processing stage or priority. Read the complete letter and its authorship history. You can assign it to a named clinician or team.\n\nEnter a review note and choose **Confirm reviewed**. Then enter the filing outcome and choose **File to patient history**. Filing requires a recorded review. Filed letters remain accessible in the **filed** queue, including the original hospital text and the GP review and filing notes. Assignment records responsibility; it does not impersonate a clinician or change access permissions.\n\nThese actions do not automatically prescribe medication, create diagnoses, arrange follow-up or send messages outside the simulation. Teams must carry out any additional simulated actions separately.\n\n## Tags and SNOMED codes\n\nOpen **Tags and SNOMED codes** in the processing panel. Add document tags such as `Follow-up needed`, search a clinical term or numeric code, and select a concept. Choose **Save tags and codes** to persist your selections. Remove a tag or code with its remove button and save again. The inbox search includes saved tags, concept names and codes.\n\nCoding remains available after filing and records the acting team in the document history. These are annotations on the letter. They do not automatically add diagnoses to the patient problem list or change the original hospital text.\n\nThe searchable simulation subset contains 10 concepts from the [HL7 IPS CORE problem-list expansion](https://www.hl7.org/fhir/uv/ips/2019Sep/ValueSet-core-problem-list-disorders-uv-ips.html). It is not a complete terminology service.\n\n## Agent API\n\nUse your team API key with the existing authenticated site action endpoints. Documents are shared only within that team's world.\n\n- `GET /api/sites/hospital/documents` returns hospital drafts and sent letters with patient names.\n- `GET /api/sites/gp/documents` returns delivered letters and their processing status.\n- `POST /api/sites/hospital/actions` with `type: \"save_discharge_summary\"`, `patientId`, `title` and `dischargeSections` creates a draft. The sections object contains `reason`, `course`, `diagnoses`, `medicationChanges`, `results`, `followUp` and `gpActions`.\n- To update a draft, include its `resourceId` and `expectedVersion`.\n- Send through the hospital action endpoint using `type: \"process_document\"`, `documentCommand: \"send\"`, `resourceId` and `expectedVersion`.\n- To save annotations, use `documentCommand: \"annotate\"`, `documentTags: [\"Follow-up needed\"]` and `documentSnomedCodes: [{\"code\": \"195967001\", \"display\": \"Asthma\"}]`, with `resourceId` and `expectedVersion`. Both arrays are required; empty arrays clear annotations. The server accepts catalogue codes and stores their canonical display terms.\n- The GP action endpoint accepts document commands `assign` (with `clinician`), `review` (with `text`) and `file` (with `text`). Each requires `resourceId` and `expectedVersion`.\n\nUse a fresh idempotency key for each operation and reuse it when retrying the identical request. Stale resource versions and invalid stage changes return an error without changing the letter.\n\n## Default correspondence\n\nNew and existing team worlds receive 61 fictional letters across multiple patients and specialties. The population includes awaiting-review, reviewed, filed and hospital-only draft letters, with named synthetic authors, assignments and processing history. Existing letters and team edits are preserved when the seed population is added. Hospital drafts remain hidden from the GP inbox until sent."
},
{
"title": "Demographics and organisation APIs",
"url": "/docs/fhir/",
"format": "mdx",
"content": "# Demographics and organisation APIs\n\nUse the PDS-style API to find a person in your team's world, then follow their GP reference into the ODS-style organisation directory. These endpoints return FHIR R4 resource shapes with synthetic identifiers. They implement a documented subset of the NHS APIs.\n\nSupply your team key in `Authorization: Bearer …`. PDS requires the `gp` scope; ODS requires `referrals`. A normal team key has both. CIS2 staff tokens demonstrate identity protocols and do not replace team keys.\n\n## Find and read a patient\n\n```bash\ncurl --fail --silent \"$SIM_ORIGIN/api/nhs/pds/Patient?family=Khan&_count=10\" \\\n -H \"Authorization: Bearer $SIM_KEY\"\n\ncurl --fail --silent \"$SIM_ORIGIN/api/nhs/pds/Patient/SIM-000001\" \\\n -H \"Authorization: Bearer $SIM_KEY\"\n```\n\nSearch returns a `Bundle` with `type: searchset`, the total match count, entries and pagination links. Read returns a `Patient` with structured names, date of birth, synthetic address and contact details, local identifiers and a registered-GP reference. The names and birth dates come from the same patients you open in GP Records.\n\n| Parameter | Behaviour |\n| --- | --- |\n| `family`, `given` | Case-insensitive prefix matching |\n| `birthdate` | Exact calendar date, `YYYY-MM-DD` |\n| `identifier` | Local simulator patient identifier |\n| `_count` | Page size, 1–100 |\n| `_offset` | Nonnegative result offset |\n\nFilters combine with AND. Follow the returned `next` link rather than constructing page offsets. Unknown or repeated parameters and invalid dates return HTTP 400 with an `OperationOutcome`.\n\n## Find the registered organisation\n\n```bash\ncurl --fail --silent \"$SIM_ORIGIN/api/nhs/ods/Organization/SIM-RIVERSIDE\" \\\n -H \"Authorization: Bearer $SIM_KEY\"\n```\n\nThe directory includes Riverside Practice, Northbank General, Riverside Community Services and Riverside Pharmacy. The organisation identifiers match the fictional staff assignments in the CIS2 emulator.\n\nSearch `Organization` using `name`, `identifier` or `active`, with the same pagination parameters. Read a specific organisation using its `SIM-…` identifier.\n\n## Exercise failure paths\n\n| Request | Response |\n| --- | --- |\n| Missing team key | 401, `OperationOutcome` |\n| Key without the required service scope | 403, `OperationOutcome` |\n| Unknown patient or organisation | 404, `OperationOutcome` |\n| Invalid search date or unsupported parameter | 400, `OperationOutcome` |\n| POST, PUT, PATCH or DELETE | 405, `OperationOutcome` |\n\nSuccessful resources and errors use `application/fhir+json`. These are read-only endpoints. Changes made through the simulator's normal patient workflows appear in subsequent reads.\n\n`/api/nhs/pds/metadata` and `/api/nhs/ods/metadata` describe this simulator's supported interactions. The PDS metadata route is a local discovery aid, not an endpoint offered by the real NHS PDS API.\n\n## Scope of the simulation\n\nThe shapes are based on the official [PDS FHIR API](https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-fhir) and [ODS FHIR API](https://digital.nhs.uk/developer/api-catalogue/organisation-data-service-fhir). The emulator does not claim NHS conformance. It does not implement real NHS-number lookup, probabilistic patient matching, national organisation data, demographic updates or NHS production authentication.\n\nEvery resource is marked synthetic. Addresses and contacts are fictional fixtures; SIM identifiers are not NHS numbers or real ODS codes. No request contacts an NHS service."
},
{
"title": "Explore home readings in Home Health",
"url": "/docs/home/",
"format": "mdx",
"content": "# Explore home readings in Home Health\n\nOpen **At home** on the neighbourhood map and launch Home Health. The wearable dashboard and patient Messages are separate apps at the same location.\n\n## Select a resident and inspect readings\n\nOpen the resident selector and find any synthetic person by name or SIM identifier. Choose a person to view their devices and observations. Use the day or week controls to change the reading period, and expand **Recorded readings** to inspect dated values and quality labels.\n\nA missing value remains missing. Charts and summaries use the selected resident's recorded data. They do not assess health or recommend treatment.\n\n## Connect a simulated watch\n\nIf the resident has no active activity watch, choose **Connect simulated watch**. The first activity reading is due after 10 simulation minutes, followed by hourly readings. Advance time using **Simulation controls** in the fixed bottom bar, then inspect the new reading.\n\nNo physical device or external Apple or Withings account connects to the simulator. Reconnecting an already active activity watch does not create another device. An organiser can simulate device disconnection; missing readings stay visible as missing data.\n\n## Read and reply to practice messages\n\nReturn to the home desktop and launch **Messages**. Select the same resident to see delivered practice conversations. Reply where the practice allows replies. See [Messagey messaging](./messaging.mdx) for the delivery simulator and practice inbox.\n\n## Connect an agent\n\nOpen the **Wearables** group in the API explorer and authorize with your team key. The key must include `wearables` scope. New teams created without a `site` restriction include this scope; joining an existing team preserves its permissions.\n\nRead a resident's devices with `GET /api/sites/wearables/devices?patient=SIM-000006`. Read their recorded values with `GET /api/sites/wearables/readings?patient=SIM-000006`. Fresh simulator seeds include activity, resting heart rate, and sleep history for this resident. Existing published populations retain their stored history and can return empty lists. Connect a simulated watch to generate new activity readings.\n\nAdd `metric=steps`, `metric=heart-rate`, or `metric=sleep` to filter readings. Each response contains `items`, `total`, `offset`, `limit`, and the simulation time `now`. Requests default to 100 records; use `limit` from 1 to 500 and increase `offset` to retrieve further pages. Omitting `patient` returns matching records across your team's world.\n\nRead each item's `data` for its metric, value, unit, quality, and observation time. Timestamps use Unix milliseconds. Preserve `null` values and their quality labels when a device disconnects. A missing reading is not zero.\n\nTo generate readings for another resident, post this JSON to `/api/sites/wearables/actions`:\n\n```json\n{\n\t\"type\": \"connect_device\",\n\t\"patientId\": \"SIM-000003\",\n\t\"title\": \"Home activity watch\"\n}\n```\n\nPost `{\"paused\": true, \"advanceMinutes\": 10}` to `/api/clock`, then request `/api/sites/wearables/readings?patient=SIM-000003` to retrieve the first activity reading.\n\nUse `GET /api/sites/wearables/view?patient=SIM-000006` when you also need shared service records and events. See the [API reference](./api.mdx) for authentication and clock operations. The OpenAPI JSON includes the wearable request parameters and response schemas."
},
{
"title": "Work in Hospital EPR",
"url": "/docs/hospital/",
"format": "mdx",
"content": "# Work in Hospital EPR\n\nOpen [Northbank General](/hospital/) with your team's key. Hospital EPR opens the **Patient List Manager**. Select a row to manage an attendance, or select the patient's name to enter the chart.\n\n## Register and progress an attendance\n\n1. Choose **Register A&E attendance** and find a synthetic patient.\n2. Enter the presenting complaint, acuity, and location. A responsible clinician is optional at registration.\n3. Register the attendance, then select its row in **A&E tracking**.\n4. Enter a responsible clinician and choose **Start assessment**.\n5. Choose **Refer to medical take**, then open **Medical take**.\n6. Enter the inpatient location and choose **Admit to entered location**. The patient moves into **Inpatient census**.\n\nUse **Save assignment** to update the location, acuity, or responsible clinician. To finish an attendance, enter its discharge outcome and choose **Discharge**. Completed attendances remain in **Discharged**. Discharging an attendance does not write or send a discharge letter automatically.\n\n## Read the waiting measures\n\n**Current mean wait** uses people still waiting for assessment. **Mean assessment wait · arrivals today** uses people who arrived today and have an assessment time. **In A&E ≥4 hours** counts current A&E attendances that have reached four hours. A&E tracking includes patients awaiting the medical take.\n\nThe measures use the team's simulation clock. They describe this world's attendances and are not national hospital statistics. Change time through **Simulation controls** and refresh the lists to observe the effect.\n\n## Work in a patient chart\n\nUse **Documentation** for the document list and readable note preview. Notes show sections vertically, with their original author and later changes. Create a draft, review and sign it, or add an attributed addendum to a signed note. Follow [Clinical records and hospital orders](./clinical-records.mdx).\n\n**Prescription** and **Request test** open separate catalogues and order details. **Orders** retains the submitted fields. **Results** shows a laboratory flowsheet with sample dates in columns and controls for trends. Pharmacy must review and approve a new prescription before dispensing.\n\nUse [Discharge summaries and Document Inbox](./documents.mdx) to write and send a handover to the GP. Use **Handover** for related tasks and onward-care records. Creating a task, arranging a visit, and sending a letter are separate actions.\n\n## Agent requests\n\n`GET /api/sites/hospital/attendances` returns attendance resources, patient names, and simulation time. Submit mutations to `/api/sites/hospital/actions` using the team's bearer key.\n\nCreate with `type: \"register_attendance\"`, `patientId`, `title`, `acuity`, and `location`. `clinician` is optional. Update with `type: \"update_attendance\"`, `resourceId`, `expectedVersion`, and `hospitalCommand`, one of `assign`, `assess`, `refer`, `admit`, or `discharge`. Include the fields needed by that transition, such as a clinician for assessment or `disposition` for discharge.\n\nUse the API explorer for request schemas and supported values. Reuse the same idempotency key for an identical retry and reload after a version conflict."
},
{
"title": "Test staff sign-in with Staff Identity",
"url": "/docs/identity/",
"format": "mdx",
"content": "# Test staff sign-in with Staff Identity\n\nStaff Identity is the simulator's CIS2-style staff identity service. Its staff identities, organisations, and roles are fictional. A staff token does not replace the team API key or grant access to a team world.\n\n## Try a staff sign-in\n\n1. Open Staff Identity and choose the simulated smartcard or security-key method.\n2. Start sign-in and choose a fictional staff identity.\n3. Select an organisation and role, then continue.\n4. Inspect the identity on the result page. Expand **Technical session details** for the returned identity and expiry information.\n\nNo hardware, smartcard PIN, or NHS password is required. Cancelling sign-in returns a denial instead of creating a staff session.\n\n## Connect your application\n\nDiscover the issuer through the OpenID discovery document. The implemented flow uses authorization code with PKCE S256 and RS256-signed identity tokens. The bundled `nhs-sim-client` uses this origin's `/cis2/callback` route.\n\nAn organiser can register your client ID and exact redirect URLs. Start a fresh authorization request with your own state, nonce, and PKCE challenge. Exchange the one-time code using its verifier, then call the discovered userinfo endpoint with the staff access token. Use the discovery document's JWKS URL to verify identity-token signatures.\n\nThe [API reference](./api.mdx), API explorer, and OpenAPI JSON describe the simulator's endpoints. The browser sign-in demonstrates the interactive consent and role-selection flow.\n\n## Exercise failure cases\n\nIn **Developer and operator tools**, enter the organiser token and choose **Unlock operator controls**. Select normal sign-in, consent denied, service unavailable, or session expired. Set a token lifetime between 30 and 3,600 seconds, or edit the registered applications.\n\n**Apply settings** revokes existing interactions, codes, and access tokens. **Revoke all sessions** invalidates them without changing the scenario. These settings affect the running application, not a single team world. Restore normal sign-in after the exercise. Restarting the application resets identity settings and sessions."
},
{
"title": "Explore the neighbourhood",
"url": "/docs/",
"format": "mdx",
"content": "# Explore the neighbourhood\n\nA referral gets rejected. A result arrives late. A discharge letter sits in another system. Enter the map, open a workplace, and follow one fictional patient across their care.\n\n\n
Start a team worldCopy your key, choose patients, and control simulation time.\n
Work in GP RecordsConsultations, problems, allergies, and the appointment book.\n
Work in Hospital EPRA&E tracking, the medical take, inpatient charts, and orders.\n
Run PharmacyReceive referrals, dispense prescriptions, compare suppliers, and manage stock.\n
Explore the ten-year planConnect the plan's questions to people and places in the simulator.\n
Try an API requestInteractive Swagger UI, request schemas, and responses.\n