Mira EMR patient and population APIs

Developer: Mira Technologies, Inc. Product: Mira EMR, version 1.0.

This page covers three API capabilities:

• (g)(7) application access, patient selection
• (g)(9) application access, all data request (C-CDA)
• (g)(10) standardized API for patient and population services (FHIR R4, US Core 6.1.0, SMART App Launch 2.0.0, Bulk Data 1.0.1)

Hosts: Mira EMR is https://miraemr.com. The FHIR server for the development stage is https://fhir-dev.mirahealth.care (its CapabilityStatement and SMART configuration); the production FHIR server's address is published before production opens. Each practice's own FHIR base URL is published in the service base URL Bundle (§2).

1. Terms of use

1. Who may use the APIs. Patients and their authorized representatives may use any app they choose to reach their own records. Healthcare organizations that use Mira EMR (the "API Information Sources") may use the APIs and may authorize other apps to reach their population data.

2. No fees.

   • Mira charges no fee to patients or to app developers to register an app or to call these APIs.
   • Any fee Mira charges a customer for deploying the APIs is stated in our mandatory disclosures, per §170.404(a)(3).

3. Use. Apps must:

   • use the APIs as documented here
   • keep their credentials confidential
   • request only the scopes they need
   • not attempt to reach data their user is not authorized to see

   Mira does not require app developers to sign a business associate agreement to serve a patient's chosen app. Mira does not vet patient-chosen apps for security beyond the registration steps in §3.

4. Rights. Mira grants the rights needed to develop, test, market and distribute apps that use these APIs. Those rights do not depend on fees, exclusivity, non-compete terms, or reciprocal data sharing (§170.404(a)(4)).

5. Changes. Mira gives registered developers and customers advance notice of changes to the APIs, and reasonable time to update, except where a security issue requires faster action.

6. Support. support@mirahealth.care. We answer within 2 business days.

2. Service base URLs (§170.404(b)(2))

Every customer organization whose FHIR API is live is published, free of charge and with no sign-in, as a FHIR R4 Bundle (type: collection) of Organization and Endpoint resources:

