{"openapi":"3.1.0","info":{"title":"Grizzly Bulls Aircraft Intelligence API","version":"1.0.0","description":"Versioned U.S. aircraft registry discovery, current-state, and retained-history API. Aircraft data routes require a Grizzly Bulls API key, enforce an aircraft-specific monthly quota and bounded request rate, and remain externally launch-gated."},"servers":[{"url":"https://api.grizzlybulls.com/v1"}],"security":[{"AircraftApiKey":[]}],"x-aircraft-plans":[{"id":"free","monthlyRequestLimit":1000,"requestsPerMinute":30},{"id":"developer","monthlyRequestLimit":25000,"requestsPerMinute":120},{"id":"business","monthlyRequestLimit":250000,"requestsPerMinute":600}],"paths":{"/aircraft":{"get":{"operationId":"searchAircraftRegistry","summary":"Search the current aircraft registry with bounded exact filters","description":"Authenticated current-registry discovery. At least one of manufacturer, model, or state is required. Filters use exact normalized matching and combine with AND semantics. Results use opaque keyset pagination; totals, owner-name search, historical search, and bulk enumeration are not provided.","parameters":[{"name":"manufacturer","in":"query","required":false,"description":"Exact manufacturer name after trim/case normalization. At least one discovery filter is required.","schema":{"type":"string","minLength":1,"maxLength":100}},{"name":"model","in":"query","required":false,"description":"Exact aircraft model after trim/case normalization. At least one discovery filter is required.","schema":{"type":"string","minLength":1,"maxLength":100}},{"name":"state","in":"query","required":false,"description":"Exact two-letter registrant state code. At least one of manufacturer, model, or state is required.","schema":{"type":"string","pattern":"^[A-Za-z]{2}$","example":"FL"}},{"name":"limit","in":"query","required":false,"description":"Maximum current aircraft records returned.","schema":{"type":"integer","minimum":1,"maximum":50,"default":25}},{"name":"cursor","in":"query","required":false,"description":"Opaque keyset cursor returned by the previous page. It is valid only with the same normalized discovery filters.","schema":{"type":"string","minLength":1,"maxLength":1024}}],"responses":{"200":{"description":"Bounded current-registry discovery results. A valid search with no matches returns an empty data array.","headers":{"X-Aircraft-Plan":{"description":"Resolved aircraft API plan for the authenticated account.","schema":{"type":"string","enum":["free","developer","business"]}},"X-Aircraft-Rate-Limit":{"description":"Maximum requests permitted per minute for the resolved aircraft API plan.","schema":{"type":"integer","minimum":1}},"X-Aircraft-Quota-Limit":{"description":"Monthly request quota for the resolved aircraft API plan.","schema":{"type":"integer","minimum":1}},"X-Aircraft-Quota-Remaining":{"description":"Monthly requests remaining after the current operation was reserved.","schema":{"type":"integer","minimum":0}},"X-Aircraft-Quota-Reset":{"description":"UTC timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AircraftDiscoveryResponse"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/aircraft/{nNumber}":{"get":{"operationId":"getAircraftByNNumber","summary":"Get the current aircraft registration for an N-number","parameters":[{"name":"nNumber","in":"path","required":true,"description":"U.S. aircraft N-number. Matching is case-insensitive and an optional N- hyphen is normalized.","schema":{"type":"string","pattern":"^[Nn]-?(?:[1-9][0-9]{0,4}|[1-9][0-9]{0,3}[A-HJ-NP-Za-hj-np-z]|[1-9][0-9]{0,2}[A-HJ-NP-Za-hj-np-z]{2})$","example":"N100"}}],"responses":{"200":{"description":"Current aircraft registration.","headers":{"X-Aircraft-Plan":{"description":"Resolved aircraft API plan for the authenticated account.","schema":{"type":"string","enum":["free","developer","business"]}},"X-Aircraft-Rate-Limit":{"description":"Maximum requests permitted per minute for the resolved aircraft API plan.","schema":{"type":"integer","minimum":1}},"X-Aircraft-Quota-Limit":{"description":"Monthly request quota for the resolved aircraft API plan.","schema":{"type":"integer","minimum":1}},"X-Aircraft-Quota-Remaining":{"description":"Monthly requests remaining after the current operation was reserved.","schema":{"type":"integer","minimum":0}},"X-Aircraft-Quota-Reset":{"description":"UTC timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AircraftCurrentResponse"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/aircraft/{nNumber}/history":{"get":{"operationId":"getAircraftHistoryByNNumber","summary":"Get compact retained registration history and change events for an N-number","parameters":[{"name":"nNumber","in":"path","required":true,"description":"U.S. aircraft N-number. Matching is case-insensitive and an optional N- hyphen is normalized.","schema":{"type":"string","pattern":"^[Nn]-?(?:[1-9][0-9]{0,4}|[1-9][0-9]{0,3}[A-HJ-NP-Za-hj-np-z]|[1-9][0-9]{0,2}[A-HJ-NP-Za-hj-np-z]{2})$","example":"N100"}},{"name":"versionsLimit","in":"query","required":false,"description":"Maximum historical versions returned.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"versionsOffset","in":"query","required":false,"description":"Historical-version offset.","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}},{"name":"eventsLimit","in":"query","required":false,"description":"Maximum change events returned.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"eventsOffset","in":"query","required":false,"description":"Change-event offset.","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}}],"responses":{"200":{"description":"Retained history and PII-free change events.","headers":{"X-Aircraft-Plan":{"description":"Resolved aircraft API plan for the authenticated account.","schema":{"type":"string","enum":["free","developer","business"]}},"X-Aircraft-Rate-Limit":{"description":"Maximum requests permitted per minute for the resolved aircraft API plan.","schema":{"type":"integer","minimum":1}},"X-Aircraft-Quota-Limit":{"description":"Monthly request quota for the resolved aircraft API plan.","schema":{"type":"integer","minimum":1}},"X-Aircraft-Quota-Remaining":{"description":"Monthly requests remaining after the current operation was reserved.","schema":{"type":"integer","minimum":0}},"X-Aircraft-Quota-Reset":{"description":"UTC timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AircraftHistoryResponse"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}}},"components":{"securitySchemes":{"AircraftApiKey":{"type":"http","scheme":"bearer","bearerFormat":"Grizzly Bulls API key","description":"Send the API key returned by the Grizzly Bulls account key-generation flow as Authorization: Bearer <api-key>. API keys are stored only as HMAC verifiers server-side."}},"responses":{"InvalidRequest":{"description":"The aircraft identifier, discovery filters, cursor, or pagination parameters are invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"A valid Grizzly Bulls API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"No matching current or retained registration was found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"MethodNotAllowed":{"description":"The HTTP method is not supported by this endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RateLimited":{"description":"The short-window request rate or monthly aircraft API quota was exceeded.","headers":{"X-Aircraft-Plan":{"description":"Resolved aircraft API plan for the authenticated account.","schema":{"type":"string","enum":["free","developer","business"]}},"X-Aircraft-Rate-Limit":{"description":"Maximum requests permitted per minute for the resolved aircraft API plan.","schema":{"type":"integer","minimum":1}},"X-Aircraft-Quota-Limit":{"description":"Monthly request quota for the resolved aircraft API plan.","schema":{"type":"integer","minimum":1}},"X-Aircraft-Quota-Remaining":{"description":"Monthly requests remaining after the current operation was reserved.","schema":{"type":"integer","minimum":0}},"X-Aircraft-Quota-Reset":{"description":"UTC timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"}},"Retry-After":{"description":"Seconds until the request may be retried under the limiting policy.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalError":{"description":"The request failed without exposing provider or server internals.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ServiceUnavailable":{"description":"The aircraft read model, authentication authority, entitlement authority, or durable usage meter is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"schemas":{"ErrorResponse":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request","unauthenticated","rate_limited","not_found","method_not_allowed","service_unavailable","internal_error"]},"message":{"type":"string"}}}}},"AircraftDiscoveryRecord":{"type":"object","additionalProperties":false,"required":["contractVersion","aircraftId","nNumber","sourceRegistrationStatusCode","manufactureYear","manufacturer","model","registrantState"],"properties":{"contractVersion":{"type":"string","const":"aircraft-discovery-v1"},"aircraftId":{"type":["string","null"],"format":"uuid"},"nNumber":{"type":"string"},"sourceRegistrationStatusCode":{"type":["string","null"]},"manufactureYear":{"type":["integer","null"]},"manufacturer":{"type":["string","null"]},"model":{"type":["string","null"]},"registrantState":{"type":["string","null"]}}},"AircraftDiscoveryPagination":{"type":"object","additionalProperties":false,"required":["limit","nextCursor"],"properties":{"limit":{"type":"integer","minimum":1,"maximum":50},"nextCursor":{"type":["string","null"],"maxLength":1024}}},"AircraftDiscoveryResponse":{"type":"object","additionalProperties":false,"required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AircraftDiscoveryRecord"}},"pagination":{"$ref":"#/components/schemas/AircraftDiscoveryPagination"}}},"SourceSnapshot":{"type":"object","additionalProperties":false,"required":["provider","sourceContractVersion","sourceUrl","retrievedAt","archiveSha256"],"properties":{"provider":{"type":"string","const":"faa-releasable-aircraft-registry"},"sourceContractVersion":{"type":"string"},"sourceUrl":{"type":"string","format":"uri"},"retrievedAt":{"type":"string","format":"date-time"},"archiveSha256":{"type":"string","pattern":"^[a-f0-9]{64}$"}}},"Registrant":{"type":"object","additionalProperties":false,"required":["sourceTypeCode","name","street1","street2","city","state","postalCode","countyCode","countryCode","otherNames"],"properties":{"sourceTypeCode":{"type":["string","null"]},"name":{"type":["string","null"]},"street1":{"type":["string","null"]},"street2":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"postalCode":{"type":["string","null"]},"countyCode":{"type":["string","null"]},"countryCode":{"type":["string","null"]},"otherNames":{"type":"array","items":{"type":"string"}}}},"Registration":{"type":"object","additionalProperties":false,"required":["nNumber","sourceStatusCode","certificateIssueDate","expirationDate","lastActivityDate","fractionalOwnership"],"properties":{"nNumber":{"type":"string"},"sourceStatusCode":{"type":["string","null"]},"certificateIssueDate":{"type":["string","null"],"format":"date"},"expirationDate":{"type":["string","null"],"format":"date"},"lastActivityDate":{"type":["string","null"],"format":"date"},"fractionalOwnership":{"type":["boolean","null"]}}},"CurrentAircraft":{"type":"object","additionalProperties":false,"required":["serialNumber","manufactureYear","manufacturer","model","sourceAircraftTypeCode","sourceEngineTypeCode","sourceCategoryCode","sourceWeightClassCode","engineCount","seatCount","airworthinessDate","modeSCodeOctal","modeSCodeHex","typeCertificateDataSheet","typeCertificateHolder","engine"],"properties":{"serialNumber":{"type":["string","null"]},"manufactureYear":{"type":["integer","null"]},"manufacturer":{"type":["string","null"]},"model":{"type":["string","null"]},"sourceAircraftTypeCode":{"type":["string","null"]},"sourceEngineTypeCode":{"type":["string","null"]},"sourceCategoryCode":{"type":["string","null"]},"sourceWeightClassCode":{"type":["string","null"]},"engineCount":{"type":["number","null"]},"seatCount":{"type":["number","null"]},"airworthinessDate":{"type":["string","null"],"format":"date"},"modeSCodeOctal":{"type":["string","null"]},"modeSCodeHex":{"type":["string","null"]},"typeCertificateDataSheet":{"type":["string","null"]},"typeCertificateHolder":{"type":["string","null"]},"engine":{"type":"object","additionalProperties":false,"required":["manufacturer","model","sourceTypeCode","horsepower","thrust"],"properties":{"manufacturer":{"type":["string","null"]},"model":{"type":["string","null"]},"sourceTypeCode":{"type":["string","null"]},"horsepower":{"type":["number","null"]},"thrust":{"type":["number","null"]}}}}},"HistorySummary":{"type":"object","additionalProperties":false,"required":["firstObservedAt","lastObservedAt","versionCount","eventCount"],"properties":{"firstObservedAt":{"type":"string","format":"date-time"},"lastObservedAt":{"type":"string","format":"date-time"},"versionCount":{"type":"integer","minimum":1},"eventCount":{"type":"integer","minimum":0}}},"AircraftCurrentRecord":{"type":"object","additionalProperties":false,"required":["contractVersion","aircraftId","registration","aircraft","registrant","source","history"],"properties":{"contractVersion":{"type":"string","const":"aircraft-public-v1"},"aircraftId":{"type":["string","null"],"format":"uuid"},"registration":{"$ref":"#/components/schemas/Registration"},"aircraft":{"$ref":"#/components/schemas/CurrentAircraft"},"registrant":{"$ref":"#/components/schemas/Registrant"},"source":{"$ref":"#/components/schemas/SourceSnapshot"},"history":{"$ref":"#/components/schemas/HistorySummary"}}},"AircraftCurrentResponse":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AircraftCurrentRecord"}}},"ObservationBoundary":{"type":"object","additionalProperties":false,"required":["retrievedAt","sourceContractVersion","sourceUrl","archiveSha256"],"properties":{"retrievedAt":{"type":"string","format":"date-time"},"sourceContractVersion":{"type":"string"},"sourceUrl":{"type":"string","format":"uri"},"archiveSha256":{"type":"string","pattern":"^[a-f0-9]{64}$"}}},"HistoricalAircraft":{"type":"object","additionalProperties":false,"required":["serialNumber","manufactureYear","sourceAircraftTypeCode","sourceEngineTypeCode","airworthinessDate","modeSCodeOctal","modeSCodeHex"],"properties":{"serialNumber":{"type":["string","null"]},"manufactureYear":{"type":["integer","null"]},"sourceAircraftTypeCode":{"type":["string","null"]},"sourceEngineTypeCode":{"type":["string","null"]},"airworthinessDate":{"type":["string","null"],"format":"date"},"modeSCodeOctal":{"type":["string","null"]},"modeSCodeHex":{"type":["string","null"]}}},"HistoryVersion":{"type":"object","additionalProperties":false,"required":["contractVersion","aircraftId","registration","aircraft","registrant","sourceProvider","observedFrom","observedThrough"],"properties":{"contractVersion":{"type":"string","const":"aircraft-public-v1"},"aircraftId":{"type":["string","null"],"format":"uuid"},"registration":{"$ref":"#/components/schemas/Registration"},"aircraft":{"$ref":"#/components/schemas/HistoricalAircraft"},"registrant":{"$ref":"#/components/schemas/Registrant"},"sourceProvider":{"type":"string","const":"faa-releasable-aircraft-registry"},"observedFrom":{"$ref":"#/components/schemas/ObservationBoundary"},"observedThrough":{"$ref":"#/components/schemas/ObservationBoundary"}}},"HistoryEvent":{"type":"object","additionalProperties":false,"required":["contractVersion","aircraftId","previousAircraftId","nNumber","eventType","oldSourceRegistrationStatusCode","newSourceRegistrationStatusCode","changedFields","sourceEffectiveDate","observedAt","previousObservedAt","source"],"properties":{"contractVersion":{"type":"string","const":"aircraft-public-v1"},"aircraftId":{"type":["string","null"],"format":"uuid"},"previousAircraftId":{"type":["string","null"],"format":"uuid"},"nNumber":{"type":"string"},"eventType":{"type":"string","enum":["registration_added","registration_removed","registration_record_changed","aircraft_assignment_changed","status_changed","registrant_changed","registrant_pii_withheld","registrant_pii_released"]},"oldSourceRegistrationStatusCode":{"type":["string","null"]},"newSourceRegistrationStatusCode":{"type":["string","null"]},"changedFields":{"type":"array","items":{"type":"string","enum":["aircraft_assignment","registration_identifier","aircraft_model","engine_model","manufacture_year","aircraft_type","engine_type","registration_status","mode_s_code","certificate_issue_date","expiration_date","last_activity_date","airworthiness_date","fractional_ownership","registrant_type"]}},"sourceEffectiveDate":{"type":["string","null"],"format":"date"},"observedAt":{"type":"string","format":"date-time"},"previousObservedAt":{"type":["string","null"],"format":"date-time"},"source":{"$ref":"#/components/schemas/SourceSnapshot"}}},"PageMeta":{"type":"object","additionalProperties":false,"required":["limit","offset","total","hasMore"],"properties":{"limit":{"type":"integer","minimum":1,"maximum":100},"offset":{"type":"integer","minimum":0,"maximum":10000},"total":{"type":"integer","minimum":0},"hasMore":{"type":"boolean"}}},"AircraftHistoryResponse":{"type":"object","additionalProperties":false,"required":["data","pagination"],"properties":{"data":{"type":"object","additionalProperties":false,"required":["nNumber","versions","events"],"properties":{"nNumber":{"type":"string"},"versions":{"type":"array","items":{"$ref":"#/components/schemas/HistoryVersion"}},"events":{"type":"array","items":{"$ref":"#/components/schemas/HistoryEvent"}}}},"pagination":{"type":"object","additionalProperties":false,"required":["versions","events"],"properties":{"versions":{"$ref":"#/components/schemas/PageMeta"},"events":{"$ref":"#/components/schemas/PageMeta"}}}}}}}}