The TB Predict FHIR API

Overview

TB Predict scores the risk that a patient's TB treatment ends badly, and keeps the record behind every score. Other systems — a patient management system, a data warehouse, a dashboard — use it through two APIs on the same database and the same prediction pipeline, so nothing can drift between them.

Quick start

Three steps from nothing to your first patient read.

1. 1

   Get an account

   Request access for the facility, sub-county, county or national level your integration serves. A super-administrator approves it; the API then returns exactly the patients that level covers.

2. 2

   Get a token

   Sign in with the account's username (or email) and password. The response carries a token.

   curl -X POST http://tbmldashboard.masterclass.co.ke/api/auth/login/ \
     -H "Content-Type: application/json" \
     -d '{"username": "your-username", "password": "your-password"}'
   
   # → { "token": "9f2c…", … }

3. 3

   Call the FHIR server

   Send the token as a Bearer token. Find a patient by TB registration number, then fetch the whole record in one call.

   curl "http://tbmldashboard.masterclass.co.ke/fhir/Patient?identifier=TB123456" \
     -H "Authorization: Bearer <token>" \
     -H "Accept: application/fhir+json"
   
   curl "http://tbmldashboard.masterclass.co.ke/fhir/Patient/<id>/$everything" \
     -H "Authorization: Bearer <token>"

Authentication & access

• Tokens. POST /api/auth/login/ returns one. Send it on every request as Authorization: Bearer <token> (the FHIR convention) or Authorization: Token <token> — both are accepted everywhere.
• Expiry. A token stops working 12 hours after it is issued, whatever the activity. Signing in again issues a new one; POST /api/auth/logout/ revokes the current token at once.
• Scope. Every clinical resource is limited to the account's access level — national, county, sub-county or facility. A record outside it answers 404, exactly like one that does not exist, so probing ids reveals nothing.
• Audit. Every read of a patient's record is logged, and super-administrators can read the trail as AuditEvent resources.
• Public, no token needed: /fhir/metadata, the conformance resources, Organization, Location, Device, $validate and /api/health/.
• Browsers. The server sends no CORS headers: integrations are expected to call it from a server, not from a web page on another site.

Resources

Paths are relative to http://tbmldashboard.masterclass.co.ke/fhir/. Search parameters in the notes; the CapabilityStatement lists every one formally.

Operations

FHIR operations for what a plain read or search cannot do.

Requesting a prediction

Post a Parameters resource carrying the patient and whatever observations are known — only age, sex and county are required. The answer is the prediction as a RiskAssessment, and the follow-up Task when the patient is flagged.

POST /fhir/Patient/$predict-outcome
Authorization: Bearer <token>
Content-Type: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [
    { "name": "patient",
      "resource": { "resourceType": "Patient", … } },
    { "name": "observation",
      "resource": { "resourceType": "Observation", … } }
  ]
}

HTTP/1.1 200 OK
Content-Type: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [
    { "name": "riskAssessment",
      "resource": { "resourceType": "RiskAssessment", … } },
    { "name": "task",
      "resource": { "resourceType": "Task", … } }
  ]
}

Searching & paging

• Searches return searchset Bundles with total, a fullUrl and search.mode on every entry, and self / next / previous links.
• Page with _count — 50 by default, up to 1,000 — and follow the next link rather than building page URLs yourself.
• _summary=count returns the total only; _elements returns a marked subset of each resource.
• _include and _revinclude are honoured where the resource declares them (see Resources), and _sort on RiskAssessment (date), Task (authored-on) and AuditEvent (date).

Errors

The FHIR server answers every error with an OperationOutcome saying what went wrong. The core API answers {"error": "…"} — or {"detail": "…"} for sign-in failures — with a standard status code.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer

{
  "resourceType": "OperationOutcome",
  "issue": [{
    "severity": "error",
    "code": "login",
    "diagnostics": "…"
  }]
}

Conformance

• GET /fhir/metadata returns the CapabilityStatement — the machine-readable list of every resource, search parameter and operation this server supports.
• Every profile, code system and value set it uses is published on the server too, under StructureDefinition, CodeSystem, ValueSet, OperationDefinition and SearchParameter.
• Output is checked with the official HL7 FHIR validator in the backend's test suite, and every reference a resource carries resolves on this server.
• Check your own resources before sending them with POST /fhir/{Type}/$validate.

Core API

Paths are relative to http://tbmldashboard.masterclass.co.ke/api/.