Bloodwork Tracker API Documentation

Swagger-style reference for the external API. Use API keys created in the app's API page. All responses are JSON.

Open app

Base URL: https://health-tracker.project4.net/api

Authentication

Send one of these headers with external API requests:

X-API-Key: bwt_...
Authorization: Bearer bwt_...

Create keys in the signed-in app under API. Full API keys are shown once only.

Response Codes

Success Codes

Every response includes an X-BWT-Code header. Object responses also include a top-level code field. Array responses keep their array body for backward compatibility.

BWT_SUCCESS
BWT_CREATED
BWT_OK

Error Body

{
  "code": "BWT_API_KEY_INVALID",
  "message": "Invalid or missing API key"
}

ERRORError Codes

BWT_INVALID_JSON      Request body could not be parsed as JSON
BWT_VALIDATION_FAILED Required fields or values are missing or invalid
BWT_INVALID_DATE      Date is not valid YYYY-MM-DD
BWT_INVALID_NUMBER    Number field is not numeric
BWT_INVALID_OTP       One-time login code is invalid
BWT_API_KEY_INVALID   API key is missing, inactive, revoked, or incorrect
BWT_UNAUTHORIZED      Browser session is missing or invalid
BWT_FORBIDDEN         Authenticated user cannot perform the action
BWT_NOT_FOUND         Route or generic resource not found
BWT_TEST_NOT_FOUND    Blood test not found for this user/key
BWT_RESULT_NOT_FOUND  Result not found for this user/key
BWT_CONFLICT          Request conflicts with current state
BWT_RATE_LIMITED      Too many requests
BWT_SERVER_ERROR      Unexpected server error

Schemas

BloodTest

{
  "id": 123,
  "testName": "Haemoglobin",
  "groupName": "GENERAL HAEMATOLOGY",
  "unitOfMeasure": "g/L",
  "unitId": "g_l",
  "analyteId": "haemoglobin",
  "normalizedUnit": "g/L",
  "analyteName": "Haemoglobin",
  "refRangeLow": 135,
  "refRangeHigh": 180,
  "targetZoneEnabled": true,
  "targetZoneLow": 145,
  "targetZoneHigh": 165,
  "targetZoneUnit": "g/L",
  "archivedAt": null,
  "archivedReason": "",
  "conversions": [
    {
      "unitId": "g_dl",
      "unit": "g/dL",
      "multiplyBy": 0.1,
      "isApproximate": false,
      "source": "Derived metric prefix conversion",
      "notes": ""
    }
  ],
  "createdAt": "2026-05-06 10:00:00+00"
}

Normalized unit fields are included when a marker matches the built-in analyte catalog. unitOfMeasure remains the original/native unit text for backward compatibility. Target zones are visualization-only optimal ranges and do not affect low, high, or in-range status. Archived assays include archivedAt and archivedReason.

Result

{
  "id": 456,
  "testId": 123,
  "testDate": "2026-05-06",
  "value": 151,
  "createdAt": "2026-05-06 10:00:00+00"
}

External Endpoints

GET/external/bootstrap

Returns all tests, all results, and clinical notes.

Example request

curl https://health-tracker.project4.net/api/external/bootstrap \
  -H "Authorization: Bearer $BWT_API_KEY"

Example response

{
  "code": "BWT_SUCCESS",
  "tests": [],
  "results": [],
  "clinicalNotes": "Patient context..."
}

GET/external/tests

List blood tests. Optional status query values are active (default), archived, and all.

Example request

curl "https://health-tracker.project4.net/api/external/tests?status=active" \
  -H "Authorization: Bearer $BWT_API_KEY"

Example response

[
  {
    "id": 123,
    "testName": "Haemoglobin",
    "groupName": "GENERAL HAEMATOLOGY",
    "unitOfMeasure": "g/L",
    "archivedAt": null,
    "archivedReason": "",
    "refRangeLow": 135,
    "refRangeHigh": 180,
    "targetZoneEnabled": true,
    "targetZoneLow": 145,
    "targetZoneHigh": 165,
    "targetZoneUnit": "g/L",
    "createdAt": "2026-05-06 10:00:00+00"
  }
]

