Medical Data API
Medical Data API
The HCG AI API provides endpoints for managing pregnancy-related medical data, specifically HCG hormone levels and ultrasound scan measurements. All data endpoints require active session authentication.
Authentication Requirement
All requests to the medical data endpoints must include session cookies. If the user is not logged in, the server returns a 401 Unauthorized response.
HCG Blood Test Entries
Manage $\beta$-hCG tracking data over time.
GET /api/hcg-entries
Retrieves all HCG entries associated with the authenticated user, sorted by date.
Response (Array of Objects):
[
{
"id": 1,
"date": "2023-10-25",
"hcgValue": 1500,
"units": "mIU/mL",
"notes": "First test",
"lmpDate": "2023-09-20",
"cycleLength": 28,
"createdAt": "2023-10-25T10:00:00Z"
}
]
POST /api/hcg-entries
Creates a new HCG entry.
Request Body:
| Field | Type | Description |
| :--- | :--- | :--- |
| date | string | Required. Date in YYYY-MM-DD format. |
| hcgValue | number | Required. The $\beta$-hCG value. |
| units | string | Units (Default: mIU/mL). |
| notes | string | Optional clinical notes. |
| lmpDate | string | Optional Last Menstrual Period date (YYYY-MM-DD). |
| cycleLength | number | Optional average cycle length in days. |
PUT /api/hcg-entries/:id
Updates an existing entry by ID.
DELETE /api/hcg-entries/:id
Permanently removes an entry.
Ultrasound Scan Entries
Manage gestational sac measurements and fetal heart rate data.
GET /api/ultrasound-entries
Retrieves all ultrasound scan records for the authenticated user.
POST /api/ultrasound-entries
Records a new ultrasound scan.
Request Body:
| Field | Type | Description |
| :--- | :--- | :--- |
| date | string | Required. Date in YYYY-MM-DD format. |
| gestationalAge | string | Calculated age (e.g., "6w2d"). |
| gsSize | number | Gestational Sac size in mm. |
| ysSize | number | Yolk Sac size in mm. |
| crlSize | number | Crown-Rump Length in mm. |
| heartRate | number | Fetal heart rate in BPM. |
| numberOfSacs | number | Number of identified gestational sacs. |
| sacData | object | JSON object for detailed multi-sac measurements. |
Analysis Results
Analysis results are generated based on HCG trends or ultrasound measurements. These are read-only resources reflecting the system's risk assessment.
GET /api/analysis-results
Retrieves all calculated diagnoses and risk assessments.
Response Object:
{
"id": 42,
"entryType": "hcg",
"entryId": 12,
"diagnosis": "Normal HCG doubling rate detected.",
"riskLevel": "LOW",
"recommendations": [
"Schedule follow-up scan in 2 weeks",
"Continue prenatal vitamins"
],
"zScores": {
"hcg_z": 0.45
}
}
Risk Levels:
LOW: Measurements fall within expected clinical ranges.MEDIUM: Requires clinical correlation or follow-up testing.HIGH: Results significantly deviate from expected values; immediate medical consultation recommended.
Error Responses
| Code | Meaning | Description |
| :--- | :--- | :--- |
| 400 | Bad Request | Missing required fields or invalid data formats (e.g., invalid date string). |
| 401 | Unauthorized | Session is missing or expired. |
| 404 | Not Found | The requested entry ID does not exist or does not belong to the user. |
| 500 | Server Error | Database connection failure or internal processing error. |