# FlightByte

> Flight intelligence, byte by byte. A flight status API with signed webhooks: look a flight up by carrier, number and date, or subscribe and receive every gate change, delay, departure and arrival at your endpoint.

Base URL: https://api.flightbyte.dev/v1. Authentication: the `x-api-key` header. Pricing: https://flightbyte.dev/pricing. Free key: https://app.flightbyte.dev/signup. Paid plans: by card in the dashboard, https://app.flightbyte.dev/plan. Custom plans: https://flightbyte.dev/get-api-key. Support: https://flightbyte.dev/contact, or @flightbyte on Telegram (https://t.me/flightbyte).

- Full documentation in one Markdown file: https://flightbyte.dev/llms-full.txt
- Any docs page as Markdown: its URL plus `.md` (for example https://flightbyte.dev/docs/webhooks.md), or the page URL requested with `Accept: text/markdown`
- OpenAPI document: https://flightbyte.dev/openapi.json
- Building with an AI coding assistant (prompt, AGENTS.md and Cursor rules, a Claude Code skill): https://flightbyte.dev/docs/ai

## Documentation

- [Introduction](https://flightbyte.dev/docs.md): What FlightByte does, the two requests most integrations are made of, and where to go next.
- [Quickstart](https://flightbyte.dev/docs/quickstart.md): Look a flight up, subscribe to it, receive and verify the first webhook.
- [Build with AI](https://flightbyte.dev/docs/ai.md): A prompt, rules files and a Claude Code skill that teach a coding assistant the API, and the whole documentation as Markdown.
- [Authentication and quotas](https://flightbyte.dev/docs/authentication.md): The API key header, the quota windows on every key, and what a 429 looks like.
- [Flights](https://flightbyte.dev/docs/flights.md): Looking flights up, choosing a leg when a number flies twice, the timeline, and how caching works.
- [Subscriptions](https://flightbyte.dev/docs/subscriptions.md): Watching a flight, what you can filter, the lifecycle of a subscription, and the logs behind it.
- [Webhooks](https://flightbyte.dev/docs/webhooks.md): The delivery format, every event and change type, how to verify signatures, and what retries look like.
- [Countries and flags](https://flightbyte.dev/docs/countries.md): Country names in any language, emoji, and SVG flags you can drop into a page.
- [Errors](https://flightbyte.dev/docs/errors.md): One error envelope for every failure, and what each status code means here.
- [API reference](https://flightbyte.dev/docs/reference.md): Every endpoint, generated from the API's OpenAPI document, with schemas, examples and a live playground.
- [List countries](https://flightbyte.dev/docs/reference/countries/list-countries.md): List every country with its flag URLs and emoji.
- [Get a country](https://flightbyte.dev/docs/reference/countries/get-country.md): Resolve a single ISO 3166-1 alpha-2 country code.
- [Get a flag](https://flightbyte.dev/docs/reference/countries/get-flag.md): Serve a country flag as SVG.
- [Search flights](https://flightbyte.dev/docs/reference/flights/search-flights.md): Serves from the Redis cache when fresh. Concurrent identical searches are coalesced into a single upstream call. When the flight number operates more than one leg that day, pass `origin` (and optionally `destination`) to pick one; without a selector the provider default is returned and every leg is listed under `alternates`.
- [Get a flight](https://flightbyte.dev/docs/reference/flights/get-flight.md): Fetch a single flight leg by its natural key.
- [Flight timeline](https://flightbyte.dev/docs/reference/flights/flight-timeline.md): Upstream change history for a flight leg, newest first.
- [List subscriptions](https://flightbyte.dev/docs/reference/subscriptions/list-subscriptions.md): List subscriptions, newest first.
- [Create a subscription](https://flightbyte.dev/docs/reference/subscriptions/create-subscription.md): Validates that the flight exists, seeds the change-detection baseline and starts adaptive polling. The signing secret is returned in full only here.
- [Get a subscription](https://flightbyte.dev/docs/reference/subscriptions/get-subscription.md): Fetch one subscription. The secret is masked.
- [Update a subscription](https://flightbyte.dev/docs/reference/subscriptions/update-subscription.md): Update the webhook URL, event filter or delay threshold.
- [Delete a subscription](https://flightbyte.dev/docs/reference/subscriptions/delete-subscription.md): Delete a subscription and stop polling if it was the last one.
- [Pause a subscription](https://flightbyte.dev/docs/reference/subscriptions/pause-subscription.md): Stop polling and delivering without losing the subscription.
- [Resume a subscription](https://flightbyte.dev/docs/reference/subscriptions/resume-subscription.md): Resume a paused or auto-suspended subscription.
- [Send a test event](https://flightbyte.dev/docs/reference/subscriptions/send-test-event.md): Send a signed test webhook to verify the receiver.
- [List deliveries](https://flightbyte.dev/docs/reference/subscriptions/list-deliveries.md): Recent webhook delivery attempts, newest first.
- [List sent events](https://flightbyte.dev/docs/reference/subscriptions/list-events.md): Recent events generated for this subscription.
- [Reveal the secret](https://flightbyte.dev/docs/reference/subscriptions/reveal-secret.md): Reveal the signing secret again.
- [Rotate the secret](https://flightbyte.dev/docs/reference/subscriptions/rotate-secret.md): Generate a new signing secret. Previous signatures stop validating.

## Guides

- [Building a flight delay notification system](https://flightbyte.dev/guides/building-a-flight-delay-notification-system): What "delayed" means in the data, who needs to hear it and when, the rules that keep a notifier quiet until it matters, a working Node reference with hysteresis, and the edge cases that show up in the first month.
- [Flight landed notification in 20 minutes with Node.js](https://flightbyte.dev/guides/flight-landed-notification-nodejs): A Node service that watches a passenger's flight and messages the driver when it lands, when it reaches the gate and when the bags come out. No polling loop, no cron, no dependencies.
- [TK1 flies twice a day: the flight number ambiguity nobody documents](https://flightbyte.dev/guides/flight-number-ambiguity): A flight number is not a flight. Some numbers operate two legs on one date, most APIs hand you both and let you guess, and the guess is silent. What the ambiguity looks like in the data, how FlightByte refuses to guess, and the three lines of code that handle it.
- [Flight status push notifications: one webhook, every device on the flight](https://flightbyte.dev/guides/flight-push-notifications-fan-out): How a travel app turns one signed webhook into the right push on every phone that cares. The table that maps flights to devices, a receiver that answers fast and sends later, copy per change type, collapse keys so a new gate replaces the old one, quiet rules, and driving an iOS Live Activity from the same event.
- [Flight status codes explained: S, A, L, C, D, R and what phase they map to](https://flightbyte.dev/guides/flight-status-codes-explained): The letter codes that airline status feeds use, what each one hides, how FlightByte turns them into a phase you can branch on, and how the same moments are named by aviationstack, AeroDataBox and AeroAPI.
- [From a booking email to a watched flight: lookup, legs, codeshares](https://flightbyte.dev/guides/from-booking-email-to-watched-flight): An itinerary app starts with whatever a confirmation email said. How to turn that into a flight record you can trust and a subscription you pay for once: what to parse, when a lookup can confirm it, how to pick the leg, how to stop two codeshare numbers becoming two watches, and when to subscribe.
- [How adaptive polling works: 3 minutes at the gate, 12 hours a week out](https://flightbyte.dev/guides/how-adaptive-polling-works): The function that decides when FlightByte next asks about a flight, as it runs in production. Why the phase decides after departure and the clock before it, what a flight costs in polls, and the safety nets around the queue.
- [Missed connection alerts from two subscriptions](https://flightbyte.dev/guides/missed-connection-alerts): A tight connection is not a property of either flight; it lives in the gap between them. How to compute that gap from two watched flights, choose a threshold per airport, handle terminals, early departures, cancellations and diversions, and keep the alert from firing every time an estimate moves by a minute.
- [Verifying webhook signatures the right way: raw body, timing-safe compare, replay window](https://flightbyte.dev/guides/verifying-webhook-signatures): A webhook is an unauthenticated POST from the internet. The signature is what makes it yours. The three ways verifiers go wrong, working code for seven frameworks, how to rotate a secret without dropping a delivery, and a checklist.
- [Why polling a flight API costs more than you think](https://flightbyte.dev/guides/why-polling-a-flight-api-costs-more-than-you-think): The loop every flight integration starts with, the five costs hiding in it, the arithmetic for 500 flights a month on request-priced APIs, and when polling is still the right call.

## Glossary

- [Baggage carousel assignment](https://flightbyte.dev/glossary/baggage-carousel): The belt in the arrivals hall where a flight's checked bags will appear, published by the airport, usually after the aircraft reaches the gate. Also called baggage claim, belt or reclaim.
- [Codeshare flight](https://flightbyte.dev/glossary/codeshare-flight): One aircraft sold under several flight numbers. The airline that flies it is the operating carrier; each airline that sells seats on it under its own number is a marketing carrier.
- [Connection, layover and minimum connection time](https://flightbyte.dev/glossary/connection-vs-layover): A connection is a change of aircraft on one journey, a layover is the time spent waiting for it, and the minimum connection time is the shortest gap an airport considers workable. Status data gives you the two flights; the gap between them is yours to compute.
- [Flight number vs flight ID](https://flightbyte.dev/glossary/flight-number-vs-flight-id): A flight number is a label an airline reuses every day, sometimes twice in one day. A flight ID names one leg on one date. Confusing the two is how a system watches the wrong aircraft.
- [Flight phase](https://flightbyte.dev/glossary/flight-phase): Where a flight is in its life, as one of ten values from scheduled to arrived, derived from the airline's status code and the times that exist. The field to branch on.
- [IATA vs ICAO codes](https://flightbyte.dev/glossary/iata-vs-icao-codes): Two code systems for the same airports and airlines. IATA codes are the short ones on tickets and boards (IST, TK); ICAO codes are the four-letter and three-letter ones used by air traffic control and flight plans (LTFM, THY).
- [Operating carrier vs marketing carrier](https://flightbyte.dev/glossary/operating-vs-marketing-carrier): The operating carrier flies the aircraft; a marketing carrier sells seats on it under its own flight number. A booking usually shows the marketing number, an airport board the operating one, and a status system has to know they are the same aircraft.
- [Scheduled, estimated and actual times](https://flightbyte.dev/glossary/scheduled-estimated-actual-times): Three answers to "when does the flight leave", each true at a different moment. Scheduled is the timetable, estimated is the airline's current expectation, actual is what happened.