API reference
Open 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.
These 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.
Find the contract
| Reference | Contents |
|---|---|
| Interactive explorer | Operations grouped by service, editable requests, responses, and authentication controls |
| OpenAPI JSON | Machine-readable paths, parameters, schemas, examples, and security requirements |
| Runtime catalogue | Published workplaces, NHS adapters, scenarios, and documentation links |
| Handbook JSON | Every published guide with its title, URL, source format, and content for agents |
| First API workflow | Create a world, find a patient, and submit an action |
The explorer uses this website's origin. Requests on the local simulator affect local worlds. Requests on sim.animahacks.com affect hosted worlds.
Authenticate a request
Copy 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.
Outside 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.
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.
Operator 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.
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 provides team selection, request history, affected patients and an explicit return path after exploring as a team.
Read records and submit actions
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.
The 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.
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.
For 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.
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.
Raw secondary care records
The 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.
Both 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.
See clinical and genomic records for included consultation kinds, synthetic CYP2C19 data, and the hospital-only access boundary.
Wearable data
The Wearables Explorer group publishes the Home Health records in the authenticated team's world. Both operations require wearables scope.
| Operation | Records | Filters |
|---|---|---|
GET /api/sites/wearables/devices | Connected synthetic devices, including battery and sync data where recorded | patient |
GET /api/sites/wearables/readings | Wearable observations with recorded values, units, quality, and timestamps | patient, metric |
Both 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.
Each 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.
The Home Health guide includes the watch connection and first-reading workflow. These operations and their schemas also appear in the downloadable OpenAPI document.
Follow a workflow
- GP Records covers GP consultations and patient records.
- Appointment book covers session slots, bookings, and attendance.
- Clinical records and hospital orders covers signed notes, addenda, prescriptions, and laboratory requests.
- Document processing covers hospital discharge letters and GP filing.
- Practice and patient messaging covers role-specific messaging APIs, patient-initiated conversations, delivery, and scripted automatic replies.
- Home Health and wearable data covers connected devices, recorded readings, and simulated watch updates.
- Pharmacy covers referrals, dispensing, supplier quotes, purchasing, and stock costs.
- FHIR-shaped APIs covers supported demographics and organisation search.
- Legacy browser integration covers the HTML-only service and session cookies.
- Organiser controls covers administration and the configured model agent.
Handle errors
Read 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.
| Status | Typical cause | Next step |
|---|---|---|
400 | Invalid input or malformed JSON | Correct the request using the operation schema |
401 | Missing or invalid credentials | Check the authentication scheme and key |
403 | Wrong scope, ownership, or operator permission | Use an authorized service and credential |
404 | Unknown endpoint or missing resource | Check the path and the current world |
409 | Stale version, changed retry payload, or invalid state transition | Refresh the record and resolve the conflict |
413 | Request body exceeds the server limit | Reduce the payload |
429 | The deployment has reached its 5,000-team cap | Contact the organiser |
501 | A deliberately unsupported API capability | Use the documented alternative |
503 | Simulated identity unavailability | Check the configured CIS2 scenario |
Keep integrations aligned
The 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.
For production NHS integration requirements, use the NHS API catalogue. This simulator does not need live NHS credentials.