Aircraft Intelligence API reference

Grizzly Bulls Aircraft Intelligence API v1.0.0. This page is generated from the same OpenAPI contract linked below.
Contract

Version 1.0.0

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.

Base URL
https://api.grizzlybulls.com/v1
Authentication
Bearer API key
Operations
30
Schemas
66

Start with a live FAA registry request

Create a Free key, or use an existing account key. Free includes 1,000 requests per month with no payment method. The command below searches current FAA registration records where the reported registrant state is California. It does not imply that an aircraft is physically located there.

First request: bounded state lookup

Run this in Bash or zsh after saving your API key in a trusted terminal. Replace the placeholder locally; never put the key in browser code, a URL, or a public repository.

export GRIZZLY_BULLS_API_KEY="your-key"
curl --fail-with-body \
  -H "Authorization: Bearer $GRIZZLY_BULLS_API_KEY" \
  "https://api.grizzlybulls.com/v1/aircraft?state=CA&limit=3"

Swipe the code sideways to see the full request.

GET/aircraft

Search the current aircraft registry with bounded exact filters

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.

Authentication required. Operation ID: searchAircraftRegistry.

Parameters

NameLocationRequiredDetails
manufacturerqueryNo

Exact manufacturer name after trim/case normalization. At least one reviewed discovery filter is required.

{
  "type": "string",
  "minLength": 1,
  "maxLength": 100
}
modelqueryNo

Exact aircraft model after trim/case normalization. At least one reviewed discovery filter is required.

{
  "type": "string",
  "minLength": 1,
  "maxLength": 100
}
statequeryNo

Exact two-letter registrant state code. At least one reviewed discovery filter is required.

{
  "type": "string",
  "pattern": "^[A-Za-z]{2}$",
  "example": "FL"
}
serialNumberqueryNo

Exact aircraft serial number after trim/case normalization. At least one reviewed discovery filter is required.

{
  "type": "string",
  "minLength": 1,
  "maxLength": 100
}
manufactureYearqueryNo

Exact four-digit aircraft manufacture year. At least one reviewed discovery filter is required.

{
  "type": "integer",
  "minimum": 1900,
  "maximum": 2100,
  "example": 2024
}
registrationStatusqueryNo

Exact FAA source registration-status code after trim/case normalization. At least one reviewed discovery filter is required.

{
  "type": "string",
  "minLength": 1,
  "maxLength": 100
}
limitqueryNo

Maximum current aircraft records returned.

{
  "type": "integer",
  "minimum": 1,
  "maximum": 50,
  "default": 25
}
cursorqueryNo

Opaque keyset cursor returned by the previous page. It is valid only with the same normalized discovery filters.

{
  "type": "string",
  "minLength": 1,
  "maxLength": 1024
}

Responses

200Bounded current-registry discovery results. A valid search with no matches returns an empty data array.
Headers
  • X-Aircraft-Plan: Resolved aircraft API plan for the authenticated account.
  • X-Aircraft-Rate-Limit: Maximum requests permitted per minute for the resolved aircraft API plan.
  • X-Aircraft-Quota-Limit: Monthly request quota for the resolved aircraft API plan.
  • X-Aircraft-Quota-Remaining: Monthly requests remaining after the current operation was reserved.
  • X-Aircraft-Quota-Reset: UTC timestamp when the current monthly quota window resets.
{
  "$ref": "#/components/schemas/AircraftDiscoveryResponse"
}
400The aircraft identifier, change-feed window/filter/cursor, discovery filters, cursor, or pagination parameters are invalid.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "invalid_request",
    "message": "At least one reviewed aircraft discovery filter is required."
  }
}
401A valid Grizzly Bulls API key is required.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "unauthenticated",
    "message": "A valid API key is required."
  }
}
403The authenticated API key does not include the Aircraft scope required by this operation.
{
  "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."
  }
}
405The HTTP method is not supported by this endpoint.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "method_not_allowed",
    "message": "Method not allowed."
  }
}
429The short-window request rate or monthly aircraft API quota was exceeded.
Headers
  • X-Aircraft-Plan: Resolved aircraft API plan for the authenticated account.
  • X-Aircraft-Rate-Limit: Maximum requests permitted per minute for the resolved aircraft API plan.
  • X-Aircraft-Quota-Limit: Monthly request quota for the resolved aircraft API plan.
  • X-Aircraft-Quota-Remaining: Monthly requests remaining after the current operation was reserved.
  • X-Aircraft-Quota-Reset: UTC timestamp when the current monthly quota window resets.
  • Retry-After: Seconds until the request may be retried under the limiting policy.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "rate_limited",
    "message": "Aircraft API usage limit exceeded."
  }
}
500The request failed without exposing provider or server internals.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "internal_error",
    "message": "The request could not be completed."
  }
}
503The aircraft read model, authentication authority, entitlement authority, or durable usage meter is temporarily unavailable. Use bounded backoff rather than a tight retry loop.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "service_unavailable",
    "message": "Aircraft data is temporarily unavailable."
  }
}
GET/aircraft/query

Query the current FAA registry with bounded flexible filters

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.

Authentication required. Operation ID: queryAircraftRegistry.

Parameters

NameLocationRequiredDetails
filterqueryYes

Repeatable field:operator:value filter. Repeated filters combine with AND. Use /aircraft/columns to discover supported columns and operators.

{
  "type": "array",
  "minItems": 1,
  "maxItems": 8,
  "items": {
    "type": "string",
    "minLength": 3,
    "maxLength": 1200
  }
}
columnsqueryNo

Comma-separated allowlisted response columns. Defaults to all reviewed AIR15B columns.

{
  "type": "string",
  "example": "nNumber,manufacturer,model,manufactureYear"
}
sortqueryNo

One allowlisted column plus asc/desc. Non-N-number sorts must also be constrained by a filter on that column.

{
  "type": "string",
  "pattern": "^[A-Za-z][A-Za-z0-9]*(?::asc|:desc)$",
  "example": "manufacturer:asc",
  "default": "nNumber:asc"
}
limitqueryNo

Maximum current registry records returned.

{
  "type": "integer",
  "minimum": 1,
  "maximum": 50,
  "default": 25
}
cursorqueryNo

Opaque keyset cursor bound to the normalized filters, selected columns, and sort.

{
  "type": "string",
  "minLength": 1,
  "maxLength": 4096
}

Responses

200Bounded current-registry query results with an optional opaque continuation cursor.
Headers
  • X-Aircraft-Plan: Resolved aircraft API plan for the authenticated account.
  • X-Aircraft-Rate-Limit: Maximum requests permitted per minute for the resolved aircraft API plan.
  • X-Aircraft-Quota-Limit: Monthly request quota for the resolved aircraft API plan.
  • X-Aircraft-Quota-Remaining: Monthly requests remaining after the current operation was reserved.
  • X-Aircraft-Quota-Reset: UTC timestamp when the current monthly quota window resets.
{
  "$ref": "#/components/schemas/AircraftRegistryQueryResponse"
}
400The aircraft identifier, change-feed window/filter/cursor, discovery filters, cursor, or pagination parameters are invalid.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "invalid_request",
    "message": "At least one reviewed aircraft discovery filter is required."
  }
}
401A valid Grizzly Bulls API key is required.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "unauthenticated",
    "message": "A valid API key is required."
  }
}
403The authenticated API key does not include the Aircraft scope required by this operation.
{
  "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."
  }
}
405The HTTP method is not supported by this endpoint.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "method_not_allowed",
    "message": "Method not allowed."
  }
}
429The short-window request rate or monthly aircraft API quota was exceeded.
Headers
  • X-Aircraft-Plan: Resolved aircraft API plan for the authenticated account.
  • X-Aircraft-Rate-Limit: Maximum requests permitted per minute for the resolved aircraft API plan.
  • X-Aircraft-Quota-Limit: Monthly request quota for the resolved aircraft API plan.
  • X-Aircraft-Quota-Remaining: Monthly requests remaining after the current operation was reserved.
  • X-Aircraft-Quota-Reset: UTC timestamp when the current monthly quota window resets.
  • Retry-After: Seconds until the request may be retried under the limiting policy.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "rate_limited",
    "message": "Aircraft API usage limit exceeded."
  }
}
500The request failed without exposing provider or server internals.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "internal_error",
    "message": "The request could not be completed."
  }
}
503The aircraft read model, authentication authority, entitlement authority, or durable usage meter is temporarily unavailable. Use bounded backoff rather than a tight retry loop.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "service_unavailable",
    "message": "Aircraft data is temporarily unavailable."
  }
}
GET/aircraft/columns

List reviewed current-registry query columns and operators

