tom/HealthLog
1
0 Fork 0
mirror of https://github.com/MBombeck/HealthLog.git synced 2026-11-08 12:32:43 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
2e2ca2242fb615bb22a2ea384cff2d5d4e3e3fe9
HealthLog/docs/api/openapi-v1422-legacy.yaml
T
Marc-André BombeckandClaude Opus 4.7 a8b233bf86 chore(deps): add zod-openapi + yaml@2 — OpenAPI generator base 
Wires the OpenAPI 3.1 generator scaffolding ahead of the iOS-touched
route registrations. `zod-openapi` (samchungy variant, picked in W1
stream-3) reads Zod v4's native `.meta()` so schemas can stay in their
original validation files; `yaml@2` with `sortMapEntries: true` keeps
the emitted spec stable across re-runs.

`pnpm openapi:generate` overwrites `docs/api/openapi.yaml` from the
registry; `pnpm openapi:check` exits non-zero on drift. The legacy
hand-maintained spec is preserved at `docs/api/openapi-v1422-legacy.yaml`
so the iOS contract reference doesn't disappear during the
incremental migration.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-11 00:56:32 +02:00

5469 lines
176 KiB
YAML
Raw Blame History

openapi: 3.1.0
info:
title: HealthLog API
version: 1.4.0
description: |
REST API for HealthLog — a personal health-tracking PWA covering weight,
blood pressure, pulse, mood, medication compliance, blood glucose, body
composition (total body water + bone mass), pulse oximetry (SpO2), and
sleep. The same API powers the Next.js web client and the native iOS
client.
## Authentication
All non-public endpoints accept either a session cookie (`healthlog_session`,
obtained via password login or passkey verification) or a long-lived Bearer
token (`Authorization: Bearer hlk_...`) issued via `/api/tokens`. The two
schemes are interchangeable on user endpoints — clients pick whichever
suits them (cookies for the web app, Bearer for the iOS client and
machine-to-machine integrations). Admin endpoints (`/api/admin/*`) accept
only the session cookie; Bearer tokens never elevate to admin.
The API uses an envelope response shape: `{ data, error }`. On success,
`data` carries the payload and `error` is `null`. On failure, `data` is
`null` and `error` is a human-readable message.
## Conventions
- All timestamps are ISO 8601 (`date-time`) in UTC.
- All numeric IDs are CUIDs (opaque strings).
- Pagination uses `limit` + `offset` query parameters; responses include
a `meta: { total, limit, offset }` block.
- Rate limiting is applied per-IP or per-user on auth, ingest, export,
AI, and bug-report endpoints. Exceeding the budget yields a `429`.
## Admin endpoints
Routes under `/api/admin/*` are tagged `Admin` and are intended for the
internal admin UI only. iOS clients should not consume them.
contact:
name: HealthLog
url: https://healthlog.bombeck.io
license:
name: MIT
url: https://github.com/MBombeck/healthlog/blob/main/LICENSE
servers:
- url: https://healthlog.bombeck.io
description: Production
- url: http://localhost:3000
description: Local development
tags:
- name: Auth
description: Registration, login (password + passkey/WebAuthn), logout, session info, profile, password change.
- name: Measurements
description: CRUD for measurements (weight, BP, pulse, body fat, glucose, sleep, steps).
- name: Medications
description: Medication management, schedules, intake events, compliance, reminder phase config.
- name: Mood
description: Mood entries (manual + moodLog imports) and mood analytics.
- name: Dashboard
description: User-customizable dashboard widget layout.
- name: Insights
description: AI-generated insights, classifications (BMI, BP, mood, etc.), per-metric status, target ranges.
- name: Achievements
description: Gamification achievements (streaks, milestones).
- name: DoctorReport
description: Aggregated health data for client-side PDF export.
- name: Integrations
description: Withings, moodLog, Codex (ChatGPT) OAuth integrations.
- name: User
description: User-level configuration (AI provider, threshold overrides).
- name: Tokens
description: User-issued API tokens for external ingest.
- name: Notifications
description: Notification channels and preferences (Telegram, ntfy, Web Push).
- name: Onboarding
description: First-run profile setup.
- name: Health
description: Service health probe.
- name: Settings
description: Per-user settings (account deletion, data wipe, integrations, notifications).
- name: Analytics
description: Aggregated analytics summaries.
- name: Export
description: User data export (CSV/JSON) and re-import.
- name: AuditLog
description: User-facing audit log of own activity.
- name: Feedback
description: User feedback submission and history.
- name: BugReport
description: User bug reports (creates a GitHub issue when configured).
- name: Monitoring
description: Public monitoring/error reporting endpoints (CSP, Glitchtip, Umami proxy).
- name: Webhooks
description: Inbound webhooks (Withings, moodLog, Telegram).
- name: Ingest
description: External ingest endpoints authenticated via Bearer token.
- name: Admin
description: Internal admin-only endpoints. Not consumed by the iOS client.
security:
- bearerAuth: []
- sessionCookie: []
paths:
# ─── Auth ────────────────────────────────────────────────────────
/api/auth/register:
post:
tags: [Auth]
summary: Register a new user (password)
operationId: registerUser
security: []
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/RegisterInput" }
responses:
"201":
description: Created
content:
application/json:
schema:
$ref: "#/components/schemas/RegisterResponseEnvelope"
"403": { $ref: "#/components/responses/Forbidden" }
"409": { $ref: "#/components/responses/Conflict" }
"422": { $ref: "#/components/responses/Unprocessable" }
"429": { $ref: "#/components/responses/RateLimited" }
"500": { $ref: "#/components/responses/ServerError" }
/api/auth/login:
post:
tags: [Auth]
summary: Login with email/username + password
operationId: loginUser
security: []
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/LoginInput" }
responses:
"200":
description: Authenticated
content:
application/json:
schema: { $ref: "#/components/schemas/LoginResponseEnvelope" }
"401": { $ref: "#/components/responses/Unauthorized" }
"422": { $ref: "#/components/responses/Unprocessable" }
"429": { $ref: "#/components/responses/RateLimited" }
"500": { $ref: "#/components/responses/ServerError" }
/api/auth/logout:
post:
tags: [Auth]
summary: Destroy current session
operationId: logoutUser
responses:
"200":
description: Logged out
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
loggedOut: { type: boolean }
"500": { $ref: "#/components/responses/ServerError" }
/api/auth/me:
get:
tags: [Auth]
summary: Get current authenticated user
operationId: getCurrentUser
responses:
"200":
description: Current user
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/CurrentUser" }
"401": { $ref: "#/components/responses/Unauthorized" }
"500": { $ref: "#/components/responses/ServerError" }
/api/auth/profile:
put:
tags: [Auth]
summary: Update profile (email, height, DOB, gender)
operationId: updateProfile
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/ProfileInput" }
responses:
"200":
description: Updated profile
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/User" }
"401": { $ref: "#/components/responses/Unauthorized" }
"409": { $ref: "#/components/responses/Conflict" }
"422": { $ref: "#/components/responses/Unprocessable" }
"500": { $ref: "#/components/responses/ServerError" }
/api/auth/password:
post:
tags: [Auth]
summary: Change password (invalidates other sessions)
operationId: changePassword
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/ChangePasswordInput" }
responses:
"200":
description: Password changed
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
changed: { type: boolean }
"400": { $ref: "#/components/responses/BadRequest" }
"401": { $ref: "#/components/responses/Unauthorized" }
"422": { $ref: "#/components/responses/Unprocessable" }
"429": { $ref: "#/components/responses/RateLimited" }
"500": { $ref: "#/components/responses/ServerError" }
/api/auth/registration-status:
get:
tags: [Auth]
summary: Whether public registration is enabled
operationId: getRegistrationStatus
security: []
responses:
"200":
description: Registration status
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
registrationEnabled: { type: boolean }
# ─── Passkeys (WebAuthn) ───────────────────────────────────────
/api/auth/passkey/register-options:
post:
tags: [Auth]
summary: Begin passkey registration — get WebAuthn options
operationId: getPasskeyRegisterOptions
responses:
"200":
description: WebAuthn registration options
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
{ $ref: "#/components/schemas/PasskeyRegisterOptions" }
"401": { $ref: "#/components/responses/Unauthorized" }
/api/auth/passkey/register-verify:
post:
tags: [Auth]
summary: Complete passkey registration — verify attestation
operationId: verifyPasskeyRegistration
requestBody:
required: true
content:
application/json:
schema:
{ $ref: "#/components/schemas/PasskeyVerifyRegistrationInput" }
responses:
"200":
description: Passkey registered
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
verified: { type: boolean }
"400": { $ref: "#/components/responses/BadRequest" }
"401": { $ref: "#/components/responses/Unauthorized" }
"422": { $ref: "#/components/responses/Unprocessable" }
/api/auth/passkey/login-options:
post:
tags: [Auth]
summary: Begin passkey login — get WebAuthn options
operationId: getPasskeyLoginOptions
security: []
responses:
"200":
description: WebAuthn authentication options
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/PasskeyLoginOptions" }
"429": { $ref: "#/components/responses/RateLimited" }
/api/auth/passkey/login-verify:
post:
tags: [Auth]
summary: Complete passkey login — verify assertion
operationId: verifyPasskeyLogin
security: []
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/PasskeyVerifyLoginInput" }
responses:
"200":
description: Authenticated via passkey
content:
application/json:
schema: { $ref: "#/components/schemas/LoginResponseEnvelope" }
"401": { $ref: "#/components/responses/Unauthorized" }
"404": { $ref: "#/components/responses/NotFound" }
"422": { $ref: "#/components/responses/Unprocessable" }
"429": { $ref: "#/components/responses/RateLimited" }
/api/auth/passkeys:
get:
tags: [Auth]
summary: List the user's passkeys
operationId: listPasskeys
responses:
"200":
description: List of passkeys
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: array
items: { $ref: "#/components/schemas/PasskeySummary" }
"401": { $ref: "#/components/responses/Unauthorized" }
/api/auth/passkeys/{id}:
delete:
tags: [Auth]
summary: Delete a passkey
operationId: deletePasskey
parameters:
- $ref: "#/components/parameters/IdPathParam"
responses:
"200":
description: Deleted
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
success: { type: boolean }
"400": { $ref: "#/components/responses/BadRequest" }
"401": { $ref: "#/components/responses/Unauthorized" }
"404": { $ref: "#/components/responses/NotFound" }
# ─── Codex (ChatGPT) OAuth ────────────────────────────────────
/api/auth/codex/authorize:
get:
tags: [Integrations]
summary: Begin ChatGPT OAuth flow (redirects to ChatGPT)
operationId: codexAuthorize
responses:
"302":
description: Redirect to ChatGPT auth URL
"401": { $ref: "#/components/responses/Unauthorized" }
"429": { $ref: "#/components/responses/RateLimited" }
/api/auth/codex/callback:
get:
tags: [Integrations]
summary: ChatGPT OAuth callback — exchange code for tokens
operationId: codexCallback
parameters:
- in: query
name: code
schema: { type: string }
- in: query
name: state
schema: { type: string }
- in: query
name: error
schema: { type: string }
responses:
"302":
description: Redirect back to /settings with status
"401": { $ref: "#/components/responses/Unauthorized" }
/api/auth/codex/disconnect:
delete:
tags: [Integrations]
summary: Disconnect ChatGPT integration
operationId: codexDisconnect
responses:
"200":
description: Disconnected
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
disconnected: { type: boolean }
"401": { $ref: "#/components/responses/Unauthorized" }
"429": { $ref: "#/components/responses/RateLimited" }
# ─── Measurements ────────────────────────────────────────────────
/api/measurements:
get:
tags: [Measurements]
summary: List measurements (paginated, filterable)
operationId: listMeasurements
parameters:
- in: query
name: type
schema: { $ref: "#/components/schemas/MeasurementType" }
- in: query
name: from
schema: { type: string, format: date-time }
- in: query
name: to
schema: { type: string, format: date-time }
- $ref: "#/components/parameters/LimitParam"
- $ref: "#/components/parameters/OffsetParam"
- in: query
name: sortBy
schema:
type: string
enum: [type, value, measuredAt, source]
default: measuredAt
- in: query
name: sortDir
schema:
type: string
enum: [asc, desc]
default: desc
responses:
"200":
description: List of measurements
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
measurements:
type: array
items: { $ref: "#/components/schemas/Measurement" }
meta: { $ref: "#/components/schemas/PageMeta" }
"401": { $ref: "#/components/responses/Unauthorized" }
"422": { $ref: "#/components/responses/Unprocessable" }
"500": { $ref: "#/components/responses/ServerError" }
post:
tags: [Measurements]
summary: Create a measurement (single or batch)
operationId: createMeasurement
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/CreateMeasurementInput"
- type: array
items: { $ref: "#/components/schemas/CreateMeasurementInput" }
minItems: 1
maxItems: 5
responses:
"201":
description: Created
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
oneOf:
- $ref: "#/components/schemas/Measurement"
- type: array
items: { $ref: "#/components/schemas/Measurement" }
"401": { $ref: "#/components/responses/Unauthorized" }
"409": { $ref: "#/components/responses/Conflict" }
"422": { $ref: "#/components/responses/Unprocessable" }
"500": { $ref: "#/components/responses/ServerError" }
/api/measurements/{id}:
parameters:
- $ref: "#/components/parameters/IdPathParam"
get:
tags: [Measurements]
summary: Get a single measurement
operationId: getMeasurement
responses:
"200":
description: Measurement
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/Measurement" }
"401": { $ref: "#/components/responses/Unauthorized" }
"404": { $ref: "#/components/responses/NotFound" }
put:
tags: [Measurements]
summary: Update a measurement
operationId: updateMeasurement
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/UpdateMeasurementInput" }
responses:
"200":
description: Updated
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/Measurement" }
"401": { $ref: "#/components/responses/Unauthorized" }
"404": { $ref: "#/components/responses/NotFound" }
"422": { $ref: "#/components/responses/Unprocessable" }
delete:
tags: [Measurements]
summary: Delete a measurement
operationId: deleteMeasurement
responses:
"200":
description: Deleted
content:
application/json:
schema: { $ref: "#/components/schemas/DeletedEnvelope" }
"401": { $ref: "#/components/responses/Unauthorized" }
"404": { $ref: "#/components/responses/NotFound" }
# ─── Medications ─────────────────────────────────────────────────
/api/medications:
get:
tags: [Medications]
summary: List medications (with today's intake summary)
operationId: listMedications
responses:
"200":
description: List
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: array
items:
{
$ref: "#/components/schemas/MedicationWithSchedules",
}
"401": { $ref: "#/components/responses/Unauthorized" }
post:
tags: [Medications]
summary: Create a medication with schedules
operationId: createMedication
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/CreateMedicationInput" }
responses:
"201":
description: Created
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
{ $ref: "#/components/schemas/MedicationWithSchedules" }
"401": { $ref: "#/components/responses/Unauthorized" }
"422": { $ref: "#/components/responses/Unprocessable" }
/api/medications/{id}:
parameters:
- $ref: "#/components/parameters/IdPathParam"
get:
tags: [Medications]
summary: Get a single medication
operationId: getMedication
responses:
"200":
description: Medication
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
{ $ref: "#/components/schemas/MedicationWithSchedules" }
"401": { $ref: "#/components/responses/Unauthorized" }
"404": { $ref: "#/components/responses/NotFound" }
put:
tags: [Medications]
summary: Update a medication
operationId: updateMedication
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/UpdateMedicationInput" }
responses:
"200":
description: Updated
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
{ $ref: "#/components/schemas/MedicationWithSchedules" }
"401": { $ref: "#/components/responses/Unauthorized" }
"404": { $ref: "#/components/responses/NotFound" }
"422": { $ref: "#/components/responses/Unprocessable" }
delete:
tags: [Medications]
summary: Delete a medication (revokes its API tokens)
operationId: deleteMedication
responses:
"200":
description: Deleted
content:
application/json:
schema: { $ref: "#/components/schemas/DeletedEnvelope" }
"401": { $ref: "#/components/responses/Unauthorized" }
"404": { $ref: "#/components/responses/NotFound" }
/api/medications/{id}/intake:
parameters:
- $ref: "#/components/parameters/IdPathParam"
get:
tags: [Medications]
summary: List intake events for a medication
operationId: listMedicationIntakes
parameters:
- $ref: "#/components/parameters/LimitParam"
- $ref: "#/components/parameters/OffsetParam"
- in: query
name: sortBy
schema:
type: string
enum: [scheduledFor, takenAt, source, createdAt]
default: scheduledFor
- in: query
name: sortDir
schema: { type: string, enum: [asc, desc], default: desc }
responses:
"200":
description: Events
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
events:
type: array
items:
{
$ref: "#/components/schemas/MedicationIntakeEvent",
}
meta: { $ref: "#/components/schemas/PageMeta" }
"401": { $ref: "#/components/responses/Unauthorized" }
"404": { $ref: "#/components/responses/NotFound" }
"422": { $ref: "#/components/responses/Unprocessable" }
post:
tags: [Medications]
summary: Log a medication intake or skip
operationId: createMedicationIntake
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/CreateIntakeInput" }
responses:
"200":
description: Idempotent return of existing event
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
{ $ref: "#/components/schemas/MedicationIntakeEvent" }
"201":
description: Created
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
{ $ref: "#/components/schemas/MedicationIntakeEvent" }
"401": { $ref: "#/components/responses/Unauthorized" }
"404": { $ref: "#/components/responses/NotFound" }
"422": { $ref: "#/components/responses/Unprocessable" }
/api/medications/{id}/intake/{eventId}:
parameters:
- $ref: "#/components/parameters/IdPathParam"
- in: path
name: eventId
required: true
schema: { type: string }
put:
tags: [Medications]
summary: Update an intake event
operationId: updateMedicationIntake
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/UpdateIntakeInput" }
responses:
"200":
description: Updated
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
{ $ref: "#/components/schemas/MedicationIntakeEvent" }
"401": { $ref: "#/components/responses/Unauthorized" }
"404": { $ref: "#/components/responses/NotFound" }
"422": { $ref: "#/components/responses/Unprocessable" }
delete:
tags: [Medications]
summary: Delete an intake event
operationId: deleteMedicationIntake
responses:
"200":
description: Deleted
content:
application/json:
schema: { $ref: "#/components/schemas/DeletedEnvelope" }
"401": { $ref: "#/components/responses/Unauthorized" }
"404": { $ref: "#/components/responses/NotFound" }
/api/medications/{id}/intake/import:
parameters:
- $ref: "#/components/parameters/IdPathParam"
post:
tags: [Medications]
summary: Bulk-import historical intakes for one medication
operationId: importMedicationIntakes
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- type: array
items: { $ref: "#/components/schemas/IntakeImportEntry" }
minItems: 1
maxItems: 1000
- type: object
description: Object whose first array-valued property is treated as the entries.
additionalProperties: true
responses:
"201":
description: Import result
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/IntakeImportResult" }
"401": { $ref: "#/components/responses/Unauthorized" }
"404": { $ref: "#/components/responses/NotFound" }
"422": { $ref: "#/components/responses/Unprocessable" }
/api/medications/{id}/intake/purge:
parameters:
- $ref: "#/components/parameters/IdPathParam"
delete:
tags: [Medications]
summary: Delete ALL intake events for a medication
operationId: purgeMedicationIntakes
responses:
"200":
description: Purged
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
purged: { type: boolean }
count: { type: integer }
"401": { $ref: "#/components/responses/Unauthorized" }
"404": { $ref: "#/components/responses/NotFound" }
/api/medications/{id}/compliance:
parameters:
- $ref: "#/components/parameters/IdPathParam"
get:
tags: [Medications]
summary: Compliance summary for a medication (7d, 30d, 90 daily)
operationId: getMedicationCompliance
responses:
"200":
description: Compliance
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
{
$ref: "#/components/schemas/MedicationComplianceResponse",
}
"401": { $ref: "#/components/responses/Unauthorized" }
"404": { $ref: "#/components/responses/NotFound" }
/api/medications/{id}/phase-config:
parameters:
- $ref: "#/components/parameters/IdPathParam"
get:
tags: [Medications]
summary: Get reminder-phase config (or defaults)
operationId: getPhaseConfig
responses:
"200":
description: Phase config
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/ReminderPhaseConfig" }
"401": { $ref: "#/components/responses/Unauthorized" }
"404": { $ref: "#/components/responses/NotFound" }
put:
tags: [Medications]
summary: Update reminder-phase config
operationId: updatePhaseConfig
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/ReminderPhaseConfig" }
responses:
"200":
description: Updated
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/ReminderPhaseConfig" }
"400": { $ref: "#/components/responses/BadRequest" }
"401": { $ref: "#/components/responses/Unauthorized" }
"404": { $ref: "#/components/responses/NotFound" }
delete:
tags: [Medications]
summary: Reset reminder-phase config to defaults
operationId: resetPhaseConfig
responses:
"200":
description: Reset
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
reset: { type: boolean }
"401": { $ref: "#/components/responses/Unauthorized" }
"404": { $ref: "#/components/responses/NotFound" }
/api/medications/{id}/api-endpoint:
parameters:
- $ref: "#/components/parameters/IdPathParam"
get:
tags: [Medications]
summary: Whether an external API token is enabled for this medication
operationId: getMedicationApiEndpoint
responses:
"200":
description: Status
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
enabled: { type: boolean }
activeTokenCount: { type: integer }
"401": { $ref: "#/components/responses/Unauthorized" }
"403": { $ref: "#/components/responses/Forbidden" }
"404": { $ref: "#/components/responses/NotFound" }
put:
tags: [Medications]
summary: Enable / disable a medication-scoped API token
operationId: setMedicationApiEndpoint
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
enabled: { type: boolean }
required: [enabled]
responses:
"200":
description: Existing token reused or revocation result
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
{
$ref: "#/components/schemas/MedicationApiEndpointResponse",
}
"201":
description: New medication-scoped token created
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
{
$ref: "#/components/schemas/MedicationApiEndpointResponse",
}
"401": { $ref: "#/components/responses/Unauthorized" }
"403": { $ref: "#/components/responses/Forbidden" }
"404": { $ref: "#/components/responses/NotFound" }
"422": { $ref: "#/components/responses/Unprocessable" }
/api/medications/intake-summary:
get:
tags: [Medications]
summary: Daily intake summary (for streak chart)
operationId: getIntakeSummary
parameters:
- in: query
name: from
schema: { type: string, format: date-time }
- in: query
name: to
schema: { type: string, format: date-time }
responses:
"200":
description: Summary
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
{ $ref: "#/components/schemas/IntakeSummaryResponse" }
"401": { $ref: "#/components/responses/Unauthorized" }
"422": { $ref: "#/components/responses/Unprocessable" }
# ─── Mood ─────────────────────────────────────────────────────
/api/mood-entries:
get:
tags: [Mood]
summary: List mood entries (paginated, filterable)
operationId: listMoodEntries
parameters:
- in: query
name: mood
schema: { $ref: "#/components/schemas/MoodLevel" }
- in: query
name: from
description: "YYYY-MM-DD lower bound (inclusive)."
schema: { type: string }
- in: query
name: to
description: "YYYY-MM-DD upper bound (inclusive)."
schema: { type: string }
- $ref: "#/components/parameters/LimitParam"
- $ref: "#/components/parameters/OffsetParam"
- in: query
name: sortBy
schema: { type: string, default: moodLoggedAt }
- in: query
name: sortDir
schema: { type: string, enum: [asc, desc], default: desc }
responses:
"200":
description: Mood entries
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
entries:
type: array
items: { $ref: "#/components/schemas/MoodEntry" }
meta: { $ref: "#/components/schemas/PageMeta" }
"401": { $ref: "#/components/responses/Unauthorized" }
"422": { $ref: "#/components/responses/Unprocessable" }
post:
tags: [Mood]
summary: Create a mood entry
operationId: createMoodEntry
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/CreateMoodEntryInput" }
responses:
"201":
description: Created
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/MoodEntry" }
"401": { $ref: "#/components/responses/Unauthorized" }
"409": { $ref: "#/components/responses/Conflict" }
"422": { $ref: "#/components/responses/Unprocessable" }
/api/mood-entries/{id}:
parameters:
- $ref: "#/components/parameters/IdPathParam"
get:
tags: [Mood]
summary: Get a mood entry
operationId: getMoodEntry
responses:
"200":
description: Mood entry
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/MoodEntry" }
"401": { $ref: "#/components/responses/Unauthorized" }
"404": { $ref: "#/components/responses/NotFound" }
put:
tags: [Mood]
summary: Update a mood entry
operationId: updateMoodEntry
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/UpdateMoodEntryInput" }
responses:
"200":
description: Updated
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/MoodEntry" }
"401": { $ref: "#/components/responses/Unauthorized" }
"404": { $ref: "#/components/responses/NotFound" }
"422": { $ref: "#/components/responses/Unprocessable" }
delete:
tags: [Mood]
summary: Delete a mood entry
operationId: deleteMoodEntry
responses:
"200":
description: Deleted
content:
application/json:
schema: { $ref: "#/components/schemas/DeletedEnvelope" }
"401": { $ref: "#/components/responses/Unauthorized" }
"404": { $ref: "#/components/responses/NotFound" }
/api/mood/analytics:
get:
tags: [Mood]
summary: Mood analytics (daily averages + summary)
operationId: getMoodAnalytics
responses:
"200":
description: Analytics
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/MoodAnalytics" }
"401": { $ref: "#/components/responses/Unauthorized" }
# ─── Dashboard ────────────────────────────────────────────────
/api/dashboard/widgets:
get:
tags: [Dashboard]
summary: Get the resolved dashboard widget layout
operationId: getDashboardWidgets
responses:
"200":
description: Layout
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/DashboardLayout" }
"401": { $ref: "#/components/responses/Unauthorized" }
put:
tags: [Dashboard]
summary: Replace the dashboard widget layout
operationId: updateDashboardWidgets
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/DashboardLayout" }
responses:
"200":
description: Updated
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/DashboardLayout" }
"401": { $ref: "#/components/responses/Unauthorized" }
"422": { $ref: "#/components/responses/Unprocessable" }
delete:
tags: [Dashboard]
summary: Reset dashboard layout to defaults
operationId: resetDashboardWidgets
responses:
"200":
description: Reset
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/DashboardLayout" }
"401": { $ref: "#/components/responses/Unauthorized" }
# ─── Insights ────────────────────────────────────────────────
/api/insights/comprehensive:
get:
tags: [Insights]
summary: Comprehensive 90-day analytics bundle
operationId: getComprehensiveInsights
responses:
"200":
description: Insights bundle
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
{ $ref: "#/components/schemas/ComprehensiveInsights" }
"401": { $ref: "#/components/responses/Unauthorized" }
/api/insights/generate:
post:
tags: [Insights]
summary: Generate AI-narrative insights (cached for 24h)
operationId: generateInsights
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
force: { type: boolean, description: "Bypass 24h cache" }
responses:
"200":
description: Insights
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
{ $ref: "#/components/schemas/InsightGenerateResult" }
"401": { $ref: "#/components/responses/Unauthorized" }
"422": { $ref: "#/components/responses/Unprocessable" }
"429": { $ref: "#/components/responses/RateLimited" }
"502":
description: Upstream AI provider failure
content:
application/json:
schema: { $ref: "#/components/schemas/ApiError" }
/api/insights/settings:
get:
tags: [Insights]
summary: Get insights settings (privacy mode, provider status)
operationId: getInsightsSettings
responses:
"200":
description: Settings
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/InsightsSettings" }
"401": { $ref: "#/components/responses/Unauthorized" }
put:
tags: [Insights]
summary: Update insights settings (privacy mode)
operationId: updateInsightsSettings
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
privacyMode: { type: string, enum: [aggregated, raw] }
responses:
"200":
description: Updated
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
updated: { type: boolean }
"401": { $ref: "#/components/responses/Unauthorized" }
"422": { $ref: "#/components/responses/Unprocessable" }
/api/insights/targets:
get:
tags: [Insights]
summary: Per-metric target ranges + classification
operationId: getInsightTargets
responses:
"200":
description: Targets
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
{ $ref: "#/components/schemas/InsightTargetsResponse" }
"401": { $ref: "#/components/responses/Unauthorized" }
/api/insights/blood-pressure-status:
get:
tags: [Insights]
summary: BP-specific narrative status
operationId: getBloodPressureStatus
parameters:
- $ref: "#/components/parameters/LocaleParam"
responses:
"200":
description: BP status
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/InsightStatusBundle" }
"401": { $ref: "#/components/responses/Unauthorized" }
/api/insights/bmi-status:
get:
tags: [Insights]
summary: BMI narrative status
operationId: getBmiStatus
parameters:
- $ref: "#/components/parameters/LocaleParam"
responses:
"200":
description: BMI status
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/InsightStatusBundle" }
"401": { $ref: "#/components/responses/Unauthorized" }
/api/insights/general-status:
get:
tags: [Insights]
summary: General health narrative status
operationId: getGeneralStatus
parameters:
- $ref: "#/components/parameters/LocaleParam"
responses:
"200":
description: Status
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/InsightStatusBundle" }
"401": { $ref: "#/components/responses/Unauthorized" }
/api/insights/medication-compliance-status:
get:
tags: [Insights]
summary: Medication compliance narrative status
operationId: getMedicationComplianceStatus
parameters:
- $ref: "#/components/parameters/LocaleParam"
responses:
"200":
description: Status
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/InsightStatusBundle" }
"401": { $ref: "#/components/responses/Unauthorized" }
/api/insights/mood-status:
get:
tags: [Insights]
summary: Mood narrative status
operationId: getMoodStatus
parameters:
- $ref: "#/components/parameters/LocaleParam"
responses:
"200":
description: Status
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/InsightStatusBundle" }
"401": { $ref: "#/components/responses/Unauthorized" }
/api/insights/pulse-status:
get:
tags: [Insights]
summary: Pulse narrative status
operationId: getPulseStatus
parameters:
- $ref: "#/components/parameters/LocaleParam"
responses:
"200":
description: Status
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/InsightStatusBundle" }
"401": { $ref: "#/components/responses/Unauthorized" }
/api/insights/weight-status:
get:
tags: [Insights]
summary: Weight narrative status
operationId: getWeightStatus
parameters:
- $ref: "#/components/parameters/LocaleParam"
responses:
"200":
description: Status
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/InsightStatusBundle" }
"401": { $ref: "#/components/responses/Unauthorized" }
# ─── Achievements ─────────────────────────────────────────────
/api/gamification/achievements:
get:
tags: [Achievements]
summary: Get achievements progress + unlocks
operationId: getAchievements
responses:
"200":
description: Achievements
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/AchievementsResult" }
"401": { $ref: "#/components/responses/Unauthorized" }
# ─── DoctorReport ─────────────────────────────────────────────
/api/doctor-report:
post:
tags: [DoctorReport]
summary: Aggregated health data for doctor-report PDF
operationId: getDoctorReport
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
days:
type: integer
minimum: 1
maximum: 365
default: 90
responses:
"200":
description: Report data
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
{ $ref: "#/components/schemas/DoctorReportResponse" }
"401": { $ref: "#/components/responses/Unauthorized" }
"429": { $ref: "#/components/responses/RateLimited" }
# ─── Onboarding ───────────────────────────────────────────────
/api/onboarding/complete:
post:
tags: [Onboarding]
summary: Mark onboarding complete and save initial profile
operationId: completeOnboarding
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/OnboardingInput" }
responses:
"200":
description: Completed
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
completed: { type: boolean }
"401": { $ref: "#/components/responses/Unauthorized" }
"422": { $ref: "#/components/responses/Unprocessable" }
# ─── Health probe ─────────────────────────────────────────────
/api/health:
get:
tags: [Health]
summary: Service liveness probe
operationId: healthCheck
security: []
responses:
"200":
description: Healthy
content:
application/json:
schema: { $ref: "#/components/schemas/HealthStatus" }
"503":
description: Degraded
content:
application/json:
schema: { $ref: "#/components/schemas/HealthStatus" }
# ─── Tokens ──────────────────────────────────────────────────
/api/tokens:
get:
tags: [Tokens]
summary: List the user's API tokens (metadata only — secrets never returned)
operationId: listTokens
responses:
"200":
description: Tokens
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: array
items: { $ref: "#/components/schemas/ApiTokenSummary" }
"401": { $ref: "#/components/responses/Unauthorized" }
"403": { $ref: "#/components/responses/Forbidden" }
post:
tags: [Tokens]
summary: Create an API token (token returned ONCE)
operationId: createToken
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/CreateTokenInput" }
responses:
"201":
description: Created (token visible once)
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
token: { type: string, example: "hlk_<hex>" }
name: { type: string }
"401": { $ref: "#/components/responses/Unauthorized" }
"403": { $ref: "#/components/responses/Forbidden" }
"422": { $ref: "#/components/responses/Unprocessable" }
/api/tokens/{id}:
parameters:
- $ref: "#/components/parameters/IdPathParam"
delete:
tags: [Tokens]
summary: Revoke an API token
operationId: revokeToken
responses:
"200":
description: Revoked
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
revoked: { type: boolean }
"401": { $ref: "#/components/responses/Unauthorized" }
"403": { $ref: "#/components/responses/Forbidden" }
"404": { $ref: "#/components/responses/NotFound" }
# ─── Ingest (external) ────────────────────────────────────────
/api/ingest/medication:
post:
tags: [Ingest]
summary: External medication intake ingest (Bearer token, idempotent)
operationId: ingestMedicationIntake
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/ExternalIntakeInput" }
responses:
"200":
description: Existing event returned (idempotent replay)
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
{ $ref: "#/components/schemas/MedicationIntakeEvent" }
"201":
description: Created
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
{ $ref: "#/components/schemas/MedicationIntakeEvent" }
"401": { $ref: "#/components/responses/Unauthorized" }
"403": { $ref: "#/components/responses/Forbidden" }
"404": { $ref: "#/components/responses/NotFound" }
"422": { $ref: "#/components/responses/Unprocessable" }
"429": { $ref: "#/components/responses/RateLimited" }
# ─── Notifications ────────────────────────────────────────────
/api/notifications/preferences:
get:
tags: [Notifications]
summary: List notification channels + preferences
operationId: getNotificationPreferences
responses:
"200":
description: Preferences
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
{
$ref: "#/components/schemas/NotificationPreferencesResponse",
}
"401": { $ref: "#/components/responses/Unauthorized" }
put:
tags: [Notifications]
summary: Toggle a single channel/event preference
operationId: updateNotificationPreference
requestBody:
required: true
content:
application/json:
schema:
{ $ref: "#/components/schemas/UpdateNotificationPreferenceInput" }
responses:
"200":
description: Updated
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
{ $ref: "#/components/schemas/NotificationPreference" }
"401": { $ref: "#/components/responses/Unauthorized" }
"404": { $ref: "#/components/responses/NotFound" }
"422": { $ref: "#/components/responses/Unprocessable" }
/api/notifications/vapid:
get:
tags: [Notifications]
summary: Get VAPID public key (Web Push)
operationId: getVapidKey
security: []
responses:
"200":
description: VAPID key
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
publicKey: { type: string }
"503":
description: Not configured
content:
application/json:
schema: { $ref: "#/components/schemas/ApiError" }
/api/notifications/web-push:
post:
tags: [Notifications]
summary: Subscribe a Web Push endpoint
operationId: subscribeWebPush
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/WebPushSubscribeInput" }
responses:
"200":
description: Subscribed
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
subscribed: { type: boolean }
"401": { $ref: "#/components/responses/Unauthorized" }
"422": { $ref: "#/components/responses/Unprocessable" }
delete:
tags: [Notifications]
summary: Unsubscribe a Web Push endpoint
operationId: unsubscribeWebPush
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
endpoint: { type: string, format: uri }
required: [endpoint]
responses:
"200":
description: Unsubscribed
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
unsubscribed: { type: boolean }
"401": { $ref: "#/components/responses/Unauthorized" }
"422": { $ref: "#/components/responses/Unprocessable" }
# ─── User configuration ───────────────────────────────────────
/api/user/ai-provider:
get:
tags: [User]
summary: Get user-level AI provider config
operationId: getUserAiProvider
responses:
"200":
description: Config
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/UserAiProvider" }
"401": { $ref: "#/components/responses/Unauthorized" }
patch:
tags: [User]
summary: Update user-level AI provider config
operationId: updateUserAiProvider
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/UpdateUserAiProviderInput" }
responses:
"200":
description: Updated
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
updated: { type: boolean }
"401": { $ref: "#/components/responses/Unauthorized" }
"422": { $ref: "#/components/responses/Unprocessable" }
/api/user/thresholds:
get:
tags: [User]
summary: Get effective + override threshold ranges
operationId: getThresholds
responses:
"200":
description: Thresholds
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/ThresholdsResponse" }
"401": { $ref: "#/components/responses/Unauthorized" }
"404": { $ref: "#/components/responses/NotFound" }
put:
tags: [User]
summary: Set per-metric threshold overrides (partial)
operationId: updateThresholds
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/ThresholdOverrides" }
responses:
"200":
description: Updated
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
overrides:
{ $ref: "#/components/schemas/ThresholdOverrides" }
"401": { $ref: "#/components/responses/Unauthorized" }
"422": { $ref: "#/components/responses/Unprocessable" }
delete:
tags: [User]
summary: Reset threshold overrides (all or one metric)
operationId: resetThresholds
parameters:
- in: query
name: metric
schema: { type: string }
description: "If supplied, only this metric is reset; otherwise all overrides are cleared."
responses:
"200":
description: Reset
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
overrides:
{ $ref: "#/components/schemas/ThresholdOverrides" }
"400": { $ref: "#/components/responses/BadRequest" }
"401": { $ref: "#/components/responses/Unauthorized" }
# ─── Analytics + AI test ──────────────────────────────────────
/api/analytics:
get:
tags: [Analytics]
summary: Per-type measurement summaries + BMI + BP-in-target
operationId: getAnalytics
responses:
"200":
description: Analytics
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/AnalyticsResponse" }
"401": { $ref: "#/components/responses/Unauthorized" }
/api/ai/test:
post:
tags: [User]
summary: Test the configured AI provider
operationId: testAiProvider
responses:
"200":
description: AI test result
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/AiTestResult" }
"401": { $ref: "#/components/responses/Unauthorized" }
"422": { $ref: "#/components/responses/Unprocessable" }
"429": { $ref: "#/components/responses/RateLimited" }
"502":
description: Upstream AI provider failure
content:
application/json:
schema: { $ref: "#/components/schemas/ApiError" }
# ─── Export / Import ──────────────────────────────────────────
/api/export:
get:
tags: [Export]
summary: Export user data (CSV or JSON)
operationId: exportData
parameters:
- in: query
name: format
schema: { type: string, enum: [csv, json], default: json }
- in: query
name: type
schema:
type: string
enum: [measurements, medications, intake, mood, all]
default: all
responses:
"200":
description: Export payload
content:
application/json:
schema:
type: object
properties:
data:
type: object
additionalProperties: true
text/csv:
schema: { type: string }
"401": { $ref: "#/components/responses/Unauthorized" }
"422": { $ref: "#/components/responses/Unprocessable" }
"429": { $ref: "#/components/responses/RateLimited" }
/api/import:
post:
tags: [Export]
summary: Import previously exported data (JSON)
operationId: importData
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/ImportInput" }
responses:
"200":
description: Import stats
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/ImportResult" }
"401": { $ref: "#/components/responses/Unauthorized" }
"422": { $ref: "#/components/responses/Unprocessable" }
# ─── Audit log + Feedback + Bug report ────────────────────────
/api/audit-log:
get:
tags: [AuditLog]
summary: Personal audit log entries
operationId: getAuditLog
parameters:
- $ref: "#/components/parameters/LimitParam"
- $ref: "#/components/parameters/OffsetParam"
responses:
"200":
description: Entries
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/AuditLogResponse" }
"401": { $ref: "#/components/responses/Unauthorized" }
/api/feedback:
get:
tags: [Feedback]
summary: List the user's submitted feedback
operationId: listFeedback
parameters:
- $ref: "#/components/parameters/LimitParam"
- $ref: "#/components/parameters/OffsetParam"
responses:
"200":
description: Feedback
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
items:
type: array
items:
{ $ref: "#/components/schemas/FeedbackSummary" }
meta: { $ref: "#/components/schemas/PageMeta" }
"401": { $ref: "#/components/responses/Unauthorized" }
post:
tags: [Feedback]
summary: Submit feedback (with optional screenshot)
operationId: submitFeedback
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/CreateFeedbackInput" }
responses:
"201":
description: Created
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/FeedbackSummary" }
"401": { $ref: "#/components/responses/Unauthorized" }
"422": { $ref: "#/components/responses/Unprocessable" }
"429": { $ref: "#/components/responses/RateLimited" }
/api/bugreport:
post:
tags: [BugReport]
summary: File a bug report (creates a GitHub issue when configured)
operationId: submitBugReport
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/BugReportInput" }
responses:
"200":
description: Issue created
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
issueNumber: { type: integer }
issueUrl: { type: string, format: uri }
"401": { $ref: "#/components/responses/Unauthorized" }
"422": { $ref: "#/components/responses/Unprocessable" }
"429": { $ref: "#/components/responses/RateLimited" }
"500": { $ref: "#/components/responses/ServerError" }
"503":
description: Bug report not configured
content:
application/json:
schema: { $ref: "#/components/schemas/ApiError" }
/api/bugreport/status:
get:
tags: [BugReport]
summary: Whether bug-report submission is configured
operationId: getBugReportStatus
responses:
"200":
description: Status
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
configured: { type: boolean }
isAdmin: { type: boolean }
"401": { $ref: "#/components/responses/Unauthorized" }
"429": { $ref: "#/components/responses/RateLimited" }
# ─── Settings (per-user) ──────────────────────────────────────
/api/settings/account:
delete:
tags: [Settings]
summary: Delete the user's account (and all data)
operationId: deleteAccount
responses:
"200":
description: Account deleted
content:
application/json:
schema: { $ref: "#/components/schemas/DeletedEnvelope" }
"401": { $ref: "#/components/responses/Unauthorized" }
/api/settings/data:
delete:
tags: [Settings]
summary: Wipe the user's data (keep account)
operationId: wipeData
responses:
"200":
description: Data wiped
content:
application/json:
schema: { $ref: "#/components/schemas/DeletedEnvelope" }
"401": { $ref: "#/components/responses/Unauthorized" }
/api/settings/global-services:
get:
tags: [Settings]
summary: Global service availability flags (telegram, ntfy, web-push, …)
operationId: getGlobalServices
responses:
"200":
description: Flags
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/GlobalServicesFlags" }
"401": { $ref: "#/components/responses/Unauthorized" }
/api/settings/moodlog:
put:
tags: [Settings]
summary: Configure moodLog integration
operationId: updateMoodLogSettings
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/MoodLogSettingsInput" }
responses:
"200":
description: Updated
content:
application/json:
schema: { $ref: "#/components/schemas/UpdatedEnvelope" }
"401": { $ref: "#/components/responses/Unauthorized" }
"422": { $ref: "#/components/responses/Unprocessable" }
delete:
tags: [Settings]
summary: Disconnect moodLog integration
operationId: deleteMoodLogSettings
responses:
"200":
description: Removed
content:
application/json:
schema: { $ref: "#/components/schemas/DeletedEnvelope" }
"401": { $ref: "#/components/responses/Unauthorized" }
/api/settings/ntfy:
get:
tags: [Settings]
summary: Get ntfy channel settings
operationId: getNtfySettings
responses:
"200":
description: Config
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/NtfySettings" }
"401": { $ref: "#/components/responses/Unauthorized" }
put:
tags: [Settings]
summary: Update ntfy channel settings
operationId: updateNtfySettings
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/NtfySettingsInput" }
responses:
"200":
description: Updated
content:
application/json:
schema: { $ref: "#/components/schemas/UpdatedEnvelope" }
"401": { $ref: "#/components/responses/Unauthorized" }
"422": { $ref: "#/components/responses/Unprocessable" }
/api/settings/ntfy/test:
post:
tags: [Settings]
summary: Send a test ntfy notification
operationId: testNtfy
responses:
"200":
description: Test result
content:
application/json:
schema: { $ref: "#/components/schemas/ApiEnvelope" }
"401": { $ref: "#/components/responses/Unauthorized" }
/api/settings/reminder-thresholds:
get:
tags: [Settings]
summary: Get reminder lateness thresholds (admin-defined defaults)
operationId: getReminderThresholds
responses:
"200":
description: Thresholds
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/ReminderThresholds" }
"401": { $ref: "#/components/responses/Unauthorized" }
/api/settings/telegram:
get:
tags: [Settings]
summary: Get Telegram channel settings
operationId: getTelegramSettings
responses:
"200":
description: Config
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/TelegramSettings" }
"401": { $ref: "#/components/responses/Unauthorized" }
put:
tags: [Settings]
summary: Update Telegram channel settings
operationId: updateTelegramSettings
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/TelegramSettingsInput" }
responses:
"200":
description: Updated
content:
application/json:
schema: { $ref: "#/components/schemas/UpdatedEnvelope" }
"401": { $ref: "#/components/responses/Unauthorized" }
"422": { $ref: "#/components/responses/Unprocessable" }
/api/settings/telegram/test:
post:
tags: [Settings]
summary: Send a test Telegram message
operationId: testTelegram
responses:
"200":
description: Test result
content:
application/json:
schema: { $ref: "#/components/schemas/ApiEnvelope" }
"401": { $ref: "#/components/responses/Unauthorized" }
# ─── Withings integration ────────────────────────────────────
/api/withings/connect:
get:
tags: [Integrations]
summary: Begin Withings OAuth (302 redirect)
operationId: withingsConnect
responses:
"302":
description: Redirect to Withings
"400": { $ref: "#/components/responses/BadRequest" }
"401": { $ref: "#/components/responses/Unauthorized" }
/api/withings/callback:
get:
tags: [Integrations]
summary: Withings OAuth callback (302 to /settings)
operationId: withingsCallback
parameters:
- in: query
name: code
schema: { type: string }
- in: query
name: state
schema: { type: string }
responses:
"302":
description: Redirect back to /settings with status
/api/withings/disconnect:
post:
tags: [Integrations]
summary: Disconnect Withings
operationId: withingsDisconnect
responses:
"200":
description: Disconnected
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
disconnected: { type: boolean }
"401": { $ref: "#/components/responses/Unauthorized" }
"404": { $ref: "#/components/responses/NotFound" }
/api/withings/credentials:
get:
tags: [Integrations]
summary: Whether Withings client credentials are stored
operationId: getWithingsCredentialsStatus
responses:
"200":
description: Status
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
hasCredentials: { type: boolean }
"401": { $ref: "#/components/responses/Unauthorized" }
put:
tags: [Integrations]
summary: Save Withings client ID + secret (encrypted)
operationId: saveWithingsCredentials
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/WithingsCredentialsInput" }
responses:
"200":
description: Saved
content:
application/json:
schema: { $ref: "#/components/schemas/UpdatedEnvelope" }
"401": { $ref: "#/components/responses/Unauthorized" }
"422": { $ref: "#/components/responses/Unprocessable" }
delete:
tags: [Integrations]
summary: Delete Withings credentials (and disconnect)
operationId: deleteWithingsCredentials
responses:
"200":
description: Deleted
content:
application/json:
schema: { $ref: "#/components/schemas/DeletedEnvelope" }
"401": { $ref: "#/components/responses/Unauthorized" }
/api/withings/status:
get:
tags: [Integrations]
summary: Withings connection status
operationId: withingsStatus
responses:
"200":
description: Status
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/WithingsStatus" }
"401": { $ref: "#/components/responses/Unauthorized" }
/api/withings/sync:
post:
tags: [Integrations]
summary: Trigger a Withings sync (incremental or full)
operationId: withingsSync
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
fullSync: { type: boolean, default: false }
responses:
"200":
description: Sync result
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
imported: { type: integer }
fullSync: { type: boolean }
"401": { $ref: "#/components/responses/Unauthorized" }
/api/withings/webhook:
post:
tags: [Webhooks]
summary: Withings webhook (notification of new measurements)
operationId: withingsWebhook
security: []
parameters:
- in: query
name: secret
schema: { type: string }
description: "Shared secret for webhook authentication."
responses:
"200":
description: Acknowledged
content:
application/json:
schema:
type: object
properties:
status: { type: string }
"401":
description: Unauthorized
"429":
description: Rate limited
get:
tags: [Webhooks]
summary: Withings webhook URL verification
operationId: withingsWebhookVerifyGet
security: []
parameters:
- in: query
name: secret
schema: { type: string }
responses:
"200":
description: OK
content:
application/json:
schema:
type: object
properties:
status: { type: string }
"401":
description: Unauthorized
head:
tags: [Webhooks]
summary: Withings webhook URL verification (HEAD)
operationId: withingsWebhookVerifyHead
security: []
parameters:
- in: query
name: secret
schema: { type: string }
responses:
"200":
description: OK
"401":
description: Unauthorized
# ─── moodLog integration ─────────────────────────────────────
/api/integrations/moodlog/status:
get:
tags: [Integrations]
summary: moodLog connection status
operationId: moodLogStatus
responses:
"200":
description: Status
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/MoodLogStatus" }
"401": { $ref: "#/components/responses/Unauthorized" }
/api/integrations/moodlog/sync:
post:
tags: [Integrations]
summary: Trigger a moodLog sync
operationId: moodLogSync
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
fullSync: { type: boolean, default: false }
responses:
"200":
description: Sync result
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
imported: { type: integer }
"401": { $ref: "#/components/responses/Unauthorized" }
"403": { $ref: "#/components/responses/Forbidden" }
/api/integrations/moodlog/webhook:
post:
tags: [Webhooks]
summary: Inbound webhook from moodLog
operationId: moodLogWebhook
security: []
parameters:
- in: header
name: X-Webhook-Secret
required: true
schema: { type: string }
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
"200":
description: Acknowledged
"400": { $ref: "#/components/responses/BadRequest" }
"401": { $ref: "#/components/responses/Unauthorized" }
"403": { $ref: "#/components/responses/Forbidden" }
"429": { $ref: "#/components/responses/RateLimited" }
/api/telegram/webhook:
post:
tags: [Webhooks]
summary: Telegram inbound webhook
operationId: telegramWebhook
security: []
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
"200":
description: Acknowledged
get:
tags: [Webhooks]
summary: Telegram webhook health probe
operationId: telegramWebhookGet
security: []
responses:
"200":
description: OK
# ─── Public monitoring / proxies ─────────────────────────────
/api/monitoring/csp-report:
post:
tags: [Monitoring]
summary: Browser CSP violation report sink
operationId: cspReport
security: []
requestBody:
required: true
content:
application/csp-report:
schema:
type: object
additionalProperties: true
application/json:
schema:
type: object
additionalProperties: true
responses:
"204":
description: Accepted (no body)
/api/monitoring/glitchtip:
post:
tags: [Monitoring]
summary: Forward errors to Glitchtip
operationId: glitchtipReport
security: []
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
"204":
description: Accepted
/api/monitoring/settings:
get:
tags: [Monitoring]
summary: Public monitoring settings (umami / glitchtip flags)
operationId: getMonitoringSettings
security: []
responses:
"200":
description: Public settings
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
{
$ref: "#/components/schemas/PublicMonitoringSettings",
}
/api/monitoring/umami-script:
get:
tags: [Monitoring]
summary: Server-side proxy for the Umami tracker script
operationId: getUmamiScript
security: []
responses:
"200":
description: Tracker script
content:
application/javascript:
schema: { type: string }
/api/send:
post:
tags: [Monitoring]
summary: Server-side proxy for Umami /api/send
operationId: umamiProxySend
security: []
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
"200":
description: Forwarded
"204":
description: No-op when umami is disabled
"413":
description: Payload too large
# ─── Admin (internal) ────────────────────────────────────────
/api/admin/ai-settings:
get:
tags: [Admin]
security:
- sessionCookie: []
summary: "Internal: get admin-managed AI fallback settings"
operationId: adminGetAiSettings
responses:
"200":
{
description: OK,
content:
{
application/json:
{ schema: { $ref: "#/components/schemas/ApiEnvelope" } },
},
}
"401": { $ref: "#/components/responses/Unauthorized" }
"403": { $ref: "#/components/responses/Forbidden" }
put:
tags: [Admin]
security:
- sessionCookie: []
summary: "Internal: update admin-managed AI fallback settings"
operationId: adminUpdateAiSettings
requestBody:
required: true
content:
application/json:
schema: { type: object, additionalProperties: true }
responses:
"200":
{
description: OK,
content:
{
application/json:
{ schema: { $ref: "#/components/schemas/ApiEnvelope" } },
},
}
"401": { $ref: "#/components/responses/Unauthorized" }
"403": { $ref: "#/components/responses/Forbidden" }
"422": { $ref: "#/components/responses/Unprocessable" }
/api/admin/audit-log:
get:
tags: [Admin]
security:
- sessionCookie: []
summary: "Internal: cross-user audit log"
operationId: adminGetAuditLog
parameters:
- $ref: "#/components/parameters/LimitParam"
- $ref: "#/components/parameters/OffsetParam"
responses:
"200":
{
description: OK,
content:
{
application/json:
{ schema: { $ref: "#/components/schemas/ApiEnvelope" } },
},
}
"401": { $ref: "#/components/responses/Unauthorized" }
"403": { $ref: "#/components/responses/Forbidden" }
/api/admin/data:
delete:
tags: [Admin]
security:
- sessionCookie: []
summary: "Internal: wipe per-user or all data"
operationId: adminWipeData
responses:
"200":
{
description: OK,
content:
{
application/json:
{ schema: { $ref: "#/components/schemas/ApiEnvelope" } },
},
}
"401": { $ref: "#/components/responses/Unauthorized" }
"403": { $ref: "#/components/responses/Forbidden" }
/api/admin/feedback:
get:
tags: [Admin]
security:
- sessionCookie: []
summary: "Internal: list all feedback"
operationId: adminListFeedback
parameters:
- $ref: "#/components/parameters/LimitParam"
- $ref: "#/components/parameters/OffsetParam"
responses:
"200":
{
description: OK,
content:
{
application/json:
{ schema: { $ref: "#/components/schemas/ApiEnvelope" } },
},
}
"401": { $ref: "#/components/responses/Unauthorized" }
"403": { $ref: "#/components/responses/Forbidden" }
/api/admin/feedback/{id}:
parameters:
- $ref: "#/components/parameters/IdPathParam"
patch:
tags: [Admin]
security:
- sessionCookie: []
summary: "Internal: update feedback status / admin note"
operationId: adminUpdateFeedback
requestBody:
required: true
content:
application/json:
schema: { type: object, additionalProperties: true }
responses:
"200":
{
description: OK,
content:
{
application/json:
{ schema: { $ref: "#/components/schemas/ApiEnvelope" } },
},
}
"401": { $ref: "#/components/responses/Unauthorized" }
"403": { $ref: "#/components/responses/Forbidden" }
"404": { $ref: "#/components/responses/NotFound" }
delete:
tags: [Admin]
security:
- sessionCookie: []
summary: "Internal: delete feedback"
operationId: adminDeleteFeedback
responses:
"200":
{
description: OK,
content:
{
application/json:
{ schema: { $ref: "#/components/schemas/ApiEnvelope" } },
},
}
"401": { $ref: "#/components/responses/Unauthorized" }
"403": { $ref: "#/components/responses/Forbidden" }
"404": { $ref: "#/components/responses/NotFound" }
/api/admin/feedback/{id}/github:
parameters:
- $ref: "#/components/parameters/IdPathParam"
post:
tags: [Admin]
security:
- sessionCookie: []
summary: "Internal: escalate feedback to a GitHub issue"
operationId: adminEscalateFeedback
responses:
"200":
{
description: OK,
content:
{
application/json:
{ schema: { $ref: "#/components/schemas/ApiEnvelope" } },
},
}
"401": { $ref: "#/components/responses/Unauthorized" }
"403": { $ref: "#/components/responses/Forbidden" }
"404": { $ref: "#/components/responses/NotFound" }
/api/admin/monitoring/glitchtip-test:
post:
tags: [Admin]
security:
- sessionCookie: []
summary: "Internal: send Glitchtip test event"
operationId: adminGlitchtipTest
responses:
"200":
{
description: OK,
content:
{
application/json:
{ schema: { $ref: "#/components/schemas/ApiEnvelope" } },
},
}
"401": { $ref: "#/components/responses/Unauthorized" }
"403": { $ref: "#/components/responses/Forbidden" }
/api/admin/monitoring/umami-test:
post:
tags: [Admin]
security:
- sessionCookie: []
summary: "Internal: send Umami test ping"
operationId: adminUmamiTest
responses:
"200":
{
description: OK,
content:
{
application/json:
{ schema: { $ref: "#/components/schemas/ApiEnvelope" } },
},
}
"401": { $ref: "#/components/responses/Unauthorized" }
"403": { $ref: "#/components/responses/Forbidden" }
/api/admin/notifications/reminder-check:
post:
tags: [Admin]
security:
- sessionCookie: []
summary: "Internal: trigger medication reminder evaluation"
operationId: adminTriggerReminderCheck
responses:
"200":
{
description: OK,
content:
{
application/json:
{ schema: { $ref: "#/components/schemas/ApiEnvelope" } },
},
}
"401": { $ref: "#/components/responses/Unauthorized" }
"403": { $ref: "#/components/responses/Forbidden" }
/api/admin/notifications/test:
post:
tags: [Admin]
security:
- sessionCookie: []
summary: "Internal: send a test notification"
operationId: adminTestNotification
responses:
"200":
{
description: OK,
content:
{
application/json:
{ schema: { $ref: "#/components/schemas/ApiEnvelope" } },
},
}
"401": { $ref: "#/components/responses/Unauthorized" }
"403": { $ref: "#/components/responses/Forbidden" }
/api/admin/settings:
get:
tags: [Admin]
security:
- sessionCookie: []
summary: "Internal: get app-wide settings"
operationId: adminGetSettings
responses:
"200":
{
description: OK,
content:
{
application/json:
{ schema: { $ref: "#/components/schemas/ApiEnvelope" } },
},
}
"401": { $ref: "#/components/responses/Unauthorized" }
"403": { $ref: "#/components/responses/Forbidden" }
put:
tags: [Admin]
security:
- sessionCookie: []
summary: "Internal: update app-wide settings"
operationId: adminUpdateSettings
requestBody:
required: true
content:
application/json:
schema: { type: object, additionalProperties: true }
responses:
"200":
{
description: OK,
content:
{
application/json:
{ schema: { $ref: "#/components/schemas/ApiEnvelope" } },
},
}
"401": { $ref: "#/components/responses/Unauthorized" }
"403": { $ref: "#/components/responses/Forbidden" }
"422": { $ref: "#/components/responses/Unprocessable" }
/api/admin/status:
get:
tags: [Admin]
security:
- sessionCookie: []
summary: "Internal: deep system status"
operationId: adminStatus
responses:
"200":
{
description: OK,
content:
{
application/json:
{ schema: { $ref: "#/components/schemas/ApiEnvelope" } },
},
}
"401": { $ref: "#/components/responses/Unauthorized" }
"403": { $ref: "#/components/responses/Forbidden" }
/api/admin/tokens:
get:
tags: [Admin]
security:
- sessionCookie: []
summary: "Internal: list all API tokens (cross-user)"
operationId: adminListTokens
responses:
"200":
{
description: OK,
content:
{
application/json:
{ schema: { $ref: "#/components/schemas/ApiEnvelope" } },
},
}
"401": { $ref: "#/components/responses/Unauthorized" }
"403": { $ref: "#/components/responses/Forbidden" }
/api/admin/users:
get:
tags: [Admin]
security:
- sessionCookie: []
summary: "Internal: list all users"
operationId: adminListUsers
responses:
"200":
{
description: OK,
content:
{
application/json:
{ schema: { $ref: "#/components/schemas/ApiEnvelope" } },
},
}
"401": { $ref: "#/components/responses/Unauthorized" }
"403": { $ref: "#/components/responses/Forbidden" }
/api/admin/users/{id}:
parameters:
- $ref: "#/components/parameters/IdPathParam"
put:
tags: [Admin]
security:
- sessionCookie: []
summary: "Internal: update a user (username/email/role)"
operationId: adminUpdateUser
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/AdminUpdateUserInput" }
responses:
"200":
{
description: OK,
content:
{
application/json:
{ schema: { $ref: "#/components/schemas/ApiEnvelope" } },
},
}
"400": { $ref: "#/components/responses/BadRequest" }
"401": { $ref: "#/components/responses/Unauthorized" }
"403": { $ref: "#/components/responses/Forbidden" }
"404": { $ref: "#/components/responses/NotFound" }
"422": { $ref: "#/components/responses/Unprocessable" }
/api/admin/users/{id}/reset-password:
parameters:
- $ref: "#/components/parameters/IdPathParam"
post:
tags: [Admin]
security:
- sessionCookie: []
summary: "Internal: reset a user's password"
operationId: adminResetUserPassword
responses:
"200":
{
description: OK,
content:
{
application/json:
{ schema: { $ref: "#/components/schemas/ApiEnvelope" } },
},
}
"401": { $ref: "#/components/responses/Unauthorized" }
"403": { $ref: "#/components/responses/Forbidden" }
"404": { $ref: "#/components/responses/NotFound" }
/api/admin/status-overview:
get:
tags: [Admin]
security:
- sessionCookie: []
summary: "Internal: aggregator for the 6-card status grid (v1.4)"
description: |
Returns the precomputed status payload the admin top strip
renders — users / integrations / monitoring / backups /
maintenance / audit-log summaries with severity already
resolved server-side. Single batched query, no N+1.
operationId: adminStatusOverview
responses:
"200":
{
description: OK,
content:
{
application/json:
{ schema: { $ref: "#/components/schemas/ApiEnvelope" } },
},
}
"401": { $ref: "#/components/responses/Unauthorized" }
"403": { $ref: "#/components/responses/Forbidden" }
/api/admin/backup/test:
post:
tags: [Admin]
security:
- sessionCookie: []
summary: "Internal: probe the configured S3-compatible backup target (v1.4)"
description: |
Round-trips a small object against the bucket using the
configured `BACKUP_S3_*` credentials. Returns latency and the
sanitised endpoint host on success; never echoes the access key.
operationId: adminBackupTest
responses:
"200":
{
description: OK,
content:
{
application/json:
{ schema: { $ref: "#/components/schemas/ApiEnvelope" } },
},
}
"401": { $ref: "#/components/responses/Unauthorized" }
"403": { $ref: "#/components/responses/Forbidden" }
"422": { $ref: "#/components/responses/Unprocessable" }
# ─── Public + v1.4 additions ─────────────────────────────────────────
/api/version:
get:
tags: [Public]
summary: "Public: running version + build SHA + license"
description: |
Public, unauthenticated. Returns
`{ version, buildSha, builtAt, license, repository, changelog, docs }`.
Used by the docker container healthcheck and the Settings →
About surface's "Check for updates" button.
operationId: getVersion
responses:
"200":
{
description: OK,
content:
{
application/json:
{ schema: { $ref: "#/components/schemas/ApiEnvelope" } },
},
}
/api/integrations/withings/test:
post:
tags: [Withings]
security:
- sessionCookie: []
summary: "Probe the saved Withings OAuth connection (v1.4)"
operationId: withingsTest
responses:
"200":
{
description: OK,
content:
{
application/json:
{ schema: { $ref: "#/components/schemas/ApiEnvelope" } },
},
}
"401": { $ref: "#/components/responses/Unauthorized" }
"422": { $ref: "#/components/responses/Unprocessable" }
"429": { $ref: "#/components/responses/RateLimited" }
/api/integrations/moodlog/test:
post:
tags: [Moodlog]
security:
- sessionCookie: []
summary: "Probe moodLog.app reachability (v1.4)"
description: |
SSRF-guarded HEAD against the configured moodLog endpoint.
Returns `{ ok, latency_ms, errorCode? }` so the UI can
localise the failure message.
operationId: moodlogTest
responses:
"200":
{
description: OK,
content:
{
application/json:
{ schema: { $ref: "#/components/schemas/ApiEnvelope" } },
},
}
"401": { $ref: "#/components/responses/Unauthorized" }
"429": { $ref: "#/components/responses/RateLimited" }
/api/notifications/web-push/test:
post:
tags: [Notifications]
security:
- sessionCookie: []
summary: "Send a test Web Push to the current user (v1.4)"
operationId: webPushTest
responses:
"200":
{
description: OK,
content:
{
application/json:
{ schema: { $ref: "#/components/schemas/ApiEnvelope" } },
},
}
"401": { $ref: "#/components/responses/Unauthorized" }
"422": { $ref: "#/components/responses/Unprocessable" }
"429": { $ref: "#/components/responses/RateLimited" }
/api/monitoring/glitchtip/test:
post:
tags: [Monitoring]
security:
- sessionCookie: []
summary: "Probe the Glitchtip ingest endpoint (v1.4)"
operationId: glitchtipTest
responses:
"200":
{
description: OK,
content:
{
application/json:
{ schema: { $ref: "#/components/schemas/ApiEnvelope" } },
},
}
"401": { $ref: "#/components/responses/Unauthorized" }
"422": { $ref: "#/components/responses/Unprocessable" }
"429": { $ref: "#/components/responses/RateLimited" }
/api/monitoring/umami/test:
post:
tags: [Monitoring]
security:
- sessionCookie: []
summary: "Verify the Umami script + website ID resolve (v1.4)"
operationId: umamiTest
responses:
"200":
{
description: OK,
content:
{
application/json:
{ schema: { $ref: "#/components/schemas/ApiEnvelope" } },
},
}
"401": { $ref: "#/components/responses/Unauthorized" }
"422": { $ref: "#/components/responses/Unprocessable" }
"429": { $ref: "#/components/responses/RateLimited" }
/api/auth/refresh:
post:
tags: [Auth]
summary: "Native client: refresh-token rotation (v1.4)"
description: |
Exchanges a refresh token (`hlr_<64hex>`) for a fresh 24h
access token and a new refresh token. Cookie-session browsers
do not use this. Reuse-detection: presenting the same refresh
token a second time revokes every refresh token for the user.
operationId: authRefresh
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [refreshToken]
properties:
refreshToken: { type: string, pattern: "^hlr_[A-Fa-f0-9]{64}$" }
revoke:
type: boolean
default: false
description: "When true, revokes the refresh row + paired access token instead of rotating."
responses:
"200":
{
description: OK,
content:
{
application/json:
{ schema: { $ref: "#/components/schemas/ApiEnvelope" } },
},
}
"401": { $ref: "#/components/responses/Unauthorized" }
"422": { $ref: "#/components/responses/Unprocessable" }
"429": { $ref: "#/components/responses/RateLimited" }
/api/auth/refresh/revoke:
post:
tags: [Auth]
summary: "Native client: revoke a refresh token + paired access token (v1.4)"
operationId: authRefreshRevoke
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [refreshToken]
properties:
refreshToken: { type: string, pattern: "^hlr_[A-Fa-f0-9]{64}$" }
responses:
"200":
{
description: OK,
content:
{
application/json:
{ schema: { $ref: "#/components/schemas/ApiEnvelope" } },
},
}
"401": { $ref: "#/components/responses/Unauthorized" }
"422": { $ref: "#/components/responses/Unprocessable" }
# ─── iOS adapter endpoints (v1.3) ────────────────────────────────────
/api/dashboard/summary:
get:
tags: [Dashboard]
summary: "iOS: aggregated dashboard summary"
description: |
Single-call aggregate for the iOS DashboardSummary view. Combines
greeting, current/longest activity-day streak, today's medication
compliance, optional highlight insight, and per-metric latest +
7-day sparkline + trend.
operationId: getDashboardSummary
responses:
"200":
description: Dashboard summary
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/DashboardSummary" }
"401": { $ref: "#/components/responses/Unauthorized" }
/api/measurements/series:
get:
tags: [Measurements]
summary: "iOS: time-series + summary stats for a metric kind"
operationId: getMeasurementSeries
parameters:
- in: query
name: kind
required: true
schema: { $ref: "#/components/schemas/MetricKind" }
- in: query
name: days
schema:
type: integer
minimum: 1
maximum: 365
default: 30
responses:
"200":
description: Series payload
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/MeasurementSeries" }
"401": { $ref: "#/components/responses/Unauthorized" }
"422": { $ref: "#/components/responses/Unprocessable" }
/api/integrations/healthkit:
get:
tags: [Integrations]
summary: "iOS: HealthKit per-metric direction config"
operationId: getHealthKitConfig
responses:
"200":
description: HealthKit config
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/HealthKitConfig" }
"401": { $ref: "#/components/responses/Unauthorized" }
patch:
tags: [Integrations]
summary: "iOS: update HealthKit per-metric direction config"
operationId: updateHealthKitConfig
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/HealthKitConfigPatch" }
responses:
"200":
description: Updated config
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/HealthKitConfig" }
"401": { $ref: "#/components/responses/Unauthorized" }
"422": { $ref: "#/components/responses/Unprocessable" }
/api/user/profile:
get:
tags: [Auth]
summary: "iOS: flattened user profile"
operationId: getUserProfile
responses:
"200":
description: User profile
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/IosUserProfile" }
"401": { $ref: "#/components/responses/Unauthorized" }
patch:
tags: [Auth]
summary: "iOS: update profile fields"
operationId: updateUserProfile
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/IosUserProfilePatch" }
responses:
"200":
description: Updated profile
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data: { $ref: "#/components/schemas/IosUserProfile" }
"401": { $ref: "#/components/responses/Unauthorized" }
"409": { $ref: "#/components/responses/Conflict" }
"422": { $ref: "#/components/responses/Unprocessable" }
/api/devices:
post:
tags: [Notifications]
summary: "iOS: register an APNs device token"
operationId: registerDevice
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/DeviceRegisterInput" }
responses:
"201":
description: Device registered (or token transferred)
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
id: { type: string }
"401": { $ref: "#/components/responses/Unauthorized" }
"422": { $ref: "#/components/responses/Unprocessable" }
/api/medications/intake:
get:
tags: [Medications]
summary: "iOS: today list or compliance buckets"
operationId: listIntakeAggregator
parameters:
- in: query
name: scope
required: true
schema: { type: string, enum: [today, compliance] }
- in: query
name: days
schema:
type: integer
minimum: 1
maximum: 365
default: 30
responses:
"200":
description: Aggregator payload
content:
application/json:
schema: { $ref: "#/components/schemas/ApiEnvelope" }
"401": { $ref: "#/components/responses/Unauthorized" }
"422": { $ref: "#/components/responses/Unprocessable" }
post:
tags: [Medications]
summary: "iOS: update an intake event by id (taken/skipped/snoozed)"
operationId: updateIntakeAggregator
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/IntakeUpdateInput" }
responses:
"200":
description: Updated intake event
content:
application/json:
schema: { $ref: "#/components/schemas/ApiEnvelope" }
"401": { $ref: "#/components/responses/Unauthorized" }
"404": { $ref: "#/components/responses/NotFound" }
"422": { $ref: "#/components/responses/Unprocessable" }
/api/insights/cards:
get:
tags: [Insights]
summary: "iOS: rule-based insight cards"
operationId: getInsightCards
responses:
"200":
description: Insight cards
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: array
items: { $ref: "#/components/schemas/InsightCard" }
"401": { $ref: "#/components/responses/Unauthorized" }
/api/insights/correlations:
get:
tags: [Insights]
summary: "iOS: cross-metric correlations (placeholder)"
operationId: getInsightCorrelations
description: |
Returns an empty array until the correlations engine is wired up
(Phase 7). Audited via `insights.correlations.empty`.
responses:
"200":
description: Correlations
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: array
items:
{ $ref: "#/components/schemas/InsightCorrelation" }
"401": { $ref: "#/components/responses/Unauthorized" }
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: "hlk_<hex>"
description: |
Long-lived API token issued via `POST /api/tokens`. Accepted on all
user endpoints (interchangeable with the session cookie) and required
on external ingest endpoints (e.g. `/api/ingest/medication`). Tokens
are prefixed `hlk_` and stored as HMAC-SHA-256 hashes server-side
(keyed with `API_TOKEN_HMAC_KEY` so a DB dump alone does not allow
precomputed-rainbow lookups). Bearer tokens never grant admin access
— admin routes require the session cookie. Permission scopes are
enforced from the token's `permissions` array; a token MUST declare
either the explicit required permission for the route or the
wildcard `"*"`.
sessionCookie:
type: apiKey
in: cookie
name: healthlog_session
description: |
HttpOnly session cookie set by `/api/auth/login` and the passkey
login flow. Authenticates the web app and (optionally) the iOS
client when used in a web view.
parameters:
IdPathParam:
in: path
name: id
required: true
schema:
type: string
description: "CUID identifier."
LimitParam:
in: query
name: limit
schema:
type: integer
minimum: 1
maximum: 500
default: 100
OffsetParam:
in: query
name: offset
schema:
type: integer
minimum: 0
default: 0
LocaleParam:
in: query
name: locale
schema:
type: string
enum: [de, en]
description: "Override the resolved locale for narrative text."
responses:
BadRequest:
description: Bad request
content:
application/json:
schema: { $ref: "#/components/schemas/ApiError" }
Unauthorized:
description: Authentication required
content:
application/json:
schema: { $ref: "#/components/schemas/ApiError" }
Forbidden:
description: Forbidden
content:
application/json:
schema: { $ref: "#/components/schemas/ApiError" }
NotFound:
description: Not found
content:
application/json:
schema: { $ref: "#/components/schemas/ApiError" }
Conflict:
description: Conflict (e.g. duplicate)
content:
application/json:
schema: { $ref: "#/components/schemas/ApiError" }
Unprocessable:
description: Validation failure
content:
application/json:
schema: { $ref: "#/components/schemas/ApiError" }
RateLimited:
description: Rate limit exceeded
content:
application/json:
schema: { $ref: "#/components/schemas/ApiError" }
ServerError:
description: Internal server error
content:
application/json:
schema: { $ref: "#/components/schemas/ApiError" }
schemas:
# ─── Envelope / errors ─────────────────────────────────────
ApiEnvelope:
type: object
description: Standard envelope. On success `error` is `null`; on failure `data` is `null` and `error` is a string.
properties:
data:
description: Response payload (typed per-endpoint).
error:
type: [string, "null"]
required: [data, error]
ApiError:
type: object
properties:
data:
type: "null"
error:
type: string
required: [data, error]
DeletedEnvelope:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
deleted: { type: boolean }
UpdatedEnvelope:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
updated: { type: boolean }
PageMeta:
type: object
properties:
total: { type: integer }
limit: { type: integer }
offset: { type: integer }
required: [total, limit, offset]
# ─── Enums ─────────────────────────────────────────────────
MeasurementType:
type: string
enum:
- WEIGHT
- BLOOD_PRESSURE_SYS
- BLOOD_PRESSURE_DIA
- PULSE
- BODY_FAT
- SLEEP_DURATION
- ACTIVITY_STEPS
- BLOOD_GLUCOSE
- TOTAL_BODY_WATER
- BONE_MASS
- OXYGEN_SATURATION
MeasurementSource:
type: string
enum: [MANUAL, WITHINGS, IMPORT]
GlucoseContext:
type: string
enum: [FASTING, POSTPRANDIAL, RANDOM, BEDTIME]
IntakeSource:
type: string
enum: [WEB, API, REMINDER, IMPORT]
ReminderPhase:
type: string
enum: [GREEN, YELLOW, ORANGE, RED]
PhaseMode:
type: string
enum: [MINUTES, PERCENT]
UserRole:
type: string
enum: [ADMIN, USER]
Gender:
type: string
enum: [MALE, FEMALE]
MoodLevel:
type: string
enum: [SUPER_GUT, GUT, OKAY, SCHLECHT, LAUSIG]
MedicationCategory:
type: string
enum:
- BLOOD_PRESSURE
- VITAMIN
- SUPPLEMENT
- PAIN_RELIEF
- ALLERGY
- DIGESTIVE
- THYROID
- HORMONE
- SKIN
- SLEEP_AID
- OTHER
NotificationChannelType:
type: string
enum: [TELEGRAM, NTFY, WEB_PUSH]
AiProviderType:
type: string
enum: [OPENAI, ANTHROPIC, LOCAL, CHATGPT_OAUTH]
InsightSeverity:
type: string
enum: [normal, mild, moderate, severe, info]
Trend:
type: [string, "null"]
enum: [up, down, stable, null]
# ─── Auth DTOs ─────────────────────────────────────────────
RegisterInput:
type: object
properties:
email: { type: string, format: email }
username:
type: string
minLength: 3
maxLength: 30
pattern: "^[a-zA-Z0-9_-]+$"
password:
type: string
minLength: 12
required: [email, username, password]
LoginInput:
type: object
properties:
email:
type: string
description: Email or username.
password: { type: string }
required: [email, password]
LoginResponseEnvelope:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
user:
type: object
properties:
id: { type: string }
username: { type: string }
required: [id, username]
token:
type: string
description: |
Long-lived `hlk_*` Bearer token. Only returned when the
request carries `X-Client-Type: native` or a User-Agent
starting with `HealthLog-iOS`. Use it for subsequent
requests as `Authorization: Bearer <token>`.
tokenExpiresAt:
type: string
format: date-time
description: ISO timestamp at which the auto-issued token expires.
RegisterResponseEnvelope:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
user:
type: object
properties:
id: { type: string }
username: { type: string }
email: { type: [string, "null"] }
ProfileInput:
type: object
properties:
email: { type: [string, "null"], format: email }
heightCm:
type: [number, "null"]
minimum: 50
maximum: 300
dateOfBirth:
type: [string, "null"]
format: date
gender:
oneOf:
- $ref: "#/components/schemas/Gender"
- type: "null"
ChangePasswordInput:
type: object
properties:
currentPassword: { type: string }
newPassword: { type: string, minLength: 12 }
confirmPassword: { type: string }
required: [currentPassword, newPassword, confirmPassword]
User:
type: object
description: Public-facing user shape.
properties:
id: { type: string }
username: { type: string }
email: { type: [string, "null"], format: email }
role: { $ref: "#/components/schemas/UserRole" }
heightCm: { type: [number, "null"] }
dateOfBirth: { type: [string, "null"], format: date-time }
gender:
oneOf:
- $ref: "#/components/schemas/Gender"
- type: "null"
timezone: { type: string }
required: [id, username, role, timezone]
CurrentUser:
allOf:
- $ref: "#/components/schemas/User"
- type: object
properties:
onboardingCompletedAt:
type: [string, "null"]
format: date-time
gravatarUrl:
type: [string, "null"]
glucoseUnit:
type: [string, "null"]
enum: ["mg/dL", "mmol/L", null]
# ─── Passkey DTOs ──────────────────────────────────────────
PasskeyRegisterOptions:
type: object
description: SimpleWebAuthn `PublicKeyCredentialCreationOptionsJSON` plus a server-issued challenge id.
properties:
options:
type: object
additionalProperties: true
description: WebAuthn registration options.
challengeId: { type: string }
required: [options, challengeId]
PasskeyLoginOptions:
type: object
properties:
options:
type: object
additionalProperties: true
description: WebAuthn authentication options.
challengeId: { type: string }
required: [options, challengeId]
PasskeyVerifyRegistrationInput:
type: object
properties:
challengeId: { type: string }
credential:
type: object
additionalProperties: true
description: "`RegistrationResponseJSON` from `@simplewebauthn/browser`."
required: [challengeId, credential]
PasskeyVerifyLoginInput:
type: object
properties:
challengeId: { type: string }
credential:
type: object
additionalProperties: true
description: "`AuthenticationResponseJSON` from `@simplewebauthn/browser`."
required: [challengeId, credential]
PasskeySummary:
type: object
properties:
id: { type: string }
name: { type: string }
credentialDeviceType: { type: string }
credentialBackedUp: { type: boolean }
createdAt: { type: string, format: date-time }
required: [id, name, credentialDeviceType, credentialBackedUp, createdAt]
# ─── Measurement DTOs ──────────────────────────────────────
Measurement:
type: object
properties:
id: { type: string }
userId: { type: string }
type: { $ref: "#/components/schemas/MeasurementType" }
value: { type: number }
unit: { type: string }
source: { $ref: "#/components/schemas/MeasurementSource" }
measuredAt: { type: string, format: date-time }
notes: { type: [string, "null"], maxLength: 25 }
externalId: { type: [string, "null"] }
glucoseContext:
oneOf:
- $ref: "#/components/schemas/GlucoseContext"
- type: "null"
createdAt: { type: string, format: date-time }
updatedAt: { type: string, format: date-time }
required:
[
id,
userId,
type,
value,
unit,
source,
measuredAt,
createdAt,
updatedAt,
]
CreateMeasurementInput:
type: object
properties:
type: { $ref: "#/components/schemas/MeasurementType" }
value: { type: number }
measuredAt: { type: string, format: date-time }
notes: { type: string, maxLength: 25 }
source:
allOf: [{ $ref: "#/components/schemas/MeasurementSource" }]
default: MANUAL
glucoseContext:
$ref: "#/components/schemas/GlucoseContext"
required: [type, value, measuredAt]
UpdateMeasurementInput:
type: object
properties:
value: { type: number, minimum: 0, maximum: 500000 }
measuredAt: { type: string, format: date-time }
notes: { type: [string, "null"], maxLength: 25 }
# ─── Medication DTOs ───────────────────────────────────────
MedicationSchedule:
type: object
properties:
id: { type: string }
medicationId: { type: string }
windowStart:
type: string
pattern: '^([01]\d|2[0-3]):([0-5]\d)$'
description: HH:mm
windowEnd:
type: string
pattern: '^([01]\d|2[0-3]):([0-5]\d)$'
label: { type: [string, "null"] }
dose:
{ type: [string, "null"], description: "Per-schedule dose override" }
daysOfWeek:
type: [string, "null"]
description: "Serialized recurrence (CSV of 0..6, optional intervalWeeks suffix)."
required: [id, medicationId, windowStart, windowEnd]
Medication:
type: object
properties:
id: { type: string }
userId: { type: string }
name: { type: string }
dose: { type: string }
active: { type: boolean }
notificationsEnabled: { type: boolean }
pausedAt: { type: [string, "null"], format: date-time }
snoozedUntil: { type: [string, "null"], format: date-time }
createdAt: { type: string, format: date-time }
updatedAt: { type: string, format: date-time }
required:
[
id,
userId,
name,
dose,
active,
notificationsEnabled,
createdAt,
updatedAt,
]
MedicationWithSchedules:
allOf:
- $ref: "#/components/schemas/Medication"
- type: object
properties:
schedules:
type: array
items: { $ref: "#/components/schemas/MedicationSchedule" }
category: { $ref: "#/components/schemas/MedicationCategory" }
lastTakenAt:
type: [string, "null"]
format: date-time
todayEventCount:
type: integer
MedicationScheduleInput:
type: object
properties:
windowStart: { type: string, pattern: '^([01]\d|2[0-3]):([0-5]\d)$' }
windowEnd: { type: string, pattern: '^([01]\d|2[0-3]):([0-5]\d)$' }
label: { type: string, maxLength: 50 }
dose: { type: string, maxLength: 50 }
daysOfWeek:
type: array
items: { type: integer, minimum: 0, maximum: 6 }
intervalWeeks:
type: integer
minimum: 1
maximum: 4
required: [windowStart, windowEnd]
CreateMedicationInput:
type: object
properties:
name: { type: string, minLength: 1, maxLength: 100 }
dose: { type: string, minLength: 1, maxLength: 50 }
category: { $ref: "#/components/schemas/MedicationCategory" }
schedules:
type: array
minItems: 1
items: { $ref: "#/components/schemas/MedicationScheduleInput" }
required: [name, dose, schedules]
UpdateMedicationInput:
type: object
properties:
name: { type: string, minLength: 1, maxLength: 100 }
dose: { type: string, minLength: 1, maxLength: 50 }
category: { $ref: "#/components/schemas/MedicationCategory" }
active: { type: boolean }
notificationsEnabled: { type: boolean }
schedules:
type: array
items: { $ref: "#/components/schemas/MedicationScheduleInput" }
MedicationIntakeEvent:
type: object
properties:
id: { type: string }
userId: { type: string }
medicationId: { type: string }
scheduledFor: { type: string, format: date-time }
takenAt: { type: [string, "null"], format: date-time }
skipped: { type: boolean }
source: { $ref: "#/components/schemas/IntakeSource" }
idempotencyKey: { type: [string, "null"] }
createdAt: { type: string, format: date-time }
required:
[id, userId, medicationId, scheduledFor, skipped, source, createdAt]
CreateIntakeInput:
type: object
properties:
scheduledFor: { type: string, format: date-time }
takenAt: { type: string, format: date-time }
skipped: { type: boolean, default: false }
idempotencyKey: { type: string, maxLength: 128 }
UpdateIntakeInput:
type: object
properties:
takenAt: { type: [string, "null"], format: date-time }
skipped: { type: boolean }
scheduledFor: { type: string, format: date-time }
IntakeImportEntry:
type: object
properties:
datum:
type: string
pattern: '^\d{4}-\d{2}-\d{2}$'
description: YYYY-MM-DD
uhrzeit:
type: string
pattern: '^\d{2}:\d{2}:\d{2}$'
description: HH:mm:ss
zaehler:
oneOf:
- { type: integer }
- { type: string }
required: [datum, uhrzeit]
IntakeImportResult:
type: object
properties:
imported: { type: integer }
skippedDuplicates: { type: integer }
skippedInvalid: { type: integer }
ExternalIntakeInput:
type: object
properties:
medicationName: { type: string, maxLength: 200 }
takenAt: { type: string, format: date-time }
idempotencyKey: { type: string, maxLength: 128 }
required: [medicationName, idempotencyKey]
DailyComplianceEntry:
type: object
properties:
expected: { type: integer }
taken: { type: integer }
skipped: { type: integer }
onTime: { type: integer }
late: { type: integer }
veryLate: { type: integer }
ComplianceSummary:
type: object
properties:
rate: { type: number, description: "Fraction 0..1" }
taken: { type: integer }
skipped: { type: integer }
missed: { type: integer }
streak: { type: integer }
MedicationComplianceResponse:
type: object
properties:
compliance7: { $ref: "#/components/schemas/ComplianceSummary" }
compliance30: { $ref: "#/components/schemas/ComplianceSummary" }
dailyCompliance:
type: object
additionalProperties:
{ $ref: "#/components/schemas/DailyComplianceEntry" }
ReminderPhaseConfig:
type: object
properties:
greenValue: { type: integer, default: 60 }
greenMode:
{
allOf: [{ $ref: "#/components/schemas/PhaseMode" }],
default: MINUTES,
}
yellowValue: { type: integer, default: 30 }
yellowMode:
{
allOf: [{ $ref: "#/components/schemas/PhaseMode" }],
default: MINUTES,
}
orangeValue: { type: integer, default: 0 }
orangeMode:
{
allOf: [{ $ref: "#/components/schemas/PhaseMode" }],
default: MINUTES,
}
redValue: { type: integer, default: 240 }
redMode:
{
allOf: [{ $ref: "#/components/schemas/PhaseMode" }],
default: MINUTES,
}
MedicationApiEndpointResponse:
type: object
properties:
enabled: { type: boolean }
activeTokenCount: { type: integer }
token:
type: [string, "null"]
description: "Plaintext token, only returned once on creation."
created: { type: boolean }
revokedTokenCount: { type: integer }
IntakeSummaryPoint:
type: object
properties:
date:
type: string
description: YYYY-MM-DD (Berlin local).
total: { type: integer }
medications:
type: object
additionalProperties: { type: integer }
required: [date, total]
IntakeSummaryResponse:
type: object
properties:
points:
type: array
items: { $ref: "#/components/schemas/IntakeSummaryPoint" }
medications:
type: array
items: { type: string }
# ─── Mood DTOs ─────────────────────────────────────────────
MoodEntry:
type: object
properties:
id: { type: string }
userId: { type: string }
date:
type: string
description: YYYY-MM-DD
mood: { $ref: "#/components/schemas/MoodLevel" }
score:
type: integer
minimum: 1
maximum: 5
tags:
type: array
items: { type: string }
source: { type: string, default: MANUAL }
moodLoggedAt: { type: string, format: date-time }
syncedAt: { type: string, format: date-time }
createdAt: { type: string, format: date-time }
updatedAt: { type: string, format: date-time }
required: [id, userId, date, mood, score, source, moodLoggedAt]
CreateMoodEntryInput:
type: object
properties:
mood: { $ref: "#/components/schemas/MoodLevel" }
moodLoggedAt: { type: string, format: date-time }
tags:
type: array
items: { type: string }
source: { type: string }
required: [mood, moodLoggedAt]
UpdateMoodEntryInput:
type: object
properties:
mood: { $ref: "#/components/schemas/MoodLevel" }
moodLoggedAt: { type: string, format: date-time }
tags:
type: array
items: { type: string }
MoodAnalytics:
type: object
properties:
entries:
type: array
items:
type: object
properties:
date: { type: string }
score: { type: number }
samples: { type: integer }
summary:
type: object
additionalProperties: true
# ─── Dashboard DTOs ────────────────────────────────────────
DashboardWidget:
type: object
properties:
id:
type: string
enum:
[
weight,
bp,
pulse,
bodyFat,
mood,
medications,
sleep,
steps,
glucose,
bpInTarget,
]
visible: { type: boolean }
order: { type: integer, minimum: 0, maximum: 99 }
required: [id, visible, order]
DashboardLayout:
type: object
properties:
version: { type: integer, enum: [1] }
widgets:
type: array
minItems: 1
maxItems: 20
items: { $ref: "#/components/schemas/DashboardWidget" }
required: [version, widgets]
# ─── Insights DTOs ─────────────────────────────────────────
Classification:
type: object
properties:
category: { type: string }
color: { type: string }
severity: { $ref: "#/components/schemas/InsightSeverity" }
SummaryStats:
type: object
properties:
latest: { type: [number, "null"] }
avg7: { type: [number, "null"] }
avg30: { type: [number, "null"] }
min: { type: [number, "null"] }
max: { type: [number, "null"] }
count: { type: integer }
slope30:
type: [object, "null"]
properties:
slope: { type: number }
r2: { type: number }
anomalyCount: { type: integer }
CorrelationResult:
type: [object, "null"]
properties:
r: { type: number }
strength: { type: string }
n: { type: integer }
Alert:
type: object
properties:
severity: { $ref: "#/components/schemas/InsightSeverity" }
message: { type: string }
type: { type: string }
BpTargets:
type: [object, "null"]
properties:
sysLow: { type: integer }
sysHigh: { type: integer }
diaLow: { type: integer }
diaHigh: { type: integer }
ComprehensiveInsights:
type: object
properties:
summaries:
type: object
additionalProperties: { $ref: "#/components/schemas/SummaryStats" }
bmi: { type: [number, "null"] }
bmiClassification:
oneOf:
- $ref: "#/components/schemas/Classification"
- type: "null"
bpClassification:
oneOf:
- $ref: "#/components/schemas/Classification"
- type: "null"
bpPctInTarget: { type: [integer, "null"] }
bpTargets: { $ref: "#/components/schemas/BpTargets" }
weightBpCorrelation: { $ref: "#/components/schemas/CorrelationResult" }
scatterData:
type: array
items:
type: object
properties:
weight: { type: number }
sysBP: { type: number }
bpMedicationCorrelation:
type: [object, "null"]
properties:
r: { type: number }
strength: { type: string }
n: { type: integer }
medicationCount: { type: integer }
bpMedicationScatterData:
type: array
items:
type: object
properties:
continuityPct: { type: integer }
sysBP: { type: number }
moodSummary:
oneOf:
- $ref: "#/components/schemas/SummaryStats"
- type: "null"
moodBpCorrelation: { $ref: "#/components/schemas/CorrelationResult" }
moodBpScatterData:
type: array
items:
type: object
properties:
mood: { type: number }
sysBP: { type: number }
moodWeightCorrelation:
{ $ref: "#/components/schemas/CorrelationResult" }
moodWeightScatterData:
type: array
items:
type: object
properties:
mood: { type: number }
weight: { type: number }
moodPulseCorrelation: { $ref: "#/components/schemas/CorrelationResult" }
moodPulseScatterData:
type: array
items:
type: object
properties:
mood: { type: number }
pulse: { type: number }
medications:
type: array
items:
type: object
properties:
id: { type: string }
name: { type: string }
dose: { type: string }
category: { $ref: "#/components/schemas/MedicationCategory" }
compliance7: { type: number }
compliance30: { type: number }
streak: { type: integer }
taken7: { type: integer }
skipped7: { type: integer }
missed7: { type: integer }
alerts:
type: array
items: { $ref: "#/components/schemas/Alert" }
hasProvider: { type: boolean }
dataSpanDays: { type: integer }
totalMeasurements: { type: integer }
InsightTargetItem:
type: object
properties:
type: { type: string }
label: { type: string }
current: { type: [number, "null"] }
average30: { type: [number, "null"] }
trend: { $ref: "#/components/schemas/Trend" }
unit: { type: string }
range:
type: [object, "null"]
properties:
min: { type: number }
max: { type: number }
classification:
oneOf:
- $ref: "#/components/schemas/Classification"
- type: "null"
source: { type: string }
details:
type: object
properties:
medications:
type: array
items:
type: object
properties:
name: { type: string }
compliance7: { type: number }
compliance30: { type: number }
InsightTargetsResponse:
type: object
properties:
targets:
type: array
items: { $ref: "#/components/schemas/InsightTargetItem" }
bpDiastolic:
type: object
properties:
current: { type: [number, "null"] }
average30: { type: [number, "null"] }
range:
type: [object, "null"]
properties:
min: { type: number }
max: { type: number }
profile:
type: object
properties:
heightCm: { type: [number, "null"] }
age: { type: [integer, "null"] }
gender:
oneOf:
- $ref: "#/components/schemas/Gender"
- type: "null"
glucoseUnit: { type: string }
InsightStatusBundle:
type: object
description: Narrative status payload (shape varies per status route).
additionalProperties: true
InsightGenerateResult:
type: object
properties:
insights:
type: object
additionalProperties: true
cached: { type: boolean }
cachedAt: { type: string, format: date-time }
InsightsSettings:
type: object
properties:
codexStatus: { type: string, enum: [connected, disconnected] }
codexConnectedAt: { type: [string, "null"], format: date-time }
hasAdminKey: { type: boolean }
privacyMode: { type: string, enum: [aggregated, raw] }
lastInsightAt: { type: [string, "null"], format: date-time }
# ─── Achievements ──────────────────────────────────────────
Achievement:
type: object
properties:
id: { type: string }
title: { type: string }
description: { type: string }
target: { type: integer }
progress: { type: integer }
unlocked: { type: boolean }
completedAt:
type: [string, "null"]
format: date-time
AchievementsResult:
type: object
properties:
achievements:
type: array
items: { $ref: "#/components/schemas/Achievement" }
unlockedCount: { type: integer }
totalCount: { type: integer }
# ─── Doctor report ─────────────────────────────────────────
DoctorReportResponse:
type: object
properties:
period:
type: object
properties:
days: { type: integer }
since: { type: string, format: date-time }
patient:
type: object
properties:
username: { type: [string, "null"] }
dateOfBirth: { type: [string, "null"], format: date-time }
gender:
oneOf:
- $ref: "#/components/schemas/Gender"
- type: "null"
heightCm: { type: [number, "null"] }
measurements:
type: object
additionalProperties:
type: array
items:
type: object
properties:
value: { type: number }
measuredAt: { type: string, format: date-time }
stats:
type: object
additionalProperties:
type: object
properties:
avg: { type: number }
min: { type: number }
max: { type: number }
count: { type: integer }
latest: { type: number }
glucoseStats:
type: object
additionalProperties:
type: object
properties:
avg: { type: number }
min: { type: number }
max: { type: number }
count: { type: integer }
latest: { type: number }
glucoseRanges:
type: object
additionalProperties:
type: object
properties:
min: { type: number }
max: { type: number }
glucoseUnit: { type: string }
bmi: { type: [number, "null"] }
compliance:
type: object
additionalProperties:
type: object
properties:
total: { type: integer }
taken: { type: integer }
skipped: { type: integer }
missed: { type: integer }
medications:
type: array
items:
type: object
properties:
name: { type: string }
dose: { type: string }
schedules:
type: array
items:
type: object
properties:
windowStart: { type: string }
windowEnd: { type: string }
label: { type: [string, "null"] }
mood:
type: [object, "null"]
properties:
avg: { type: number }
min: { type: number }
max: { type: number }
count: { type: integer }
distribution:
type: object
additionalProperties: { type: integer }
# ─── Onboarding ────────────────────────────────────────────
OnboardingInput:
type: object
properties:
heightCm: { type: number, minimum: 50, maximum: 300 }
dateOfBirth: { type: string, format: date }
gender: { $ref: "#/components/schemas/Gender" }
# ─── Health probe ──────────────────────────────────────────
HealthStatus:
type: object
properties:
status: { type: string, enum: [ok, degraded] }
timestamp: { type: string, format: date-time }
database: { type: string }
worker: { type: string }
workerLastHeartbeat: { type: string, format: date-time }
# ─── Tokens ────────────────────────────────────────────────
ApiTokenSummary:
type: object
properties:
id: { type: string }
name: { type: string }
permissions:
type: array
items: { type: string }
lastUsedAt: { type: [string, "null"], format: date-time }
expiresAt: { type: [string, "null"], format: date-time }
createdAt: { type: string, format: date-time }
revoked: { type: boolean }
CreateTokenInput:
type: object
properties:
name: { type: string, minLength: 1, maxLength: 100 }
expiresInDays: { type: integer, minimum: 1, maximum: 365 }
required: [name]
# ─── Notifications ─────────────────────────────────────────
NotificationChannel:
type: object
properties:
id: { type: string }
type: { $ref: "#/components/schemas/NotificationChannelType" }
label: { type: string }
enabled: { type: boolean }
globallyEnabled: { type: boolean }
NotificationPreference:
type: object
properties:
channelId: { type: string }
eventType: { type: string }
enabled: { type: boolean }
NotificationPreferencesResponse:
type: object
properties:
channels:
type: array
items: { $ref: "#/components/schemas/NotificationChannel" }
preferences:
type: array
items: { $ref: "#/components/schemas/NotificationPreference" }
eventTypes:
type: array
items: { type: string }
UpdateNotificationPreferenceInput:
type: object
properties:
channelId: { type: string }
eventType: { type: string }
enabled: { type: boolean }
required: [channelId, eventType, enabled]
WebPushSubscribeInput:
type: object
properties:
endpoint: { type: string, format: uri }
keys:
type: object
properties:
p256dh: { type: string }
auth: { type: string }
required: [p256dh, auth]
required: [endpoint, keys]
# ─── User config ───────────────────────────────────────────
UserAiProvider:
type: object
properties:
provider:
oneOf:
- $ref: "#/components/schemas/AiProviderType"
- type: "null"
model: { type: [string, "null"] }
baseUrl: { type: [string, "null"] }
hasAnthropicKey: { type: boolean }
anthropicKeyPreview: { type: [string, "null"] }
hasLocalKey: { type: boolean }
UpdateUserAiProviderInput:
type: object
properties:
provider:
oneOf:
- $ref: "#/components/schemas/AiProviderType"
- type: "null"
model: { type: [string, "null"] }
baseUrl: { type: [string, "null"] }
anthropicKey: { type: [string, "null"] }
localKey: { type: [string, "null"] }
ThresholdRange:
type: object
properties:
greenMin: { type: number }
greenMax: { type: number }
orangeMin: { type: number }
orangeMax: { type: number }
redMin: { type: number }
redMax: { type: number }
EffectiveRange:
type: object
properties:
range:
oneOf:
- $ref: "#/components/schemas/ThresholdRange"
- type: "null"
isOverride: { type: boolean }
defaultRange:
oneOf:
- $ref: "#/components/schemas/ThresholdRange"
- type: "null"
ThresholdOverrides:
type: object
description: "Map of metric name → `{ min, max }` override."
additionalProperties:
type: object
properties:
min: { type: number }
max: { type: number }
ThresholdsResponse:
type: object
properties:
effective:
type: object
additionalProperties: { $ref: "#/components/schemas/EffectiveRange" }
overrides: { $ref: "#/components/schemas/ThresholdOverrides" }
# ─── Analytics ─────────────────────────────────────────────
AnalyticsResponse:
type: object
properties:
summaries:
type: object
additionalProperties: { $ref: "#/components/schemas/SummaryStats" }
bmi: { type: [number, "null"] }
bpInTargetPct: { type: [integer, "null"] }
glucoseByContext:
type: object
additionalProperties: { $ref: "#/components/schemas/SummaryStats" }
AiTestResult:
type: object
properties:
ok: { type: boolean }
providerType: { $ref: "#/components/schemas/AiProviderType" }
model: { type: string }
tokensUsed:
type: object
properties:
input: { type: integer }
output: { type: integer }
sample: { type: string }
# ─── Export / Import ───────────────────────────────────────
ImportInput:
type: object
properties:
measurements:
type: array
maxItems: 10000
items:
type: object
properties:
type: { $ref: "#/components/schemas/MeasurementType" }
value: { type: number }
unit: { type: string }
measuredAt: { type: string, format: date-time }
source: { type: string }
notes: { type: string }
required: [type, value, unit, measuredAt]
moodEntries:
type: array
maxItems: 10000
items:
type: object
properties:
date: { type: string }
mood: { $ref: "#/components/schemas/MoodLevel" }
score: { type: integer, minimum: 1, maximum: 5 }
tags: { type: string }
loggedAt: { type: string, format: date-time }
required: [date, mood, score]
ImportResult:
type: object
properties:
measurements: { type: integer }
moodEntries: { type: integer }
skipped: { type: integer }
# ─── Audit log ─────────────────────────────────────────────
AuditLogEntry:
type: object
properties:
id: { type: string }
action: { type: string }
ipAddress: { type: [string, "null"] }
location: { type: [string, "null"] }
details: { type: [string, "null"], description: "JSON string" }
createdAt: { type: string, format: date-time }
AuditLogResponse:
type: object
properties:
entries:
type: array
items: { $ref: "#/components/schemas/AuditLogEntry" }
meta: { $ref: "#/components/schemas/PageMeta" }
# ─── Feedback ──────────────────────────────────────────────
FeedbackCategory:
type: string
enum: [BUG, FEATURE_REQUEST, QUESTION, OTHER]
FeedbackStatus:
type: string
enum: [OPEN, ACKNOWLEDGED, RESOLVED, ARCHIVED]
FeedbackSummary:
type: object
properties:
id: { type: string }
category: { $ref: "#/components/schemas/FeedbackCategory" }
subject: { type: string }
status: { $ref: "#/components/schemas/FeedbackStatus" }
adminNote: { type: [string, "null"] }
gitHubIssueUrl: { type: [string, "null"], format: uri }
createdAt: { type: string, format: date-time }
updatedAt: { type: string, format: date-time }
CreateFeedbackInput:
type: object
properties:
category: { $ref: "#/components/schemas/FeedbackCategory" }
subject: { type: string }
description: { type: string }
screenshot:
type: string
description: "Base64-encoded PNG/JPG (≤5 MB)."
metadata:
type: object
additionalProperties: true
required: [category, subject, description]
BugReportInput:
type: object
properties:
description: { type: string, minLength: 10, maxLength: 5000 }
screenshot:
type: string
description: "`data:image/(png|jpeg|webp|gif);base64,...` data URL."
required: [description]
# ─── Settings ──────────────────────────────────────────────
GlobalServicesFlags:
type: object
properties:
telegram: { type: boolean }
ntfy: { type: boolean }
webPush: { type: boolean }
api: { type: boolean }
moodLog: { type: boolean }
MoodLogSettingsInput:
type: object
properties:
url: { type: [string, "null"], format: uri }
apiKey: { type: [string, "null"] }
enabled: { type: boolean }
webhookSecret: { type: [string, "null"] }
NtfySettings:
type: object
properties:
configured: { type: boolean }
enabled: { type: boolean }
topic: { type: [string, "null"] }
serverUrl: { type: [string, "null"] }
NtfySettingsInput:
type: object
properties:
topic: { type: [string, "null"] }
serverUrl: { type: [string, "null"], format: uri }
enabled: { type: boolean }
accessToken: { type: [string, "null"] }
TelegramSettings:
type: object
properties:
configured: { type: boolean }
enabled: { type: boolean }
chatId: { type: [string, "null"] }
TelegramSettingsInput:
type: object
properties:
botToken: { type: [string, "null"] }
chatId: { type: [string, "null"] }
enabled: { type: boolean }
ReminderThresholds:
type: object
properties:
reminderLateMinutes: { type: integer }
reminderMissedMinutes: { type: integer }
# ─── Withings + moodLog status ─────────────────────────────
WithingsCredentialsInput:
type: object
properties:
clientId: { type: string }
clientSecret: { type: string }
required: [clientId, clientSecret]
WithingsStatus:
type: object
properties:
connected: { type: boolean }
configured: { type: boolean }
lastSyncedAt: { type: [string, "null"], format: date-time }
connectedAt: { type: string, format: date-time }
tokenExpired: { type: boolean }
tokenRefreshFailed: { type: boolean }
tokenExpiresAt: { type: string, format: date-time }
MoodLogStatus:
type: object
properties:
configured: { type: boolean }
enabled: { type: boolean }
lastSyncedAt: { type: [string, "null"], format: date-time }
entryCount: { type: integer }
webhookSecret: { type: [string, "null"] }
PublicMonitoringSettings:
type: object
properties:
umamiEnabled: { type: boolean }
umamiScriptUrl: { type: [string, "null"] }
umamiWebsiteId: { type: [string, "null"] }
glitchtipEnabled: { type: boolean }
glitchtipDsn: { type: [string, "null"] }
glitchtipEnvironment: { type: [string, "null"] }
# ─── iOS adapter DTOs (v1.3) ──────────────────────────────
# Used by /api/dashboard/summary (`MetricCard.kind`) and the
# /api/measurements/series adapter. Extended in v1.3.3 to cover the
# body-composition + SpO2 measurements that the server already emits.
# iOS clients SHOULD decode unknown values defensively; we still
# publish the canonical list here so generated codecs stay accurate.
MetricKind:
type: string
enum:
- weight
- bloodPressure
- pulse
- bodyFat
- glucose
- sleep
- steps
- totalBodyWater
- boneMass
- oxygenSaturation
InsightSeverityIos:
type: string
enum: [alert, caution, info, good]
DashboardSummaryGreeting:
type: object
properties:
salutation: { type: string }
date: { type: string, format: date-time }
required: [salutation, date]
DashboardSummaryStreak:
type: object
properties:
currentDays: { type: integer }
longest: { type: integer }
label: { type: string }
required: [currentDays, longest, label]
DashboardSummaryCompliance:
type: object
properties:
scheduledToday: { type: integer }
takenToday: { type: integer }
required: [scheduledToday, takenToday]
DashboardMetricCard:
type: object
properties:
id: { type: string }
kind: { $ref: "#/components/schemas/MetricKind" }
title: { type: string }
latestValue: { type: [number, "null"] }
secondaryValue: { type: [number, "null"] }
unit: { type: string }
trend:
type: string
enum: [up, down, flat, unknown]
sparkline:
type: array
items: { type: number }
updatedAt: { type: [string, "null"], format: date-time }
required: [id, kind, title, unit, trend, sparkline]
DashboardSummary:
type: object
properties:
greeting: { $ref: "#/components/schemas/DashboardSummaryGreeting" }
streak: { $ref: "#/components/schemas/DashboardSummaryStreak" }
compliance: { $ref: "#/components/schemas/DashboardSummaryCompliance" }
highlightInsight:
oneOf:
- { type: "null" }
- { $ref: "#/components/schemas/InsightCard" }
metrics:
type: array
items: { $ref: "#/components/schemas/DashboardMetricCard" }
lastUpdated: { type: string, format: date-time }
required: [greeting, streak, compliance, metrics, lastUpdated]
MeasurementSeriesPoint:
type: object
properties:
id: { type: string }
at: { type: string, format: date-time }
value: { type: number }
secondary: { type: [number, "null"] }
required: [id, at, value]
MeasurementSeriesStats:
type: object
properties:
mean: { type: number }
min: { type: number }
max: { type: number }
stdDev: { type: number }
count: { type: integer }
required: [mean, min, max, stdDev, count]
MeasurementSeries:
type: object
properties:
kind: { $ref: "#/components/schemas/MetricKind" }
points:
type: array
items: { $ref: "#/components/schemas/MeasurementSeriesPoint" }
stats: { $ref: "#/components/schemas/MeasurementSeriesStats" }
required: [kind, points, stats]
HealthKitDirection:
type: string
enum: [bidirectional, readOnly, writeOnly, disabled]
HealthKitEntry:
type: object
properties:
id: { type: string }
kind: { type: string }
direction: { $ref: "#/components/schemas/HealthKitDirection" }
enabled: { type: boolean }
required: [id, kind, direction, enabled]
HealthKitConfig:
type: object
properties:
entries:
type: array
items: { $ref: "#/components/schemas/HealthKitEntry" }
lastSyncedAt: { type: [string, "null"], format: date-time }
required: [entries]
HealthKitConfigPatch:
type: object
properties:
entries:
type: array
maxItems: 50
items:
type: object
properties:
id: { type: string }
kind: { type: string }
direction: { $ref: "#/components/schemas/HealthKitDirection" }
enabled: { type: boolean }
required: [id, direction]
required: [entries]
IosUserProfile:
type: object
properties:
username: { type: string }
displayName: { type: [string, "null"] }
email: { type: [string, "null"], format: email }
dateOfBirth: { type: [string, "null"], format: date-time }
gender: { $ref: "#/components/schemas/Gender" }
heightCm: { type: [number, "null"] }
locale: { type: [string, "null"] }
timezone: { type: string }
required: [username, timezone]
IosUserProfilePatch:
type: object
properties:
displayName: { type: [string, "null"], minLength: 1, maxLength: 80 }
email: { type: [string, "null"], format: email }
dateOfBirth: { type: [string, "null"] }
gender:
oneOf:
- { type: "null" }
- { $ref: "#/components/schemas/Gender" }
heightCm: { type: [number, "null"], minimum: 50, maximum: 300 }
locale:
type: [string, "null"]
enum: [de, en, null]
timezone: { type: string, minLength: 1, maxLength: 64 }
DeviceRegisterInput:
type: object
properties:
token: { type: string, minLength: 8, maxLength: 512 }
bundleId: { type: string, minLength: 1, maxLength: 128 }
locale: { type: string }
appVersion: { type: string }
model: { type: string }
required: [token, bundleId]
IntakeUpdateInput:
type: object
properties:
intakeId: { type: string }
status:
type: string
enum: [taken, skipped, snoozed]
takenAt: { type: string, format: date-time }
snoozedUntil: { type: string, format: date-time }
required: [intakeId, status]
InsightRecommendation:
type: object
properties:
id: { type: string }
label: { type: string }
actionURL: { type: [string, "null"] }
required: [id, label]
InsightCard:
type: object
properties:
id: { type: string }
title: { type: string }
summary: { type: string }
body: { type: [string, "null"] }
severity: { $ref: "#/components/schemas/InsightSeverityIos" }
recommendations:
type: array
items: { $ref: "#/components/schemas/InsightRecommendation" }
generatedAt: { type: string, format: date-time }
provider: { type: string }
required:
[id, title, summary, severity, recommendations, generatedAt, provider]
InsightCorrelation:
type: object
properties:
id: { type: string }
leftMetric: { type: string }
rightMetric: { type: string }
coefficient: { type: number }
sampleSize: { type: integer }
required: [id, leftMetric, rightMetric, coefficient, sampleSize]
# ─── Admin DTOs ────────────────────────────────────────────
AdminUpdateUserInput:
type: object
properties:
username: { type: string, minLength: 3, maxLength: 30 }
email: { type: [string, "null"], format: email }
role: { $ref: "#/components/schemas/UserRole" }
Reference in new issue View Git Blame Copy Permalink