{"openapi":"3.1.0","info":{"title":"Grizzly Bulls Aircraft Intelligence API","version":"1.0.0","description":"Versioned U.S. aircraft registry API with exact N-number and ICAO24 / Mode-S lookup, evidence-backed N-number lifecycle status, bounded exact current-registry discovery including serial/year/status filters, flexible allowlisted current-registry querying, retained observed registration history, a bounded registry-wide observed change feed, paid asynchronous CSV/JSON/XLSX exports with saved report definitions, and paid N-number watch lists with signed webhook delivery. Aircraft data routes require a Grizzly Bulls API key; request reads, exports, saved reports, and webhook watches use code-owned plan limits. Exact N-number document-index evidence is also available with privacy-safe FAA provenance and explicit legal nonclaims. Shared Grizzly Bulls API keys may carry least-privilege Aircraft scopes, and authenticated customers can inspect current Aircraft plan and monthly usage without consuming Aircraft monthly quota.","contact":{"name":"Grizzly Bulls API support","url":"https://grizzlybulls.com/contact"}},"externalDocs":{"description":"Aircraft Intelligence API quickstart, limits, troubleshooting, and key guidance","url":"https://grizzlybulls.com/aircraft-api"},"servers":[{"url":"https://api.grizzlybulls.com/v1"}],"security":[{"AircraftApiKey":[]}],"x-aircraft-plans":[{"id":"free","monthlyRequestLimit":1000,"requestsPerMinute":30,"webhookWatchLimit":0,"savedReportLimit":0,"monthlyExportRunLimit":0,"exportRowLimit":0,"exportMaxBytes":0,"exportRetentionHours":0},{"id":"developer","monthlyRequestLimit":25000,"requestsPerMinute":120,"webhookWatchLimit":25,"savedReportLimit":25,"monthlyExportRunLimit":100,"exportRowLimit":5000,"exportMaxBytes":16777216,"exportRetentionHours":24},{"id":"business","monthlyRequestLimit":250000,"requestsPerMinute":600,"webhookWatchLimit":250,"savedReportLimit":250,"monthlyExportRunLimit":1000,"exportRowLimit":25000,"exportMaxBytes":67108864,"exportRetentionHours":72}],"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, state, serialNumber, manufactureYear, or registrationStatus is required. Filters use exact normalized matching and combine with AND semantics. Results use opaque filter-bound keyset pagination; totals, owner-name search, historical search, fuzzy matching, arbitrary sorting, and bulk enumeration are not provided.","parameters":[{"name":"manufacturer","in":"query","required":false,"description":"Exact manufacturer name after trim/case normalization. At least one reviewed 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 reviewed 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 reviewed discovery filter is required.","schema":{"type":"string","pattern":"^[A-Za-z]{2}$","example":"FL"}},{"name":"serialNumber","in":"query","required":false,"description":"Exact aircraft serial number after trim/case normalization. At least one reviewed discovery filter is required.","schema":{"type":"string","minLength":1,"maxLength":100}},{"name":"manufactureYear","in":"query","required":false,"description":"Exact four-digit aircraft manufacture year. At least one reviewed discovery filter is required.","schema":{"type":"integer","minimum":1900,"maximum":2100,"example":2024}},{"name":"registrationStatus","in":"query","required":false,"description":"Exact FAA source registration-status code after trim/case normalization. At least one reviewed discovery filter is required.","schema":{"type":"string","minLength":1,"maxLength":100}},{"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"},"403":{"description":"The authenticated API key does not include the Aircraft scope required by this operation.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","const":"forbidden"},"message":{"type":"string"}}}}},"example":{"error":{"code":"forbidden","message":"This API key is not permitted for this operation."}}}}},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"x-required-api-key-scope":"aircraft:query"}},"/aircraft/query":{"get":{"operationId":"queryAircraftRegistry","summary":"Query the current FAA registry with bounded flexible filters","description":"Authenticated AIR15B current-registry query over the same reviewed aircraft_public discovery projection as the legacy exact-filter route. At least one filter is required. Supported operators are column-specific and include exact/in matching, prefix matching, contains for reviewed manufacturer/model keys, and bounded manufacture-year ranges. Response projection and sorting are allowlisted. Owner or registrant-name filters, unfiltered registry walking, offset pagination, arbitrary SQL, regex, totals, and historical search are not provided.","parameters":[{"name":"filter","in":"query","required":true,"style":"form","explode":true,"description":"Repeatable field:operator:value filter. Repeated filters combine with AND. Use /aircraft/columns to discover supported columns and operators.","schema":{"type":"array","minItems":1,"maxItems":8,"items":{"type":"string","minLength":3,"maxLength":1200}},"examples":{"containsManufacturer":{"value":["manufacturer:contains:CESSNA"]},"yearAndState":{"value":["manufactureYear:between:2015,2025","registrantState:in:FL,GA"]}}},{"name":"columns","in":"query","required":false,"description":"Comma-separated allowlisted response columns. Defaults to all reviewed AIR15B columns.","schema":{"type":"string","example":"nNumber,manufacturer,model,manufactureYear"}},{"name":"sort","in":"query","required":false,"description":"One allowlisted column plus asc/desc. Non-N-number sorts must also be constrained by a filter on that column.","schema":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9]*(?::asc|:desc)$","example":"manufacturer:asc","default":"nNumber:asc"}},{"name":"limit","in":"query","required":false,"description":"Maximum current registry records returned.","schema":{"type":"integer","minimum":1,"maximum":50,"default":25}},{"name":"cursor","in":"query","required":false,"description":"Opaque keyset cursor bound to the normalized filters, selected columns, and sort.","schema":{"type":"string","minLength":1,"maxLength":4096}}],"responses":{"200":{"description":"Bounded current-registry query results with an optional opaque continuation cursor.","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/AircraftRegistryQueryResponse"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The authenticated API key does not include the Aircraft scope required by this operation.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","const":"forbidden"},"message":{"type":"string"}}}}},"example":{"error":{"code":"forbidden","message":"This API key is not permitted for this operation."}}}}},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"x-required-api-key-scope":"aircraft:query"}},"/aircraft/columns":{"get":{"operationId":"getAircraftRegistryQueryColumns","summary":"List reviewed current-registry query columns and operators","description":"Authenticated metadata for the AIR15B query grammar. This route does not read registry rows or consume registry_search quota.","responses":{"200":{"description":"Allowlisted query columns, supported operators, sortability, and grammar limits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AircraftRegistryColumnsResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/aircraft/changes":{"get":{"operationId":"getAircraftObservedChanges","summary":"Get bounded observed aircraft registry changes","description":"Authenticated registry-wide change feed over Grizzly Bulls observation time, not inferred legal transaction time. since is required, until is optional, and each window is limited to 7 days. Results use the existing reviewed history-event vocabulary plus privacy-safe before/after diffs where retained public versions support those values. Registrant names, addresses, aliases, owner-search semantics, unbounded registry export, and legal ownership-transfer claims are not provided.","parameters":[{"name":"since","in":"query","required":true,"description":"Inclusive Grizzly Bulls observation-time lower bound. Must be an ISO 8601 date-time with an explicit timezone.","schema":{"type":"string","format":"date-time"}},{"name":"until","in":"query","required":false,"description":"Exclusive observation-time upper bound. Defaults to the first request time and is frozen inside any returned cursor. The since/until window may not exceed 7 days.","schema":{"type":"string","format":"date-time"}},{"name":"eventType","in":"query","required":false,"description":"Optional exact reviewed history-event type.","schema":{"type":"string","enum":["registration_added","registration_removed","registration_record_changed","aircraft_assignment_changed","status_changed","registrant_changed","registrant_pii_withheld","registrant_pii_released"]}},{"name":"limit","in":"query","required":false,"description":"Maximum observed change events 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 bound to the same since/until/eventType window.","schema":{"type":"string","minLength":1,"maxLength":2048}}],"responses":{"200":{"description":"Bounded observed change events. A valid window with no events 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/AircraftChangeFeedResponse"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The authenticated API key does not include the Aircraft scope required by this operation.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","const":"forbidden"},"message":{"type":"string"}}}}},"example":{"error":{"code":"forbidden","message":"This API key is not permitted for this operation."}}}}},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"x-required-api-key-scope":"aircraft:read"}},"/aircraft/reports":{"get":{"operationId":"listAircraftSavedReports","summary":"List saved Aircraft report definitions","description":"Lists this account's retained saved definitions. Definitions reuse the AIR15B current-registry query grammar or AIR14C bounded observed-change grammar; they are not a second query language.","responses":{"200":{"description":"Saved report definitions and the current plan limit.","headers":{"X-Aircraft-Plan":{"description":"Resolved Aircraft API plan for the authenticated account.","schema":{"type":"string","enum":["free","developer","business"]}},"X-Aircraft-Saved-Report-Limit":{"description":"Maximum saved Aircraft report definitions permitted by the current plan.","schema":{"type":"integer","minimum":0,"maximum":250}},"X-Aircraft-Monthly-Export-Run-Limit":{"description":"Maximum asynchronous export runs per UTC calendar month.","schema":{"type":"integer","minimum":0,"maximum":1000}},"X-Aircraft-Export-Row-Limit":{"description":"Maximum rows permitted in one completed export.","schema":{"type":"integer","minimum":0,"maximum":25000}},"X-Aircraft-Export-Retention-Hours":{"description":"Hours a completed export remains downloadable.","schema":{"type":"integer","minimum":0,"maximum":72}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AircraftSavedReportListResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"post":{"operationId":"createAircraftSavedReport","summary":"Create a paid saved Aircraft report definition","description":"Creates a named reusable Developer or Business report definition over AIR15B current-registry filters/projection/sort or AIR14C observed-change windows. Owner-name search, unfiltered registry enumeration, and private fields remain unsupported.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AircraftSavedReportInput"}}}},"responses":{"201":{"description":"Saved report created.","headers":{"X-Aircraft-Plan":{"description":"Resolved Aircraft API plan for the authenticated account.","schema":{"type":"string","enum":["free","developer","business"]}},"X-Aircraft-Saved-Report-Limit":{"description":"Maximum saved Aircraft report definitions permitted by the current plan.","schema":{"type":"integer","minimum":0,"maximum":250}},"X-Aircraft-Monthly-Export-Run-Limit":{"description":"Maximum asynchronous export runs per UTC calendar month.","schema":{"type":"integer","minimum":0,"maximum":1000}},"X-Aircraft-Export-Row-Limit":{"description":"Maximum rows permitted in one completed export.","schema":{"type":"integer","minimum":0,"maximum":25000}},"X-Aircraft-Export-Retention-Hours":{"description":"Hours a completed export remains downloadable.","schema":{"type":"integer","minimum":0,"maximum":72}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AircraftSavedReportResponse"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/NotEntitled"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"409":{"$ref":"#/components/responses/SavedReportConflict"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/aircraft/reports/{reportId}":{"put":{"operationId":"updateAircraftSavedReport","summary":"Replace a paid saved Aircraft report definition","parameters":[{"name":"reportId","in":"path","required":true,"description":"Aircraft saved report identifier.","schema":{"type":"string","pattern":"^arp_[a-f0-9]{24}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AircraftSavedReportInput"}}}},"responses":{"200":{"description":"Saved report replaced.","headers":{"X-Aircraft-Plan":{"description":"Resolved Aircraft API plan for the authenticated account.","schema":{"type":"string","enum":["free","developer","business"]}},"X-Aircraft-Saved-Report-Limit":{"description":"Maximum saved Aircraft report definitions permitted by the current plan.","schema":{"type":"integer","minimum":0,"maximum":250}},"X-Aircraft-Monthly-Export-Run-Limit":{"description":"Maximum asynchronous export runs per UTC calendar month.","schema":{"type":"integer","minimum":0,"maximum":1000}},"X-Aircraft-Export-Row-Limit":{"description":"Maximum rows permitted in one completed export.","schema":{"type":"integer","minimum":0,"maximum":25000}},"X-Aircraft-Export-Retention-Hours":{"description":"Hours a completed export remains downloadable.","schema":{"type":"integer","minimum":0,"maximum":72}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AircraftSavedReportResponse"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/NotEntitled"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"409":{"$ref":"#/components/responses/Conflict"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"delete":{"operationId":"deleteAircraftSavedReport","summary":"Delete a saved Aircraft report definition","description":"Deletes an owned definition. Existing export runs retain the immutable definition captured when they were queued.","parameters":[{"name":"reportId","in":"path","required":true,"description":"Aircraft saved report identifier.","schema":{"type":"string","pattern":"^arp_[a-f0-9]{24}$"}}],"responses":{"204":{"description":"Saved report deleted."},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/aircraft/exports":{"get":{"operationId":"listAircraftExports","summary":"List recent asynchronous Aircraft exports","parameters":[{"name":"limit","in":"query","required":false,"description":"Maximum recent export runs returned.","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}],"responses":{"200":{"description":"Recent export-run status for the authenticated account.","headers":{"X-Aircraft-Plan":{"description":"Resolved Aircraft API plan for the authenticated account.","schema":{"type":"string","enum":["free","developer","business"]}},"X-Aircraft-Saved-Report-Limit":{"description":"Maximum saved Aircraft report definitions permitted by the current plan.","schema":{"type":"integer","minimum":0,"maximum":250}},"X-Aircraft-Monthly-Export-Run-Limit":{"description":"Maximum asynchronous export runs per UTC calendar month.","schema":{"type":"integer","minimum":0,"maximum":1000}},"X-Aircraft-Export-Row-Limit":{"description":"Maximum rows permitted in one completed export.","schema":{"type":"integer","minimum":0,"maximum":25000}},"X-Aircraft-Export-Retention-Hours":{"description":"Hours a completed export remains downloadable.","schema":{"type":"integer","minimum":0,"maximum":72}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AircraftExportRunListResponse"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"post":{"operationId":"createAircraftExport","summary":"Queue a paid asynchronous Aircraft export","description":"Queues a bounded CSV, JSON, or XLSX export from exactly one saved report or one inline definition. Registry exports reuse AIR15B query semantics; change exports reuse AIR14C observation-window and privacy-safe event semantics. A run that exceeds its plan row ceiling fails rather than returning a silently truncated file.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AircraftExportCreateInput"}}}},"responses":{"202":{"description":"Export queued for asynchronous generation.","headers":{"X-Aircraft-Plan":{"description":"Resolved Aircraft API plan for the authenticated account.","schema":{"type":"string","enum":["free","developer","business"]}},"X-Aircraft-Saved-Report-Limit":{"description":"Maximum saved Aircraft report definitions permitted by the current plan.","schema":{"type":"integer","minimum":0,"maximum":250}},"X-Aircraft-Monthly-Export-Run-Limit":{"description":"Maximum asynchronous export runs per UTC calendar month.","schema":{"type":"integer","minimum":0,"maximum":1000}},"X-Aircraft-Export-Row-Limit":{"description":"Maximum rows permitted in one completed export.","schema":{"type":"integer","minimum":0,"maximum":25000}},"X-Aircraft-Export-Retention-Hours":{"description":"Hours a completed export remains downloadable.","schema":{"type":"integer","minimum":0,"maximum":72}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AircraftExportCreateResponse"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/NotEntitled"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"429":{"$ref":"#/components/responses/ExportRunLimitReached"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/aircraft/exports/{exportId}":{"get":{"operationId":"getAircraftExport","summary":"Get one asynchronous Aircraft export status","parameters":[{"name":"exportId","in":"path","required":true,"description":"Aircraft export run identifier.","schema":{"type":"string","pattern":"^aex_[a-f0-9]{24}$"}}],"responses":{"200":{"description":"Current export-run status.","headers":{"X-Aircraft-Plan":{"description":"Resolved Aircraft API plan for the authenticated account.","schema":{"type":"string","enum":["free","developer","business"]}},"X-Aircraft-Saved-Report-Limit":{"description":"Maximum saved Aircraft report definitions permitted by the current plan.","schema":{"type":"integer","minimum":0,"maximum":250}},"X-Aircraft-Monthly-Export-Run-Limit":{"description":"Maximum asynchronous export runs per UTC calendar month.","schema":{"type":"integer","minimum":0,"maximum":1000}},"X-Aircraft-Export-Row-Limit":{"description":"Maximum rows permitted in one completed export.","schema":{"type":"integer","minimum":0,"maximum":25000}},"X-Aircraft-Export-Retention-Hours":{"description":"Hours a completed export remains downloadable.","schema":{"type":"integer","minimum":0,"maximum":72}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AircraftExportRunResponse"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/aircraft/exports/{exportId}/download":{"get":{"operationId":"downloadAircraftExport","summary":"Download one completed retained Aircraft export","description":"Downloads a completed file only after its byte length and retained SHA-256 evidence match. Completed files expire after the plan retention window.","parameters":[{"name":"exportId","in":"path","required":true,"description":"Aircraft export run identifier.","schema":{"type":"string","pattern":"^aex_[a-f0-9]{24}$"}}],"responses":{"200":{"description":"Completed CSV, JSON, or XLSX export.","headers":{"X-Aircraft-Plan":{"description":"Resolved Aircraft API plan for the authenticated account.","schema":{"type":"string","enum":["free","developer","business"]}},"X-Aircraft-Saved-Report-Limit":{"description":"Maximum saved Aircraft report definitions permitted by the current plan.","schema":{"type":"integer","minimum":0,"maximum":250}},"X-Aircraft-Monthly-Export-Run-Limit":{"description":"Maximum asynchronous export runs per UTC calendar month.","schema":{"type":"integer","minimum":0,"maximum":1000}},"X-Aircraft-Export-Row-Limit":{"description":"Maximum rows permitted in one completed export.","schema":{"type":"integer","minimum":0,"maximum":25000}},"X-Aircraft-Export-Retention-Hours":{"description":"Hours a completed export remains downloadable.","schema":{"type":"integer","minimum":0,"maximum":72}}},"content":{"text/csv":{"schema":{"type":"string","format":"binary"}},"application/json":{"schema":{"type":"string","format":"binary"}},"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"409":{"$ref":"#/components/responses/NotReady"},"410":{"$ref":"#/components/responses/Expired"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/aircraft/watches":{"get":{"operationId":"listAircraftWebhookWatches","summary":"List configured Aircraft webhook watches","description":"Lists this account's configured N-number watches. Free accounts may inspect or delete watches retained after a paid-plan downgrade, but only Developer and Business plans can create watches or queue test deliveries.","responses":{"200":{"description":"Configured webhook watches and the current plan watch limit.","headers":{"X-Aircraft-Plan":{"description":"Resolved Aircraft API plan for the authenticated account.","schema":{"type":"string","enum":["free","developer","business"]}},"X-Aircraft-Webhook-Watch-Limit":{"description":"Maximum configured Aircraft webhook watches permitted by the current plan.","schema":{"type":"integer","minimum":0,"maximum":250}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AircraftWebhookWatchListResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"post":{"operationId":"createAircraftWebhookWatch","summary":"Create a paid N-number webhook watch","description":"Creates one exact N-number watch for a Developer or Business account. endpointUrl must be an HTTPS URL on the public Internet and must resolve only to public addresses at creation time; delivery re-resolves and pins a reviewed public address before every attempt. eventTypes may contain only AIR14C reviewed change-event types. The signing secret is returned only in this successful creation response. Equivalent watches are rejected rather than silently changing event filters.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AircraftWebhookWatchCreateInput"}}}},"responses":{"201":{"description":"Webhook watch created. Store the returned signingSecret securely; it is not returned by later reads.","headers":{"X-Aircraft-Plan":{"description":"Resolved Aircraft API plan for the authenticated account.","schema":{"type":"string","enum":["free","developer","business"]}},"X-Aircraft-Webhook-Watch-Limit":{"description":"Maximum configured Aircraft webhook watches permitted by the current plan.","schema":{"type":"integer","minimum":0,"maximum":250}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AircraftWebhookWatchCreateResponse"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/NotEntitled"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"409":{"$ref":"#/components/responses/Conflict"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/aircraft/watches/{watchId}":{"delete":{"operationId":"deleteAircraftWebhookWatch","summary":"Delete an Aircraft webhook watch","description":"Deletes an owned watch and its retained delivery troubleshooting records. This remains available after a paid-plan downgrade.","parameters":[{"name":"watchId","in":"path","required":true,"description":"Aircraft webhook watch identifier.","schema":{"type":"string","pattern":"^aw_[a-f0-9]{24}$"}}],"responses":{"204":{"description":"Webhook watch deleted."},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/aircraft/watches/{watchId}/test":{"post":{"operationId":"queueAircraftWebhookTest","summary":"Queue a synthetic signed webhook test","description":"Queues a synthetic test event for an owned watch on a Developer or Business plan. The event is explicitly marked as a test and does not represent an FAA registry observation. Each watch may queue at most one synthetic test in any five-minute window.","parameters":[{"name":"watchId","in":"path","required":true,"description":"Aircraft webhook watch identifier.","schema":{"type":"string","pattern":"^aw_[a-f0-9]{24}$"}}],"responses":{"202":{"description":"Synthetic test delivery queued.","headers":{"X-Aircraft-Plan":{"description":"Resolved Aircraft API plan for the authenticated account.","schema":{"type":"string","enum":["free","developer","business"]}},"X-Aircraft-Webhook-Watch-Limit":{"description":"Maximum configured Aircraft webhook watches permitted by the current plan.","schema":{"type":"integer","minimum":0,"maximum":250}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AircraftWebhookTestResponse"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/NotEntitled"},"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/watches/{watchId}/deliveries":{"get":{"operationId":"listAircraftWebhookDeliveries","summary":"List recent webhook delivery attempts","description":"Returns up to 20 recent deliveries and their bounded attempt history for one owned watch. Endpoint URLs, signing secrets, and response bodies are not copied into delivery-attempt history.","parameters":[{"name":"watchId","in":"path","required":true,"description":"Aircraft webhook watch identifier.","schema":{"type":"string","pattern":"^aw_[a-f0-9]{24}$"}},{"name":"limit","in":"query","required":false,"description":"Maximum recent webhook deliveries returned for troubleshooting.","schema":{"type":"integer","minimum":1,"maximum":20,"default":10}}],"responses":{"200":{"description":"Recent webhook deliveries for troubleshooting.","headers":{"X-Aircraft-Plan":{"description":"Resolved Aircraft API plan for the authenticated account.","schema":{"type":"string","enum":["free","developer","business"]}},"X-Aircraft-Webhook-Watch-Limit":{"description":"Maximum configured Aircraft webhook watches permitted by the current plan.","schema":{"type":"integer","minimum":0,"maximum":250}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AircraftWebhookDeliveryListResponse"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/aircraft/n-number/{nNumber}/status":{"get":{"operationId":"getAircraftNNumberStatus","summary":"Resolve reviewed FAA lifecycle status for an N-number","description":"Resolves one evidence-backed state across the current FAA registration, current FAA reservation, and current FAA deregistration authorities. registered takes precedence over reserved, which takes precedence over deregistered. unknown means only that the N-number is absent from all three reviewed authorities in the cited source snapshot; it does not mean the N-number is available, acquirable, or legally assignable. Reservation party names and addresses are never exposed. The service fails closed if the lifecycle projection is not aligned to the current FAA snapshot.","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":"Reviewed lifecycle status. unknown is a successful evidence-backed absence result, not an availability determination.","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/AircraftNNumberStatusResponse"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The authenticated API key does not include the Aircraft scope required by this operation.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","const":"forbidden"},"message":{"type":"string"}}}}},"example":{"error":{"code":"forbidden","message":"This API key is not permitted for this operation."}}}}},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"x-required-api-key-scope":"aircraft:read"}},"/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"},"403":{"description":"The authenticated API key does not include the Aircraft scope required by this operation.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","const":"forbidden"},"message":{"type":"string"}}}}},"example":{"error":{"code":"forbidden","message":"This API key is not permitted for this operation."}}}}},"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"}},"x-required-api-key-scope":"aircraft:read"}},"/aircraft/icao24/{hex}":{"get":{"operationId":"getAircraftByIcao24","summary":"Get the current aircraft registration for an ICAO24 / Mode-S code","description":"Authenticated exact current-registry lookup by six-hex-digit ICAO24 / Mode-S address. This resolves only the reviewed U.S. FAA current registry and does not provide ADS-B positions, flight data, transponder history, or global coverage.","parameters":[{"name":"hex","in":"path","required":true,"description":"Six-hex-digit ICAO24 / Mode-S aircraft address. Matching is case-insensitive and normalized to uppercase.","schema":{"type":"string","pattern":"^[0-9A-F]{6}$","example":"A00001"}}],"responses":{"200":{"description":"Current aircraft registration using the same response contract as N-number lookup.","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"},"403":{"description":"The authenticated API key does not include the Aircraft scope required by this operation.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","const":"forbidden"},"message":{"type":"string"}}}}},"example":{"error":{"code":"forbidden","message":"This API key is not permitted for this operation."}}}}},"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"}},"x-required-api-key-scope":"aircraft:read"}},"/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"},"403":{"description":"The authenticated API key does not include the Aircraft scope required by this operation.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","const":"forbidden"},"message":{"type":"string"}}}}},"example":{"error":{"code":"forbidden","message":"This API key is not permitted for this operation."}}}}},"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"}},"x-required-api-key-scope":"aircraft:read"}},"/aircraft/watch-lists":{"get":{"operationId":"listAircraftWatchLists","summary":"List named Aircraft watch lists","description":"Lists named multi-aircraft watch lists, delivery frequency, UTC digest schedule, next scheduled delivery, and unread alert counts. Retained lists remain readable after a paid-plan downgrade.","responses":{"200":{"description":"Configured watch lists and current plan limits.","headers":{"X-Aircraft-Plan":{"description":"Effective Aircraft API plan for this request.","schema":{"type":"string","enum":["free","developer","business"]}},"X-Aircraft-Watch-List-Limit":{"description":"Maximum possible named watch lists under the current watched-aircraft target limit.","schema":{"type":"integer","minimum":0,"maximum":250}},"X-Aircraft-Watched-Aircraft-Limit":{"description":"Maximum total N-number memberships across Aircraft watch lists for the current plan.","schema":{"type":"integer","minimum":0,"maximum":250}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AircraftWatchListListResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"post":{"operationId":"createAircraftWatchList","summary":"Create a named multi-aircraft watch list","description":"Creates one Developer or Business watch list over exact U.S. N-numbers. none records alert history only, realtime sends each matching change, and daily/weekly send one signed digest for each non-empty UTC schedule window. Empty windows advance without sending a webhook. The signing secret is returned only on successful creation.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AircraftWatchListInput"}}}},"responses":{"201":{"description":"Watch list created.","headers":{"X-Aircraft-Plan":{"description":"Effective Aircraft API plan for this request.","schema":{"type":"string","enum":["free","developer","business"]}},"X-Aircraft-Watch-List-Limit":{"description":"Maximum possible named watch lists under the current watched-aircraft target limit.","schema":{"type":"integer","minimum":0,"maximum":250}},"X-Aircraft-Watched-Aircraft-Limit":{"description":"Maximum total N-number memberships across Aircraft watch lists for the current plan.","schema":{"type":"integer","minimum":0,"maximum":250}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AircraftWatchListCreateResponse"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/NotEntitled"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"409":{"$ref":"#/components/responses/Conflict"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/aircraft/watch-lists/{watchId}":{"get":{"operationId":"getAircraftWatchList","summary":"Get one Aircraft watch list","parameters":[{"name":"watchId","in":"path","required":true,"description":"Opaque Aircraft watch-list identifier.","schema":{"type":"string","pattern":"^aw_[a-f0-9]{24}$"}}],"responses":{"200":{"description":"Owned watch list.","headers":{"X-Aircraft-Plan":{"description":"Effective Aircraft API plan for this request.","schema":{"type":"string","enum":["free","developer","business"]}},"X-Aircraft-Watch-List-Limit":{"description":"Maximum possible named watch lists under the current watched-aircraft target limit.","schema":{"type":"integer","minimum":0,"maximum":250}},"X-Aircraft-Watched-Aircraft-Limit":{"description":"Maximum total N-number memberships across Aircraft watch lists for the current plan.","schema":{"type":"integer","minimum":0,"maximum":250}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AircraftWatchListResponse"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"put":{"operationId":"replaceAircraftWatchList","summary":"Replace one Aircraft watch-list definition","description":"Replaces name, exact N-number membership, endpoint, event filters, delivery frequency, and UTC digest schedule. Pending change or digest deliveries from the prior definition are retired before the new configuration becomes active.","parameters":[{"name":"watchId","in":"path","required":true,"description":"Opaque Aircraft watch-list identifier.","schema":{"type":"string","pattern":"^aw_[a-f0-9]{24}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AircraftWatchListInput"}}}},"responses":{"200":{"description":"Updated watch list.","headers":{"X-Aircraft-Plan":{"description":"Effective Aircraft API plan for this request.","schema":{"type":"string","enum":["free","developer","business"]}},"X-Aircraft-Watch-List-Limit":{"description":"Maximum possible named watch lists under the current watched-aircraft target limit.","schema":{"type":"integer","minimum":0,"maximum":250}},"X-Aircraft-Watched-Aircraft-Limit":{"description":"Maximum total N-number memberships across Aircraft watch lists for the current plan.","schema":{"type":"integer","minimum":0,"maximum":250}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AircraftWatchListResponse"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/NotEntitled"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"409":{"$ref":"#/components/responses/Conflict"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"delete":{"operationId":"deleteAircraftWatchList","summary":"Delete one Aircraft watch list","description":"Deletes the owned list plus its target memberships, alert history, and retained delivery troubleshooting records.","parameters":[{"name":"watchId","in":"path","required":true,"description":"Opaque Aircraft watch-list identifier.","schema":{"type":"string","pattern":"^aw_[a-f0-9]{24}$"}}],"responses":{"204":{"description":"Watch list deleted."},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/aircraft/watch-lists/{watchId}/alerts":{"get":{"operationId":"listAircraftWatchAlerts","summary":"List alert history for one watch list","description":"Returns bounded alert history using the same public change representation as the Aircraft change feed. Use unread=true for unread-only history.","parameters":[{"name":"watchId","in":"path","required":true,"description":"Opaque Aircraft watch-list identifier.","schema":{"type":"string","pattern":"^aw_[a-f0-9]{24}$"}},{"name":"limit","in":"query","required":false,"description":"Maximum watch-list alerts returned.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","required":false,"description":"Opaque watch-alert pagination cursor.","schema":{"type":"string","maxLength":512}},{"name":"unread","in":"query","required":false,"description":"When true, return only unread watch alerts.","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Bounded alert history.","headers":{"X-Aircraft-Plan":{"description":"Effective Aircraft API plan for this request.","schema":{"type":"string","enum":["free","developer","business"]}},"X-Aircraft-Watch-List-Limit":{"description":"Maximum possible named watch lists under the current watched-aircraft target limit.","schema":{"type":"integer","minimum":0,"maximum":250}},"X-Aircraft-Watched-Aircraft-Limit":{"description":"Maximum total N-number memberships across Aircraft watch lists for the current plan.","schema":{"type":"integer","minimum":0,"maximum":250}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AircraftWatchAlertListResponse"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"post":{"operationId":"markAircraftWatchAlertsRead","summary":"Mark watch-list alerts read","description":"Marks up to 100 owned alert ids read. This remains available for retained alert history after a paid-plan downgrade.","parameters":[{"name":"watchId","in":"path","required":true,"description":"Opaque Aircraft watch-list identifier.","schema":{"type":"string","pattern":"^aw_[a-f0-9]{24}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AircraftWatchAlertReadInput"}}}},"responses":{"200":{"description":"Read state applied.","headers":{"X-Aircraft-Plan":{"description":"Effective Aircraft API plan for this request.","schema":{"type":"string","enum":["free","developer","business"]}},"X-Aircraft-Watch-List-Limit":{"description":"Maximum possible named watch lists under the current watched-aircraft target limit.","schema":{"type":"integer","minimum":0,"maximum":250}},"X-Aircraft-Watched-Aircraft-Limit":{"description":"Maximum total N-number memberships across Aircraft watch lists for the current plan.","schema":{"type":"integer","minimum":0,"maximum":250}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AircraftWatchAlertReadResponse"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/aircraft/{nNumber}/documents":{"get":{"operationId":"getAircraftDocumentIndex","summary":"Get FAA document-index evidence for one aircraft N-number","description":"Authenticated, bounded FAA Aircraft Document Index evidence for aircraft collateral matching exactly one canonical U.S. N-number. Results expose the FAA document identifier when present, document types, receipt/processing/correction dates, and source provenance. Party names and contact identity are not published. A document type or index row does not establish beneficial ownership, current legal ownership, clear or encumbered title, a current lien, lien priority, release completeness, sale completion, legal transfer, or a title-search result.","parameters":[{"name":"nNumber","in":"path","required":true,"description":"U.S. aircraft N-number. Matching is case-insensitive and 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":"limit","in":"query","required":false,"description":"Maximum indexed document records returned. One shared safety bound applies while production query-cost evidence is collected.","schema":{"type":"integer","minimum":1,"maximum":50,"default":25}},{"name":"cursor","in":"query","required":false,"description":"Opaque N-number- and FAA-source-snapshot-bound keyset cursor returned by the previous page. A cursor from a superseded FAA snapshot fails closed with 400 invalid_request guidance to restart pagination rather than mixing pages across source snapshots.","schema":{"type":"string","minLength":1,"maxLength":1024}}],"responses":{"200":{"description":"Bounded FAA document-index evidence. A valid N-number with no matching rows 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/AircraftDocumentIndexResponse"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The authenticated API key does not include the Aircraft scope required by this operation.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","const":"forbidden"},"message":{"type":"string"}}}}},"example":{"error":{"code":"forbidden","message":"This API key is not permitted for this operation."}}}}},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"x-required-api-key-scope":"aircraft:read"}},"/aircraft/usage":{"get":{"operationId":"getAircraftApiUsage","summary":"Get current Aircraft plan, monthly usage, and key scopes","description":"Authenticated read-only Aircraft control-plane view. This endpoint is protected by the shared account-level developer API safety ceiling but does not reserve or consume Aircraft monthly data-plane quota.","x-required-api-key-scope":"aircraft:usage","responses":{"200":{"description":"Current Aircraft plan, monthly usage, remaining quota, reset time, and effective Aircraft scopes.","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 data-plane requests permitted per minute for the resolved Aircraft API plan.","schema":{"type":"integer","minimum":1}},"X-Aircraft-Quota-Limit":{"description":"Monthly Aircraft data-plane request quota for the resolved plan.","schema":{"type":"integer","minimum":1}},"X-Aircraft-Quota-Remaining":{"description":"Current monthly Aircraft data-plane requests remaining. Reading this endpoint does not decrement the value.","schema":{"type":"integer","minimum":0}},"X-Aircraft-Quota-Reset":{"description":"UTC timestamp when the current Aircraft monthly quota window resets.","schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"type":"object","additionalProperties":false,"required":["plan","usage","credential"],"properties":{"plan":{"type":"object","additionalProperties":false,"required":["id","requestsPerMinute","monthlyRequestLimit"],"properties":{"id":{"type":"string","enum":["free","developer","business","demo"]},"requestsPerMinute":{"type":"integer","minimum":1},"monthlyRequestLimit":{"type":"integer","minimum":1}}},"usage":{"type":"object","additionalProperties":false,"required":["requestCount","remaining","limit","resetAt"],"properties":{"requestCount":{"type":"integer","minimum":0},"remaining":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1},"resetAt":{"type":"string","format":"date-time"}}},"credential":{"type":"object","additionalProperties":false,"required":["mode","aircraftScopes"],"properties":{"mode":{"type":"string","enum":["legacy_unscoped","scoped","first_party_demo"]},"aircraftScopes":{"type":"array","uniqueItems":true,"items":{"type":"string","enum":["aircraft:read","aircraft:query","aircraft:usage"]}}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The authenticated API key does not include the Aircraft scope required by this operation.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","const":"forbidden"},"message":{"type":"string"}}}}},"example":{"error":{"code":"forbidden","message":"This API key is not permitted for this operation."}}}}},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"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, change-feed window/filter/cursor, discovery filters, cursor, or pagination parameters are invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"At least one reviewed aircraft discovery filter is required."}}}}},"Unauthorized":{"description":"A valid Grizzly Bulls API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"unauthenticated","message":"A valid API key is required."}}}}},"NotFound":{"description":"No matching current or retained registration was found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"not_found","message":"No current aircraft registration was found for that N-number."}}}}},"MethodNotAllowed":{"description":"The HTTP method is not supported by this endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"method_not_allowed","message":"Method not allowed."}}}}},"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"},"example":{"error":{"code":"rate_limited","message":"Aircraft API usage limit exceeded."}}}}},"ExportRunLimitReached":{"description":"The monthly asynchronous Aircraft export-run allowance for the current plan is exhausted.","headers":{"X-Aircraft-Plan":{"description":"Resolved Aircraft API plan for the authenticated account.","schema":{"type":"string","enum":["free","developer","business"]}},"X-Aircraft-Saved-Report-Limit":{"description":"Maximum saved Aircraft report definitions permitted by the current plan.","schema":{"type":"integer","minimum":0,"maximum":250}},"X-Aircraft-Monthly-Export-Run-Limit":{"description":"Maximum asynchronous export runs per UTC calendar month.","schema":{"type":"integer","minimum":0,"maximum":1000}},"X-Aircraft-Export-Row-Limit":{"description":"Maximum rows permitted in one completed export.","schema":{"type":"integer","minimum":0,"maximum":25000}},"X-Aircraft-Export-Retention-Hours":{"description":"Hours a completed export remains downloadable.","schema":{"type":"integer","minimum":0,"maximum":72}},"Retry-After":{"description":"Seconds until the next UTC calendar-month export allowance begins.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"limit_reached","message":"Monthly Aircraft export run limit reached for this plan."}}}}},"InternalError":{"description":"The request failed without exposing provider or server internals.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"internal_error","message":"The request could not be completed."}}}}},"NotEntitled":{"description":"The current Aircraft API plan does not include the requested paid Aircraft capability.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"not_entitled","message":"This Aircraft capability requires a Developer or Business plan."}}}}},"SavedReportConflict":{"description":"The saved-report mutation conflicts with an existing name or the current plan saved-report ceiling.","headers":{"X-Aircraft-Plan":{"description":"Resolved Aircraft API plan for the authenticated account.","schema":{"type":"string","enum":["free","developer","business"]}},"X-Aircraft-Saved-Report-Limit":{"description":"Maximum saved Aircraft report definitions permitted by the current plan.","schema":{"type":"integer","minimum":0,"maximum":250}},"X-Aircraft-Monthly-Export-Run-Limit":{"description":"Maximum asynchronous export runs per UTC calendar month.","schema":{"type":"integer","minimum":0,"maximum":1000}},"X-Aircraft-Export-Row-Limit":{"description":"Maximum rows permitted in one completed export.","schema":{"type":"integer","minimum":0,"maximum":25000}},"X-Aircraft-Export-Retention-Hours":{"description":"Hours a completed export remains downloadable.","schema":{"type":"integer","minimum":0,"maximum":72}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"duplicateName":{"value":{"error":{"code":"conflict","message":"A saved report with that name already exists."}}},"planLimit":{"value":{"error":{"code":"limit_reached","message":"Aircraft saved report limit reached for this plan."}}}}}}},"Conflict":{"description":"The requested Aircraft control-plane mutation conflicts with retained state or a plan-owned limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"conflict","message":"An equivalent Aircraft webhook watch already exists."}}}}},"NotReady":{"description":"The requested asynchronous Aircraft export is not yet completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"not_ready","message":"Aircraft export is not ready for download."}}}}},"Expired":{"description":"The requested retained export has expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"expired","message":"Aircraft export has expired."}}}}},"ServiceUnavailable":{"description":"The aircraft read model, authentication authority, entitlement authority, or durable usage meter is temporarily unavailable. Use bounded backoff rather than a tight retry loop.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"service_unavailable","message":"Aircraft data is temporarily unavailable."}}}}}},"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_entitled","conflict","limit_reached","not_found","not_ready","expired","method_not_allowed","service_unavailable","internal_error"]},"message":{"type":"string"}}}}},"AircraftRegistryReportDefinition":{"type":"object","additionalProperties":false,"required":["kind","query"],"properties":{"kind":{"type":"string","const":"registry_query"},"query":{"type":"object","additionalProperties":false,"required":["filters","columns","sort"],"properties":{"filters":{"type":"array","minItems":1,"maxItems":8,"items":{"type":"object","additionalProperties":false,"required":["column","operator","values"],"properties":{"column":{"type":"string","enum":["aircraftId","nNumber","sourceRegistrationStatusCode","serialNumber","manufactureYear","manufacturer","model","registrantState"]},"operator":{"type":"string","enum":["equals","contains","starts_with","in","gte","lte","between"]},"values":{"type":"array","minItems":1,"maxItems":10,"items":{"oneOf":[{"type":"string"},{"type":"integer"}]}}}}},"columns":{"type":"array","minItems":1,"items":{"type":"string","enum":["aircraftId","nNumber","sourceRegistrationStatusCode","serialNumber","manufactureYear","manufacturer","model","registrantState"]}},"sort":{"type":"object","additionalProperties":false,"required":["column","direction"],"properties":{"column":{"type":"string","enum":["aircraftId","nNumber","sourceRegistrationStatusCode","serialNumber","manufactureYear","manufacturer","model","registrantState"]},"direction":{"type":"string","enum":["asc","desc"]}}}}}}},"AircraftChangeReportDefinition":{"type":"object","additionalProperties":false,"required":["kind","query"],"properties":{"kind":{"type":"string","const":"change_feed"},"query":{"type":"object","additionalProperties":false,"required":["since","until","eventType"],"properties":{"since":{"type":"string","format":"date-time"},"until":{"type":"string","format":"date-time"},"eventType":{"type":["string","null"],"enum":["registration_added","registration_removed","registration_record_changed","aircraft_assignment_changed","status_changed","registrant_changed","registrant_pii_withheld","registrant_pii_released",null]}}}}},"AircraftSavedReportDefinition":{"oneOf":[{"$ref":"#/components/schemas/AircraftRegistryReportDefinition"},{"$ref":"#/components/schemas/AircraftChangeReportDefinition"}]},"AircraftSavedReportInput":{"type":"object","additionalProperties":false,"required":["name","definition"],"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"definition":{"$ref":"#/components/schemas/AircraftSavedReportDefinition"}}},"AircraftSavedReport":{"type":"object","additionalProperties":false,"required":["reportId","name","kind","definition","createdAt","updatedAt"],"properties":{"reportId":{"type":"string","pattern":"^arp_[a-f0-9]{24}$"},"name":{"type":"string","minLength":1,"maxLength":120},"kind":{"type":"string","enum":["registry_query","change_feed"]},"definition":{"$ref":"#/components/schemas/AircraftSavedReportDefinition"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"AircraftSavedReportResponse":{"type":"object","additionalProperties":false,"required":["data","limits"],"properties":{"data":{"$ref":"#/components/schemas/AircraftSavedReport"},"limits":{"type":"object","additionalProperties":false,"required":["savedReportLimit"],"properties":{"savedReportLimit":{"type":"integer","minimum":1,"maximum":250}}}}},"AircraftSavedReportListResponse":{"type":"object","additionalProperties":false,"required":["data","limits"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AircraftSavedReport"}},"limits":{"type":"object","additionalProperties":false,"required":["savedReportLimit"],"properties":{"savedReportLimit":{"type":"integer","minimum":0,"maximum":250}}}}},"AircraftExportCreateInput":{"type":"object","additionalProperties":false,"required":["format"],"properties":{"format":{"type":"string","enum":["csv","json","xlsx"]},"reportId":{"type":["string","null"],"pattern":"^arp_[a-f0-9]{24}$"},"definition":{"oneOf":[{"$ref":"#/components/schemas/AircraftSavedReportDefinition"},{"type":"null"}]}},"description":"Supply exactly one of reportId or definition."},"AircraftExportRun":{"type":"object","additionalProperties":false,"required":["exportId","reportId","kind","format","status","rowLimit","rowCount","storageBytes","storageSha256","errorCode","createdAt","claimedAt","completedAt","expiresAt"],"properties":{"exportId":{"type":"string","pattern":"^aex_[a-f0-9]{24}$"},"reportId":{"type":["string","null"],"pattern":"^arp_[a-f0-9]{24}$"},"kind":{"type":"string","enum":["registry_query","change_feed"]},"format":{"type":"string","enum":["csv","json","xlsx"]},"status":{"type":"string","enum":["queued","running","completed","failed","expired"]},"rowLimit":{"type":"integer","minimum":1,"maximum":25000},"rowCount":{"type":["integer","null"],"minimum":0,"maximum":25000},"storageBytes":{"type":["integer","null"],"minimum":0,"maximum":67108864},"storageSha256":{"type":["string","null"],"pattern":"^[a-f0-9]{64}$"},"errorCode":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"claimedAt":{"type":["string","null"],"format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"expiresAt":{"type":["string","null"],"format":"date-time"}}},"AircraftExportRunResponse":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AircraftExportRun"}}},"AircraftExportRunListResponse":{"type":"object","additionalProperties":false,"required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AircraftExportRun"}},"pagination":{"type":"object","additionalProperties":false,"required":["limit"],"properties":{"limit":{"type":"integer","minimum":1,"maximum":50}}}}},"AircraftExportCreateResponse":{"type":"object","additionalProperties":false,"required":["data","limits"],"properties":{"data":{"$ref":"#/components/schemas/AircraftExportRun"},"limits":{"type":"object","additionalProperties":false,"required":["monthlyExportRunLimit","exportRowLimit","retentionHours"],"properties":{"monthlyExportRunLimit":{"type":"integer","minimum":1,"maximum":1000},"exportRowLimit":{"type":"integer","minimum":1,"maximum":25000},"retentionHours":{"type":"integer","minimum":1,"maximum":72}}}}},"AircraftWebhookWatch":{"type":"object","additionalProperties":false,"required":["watchId","name","nNumber","nNumbers","endpointUrl","eventTypes","frequency","status","unreadAlertCount","createdAt","updatedAt","schedule","nextDeliveryAt"],"properties":{"watchId":{"type":"string","pattern":"^aw_[a-f0-9]{24}$"},"name":{"type":"string","minLength":1,"maxLength":80},"nNumber":{"type":"string","pattern":"^N(?:[1-9][0-9]{0,4}|[1-9][0-9]{0,3}[A-HJ-NP-Z]|[1-9][0-9]{0,2}[A-HJ-NP-Z]{2})$"},"nNumbers":{"type":"array","minItems":1,"maxItems":250,"uniqueItems":true,"items":{"type":"string","pattern":"^N(?:[1-9][0-9]{0,4}|[1-9][0-9]{0,3}[A-HJ-NP-Z]|[1-9][0-9]{0,2}[A-HJ-NP-Z]{2})$"}},"endpointUrl":{"type":"string","format":"uri","maxLength":2048},"eventTypes":{"type":"array","minItems":1,"maxItems":8,"uniqueItems":true,"items":{"type":"string","enum":["registration_added","registration_removed","registration_record_changed","aircraft_assignment_changed","status_changed","registrant_changed","registrant_pii_withheld","registrant_pii_released"]}},"frequency":{"type":"string","enum":["none","realtime","daily","weekly"]},"status":{"type":"string","const":"active"},"unreadAlertCount":{"type":"integer","minimum":0},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"schedule":{"oneOf":[{"type":"null"},{"type":"object","additionalProperties":false,"required":["timeUtc"],"properties":{"timeUtc":{"type":"string","pattern":"^(?:[01]\\d|2[0-3]):[0-5]\\d$","description":"Daily delivery time in UTC using 24-hour HH:MM."}}},{"type":"object","additionalProperties":false,"required":["dayOfWeek","timeUtc"],"properties":{"dayOfWeek":{"type":"string","enum":["sunday","monday","tuesday","wednesday","thursday","friday","saturday"]},"timeUtc":{"type":"string","pattern":"^(?:[01]\\d|2[0-3]):[0-5]\\d$","description":"Weekly delivery time in UTC using 24-hour HH:MM."}}}],"description":"UTC digest schedule. Must be null for none/realtime, time-only for daily, and weekday plus time for weekly."},"nextDeliveryAt":{"type":["string","null"],"format":"date-time","description":"Next scheduled digest boundary, or null when delivery is none/realtime."}}},"AircraftWebhookWatchCreateInput":{"type":"object","additionalProperties":false,"required":["nNumber","endpointUrl"],"properties":{"nNumber":{"type":"string","description":"Canonical or normalizable U.S. N-number. AIR14F intentionally does not support saved searches or aircraftId watches."},"endpointUrl":{"type":"string","format":"uri","maxLength":2048,"description":"HTTPS public-Internet endpoint. Redirects are not followed."},"eventTypes":{"type":"array","minItems":1,"maxItems":8,"uniqueItems":true,"description":"Optional exact AIR14C event-type subset. Omit to watch all reviewed event types.","items":{"type":"string","enum":["registration_added","registration_removed","registration_record_changed","aircraft_assignment_changed","status_changed","registrant_changed","registrant_pii_withheld","registrant_pii_released"]}}}},"AircraftWebhookWatchCreated":{"type":"object","additionalProperties":false,"required":["watchId","name","nNumber","nNumbers","endpointUrl","eventTypes","frequency","status","unreadAlertCount","createdAt","updatedAt","schedule","nextDeliveryAt","signingSecret","signingVersion"],"properties":{"watchId":{"type":"string","pattern":"^aw_[a-f0-9]{24}$"},"name":{"type":"string","minLength":1,"maxLength":80},"nNumber":{"type":"string","pattern":"^N(?:[1-9][0-9]{0,4}|[1-9][0-9]{0,3}[A-HJ-NP-Z]|[1-9][0-9]{0,2}[A-HJ-NP-Z]{2})$"},"nNumbers":{"type":"array","minItems":1,"maxItems":250,"uniqueItems":true,"items":{"type":"string","pattern":"^N(?:[1-9][0-9]{0,4}|[1-9][0-9]{0,3}[A-HJ-NP-Z]|[1-9][0-9]{0,2}[A-HJ-NP-Z]{2})$"}},"endpointUrl":{"type":"string","format":"uri","maxLength":2048},"eventTypes":{"type":"array","minItems":1,"maxItems":8,"uniqueItems":true,"items":{"type":"string","enum":["registration_added","registration_removed","registration_record_changed","aircraft_assignment_changed","status_changed","registrant_changed","registrant_pii_withheld","registrant_pii_released"]}},"frequency":{"type":"string","enum":["none","realtime","daily","weekly"]},"status":{"type":"string","const":"active"},"unreadAlertCount":{"type":"integer","minimum":0},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"schedule":{"oneOf":[{"type":"null"},{"type":"object","additionalProperties":false,"required":["timeUtc"],"properties":{"timeUtc":{"type":"string","pattern":"^(?:[01]\\d|2[0-3]):[0-5]\\d$","description":"Daily delivery time in UTC using 24-hour HH:MM."}}},{"type":"object","additionalProperties":false,"required":["dayOfWeek","timeUtc"],"properties":{"dayOfWeek":{"type":"string","enum":["sunday","monday","tuesday","wednesday","thursday","friday","saturday"]},"timeUtc":{"type":"string","pattern":"^(?:[01]\\d|2[0-3]):[0-5]\\d$","description":"Weekly delivery time in UTC using 24-hour HH:MM."}}}],"description":"UTC digest schedule. Must be null for none/realtime, time-only for daily, and weekday plus time for weekly."},"nextDeliveryAt":{"type":["string","null"],"format":"date-time","description":"Next scheduled digest boundary, or null when delivery is none/realtime."},"signingSecret":{"type":"string","pattern":"^whsec_[A-Za-z0-9_-]+$"},"signingVersion":{"type":"string","const":"v1"}}},"AircraftWebhookWatchCreateResponse":{"type":"object","additionalProperties":false,"required":["data","limits"],"properties":{"data":{"$ref":"#/components/schemas/AircraftWebhookWatchCreated"},"limits":{"type":"object","additionalProperties":false,"required":["watchLimit"],"properties":{"watchLimit":{"type":"integer","minimum":1,"maximum":250}}}}},"AircraftWebhookWatchListResponse":{"type":"object","additionalProperties":false,"required":["data","limits"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AircraftWebhookWatch"}},"limits":{"type":"object","additionalProperties":false,"required":["watchLimit"],"properties":{"watchLimit":{"type":"integer","minimum":0,"maximum":250}}}}},"AircraftWebhookDeliveryAttempt":{"type":"object","additionalProperties":false,"required":["attemptNumber","attemptedAt","outcome","httpStatus","errorCode","durationMs"],"properties":{"attemptNumber":{"type":"integer","minimum":1,"maximum":5},"attemptedAt":{"type":"string","format":"date-time"},"outcome":{"type":"string","enum":["delivered","retryable","failed"]},"httpStatus":{"type":["integer","null"],"minimum":100,"maximum":599},"errorCode":{"type":["string","null"]},"durationMs":{"type":"integer","minimum":0,"maximum":60000}}},"AircraftWebhookDelivery":{"type":"object","additionalProperties":false,"required":["deliveryId","eventId","eventKind","eventType","nNumber","observedAt","attemptCount","nextAttemptAt","deliveredAt","terminalAt","terminalReason","createdAt","attempts"],"properties":{"deliveryId":{"type":"string","pattern":"^awd_[a-f0-9]{24}$"},"eventId":{"type":"string","pattern":"^aevt_(?:test_)?[a-f0-9]{24,32}$"},"eventKind":{"type":"string","enum":["change","test"]},"eventType":{"type":["string","null"],"enum":["registration_added","registration_removed","registration_record_changed","aircraft_assignment_changed","status_changed","registrant_changed","registrant_pii_withheld","registrant_pii_released",null]},"nNumber":{"type":"string","pattern":"^N(?:[1-9][0-9]{0,4}|[1-9][0-9]{0,3}[A-HJ-NP-Z]|[1-9][0-9]{0,2}[A-HJ-NP-Z]{2})$"},"observedAt":{"type":["string","null"],"format":"date-time"},"attemptCount":{"type":"integer","minimum":0,"maximum":5},"nextAttemptAt":{"type":["string","null"],"format":"date-time"},"deliveredAt":{"type":["string","null"],"format":"date-time"},"terminalAt":{"type":["string","null"],"format":"date-time"},"terminalReason":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"attempts":{"type":"array","maxItems":5,"items":{"$ref":"#/components/schemas/AircraftWebhookDeliveryAttempt"}}}},"AircraftWebhookDeliveryListResponse":{"type":"object","additionalProperties":false,"required":["data","watch","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AircraftWebhookDelivery"}},"watch":{"type":"object","additionalProperties":false,"required":["watchId","nNumber"],"properties":{"watchId":{"type":"string","pattern":"^aw_[a-f0-9]{24}$"},"nNumber":{"type":"string","pattern":"^N(?:[1-9][0-9]{0,4}|[1-9][0-9]{0,3}[A-HJ-NP-Z]|[1-9][0-9]{0,2}[A-HJ-NP-Z]{2})$"}}},"pagination":{"type":"object","additionalProperties":false,"required":["limit"],"properties":{"limit":{"type":"integer","minimum":1,"maximum":20}}}}},"AircraftWebhookTestResponse":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"type":"object","additionalProperties":false,"required":["deliveryId","eventId","status","createdAt"],"properties":{"deliveryId":{"type":"string","pattern":"^awd_[a-f0-9]{24}$"},"eventId":{"type":"string","pattern":"^aevt_test_[a-f0-9]{24}$"},"status":{"type":"string","const":"queued"},"createdAt":{"type":"string","format":"date-time"}}}}},"AircraftRegistryQueryRecord":{"type":"object","additionalProperties":false,"required":["contractVersion"],"properties":{"contractVersion":{"type":"string","const":"aircraft-query-v1"},"aircraftId":{"type":["string","null"],"format":"uuid"},"nNumber":{"type":"string"},"sourceRegistrationStatusCode":{"type":["string","null"]},"serialNumber":{"type":["string","null"]},"manufactureYear":{"type":["integer","null"]},"manufacturer":{"type":["string","null"]},"model":{"type":["string","null"]},"registrantState":{"type":["string","null"]}}},"AircraftRegistryQueryResponse":{"type":"object","additionalProperties":false,"required":["data","query","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AircraftRegistryQueryRecord"}},"query":{"type":"object","additionalProperties":false,"required":["columns","sort"],"properties":{"columns":{"type":"array","items":{"type":"string","enum":["aircraftId","nNumber","sourceRegistrationStatusCode","serialNumber","manufactureYear","manufacturer","model","registrantState"]}},"sort":{"type":"object","additionalProperties":false,"required":["column","direction"],"properties":{"column":{"type":"string","enum":["aircraftId","nNumber","sourceRegistrationStatusCode","serialNumber","manufactureYear","manufacturer","model","registrantState"]},"direction":{"type":"string","enum":["asc","desc"]}}}}},"pagination":{"type":"object","additionalProperties":false,"required":["limit","nextCursor"],"properties":{"limit":{"type":"integer","minimum":1,"maximum":50},"nextCursor":{"type":["string","null"],"maxLength":4096}}}}},"AircraftRegistryQueryColumn":{"type":"object","additionalProperties":false,"required":["name","type","filterable","sortable","operators"],"properties":{"name":{"type":"string","enum":["aircraftId","nNumber","sourceRegistrationStatusCode","serialNumber","manufactureYear","manufacturer","model","registrantState"]},"type":{"type":"string","enum":["string","integer","uuid"]},"filterable":{"type":"boolean"},"sortable":{"type":"boolean"},"operators":{"type":"array","items":{"type":"string","enum":["equals","contains","starts_with","in","gte","lte","between"]}}}},"AircraftRegistryColumnsResponse":{"type":"object","additionalProperties":false,"required":["data","grammar"],"properties":{"data":{"type":"array","minItems":8,"maxItems":8,"items":{"$ref":"#/components/schemas/AircraftRegistryQueryColumn"}},"grammar":{"type":"object","additionalProperties":false,"required":["filter","columns","sort","maxFilters","maxInValues"],"properties":{"filter":{"type":"string"},"columns":{"type":"string"},"sort":{"type":"string"},"maxFilters":{"type":"integer","minimum":1,"maximum":8},"maxInValues":{"type":"integer","minimum":1}}}}},"AircraftDiscoveryRecord":{"type":"object","additionalProperties":false,"required":["contractVersion","aircraftId","nNumber","sourceRegistrationStatusCode","serialNumber","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"]},"serialNumber":{"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"}}},"ReservedNNumberContext":{"type":"object","additionalProperties":false,"required":["reserveDate","sourceReservationTypeCode","expirationNoticeDate","purgeDate"],"properties":{"reserveDate":{"type":["string","null"],"format":"date"},"sourceReservationTypeCode":{"type":["string","null"]},"expirationNoticeDate":{"type":["string","null"],"format":"date"},"purgeDate":{"type":["string","null"],"format":"date"}}},"DeregisteredNNumberContext":{"type":"object","additionalProperties":false,"required":["aircraftId","serialNumber","manufactureYear","sourceRegistrationStatusCode","cancellationDate","exportCountryCode","lastActivityDate","certificateIssueDate","airworthinessDate","modeSCodeOctal","modeSCodeHex","matchingRecordCount"],"properties":{"aircraftId":{"type":["string","null"],"format":"uuid"},"serialNumber":{"type":["string","null"]},"manufactureYear":{"type":["integer","null"]},"sourceRegistrationStatusCode":{"type":["string","null"]},"cancellationDate":{"type":["string","null"],"format":"date"},"exportCountryCode":{"type":["string","null"]},"lastActivityDate":{"type":["string","null"],"format":"date"},"certificateIssueDate":{"type":["string","null"],"format":"date"},"airworthinessDate":{"type":["string","null"],"format":"date"},"modeSCodeOctal":{"type":["string","null"]},"modeSCodeHex":{"type":["string","null"]},"matchingRecordCount":{"type":"integer","minimum":1,"description":"Number of current DEREG rows observed for this N-number. Context fields come from the deterministic latest reviewed row."}}},"AircraftNNumberStatus":{"type":"object","additionalProperties":false,"required":["contractVersion","nNumber","state","availability","observedAt","source","registered","reserved","deregistered"],"properties":{"contractVersion":{"type":"string","const":"aircraft-n-number-status-v1"},"nNumber":{"type":"string"},"state":{"type":"string","enum":["registered","reserved","deregistered","unknown"]},"availability":{"type":"string","const":"not_determined","description":"AIR14D never infers FAA N-number availability from registry absence or lifecycle state."},"observedAt":{"type":"string","format":"date-time"},"source":{"$ref":"#/components/schemas/SourceSnapshot"},"registered":{"oneOf":[{"$ref":"#/components/schemas/AircraftCurrentRecord"},{"type":"null"}]},"reserved":{"oneOf":[{"$ref":"#/components/schemas/ReservedNNumberContext"},{"type":"null"}]},"deregistered":{"oneOf":[{"$ref":"#/components/schemas/DeregisteredNNumberContext"},{"type":"null"}]}}},"AircraftNNumberStatusResponse":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AircraftNNumberStatus"}}},"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"}}},"AircraftChangeDiffValue":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"object","additionalProperties":false,"required":["modeSCodeOctal","modeSCodeHex"],"properties":{"modeSCodeOctal":{"type":["string","null"]},"modeSCodeHex":{"type":["string","null"]}}}]},"AircraftChangeDiffSide":{"type":"object","additionalProperties":false,"required":["available","value"],"properties":{"available":{"type":"boolean","description":"Whether a matching retained public version exists on this side of the observed change. false is distinct from an available retained value that is itself null."},"value":{"$ref":"#/components/schemas/AircraftChangeDiffValue"}}},"AircraftChangeDiff":{"type":"object","additionalProperties":false,"required":["field","before","after"],"properties":{"field":{"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"]},"before":{"$ref":"#/components/schemas/AircraftChangeDiffSide"},"after":{"$ref":"#/components/schemas/AircraftChangeDiffSide"}}},"AircraftChangeFeedItem":{"type":"object","additionalProperties":false,"required":["event","diffs"],"properties":{"event":{"$ref":"#/components/schemas/HistoryEvent"},"diffs":{"type":"array","description":"Privacy-safe before/after values for the subset of changedFields supported by retained public versions. Historical make/model descriptions are intentionally not reconstructed from current reference data, and sensitive registrant values never appear here.","items":{"$ref":"#/components/schemas/AircraftChangeDiff"}}}},"AircraftChangeFeedWindow":{"type":"object","additionalProperties":false,"required":["since","until","eventType"],"properties":{"since":{"type":"string","format":"date-time"},"until":{"type":"string","format":"date-time"},"eventType":{"type":["string","null"],"enum":["registration_added","registration_removed","registration_record_changed","aircraft_assignment_changed","status_changed","registrant_changed","registrant_pii_withheld","registrant_pii_released",null]}}},"AircraftChangeFeedPagination":{"type":"object","additionalProperties":false,"required":["limit","nextCursor"],"properties":{"limit":{"type":"integer","minimum":1,"maximum":50},"nextCursor":{"type":["string","null"],"maxLength":2048}}},"AircraftChangeFeedResponse":{"type":"object","additionalProperties":false,"required":["data","window","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AircraftChangeFeedItem"}},"window":{"$ref":"#/components/schemas/AircraftChangeFeedWindow"},"pagination":{"$ref":"#/components/schemas/AircraftChangeFeedPagination"}}},"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"}}}}},"AircraftWatchListInput":{"type":"object","additionalProperties":false,"required":["name","nNumbers","endpointUrl"],"properties":{"name":{"type":"string","minLength":1,"maxLength":80},"nNumbers":{"type":"array","minItems":1,"maxItems":250,"uniqueItems":true,"items":{"type":"string","pattern":"^N(?:[1-9][0-9]{0,4}|[1-9][0-9]{0,3}[A-HJ-NP-Z]|[1-9][0-9]{0,2}[A-HJ-NP-Z]{2})$"}},"endpointUrl":{"type":"string","format":"uri","maxLength":2048},"eventTypes":{"type":"array","minItems":1,"maxItems":8,"uniqueItems":true,"items":{"type":"string","enum":["registration_added","registration_removed","registration_record_changed","aircraft_assignment_changed","status_changed","registrant_changed","registrant_pii_withheld","registrant_pii_released"]}},"frequency":{"type":"string","enum":["none","realtime","daily","weekly"],"default":"realtime"},"schedule":{"oneOf":[{"type":"null"},{"type":"object","additionalProperties":false,"required":["timeUtc"],"properties":{"timeUtc":{"type":"string","pattern":"^(?:[01]\\d|2[0-3]):[0-5]\\d$","description":"Daily delivery time in UTC using 24-hour HH:MM."}}},{"type":"object","additionalProperties":false,"required":["dayOfWeek","timeUtc"],"properties":{"dayOfWeek":{"type":"string","enum":["sunday","monday","tuesday","wednesday","thursday","friday","saturday"]},"timeUtc":{"type":"string","pattern":"^(?:[01]\\d|2[0-3]):[0-5]\\d$","description":"Weekly delivery time in UTC using 24-hour HH:MM."}}}],"description":"UTC digest schedule. Must be null for none/realtime, time-only for daily, and weekday plus time for weekly."}},"description":"For daily delivery provide schedule.timeUtc. For weekly delivery provide schedule.dayOfWeek and schedule.timeUtc. Times are UTC. Omit schedule for realtime or none."},"AircraftWatchList":{"$ref":"#/components/schemas/AircraftWebhookWatch"},"AircraftWatchListCreated":{"type":"object","additionalProperties":false,"required":["watchId","name","nNumber","nNumbers","endpointUrl","eventTypes","frequency","status","unreadAlertCount","createdAt","updatedAt","schedule","nextDeliveryAt","signingSecret","signingVersion"],"properties":{"watchId":{"type":"string","pattern":"^aw_[a-f0-9]{24}$"},"name":{"type":"string","minLength":1,"maxLength":80},"nNumber":{"type":"string","pattern":"^N(?:[1-9][0-9]{0,4}|[1-9][0-9]{0,3}[A-HJ-NP-Z]|[1-9][0-9]{0,2}[A-HJ-NP-Z]{2})$"},"nNumbers":{"type":"array","minItems":1,"maxItems":250,"uniqueItems":true,"items":{"type":"string","pattern":"^N(?:[1-9][0-9]{0,4}|[1-9][0-9]{0,3}[A-HJ-NP-Z]|[1-9][0-9]{0,2}[A-HJ-NP-Z]{2})$"}},"endpointUrl":{"type":"string","format":"uri","maxLength":2048},"eventTypes":{"type":"array","minItems":1,"maxItems":8,"uniqueItems":true,"items":{"type":"string","enum":["registration_added","registration_removed","registration_record_changed","aircraft_assignment_changed","status_changed","registrant_changed","registrant_pii_withheld","registrant_pii_released"]}},"frequency":{"type":"string","enum":["none","realtime","daily","weekly"]},"status":{"type":"string","const":"active"},"unreadAlertCount":{"type":"integer","minimum":0},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"schedule":{"oneOf":[{"type":"null"},{"type":"object","additionalProperties":false,"required":["timeUtc"],"properties":{"timeUtc":{"type":"string","pattern":"^(?:[01]\\d|2[0-3]):[0-5]\\d$","description":"Daily delivery time in UTC using 24-hour HH:MM."}}},{"type":"object","additionalProperties":false,"required":["dayOfWeek","timeUtc"],"properties":{"dayOfWeek":{"type":"string","enum":["sunday","monday","tuesday","wednesday","thursday","friday","saturday"]},"timeUtc":{"type":"string","pattern":"^(?:[01]\\d|2[0-3]):[0-5]\\d$","description":"Weekly delivery time in UTC using 24-hour HH:MM."}}}],"description":"UTC digest schedule. Must be null for none/realtime, time-only for daily, and weekday plus time for weekly."},"nextDeliveryAt":{"type":["string","null"],"format":"date-time","description":"Next scheduled digest boundary, or null when delivery is none/realtime."},"signingSecret":{"type":"string","pattern":"^whsec_[A-Za-z0-9_-]+$"},"signingVersion":{"type":"string","const":"v1"}}},"AircraftWatchListLimits":{"type":"object","additionalProperties":false,"required":["watchListLimit","watchedAircraftLimit"],"properties":{"watchListLimit":{"type":"integer","minimum":0,"maximum":250},"watchedAircraftLimit":{"type":"integer","minimum":0,"maximum":250}}},"AircraftWatchListCreateResponse":{"type":"object","additionalProperties":false,"required":["data","limits"],"properties":{"data":{"$ref":"#/components/schemas/AircraftWatchListCreated"},"limits":{"$ref":"#/components/schemas/AircraftWatchListLimits"}}},"AircraftWatchListListResponse":{"type":"object","additionalProperties":false,"required":["data","limits"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AircraftWatchList"}},"limits":{"$ref":"#/components/schemas/AircraftWatchListLimits"}}},"AircraftWatchListResponse":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AircraftWatchList"}}},"AircraftWatchAlert":{"type":"object","additionalProperties":false,"required":["alertId","observedAt","sourceArchiveSha256","eventType","nNumber","readAt","createdAt","change"],"properties":{"alertId":{"type":"string","pattern":"^aal_[a-f0-9]{24}$"},"observedAt":{"type":"string","format":"date-time"},"sourceArchiveSha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"eventType":{"type":"string","enum":["registration_added","registration_removed","registration_record_changed","aircraft_assignment_changed","status_changed","registrant_changed","registrant_pii_withheld","registrant_pii_released"]},"nNumber":{"type":"string","pattern":"^N(?:[1-9][0-9]{0,4}|[1-9][0-9]{0,3}[A-HJ-NP-Z]|[1-9][0-9]{0,2}[A-HJ-NP-Z]{2})$"},"readAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"change":{"$ref":"#/components/schemas/AircraftChangeFeedItem"}}},"AircraftWatchAlertListResponse":{"type":"object","additionalProperties":false,"required":["data","watch","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AircraftWatchAlert"}},"watch":{"type":"object","additionalProperties":false,"required":["watchId","name","nNumbers"],"properties":{"watchId":{"type":"string","pattern":"^aw_[a-f0-9]{24}$"},"name":{"type":"string","minLength":1,"maxLength":80},"nNumbers":{"type":"array","minItems":1,"maxItems":250,"items":{"type":"string","pattern":"^N(?:[1-9][0-9]{0,4}|[1-9][0-9]{0,3}[A-HJ-NP-Z]|[1-9][0-9]{0,2}[A-HJ-NP-Z]{2})$"}}}},"pagination":{"type":"object","additionalProperties":false,"required":["limit","unreadOnly","nextCursor"],"properties":{"limit":{"type":"integer","minimum":1,"maximum":100},"unreadOnly":{"type":"boolean"},"nextCursor":{"type":["string","null"],"maxLength":512}}}}},"AircraftWatchAlertReadInput":{"type":"object","additionalProperties":false,"required":["alertIds"],"properties":{"alertIds":{"type":"array","minItems":1,"maxItems":100,"uniqueItems":true,"items":{"type":"string","pattern":"^aal_[a-f0-9]{24}$"}}}},"AircraftWatchAlertReadResponse":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"type":"object","additionalProperties":false,"required":["marked","readAt"],"properties":{"marked":{"type":"integer","minimum":0,"maximum":100},"readAt":{"type":"string","format":"date-time"}}}}},"AircraftDocumentIndexRecord":{"type":"object","additionalProperties":false,"required":["contractVersion","nNumber","documentId","documentTypeCode","documentTypeLabel","receiptDate","processingDate","correctionDate","correctionKind","source"],"properties":{"contractVersion":{"type":"string","const":"aircraft-document-index-v1"},"nNumber":{"type":"string","pattern":"^N[0-9][0-9A-Z]{0,4}$"},"documentId":{"type":["string","null"],"description":"FAA document-image identifier when the releasable Document Index supplies one; null when FAA leaves the field blank."},"documentTypeCode":{"type":["string","null"],"description":"FAA document type code as supplied. Unknown or blank values are not inferred."},"documentTypeLabel":{"type":["string","null"],"enum":["Evidence of Ownership","Security Conveyance/Lien","Lien Release","Repossession","Evidence of Ownership w/Lien","Disclaimer","Court Documents",null],"description":"Reviewed FAA label for a known document type code, otherwise null."},"receiptDate":{"type":["string","null"],"format":"date"},"processingDate":{"type":["string","null"],"format":"date"},"correctionDate":{"type":["string","null"],"format":"date"},"correctionKind":{"type":["string","null"],"enum":["added","changed",null],"description":"Bounded interpretation of reviewed FAA correction-identification codes. Blank or unreviewed source codes remain null."},"source":{"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}$"}}}}},"AircraftDocumentIndexResponse":{"type":"object","additionalProperties":false,"required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AircraftDocumentIndexRecord"}},"pagination":{"type":"object","additionalProperties":false,"required":["limit","nextCursor"],"properties":{"limit":{"type":"integer","minimum":1,"maximum":50},"nextCursor":{"type":["string","null"],"maxLength":1024}}}}}}},"x-aircraft-api-key-scopes":{"aircraft:read":"Current lookup, lifecycle status, retained history, observed change-feed, and FAA document-index reads.","aircraft:query":"Bounded current-registry discovery and flexible registry query reads.","aircraft:usage":"Read the current Aircraft plan, monthly usage, remaining quota, and effective Aircraft key scopes."}}