openapi: 3.0.3
info:
  title: FlightLabs Aircraft Flights API
  description: 'Real-time and historical flight tracker and status API providing live data for flights, airports, schedules, timetables, IATA codes, airline routes, and flight pricing globally. Operated by Zyla Labs, FlightLabs offers 16+ endpoints covering live flights, flight delays, future predictions, airline routes, and flight pricing.

    '
  version: '1.0'
  contact:
    name: FlightLabs Support
    email: hello@goflightlabs.com
    url: https://www.goflightlabs.com
  termsOfService: https://www.goflightlabs.com/terms
  license:
    name: Commercial
    url: https://www.goflightlabs.com/pricing
servers:
- url: https://app.goflightlabs.com
  description: FlightLabs Production API
security:
- AccessKey: []
tags:
- name: Flights
  description: Real-time and historical flight data endpoints
paths:
  /flights:
    get:
      operationId: getRealTimeFlights
      summary: Real-Time Flights
      description: 'Retrieve real-time live flight information for active flights globally. Returns live aircraft positions, flight status, departure/arrival information, and more.

        '
      tags:
      - Flights
      parameters:
      - $ref: '#/components/parameters/AccessKey'
      - $ref: '#/components/parameters/Limit'
      - name: flightIata
        in: query
        description: Filter by flight IATA code (e.g. AA100)
        required: false
        schema:
          type: string
          example: AA100
      - name: flightIcao
        in: query
        description: Filter by flight ICAO code (e.g. AAL100)
        required: false
        schema:
          type: string
          example: AAL100
      - name: flightNum
        in: query
        description: Filter by flight number only (e.g. 100)
        required: false
        schema:
          type: string
          example: '100'
      - name: airlineIata
        in: query
        description: Filter by airline IATA code (e.g. AA)
        required: false
        schema:
          type: string
          example: AA
      - name: airlineIcao
        in: query
        description: Filter by airline ICAO code (e.g. AAL)
        required: false
        schema:
          type: string
          example: AAL
      - name: depIata
        in: query
        description: Filter by departure airport IATA code
        required: false
        schema:
          type: string
          example: JFK
      - name: depIcao
        in: query
        description: Filter by departure airport ICAO code
        required: false
        schema:
          type: string
          example: KJFK
      - name: arrIata
        in: query
        description: Filter by arrival airport IATA code
        required: false
        schema:
          type: string
          example: LAX
      - name: arrIcao
        in: query
        description: Filter by arrival airport ICAO code
        required: false
        schema:
          type: string
          example: KLAX
      - name: regNum
        in: query
        description: Filter by aircraft registration number
        required: false
        schema:
          type: string
          example: N12345
      - name: hex
        in: query
        description: Filter by aircraft ICAO24 hex code
        required: false
        schema:
          type: string
          example: a1b2c3
      responses:
        '200':
          description: Successful response with real-time flight data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlightsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /flights-callsign:
    get:
      operationId: getFlightsByCallsign
      summary: Flights with CallSign
      description: 'Look up active flights by callsign or airline ICAO code. Returns real-time flight status for the matched aircraft.

        '
      tags:
      - Flights
      parameters:
      - $ref: '#/components/parameters/AccessKey'
      - $ref: '#/components/parameters/Limit'
      - name: callsign
        in: query
        description: Aircraft callsign to search for
        required: false
        schema:
          type: string
          example: AAL100
      - name: airlineIcao
        in: query
        description: Airline ICAO code to filter results
        required: false
        schema:
          type: string
          example: AAL
      responses:
        '200':
          description: Successful response with flight data by callsign
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlightsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /historical-flights:
    get:
      operationId: getHistoricalFlights
      summary: Historical Flights
      description: 'Retrieve historical flight data for past departures and arrivals within a specified date range.

        '
      tags:
      - Flights
      parameters:
      - $ref: '#/components/parameters/AccessKey'
      - $ref: '#/components/parameters/Limit'
      - name: flightIata
        in: query
        description: Flight IATA code
        required: false
        schema:
          type: string
          example: AA100
      - name: flightIcao
        in: query
        description: Flight ICAO code
        required: false
        schema:
          type: string
          example: AAL100
      - name: airlineIata
        in: query
        description: Airline IATA code
        required: false
        schema:
          type: string
          example: AA
      - name: depIata
        in: query
        description: Departure airport IATA code
        required: false
        schema:
          type: string
          example: JFK
      - name: arrIata
        in: query
        description: Arrival airport IATA code
        required: false
        schema:
          type: string
          example: LAX
      - name: dateFrom
        in: query
        description: Start date for historical query (YYYY-MM-DD)
        required: false
        schema:
          type: string
          format: date
          example: '2026-01-01'
      - name: dateTo
        in: query
        description: End date for historical query (YYYY-MM-DD)
        required: false
        schema:
          type: string
          format: date
          example: '2026-01-31'
      responses:
        '200':
          description: Successful response with historical flight data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlightsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /schedules:
    get:
      operationId: getFlightSchedules
      summary: Flights Schedules
      description: 'Retrieve current and upcoming scheduled flights for airports, including departures and arrivals with times, terminals, and status.

        '
      tags:
      - Flights
      parameters:
      - $ref: '#/components/parameters/AccessKey'
      - $ref: '#/components/parameters/Limit'
      - name: depIata
        in: query
        description: Departure airport IATA code
        required: false
        schema:
          type: string
          example: JFK
      - name: arrIata
        in: query
        description: Arrival airport IATA code
        required: false
        schema:
          type: string
          example: LAX
      - name: airlineIata
        in: query
        description: Airline IATA code
        required: false
        schema:
          type: string
          example: AA
      - name: flightIata
        in: query
        description: Flight IATA code
        required: false
        schema:
          type: string
          example: AA100
      - name: type
        in: query
        description: Schedule type - departure or arrival
        required: false
        schema:
          type: string
          enum:
          - departure
          - arrival
      responses:
        '200':
          description: Successful response with schedule data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchedulesResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /future-flights:
    get:
      operationId: getFutureFlights
      summary: Future Flights Prediction
      description: 'Retrieve predicted flight schedules for future dates (7+ days ahead). Useful for planning and forecasting.

        '
      tags:
      - Flights
      parameters:
      - $ref: '#/components/parameters/AccessKey'
      - $ref: '#/components/parameters/Limit'
      - name: depIata
        in: query
        description: Departure airport IATA code
        required: false
        schema:
          type: string
          example: JFK
      - name: arrIata
        in: query
        description: Arrival airport IATA code
        required: false
        schema:
          type: string
          example: LAX
      - name: airlineIata
        in: query
        description: Airline IATA code
        required: false
        schema:
          type: string
          example: AA
      - name: date
        in: query
        description: Future date (YYYY-MM-DD)
        required: false
        schema:
          type: string
          format: date
          example: '2026-07-01'
      responses:
        '200':
          description: Successful response with future flight predictions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchedulesResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /flight-delay:
    get:
      operationId: getFlightDelay
      summary: Flight Delay
      description: 'Retrieve flights that are delayed beyond specified thresholds. Returns scheduled vs actual times for delayed departures and arrivals.

        '
      tags:
      - Flights
      parameters:
      - $ref: '#/components/parameters/AccessKey'
      - $ref: '#/components/parameters/Limit'
      - name: type
        in: query
        description: Delay type - departure or arrival
        required: false
        schema:
          type: string
          enum:
          - departure
          - arrival
      - name: depIata
        in: query
        description: Departure airport IATA code
        required: false
        schema:
          type: string
          example: JFK
      - name: arrIata
        in: query
        description: Arrival airport IATA code
        required: false
        schema:
          type: string
          example: LAX
      - name: airlineIata
        in: query
        description: Airline IATA code
        required: false
        schema:
          type: string
          example: AA
      - name: minDelay
        in: query
        description: Minimum delay in minutes to filter results
        required: false
        schema:
          type: integer
          example: 30
      responses:
        '200':
          description: Successful response with delay data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlightsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /flights-by-airline:
    get:
      operationId: getFlightsByAirline
      summary: Flights By Airline
      description: 'Filter the live flight feed by airline operator to retrieve all active flights operated by a specific airline.

        '
      tags:
      - Flights
      parameters:
      - $ref: '#/components/parameters/AccessKey'
      - $ref: '#/components/parameters/Limit'
      - name: airlineIata
        in: query
        description: Airline IATA code (required)
        required: true
        schema:
          type: string
          example: AA
      - name: airlineIcao
        in: query
        description: Airline ICAO code
        required: false
        schema:
          type: string
          example: AAL
      responses:
        '200':
          description: Successful response with flights by airline
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlightsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /flight-data-by-date:
    get:
      operationId: getFlightDataByDate
      summary: Flight Data by Date
      description: 'Retrieve detailed flight records for a specific flight number across a date range.

        '
      tags:
      - Flights
      parameters:
      - $ref: '#/components/parameters/AccessKey'
      - $ref: '#/components/parameters/Limit'
      - name: flightIata
        in: query
        description: Flight IATA code (e.g. AA100)
        required: false
        schema:
          type: string
          example: AA100
      - name: dateFrom
        in: query
        description: Start date (YYYY-MM-DD)
        required: false
        schema:
          type: string
          format: date
          example: '2026-01-01'
      - name: dateTo
        in: query
        description: End date (YYYY-MM-DD)
        required: false
        schema:
          type: string
          format: date
          example: '2026-01-31'
      responses:
        '200':
          description: Successful response with flight data by date
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlightsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /flight-info:
    get:
      operationId: getFlightInfoByNumber
      summary: Flight Info By Flight Number
      description: 'Retrieve detailed information for a specific flight number, including status, schedule, aircraft, and route details.

        '
      tags:
      - Flights
      parameters:
      - $ref: '#/components/parameters/AccessKey'
      - name: flightIata
        in: query
        description: Flight IATA code (e.g. AA100)
        required: false
        schema:
          type: string
          example: AA100
      - name: flightIcao
        in: query
        description: Flight ICAO code (e.g. AAL100)
        required: false
        schema:
          type: string
          example: AAL100
      - name: flightNum
        in: query
        description: Flight number only (e.g. 100)
        required: false
        schema:
          type: string
          example: '100'
      responses:
        '200':
          description: Successful response with flight info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlightInfoResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    ScheduleEntry:
      type: object
      description: Scheduled flight entry
      properties:
        airline_iata:
          type: string
          example: AA
        airline_icao:
          type: string
          example: AAL
        flight_iata:
          type: string
          example: AA100
        flight_icao:
          type: string
          example: AAL100
        flight_number:
          type: string
          example: '100'
        cs_airline_iata:
          type: string
          description: Code-share airline IATA
          example: BA
        cs_flight_number:
          type: string
          description: Code-share flight number
          example: '6000'
        cs_flight_iata:
          type: string
          description: Code-share flight IATA
          example: BA6000
        status:
          type: string
          example: scheduled
        dep_iata:
          type: string
          example: JFK
        dep_icao:
          type: string
          example: KJFK
        dep_terminal:
          type: string
          example: '8'
        dep_gate:
          type: string
          example: B12
        dep_time:
          type: string
          format: date-time
          example: '2026-06-13T10:00:00.000'
        dep_time_utc:
          type: string
          format: date-time
          example: '2026-06-13T14:00:00.000'
        arr_iata:
          type: string
          example: LAX
        arr_icao:
          type: string
          example: KLAX
        arr_terminal:
          type: string
          example: '4'
        arr_gate:
          type: string
          example: A5
        arr_time:
          type: string
          format: date-time
          example: '2026-06-13T17:30:00.000'
        arr_time_utc:
          type: string
          format: date-time
          example: '2026-06-13T00:30:00.000'
        duration:
          type: integer
          description: Flight duration in minutes
          example: 330
        aircraft_icao:
          type: string
          example: B77W
        delayed:
          type: integer
          description: Delay in minutes
          example: 0
    SchedulesResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/ScheduleEntry'
    FlightInfoResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          $ref: '#/components/schemas/ScheduleEntry'
    FlightData:
      type: object
      description: Real-time or historical flight data record
      properties:
        hex:
          type: string
          description: ICAO24 hex identifier for the aircraft
          example: a1b2c3
        reg_number:
          type: string
          description: Aircraft registration number
          example: N12345
        flag:
          type: string
          description: Country flag code
          example: US
        lat:
          type: number
          format: float
          description: Aircraft latitude
          example: 40.7128
        lng:
          type: number
          format: float
          description: Aircraft longitude
          example: -74.006
        alt:
          type: number
          format: float
          description: Aircraft altitude in feet
          example: 35000
        dir:
          type: number
          format: float
          description: Aircraft heading in degrees
          example: 270.5
        speed:
          type: number
          format: float
          description: Aircraft speed in km/h
          example: 900
        v_speed:
          type: number
          format: float
          description: Vertical speed in ft/min
          example: 0
        squawk:
          type: string
          description: Transponder squawk code
          example: '1234'
        flight_number:
          type: string
          description: Flight number
          example: '100'
        flight_icao:
          type: string
          description: Flight ICAO code
          example: AAL100
        flight_iata:
          type: string
          description: Flight IATA code
          example: AA100
        dep_icao:
          type: string
          description: Departure airport ICAO code
          example: KJFK
        dep_iata:
          type: string
          description: Departure airport IATA code
          example: JFK
        arr_icao:
          type: string
          description: Arrival airport ICAO code
          example: KLAX
        arr_iata:
          type: string
          description: Arrival airport IATA code
          example: LAX
        airline_icao:
          type: string
          description: Airline ICAO code
          example: AAL
        airline_iata:
          type: string
          description: Airline IATA code
          example: AA
        eta:
          type: integer
          description: Estimated time of arrival (Unix timestamp)
          example: 1720000000
        status:
          type: string
          description: Flight status
          enum:
          - en-route
          - landed
          - scheduled
          - cancelled
          - diverted
          example: en-route
        updated:
          type: integer
          description: Last update time (Unix timestamp)
          example: 1719999000
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              example: 101
            type:
              type: string
              example: invalid_access_key
            info:
              type: string
              example: You have not supplied a valid API Access Key.
    FlightsResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/FlightData'
  responses:
    Unauthorized:
      description: Unauthorized - invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  parameters:
    Limit:
      name: limit
      in: query
      description: Maximum number of results to return (integer, up to 10000)
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 10000
        example: 100
    AccessKey:
      name: access_key
      in: query
      description: Your FlightLabs API access key
      required: true
      schema:
        type: string
        example: YOUR_ACCESS_KEY
  securitySchemes:
    AccessKey:
      type: apiKey
      in: query
      name: access_key
      description: API key obtained from your FlightLabs dashboard
externalDocs:
  description: FlightLabs API Documentation
  url: https://www.goflightlabs.com/dashboard#api-documentation