• Bundle: GET https://miraemr.com/api/v1/api-access/service-base-urls. Response 200 application/fhir+json.
• Organization (US Core Organization): name, address, identifier (the NPI when the organization has one, and always the Mira organization id https://mirahealth.care/fhir/sid/organization-id), telecom, and endpoint referencing its Endpoint.
• Endpoint: status active, connectionType hl7-fhir-rest, payloadType any, payloadMimeType application/fhir+json, managingOrganization, and address, the organization's FHIR base URL (on the development stage, https://fhir-dev.mirahealth.care/fhir/R4).
• References inside the Bundle are urn:uuid: full URLs.

The Bundle is generated from the live configuration. It is served with Cache-Control: public, max-age=300, so a change (a customer going live or changing its endpoint) shows within 5 minutes.

3. Registering an app (§170.404(b)(1))

1. Register online at https://miraemr.com/developers/register (no sign-in). The form asks for:

   • the practice the app will connect to (the practices listed in §2)
   • app name, your organization, a contact name and email, your website
   • who uses the app: patients, clinicians or practice staff, or a back-end system
   • redirect URIs (https; http://localhost for development), and whether to register a SMART on FHIR client (required for a patient app)
   • for a SMART client, optionally your key set URL (jwksUri, https) for private_key_jwt
   • what the app does with the data
   • acceptance of these terms

   Registration is free. You may also email support@mirahealth.care with the same details.

2. Authenticity verification. The practice's administrator, in Mira, confirms your identity and contact (for example a reply from an address on your own domain, and a working website). The decision is made within 10 business days of registration; Mira shows the administrator the due date. The same steps apply to every developer.

3. Credentials. When the registration is activated, Mira issues the credentials within 5 business days of verification (normally at once):

   • Patient apps get a SMART client only. A patient app reaches a record only when that patient signs in and authorizes it (§4, §5.1); it never receives a key to the practice's records.
   • Provider and back-end apps get a Mira API key mira_<client id>.<secret> for §5. It reads every patient of that practice, so the administrator activates it as an explicit authorization of practice-wide access. It is shown once to the administrator, who sends it to your contact email; Mira keeps only a SHA-256 fingerprint. A lost key is revoked and a new registration made.
   • When you asked for one, a SMART client (client_id and client_secret) on the practice's FHIR server (§4) with your redirect URIs (and key set URL). A back-end SMART client reads every patient of the practice except restricted charts, read only, and the status and files of its own bulk exports (§4); Mira proves it can obtain a token before reporting it ready. If the FHIR server cannot take the registration at that moment, it stays on the administrator's work list with the 5-business-day deadline until it is completed.

   A declined registration is told why. An administrator can revoke a key at any time; the next call with it is refused.

4. A healthcare organization that uses Mira EMR may also enable an app for its own users through the same screen.

4. (g)(10) Standardized API for patient and population services (FHIR R4)

This section is the (g)(10) API documentation required by §170.315(g)(10)(viii): the API syntax and function names (§4.4 to §4.6), the required and optional parameters with their data types and the return variables with their types and structures (§4.3 to §4.6), exceptions and their handling (§4.7), the software components and configuration an app needs (§4.2), and what an app needs to register with the authorization server (§3 and §4.3). The machine-readable source of the same facts is the live CapabilityStatement (§4.1).

Below, [base] stands for a practice's FHIR base URL. On the development stage every practice's base is https://fhir-dev.mirahealth.care/fhir/R4; the production FHIR server's address is published before production opens. Each practice's base is also in the service base URL Bundle (§2). The base URL answers only API requests (with a token); open its CapabilityStatement to read it in a browser.

4.1 Endpoints, capability statement and conformance

The CapabilityStatement needs no token. It names the server software (Medplum 5.2.3), FHIR version 4.0.1, the JSON format, every resource type with its supported profiles, interactions and search parameters, the Group $export operation, and the OAuth endpoints (in rest.security). It instantiates the US Core server and Bulk Data CapabilityStatements.

4.2 Software components and configuration

What Mira runs.

• FHIR server and authorization server: Medplum 5.2.3, one project per practice. It serves the FHIR API, the SMART authorization and token endpoints, token introspection and bulk export.
• Sign-in page: the Medplum sign-in app at fhir-login-dev.mirahealth.care, where a user signs in, chooses which scopes to grant, and consents.
• Mira EMR: the system of record. It writes each practice's chart to the FHIR server, publishes the service base URLs (§2), handles registration (§3), and serves the bytes of clinical documents (§4.4).

What an app needs.

• An HTTPS client (TLS 1.2 or later) that can send an Authorization: Bearer header and parse JSON. The FHIR server speaks JSON only (application/fhir+json); XML is not offered.
• An OAuth 2.0 client that follows SMART App Launch 2.0.0 (any SMART client library will do): the authorization code grant with PKCE S256 for patient and clinician apps, or client_credentials with private_key_jwt (or the client secret) for back-end apps.
• A client registered through §3, with these settings:
  • Register redirect URIs exactly; no wildcards.
  • Every SMART client registered through Mira receives a client_id and a client_secret. The authorization code grant always requires PKCE (S256). An app that cannot keep a secret (a browser or native app) sends only its client_id with PKCE, as a public client; the secret is not checked in that grant.
  • Any SMART client may register a key set URL (jwksUri) for private_key_jwt, signed with RS256, RS384 or ES384.
  • Request launch/patient for a standalone patient launch, or launch for an EHR launch.
• For bulk export: the ability to poll a status URL and download NDJSON files (§4.6).

4.3 Authorization (SMART App Launch 2.0.0)

Endpoints. These are API endpoints, not pages: each answers only the request shown. They are also listed in the SMART configuration.

Authorization request (GET [authorize]?…, or the same fields form-encoded in a POST). Every parameter is a string.

Success redirects to {redirect_uri}?code={code}&state={state}. An error after the client and redirect URI are known redirects to {redirect_uri}?error={code}&error_description={text}&state={state} (for example invalid_request or unsupported_response_type).

Token request (POST [token], Content-Type: application/x-www-form-urlencoded).

Token response (200 application/json):

The server also returns project, profile and fhirContext (Medplum fields); apps can ignore them. A refused token request answers 400 with {"error": string, "error_description": string}, for example {"error":"invalid_request","error_description":"Invalid client"}; invalid_grant means the code or refresh token was already used, expired or revoked.

Token introspection response (200 application/json): active (boolean). An active token adds scope (string), client_id (string), sub (string), iss (string), iat and exp (integer, seconds since 1970) and patient (string, when there is a patient context). An unknown, expired or revoked token answers {"active": false}.

Scopes. SMART v1 and v2 syntax are both accepted (the SMART configuration lists permission-v1 and permission-v2).

• patient/ scopes need a patient context (a patient launch or a patient account). system/ scopes are for back-end clients (client_credentials).
• A token reads only what both its scopes and its account's access rules allow. The access rules are read only, so a write scope grants nothing.
• A granular scope never authorizes the whole resource type: a token with only patient/Observation.rs?category=…|laboratory gets laboratory Observations and nothing else.
• scopes_supported in the SMART configuration lists patient/*.rs, user/*.cruds, openid, fhirUser, launch, launch/patient, offline_access and online_access. That list is fixed by the FHIR server software (Medplum 5.2.3) and is not complete: every scope form above is accepted.

Sign-in accounts. A patient or clinician signs in on the FHIR server's own sign-in page with an account Mira creates on the practice's request; the FHIR server emails an invitation to set a password. Mira EMR has no self-service screen for this yet. A patient account reads only that patient's own record; a clinician account reads every patient of the practice except restricted charts, read only.

Launches.

• Standalone patient launch: the patient signs in with that account.
• EHR launch: Mira creates the launch context (the patient, and the visit when given) on the FHIR server and opens the app's launch URL with iss (the FHIR base URL) and launch; the app then authorizes with launch and the clinician signs in. Mira EMR's chart has no launch button yet: an EHR launch is started with Mira's launchFhirApp command, and never for a restricted chart.

Refresh tokens.

• Issued to: apps granted offline_access (or online_access). This includes native apps that can keep a secret or use PKCE.
• Life: 100 days, for the first refresh token and for every renewed one. Mira sets this lifetime on every app it registers on the FHIR server (the FHIR server's own default is two weeks).
• Renewal: using a refresh token at the token endpoint (grant_type=refresh_token) returns a new access token and a new refresh token without the user signing in again, per §170.315(g)(10)(v)(A).

Registration. Apps register through §3. What the authorization server needs: the redirect URIs (https; http://localhost for development), whether the app is a patient app, a clinician app or a back-end system, and optionally a key set URL (jwksUri, https) for private_key_jwt. Mira issues the client_id and client_secret (§3, step 3).

4.4 Requests and responses

Functions. The API's functions are the FHIR RESTful interactions and one operation:

Send on every request: Authorization: Bearer {access_token} and Accept: application/fhir+json. Responses are application/fhir+json. The API is read only for apps: the create, update, patch and delete interactions the CapabilityStatement lists are refused.

Parameter data types (FHIR search parameter types):

Several values of one parameter separated by commas match any of them (status=active,completed). No US Core search below uses a composite parameter.

Search results. A search returns a Bundle:

No match returns 200 with no entries. _revinclude=Provenance:target adds each result's US Core Provenance (author and author organization). _count sets the page size.

Document content. A DocumentReference (and a report-type DiagnosticReport) holds its document in content[].attachment.url (presentedForm[].url), an address on Mira EMR of the form https://{Mira EMR host}/fhir-binary/{documentId}. Fetch it with GET and the same Authorization: Bearer token; it returns the document's bytes with its own content type. It serves only documents the token may read.

What a patient token reads. A patient-context token reads that patient's own record. On the current server software (Medplum 5.2.3), patient/ scopes reach only resources in the patient's compartment, so a patient app cannot read the Practitioner or Organization resources a record refers to; a clinician (user/) or back-end (system/) token can.

4.5 Supported resources and searches

The US Core 6.1.0 resources Mira sends for USCDI v3, and the searches each supports. Every search below is a SHALL or SHOULD search of the US Core server CapabilityStatement, and every parameter in it is in the live CapabilityStatement's list for that resource (checked 2026-10-22). The read row links the profile every returned resource conforms to; the resources in a search's Bundle conform to the same profile.

• Observation categories: laboratory, vital-signs, social-history, survey, imaging (a report's impression), procedure (a clinical test result, US Core Observation Clinical Result: one recorded by its LOINC code, such as an EKG's QT interval 44975-1 in seconds, or a signed EKG report), and the US Core categories sdoh, functional-status, disability-status and cognitive-status.
• MedicationDispense: a prescription's pharmacy fill status (USCDI v3 Fill Status). status is completed (filled), in-progress (partly filled) or declined (not filled); authorizingPrescription is the MedicationRequest; the drug and dosage instruction are the prescription's; the pharmacy is the performer (an Organization). The fill comes from DoseSpot when the pharmacy reports it (RxFill), or staff record it on the prescription.
• DiagnosticReport: a laboratory pathology report (LOINC 11526-1, 11529-5, 60567-5, 60568-3) carries both the LAB and the LOINC Pathology category, so it is returned for either category and its result points at its laboratory Observations.
• DocumentReference: the clinical notes (category clinical-note).
• Not sent: Medication (a medication is coded inside its MedicationRequest and MedicationDispense), PractitionerRole and QuestionnaireResponse.

AllergyIntolerance

Optional on every search: _count (number), _revinclude=Provenance:target (string).

CarePlan

Optional on every search: _count (number), _revinclude=Provenance:target (string).

CareTeam

Optional on every search: _count (number), _revinclude=Provenance:target (string).

Condition

Optional on every search: _count (number), _revinclude=Provenance:target (string).

Coverage

Optional on every search: _count (number), _revinclude=Provenance:target (string).

Device

Optional on every search: _count (number), _revinclude=Provenance:target (string).

DiagnosticReport

Optional on every search: _count (number), _revinclude=Provenance:target (string).

DocumentReference

Optional on every search: _count (number), _revinclude=Provenance:target (string).

Encounter

Optional on every search: _count (number), _revinclude=Provenance:target (string).

Goal

Optional on every search: _count (number), _revinclude=Provenance:target (string).

Immunization

Optional on every search: _count (number), _revinclude=Provenance:target (string).

Location

Optional on every search: _count (number).

MedicationDispense

Optional on every search: _count (number), _revinclude=Provenance:target (string).

MedicationRequest

Optional on every search: _count (number), _revinclude=Provenance:target (string).

Observation

Profiles: Laboratory Result, Clinical Result, Screening and Assessment, Smoking Status, Occupation, Pregnancy Status, Pregnancy Intent, Sexual Orientation, Vital Signs, Blood Pressure, BMI, Body Height, Body Weight, Body Temperature, Head Circumference, Heart Rate, Respiratory Rate, Pulse Oximetry, Pediatric BMI for Age, Pediatric Weight for Height, Pediatric Head Occipital-frontal Circumference Percentile.

Optional on every search: _count (number), _revinclude=Provenance:target (string).

Organization

Optional on every search: _count (number).

Patient

Optional on every search: _count (number), _revinclude=Provenance:target (string).

Practitioner

Optional on every search: _count (number).

Procedure

Optional on every search: _count (number), _revinclude=Provenance:target (string).

Provenance

RelatedPerson

Optional on every search: _count (number), _revinclude=Provenance:target (string).

ServiceRequest

Optional on every search: _count (number), _revinclude=Provenance:target (string).

Specimen

Optional on every search: _count (number).

Group (bulk export)

One Group per practice: every patient of the practice except restricted charts. It has no US Core profile.

4.6 Bulk Data Access 1.0.1 ($export)

Authorization. A back-end client (client_credentials with private_key_jwt or its client secret, §4.3) with a system/ read scope, for example system/*.rs or system/*.read. The practice's Group excludes restricted charts. A patient token may not use Group export.

Kick-off request. Headers Accept: application/fhir+json, Prefer: respond-async and Authorization: Bearer {access_token}.

Kick-off response. 202 Accepted with the header Content-Location: https://fhir-dev.mirahealth.care/fhir/R4/bulkdata/export/{exportId}, the status URL. A refused request answers 4xx with an OperationOutcome (§4.7).

Status request. GET {Content-Location} with Authorization: Bearer {access_token}. A client reads only its own exports.

• 202 Accepted, no body: still running. Poll again after a few seconds.
• 200 OK, application/json: complete. The body is the manifest below.
• 404: the export was cancelled or does not exist for this client.

Cancelling a running export (DELETE {Content-Location}) is not available to clients registered through Mira.

Completion manifest.

The server also returns a deleted array (a Bulk Data 2.0 field); Bulk Data 1.0.1 clients can ignore it.

{
	"transactionTime": "2026-10-22T15:00:00.000Z",
	"request": "https://fhir-dev.mirahealth.care/fhir/R4/Group/{id}/$export",
	"requiresAccessToken": false,
	"output": [
		{"type": "Patient", "url": "https://fhir-dev.mirahealth.care/storage/…"},
		{"type": "Condition", "url": "https://fhir-dev.mirahealth.care/storage/…"}
	],
	"error": []
}

File request. GET {output[].url} with no Authorization header returns 200 and the file in NDJSON: one FHIR resource, as JSON, per line, all of the file's type.

4.7 Errors and exception handling

FHIR API. Every error is an HTTP status code with a FHIR OperationOutcome body (application/fhir+json):

{
	"resourceType": "OperationOutcome",
	"id": "unauthorized",
	"issue": [{"severity": "error", "code": "login", "details": {"text": "Unauthorized"}}]
}

Bulk export: 202 while running, then 200 with the manifest (§4.6).

Authorization server. The token and introspection endpoints answer errors as {"error": string, "error_description": string} (§4.3). The authorize endpoint returns its errors to the app's redirect_uri as error, error_description and state query parameters; when the client_id or redirect_uri itself is invalid, it shows an error page instead of redirecting.

4.8 Limits

Sign-in allows 5 attempts per minute per address (429 Too Many Requests). The token endpoint takes at most 300 requests per 5 minutes per address; past that the firewall answers 403.

5. (g)(7) patient selection and (g)(9) all data request

Mira EMR serves these two APIs itself, under https://miraemr.com/api/v1/api-access. Version: v1. A breaking change gets a new path version and the notice in §1.5.

5.1 Authentication and app configuration

Send one credential as Authorization: Bearer <credential> on every request. A request with an access_token query parameter is refused (400). There are no cookies; browser apps may call cross-origin (CORS *, preflight answered).

Software you need: any HTTPS client (TLS 1.2 or later) that can set a header, parse JSON (§5.2) and save XML (§5.3). For SMART tokens, a SMART App Launch 2.0 client library (§4). Responses are never cached (Cache-Control: no-store).

Results never cross practices. With a SMART token, Mira asks the FHIR server, as that token, which of the matching patients it may see (§5.2) and whether it may read the patient and every resource type of the CCD (§5.3); anything refused is left out or refused. A restricted chart (a confidential chart the practice limits to named staff) is reachable only by the patient's own token.

5.2 (g)(7) Patient selection: GET /api/v1/api-access/patients

Returns the Mira patient id (the token for §5.3) of every patient of the practice who matches and whom the credential may reach.

Query parameters. Provide either identifier, or name with birthdate.

Only charts the CCD (§5.3) can be produced for are listed: a merged chart is not, and neither is a chart with no date of birth or of a minor (the patient record export Mira serves today is for adults).

Response 200 application/json:

{
	"patients": [
		{
			"id": "6f0c9a8e-2c3b-4f7e-9a51-0d2b8c7e1a44",
			"identifier": [
				{"system": "https://mirahealth.care/fhir/sid/mrn/<organizationId>", "value": "12345"},
				{"system": "https://mirahealth.care/fhir/sid/patient-id", "value": "6f0c9a8e-2c3b-4f7e-9a51-0d2b8c7e1a44"}
			],
			"name": {"family": "Rivera", "given": ["Ana"]},
			"birthDate": "1971-04-05",
			"sex": "female"
		}
	],
	"total": 1,
	"next": null
}

No match returns 200 with "patients": [], not 404.

5.3 (g)(9) All data request: GET /api/v1/api-access/patients/{id}/ccd

Returns a C-CDA R2.1 Continuity of Care Document (Companion Guide R4.1, USCDI v3) for one patient: every USCDI data class Mira holds for the patient, as section narrative and discrete entries, in one document.

Date semantics.

• With neither start nor end, the document holds all of the patient's data.
• A specific date: send the same day as start and end.
• A date range: the document holds the data relevant to that period: encounters, procedures, results, vital signs, immunizations, notes and assessments dated in it, and problems, medications, allergies, goals and care plans active at any time in it. Either end may be left open.
• Patient demographics, the care team, the author and custodian are always included.
• Dates are compared at day precision on the date as recorded; a timestamped entry counts on its UTC calendar date.
• documentationOf/serviceEvent/effectiveTime gives the span of the data in the document.
• start after end is a 400.

What the practice withholds. The document is the same record the practice releases to the patient in its patient portal: an item the practice has held from release (for example under a HIPAA or state-law restriction), a result not yet released, and a visit note not yet released are left out.

Response 200 application/xml. A single ClinicalDocument:

• templateId 2.16.840.1.113883.10.20.22.1.2, extension 2015-08-01
• sections per the C-CDA R2.1 CCD and Companion Guide R4.1, including Assessment and Plan of Treatment, Goals, Health Concerns, and implantable device UDIs in Medical Equipment

Headers: Content-Type: application/xml; charset=utf-8, Content-Disposition: attachment; filename="ccd-<id>.xml", Cache-Control: no-store.

5.4 Errors

Every error is JSON: {"error": {"code": "<code>", "message": "<plain words>"}}. Every response of §5.2 and §5.3 carries an X-Request-Id header.

5.5 Specifications

• C-CDA R2.1 (HL7 CDA R2 IG: C-CDA Templates for Clinical Notes R2.1; HL7 product brief, where R2.1 is listed among the releases) with the Companion Guide R4.1
• USCDI v3
• RFC 6749 (OAuth 2.0), RFC 6750 (bearer tokens)
• RFC 7523 (private_key_jwt)
• SMART App Launch 2.0.0
• ONC test procedures: (g)(7) application access, patient selection, (g)(9) application access, all data request

5.6 Example

GET /api/v1/api-access/patients?identifier=https%3A%2F%2Fmirahealth.care%2Ffhir%2Fsid%2Fmrn%2F<org>%7C12345 HTTP/1.1
Host: miraemr.com
Authorization: Bearer mira_0b8a…_c1.Yc3…

GET /api/v1/api-access/patients/6f0c9a8e-2c3b-4f7e-9a51-0d2b8c7e1a44/ccd?start=2026-01-01&end=2026-06-30 HTTP/1.1
Host: miraemr.com
Authorization: Bearer mira_0b8a…_c1.Yc3…
Accept: application/xml

curl -H "Authorization: Bearer $MIRA_API_KEY" \
  "https://miraemr.com/api/v1/api-access/patients?name=Rivera,Ana&birthdate=1971-04-05"
curl -H "Authorization: Bearer $MIRA_API_KEY" -o ccd.xml \
  "https://miraemr.com/api/v1/api-access/patients/<id>/ccd?start=2026-01-10&end=2026-01-10"

6. Security

• TLS 1.2 or later only.
• HSTS: Mira EMR and the FHIR server send Strict-Transport-Security; the FHIR sign-in page host does not yet.
• Every request is audited.
• Tokens are bearer tokens: keep them secret, and never put them in URLs.
• Report a vulnerability to support@mirahealth.care.