Authenticated metadata for the AIR15B query grammar. This route does not read registry rows or consume registry_search quota.

Authentication required. Operation ID: getAircraftRegistryQueryColumns.

Responses

200Allowlisted query columns, supported operators, sortability, and grammar limits.
{
  "$ref": "#/components/schemas/AircraftRegistryColumnsResponse"
}
401A valid Grizzly Bulls API key is required.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "unauthenticated",
    "message": "A valid API key is required."
  }
}
405The HTTP method is not supported by this endpoint.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "method_not_allowed",
    "message": "Method not allowed."
  }
}
500The request failed without exposing provider or server internals.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "internal_error",
    "message": "The request could not be completed."
  }
}
503The aircraft read model, authentication authority, entitlement authority, or durable usage meter is temporarily unavailable. Use bounded backoff rather than a tight retry loop.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "service_unavailable",
    "message": "Aircraft data is temporarily unavailable."
  }
}
GET/aircraft/changes

Get bounded observed aircraft registry changes

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.

Authentication required. Operation ID: getAircraftObservedChanges.

Parameters

NameLocationRequiredDetails
sincequeryYes

Inclusive Grizzly Bulls observation-time lower bound. Must be an ISO 8601 date-time with an explicit timezone.

{
  "type": "string",
  "format": "date-time"
}
untilqueryNo

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.

{
  "type": "string",
  "format": "date-time"
}
eventTypequeryNo

Optional exact reviewed history-event type.

{
  "type": "string",
  "enum": [
    "registration_added",
    "registration_removed",
    "registration_record_changed",
    "aircraft_assignment_changed",
    "status_changed",
    "registrant_changed",
    "registrant_pii_withheld",
    "registrant_pii_released"
  ]
}
limitqueryNo

Maximum observed change events returned.

{
  "type": "integer",
  "minimum": 1,
  "maximum": 50,
  "default": 25
}
cursorqueryNo

Opaque keyset cursor returned by the previous page. It is bound to the same since/until/eventType window.

{
  "type": "string",
  "minLength": 1,
  "maxLength": 2048
}

Responses

200Bounded observed change events. A valid window with no events returns an empty data array.
Headers
  • X-Aircraft-Plan: Resolved aircraft API plan for the authenticated account.
  • X-Aircraft-Rate-Limit: Maximum requests permitted per minute for the resolved aircraft API plan.
  • X-Aircraft-Quota-Limit: Monthly request quota for the resolved aircraft API plan.
  • X-Aircraft-Quota-Remaining: Monthly requests remaining after the current operation was reserved.
  • X-Aircraft-Quota-Reset: UTC timestamp when the current monthly quota window resets.
{
  "$ref": "#/components/schemas/AircraftChangeFeedResponse"
}
400The aircraft identifier, change-feed window/filter/cursor, discovery filters, cursor, or pagination parameters are invalid.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "invalid_request",
    "message": "At least one reviewed aircraft discovery filter is required."
  }
}
401A valid Grizzly Bulls API key is required.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "unauthenticated",
    "message": "A valid API key is required."
  }
}
403The authenticated API key does not include the Aircraft scope required by this operation.
{
  "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."
  }
}
405The HTTP method is not supported by this endpoint.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "method_not_allowed",
    "message": "Method not allowed."
  }
}
429The short-window request rate or monthly aircraft API quota was exceeded.
Headers
  • X-Aircraft-Plan: Resolved aircraft API plan for the authenticated account.
  • X-Aircraft-Rate-Limit: Maximum requests permitted per minute for the resolved aircraft API plan.
  • X-Aircraft-Quota-Limit: Monthly request quota for the resolved aircraft API plan.
  • X-Aircraft-Quota-Remaining: Monthly requests remaining after the current operation was reserved.
  • X-Aircraft-Quota-Reset: UTC timestamp when the current monthly quota window resets.
  • Retry-After: Seconds until the request may be retried under the limiting policy.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "rate_limited",
    "message": "Aircraft API usage limit exceeded."
  }
}
500The request failed without exposing provider or server internals.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "internal_error",
    "message": "The request could not be completed."
  }
}
503The aircraft read model, authentication authority, entitlement authority, or durable usage meter is temporarily unavailable. Use bounded backoff rather than a tight retry loop.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "service_unavailable",
    "message": "Aircraft data is temporarily unavailable."
  }
}
GET/aircraft/reports

List saved Aircraft report definitions

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.

Authentication required. Operation ID: listAircraftSavedReports.

Responses

200Saved report definitions and the current plan limit.
Headers
  • X-Aircraft-Plan: Resolved Aircraft API plan for the authenticated account.
  • X-Aircraft-Saved-Report-Limit: Maximum saved Aircraft report definitions permitted by the current plan.
  • X-Aircraft-Monthly-Export-Run-Limit: Maximum asynchronous export runs per UTC calendar month.
  • X-Aircraft-Export-Row-Limit: Maximum rows permitted in one completed export.
  • X-Aircraft-Export-Retention-Hours: Hours a completed export remains downloadable.
{
  "$ref": "#/components/schemas/AircraftSavedReportListResponse"
}
401A valid Grizzly Bulls API key is required.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "unauthenticated",
    "message": "A valid API key is required."
  }
}
405The HTTP method is not supported by this endpoint.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "method_not_allowed",
    "message": "Method not allowed."
  }
}
500The request failed without exposing provider or server internals.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "internal_error",
    "message": "The request could not be completed."
  }
}
503The aircraft read model, authentication authority, entitlement authority, or durable usage meter is temporarily unavailable. Use bounded backoff rather than a tight retry loop.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "service_unavailable",
    "message": "Aircraft data is temporarily unavailable."
  }
}
POST/aircraft/reports

Create a paid saved Aircraft report definition

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.

Authentication required. Operation ID: createAircraftSavedReport.

Request body

{
  "$ref": "#/components/schemas/AircraftSavedReportInput"
}

Responses

201Saved report created.
Headers
  • X-Aircraft-Plan: Resolved Aircraft API plan for the authenticated account.
  • X-Aircraft-Saved-Report-Limit: Maximum saved Aircraft report definitions permitted by the current plan.
  • X-Aircraft-Monthly-Export-Run-Limit: Maximum asynchronous export runs per UTC calendar month.
  • X-Aircraft-Export-Row-Limit: Maximum rows permitted in one completed export.
  • X-Aircraft-Export-Retention-Hours: Hours a completed export remains downloadable.
{
  "$ref": "#/components/schemas/AircraftSavedReportResponse"
}
400The aircraft identifier, change-feed window/filter/cursor, discovery filters, cursor, or pagination parameters are invalid.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "invalid_request",
    "message": "At least one reviewed aircraft discovery filter is required."
  }
}
401A valid Grizzly Bulls API key is required.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "unauthenticated",
    "message": "A valid API key is required."
  }
}
403The current Aircraft API plan does not include the requested paid Aircraft capability.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "not_entitled",
    "message": "This Aircraft capability requires a Developer or Business plan."
  }
}
405The HTTP method is not supported by this endpoint.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "method_not_allowed",
    "message": "Method not allowed."
  }
}
409The saved-report mutation conflicts with an existing name or the current plan saved-report ceiling.
Headers
  • X-Aircraft-Plan: Resolved Aircraft API plan for the authenticated account.
  • X-Aircraft-Saved-Report-Limit: Maximum saved Aircraft report definitions permitted by the current plan.
  • X-Aircraft-Monthly-Export-Run-Limit: Maximum asynchronous export runs per UTC calendar month.
  • X-Aircraft-Export-Row-Limit: Maximum rows permitted in one completed export.
  • X-Aircraft-Export-Retention-Hours: Hours a completed export remains downloadable.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "conflict",
    "message": "A saved report with that name already exists."
  }
}
500The request failed without exposing provider or server internals.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "internal_error",
    "message": "The request could not be completed."
  }
}
503The aircraft read model, authentication authority, entitlement authority, or durable usage meter is temporarily unavailable. Use bounded backoff rather than a tight retry loop.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "service_unavailable",
    "message": "Aircraft data is temporarily unavailable."
  }
}
PUT/aircraft/reports/{reportId}

Replace a paid saved Aircraft report definition

Authentication required. Operation ID: updateAircraftSavedReport.

Parameters

NameLocationRequiredDetails
reportIdpathYes

Aircraft saved report identifier.

{
  "type": "string",
  "pattern": "^arp_[a-f0-9]{24}$"
}

Request body

{
  "$ref": "#/components/schemas/AircraftSavedReportInput"
}

Responses