POST/external/tests

Create a blood test.

Example request

curl -X POST https://health-tracker.project4.net/api/external/tests \
  -H "Authorization: Bearer $BWT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "testName": "Ferritin",
    "groupName": "IRON STUDIES",
    "unitOfMeasure": "ug/L",
    "refRangeLow": 30,
    "refRangeHigh": 400,
    "targetZoneEnabled": true,
    "targetZoneLow": 80,
    "targetZoneHigh": 180,
    "targetZoneUnit": "ug/L"
  }'

Request body

{
  "testName": "Ferritin",
  "groupName": "IRON STUDIES",
  "unitOfMeasure": "ug/L",
  "refRangeLow": 30,
  "refRangeHigh": 400,
  "targetZoneEnabled": true,
  "targetZoneLow": 80,
  "targetZoneHigh": 180,
  "targetZoneUnit": "ug/L"
}

Example response

{
  "code": "BWT_CREATED",
  "id": 124,
  "testName": "Ferritin",
  "groupName": "IRON STUDIES",
  "unitOfMeasure": "ug/L",
  "refRangeLow": 30,
  "refRangeHigh": 400,
  "targetZoneEnabled": true,
  "targetZoneLow": 80,
  "targetZoneHigh": 180,
  "targetZoneUnit": "ug/L",
  "createdAt": "2026-05-06 10:00:00+00"
}

GET/external/tests/{id}

Return one test and its results.

Example request

curl https://health-tracker.project4.net/api/external/tests/123 \
  -H "Authorization: Bearer $BWT_API_KEY"

Example response

{
  "code": "BWT_SUCCESS",
  "test": {
    "id": 123,
    "testName": "Haemoglobin",
    "groupName": "GENERAL HAEMATOLOGY",
    "unitOfMeasure": "g/L",
    "refRangeLow": 135,
    "refRangeHigh": 180,
    "targetZoneEnabled": true,
    "targetZoneLow": 145,
    "targetZoneHigh": 165,
    "targetZoneUnit": "g/L",
    "createdAt": "2026-05-06 10:00:00+00"
  },
  "results": [
    {
      "id": 456,
      "testId": 123,
      "testDate": "2026-05-06",
      "value": 151,
      "createdAt": "2026-05-06 10:00:00+00"
    }
  ]
}

PUT/external/tests/{id}

Replace a test definition.

Example request

curl -X PUT https://health-tracker.project4.net/api/external/tests/123 \
  -H "Authorization: Bearer $BWT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "testName": "Ferritin",
    "groupName": "IRON STUDIES",
    "unitOfMeasure": "ug/L",
    "refRangeLow": 30,
    "refRangeHigh": 400,
    "targetZoneEnabled": true,
    "targetZoneLow": 80,
    "targetZoneHigh": 180,
    "targetZoneUnit": "ug/L"
  }'

Example response

{
  "code": "BWT_SUCCESS",
  "id": 123,
  "testName": "Ferritin",
  "groupName": "IRON STUDIES",
  "unitOfMeasure": "ug/L",
  "refRangeLow": 30,
  "refRangeHigh": 400,
  "targetZoneEnabled": true,
  "targetZoneLow": 80,
  "targetZoneHigh": 180,
  "targetZoneUnit": "ug/L",
  "createdAt": "2026-05-06 10:00:00+00"
}

PATCH/external/tests/{id}

Update a test definition.

Example request

curl -X PATCH https://health-tracker.project4.net/api/external/tests/123 \
  -H "Authorization: Bearer $BWT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "testName": "Ferritin",
    "groupName": "IRON STUDIES",
    "unitOfMeasure": "ug/L",
    "refRangeLow": 30,
    "refRangeHigh": 400,
    "targetZoneEnabled": true,
    "targetZoneLow": 80,
    "targetZoneHigh": 180,
    "targetZoneUnit": "ug/L"
  }'

Example response

{
  "code": "BWT_SUCCESS",
  "id": 123,
  "testName": "Ferritin",
  "groupName": "IRON STUDIES",
  "unitOfMeasure": "ug/L",
  "refRangeLow": 30,
  "refRangeHigh": 400,
  "targetZoneEnabled": true,
  "targetZoneLow": 80,
  "targetZoneHigh": 180,
  "targetZoneUnit": "ug/L",
  "createdAt": "2026-05-06 10:00:00+00"
}

