Admin

Tenant-admin operations (Admin or TrialAdmin role).

📄️List tenant email domains

Returns all known email domains for the tenant (for personalization placeholders and malicious-sender flagging). Requires Admin or TrialAdmin role.

📄️Add an email domain

Inserts a new domain. If a row with the same `domain` already exists the request is a no-op and returns `200` with `{ message }`; otherwise `201` with the new row. Requires Admin or TrialAdmin role.

📄️Delete an email domain

Removes a domain by its `domain` value. Requires Admin or TrialAdmin role.

📄️Get tenant config

Returns the single config row (or `null` if none exists). `max_templates_per_wave` is always normalized to 10. Requires Admin or TrialAdmin role.

📄️Create tenant config

Inserts the initial config row. Errors with 400 if a row already exists — use PUT to update. Requires Admin or TrialAdmin role.

📄️Update tenant config

Partial update of the existing config row. Pass `logo_base64: null` to clear the logo. Requires Admin or TrialAdmin role.

📄️Clear tenant logo

Sets `logo_base64` to NULL on the existing config row. Requires Admin or TrialAdmin role.

📄️List templates (paginated)

Returns templates enriched with S3 metadata (subject/sender/topics). Supports topic and free-text search. Optional `withTopicSync=true` backfills topics from S3 into the DB. Requires Admin or TrialAdmin role.

📄️Toggle template enabled/disabled

Flips the `is_enabled` flag for the given template id. Requires Admin or TrialAdmin role.

📄️List topics with template counts

Returns each topic with its total and enabled template counts. Requires Admin or TrialAdmin role.

📄️Get template (or feedback) JSON

Returns the resolved template payload from S3 for the requested language. `mode=feedback` returns the post-swipe feedback variant. Requires Admin or TrialAdmin role.

📄️List available languages for a template

Returns one entry per language with `hasFeedback` set from a runtime S3 HeadObject. The DB column alone is not trustworthy (a CHECK constraint forces it non-null even when the S3 file does not yet exist). Requires Admin or TrialAdmin role.

📄️Bulk enable/disable templates by topic

Flips `is_enabled` for every template linked to the given topic. Requires Admin or TrialAdmin role.

📄️Analytics overview

Headline totals (users, active-this-wave, avg score) plus a per-week growth series for the requested timeframe. Requires Admin or TrialAdmin role.

📄️Analytics insights (admin dashboard)

Funnel + segment cohorts (high-risk, inactive, improving, declining), top/bottom leaderboards, retention and topic-risk for the requested timeframe. Returns a `insights_partial_failure` body on internal errors instead of 500. Requires Admin or TrialAdmin role.

📄️Per-wave participation + scores

Recent waves with participants, avg_score and total_users. Falls back to the Cognito user count for total_users when per-wave assignments cannot be computed. Requires Admin or TrialAdmin role.

📄️Per-season participation + scores

Recent seasons with participants and avg_score (computed from swipes). Requires Admin or TrialAdmin role.

📄️Top + bottom leaderboard

`scope=wave` uses the active wave; `scope=season` (default) uses the active season. Each row is enriched with display name + email from Cognito. Requires Admin or TrialAdmin role.

📄️Inactive users for a single wave

Users assigned to the wave who have no swipe row yet. Defaults to the active wave; pass `wave_id` for a specific one. Requires Admin or TrialAdmin role.

📄️Inactive users across recent waves

For each recent wave returns total_assigned / played / inactive counts. Optional `includeUsers=true` adds enriched per-wave user lists. `assigned=directory` uses Cognito as the assigned set. Requires Admin or TrialAdmin role.

📄️Template-ready export bundle

A single response shaped for downstream report generation: overview totals, users summary + detail, templates summary, top-incorrect, topic weaknesses, user progress, inactive users, and wave performance. Requires Admin or TrialAdmin role.

📄️List tenant users

Returns Cognito users joined with per-user RDS metrics (lastLogin, score, activity flags). Supports search + bucketed filters + sort. Requires Admin or TrialAdmin role.

📄️Onboard a single user

Creates the Cognito user (if new), sends invite email when `sendReset=true`, and consumes a license. Refused with 409 once the license limit is reached. Requires Admin or TrialAdmin role.

📄️Send reminder emails to inactive users

Sends localized 'continue your training' emails to users who have not played in the active wave. `mode=selected` filters to the provided `userIds`/`emails` set; otherwise targets every inactive user. Requires Admin or TrialAdmin role.

📄️Get full user details

Identity (Cognito attributes + groups), activity (recency + sessions), performance (totals, current wave/season, trend), and risk-learning signals (hardest topics, wrong items). Requires Admin or TrialAdmin role.

📄️Export user swipe history

Returns the user's full swipe history as CSV (default) or JSON. Each row carries created_at, template metadata, wave/season context and the swipe outcome. Requires Admin or TrialAdmin role.

📄️Bulk-import users from CSV

Multipart upload. Streams the CSV and onboards each row through Cognito + license accounting. Stops counting against the license limit once exhausted (existing users still re-process). Returns per-row successes + failures. Requires Admin or TrialAdmin role.

📄️Send a password reset email

Triggers a Cognito password-reset email for the given user email via SES. Requires Admin or TrialAdmin role.

📄️Delete a user

Removes the user from Cognito and clears the email→tenant mapping in DynamoDB. Requires Admin or TrialAdmin role.

📄️Get trial config

Returns the persisted trial config (or null). Requires TrialScheduler role.

📄️Save trial config

`default` mode requires `default_start_at_iso`; `custom` mode requires a `custom_plan` array. Requires TrialScheduler role.

📄️Trial overview

Returns whether the trial is currently active, plus the most recent trial season (scheduled/active/ended). Requires TrialScheduler role.

📄️Activate or deactivate the trial

Activating cancels existing trial seasons, then schedules new ones from the saved config (default anchor or custom plan). Requires TrialScheduler role.

📄️Schedule overview

Composite view: active/scheduled seasons, automation config, etc. Requires Admin or TrialAdmin role.

📄️List upcoming scheduled seasons

Returns seasons in `scheduled` state, ordered by start. Requires Admin or TrialAdmin role.

📄️Next scheduled season

Returns the soonest scheduled season (or null). Requires Admin or TrialAdmin role.

📄️Get automation config

Current scheduler automation config (enabled, gap, wave shape, anchor). Requires Admin or TrialAdmin role.

📄️Update automation config

`auto_start_anchor_iso` cannot be before the end of the currently active season.

📄️Schedule a new season (manual)

Refused (400) when `auto_enabled=true` in tenant config — disable automation first. Requires Admin role.

📄️Update a scheduled season

Patches start time and/or wave shape on a season still in `scheduled` state. Requires Admin role.

📄️Cancel a scheduled season

Cancels a season still in `scheduled` state. Active/ended seasons cannot be cancelled. Requires Admin role.