{"openapi":"3.1.0","info":{"title":"Google Flights API (Bowmark)","version":"e833508f87ff","description":"Google Flights (flights.google.com) — itinerary search plus the per-result booking panel, read from each row's ARIA label.\n\nEvery function Bowmark has for Google Flights (flights.google.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/google_flights/parseSearchUrl":{"post":{"operationId":"parseSearchUrl","summary":"Reads the current trip (from, to, depart, return, cabin, passengers, stops) out of a Google Flights URL, in either spelling: the `?q=Flights from SFO to JFK on …` form or the encoded `?tfs=` form Goog","description":"Reads the current trip (from, to, depart, return, cabin, passengers, stops) out of a Google Flights URL, in either spelling: the `?q=Flights from SFO to JFK on …` form or the encoded `?tfs=` form Google rewrites the address bar to as soon as a person clicks anything. On a Google Flights page, `bowmark.providers.google_flights.parseSearchUrl({ url: location.href })` gives the page's trip, which you pass as-is to `search`, `getPriceGraph` or `bowmark.flights.search` (its `tripType`, `legs`, `currency`, `source` and `warnings` are accepted there and applied or reported: a one way trip that also has a `return` is refused, a multi-city trip searches leg 1 and names the dropped legs, a currency other than USD is warned about). Pure: no network, no browser. Returns null for a URL that is not a flights search. `warnings` names what could not be read exactly (a metro area such as NYC, a multi-city trip, children or infants in the passenger count).\n\nCalls `bowmark.providers.google_flights.parseSearchUrl`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<GoogleParsedSearch | null>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"type":"object","properties":{"url":{"type":"string"}},"required":["url"],"additionalProperties":true,"description":"TypeScript: `{ url: string }`"}},"required":["args"],"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/google_flights/search":{"post":{"operationId":"search","summary":"Runs the itinerary search and reads the rendered result rows.","description":"Runs the itinerary search and reads the rendered result rows. Interaction-gated: Google renders prices only after its own live query resolves, so this is not reachable as static HTML.\n\nCalls `bowmark.providers.google_flights.search`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<GoogleFlight[]>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"$ref":"#/components/schemas/GoogleFlightQuery","description":"TypeScript: `GoogleFlightQuery`"}},"required":["query"],"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":{"type":"array","items":{"$ref":"#/components/schemas/GoogleFlight"}}}}]}}}},"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/google_flights/getBookingOptions":{"post":{"operationId":"getBookingOptions","summary":"Selects one result from the same search and reads its booking panel — who actually sells the fare, at what fare type and price.","description":"Selects one result from the same search and reads its booking panel — who actually sells the fare, at what fare type and price. This is a second interaction (click into the row), not a field on the search result. A seller with a real link carries `checkout`, a handoff URL on that seller's own site the person opens to book themselves: Bowmark never books or pays.\n\nCalls `bowmark.providers.google_flights.getBookingOptions`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<GoogleBookingOption[]>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"row":{"$ref":"#/components/schemas/GoogleFlight","description":"TypeScript: `GoogleFlight`"}},"required":["row"],"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/google_flights/getPriceGraph":{"post":{"operationId":"getPriceGraph","summary":"Answers 'when is this route cheapest' in ONE call: the price for every departure date across roughly two months around the requested one, plus which date wins.","description":"Answers 'when is this route cheapest' in ONE call: the price for every departure date across roughly two months around the requested one, plus which date wins. The window is Google's own (about depart-7 to depart+52) and is not selectable. For a round trip Google slides a fixed-length stay, so each column carries the return date priced with it.\n\nCalls `bowmark.providers.google_flights.getPriceGraph`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<GooglePriceGraph>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"$ref":"#/components/schemas/GoogleFlightQuery","description":"TypeScript: `GoogleFlightQuery`"}},"required":["query"],"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}}},"GoogleFlight":{"type":"object","properties":{"id":{"type":"string"},"price":{"anyOf":[{"type":"number"},{"type":"null"}]},"currency":{"type":"string"},"tripType":{"anyOf":[{"const":"round trip"},{"const":"one way"}]},"airlines":{"type":"array","items":{"type":"string"}},"stops":{"type":"number"},"depart":{"type":"string"},"arrive":{"type":"string"},"durationMinutes":{"anyOf":[{"type":"number"},{"type":"null"}]},"url":{"type":"string"}},"required":["id","price","currency","tripType","airlines","stops","depart","arrive","durationMinutes"],"additionalProperties":true},"GoogleFlightQuery":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"depart":{"type":"string"},"return":{"type":"string"},"cabin":{"anyOf":[{"const":"economy"},{"const":"premium"},{"const":"business"},{"const":"first"}]},"stops":{"anyOf":[{"const":"any"},{"const":"nonstop"},{"const":"1"}]},"passengers":{"type":"number"},"tripType":{"anyOf":[{"const":"one way"},{"const":"round trip"},{"const":"multi-city"}]},"legs":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"date":{"type":"string"}},"required":["from","to","date"],"additionalProperties":true}},"currency":{"type":"string"},"source":{"anyOf":[{"const":"tfs"},{"const":"q"}]},"warnings":{"type":"array","items":{"type":"string"}}},"required":["from","to","depart"],"additionalProperties":true}}}}