DELETE/external/tests/{id}

Delete a test and its results.

Example request

curl -X DELETE https://health-tracker.project4.net/api/external/tests/123 \
  -H "Authorization: Bearer $BWT_API_KEY"

Example response

{ "code": "BWT_OK", "ok": true }

GET/external/results

List results. Optional query parameters: testId, from, to, and status. Archived assay results are hidden unless status=archived or status=all is requested.

Example request

curl "https://health-tracker.project4.net/api/external/results?testId=123&from=2026-01-01&to=2026-12-31&status=active" \
  -H "Authorization: Bearer $BWT_API_KEY"

Example response

[
  {
    "id": 456,
    "testId": 123,
    "testDate": "2026-05-06",
    "value": 151,
    "createdAt": "2026-05-06 10:00:00+00"
  }
]

POST/external/results

Create or upsert a dated result.

Example request

curl -X POST https://health-tracker.project4.net/api/external/results \
  -H "Authorization: Bearer $BWT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "testId": 123,
    "testDate": "2026-05-06",
    "value": 151
  }'

Request body

{
  "testId": 123,
  "testDate": "2026-05-06",
  "value": 151
}

Example response

{
  "code": "BWT_CREATED",
  "id": 456,
  "testId": 123,
  "testDate": "2026-05-06",
  "value": 151,
  "createdAt": "2026-05-06 10:00:00+00"
}

GET/external/results/{id}

Return one result.

Example request

curl https://health-tracker.project4.net/api/external/results/456 \
  -H "Authorization: Bearer $BWT_API_KEY"

Example response

{
  "code": "BWT_SUCCESS",
  "id": 456,
  "testId": 123,
  "testDate": "2026-05-06",
  "value": 151,
  "createdAt": "2026-05-06 10:00:00+00"
}

PUT/external/results/{id}

Replace a result.

Example request

curl -X PUT https://health-tracker.project4.net/api/external/results/456 \
  -H "Authorization: Bearer $BWT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "testId": 123,
    "testDate": "2026-05-06",
    "value": 152
  }'

Example response

{
  "code": "BWT_SUCCESS",
  "id": 456,
  "testId": 123,
  "testDate": "2026-05-06",
  "value": 152,
  "createdAt": "2026-05-06 10:00:00+00"
}

PATCH/external/results/{id}

Update a result.

Example request

curl -X PATCH https://health-tracker.project4.net/api/external/results/456 \
  -H "Authorization: Bearer $BWT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "testId": 123,
    "testDate": "2026-05-06",
    "value": 152
  }'

Example response

{
  "code": "BWT_SUCCESS",
  "id": 456,
  "testId": 123,
  "testDate": "2026-05-06",
  "value": 152,
  "createdAt": "2026-05-06 10:00:00+00"
}

DELETE/external/results/{id}

Delete a result.

Example request

curl -X DELETE https://health-tracker.project4.net/api/external/results/456 \
  -H "Authorization: Bearer $BWT_API_KEY"

Example response

{ "code": "BWT_OK", "ok": true }

GET/external/clinical-notes

Return clinical notes.

Example request

curl https://health-tracker.project4.net/api/external/clinical-notes \
  -H "Authorization: Bearer $BWT_API_KEY"

Example response

{
  "code": "BWT_SUCCESS",
  "clinicalNotes": "Patient context..."
}

PUT/external/clinical-notes

Update clinical notes.

Example request

curl -X PUT https://health-tracker.project4.net/api/external/clinical-notes \
  -H "Authorization: Bearer $BWT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clinicalNotes": "Updated patient context..."
  }'

Request body

{ "clinicalNotes": "Updated patient context..." }

Example response

{
  "code": "BWT_SUCCESS",
  "clinicalNotes": "Updated patient context..."
}

Example

curl https://health-tracker.project4.net/api/external/tests \
  -H "Authorization: Bearer $BWT_API_KEY"

Markdown reference remains available at API-DOCS.md.