{"openapi":"3.1.0","info":{"title":"Ayulex HMIS FHIR R4 API","version":"2026-11-06","description":"Read-only HL7 FHIR R4 (4.0.1) interface to one hospital's records. Each request needs a hospital API key with the fhir:read scope, sent as a bearer token. Each key may make 600 requests a minute. Every record released is written to the hospital's audit trail; restricted patients are never released.","contact":{"email":"support@ayulex.com","url":"https://hmis.ayulex.com/developers"}},"externalDocs":{"description":"Developer guide","url":"https://hmis.ayulex.com/developers"},"servers":[{"url":"https://hmis.ayulex.com/api/fhir"}],"security":[{"apiKey":[]}],"paths":{"/metadata":{"get":{"summary":"CapabilityStatement","security":[],"responses":{"200":{"description":"What this server supports","content":{"application/fhir+json":{"schema":{"type":"object","required":["resourceType"],"properties":{"resourceType":{"const":"CapabilityStatement"}},"additionalProperties":true,"externalDocs":{"description":"HL7 FHIR R4 CapabilityStatement","url":"https://hl7.org/fhir/R4/capabilitystatement.html"}}}}}}}},"/Patient":{"get":{"summary":"Search patients","description":"Search by identifier (system|value) or telecom. One of the two is required. Returns up to 20 matches.","parameters":[{"name":"identifier","in":"query","description":"urn:ayulex:uhid|{UHID}, or https://healthid.abdm.gov.in|{ABHA number or address}","schema":{"type":"string"}},{"name":"telecom","in":"query","description":"Phone number; the last 10 digits are matched","schema":{"type":"string"}}],"responses":{"200":{"description":"searchset Bundle of Patient resources","content":{"application/fhir+json":{"schema":{"type":"object","required":["resourceType"],"properties":{"resourceType":{"const":"Bundle"}},"additionalProperties":true,"externalDocs":{"description":"HL7 FHIR R4 Bundle","url":"https://hl7.org/fhir/R4/bundle.html"}}}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/Throttled"}}}},"/Patient/{id}":{"get":{"summary":"Read a patient","parameters":[{"name":"id","in":"path","required":true,"description":"Patient id","schema":{"type":"string"}}],"responses":{"200":{"description":"Patient","content":{"application/fhir+json":{"schema":{"type":"object","required":["resourceType"],"properties":{"resourceType":{"const":"Patient"}},"additionalProperties":true,"externalDocs":{"description":"HL7 FHIR R4 Patient","url":"https://hl7.org/fhir/R4/patient.html"}}}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/Throttled"}}}},"/Encounter/{id}":{"get":{"summary":"Read an encounter","description":"Diagnoses carry ICD-10, ICD-10-CM, ICD-11 or SNOMED CT codes.","parameters":[{"name":"id","in":"path","required":true,"description":"Encounter id","schema":{"type":"string"}}],"responses":{"200":{"description":"Encounter","content":{"application/fhir+json":{"schema":{"type":"object","required":["resourceType"],"properties":{"resourceType":{"const":"Encounter"}},"additionalProperties":true,"externalDocs":{"description":"HL7 FHIR R4 Encounter","url":"https://hl7.org/fhir/R4/encounter.html"}}}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/Throttled"}}}},"/MedicationRequest/{id}":{"get":{"summary":"Read a prescription or one prescribed medicine","parameters":[{"name":"id","in":"path","required":true,"description":"A prescription id returns all its lines as a collection Bundle; {prescriptionId}-{n} returns one MedicationRequest.","schema":{"type":"string"}}],"responses":{"200":{"description":"MedicationRequest, or a collection Bundle of them","content":{"application/fhir+json":{"schema":{"oneOf":[{"type":"object","required":["resourceType"],"properties":{"resourceType":{"const":"MedicationRequest"}},"additionalProperties":true,"externalDocs":{"description":"HL7 FHIR R4 MedicationRequest","url":"https://hl7.org/fhir/R4/medicationrequest.html"}},{"type":"object","required":["resourceType"],"properties":{"resourceType":{"const":"Bundle"}},"additionalProperties":true,"externalDocs":{"description":"HL7 FHIR R4 Bundle","url":"https://hl7.org/fhir/R4/bundle.html"}}]}}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/Throttled"}}}},"/Observation/{id}":{"get":{"summary":"Read vital signs","parameters":[{"name":"id","in":"path","required":true,"description":"A vitals id returns the set as a collection Bundle; {vitalsId}-{bp|hr|rr|spo2|temp|weight|height|bmi} returns one Observation.","schema":{"type":"string"}}],"responses":{"200":{"description":"Observation (LOINC-coded vital sign), or a collection Bundle of them","content":{"application/fhir+json":{"schema":{"oneOf":[{"type":"object","required":["resourceType"],"properties":{"resourceType":{"const":"Observation"}},"additionalProperties":true,"externalDocs":{"description":"HL7 FHIR R4 Observation","url":"https://hl7.org/fhir/R4/observation.html"}},{"type":"object","required":["resourceType"],"properties":{"resourceType":{"const":"Bundle"}},"additionalProperties":true,"externalDocs":{"description":"HL7 FHIR R4 Bundle","url":"https://hl7.org/fhir/R4/bundle.html"}}]}}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/Throttled"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Hospital API key (begins ayx_) with the fhir:read scope, issued in Settings → Integrations."}},"schemas":{"OperationOutcome":{"type":"object","required":["resourceType","issue"],"properties":{"resourceType":{"const":"OperationOutcome"},"issue":{"type":"array","items":{"type":"object","properties":{"severity":{"const":"error"},"code":{"enum":["invalid","security","not-found","throttled","exception"]},"diagnostics":{"type":"string"}}}}},"externalDocs":{"description":"HL7 FHIR R4 OperationOutcome","url":"https://hl7.org/fhir/R4/operationoutcome.html"}}},"responses":{"Invalid":{"description":"Malformed request","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/OperationOutcome"}}}},"Unauthorized":{"description":"Missing, unknown, revoked or expired key, or the hospital is suspended","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/OperationOutcome"}}}},"Forbidden":{"description":"The key lacks the fhir:read scope","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/OperationOutcome"}}}},"NotFound":{"description":"No such record in this hospital, or the patient is restricted","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/OperationOutcome"}}}},"Throttled":{"description":"More than 600 requests in the current minute from this key","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/OperationOutcome"}}}}}}}