HTTP API

/api/* is served directly by Bun (src/server/api.ts) so it stays available even when the Next.js subprocess is down. Every route delegates to a framework-agnostic core under src/api/* that the equivalent Next.js routes also import — Bun and Next behave identically.

CORS is enabled (Access-Control-Allow-Origin: *); no auth (staging only).

Base URL

In Postman, the DOBBY_SERVER collection variable points at this base.

Conventions

• All bodies are JSON. Set Content-Type: application/json.
• All dates are ISO YYYY-MM-DD (UTC).
• Stations are UIC codes (e.g. 7015400 for London St Pancras). The MCP tool eurostar_list_stations is the easiest way to look these up; the STATIONS source is the authoritative list.
• Errors return JSON { "success": false, "error": "..." } (or { "error": "..." } on routes that don't carry a success flag) plus an HTTP status code.

Endpoints

GET /health

Server health + version. (/healthz is kept as a quiet alias for backward compatibility - some Google front-ends reserve /healthz for platform checks and don't pass it through.)

curl http://localhost:4242/health

Response:

{
  "ok": true,
  "name": "booking-bot",
  "version": "1.0.38",
  "uptimeSeconds": 1234
}

POST /api/booking

Create a staging booking. Drives the full pipeline: journey search → cart → hold → checkout. Synchronous; 10–30 s typical.

Request body — BookingRequest (see app/types/api.ts for the source of truth):

Example:

curl -X POST http://localhost:4242/api/booking \
  -H "content-type: application/json" \
  -d '{
    "origin": "7015400",
    "destination": "8727100",
    "outboundDate": "2026-12-01",
    "passengers": {
      "adults": 1, "children": 0, "seniors": 0, "youths": 0, "infants": 0,
      "adultsWheelchair": 0, "childrenWheelchair": 0, "wheelchairCompanions": 0, "guideDogs": 0
    },
    "market": "uk-en",
    "outClass": ["STANDARD"]
  }'

Success response (HTTP 200) — BookingResponse (see app/types/api.ts):

{
  "success": true,
  "bookingReference": "ABC123",
  "cartId": "kNWbdOYLr6j4wGXE",
  "links": { "myb": "https://...", "voyager": "https://..." },
  "timings": { "search": 616, "createCart": 71, "holdCart": 519, "checkout": 1234 },
  "selectedJourney": {
    "outbound": {
      "legs": [
        {
          "origin": "London St Pancras Int'l",
          "destination": "Paris Gare du Nord",
          "departureDate": "2026-12-01",
          "departureTime": "18:01",
          "arrivalTime": "21:17",
          "trainNumber": "9046",
          "classOfService": "STANDARD"
        }
      ],
      "totalPrice": 56.5
    }
  }
}

Error responses:

POST /api/search-link

Build a deep-link URL into eurostar.com that opens the same search the booking would run. Useful for "preview the journey before booking it".

Request body: identical to /api/booking.

Example:

curl -X POST http://localhost:4242/api/search-link \
  -H "content-type: application/json" \
  -d '{ "origin": "7015400", "destination": "8727100", "outboundDate": "2026-12-01",
        "passengers": { "adults": 1, "children": 0, "seniors": 0, "youths": 0, "infants": 0,
                        "adultsWheelchair": 0, "childrenWheelchair": 0, "wheelchairCompanions": 0, "guideDogs": 0 },
        "market": "uk-en" }'

Success response (HTTP 200):

{ "url": "https://staging.eurostar.com/search/uk-en?origin=7015400&destination=8727100&outbound=2026-12-01&adult=1" }

Error responses:

POST /api/cancel

Cancel an existing staging booking by reference + surname. Mirrors the CLI's --cancel --pnr <X> --surname <Y> flow — and is the endpoint the Web UI's Advanced → Cancel form calls.

Request body — CancelRequest (see app/types/api.ts):

Example:

curl -X POST http://localhost:4242/api/cancel \
  -H "content-type: application/json" \
  -d '{ "reference": "ABC123", "lastName": "Smith", "market": "uk-en", "method": "CC" }'

Success response (HTTP 200) — CancelResponse:

{
  "success": true,
  "reference": "ABC123",
  "result": { "kind": "card", "bookingReference": "ABC123", "lastName": "Smith" },
  "timings": { "bookingLogin": 412, "bookingBySession": 230, "refundProposal": 318, "refund": 905 }
}

For voucher refunds, result.kind is "voucher" and the payload includes value and voucher.{reference,expiryDate}.

Error responses:

GET /api/checkout-vars

Status of the local variables/checkout.json file used in the final checkout mutation. Used by the UI's "are we ready to book?" indicator.

Response (HTTP 200):

{
  "exists": true,
  "fresh": true,
  "contentValid": true,
  "valid": true,
  "age": 12345,
  "debug": {
    "resolvedPath": "/Users/me/.booking-bot/variables/checkout.json",
    "homePath":     "/Users/me/.booking-bot/variables/checkout.json",
    "cwdPath":      "/Users/me/eil/booking-bot/variables/checkout.json",
    "homeExists":   true,
    "cwdExists":    false,
    "resolvedExists": true,
    "cwd": "/Users/me/eil/booking-bot"
  }
}

POST /api/checkout-vars/refresh

Server-Sent Events stream that spawns bun refresh (Playwright) and forwards parsed progress events. Used by the UI's "Refresh credentials" button.

Request body (all fields optional):

{ "showBrowser": false, "forceRefresh": true }

Response: Content-Type: text/event-stream. Each line is data: <JSON>\n\n where the JSON has a type discriminator:

Example:

curl -N -X POST http://localhost:4242/api/checkout-vars/refresh \
  -H "content-type: application/json" \
  -d '{ "showBrowser": false, "forceRefresh": true }'

data: {"type":"status","message":"Starting refresh process..."}

data: {"type":"status","message":"Searching for journeys..."}

data: {"type":"status","message":"Cart created, starting browser..."}

data: {"type":"complete","success":true,"message":"Credentials refreshed successfully"}

Errors: delivered as { "type": "error", "message": "..." } events on the stream itself. The HTTP status is always 200 once the stream starts.

OPTIONS / CORS

Every /api/* route accepts OPTIONS and replies with the CORS preflight headers:

Access-Control-Allow-Origin:  *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type

Other unified-server routes

These aren't /api/* but they're part of the same server — see server.md for the full routing table: