openapi: 3.0.3
info:
  title: FlightLabs Aircraft 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: Aircraft
  description: Aircraft and aircraft type reference data endpoints
paths:
  /aircraft_types:
    get:
      operationId: getAircraftTypes
      summary: Aircraft Types
      description: 'Retrieve aircraft type reference data including IATA codes and type names.

        '
      tags:
      - Aircraft
      parameters:
      - $ref: '#/components/parameters/AccessKey'
      - name: codeIataAircraft
        in: query
        description: Aircraft IATA code (e.g. B737)
        required: false
        schema:
          type: string
          example: B737
      responses:
        '200':
          description: Successful response with aircraft type data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AircraftTypesResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /airplanes:
    get:
      operationId: getAirplanes
      summary: Airplanes
      description: 'Retrieve airplane (aircraft) reference data by registration number, hex ICAO code, or airline. Returns registration details, model, type codes, construction/delivery dates, and engine specifications. Note - This endpoint is deprecated and may be removed in a future version.

        '
      tags:
      - Aircraft
      deprecated: true
      parameters:
      - $ref: '#/components/parameters/AccessKey'
      - name: numberRegistration
        in: query
        description: Aircraft registration number
        required: false
        schema:
          type: string
          example: N12345
      - name: hexIcaoAirplane
        in: query
        description: Hex ICAO code for the aircraft
        required: false
        schema:
          type: string
          example: a1b2c3
      - name: codeIataAirline
        in: query
        description: Airline IATA code to filter aircraft
        required: false
        schema:
          type: string
          example: AA
      responses:
        '200':
          description: Successful response with airplane data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AirplanesResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    AircraftTypesResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/AircraftTypeData'
    AirplaneData:
      type: object
      description: Airplane reference data
      properties:
        numberRegistration:
          type: string
          example: N12345
        productionLine:
          type: string
          example: Boeing 737 Classic
        airplaneIataType:
          type: string
          example: B738
        planeModel:
          type: string
          example: 737-800
        modelCode:
          type: string
          example: B738
        hexIcaoAirplane:
          type: string
          example: a1b2c3
        codeIataAirline:
          type: string
          example: AA
        codeIcaoAirline:
          type: string
          example: AAL
        planeAge:
          type: string
          description: Age of aircraft in years
          example: '10'
        statusPlane:
          type: string
          enum:
          - active
          - stored
          - scrapped
          example: active
        planeOwner:
          type: string
          example: American Airlines
        enginesCount:
          type: string
          example: '2'
        enginesType:
          type: string
          enum:
          - JET
          - PISTON
          - TURBOPROP
          example: JET
        planeSerialNumber:
          type: string
          example: '30000'
        lineNumber:
          type: string
          example: '500'
        constructionNumber:
          type: string
          example: '12345'
        deliveryDate:
          type: string
          format: date
          example: '2016-06-01'
        firstFlight:
          type: string
          format: date
          example: '2016-04-01'
        registrationDate:
          type: string
          format: date
          example: '2016-06-15'
        rolloutDate:
          type: string
          format: date
          example: '2016-03-01'
    AirplanesResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/AirplaneData'
    AircraftTypeData:
      type: object
      description: Aircraft type reference data
      properties:
        aircraftTypeId:
          type: string
          example: '1'
        nameAircraftType:
          type: string
          example: Boeing 737-800
        codeIataAircraftType:
          type: string
          example: B738
    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.
  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:
    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