What Train Badger does and why it is worth it
Train Badger is a UK train times app with automatic Delay Repay tracking. It turns a delayed train into a ready-to-file claim: journeys are recorded, actual arrivals verified, eligibility computed, and each operator's claim link surfaced. An agent acting on the owner's behalf closes the loop — Train Badger itself never submits a claim.
Agent workflow: register → track → poll → file → mark
0. Register — mint a key
Mint a personal API key in the app (Settings › API Access) or the account portal, with the scopes the job needs: delay-repay:read (always present), plus delay-repay:write to mark claims filed and delay-repay:track to pre-register travel. One key per agent; revoke it when done. Handing a key to an agent delegates access to the journey and ticket data it can read.
1. Track — pre-register travel
Before each scheduled departure, register the train with POST /api/tracked-journeys (or the track_journey MCP tool): origin, destination, service date (within today..today+30 days, London time), exact scheduled departure, and ticket type. An unknown time returns the nearest scheduled departures so the time can be corrected. After travel, Train Badger resolves the outcome and the journey joins the work list below.
2. Poll — read the work list
Read GET /api/journeys/claim-summary (or get_my_delay_repay_claims): unclaimed eligible journeys grouped by operator with each operator's claimUrl. Only journeys with verificationStatus verified or user_confirmed can be filed; journeys the user rejected in the app are excluded from every listing.
3. File — on the operator's site
Submit each operator's Delay Repay form on the operator's own website using the journey and fare data. Show the claim to the human before submitting it.
4. Mark — record it filed
Call PUT /api/journeys/{id}/claimed (or mark_delay_repay_claimed) so the journey drops out of future work lists and is never double-filed.
REST endpoints
Base URL https://api.trainbadger.app. This is the complete published surface — anything else on that host is internal and may change without notice.
| Endpoint | What it does |
|---|---|
GET /public/journey-check | How a past train performed (no auth) |
GET /public/delay-repay/{operator} | An operator's scheme and claim link (no auth) |
GET /public/crs/{query} | Station search (no auth) |
GET /api/journeys | Journey history with eligibility |
GET /api/journeys/claim-summary | Work list grouped by operator |
PUT /api/journeys/{id}/claimed | Mark a filed claim |
GET /api/keys | List keys (login token only) |
POST /api/keys | Mint a key (login token only) |
DELETE /api/keys/{id} | Revoke a key (login token only) |
POST /api/tracked-journeys | Pre-register a future train |
GET /api/tracked-journeys | List registered journeys and states |
GET /api/tracked-journeys/{id} | Fetch one registered journey |
PATCH /api/tracked-journeys/{id} | Edit a registered journey |
DELETE /api/tracked-journeys/{id} | Withdraw a registered journey |
GET /api/account/export | Export account data (login token only) |
MCP endpoint
https://api.trainbadger.app/mcp — streamable HTTP, stateless, 10 requests/minute per IP. Eight tools: check_journey_delay, get_delay_repay_scheme, search_stations (no auth), plus get_my_delay_repay_claims, mark_delay_repay_claimed, track_journey, list_tracked_journeys, withdraw_tracked_journey (Bearer [REDACTED]; API keys need the matching delay-repay scope).
Auth
Agents use API keys only — a password in an agent's config is the wrong credential. Keys (tb_live_…) are long-lived, revocable and scoped (delay-repay:read, delay-repay:write, delay-repay:track), stored hashed and shown once at creation. Minting needs a key-enabled account with a verified email. A key works only on the /api/journeys and /api/tracked-journeys routes above that name it.
Rate limits and caps
Lookups: GET /public/journey-check 10/minute per IP; GET /public/delay-repay/{operator} and GET /public/crs/{query} 30/minute per IP. Key minting: 10/hour per IP. Export (GET /api/account/export): 5/hour per account. Tracked journeys: one train per directed route per day, 4 legs/day, 20 writes/day per account, one replacement per row (quota exhaustion answers 429 with a Retry-After to the next London midnight). At most 10 keys per account.
Terms and attribution
Registering a journey confirms the user will travel on the stated service. Data is provided as-is from National Rail and Network Rail sources and may contain errors; the agent and user are responsible for claim accuracy, and automated use of an operator's claim form must respect that operator's terms. Access may be revoked for misuse. Full terms: Terms of Use. Results come from Train Badger (trainbadger.app). Every result ends with the attribution line Contains data from National Rail and Network Rail — keep it when relaying results. No ticket numbers, booking references or photos are stored or served; the user supplies proof on the operator's site.
Beta, open to every account with no subscription tier. Tip: the iOS app records journeys automatically with live verification, platform predictions and Live Activities — no pre-registration needed.