# 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

| Method | Path | Description | Auth Required |
|--------|------|-------------|---------------|
| POST | /login | Authenticate user and create session | No |
| POST | /logout | Destroy current session | Yes |
| GET | /whoami | Get current user info | No (returns unauthenticated if no session) |

#### POST /login

**Request Body:**
```json
{
  "username": "string",
  "password": "string"
}
```

**Success Response (200):**
```json
{
  "message": "Login successful",
  "user": {
    "id": 1,
    "username": "admin",
    "role": "admin",
    "display_name": "Marie Dupont"
  }
}
```

**Error Response (401):**
```json
{
  "error": "Invalid username or password"
}
```

#### POST /logout

**Success Response (200):**
```json
{
  "message": "Logged out successfully"
}
```

#### GET /whoami

**Success Response (200) - Authenticated:**
```json
{
  "authenticated": true,
  "user": {
    "id": 1,
    "username": "admin",
    "role": "admin",
    "display_name": "Marie Dupont"
  }
}
```

**Success Response (200) - Unauthenticated:**
```json
{
  "authenticated": false
}
```

---

### Patients

| Method | Path | Description | Auth Required | Roles |
|--------|------|-------------|---------------|-------|
| GET | /patients | List patients (role-filtered) | Yes | All |
| GET | /patients/{id} | Get patient details | Yes | All |

#### GET /patients

**Query Parameters:**
- id (optional): Filter by patient ID

**Success Response (200):**
```json
{
  "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

| Method | Path | Description | Auth Required | Roles |
|--------|------|-------------|---------------|-------|
| POST | /reports | Submit toxicity report | Yes | Patient, Caregiver, Clinician |
| GET | /reports | List reports | Yes | All |

#### POST /reports

**Request Body:**
```json
{
  "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):**
```json
{
  "message": "Report submitted successfully",
  "report_id": 42,
  "grades": [
    {
      "term": "Nausea",
      "grade": 2,
      "provisional": true
    }
  ],
  "alert": {
    "tier": "urgent",
    "message": "Grade 3 fatigue detected"
  }
}
```

---

### Alerts

| Method | Path | Description | Auth Required | Roles |
|--------|------|-------------|---------------|-------|
| GET | /alerts | List alerts | Yes | Clinician |
| POST | /alerts/{id}/acknowledge | Acknowledge an alert | Yes | Clinician |

---

### Timeline

| Method | Path | Description | Auth Required | Roles |
|--------|------|-------------|---------------|-------|
| GET | /timeline | Get care coordination timeline | Yes | All |

---

### Treatment Plan

| Method | Path | Description | Auth Required | Roles |
|--------|------|-------------|---------------|-------|
| GET | /treatment-plan | Get treatment plan | Yes | All |

---

### Messages

| Method | Path | Description | Auth Required | Roles |
|--------|------|-------------|---------------|-------|
| POST | /messages | Send a message | Yes | All |
| GET | /messages | List messages | Yes | All |

---

### Export

| Method | Path | Description | Auth Required | Roles |
|--------|------|-------------|---------------|-------|
| GET | /export/summary | Generate toxicity summary | Yes | Clinician |

---

### Guidance

| Method | Path | Description | Auth Required | Roles |
|--------|------|-------------|---------------|-------|
| GET | /guidance | Get patient guidance | Yes | All |

---

### Audit Log

| Method | Path | Description | Auth Required | Roles |
|--------|------|-------------|---------------|-------|
| GET | /audit-log | Get audit trail | Yes | Admin |

---

### AI Chat

| Method | Path | Description | Auth Required | Roles |
|--------|------|-------------|---------------|-------|
| POST | /chat | AI chat (stub adapter) | Yes | All |

---

## Notes

1. All timestamps are in ISO 8601 format (UTC).
2. All IDs are integers, auto-incremented by SQLite.
3. Session cookies are HttpOnly but not Secure (for local development).
4. The audit log is append-only and cannot be modified or deleted.
5. The AI chat endpoint uses a stub adapter by default; set GLM_API_KEY environment variable to use the GLM adapter.