FAQ

Is this API session-based?

No. There is no server-side session store, session cookie, or per-user login state. Auth is a single shared static bearer token (tds-stats-secure-token-2026) — anyone who has it has full access to every protected endpoint. The only server-side state, USER_CONTEXT, is a 5-minute, IP-keyed "last meeting queried" cache used purely so the dashboard can restore context — it holds no security meaning. See overview → Auth.

Which endpoints should an external integrator use?

The camelCase ones: /trainerStats, /jockeyStats, /meetingStats. They're documented at /api-docs, accept courseId only, and are the only endpoints that honor external_api.enabled. See api-reference.

Why are there two nearly-identical sets of trainer/jockey endpoints?

/trainer-stats//jockey-stats (kebab-case) always compute locally from the DB and accept either courseName or courseId. /trainerStats//jockeyStats//meetingStats (camelCase) are the newer "public" endpoints — courseId only, optional external-API bypass, and they update USER_CONTEXT. The kebab-case pair looks like the original implementation; the camelCase pair was added on top for external consumers rather than replacing it. See architecture for the full behavioral diff.

How do I get real database or external-API credentials?

Ask Thilina or Ryan. Never put real credentials in config.example.json — that file is the template only and has previously been found with real values checked in by mistake; always double-check before committing.

What happens if external_api.enabled is true but the external API is unreachable?

fetch_meeting_stats_from_external_api will raise (login/network errors propagate), which surfaces as a 500 from /trainerStats//jockeyStats//meetingStats — there's no automatic fallback to the local DB path once the external API is enabled and a call is attempted. Set external_api.enabled back to false to force the local path.

Does /trainerStats (camelCase) accept courseName like /trainer-stats does?

No — the camelCase endpoints only accept courseId (Query(..., alias="courseId"), required). Passing courseName to them has no effect; use /trainer-stats//jockey-stats if you only have a course name and not an ID.

Why does /trainer-stats?courseName=... (no courseId) sometimes return nothing?

There's an observed quirk in the underlying SQL where the "filter by course name" branch actually still filters on the integer course_id column. See the "Known quirk" note in database before assuming there's no data for a given date/course.

Where's the exhaustive reference if I need more detail than the wiki?

FULL_PROJECT_DOCUMENTATION.md in the repo root — a longer single-file writeup covering the same ground as this KB (overview, architecture, database, API reference) plus more prose explanation. It isn't automatically kept in sync with this KB.