200Saved report replaced.
Headers
  • X-Aircraft-Plan: Resolved Aircraft API plan for the authenticated account.
  • X-Aircraft-Saved-Report-Limit: Maximum saved Aircraft report definitions permitted by the current plan.
  • X-Aircraft-Monthly-Export-Run-Limit: Maximum asynchronous export runs per UTC calendar month.
  • X-Aircraft-Export-Row-Limit: Maximum rows permitted in one completed export.
  • X-Aircraft-Export-Retention-Hours: Hours a completed export remains downloadable.
{
  "$ref": "#/components/schemas/AircraftSavedReportResponse"
}
400The aircraft identifier, change-feed window/filter/cursor, discovery filters, cursor, or pagination parameters are invalid.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "invalid_request",
    "message": "At least one reviewed aircraft discovery filter is required."
  }
}
401A valid Grizzly Bulls API key is required.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "unauthenticated",
    "message": "A valid API key is required."
  }
}
403The current Aircraft API plan does not include the requested paid Aircraft capability.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "not_entitled",
    "message": "This Aircraft capability requires a Developer or Business plan."
  }
}
404No matching current or retained registration was found.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "not_found",
    "message": "No current aircraft registration was found for that N-number."
  }
}
405The HTTP method is not supported by this endpoint.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "method_not_allowed",
    "message": "Method not allowed."
  }
}
409The requested Aircraft control-plane mutation conflicts with retained state or a plan-owned limit.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "conflict",
    "message": "An equivalent Aircraft webhook watch already exists."
  }
}
500The request failed without exposing provider or server internals.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "internal_error",
    "message": "The request could not be completed."
  }
}
503The aircraft read model, authentication authority, entitlement authority, or durable usage meter is temporarily unavailable. Use bounded backoff rather than a tight retry loop.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "service_unavailable",
    "message": "Aircraft data is temporarily unavailable."
  }
}
DELETE/aircraft/reports/{reportId}

Delete a saved Aircraft report definition

Deletes an owned definition. Existing export runs retain the immutable definition captured when they were queued.

Authentication required. Operation ID: deleteAircraftSavedReport.

Parameters

NameLocationRequiredDetails
reportIdpathYes

Aircraft saved report identifier.

{
  "type": "string",
  "pattern": "^arp_[a-f0-9]{24}$"
}

Responses

204Saved report deleted.
400The aircraft identifier, change-feed window/filter/cursor, discovery filters, cursor, or pagination parameters are invalid.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "invalid_request",
    "message": "At least one reviewed aircraft discovery filter is required."
  }
}
401A valid Grizzly Bulls API key is required.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "unauthenticated",
    "message": "A valid API key is required."
  }
}
404No matching current or retained registration was found.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "not_found",
    "message": "No current aircraft registration was found for that N-number."
  }
}
405The HTTP method is not supported by this endpoint.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "method_not_allowed",
    "message": "Method not allowed."
  }
}
500The request failed without exposing provider or server internals.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "internal_error",
    "message": "The request could not be completed."
  }
}
503The aircraft read model, authentication authority, entitlement authority, or durable usage meter is temporarily unavailable. Use bounded backoff rather than a tight retry loop.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "service_unavailable",
    "message": "Aircraft data is temporarily unavailable."
  }
}
GET/aircraft/exports

List recent asynchronous Aircraft exports

Authentication required. Operation ID: listAircraftExports.

Parameters

NameLocationRequiredDetails
limitqueryNo

Maximum recent export runs returned.

{
  "type": "integer",
  "minimum": 1,
  "maximum": 50,
  "default": 20
}

Responses

200Recent export-run status for the authenticated account.
Headers
  • X-Aircraft-Plan: Resolved Aircraft API plan for the authenticated account.
  • X-Aircraft-Saved-Report-Limit: Maximum saved Aircraft report definitions permitted by the current plan.
  • X-Aircraft-Monthly-Export-Run-Limit: Maximum asynchronous export runs per UTC calendar month.
  • X-Aircraft-Export-Row-Limit: Maximum rows permitted in one completed export.
  • X-Aircraft-Export-Retention-Hours: Hours a completed export remains downloadable.
{
  "$ref": "#/components/schemas/AircraftExportRunListResponse"
}
400The aircraft identifier, change-feed window/filter/cursor, discovery filters, cursor, or pagination parameters are invalid.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "invalid_request",
    "message": "At least one reviewed aircraft discovery filter is required."
  }
}
401A valid Grizzly Bulls API key is required.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "unauthenticated",
    "message": "A valid API key is required."
  }
}
405The HTTP method is not supported by this endpoint.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "method_not_allowed",
    "message": "Method not allowed."
  }
}
500The request failed without exposing provider or server internals.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "internal_error",
    "message": "The request could not be completed."
  }
}
503The aircraft read model, authentication authority, entitlement authority, or durable usage meter is temporarily unavailable. Use bounded backoff rather than a tight retry loop.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "service_unavailable",
    "message": "Aircraft data is temporarily unavailable."
  }
}
POST/aircraft/exports

Queue a paid asynchronous Aircraft export

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.

Authentication required. Operation ID: createAircraftExport.

Request body

{
  "$ref": "#/components/schemas/AircraftExportCreateInput"
}

Responses

202Export queued for asynchronous generation.
Headers
  • X-Aircraft-Plan: Resolved Aircraft API plan for the authenticated account.
  • X-Aircraft-Saved-Report-Limit: Maximum saved Aircraft report definitions permitted by the current plan.
  • X-Aircraft-Monthly-Export-Run-Limit: Maximum asynchronous export runs per UTC calendar month.
  • X-Aircraft-Export-Row-Limit: Maximum rows permitted in one completed export.
  • X-Aircraft-Export-Retention-Hours: Hours a completed export remains downloadable.
{
  "$ref": "#/components/schemas/AircraftExportCreateResponse"
}
400The aircraft identifier, change-feed window/filter/cursor, discovery filters, cursor, or pagination parameters are invalid.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "invalid_request",
    "message": "At least one reviewed aircraft discovery filter is required."
  }
}
401A valid Grizzly Bulls API key is required.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "unauthenticated",
    "message": "A valid API key is required."
  }
}
403The current Aircraft API plan does not include the requested paid Aircraft capability.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "not_entitled",
    "message": "This Aircraft capability requires a Developer or Business plan."
  }
}
404No matching current or retained registration was found.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "not_found",
    "message": "No current aircraft registration was found for that N-number."
  }
}
405The HTTP method is not supported by this endpoint.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "method_not_allowed",
    "message": "Method not allowed."
  }
}
429The monthly asynchronous Aircraft export-run allowance for the current plan is exhausted.
Headers
  • X-Aircraft-Plan: Resolved Aircraft API plan for the authenticated account.
  • X-Aircraft-Saved-Report-Limit: Maximum saved Aircraft report definitions permitted by the current plan.
  • X-Aircraft-Monthly-Export-Run-Limit: Maximum asynchronous export runs per UTC calendar month.
  • X-Aircraft-Export-Row-Limit: Maximum rows permitted in one completed export.
  • X-Aircraft-Export-Retention-Hours: Hours a completed export remains downloadable.
  • Retry-After: Seconds until the next UTC calendar-month export allowance begins.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "limit_reached",
    "message": "Monthly Aircraft export run limit reached for this plan."
  }
}
500The request failed without exposing provider or server internals.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "internal_error",
    "message": "The request could not be completed."
  }
}
503The aircraft read model, authentication authority, entitlement authority, or durable usage meter is temporarily unavailable. Use bounded backoff rather than a tight retry loop.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "service_unavailable",
    "message": "Aircraft data is temporarily unavailable."
  }
}
GET/aircraft/exports/{exportId}

Get one asynchronous Aircraft export status

Authentication required. Operation ID: getAircraftExport.

Parameters

NameLocationRequiredDetails
exportIdpathYes

Aircraft export run identifier.

{
  "type": "string",
  "pattern": "^aex_[a-f0-9]{24}$"
}

Responses

