{"openapi":"3.1.0","info":{"title":"American Airlines API (Bowmark)","version":"e833508f87ff","description":"American Airlines' own site — its published fares and award availability, flight status, reservation lookup, seat maps, baggage allowance and fee schedules. Flight status, reservation lookup and the published baggage allowance for a route are live and browserless; the rest are declared stubs.\n\nEvery function Bowmark has for American Airlines (aa.com) as one HTTP call. Each runs on Bowmark's infrastructure with the same billing, rules and response envelope as `POST /v1/run`. The whole API: https://api.bowmark.ai/openapi.json. Guide: https://bowmark.ai/docs/api.","contact":{"email":"support@bowmark.ai","url":"https://bowmark.ai/docs/api"}},"servers":[{"url":"https://api.bowmark.ai"}],"security":[{"bearer":[]},{"apiKeyHeader":[]}],"paths":{"/v1/sites/aa/getFlightStatus":{"post":{"operationId":"getFlightStatus","summary":"An American Airlines flight's live status.","description":"An American Airlines flight's live status. Pass `date` (the flight's ORIGIN date, ISO \"2026-08-04\") plus EITHER `flightNumber` (\"2005\", \"100\", or \"AA2005\" — American's own numbers are 1-4 digits) OR both `origin` and `destination` as IATA codes (\"DFW\", \"LAX\") to get every American NONSTOP on that route that day. Each flight comes back with American's own status wording and its stable status key (\"Arrived at gate\" / `flight.status.arrivedAtGate`), a severity colour, the canceled / diverted / inFlight / landed booleans, scheduled, estimated and actual times at both ends as ISO strings carrying each airport's own UTC offset, gate, terminal, city and baggage-claim belt, the aircraft type and tail number, codeshare and operating carrier, and American's passenger-facing disruption message when a flight is delayed or cancelled. Adding `origin`/`destination` alongside a `flightNumber` narrows it to that leg, which is how you disambiguate a number American flies twice in a day — and it is a real filter: a flight that does not fly the route you named comes back as an empty list rather than mislabelled. Route mode returns NONSTOPS only; American's own results page mixes connecting itineraries in beside the direct ones, and reporting a DFW-ORD leg as a DFW-LAX flight would be a confident lie. The date is NOT limited to the five days American's own picker offers — measured working from 8 days back to 200 days ahead. An empty `flights` list is an answer, not a failure: it means American flies no such flight that day.\n\nCalls `bowmark.providers.aa.getFlightStatus`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<aaFlightStatusResult>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"arg0":{}},"required":["arg0"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/aa/getBaggageAllowance":{"post":{"operationId":"getBaggageAllowance","summary":"American Airlines' published baggage allowance and fees for a ROUTE.","description":"American Airlines' published baggage allowance and fees for a ROUTE. `origin` and `destination` are COUNTRIES — an ISO-3166 alpha-2 code (\"US\", \"GB\") or a country name (\"United Kingdom\"), matched against American's own country list — because American prices bags by REGION and publishes its regions as lists of countries (\"Bag fees are based on these regions\"). An IATA airport code is refused with a message saying so rather than guessed at. Returns the fee row American's own table lands that trip on (which region, and whether it matched on the country or its region), the first, second, third and fourth-bag prices with every dollar figure printed in each cell plus its footnote markers, the checked-bag weight and size limits (50 lbs / 23 kgs, 62 in / 158 cm at the time of writing, with First/Business and Australia/New Zealand qualifications in `notes`), the carry-on and personal-item dimensions, the free-checked-bag entitlements by AAdvantage status, cabin and cardholder rule, how many bags American will accept on that trip at all, and the table's own footnotes verbatim. HONEST LIMITS, because they decide what this can be used for: a cell like \"$0 / $85*\" is TWO published prices and the footnotes say which of them a given fare and status pays — this function returns both rather than picking, since American's public pages do not price an individual ticket and no open surface on aa.com does either. It throws rather than guess for a trip where neither end is in American's domestic band (every row of the table describes the other end of such a trip), and for Cuba, which American prices from two separate direction-of-travel tables this function deliberately does not read as if they were the same one.\n\nCalls `bowmark.providers.aa.getBaggageAllowance`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<aaBaggageAllowance>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"arg0":{"$ref":"#/components/schemas/aaBaggageAllowanceArgs","description":"TypeScript: `aaBaggageAllowanceArgs`"}},"required":["arg0"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/aa/retrieveBooking":{"post":{"operationId":"retrieveBooking","summary":"Reads an existing American Airlines reservation by its six-letter record locator (PNR) and the passenger's last name — nothing is signed into, and both are the caller's own details, passed at call tim","description":"Reads an existing American Airlines reservation by its six-letter record locator (PNR) and the passenger's last name — nothing is signed into, and both are the caller's own details, passed at call time. Returns the record locator, American's own status string, when the booking was made, every passenger (name, passenger id, fare type, loyalty number, ticket numbers), and the itinerary as slices of flown segments (flight number, marketing and operating carrier codes, cabin, booking class, departure time, and each leg's origin/destination airport and city). Throws when the locator and last name do not both match a real reservation — American validates the pair together, so a real locator paired with the wrong last name answers exactly like one that does not exist at all; there is no way to tell those two cases apart from the outside. HONEST LIMIT: the not-found path is live-verified; the success shape above is reconstructed from American's own client code and has not been observed on the wire, since no consenting real booking was available to test it — see `retrieve-booking.ts` for what that means for field accuracy.\n\nCalls `bowmark.providers.aa.retrieveBooking`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<aaReservation>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"arg0":{"$ref":"#/components/schemas/aaRetrieveBookingArgs","description":"TypeScript: `aaRetrieveBookingArgs`"}},"required":["arg0"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Your Bowmark API key."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-Bowmark-Key"}},"responses":{"NotFound":{"description":"No such site or function.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}},"schemas":{"RunEnvelope":{"type":"object","description":"What a run returns. `status` says whether the SCRIPT succeeded. A script that threw or paused for a login is still HTTP 200. Branch on `status`, not on the HTTP code.","required":["ok","status","result","logs","error","ms"],"properties":{"runId":{"type":"string","description":"Stable id for this run. Quote it in a support or `report` message."},"ok":{"type":"boolean","description":"False only when the run produced nothing usable."},"status":{"type":"string","enum":["ok","error","partial","needs_user"],"description":"`partial`: the result is real but some calls failed (see `incomplete`); `ok` stays true. `needs_user`: a person must sign in to a site first. Relay `meta.handoff.url` to them, then run again."},"egress":{"type":"string","enum":["default","link"],"description":"The egress the run was given, present only when the request asked for one. `link`: every request went through the caller's own Chrome (Bowmark Buddy)."},"result":{"description":"Whatever the script `return`ed. Any JSON value."},"logs":{"type":"array","items":{"type":"string"},"description":"Lines the script wrote with `log(...)`."},"error":{"type":["string","null"],"description":"Why the run failed, in plain words. Null on success."},"ms":{"type":"integer","description":"How long the script itself ran, in milliseconds."},"queuedMs":{"type":"integer","description":"How long the run waited for a worker before starting. Present only when it was a second or more."},"needs":{"type":"array","description":"The sign-ins this script is waiting on. Present when `status` is `needs_user`.","items":{"type":"object","required":["capability","provider","providerTitle","kind"],"properties":{"capability":{"type":"string"},"provider":{"type":"string"},"providerTitle":{"type":"string","description":"The site's name, to show a person."},"kind":{"type":"string"}}}},"incomplete":{"type":"object","description":"Present only when `status` is `partial`: which calls did not answer.","properties":{"summary":{"type":"string"},"totalCalls":{"type":"integer"}},"additionalProperties":true},"emptyHanded":{"type":"object","description":"Present when the script returned nothing while its calls returned rows, usually a filter that matched none of the site's own labels. Lists the label values the calls actually returned.","additionalProperties":true},"notes":{"type":"array","description":"Caveats a call attached to a complete answer. Never changes `status`.","items":{"type":"object","properties":{"path":{"type":"string"},"notes":{"type":"array","items":{"type":"string"}}}}},"meta":{"type":"object","properties":{"handoff":{"type":"object","description":"A single-use sign-in link for a person to open. Expires at `expiresAt`.","properties":{"ref":{"type":"string"},"url":{"type":"string","format":"uri"},"expiresAt":{"type":"string","format":"date-time"}}},"concurrency":{"type":"object","description":"On a 429: how many runs are in flight and when to retry.","properties":{"limit":{"type":"integer"},"inFlight":{"type":"integer"},"retryAfterSeconds":{"type":"integer"}}}},"additionalProperties":true},"notice":{"type":"object","description":"Set when the account owner has not accepted the current Terms. Relay it to them.","additionalProperties":true}}},"aaBaggageAllowanceArgs":{"type":"object","properties":{"origin":{"type":"string"},"destination":{"type":"string"}},"required":["origin","destination"],"additionalProperties":true},"aaRetrieveBookingArgs":{"type":"object","properties":{"recordLocator":{"type":"string"},"lastName":{"type":"string"}},"required":["recordLocator","lastName"],"additionalProperties":true}}}}