API & Automation
Everything the TravStats web UI does, the REST API can do. Most self-hosters never touch it; some find it the most valuable feature of the lot.
When you’ll want it
Section titled “When you’ll want it”- Backups via API — fetch all your flights as JSON on a cron, store outside Postgres.
- AI agents and assistants — let your local Claude / ChatGPT instance read and write your travel history with a scoped token.
- Dashboards in Home Assistant / Grafana — pull stats endpoints into widgets next to your other home metrics.
- Bulk corrections — fix a misspelled airline across hundreds of flights in one script run.
- Mailbox sweepers — walk an IMAP folder, POST every booking confirmation through
/parse-email, never type a flight again. - Browser plugins — log a flight from any web page that knows the flight number.
- Migration tooling — read from another tool’s API, write into TravStats.
What’s available
Section titled “What’s available”The API surface mirrors the UI:
| Resource | Read | Write | Endpoint root |
|---|---|---|---|
| Flights | ✓ | ✓ | GET /api/v1/flights, POST /api/v1/flights, PUT /api/v1/flights/:id, DELETE /api/v1/flights/:id |
| Trips | ✓ | ✓ | GET /api/v1/trips, POST /api/v1/trips, etc. |
| Bookings | ✓ | ✓ | GET /api/v1/trips/bookings, etc. |
| Airports | ✓ | – | GET /api/v1/airports/search?q=… |
| Statistics | ✓ | – | GET /api/v1/stats/summary, …/routes, …/airlines, …/countries |
| Achievements | ✓ | – | GET /api/v1/achievements |
| Parsers | – | ✓ | POST /api/v1/parse-email, POST /api/v1/parse-boardingpass |
| Auth | – | ✓ | POST /api/v1/auth/register, …/login, …/logout |
| Personal Access Tokens | ✓ | ✓ | GET/POST /api/v1/settings/tokens, DELETE /api/v1/settings/tokens/:id |
| Admin | ✓ | ✓ | GET/POST /api/v1/admin/… (admin scope required) |
Two complementary references live on the running server:
- Swagger UI — interactive, click-to-call docs at
https://your-instance/api/v1/docs. Auto-generated from the same Zod schemas the API validates against. - Raw OpenAPI 3.0 JSON — at
https://your-instance/api/v1/openapi.json. Feed it to any OpenAPI-aware tooling: code generators, Postman, Bruno, etc.
Authentication
Section titled “Authentication”Two paths, same credentials:
| Mechanism | Set on | Used for |
|---|---|---|
| HttpOnly session cookie | Browser, after POST /auth/login | The web UI itself |
| Personal Access Token | Authorization: Bearer ts_pat_… header | Everything else (scripts, agents, integrations) |
Browser sessions stay in the cookie automatically; you don’t see them. For everything programmatic, use a Personal Access Token.
Rate limits
Section titled “Rate limits”Every endpoint has a rate limit. The defaults are friendly to typical UI use and not so friendly to runaway scripts:
| Bucket | Default limit |
|---|---|
| Login attempts | 5 / 15 min per IP |
| Flight creation | 30 / hour per user |
| Email parser | 60 / hour per user |
| Boarding pass parser | 30 / hour per user |
| General authenticated reads | 1000 / hour per user |
| Admin endpoints | 100 / hour per user |
Personal Access Tokens get their own bucket per token —
pat:<token-id> — so an aggressive script can’t lock the owning
user out of the web UI. If you’re hitting limits, either tune them
in the source or split your script into multiple tokens.
Pages in this section
Section titled “Pages in this section”- Personal Access Tokens — Mint a token, pick the right scope (
read/write/admin), use it from a script. Includes example curl, Python and Node.js snippets. - REST API reference — A practical walkthrough of the endpoints you’ll use most: pagination, the (
local,timezone) write contract, the merge-on-create flag, the parser endpoints. Pointer to Swagger UI for the rest.