HCG Monitoring API

HCG Monitoring API

The HCG Monitoring API allows users to record, retrieve, and manage β-hCG blood test results. It supports basic value tracking as well as advanced gestational details such as Last Menstrual Period (LMP) and cycle length to facilitate more accurate risk assessment.

Authentication

All HCG Monitoring endpoints require an active session. Requests must include the session cookie established via the /api/login or /api/register endpoints.

---

Data Object Schema

When interacting with HCG entries, the data follows this structure:

| Field | Type | Description | | :--- | :--- | :--- | | id | number | Unique identifier (read-only). | | date | string | The date of the blood test in YYYY-MM-DD format. | | hcgValue | number | The β-hCG concentration level. | | units | string | Units of measurement (default: mIU/mL). | | notes | string | Optional clinical or personal notes. | | lmpDate | string | Optional: Date of Last Menstrual Period (YYYY-MM-DD). | | cycleLength | number | Optional: Average menstrual cycle length in days. | | ovulationDate| string | Optional: Estimated or confirmed ovulation date (YYYY-MM-DD). |

---

Endpoints

1. Retrieve All Entries

Fetch a list of all HCG entries associated with the authenticated user, sorted by entry date.

• URL: /api/hcg-entries
• Method: GET
• Success Response: 200 OK
• Example Output:

  [
    {
      "id": 101,
      "date": "2023-10-15",
      "hcgValue": 450,
      "units": "mIU/mL",
      "lmpDate": "2023-09-10",
      "cycleLength": 28,
      "notes": "First blood draw"
    }
  ]
  

2. Create New Entry

Create a new HCG record. This data is used by the AI engine to calculate doubling times and risk levels.

• URL: /api/hcg-entries
• Method: POST
• Payload:

  {
    "date": "2023-10-17",
    "hcgValue": 1200,
    "units": "mIU/mL",
    "notes": "Follow-up test",
    "lmpDate": "2023-09-10"
  }
  

• Success Response: 200 OK (returns the created object).

3. Update Entry

Modify an existing record by its unique ID.

• URL: /api/hcg-entries/:id
• Method: PUT
• Payload: Any subset of the data fields.
• Example Request:

  {
    "hcgValue": 1250,
    "notes": "Correction: updated value from lab portal"
  }
  

• Success Response: 200 OK
• Error Response: 404 Not Found if the ID does not exist for the current user.

4. Delete Entry

Permanently remove a record from the tracking history.

• URL: /api/hcg-entries/:id
• Method: DELETE
• Success Response: 200 OK

  { "message": "HCG entry deleted successfully" }
  

---

Advanced Cycle Tracking

The API supports advanced fields (lmpDate, cycleLength, ovulationDate) which are critical for users with irregular cycles or those using Assisted Reproductive Technology (ART).

When these fields are provided, the backend's analysis engine (see Analysis Results) prioritizes them over standard calculations to provide a more accurate "Adjusted Gestational Age."