Mini-game State and History

Use these two read-only endpoints together to support spin wheels, streaks, and quiz history without confusing current availability with past events.

WARNING

Both calls are server-to-server. Use a Community API key with customerSuccess, and never expose it to a browser or mobile client.

Which endpoint should I use?

Question	Endpoint
How many spins are available now?	Get current mini-game and streak state
Is the current wheel mission cleared?	Get current mini-game and streak state
Has the user spun during the current UTC day?	Get current mini-game and streak state
When was a spin earned, used, or expired?	List mini-game logs by user email
Why did a streak change?	Current state first, then logs for chronology
Did an admin adjustment occur?	Logs, filtered locally for `admin-updated`

1. Read current state first

Send the user's email to /v1/users/mini-game-streak-stats. The response includes active spin wheels and configured streaks. Match by name, because array order is not guaranteed.

Interpret the wheel fields independently:

spins is the number of currently available spins.

missionCleared describes the latest mission activity that has not expired.

spinToday means at least one spin result exists during the current UTC day.

currentStreak is the stored streak counter.

These values can differ legitimately. For example, a user may have cleared a mission but already used the resulting spin.

2. Read history when the state needs explanation

Call /v1/mini-game-logs/by-email with a small page size. Page 1 is newest first. Follow the relevant gameName and action sequence:

spin-earned adds historical evidence that a spin became available;

spin-used shows consumption;

spin-expired shows an unused spin expired;

streak-earned and streak-broken explain streak transitions;

admin-updated marks a manual adjustment;

quiz actions record quiz lifecycle outcomes.

Fields are action-specific. Do not require reward, mission, spin, streak, or admin fields on every row.

3. Treat time consistently

spinToday uses the UTC day. Log timestamps are UTC ISO-8601 values. Compare createdAt, expiresAt, and expiredAt in UTC before diagnosing a missing or expired spin.

Mission windows can be daily, weekly, or monthly. A previously completed mission does not keep missionCleared true after its activity expires.

4. Handle empty results correctly

Current state can return empty arrays when no wheels or streaks are configured.

A configured wheel can return 0 and false values.

Logs can return 200 with an empty list and totalPages: 0.

An unresolved email returns 404.

An empty result is community-scoped. Do not use it to claim that the identity or activity does not exist globally.

5. Troubleshooting checklist

Confirm the API key belongs to the intended community and has customerSuccess.

Confirm the email is valid; matching is case-insensitive.

Read current state and record the exact wheel/streak name.

Read logs page 1 and follow the matching game's events.

Paginate only when the target period is older.

Compare all dates in UTC.

Use the business system that drives the mission to explain eligibility; do not infer it from the mini-game APIs alone.

Escalate before any manual correction. These two endpoints are read-only and should remain the verification path before and after an approved change.

Acceptance checks

A complete integration test should cover:

authenticated success with configured data;

success with empty logs;

success with empty configuration;

default and explicit pagination;

invalid email and pagination boundaries;

unresolved email;

key without customerSuccess;

correlation of one earned/used/expired sequence with the current state;

UTC day-boundary behavior for spinToday.

Which endpoint should I use?#

1. Read current state first#

2. Read history when the state needs explanation#

3. Treat time consistently#

4. Handle empty results correctly#

5. Troubleshooting checklist#

Acceptance checks#

Which endpoint should I use?

1. Read current state first

2. Read history when the state needs explanation

3. Treat time consistently

4. Handle empty results correctly

5. Troubleshooting checklist

Acceptance checks