# Flights API reference

Use this as compact context for the live bluedoor Flights API.

Primary URLs:

- API base URL: https://api.bluedoor.sh/flights/v1
- OpenAPI JSON: https://bluedoor.sh/apis/flights/docs/openapi.json
- Docs: https://bluedoor.sh/apis/flights/docs
- Landing page: https://bluedoor.sh/apis/flights

Production shape:

- Two layers fused: Google Flights breadth (every scheduled carrier, live price + schedule) joined with direct-carrier depth (fare-class/RBD ladders + numeric seats-remaining).
- Routes are use cases, not tables; usage is metered in credits per call (like LLM tokens), echoed in X-Credits-* response headers and meta.credits_charged.
- Success envelope: {"data": ..., "meta": ...}. Boundary errors (401/402/413): {"error": {code, message}, "meta": ...}. Handler errors (400/404/503): {"detail": {code, message}}. Schema errors: standard FastAPI 422.
- Anonymous calls allowed (small daily credit grant per IP). Self-serve keys: 100,000 credits/month, minted via email OTP (POST /v1/auth/otp then /v1/auth/verify). Send keys as x-api-key or Authorization: Bearer.
- Not a booking API.

Important public routes (credits per call):

- GET  /v1/                                    free — route catalog, credit costs, plans
- POST /v1/search                              5 + 10/live-depth carrier + 1/cached — itineraries + prices for an O&D/date, enrich=auto joins fare-class/seat depth
- GET  /v1/prices/cheapest-dates               3 — lowest fare per departure date over a window
- GET  /v1/prices/grid                         4 — depart-date × trip-length lowest-fare matrix
- GET  /v1/flights/{flight}/seats              2 cached / 15 live — RBD ladder + seats-remaining for one flight
- GET  /v1/flights/{flight}/history            2 — observed fare/seat snapshots over time (panel)
- GET  /v1/historical/flights/{carrier}/{num}  2 — alias of flight history
- POST /v1/itineraries/reprice                 2 + 2/itinerary — re-price itinerary_id tokens from /v1/search
- GET  /v1/deals                               10 + 0.5/destination — cheapest getaway per destination over a month
- GET  /v1/coverage/routes/{od}                1 — per-carrier depth tier + freshness for a route
- GET  /v1/usage                               free — your plan, balance, ledger
- GET  /v1/sources                             free — source roster + lineage
- POST /v1/auth/otp, /v1/auth/verify           free — self-serve API key issuance (email OTP)

Example:

```bash
curl -X POST "https://api.bluedoor.sh/flights/v1/search" \
  -H "x-api-key: YOUR_KEY" -H "content-type: application/json" \
  -d '{"origin": "SEA", "destination": "DCA", "depart_date": "2026-07-01", "enrich": "auto"}'
```