Hospital API reference

The Hospital API is the entry point used by HealthTAG Lambda functions running on AWS. It receives the HealthTAG request, validates access, and queries the hospital’s FHIR server. The current Compose file exposes it at http://<NODE_HOST>:9000; restrict access to approved HealthTAG callers in production.

The hospital creates and manages FHIR_API_KEY. The Hospital API sends this key to Kong in the apikey header when it queries the key-authenticated FHIR route. The key does not authenticate the Lambda request to the Hospital API.

GET /api/health-check

Returns HTTP 200 with an empty JSON object when the Express process can serve requests.

curl --fail http://<NODE_HOST>:9000/api/health-check

{}

This is a liveness check only; it does not test PostgreSQL, HAPI, Kong, the upstream HealthTAG API, or blockchain RPC.

POST /api/patients

Retrieves the matching patient’s FHIR $everything entries after the application’s access flow.

Request

Item	Required	Description
Content-Type: application/json	Yes	JSON request body
promptCareId	Yes	HealthTAG patient identifier value
token	Yes	Forwarded as the Authorization header to HEALTHTAG_API_URL/validate-access

curl --request POST 'http://<NODE_HOST>:9000/api/patients' \
  --header 'Content-Type: application/json' \
  --data '{"promptCareId":"<PROMPT_CARE_ID>","token":"<ACCESS_TOKEN>"}'

Success response

{
  "resources": [
    { "resource": { "resourceType": "Patient", "id": "example" } }
  ]
}

The array is copied from the FHIR Bundle’s entry field, so each element is a Bundle entry rather than a bare resource. If lookup or $everything parsing fails, the current implementation may return HTTP 200 with {}.

Current status behavior

Status	Meaning in current code
200	Data response or {} when patient/FHIR parsing fails
400	Missing fields, incomplete upstream credentials, or intended access denial
500 or connection failure	Unhandled upstream/FHIR/runtime error

The endpoint has no stable structured error schema. Do not build client behavior around response bodies for failures.

[!DANGER] The current authorization implementation has known defects. Read Known implementation risks before integrating or deploying it.

The FHIR data flow explains how the endpoint searches HAPI and builds its response.