200Current export-run status.
Headers
  • X-Aircraft-Plan: Resolved Aircraft API plan for the authenticated account.
  • X-Aircraft-Saved-Report-Limit: Maximum saved Aircraft report definitions permitted by the current plan.
  • X-Aircraft-Monthly-Export-Run-Limit: Maximum asynchronous export runs per UTC calendar month.
  • X-Aircraft-Export-Row-Limit: Maximum rows permitted in one completed export.
  • X-Aircraft-Export-Retention-Hours: Hours a completed export remains downloadable.
{
  "$ref": "#/components/schemas/AircraftExportRunResponse"
}
400The aircraft identifier, change-feed window/filter/cursor, discovery filters, cursor, or pagination parameters are invalid.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "invalid_request",
    "message": "At least one reviewed aircraft discovery filter is required."
  }
}
401A valid Grizzly Bulls API key is required.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "unauthenticated",
    "message": "A valid API key is required."
  }
}
404No matching current or retained registration was found.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "not_found",
    "message": "No current aircraft registration was found for that N-number."
  }
}
405The HTTP method is not supported by this endpoint.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "method_not_allowed",
    "message": "Method not allowed."
  }
}
500The request failed without exposing provider or server internals.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "internal_error",
    "message": "The request could not be completed."
  }
}
503The aircraft read model, authentication authority, entitlement authority, or durable usage meter is temporarily unavailable. Use bounded backoff rather than a tight retry loop.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "service_unavailable",
    "message": "Aircraft data is temporarily unavailable."
  }
}
GET/aircraft/exports/{exportId}/download

Download one completed retained Aircraft export

Downloads a completed file only after its byte length and retained SHA-256 evidence match. Completed files expire after the plan retention window.

Authentication required. Operation ID: downloadAircraftExport.

Parameters

NameLocationRequiredDetails
exportIdpathYes

Aircraft export run identifier.

{
  "type": "string",
  "pattern": "^aex_[a-f0-9]{24}$"
}

Responses

200Completed CSV, JSON, or XLSX export.
Headers
  • X-Aircraft-Plan: Resolved Aircraft API plan for the authenticated account.
  • X-Aircraft-Saved-Report-Limit: Maximum saved Aircraft report definitions permitted by the current plan.
  • X-Aircraft-Monthly-Export-Run-Limit: Maximum asynchronous export runs per UTC calendar month.
  • X-Aircraft-Export-Row-Limit: Maximum rows permitted in one completed export.
  • X-Aircraft-Export-Retention-Hours: Hours a completed export remains downloadable.
{
  "type": "string",
  "format": "binary"
}
400The aircraft identifier, change-feed window/filter/cursor, discovery filters, cursor, or pagination parameters are invalid.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "invalid_request",
    "message": "At least one reviewed aircraft discovery filter is required."
  }
}
401A valid Grizzly Bulls API key is required.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "unauthenticated",
    "message": "A valid API key is required."
  }
}
404No matching current or retained registration was found.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "not_found",
    "message": "No current aircraft registration was found for that N-number."
  }
}
405The HTTP method is not supported by this endpoint.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "method_not_allowed",
    "message": "Method not allowed."
  }
}
409The requested asynchronous Aircraft export is not yet completed.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "not_ready",
    "message": "Aircraft export is not ready for download."
  }
}
410The requested retained export has expired.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "expired",
    "message": "Aircraft export has expired."
  }
}
500The request failed without exposing provider or server internals.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "internal_error",
    "message": "The request could not be completed."
  }
}
503The aircraft read model, authentication authority, entitlement authority, or durable usage meter is temporarily unavailable. Use bounded backoff rather than a tight retry loop.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "service_unavailable",
    "message": "Aircraft data is temporarily unavailable."
  }
}
GET/aircraft/watches

List configured Aircraft webhook watches

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.

Authentication required. Operation ID: listAircraftWebhookWatches.

Responses

200Configured webhook watches and the current plan watch limit.
Headers
  • X-Aircraft-Plan: Resolved Aircraft API plan for the authenticated account.
  • X-Aircraft-Webhook-Watch-Limit: Maximum configured Aircraft webhook watches permitted by the current plan.
{
  "$ref": "#/components/schemas/AircraftWebhookWatchListResponse"
}
401A valid Grizzly Bulls API key is required.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "unauthenticated",
    "message": "A valid API key is required."
  }
}
405The HTTP method is not supported by this endpoint.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "method_not_allowed",
    "message": "Method not allowed."
  }
}
500The request failed without exposing provider or server internals.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "internal_error",
    "message": "The request could not be completed."
  }
}
503The aircraft read model, authentication authority, entitlement authority, or durable usage meter is temporarily unavailable. Use bounded backoff rather than a tight retry loop.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "service_unavailable",
    "message": "Aircraft data is temporarily unavailable."
  }
}
POST/aircraft/watches

Create a paid N-number webhook watch

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.

Authentication required. Operation ID: createAircraftWebhookWatch.

Request body

{
  "$ref": "#/components/schemas/AircraftWebhookWatchCreateInput"
}

Responses

201Webhook watch created. Store the returned signingSecret securely; it is not returned by later reads.
Headers
  • X-Aircraft-Plan: Resolved Aircraft API plan for the authenticated account.
  • X-Aircraft-Webhook-Watch-Limit: Maximum configured Aircraft webhook watches permitted by the current plan.
{
  "$ref": "#/components/schemas/AircraftWebhookWatchCreateResponse"
}
400The aircraft identifier, change-feed window/filter/cursor, discovery filters, cursor, or pagination parameters are invalid.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "invalid_request",
    "message": "At least one reviewed aircraft discovery filter is required."
  }
}
401A valid Grizzly Bulls API key is required.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "unauthenticated",
    "message": "A valid API key is required."
  }
}
403The current Aircraft API plan does not include the requested paid Aircraft capability.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "not_entitled",
    "message": "This Aircraft capability requires a Developer or Business plan."
  }
}
405The HTTP method is not supported by this endpoint.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "method_not_allowed",
    "message": "Method not allowed."
  }
}
409The requested Aircraft control-plane mutation conflicts with retained state or a plan-owned limit.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "conflict",
    "message": "An equivalent Aircraft webhook watch already exists."
  }
}
500The request failed without exposing provider or server internals.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "internal_error",
    "message": "The request could not be completed."
  }
}
503The aircraft read model, authentication authority, entitlement authority, or durable usage meter is temporarily unavailable. Use bounded backoff rather than a tight retry loop.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "service_unavailable",
    "message": "Aircraft data is temporarily unavailable."
  }
}
DELETE/aircraft/watches/{watchId}

Delete an Aircraft webhook watch

Deletes an owned watch and its retained delivery troubleshooting records. This remains available after a paid-plan downgrade.

Authentication required. Operation ID: deleteAircraftWebhookWatch.

Parameters

NameLocationRequiredDetails
watchIdpathYes

Aircraft webhook watch identifier.

{
  "type": "string",
  "pattern": "^aw_[a-f0-9]{24}$"
}

Responses

204Webhook watch deleted.
400The aircraft identifier, change-feed window/filter/cursor, discovery filters, cursor, or pagination parameters are invalid.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "invalid_request",
    "message": "At least one reviewed aircraft discovery filter is required."
  }
}
401A valid Grizzly Bulls API key is required.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "unauthenticated",
    "message": "A valid API key is required."
  }
}
404No matching current or retained registration was found.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "not_found",
    "message": "No current aircraft registration was found for that N-number."
  }
}
405The HTTP method is not supported by this endpoint.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "method_not_allowed",
    "message": "Method not allowed."
  }
}
500The request failed without exposing provider or server internals.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "internal_error",
    "message": "The request could not be completed."
  }
}
503The aircraft read model, authentication authority, entitlement authority, or durable usage meter is temporarily unavailable. Use bounded backoff rather than a tight retry loop.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "service_unavailable",
    "message": "Aircraft data is temporarily unavailable."
  }
}
POST/aircraft/watches/{watchId}/test

Queue a synthetic signed webhook test

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.

Authentication required. Operation ID: queueAircraftWebhookTest.

Parameters

NameLocationRequiredDetails
watchIdpathYes

Aircraft webhook watch identifier.

{
  "type": "string",
  "pattern": "^aw_[a-f0-9]{24}$"
}

Responses

