# MindScreen AI — API Documentation

Full interactive docs are auto-generated by FastAPI once the server is
running: **`/docs`** (Swagger UI) and **`/redoc`**. This file is a
human-readable companion summary.

Base URL (local dev): `http://localhost:8000`

All authenticated endpoints require:
```
Authorization: Bearer <access_token>
```

---

## Auth

### `POST /auth/register`
Register a new participant. Enforces age eligibility (18–30) server-side.

```json
// Request
{
  "email": "person@example.com",
  "password": "SecurePass123",
  "display_name": "Alex",
  "date_of_birth": "2001-05-14"
}
```
Returns the created `UserProfile` (201). Sends a verification email (or logs
the link to the console if SMTP isn't configured — see INSTALLATION.md).

### `POST /auth/login`
```json
{ "email": "person@example.com", "password": "SecurePass123" }
```
Returns `{ "access_token": "...", "token_type": "bearer" }`.

### `POST /auth/verify-email`
```json
{ "token": "<token from the verification email/log>" }
```

### `GET /auth/me` — requires auth
Returns the current user's profile.

### `PUT /auth/me` — requires auth
Update `display_name`.

### `POST /auth/consent` — requires auth
Records informed-consent timestamp for the research study.

---

## Chat

### `POST /chat/start` — requires auth
Starts a new screening session. Returns the first bot message (consent
prompt) and a `session_uuid` to use for all subsequent turns.

### `POST /chat/message` — requires auth
```json
{ "session_uuid": "...", "message": "yes" }
```
Returns:
```json
{
  "bot_message": "...",
  "stage": "phq9",
  "safety_triggered": false,
  "is_complete": false,
  "result": null
}
```
When the session finishes, `is_complete` is `true` and `result` contains the
full `ScreeningResult` (depression/anxiety/stress scores, risk levels,
overall wellness, confidence, explanations, and the secondary ML signal).

If `safety_triggered` is `true`, the bot has paused the screening and
returned crisis resources instead of a normal reply — display this message
prominently and stop sending further screening prompts.

### `GET /chat/history/{session_uuid}` — requires auth
Full transcript of a session you own.

### `GET /chat/sessions` — requires auth
List all of your past sessions (id, stage, timestamps).

---

## Reports

### `GET /reports/{session_uuid}` — requires auth
Returns the generated screening report as HTML (self-contained, includes
scores, explanation, conversation summary, next steps, and the mandatory
disclaimer).

### `POST /feedback` — requires auth
```json
{ "session_uuid": "...", "rating": 4, "comment": "Felt easy to talk to." }
```

---

## Dashboard *(research use)*

> ⚠️ These endpoints currently only require any authenticated user. Before
> production use, add a researcher/admin role check (see the TODO comment
> in `dashboard_router.py`).

### `GET /dashboard/stats`
Aggregate counts, average scores, risk-level distribution per domain,
sessions in the last 7 days, sessions in the last 12 months.

### `GET /dashboard/export-csv`
Streams an anonymized CSV (uses `participant_code`, never email/name/raw
message text) of every completed session's scores.

---

## Errors

Standard FastAPI/Pydantic error shape:
```json
{ "detail": "human-readable message" }
```
| Status | Meaning |
|---|---|
| 400 | Validation failed (e.g. age outside 18–30, weak password) |
| 401 | Missing/invalid/expired token, or wrong credentials |
| 404 | Resource not found or not owned by the current user |
| 409 | Email already registered |
| 410 | Chat session no longer active in server memory (restart occurred) — start a new one |