# HAD Digital - API Contract

Version: 1.0.0 Date: 5 September 2026 Base URL: http://127.0.0.1:8080/api

Authentication

All endpoints except /login require a valid session cookie. The session cookie is set by the /login endpoint and must be included in subsequent requests.

Session Cookie: HAD_SESSION Max Age: 86400 seconds (24 hours)

Endpoints

Authentication

POST /login

Request Body:

{
  "username": "string",
  "password": "string"
}

Success Response (200):

{
  "message": "Login successful",
  "user": {
    "id": 1,
    "username": "admin",
    "role": "admin",
    "display_name": "Marie Dupont"
  }
}

Error Response (401):

{
  "error": "Invalid username or password"
}

POST /logout

Success Response (200):

{
  "message": "Logged out successfully"
}

GET /whoami

Success Response (200) - Authenticated:

{
  "authenticated": true,
  "user": {
    "id": 1,
    "username": "admin",
    "role": "admin",
    "display_name": "Marie Dupont"
  }
}

Success Response (200) - Unauthenticated:

{
  "authenticated": false
}

Patients

GET /patients

Query Parameters:

• id (optional): Filter by patient ID

Success Response (200):

{
  "patients": [
    {
      "id": 1,
      "mrn": "MRN-2024-001",
      "first_name": "Jeanne",
      "last_name": "Durand",
      "date_of_birth": "1958-03-15",
      "gender": "F",
      "phone": "+33 6 12 34 56 78",
      "address": "15 Rue de la Paix, Paris",
      "treatment_protocol": "FOLFOX6",
      "current_cycle": "Cycle 3 Day 8"
    }
  ]
}

Toxicity Reports

POST /reports

Request Body:

{
  "patient_id": 1,
  "symptoms": {
    "nausea": 2,
    "vomiting": 1,
    "diarrhea": 0,
    "fatigue": 3,
    "bleeding": 0,
    "infection_signs": 0,
    "rash": 0,
    "skin_changes": 0,
    "numbness": 1,
    "weakness": 2,
    "fever": 0,
    "weight_loss": 0
  },
  "notes": "Additional notes about symptoms",
  "type": "patient_report"
}

Symptom Values:

• 0: None

• 1: Mild / Grade 1

• 2: Moderate / Grade 2

• 3: Severe / Grade 3+

Success Response (200):

{
  "message": "Report submitted successfully",
  "report_id": 42,
  "grades": [
    {
      "term": "Nausea",
      "grade": 2,
      "provisional": true
    }
  ],
  "alert": {
    "tier": "urgent",
    "message": "Grade 3 fatigue detected"
  }
}

Alerts

Timeline

Treatment Plan

Messages

Export

Guidance

Audit Log

AI Chat

Notes

1. All timestamps are in ISO 8601 format (UTC).

1. All IDs are integers, auto-incremented by SQLite.

1. Session cookies are HttpOnly but not Secure (for local development).

1. The audit log is append-only and cannot be modified or deleted.

1. The AI chat endpoint uses a stub adapter by default; set GLM_API_KEY environment variable to use the GLM adapter.