202Synthetic test delivery queued.
Headers
  • X-Aircraft-Plan: Resolved Aircraft API plan for the authenticated account.
  • X-Aircraft-Webhook-Watch-Limit: Maximum configured Aircraft webhook watches permitted by the current plan.
{
  "$ref": "#/components/schemas/AircraftWebhookTestResponse"
}
400The aircraft identifier, change-feed window/filter/cursor, discovery filters, cursor, or pagination parameters are invalid.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "invalid_request",
    "message": "At least one reviewed aircraft discovery filter is required."
  }
}
401A valid Grizzly Bulls API key is required.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "unauthenticated",
    "message": "A valid API key is required."
  }
}
403The current Aircraft API plan does not include the requested paid Aircraft capability.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "not_entitled",
    "message": "This Aircraft capability requires a Developer or Business plan."
  }
}
404No matching current or retained registration was found.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "not_found",
    "message": "No current aircraft registration was found for that N-number."
  }
}
405The HTTP method is not supported by this endpoint.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "method_not_allowed",
    "message": "Method not allowed."
  }
}
429The short-window request rate or monthly aircraft API quota was exceeded.
Headers
  • X-Aircraft-Plan: Resolved aircraft API plan for the authenticated account.
  • X-Aircraft-Rate-Limit: Maximum requests permitted per minute for the resolved aircraft API plan.
  • X-Aircraft-Quota-Limit: Monthly request quota for the resolved aircraft API plan.
  • X-Aircraft-Quota-Remaining: Monthly requests remaining after the current operation was reserved.
  • X-Aircraft-Quota-Reset: UTC timestamp when the current monthly quota window resets.
  • Retry-After: Seconds until the request may be retried under the limiting policy.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "rate_limited",
    "message": "Aircraft API usage limit exceeded."
  }
}
500The request failed without exposing provider or server internals.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "internal_error",
    "message": "The request could not be completed."
  }
}
503The aircraft read model, authentication authority, entitlement authority, or durable usage meter is temporarily unavailable. Use bounded backoff rather than a tight retry loop.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "service_unavailable",
    "message": "Aircraft data is temporarily unavailable."
  }
}
GET/aircraft/watches/{watchId}/deliveries

List recent webhook delivery attempts

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.

Authentication required. Operation ID: listAircraftWebhookDeliveries.

Parameters

NameLocationRequiredDetails
watchIdpathYes

Aircraft webhook watch identifier.

{
  "type": "string",
  "pattern": "^aw_[a-f0-9]{24}$"
}
limitqueryNo

Maximum recent webhook deliveries returned for troubleshooting.

{
  "type": "integer",
  "minimum": 1,
  "maximum": 20,
  "default": 10
}

Responses

200Recent webhook deliveries for troubleshooting.
Headers
  • X-Aircraft-Plan: Resolved Aircraft API plan for the authenticated account.
  • X-Aircraft-Webhook-Watch-Limit: Maximum configured Aircraft webhook watches permitted by the current plan.
{
  "$ref": "#/components/schemas/AircraftWebhookDeliveryListResponse"
}
400The aircraft identifier, change-feed window/filter/cursor, discovery filters, cursor, or pagination parameters are invalid.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "invalid_request",
    "message": "At least one reviewed aircraft discovery filter is required."
  }
}
401A valid Grizzly Bulls API key is required.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "unauthenticated",
    "message": "A valid API key is required."
  }
}
404No matching current or retained registration was found.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "not_found",
    "message": "No current aircraft registration was found for that N-number."
  }
}
405The HTTP method is not supported by this endpoint.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "method_not_allowed",
    "message": "Method not allowed."
  }
}
500The request failed without exposing provider or server internals.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "internal_error",
    "message": "The request could not be completed."
  }
}
503The aircraft read model, authentication authority, entitlement authority, or durable usage meter is temporarily unavailable. Use bounded backoff rather than a tight retry loop.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "service_unavailable",
    "message": "Aircraft data is temporarily unavailable."
  }
}
GET/aircraft/n-number/{nNumber}/status

Resolve reviewed FAA lifecycle status for an N-number

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.

Authentication required. Operation ID: getAircraftNNumberStatus.

Parameters

NameLocationRequiredDetails
nNumberpathYes

U.S. aircraft N-number. Matching is case-insensitive and an optional N- hyphen is normalized.

{
  "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

200Reviewed lifecycle status. unknown is a successful evidence-backed absence result, not an availability determination.
Headers
  • X-Aircraft-Plan: Resolved aircraft API plan for the authenticated account.
  • X-Aircraft-Rate-Limit: Maximum requests permitted per minute for the resolved aircraft API plan.
  • X-Aircraft-Quota-Limit: Monthly request quota for the resolved aircraft API plan.
  • X-Aircraft-Quota-Remaining: Monthly requests remaining after the current operation was reserved.
  • X-Aircraft-Quota-Reset: UTC timestamp when the current monthly quota window resets.
{
  "$ref": "#/components/schemas/AircraftNNumberStatusResponse"
}
400The aircraft identifier, change-feed window/filter/cursor, discovery filters, cursor, or pagination parameters are invalid.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "invalid_request",
    "message": "At least one reviewed aircraft discovery filter is required."
  }
}
401A valid Grizzly Bulls API key is required.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "unauthenticated",
    "message": "A valid API key is required."
  }
}
403The authenticated API key does not include the Aircraft scope required by this operation.
{
  "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."
  }
}
405The HTTP method is not supported by this endpoint.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "method_not_allowed",
    "message": "Method not allowed."
  }
}
429The short-window request rate or monthly aircraft API quota was exceeded.
Headers
  • X-Aircraft-Plan: Resolved aircraft API plan for the authenticated account.
  • X-Aircraft-Rate-Limit: Maximum requests permitted per minute for the resolved aircraft API plan.
  • X-Aircraft-Quota-Limit: Monthly request quota for the resolved aircraft API plan.
  • X-Aircraft-Quota-Remaining: Monthly requests remaining after the current operation was reserved.
  • X-Aircraft-Quota-Reset: UTC timestamp when the current monthly quota window resets.
  • Retry-After: Seconds until the request may be retried under the limiting policy.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "rate_limited",
    "message": "Aircraft API usage limit exceeded."
  }
}
500The request failed without exposing provider or server internals.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "internal_error",
    "message": "The request could not be completed."
  }
}
503The aircraft read model, authentication authority, entitlement authority, or durable usage meter is temporarily unavailable. Use bounded backoff rather than a tight retry loop.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "service_unavailable",
    "message": "Aircraft data is temporarily unavailable."
  }
}
GET/aircraft/{nNumber}

Get the current aircraft registration for an N-number

Authentication required. Operation ID: getAircraftByNNumber.

Parameters

NameLocationRequiredDetails
nNumberpathYes

U.S. aircraft N-number. Matching is case-insensitive and an optional N- hyphen is normalized.

{
  "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

200Current aircraft registration.
Headers
  • X-Aircraft-Plan: Resolved aircraft API plan for the authenticated account.
  • X-Aircraft-Rate-Limit: Maximum requests permitted per minute for the resolved aircraft API plan.
  • X-Aircraft-Quota-Limit: Monthly request quota for the resolved aircraft API plan.
  • X-Aircraft-Quota-Remaining: Monthly requests remaining after the current operation was reserved.
  • X-Aircraft-Quota-Reset: UTC timestamp when the current monthly quota window resets.
{
  "$ref": "#/components/schemas/AircraftCurrentResponse"
}
400The aircraft identifier, change-feed window/filter/cursor, discovery filters, cursor, or pagination parameters are invalid.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "invalid_request",
    "message": "At least one reviewed aircraft discovery filter is required."
  }
}
401A valid Grizzly Bulls API key is required.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "unauthenticated",
    "message": "A valid API key is required."
  }
}
403The authenticated API key does not include the Aircraft scope required by this operation.
{
  "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."
  }
}
404No matching current or retained registration was found.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "not_found",
    "message": "No current aircraft registration was found for that N-number."
  }
}
405The HTTP method is not supported by this endpoint.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "method_not_allowed",
    "message": "Method not allowed."
  }
}
429The short-window request rate or monthly aircraft API quota was exceeded.
Headers
  • X-Aircraft-Plan: Resolved aircraft API plan for the authenticated account.
  • X-Aircraft-Rate-Limit: Maximum requests permitted per minute for the resolved aircraft API plan.
  • X-Aircraft-Quota-Limit: Monthly request quota for the resolved aircraft API plan.
  • X-Aircraft-Quota-Remaining: Monthly requests remaining after the current operation was reserved.
  • X-Aircraft-Quota-Reset: UTC timestamp when the current monthly quota window resets.
  • Retry-After: Seconds until the request may be retried under the limiting policy.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "rate_limited",
    "message": "Aircraft API usage limit exceeded."
  }
}
500The request failed without exposing provider or server internals.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "internal_error",
    "message": "The request could not be completed."
  }
}
503The aircraft read model, authentication authority, entitlement authority, or durable usage meter is temporarily unavailable. Use bounded backoff rather than a tight retry loop.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "service_unavailable",
    "message": "Aircraft data is temporarily unavailable."
  }
}
GET/aircraft/icao24/{hex}

Get the current aircraft registration for an ICAO24 / Mode-S code

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.

Authentication required. Operation ID: getAircraftByIcao24.

Parameters

NameLocationRequiredDetails
hexpathYes

Six-hex-digit ICAO24 / Mode-S aircraft address. Matching is case-insensitive and normalized to uppercase.

{
  "type": "string",
  "pattern": "^[0-9A-F]{6}$",
  "example": "A00001"
}

Responses

