# Train Badger for AI agents

> Point an AI agent at Train Badger's Delay Repay data: pre-register the trains your user will take, poll for claimable outcomes, file each claim on the operator's own website, and mark it filed. v1 beta — shapes may change, no SLA.

This is the machine-readable twin of https://trainbadger.app/for-agents. Short pointer: https://trainbadger.app/llms.txt. Full guide: https://trainbadger.app/llms-full.txt. Human API reference: https://trainbadger.app/api-docs. Contract: https://trainbadger.app/api-docs/openapi.json.

## 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 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.
1. **Track.** Before each scheduled departure, pre-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.
2. **Poll.** 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.** 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.** 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.

Public lookups (no auth): `GET /public/journey-check`, `GET /public/delay-repay/{operator}`, `GET /public/crs/{query}`.

Your own account data (Bearer [REDACTED] — agents use a scoped `tb_live_` key): `GET /api/journeys`, `GET /api/journeys/claim-summary`, `PUT /api/journeys/{id}/claimed`, `GET /api/keys`, `POST /api/keys`, `DELETE /api/keys/{id}`, `POST /api/tracked-journeys`, `GET /api/tracked-journeys`, `GET /api/tracked-journeys/{id}`, `PATCH /api/tracked-journeys/{id}`, `DELETE /api/tracked-journeys/{id}`, `GET /api/account/export` (login token only, like the `/api/keys` routes).

## 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] header; 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 are long-lived, revocable, scoped (`delay-repay:read`, `delay-repay:write`, `delay-repay:track`), stored hashed, 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: https://trainbadger.app/terms. 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.