{
  "openapi": "3.1.0",
  "info": {
    "title": "TailLookup API",
    "version": "1.0.0",
    "description": "Free REST API for US aircraft history: FAA registration, ownership, and NTSB accident records by tail number (N-number). Data compiled daily from the FAA Aircraft Registry and the NTSB aviation accident database; every response carries an as_of date.",
    "contact": {
      "url": "https://taillookup.com/api"
    },
    "license": {
      "name": "Data: public FAA/NTSB records",
      "url": "https://taillookup.com/methodology"
    }
  },
  "servers": [
    {
      "url": "https://taillookup.com"
    }
  ],
  "paths": {
    "/api/v1/aircraft/{tail}": {
      "get": {
        "summary": "Aircraft report by tail number",
        "description": "Returns the merged report for one US tail number: airframe (make, model, year, serial), current registration and owner, NTSB accident summary, and source links.",
        "parameters": [
          {
            "name": "tail",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "N1258C",
            "description": "US tail number / N-number (case-insensitive, N optional)"
          }
        ],
        "responses": {
          "200": {
            "description": "Aircraft report",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Aircraft"
                }
              }
            }
          },
          "404": {
            "description": "No record for this tail number"
          }
        }
      }
    },
    "/api/v1/aircraft/{tail}/events": {
      "get": {
        "summary": "NTSB accident records for a tail number",
        "description": "Every NTSB accident record on file for the tail number, with date, location, injury level, fatalities, phase of flight, probable cause, and a link to the NTSB source record.",
        "parameters": [
          {
            "name": "tail",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "N1544"
          }
        ],
        "responses": {
          "200": {
            "description": "Accident records",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Events"
                }
              }
            }
          },
          "404": {
            "description": "No record for this tail number"
          }
        }
      }
    },
    "/api/v1/search": {
      "get": {
        "summary": "Search current registrations by owner name",
        "parameters": [
          {
            "name": "owner",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 2
            },
            "example": "Delta Air Lines"
          }
        ],
        "responses": {
          "200": {
            "description": "Matching aircraft with owner, model, and location"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Aircraft": {
        "type": "object",
        "properties": {
          "tail": {
            "type": "string",
            "description": "Canonical N-number",
            "example": "N1258C"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "deregistered"
            ]
          },
          "airframe": {
            "type": "object",
            "properties": {
              "make": {
                "type": "string",
                "example": "PIPER"
              },
              "model": {
                "type": "string",
                "example": "PA-18-135"
              },
              "year": {
                "type": "integer",
                "example": 1953
              },
              "serial_number": {
                "type": "string",
                "example": "18-2497"
              },
              "type": {
                "type": "string",
                "example": "Fixed wing single-engine"
              },
              "engine": {
                "type": "string"
              }
            }
          },
          "registration": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string"
              },
              "owner": {
                "type": "object",
                "nullable": true,
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "city": {
                    "type": "string"
                  },
                  "state": {
                    "type": "string"
                  },
                  "trustee": {
                    "type": "boolean",
                    "description": "Registered via trustee"
                  }
                }
              }
            }
          },
          "accidents": {
            "type": "object",
            "properties": {
              "ntsb_count": {
                "type": "integer",
                "description": "NTSB accident records on file"
              },
              "has_fatal_record": {
                "type": "boolean"
              },
              "most_recent": {
                "type": "object",
                "nullable": true
              }
            }
          },
          "as_of": {
            "type": "string",
            "format": "date",
            "description": "FAA registry snapshot date"
          },
          "links": {
            "type": "object",
            "description": "HTML page, events endpoint, FAA source record"
          }
        }
      },
      "Events": {
        "type": "object",
        "properties": {
          "tail": {
            "type": "string"
          },
          "count": {
            "type": "integer"
          },
          "events": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "ntsb_number": {
                  "type": "string",
                  "example": "GAA17CA275"
                },
                "date": {
                  "type": "string",
                  "format": "date"
                },
                "city": {
                  "type": "string"
                },
                "state": {
                  "type": "string"
                },
                "highest_injury": {
                  "type": "string",
                  "description": "FATL | SERS | MINR | NONE"
                },
                "fatalities": {
                  "type": "integer"
                },
                "phase_of_flight": {
                  "type": "string",
                  "nullable": true
                },
                "probable_cause": {
                  "type": "string",
                  "description": "NTSB's official finding, verbatim"
                },
                "source": {
                  "type": "string",
                  "format": "uri",
                  "description": "NTSB CAROL record"
                }
              }
            }
          },
          "as_of": {
            "type": "string",
            "format": "date"
          }
        }
      }
    }
  }
}