200Current aircraft registration using the same response contract as N-number lookup.
Headers
  • X-Aircraft-Plan: Resolved aircraft API plan for the authenticated account.
  • X-Aircraft-Rate-Limit: Maximum requests permitted per minute for the resolved aircraft API plan.
  • X-Aircraft-Quota-Limit: Monthly request quota for the resolved aircraft API plan.
  • X-Aircraft-Quota-Remaining: Monthly requests remaining after the current operation was reserved.
  • X-Aircraft-Quota-Reset: UTC timestamp when the current monthly quota window resets.
{
  "$ref": "#/components/schemas/AircraftCurrentResponse"
}
400The aircraft identifier, change-feed window/filter/cursor, discovery filters, cursor, or pagination parameters are invalid.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "invalid_request",
    "message": "At least one reviewed aircraft discovery filter is required."
  }
}
401A valid Grizzly Bulls API key is required.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "unauthenticated",
    "message": "A valid API key is required."
  }
}
403The authenticated API key does not include the Aircraft scope required by this operation.
{
  "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."
  }
}
404No matching current or retained registration was found.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "not_found",
    "message": "No current aircraft registration was found for that N-number."
  }
}
405The HTTP method is not supported by this endpoint.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "method_not_allowed",
    "message": "Method not allowed."
  }
}
429The short-window request rate or monthly aircraft API quota was exceeded.
Headers
  • X-Aircraft-Plan: Resolved aircraft API plan for the authenticated account.
  • X-Aircraft-Rate-Limit: Maximum requests permitted per minute for the resolved aircraft API plan.
  • X-Aircraft-Quota-Limit: Monthly request quota for the resolved aircraft API plan.
  • X-Aircraft-Quota-Remaining: Monthly requests remaining after the current operation was reserved.
  • X-Aircraft-Quota-Reset: UTC timestamp when the current monthly quota window resets.
  • Retry-After: Seconds until the request may be retried under the limiting policy.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "rate_limited",
    "message": "Aircraft API usage limit exceeded."
  }
}
500The request failed without exposing provider or server internals.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "internal_error",
    "message": "The request could not be completed."
  }
}
503The aircraft read model, authentication authority, entitlement authority, or durable usage meter is temporarily unavailable. Use bounded backoff rather than a tight retry loop.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "service_unavailable",
    "message": "Aircraft data is temporarily unavailable."
  }
}
GET/aircraft/{nNumber}/history

Get compact retained registration history and change events for an N-number

Authentication required. Operation ID: getAircraftHistoryByNNumber.

Parameters

NameLocationRequiredDetails
nNumberpathYes

U.S. aircraft N-number. Matching is case-insensitive and an optional N- hyphen is normalized.

{
  "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"
}
versionsLimitqueryNo

Maximum historical versions returned.

{
  "type": "integer",
  "minimum": 1,
  "maximum": 100,
  "default": 50
}
versionsOffsetqueryNo

Historical-version offset.

{
  "type": "integer",
  "minimum": 0,
  "maximum": 10000,
  "default": 0
}
eventsLimitqueryNo

Maximum change events returned.

{
  "type": "integer",
  "minimum": 1,
  "maximum": 100,
  "default": 50
}
eventsOffsetqueryNo

Change-event offset.

{
  "type": "integer",
  "minimum": 0,
  "maximum": 10000,
  "default": 0
}

Responses

200Retained history and PII-free change events.
Headers
  • X-Aircraft-Plan: Resolved aircraft API plan for the authenticated account.
  • X-Aircraft-Rate-Limit: Maximum requests permitted per minute for the resolved aircraft API plan.
  • X-Aircraft-Quota-Limit: Monthly request quota for the resolved aircraft API plan.
  • X-Aircraft-Quota-Remaining: Monthly requests remaining after the current operation was reserved.
  • X-Aircraft-Quota-Reset: UTC timestamp when the current monthly quota window resets.
{
  "$ref": "#/components/schemas/AircraftHistoryResponse"
}
400The aircraft identifier, change-feed window/filter/cursor, discovery filters, cursor, or pagination parameters are invalid.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "invalid_request",
    "message": "At least one reviewed aircraft discovery filter is required."
  }
}
401A valid Grizzly Bulls API key is required.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "unauthenticated",
    "message": "A valid API key is required."
  }
}
403The authenticated API key does not include the Aircraft scope required by this operation.
{
  "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."
  }
}
404No matching current or retained registration was found.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "not_found",
    "message": "No current aircraft registration was found for that N-number."
  }
}
405The HTTP method is not supported by this endpoint.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "method_not_allowed",
    "message": "Method not allowed."
  }
}
429The short-window request rate or monthly aircraft API quota was exceeded.
Headers
  • X-Aircraft-Plan: Resolved aircraft API plan for the authenticated account.
  • X-Aircraft-Rate-Limit: Maximum requests permitted per minute for the resolved aircraft API plan.
  • X-Aircraft-Quota-Limit: Monthly request quota for the resolved aircraft API plan.
  • X-Aircraft-Quota-Remaining: Monthly requests remaining after the current operation was reserved.
  • X-Aircraft-Quota-Reset: UTC timestamp when the current monthly quota window resets.
  • Retry-After: Seconds until the request may be retried under the limiting policy.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "rate_limited",
    "message": "Aircraft API usage limit exceeded."
  }
}
500The request failed without exposing provider or server internals.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "internal_error",
    "message": "The request could not be completed."
  }
}
503The aircraft read model, authentication authority, entitlement authority, or durable usage meter is temporarily unavailable. Use bounded backoff rather than a tight retry loop.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "service_unavailable",
    "message": "Aircraft data is temporarily unavailable."
  }
}
GET/aircraft/watch-lists

List named Aircraft watch lists

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.

Authentication required. Operation ID: listAircraftWatchLists.

Responses

200Configured watch lists and current plan limits.
Headers
  • X-Aircraft-Plan: Effective Aircraft API plan for this request.
  • X-Aircraft-Watch-List-Limit: Maximum possible named watch lists under the current watched-aircraft target limit.
  • X-Aircraft-Watched-Aircraft-Limit: Maximum total N-number memberships across Aircraft watch lists for the current plan.
{
  "$ref": "#/components/schemas/AircraftWatchListListResponse"
}
401A valid Grizzly Bulls API key is required.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "unauthenticated",
    "message": "A valid API key is required."
  }
}
405The HTTP method is not supported by this endpoint.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "method_not_allowed",
    "message": "Method not allowed."
  }
}
500The request failed without exposing provider or server internals.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "internal_error",
    "message": "The request could not be completed."
  }
}
503The aircraft read model, authentication authority, entitlement authority, or durable usage meter is temporarily unavailable. Use bounded backoff rather than a tight retry loop.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "service_unavailable",
    "message": "Aircraft data is temporarily unavailable."
  }
}
POST/aircraft/watch-lists

Create a named multi-aircraft watch list

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.

Authentication required. Operation ID: createAircraftWatchList.

Request body

{
  "$ref": "#/components/schemas/AircraftWatchListInput"
}

Responses

201Watch list created.
Headers
  • X-Aircraft-Plan: Effective Aircraft API plan for this request.
  • X-Aircraft-Watch-List-Limit: Maximum possible named watch lists under the current watched-aircraft target limit.
  • X-Aircraft-Watched-Aircraft-Limit: Maximum total N-number memberships across Aircraft watch lists for the current plan.
{
  "$ref": "#/components/schemas/AircraftWatchListCreateResponse"
}
400The aircraft identifier, change-feed window/filter/cursor, discovery filters, cursor, or pagination parameters are invalid.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "invalid_request",
    "message": "At least one reviewed aircraft discovery filter is required."
  }
}
401A valid Grizzly Bulls API key is required.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "unauthenticated",
    "message": "A valid API key is required."
  }
}
403The current Aircraft API plan does not include the requested paid Aircraft capability.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "not_entitled",
    "message": "This Aircraft capability requires a Developer or Business plan."
  }
}
405The HTTP method is not supported by this endpoint.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "method_not_allowed",
    "message": "Method not allowed."
  }
}
409The requested Aircraft control-plane mutation conflicts with retained state or a plan-owned limit.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "conflict",
    "message": "An equivalent Aircraft webhook watch already exists."
  }
}
500The request failed without exposing provider or server internals.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "internal_error",
    "message": "The request could not be completed."
  }
}
503The aircraft read model, authentication authority, entitlement authority, or durable usage meter is temporarily unavailable. Use bounded backoff rather than a tight retry loop.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "service_unavailable",
    "message": "Aircraft data is temporarily unavailable."
  }
}
GET/aircraft/watch-lists/{watchId}

Get one Aircraft watch list

