REST API

Cette page est l'index du catalogue REST. Phase A pose la structure et fournit un exemple. Phase B documente l'ensemble des endpoints jalon-par-jalon avec le composant EndpointReference.

Approche

La référence est manuelle (cf. ADR Phase A) plutôt qu'auto-générée depuis l'OpenAPI. Justification :

Le composant EndpointReference permet d'inclure du contexte métier (invariants, idempotency, rate limits, exemples curl, JS, Kotlin) que l'OpenAPI ne capture pas
La cadence d'évolution back-end est lente (un jalon par mois en moyenne), la rédaction manuelle reste tenable
Le snapshot OpenAPI brut reste exposé pour outillage (Postman, generators), voir section ci-dessous

Spec OpenAPI brute

Pour les outils qui consomment de l'OpenAPI 3.0 (Postman, openapi-generator, kreya, ...) :

Statique embarqué dans la doc : /openapi.json
Endpoint live dev : curl https://api-dev.195-154-239-8.sslip.io/docs-json | jq
Téléchargement direct : openapi.json

Endpoints actuels (snapshot Jalon 2)

Méthode	Path	Description
`GET`	`/health`	Liveness probe, `{ status: "ok" }`
`POST`	`/realtime/token`	Issue un token LiveKit `accessToken` pour un senior authentifié
`POST`	`/v1/auth/login`	Login senior, aidant ou admin
`POST`	`/v1/auth/refresh`	Rotation du refresh token
`POST`	`/v1/auth/2fa/enroll`	Provisionne le secret TOTP (aidant, admin)
`POST`	`/v1/auth/2fa/verify`	Vérifie le code TOTP
`POST`	`/v1/auth/password-reset/request`	Demande de réinitialisation par email
`POST`	`/v1/auth/password-reset/apply`	Applique un token de réinitialisation
`GET`	`/v1/profile`	Profil du senior connecté
`GET`	`/v1/consents`	Catégories de consentement actives
`PUT`	`/v1/consents`	Mise à jour des consentements granulaires
`POST`	`/v1/alerts/button-pressed`	Ingestion bouton d'alerte (idempotency requis)
`GET`	`/v1/alerts/trail/:seniorId`	Trail d'alertes (aidant scope, RLS)
`GET`	`/v1/admin/alerts/recent`	Dashboard admin, alertes récentes
`POST`	`/v1/admin/caregivers/:id/reactivation-notice`	Réactiver un aidant désactivé
`GET`	`/v1/onboarding/caregiver-config`	Configuration aidant onboarding
`PUT`	`/v1/onboarding/caregiver-config`	Mise à jour configuration onboarding
`POST`	`/v1/onboarding/postpone`	Reporter l'étape d'onboarding en cours
`POST`	`/v1/onboarding/resume`	Reprendre l'onboarding après un report
`GET`	`/v1/assistance/sessions`	Liste sessions d'assistance
`GET`	`/v1/export/user-data`	Export RGPD complet (ZIP signé)

Vues admin par senior (dashboard `/seniors/:id`)

Méthode	Path	Description
`GET`	`/v1/admin/seniors/:seniorId/caregivers/cascade`	Vue cascade 3 tiers + dernier trail (PII masquée, INV-T07b)
`GET`	`/v1/admin/seniors/:seniorId/reminders`	Rappels à venir (fenêtre `?within_days=`, filtre `?kind=`)
`GET`	`/v1/admin/seniors/:seniorId/reminders/all`	Vue brute table `reminders` (tous statuses + tous kinds + passé + futur), filtres opt-in `?status=`, `?kind=`, `?from=`, `?to=`. Pagination cursor base64url `(created_at DESC, id DESC)`, `?limit=1..200` (default 50)
`GET`	`/v1/admin/seniors/:seniorId/mood-entries`	Journal humeur brut, 1 row / capture `mood_scores`. Filtres `?source=` (enum `per_turn`, `end_of_day`, `manual_entry`, `onboarding_j7`), `?from=`, `?to=`. Pagination cursor `(recorded_at DESC, id DESC)`, `?limit=1..200`
`GET`	`/v1/admin/seniors/:seniorId/absence-mode`	État du mode absence (INV-S07)
`PUT`	`/v1/admin/seniors/:seniorId/absence-mode`	Activer / désactiver le mode absence (`{ active, until? }`, `until` requis si active=true et strictement futur)
`POST`	`/v1/admin/seniors/:seniorId/mood-entries/seed-test`	Dev seed du journal humeur (`{ days?: 1..30 default 7 }`). Bloqué en prod sauf `ALLOW_TEST_SEED_IN_PROD=true`. Rate-limit 10 / actor / heure

