# QuestionsApi

STEP-style question bank service for study games and clients.

## Endpoints

- `GET /healthz` Health check.
- `GET /api/questions/systems` List available systems.
- `POST /api/questions/search` Search or build a block of questions.
- `GET /api/questions/admin/export` Cursor-paginated full-bank export (SUPER only).
- `GET /api/questions/{id}` Get one question.
- `POST /api/questions` Create question (SUPER only).
- `POST /api/questions/bulk` Upsert questions by `externalId` (SUPER only).
- `PUT /api/questions/{id}` Update question (SUPER only).
- `DELETE /api/questions/{id}` Delete question (SUPER only).
- `POST /api/question-reports` Submit a categorized question report (USER or SUPER).
- `GET /api/question-reports` List and filter reports, newest first (SUPER only).
- `GET /api/question-reports/{id}` Get a report and its question snapshot (SUPER only).
- `PATCH /api/question-reports/{id}/status` Resolve or dismiss an open report (SUPER only).

Player reads require `USER` or `SUPER` JWT auth. Authoring endpoints require `SUPER`.

## Answer tracking

The `QuestionAttempts` collection is the immutable source of truth and enforces
one first attempt per question and user with a unique compound index. Updated
clients submit the five choice IDs that were presented. Choice rates are the
percentage of presentations that resulted in selection, served from 32-way
materialized counter buckets and cached for up to five minutes. These rates are
independent and are not expected to sum to 100% when users see different
distractor subsets.

A background service snapshots the original choice IDs, backfills historical
attempts into v2 exposure counters, and reconciles recently active questions
every five minutes. The metric
`step3_answer_statistics_v2_backfill_complete` must equal `1` before adding
extra distractors to existing questions.

Search clients that set `supportsChoicePools: true` receive each complete
choice pool. Older clients receive five server-selected choices that always
include the correct answer. Published questions require 5-20 unique choices,
an explanation for every choice, and a follow-up for every incorrect choice.

- `GET /readyz` verifies MongoDB connectivity for readiness checks.
- `GET /metrics` exposes Prometheus-format service and reconciliation metrics.

The manifests in `k8s/` configure 2-10 API replicas. The cluster must have
Kubernetes Metrics Server installed before applying them with
`kubectl apply -k k8s/`.

Questions submitted through authoring endpoints must have authoritative direct
reference links recorded as described in the repository's **Question
Verification References** policy. The references must verify the keyed answer
and the material claims in the explanation; search-result links are not
acceptable.