Authentication required. Operation ID: getAircraftWatchList.

Parameters

NameLocationRequiredDetails
watchIdpathYes

Opaque Aircraft watch-list identifier.

{
  "type": "string",
  "pattern": "^aw_[a-f0-9]{24}$"
}

Responses

200Owned watch list.
Headers
  • X-Aircraft-Plan: Effective Aircraft API plan for this request.
  • X-Aircraft-Watch-List-Limit: Maximum possible named watch lists under the current watched-aircraft target limit.
  • X-Aircraft-Watched-Aircraft-Limit: Maximum total N-number memberships across Aircraft watch lists for the current plan.
{
  "$ref": "#/components/schemas/AircraftWatchListResponse"
}
400The aircraft identifier, change-feed window/filter/cursor, discovery filters, cursor, or pagination parameters are invalid.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "invalid_request",
    "message": "At least one reviewed aircraft discovery filter is required."
  }
}
401A valid Grizzly Bulls API key is required.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "unauthenticated",
    "message": "A valid API key is required."
  }
}
404No matching current or retained registration was found.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "not_found",
    "message": "No current aircraft registration was found for that N-number."
  }
}
405The HTTP method is not supported by this endpoint.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "method_not_allowed",
    "message": "Method not allowed."
  }
}
500The request failed without exposing provider or server internals.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "internal_error",
    "message": "The request could not be completed."
  }
}
503The aircraft read model, authentication authority, entitlement authority, or durable usage meter is temporarily unavailable. Use bounded backoff rather than a tight retry loop.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "service_unavailable",
    "message": "Aircraft data is temporarily unavailable."
  }
}
PUT/aircraft/watch-lists/{watchId}

Replace one Aircraft watch-list definition

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.

Authentication required. Operation ID: replaceAircraftWatchList.

Parameters

NameLocationRequiredDetails
watchIdpathYes

Opaque Aircraft watch-list identifier.

{
  "type": "string",
  "pattern": "^aw_[a-f0-9]{24}$"
}

Request body

{
  "$ref": "#/components/schemas/AircraftWatchListInput"
}

Responses

200Updated watch list.
Headers
  • X-Aircraft-Plan: Effective Aircraft API plan for this request.
  • X-Aircraft-Watch-List-Limit: Maximum possible named watch lists under the current watched-aircraft target limit.
  • X-Aircraft-Watched-Aircraft-Limit: Maximum total N-number memberships across Aircraft watch lists for the current plan.
{
  "$ref": "#/components/schemas/AircraftWatchListResponse"
}
400The aircraft identifier, change-feed window/filter/cursor, discovery filters, cursor, or pagination parameters are invalid.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "invalid_request",
    "message": "At least one reviewed aircraft discovery filter is required."
  }
}
401A valid Grizzly Bulls API key is required.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "unauthenticated",
    "message": "A valid API key is required."
  }
}
403The current Aircraft API plan does not include the requested paid Aircraft capability.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "not_entitled",
    "message": "This Aircraft capability requires a Developer or Business plan."
  }
}
404No matching current or retained registration was found.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "not_found",
    "message": "No current aircraft registration was found for that N-number."
  }
}
405The HTTP method is not supported by this endpoint.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "method_not_allowed",
    "message": "Method not allowed."
  }
}
409The requested Aircraft control-plane mutation conflicts with retained state or a plan-owned limit.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "conflict",
    "message": "An equivalent Aircraft webhook watch already exists."
  }
}
500The request failed without exposing provider or server internals.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "internal_error",
    "message": "The request could not be completed."
  }
}
503The aircraft read model, authentication authority, entitlement authority, or durable usage meter is temporarily unavailable. Use bounded backoff rather than a tight retry loop.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "service_unavailable",
    "message": "Aircraft data is temporarily unavailable."
  }
}
DELETE/aircraft/watch-lists/{watchId}

Delete one Aircraft watch list

Deletes the owned list plus its target memberships, alert history, and retained delivery troubleshooting records.

Authentication required. Operation ID: deleteAircraftWatchList.

Parameters

NameLocationRequiredDetails
watchIdpathYes

Opaque Aircraft watch-list identifier.

{
  "type": "string",
  "pattern": "^aw_[a-f0-9]{24}$"
}

Responses

204Watch list deleted.
400The aircraft identifier, change-feed window/filter/cursor, discovery filters, cursor, or pagination parameters are invalid.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "invalid_request",
    "message": "At least one reviewed aircraft discovery filter is required."
  }
}
401A valid Grizzly Bulls API key is required.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "unauthenticated",
    "message": "A valid API key is required."
  }
}
404No matching current or retained registration was found.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "not_found",
    "message": "No current aircraft registration was found for that N-number."
  }
}
405The HTTP method is not supported by this endpoint.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "method_not_allowed",
    "message": "Method not allowed."
  }
}
500The request failed without exposing provider or server internals.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "internal_error",
    "message": "The request could not be completed."
  }
}
503The aircraft read model, authentication authority, entitlement authority, or durable usage meter is temporarily unavailable. Use bounded backoff rather than a tight retry loop.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "service_unavailable",
    "message": "Aircraft data is temporarily unavailable."
  }
}
GET/aircraft/watch-lists/{watchId}/alerts

List alert history for one watch list

Returns bounded alert history using the same public change representation as the Aircraft change feed. Use unread=true for unread-only history.

Authentication required. Operation ID: listAircraftWatchAlerts.

Parameters

NameLocationRequiredDetails
watchIdpathYes

Opaque Aircraft watch-list identifier.

{
  "type": "string",
  "pattern": "^aw_[a-f0-9]{24}$"
}
limitqueryNo

Maximum watch-list alerts returned.

{
  "type": "integer",
  "minimum": 1,
  "maximum": 100,
  "default": 20
}
cursorqueryNo

Opaque watch-alert pagination cursor.

{
  "type": "string",
  "maxLength": 512
}
unreadqueryNo

When true, return only unread watch alerts.

{
  "type": "boolean",
  "default": false
}

Responses

200Bounded alert history.
Headers
  • X-Aircraft-Plan: Effective Aircraft API plan for this request.
  • X-Aircraft-Watch-List-Limit: Maximum possible named watch lists under the current watched-aircraft target limit.
  • X-Aircraft-Watched-Aircraft-Limit: Maximum total N-number memberships across Aircraft watch lists for the current plan.
{
  "$ref": "#/components/schemas/AircraftWatchAlertListResponse"
}
400The aircraft identifier, change-feed window/filter/cursor, discovery filters, cursor, or pagination parameters are invalid.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "invalid_request",
    "message": "At least one reviewed aircraft discovery filter is required."
  }
}
401A valid Grizzly Bulls API key is required.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "unauthenticated",
    "message": "A valid API key is required."
  }
}
404No matching current or retained registration was found.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "not_found",
    "message": "No current aircraft registration was found for that N-number."
  }
}
405The HTTP method is not supported by this endpoint.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "method_not_allowed",
    "message": "Method not allowed."
  }
}
500The request failed without exposing provider or server internals.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "internal_error",
    "message": "The request could not be completed."
  }
}
503The aircraft read model, authentication authority, entitlement authority, or durable usage meter is temporarily unavailable. Use bounded backoff rather than a tight retry loop.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "service_unavailable",
    "message": "Aircraft data is temporarily unavailable."
  }
}
POST/aircraft/watch-lists/{watchId}/alerts

Mark watch-list alerts read

Marks up to 100 owned alert ids read. This remains available for retained alert history after a paid-plan downgrade.

Authentication required. Operation ID: markAircraftWatchAlertsRead.

Parameters

NameLocationRequiredDetails
watchIdpathYes

Opaque Aircraft watch-list identifier.

{
  "type": "string",
  "pattern": "^aw_[a-f0-9]{24}$"
}

Request body

{
  "$ref": "#/components/schemas/AircraftWatchAlertReadInput"
}

Responses

200Read state applied.
Headers
  • X-Aircraft-Plan: Effective Aircraft API plan for this request.
  • X-Aircraft-Watch-List-Limit: Maximum possible named watch lists under the current watched-aircraft target limit.
  • X-Aircraft-Watched-Aircraft-Limit: Maximum total N-number memberships across Aircraft watch lists for the current plan.
{
  "$ref": "#/components/schemas/AircraftWatchAlertReadResponse"
}
400The aircraft identifier, change-feed window/filter/cursor, discovery filters, cursor, or pagination parameters are invalid.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "invalid_request",
    "message": "At least one reviewed aircraft discovery filter is required."
  }
}
401A valid Grizzly Bulls API key is required.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "unauthenticated",
    "message": "A valid API key is required."
  }
}
404No matching current or retained registration was found.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "not_found",
    "message": "No current aircraft registration was found for that N-number."
  }
}
405The HTTP method is not supported by this endpoint.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "method_not_allowed",
    "message": "Method not allowed."
  }
}
500The request failed without exposing provider or server internals.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "internal_error",
    "message": "The request could not be completed."
  }
}
503The aircraft read model, authentication authority, entitlement authority, or durable usage meter is temporarily unavailable. Use bounded backoff rather than a tight retry loop.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "service_unavailable",
    "message": "Aircraft data is temporarily unavailable."
  }
}
GET/aircraft/{nNumber}/documents