Administration users + stats

Méthode	Path	Description
`GET`	`/v1/admin/users`	Liste users paginée (`?cursor=&limit=1..100 default 50`). Filtres `?role=` (enum `senior`, `aidant`, `admin`), `?include_deleted=` (enum `true`, `false`, default `false`), `?search=` (1..256, trim, `ILIKE %search%` case-insensitive sur `users.email` + `seniors.display_name`). La réponse expose `total_count` (`COUNT(*) OVER ()`, respecte les filtres)
`GET`	`/v1/admin/users/:id`	Détail user
`PUT`	`/v1/admin/users/:id`	Modifier `role` / `senior_id`
`DELETE`	`/v1/admin/users/:id`	Soft-delete RGPD
`GET`	`/v1/admin/users/:id/export`	Export JSON minimal (full export = BLOC-14)
`POST`	`/v1/admin/stats/tokens/seed-test`	Dev seed `token_usage`. Body : `days_back?` (1..90, default 30), `models?` (array string), `flux?` (array enum `cache`, `memory`, `agent`). Réponse : `senior_id`, `days_back`, `models`, `flux`, `seeded_count`, `tokens_used_total`, `cost_eur_micros_total`. Bloqué en prod sauf `ALLOW_TEST_SEED_IN_PROD=true`. Rate-limit 5 / actor / heure

La liste n'est pas exhaustive. Phase B remplit EndpointReference pour chaque endpoint.

Exemple, EndpointReference

Cet exemple illustre le format ciblé pour Phase B :

POST/v1/auth/login

Échange email + password (+ TOTP pour aidant/admin) contre une paire accessToken + refreshToken JWT.

Auth: Public
Idempotency: Optional
Rate limit: 5/min/IP

Request body

Champ	Type	Requis	Notes
`email`	string	Oui	Format RFC 5322
`password`	string	Oui	Min 12 caractères
`role`	"senior" \| "aidant" \| "admin"	Oui	Détermine 2FA
`totpCode`	string	Conditionnel	Requis pour aidant/admin

Response body

Champ	Type	Notes
`accessToken`	string	JWT 15 min
`refreshToken`	string	JWT 7 jours (senior) ou 24h (aidant/admin)
`expiresIn`	number	Secondes
`requiresTwoFactor`	true	Présent si TOTP attendu

Error codes

HTTP	Cause	Body
400	Payload mal formé	`{ message: "Validation failed", details: [...] }`
401	Email ou password invalide	`{ message: "Invalid credentials" }`
409	TOTP requis mais non fourni	`{ requiresTwoFactor: true }`
429	Rate limit dépassé	Header `Retry-After`

Examples

curl -X POST https://api-dev.195-154-239-8.sslip.io/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"senior@example.com","password":"hunter2!@#","role":"senior"}'

const res = await fetch(`${API}/v1/auth/login`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ email, password, role: "senior" }),
});
const tokens = await res.json();

val response = client.post("$apiBase/v1/auth/login") {
contentType(ContentType.Application.Json)
setBody(mapOf("email" to email, "password" to password, "role" to "senior"))
}
val tokens = response.body<AuthLoginResponse>()

Phase B remplira la page avec une EndpointReference par endpoint et la regroupera par bounded context (auth, conversation, security, profile, administration). Voir la liste prévisionnelle dans DESIGN-V2.md Section 9.

REST API

Approche

Spec OpenAPI brute

Endpoints actuels (snapshot Jalon 2)

Vues admin par senior (dashboard `/seniors/:id`)

Administration users + stats

Exemple, EndpointReference

Request body

Response body

Error codes

Évolutions à venir

On this page

REST API

Approche

Spec OpenAPI brute

Endpoints actuels (snapshot Jalon 2)

Vues admin par senior (dashboard /seniors/:id)

Administration users + stats

Exemple, EndpointReference

Request body

Response body

Error codes

Évolutions à venir

On this page

Vues admin par senior (dashboard `/seniors/:id`)