Get FAA document-index evidence for one aircraft N-number

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.

Authentication required. Operation ID: getAircraftDocumentIndex.

Parameters

NameLocationRequiredDetails
nNumberpathYes

U.S. aircraft N-number. Matching is case-insensitive and normalized.

{
  "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"
}
limitqueryNo

Maximum indexed document records returned. One shared safety bound applies while production query-cost evidence is collected.

{
  "type": "integer",
  "minimum": 1,
  "maximum": 50,
  "default": 25
}
cursorqueryNo

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.

{
  "type": "string",
  "minLength": 1,
  "maxLength": 1024
}

Responses

200Bounded FAA document-index evidence. A valid N-number with no matching rows returns an empty data array.
Headers
  • X-Aircraft-Plan: Resolved aircraft API plan for the authenticated account.
  • X-Aircraft-Rate-Limit: Maximum requests permitted per minute for the resolved aircraft API plan.
  • X-Aircraft-Quota-Limit: Monthly request quota for the resolved aircraft API plan.
  • X-Aircraft-Quota-Remaining: Monthly requests remaining after the current operation was reserved.
  • X-Aircraft-Quota-Reset: UTC timestamp when the current monthly quota window resets.
{
  "$ref": "#/components/schemas/AircraftDocumentIndexResponse"
}
400The aircraft identifier, change-feed window/filter/cursor, discovery filters, cursor, or pagination parameters are invalid.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "invalid_request",
    "message": "At least one reviewed aircraft discovery filter is required."
  }
}
401A valid Grizzly Bulls API key is required.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "unauthenticated",
    "message": "A valid API key is required."
  }
}
403The authenticated API key does not include the Aircraft scope required by this operation.
{
  "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."
  }
}
405The HTTP method is not supported by this endpoint.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "method_not_allowed",
    "message": "Method not allowed."
  }
}
429The short-window request rate or monthly aircraft API quota was exceeded.
Headers
  • X-Aircraft-Plan: Resolved aircraft API plan for the authenticated account.
  • X-Aircraft-Rate-Limit: Maximum requests permitted per minute for the resolved aircraft API plan.
  • X-Aircraft-Quota-Limit: Monthly request quota for the resolved aircraft API plan.
  • X-Aircraft-Quota-Remaining: Monthly requests remaining after the current operation was reserved.
  • X-Aircraft-Quota-Reset: UTC timestamp when the current monthly quota window resets.
  • Retry-After: Seconds until the request may be retried under the limiting policy.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "rate_limited",
    "message": "Aircraft API usage limit exceeded."
  }
}
500The request failed without exposing provider or server internals.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "internal_error",
    "message": "The request could not be completed."
  }
}
503The aircraft read model, authentication authority, entitlement authority, or durable usage meter is temporarily unavailable. Use bounded backoff rather than a tight retry loop.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "service_unavailable",
    "message": "Aircraft data is temporarily unavailable."
  }
}
GET/aircraft/usage

Get current Aircraft plan, monthly usage, and key scopes

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.

Authentication required. Operation ID: getAircraftApiUsage.

Responses

200Current Aircraft plan, monthly usage, remaining quota, reset time, and effective Aircraft scopes.
Headers
  • X-Aircraft-Plan: Resolved Aircraft API plan for the authenticated account.
  • X-Aircraft-Rate-Limit: Maximum data-plane requests permitted per minute for the resolved Aircraft API plan.
  • X-Aircraft-Quota-Limit: Monthly Aircraft data-plane request quota for the resolved plan.
  • X-Aircraft-Quota-Remaining: Current monthly Aircraft data-plane requests remaining. Reading this endpoint does not decrement the value.
  • X-Aircraft-Quota-Reset: UTC timestamp when the current Aircraft monthly quota window resets.
{
  "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",
                  "charts:read"
                ]
              }
            }
          }
        }
      }
    }
  }
}
401A valid Grizzly Bulls API key is required.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "unauthenticated",
    "message": "A valid API key is required."
  }
}
403The authenticated API key does not include the Aircraft scope required by this operation.
{
  "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."
  }
}
405The HTTP method is not supported by this endpoint.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "method_not_allowed",
    "message": "Method not allowed."
  }
}
500The request failed without exposing provider or server internals.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "internal_error",
    "message": "The request could not be completed."
  }
}
503The aircraft read model, authentication authority, entitlement authority, or durable usage meter is temporarily unavailable. Use bounded backoff rather than a tight retry loop.
{
  "$ref": "#/components/schemas/ErrorResponse"
}
Example
{
  "error": {
    "code": "service_unavailable",
    "message": "Aircraft data is temporarily unavailable."
  }
}

Schemas

Reusable definitions exposed by the product OpenAPI contract.

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"
    }
  }
}
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"
    }
  }
}
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"
          ]
        }
      }
    }
  ]
}
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"
      }
    }
  }
}
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"
    }
  }
}
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
      ]
    }
  }
}
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
          ]
        }
      }
    }
  }
}
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"
    }
  }
}
AircraftDiscoveryPagination
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "limit",
    "nextCursor"
  ],
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "nextCursor": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 1024
    }
  }
}
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"
      ]
    }
  }
}
AircraftDiscoveryResponse
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "data",
    "pagination"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/AircraftDiscoveryRecord"
      }
    },
    "pagination": {
      "$ref": "#/components/schemas/AircraftDiscoveryPagination"
    }
  }
}
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
        }
      }
    }
  }
}
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."
}
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
        }
      }
    }
  }
}
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"
    }
  }
}
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
        }
      }
    }
  }
}
AircraftExportRunResponse
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/AircraftExportRun"
    }
  }
}
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"
        }
      }
    }
  }
}
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"
    }
  }
}
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
        }
      }
    }
  }
}
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"
        ]
      }
    }
  }
}
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
        }
      }
    }
  }
}
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"
              ]
            }
          }
        }
      }
    }
  }
}
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"
    }
  }
}
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"
    }
  }
}
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
        }
      }
    }
  }
}
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
        }
      }
    }
  }
}
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"
        }
      }
    }
  }
}
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"
    }
  }
}
AircraftWatchListCreateResponse
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "data",
    "limits"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/AircraftWatchListCreated"
    },
    "limits": {
      "$ref": "#/components/schemas/AircraftWatchListLimits"
    }
  }
}
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."
}
AircraftWatchListLimits
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "watchListLimit",
    "watchedAircraftLimit"
  ],
  "properties": {
    "watchListLimit": {
      "type": "integer",
      "minimum": 0,
      "maximum": 250
    },
    "watchedAircraftLimit": {
      "type": "integer",
      "minimum": 0,
      "maximum": 250
    }
  }
}
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"
    }
  }
}
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"
      }
    }
  }
}
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
    }
  }
}
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"
        }
      }
    }
  }
}
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."
    }
  }
}
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"
    }
  }
}
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"
        ]
      }
    }
  }
}
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
        }
      }
    }
  }
}
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"
          ]
        }
      }
    }
  }
}
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."
    }
  }
}
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"
        }
      }
    }
  }
}
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"
      ]
    }
  }
}
HistoryEvent
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "contractVersion",
    "eventId",
    "aircraftId",
    "previousAircraftId",
    "nNumber",
    "eventType",
    "oldSourceRegistrationStatusCode",
    "newSourceRegistrationStatusCode",
    "changedFields",
    "sourceEffectiveDate",
    "observedAt",
    "previousObservedAt",
    "source"
  ],
  "properties": {
    "contractVersion": {
      "type": "string",
      "const": "aircraft-public-v1"
    },
    "eventId": {
      "type": "string",
      "pattern": "^aevt_[a-f0-9]{32}$",
      "description": "Stable canonical identity for this source-backed observed change. The same ID is used by change feeds, change exports, and signed change webhook deliveries."
    },
    "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"
    }
  }
}
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
    }
  }
}
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"
    }
  }
}
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}$"
    }
  }
}
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"
    }
  }
}
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"
      ]
    }
  }
}
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"
    }
  }
}
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}$"
    }
  }
}