openapi: 3.1.0 info: title: MilitaryService API version: 1.0.0 security: - WorldMonitorKey: [] - ApiKeyHeader: [] servers: - url: https://api.worldmonitor.app paths: /api/military/v1/list-military-flights: get: tags: - MilitaryService summary: ListMilitaryFlights description: >- ListMilitaryFlights retrieves tracked military aircraft from OpenSky and Wingbits. operationId: ListMilitaryFlights parameters: - name: page_size in: query description: >- Maximum items per page (1-100). 0 or omitted uses the default of 100. required: false example: 25 schema: type: integer format: int32 - name: cursor in: query description: >- Cursor for the next page. Treat it as opaque: echo the next-cursor value returned in the previous response's pagination metadata verbatim, and do not construct or parse it. Empty (or any unrecognized value) requests the first page. required: false example: next-page-token schema: type: string - name: ne_lat in: query description: North-east corner latitude of bounding box. required: false example: 40.7128 schema: type: number format: double - name: ne_lon in: query description: North-east corner longitude of bounding box. required: false example: -74.006 schema: type: number format: double - name: sw_lat in: query description: South-west corner latitude of bounding box. required: false example: 40.7128 schema: type: number format: double - name: sw_lon in: query description: South-west corner longitude of bounding box. required: false example: -74.006 schema: type: number format: double - name: operator in: query description: |- Optional operator filter. Accepted but currently ignored; no-op until this handler supports the parameter. required: false example: MILITARY_OPERATOR_USAF schema: type: string enum: - MILITARY_OPERATOR_USAF - MILITARY_OPERATOR_USN - MILITARY_OPERATOR_USMC - MILITARY_OPERATOR_USA - MILITARY_OPERATOR_RAF - MILITARY_OPERATOR_RN - MILITARY_OPERATOR_FAF - MILITARY_OPERATOR_GAF - MILITARY_OPERATOR_PLAAF - MILITARY_OPERATOR_PLAN - MILITARY_OPERATOR_VKS - MILITARY_OPERATOR_IAF - MILITARY_OPERATOR_NATO - MILITARY_OPERATOR_OTHER - name: aircraft_type in: query description: |- Optional aircraft type filter. Accepted but currently ignored; no-op until this handler supports the parameter. required: false example: MILITARY_AIRCRAFT_TYPE_FIGHTER schema: type: string enum: - MILITARY_AIRCRAFT_TYPE_FIGHTER - MILITARY_AIRCRAFT_TYPE_BOMBER - MILITARY_AIRCRAFT_TYPE_TRANSPORT - MILITARY_AIRCRAFT_TYPE_TANKER - MILITARY_AIRCRAFT_TYPE_AWACS - MILITARY_AIRCRAFT_TYPE_RECONNAISSANCE - MILITARY_AIRCRAFT_TYPE_HELICOPTER - MILITARY_AIRCRAFT_TYPE_DRONE - MILITARY_AIRCRAFT_TYPE_PATROL - MILITARY_AIRCRAFT_TYPE_SPECIAL_OPS - MILITARY_AIRCRAFT_TYPE_VIP - MILITARY_AIRCRAFT_TYPE_UNKNOWN - name: jmespath in: query description: >- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: keys(@) schema: type: string responses: '200': description: Successful response content: application/json: example: clusters: - activityType: MILITARY_ACTIVITY_TYPE_EXERCISE dominantOperator: MILITARY_OPERATOR_USAF flightCount: 1 flights: - aircraftModel: example aircraftType: MILITARY_AIRCRAFT_TYPE_FIGHTER altitude: 1.5 callsign: example confidence: MILITARY_CONFIDENCE_LOW id: example-id id: example-id flights: - aircraftModel: example aircraftType: MILITARY_AIRCRAFT_TYPE_FIGHTER altitude: 1.5 callsign: example confidence: MILITARY_CONFIDENCE_LOW id: example-id pagination: nextCursor: next-page-token totalCount: 1 schema: $ref: '#/components/schemas/ListMilitaryFlightsResponse' '400': description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: >- API access requires an active subscription (the API key's subscription is inactive or expired). content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '429': description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: >- Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/military/v1/get-theater-posture: get: tags: - MilitaryService summary: GetTheaterPosture description: >- GetTheaterPosture retrieves military posture assessments for geographic theaters. operationId: GetTheaterPosture parameters: - name: theater in: query description: >- Theater name (e.g., "indo-pacific", "european", "middle-east"). Empty for all theaters. Accepted but currently ignored; no-op until this handler supports the parameter. required: false example: indo-pacific schema: type: string - name: jmespath in: query description: >- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: keys(@) schema: type: string responses: '200': description: Successful response content: application/json: example: theaters: - activeFlights: 1 activeOperations: - example assessedAt: 1717200000000 postureLevel: example theater: indo-pacific schema: $ref: '#/components/schemas/GetTheaterPostureResponse' '400': description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: >- API access requires an active subscription (the API key's subscription is inactive or expired). content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '429': description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: >- Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/military/v1/get-aircraft-details: get: tags: - MilitaryService summary: GetAircraftDetails description: >- GetAircraftDetails retrieves Wingbits aircraft enrichment data for a single ICAO24 hex. operationId: GetAircraftDetails parameters: - name: icao24 in: query description: ICAO 24-bit hex address (lowercase). required: true example: a835af schema: type: string - name: jmespath in: query description: >- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: keys(@) schema: type: string responses: '200': description: Successful response content: application/json: example: configured: true details: built: example categoryDescription: cs.AI engines: example icao24: a835af icaoAircraftType: all schema: $ref: '#/components/schemas/GetAircraftDetailsResponse' '400': description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: >- API access requires an active subscription (the API key's subscription is inactive or expired). content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '429': description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: >- Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/military/v1/get-aircraft-details-batch: post: parameters: - name: Idempotency-Key in: header description: >- Optional client-generated idempotency key. Retrying a POST with the same key and an identical request body replays the original response (only the status, body, and Content-Type are reproduced) instead of re-executing; reusing the key with a different body is rejected with 422. For mutations this avoids duplicating the side effect, while for batch-read POSTs it replays a cached snapshot that can be up to 24 hours stale. Keys are scoped per authenticated caller (falling back to the source IP for unauthenticated endpoints) and retained for 24 hours. required: false example: 4f8b9c2e-1a3d-4b6f-8e0a-2c5d7f9b1e34 schema: type: string minLength: 1 maxLength: 255 pattern: ^[\x21-\x7E]{1,255}$ tags: - MilitaryService summary: GetAircraftDetailsBatch description: >- GetAircraftDetailsBatch retrieves Wingbits aircraft enrichment data for multiple ICAO24 hexes. operationId: GetAircraftDetailsBatch requestBody: content: application/json: example: icao24s: - a835af schema: $ref: '#/components/schemas/GetAircraftDetailsBatchRequest' required: true responses: '200': description: Successful response headers: Idempotency-Key: schema: type: string description: >- The idempotency key echoed from the request. Present only when the client opted into idempotency. Idempotent-Replayed: schema: type: boolean description: >- true when this response was replayed from an earlier request with the same key, false on the first (original) request. Present only when the client opted into idempotency. content: application/json: example: configured: true fetched: 1 requested: 1 results: exampleKey: built: example categoryDescription: cs.AI engines: example icao24: a835af icaoAircraftType: all schema: $ref: '#/components/schemas/GetAircraftDetailsBatchResponse' '400': description: >- Validation error, invalid Idempotency-Key header, or malformed JSON request body content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - type: object required: - error - message properties: error: type: string message: type: string - $ref: '#/components/schemas/InvalidRequestBodyError' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: >- API access requires an active subscription (the API key's subscription is inactive or expired). content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '409': description: A request with this Idempotency-Key is still being processed headers: Idempotency-Key: schema: type: string description: The idempotency key supplied by the client. Retry-After: schema: type: string description: Seconds to wait before retrying the in-flight request. content: application/json: schema: type: object required: - error - message properties: error: type: string message: type: string '422': description: The Idempotency-Key was already used with a different request body headers: Idempotency-Key: schema: type: string description: The idempotency key supplied by the client. content: application/json: schema: type: object required: - error - message properties: error: type: string message: type: string '429': description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: >- Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/military/v1/get-wingbits-status: get: tags: - MilitaryService summary: GetWingbitsStatus description: >- GetWingbitsStatus checks whether the Wingbits enrichment API is configured. operationId: GetWingbitsStatus parameters: - name: jmespath in: query description: >- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: keys(@) schema: type: string responses: '200': description: Successful response content: application/json: example: configured: true schema: $ref: '#/components/schemas/GetWingbitsStatusResponse' '400': description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: >- API access requires an active subscription (the API key's subscription is inactive or expired). content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '429': description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: >- Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/military/v1/get-usni-fleet-report: get: tags: - MilitaryService summary: GetUSNIFleetReport description: >- GetUSNIFleetReport retrieves the latest parsed USNI Fleet Tracker report. operationId: GetUSNIFleetReport parameters: - name: force_refresh in: query description: When true, bypass cache and fetch fresh data from USNI. required: false example: true schema: type: boolean - name: jmespath in: query description: >- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: keys(@) schema: type: string responses: '200': description: Successful response content: application/json: example: cached: true error: example report: articleDate: '2026-01-15' articleTitle: example articleUrl: https://example.com/worldmonitor battleForceSummary: deployed: 1 totalShips: 1 underway: 1 parsingWarnings: - example stale: true schema: $ref: '#/components/schemas/GetUSNIFleetReportResponse' '400': description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: >- API access requires an active subscription (the API key's subscription is inactive or expired). content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '429': description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: >- Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/military/v1/list-military-bases: get: tags: - MilitaryService summary: ListMilitaryBases description: >- ListMilitaryBases retrieves military bases within a bounding box, with server-side clustering. operationId: ListMilitaryBases parameters: - name: ne_lat in: query description: North-east corner latitude of the map bounding box. required: false example: 40.7128 schema: type: number format: double - name: ne_lon in: query description: North-east corner longitude of the map bounding box. required: false example: -74.006 schema: type: number format: double - name: sw_lat in: query description: South-west corner latitude of the map bounding box. required: false example: 40.7128 schema: type: number format: double - name: sw_lon in: query description: South-west corner longitude of the map bounding box. required: false example: -74.006 schema: type: number format: double - name: zoom in: query description: Map zoom level used to decide whether to return bases or clusters. required: false example: 1 schema: type: integer format: int32 - name: type in: query description: Optional military base type filter. required: false example: us-nato schema: type: string enum: - us-nato - china - russia - uk - france - india - italy - uae - turkey - japan - other - name: kind in: query description: Optional military base kind filter. required: false example: base schema: type: string enum: - base - airfield - naval_base - military - barracks - bunker - trench - training_area - checkpoint - shelter - ammunition - office - obstacle_course - nuclear_explosion_site - range - name: country in: query description: Optional country filter for military bases. required: false example: US schema: type: string - name: jmespath in: query description: >- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: keys(@) schema: type: string responses: '200': description: Successful response content: application/json: example: bases: - branch: example catAirforce: true catNaval: true catNuclear: true catSpace: true clusters: - count: 1 dominantType: all expansionZoom: 1 latitude: 40.7128 longitude: -74.006 totalInView: 1 truncated: true schema: $ref: '#/components/schemas/ListMilitaryBasesResponse' '400': description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: >- API access requires an active subscription (the API key's subscription is inactive or expired). content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '429': description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: >- Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/military/v1/get-wingbits-live-flight: get: tags: - MilitaryService summary: GetWingbitsLiveFlight description: >- GetWingbitsLiveFlight retrieves real-time position data from the Wingbits ECS network for a single aircraft. operationId: GetWingbitsLiveFlight parameters: - name: icao24 in: query description: ICAO 24-bit hex address (lowercase, 6 characters). required: true example: a835af schema: type: string - name: jmespath in: query description: >- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: keys(@) schema: type: string responses: '200': description: Successful response content: application/json: example: flight: airlineName: WorldMonitor Analyst altitude: 1.5 arrDelayedMin: 1 arrEstimatedUtc: example arrIata: JFK schema: $ref: '#/components/schemas/GetWingbitsLiveFlightResponse' '400': description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: >- API access requires an active subscription (the API key's subscription is inactive or expired). content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '429': description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: >- Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' /api/military/v1/list-defense-patents: get: tags: - MilitaryService summary: ListDefensePatents description: >- ListDefensePatents retrieves recent defense/dual-use patent filings from the USPTO Open Data Portal. operationId: ListDefensePatents parameters: - name: cpc_code in: query description: >- CPC category filter (e.g. "H04B", "F42B"). Empty returns all categories. required: false example: H04B schema: type: string - name: assignee in: query description: >- Assignee keyword filter (case-insensitive substring match). Empty returns all. required: false example: example schema: type: string - name: limit in: query description: Maximum results to return (default 20, max 100). required: false example: 25 schema: type: integer format: int32 - name: jmespath in: query description: >- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: keys(@) schema: type: string responses: '200': description: Successful response content: application/json: example: fetchedAt: '2026-01-15T12:00:00Z' patents: - abstract: '' assignee: example cpcCode: example cpcDesc: example date: '2026-01-15' total: 1 schema: $ref: '#/components/schemas/ListDefensePatentsResponse' '400': description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: >- API access requires an active subscription (the API key's subscription is inactive or expired). content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '429': description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: >- Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' components: securitySchemes: WorldMonitorKey: type: apiKey in: header name: X-WorldMonitor-Key description: User-issued WorldMonitor API key. ApiKeyHeader: type: apiKey in: header name: X-Api-Key description: Alias header for the WorldMonitor API key (X-WorldMonitor-Key). schemas: JmespathProjectionError: description: >- Returned when a REST jmespath projection is invalid or exceeds the expression/output byte limits. properties: _jmespath_error: description: Projection error discriminator and details. type: string original_keys: description: Top-level keys or shape of the unprojected response. items: type: string type: array required: - _jmespath_error - original_keys type: object UnauthorizedError: type: object properties: error: type: string description: Human-readable error message. required: - error description: >- Returned when the API key is missing, malformed, or lacks current API access. Error: type: object properties: message: type: string description: Error message (e.g., 'user not found', 'database connection failed') description: >- Error is returned when a handler encounters an error. It contains a simple error message that the developer can customize. InvalidRequestBodyError: type: object description: Returned when a JSON POST request body is empty or malformed. properties: message: type: string description: Invalid request body required: - message GatewayError: type: object description: >- Returned by gateway infrastructure errors before an RPC handler runs, such as origin, routing, method, authentication, or quota checks. properties: error: oneOf: - type: string - type: object additionalProperties: true description: Gateway error reason or structured gateway failure details. required: - error RateLimitError: type: object description: Returned when a gateway or handler rate limit rejects the request. properties: error: type: string description: Human-readable rate-limit failure reason. required: - error ForbiddenError: type: object properties: error: type: string description: Human-readable entitlement failure reason. requiredTier: type: integer format: int32 description: Minimum entitlement tier required for this endpoint. currentTier: type: integer format: int32 description: Caller entitlement tier when known. planKey: type: string description: Caller plan key when known. required: - error description: >- Returned when a PRO-gated endpoint denies access because the caller has no resolved authenticated user, entitlements cannot be verified, or the caller lacks the required entitlement tier. FieldViolation: type: object properties: field: type: string description: >- The field path that failed validation (e.g., 'user.email' for nested fields). For header validation, this will be the header name (e.g., 'X-API-Key') description: type: string description: >- Human-readable description of the validation violation (e.g., 'must be a valid email address', 'required field missing') required: - field - description description: FieldViolation describes a single validation error for a specific field. ValidationError: type: object properties: violations: type: array items: $ref: '#/components/schemas/FieldViolation' description: List of validation violations required: - violations description: >- ValidationError is returned when request validation fails. It contains a list of field violations describing what went wrong. ListMilitaryFlightsRequest: type: object properties: pageSize: type: integer format: int32 description: >- Maximum items per page (1-100). 0 or omitted uses the default of 100. cursor: type: string description: >- Cursor for the next page. Treat it as opaque: echo the next-cursor value returned in the previous response's pagination metadata verbatim, and do not construct or parse it. Empty (or any unrecognized value) requests the first page. neLat: type: number format: double description: North-east corner latitude of bounding box. neLon: type: number format: double description: North-east corner longitude of bounding box. swLat: type: number format: double description: South-west corner latitude of bounding box. swLon: type: number format: double description: South-west corner longitude of bounding box. operator: type: string enum: - MILITARY_OPERATOR_UNSPECIFIED - MILITARY_OPERATOR_USAF - MILITARY_OPERATOR_USN - MILITARY_OPERATOR_USMC - MILITARY_OPERATOR_USA - MILITARY_OPERATOR_RAF - MILITARY_OPERATOR_RN - MILITARY_OPERATOR_FAF - MILITARY_OPERATOR_GAF - MILITARY_OPERATOR_PLAAF - MILITARY_OPERATOR_PLAN - MILITARY_OPERATOR_VKS - MILITARY_OPERATOR_IAF - MILITARY_OPERATOR_NATO - MILITARY_OPERATOR_OTHER description: >- MilitaryOperator represents the military branch or force operating an asset. aircraftType: type: string enum: - MILITARY_AIRCRAFT_TYPE_UNSPECIFIED - MILITARY_AIRCRAFT_TYPE_FIGHTER - MILITARY_AIRCRAFT_TYPE_BOMBER - MILITARY_AIRCRAFT_TYPE_TRANSPORT - MILITARY_AIRCRAFT_TYPE_TANKER - MILITARY_AIRCRAFT_TYPE_AWACS - MILITARY_AIRCRAFT_TYPE_RECONNAISSANCE - MILITARY_AIRCRAFT_TYPE_HELICOPTER - MILITARY_AIRCRAFT_TYPE_DRONE - MILITARY_AIRCRAFT_TYPE_PATROL - MILITARY_AIRCRAFT_TYPE_SPECIAL_OPS - MILITARY_AIRCRAFT_TYPE_VIP - MILITARY_AIRCRAFT_TYPE_UNKNOWN description: >- MilitaryAircraftType represents the classification of a military aircraft. description: >- ListMilitaryFlightsRequest specifies filters for retrieving military flight data. ListMilitaryFlightsResponse: type: object properties: flights: type: array items: $ref: '#/components/schemas/MilitaryFlight' clusters: type: array items: $ref: '#/components/schemas/MilitaryFlightCluster' pagination: $ref: '#/components/schemas/PaginationResponse' description: ListMilitaryFlightsResponse contains military flights and clusters. MilitaryFlight: type: object properties: id: type: string minLength: 1 description: Unique flight identifier. callsign: type: string description: Aircraft callsign. hexCode: type: string description: |- ICAO 24-bit hex address. Canonical form is UPPERCASE — seeders and handlers must uppercase before writing so hex-based lookups (src/services/military-flights.ts:getFlightByHex) match regardless of upstream source casing. registration: type: string description: Aircraft registration number. aircraftType: type: string enum: - MILITARY_AIRCRAFT_TYPE_UNSPECIFIED - MILITARY_AIRCRAFT_TYPE_FIGHTER - MILITARY_AIRCRAFT_TYPE_BOMBER - MILITARY_AIRCRAFT_TYPE_TRANSPORT - MILITARY_AIRCRAFT_TYPE_TANKER - MILITARY_AIRCRAFT_TYPE_AWACS - MILITARY_AIRCRAFT_TYPE_RECONNAISSANCE - MILITARY_AIRCRAFT_TYPE_HELICOPTER - MILITARY_AIRCRAFT_TYPE_DRONE - MILITARY_AIRCRAFT_TYPE_PATROL - MILITARY_AIRCRAFT_TYPE_SPECIAL_OPS - MILITARY_AIRCRAFT_TYPE_VIP - MILITARY_AIRCRAFT_TYPE_UNKNOWN description: >- MilitaryAircraftType represents the classification of a military aircraft. aircraftModel: type: string description: Specific aircraft model (e.g., "F-35A", "C-17A"). operator: type: string enum: - MILITARY_OPERATOR_UNSPECIFIED - MILITARY_OPERATOR_USAF - MILITARY_OPERATOR_USN - MILITARY_OPERATOR_USMC - MILITARY_OPERATOR_USA - MILITARY_OPERATOR_RAF - MILITARY_OPERATOR_RN - MILITARY_OPERATOR_FAF - MILITARY_OPERATOR_GAF - MILITARY_OPERATOR_PLAAF - MILITARY_OPERATOR_PLAN - MILITARY_OPERATOR_VKS - MILITARY_OPERATOR_IAF - MILITARY_OPERATOR_NATO - MILITARY_OPERATOR_OTHER description: >- MilitaryOperator represents the military branch or force operating an asset. operatorCountry: type: string description: Country operating the aircraft (ISO 3166-1 alpha-2). location: $ref: '#/components/schemas/GeoCoordinates' altitude: type: number format: double description: Altitude in feet. heading: type: number format: double description: Heading in degrees. speed: type: number format: double description: Speed in knots. verticalRate: type: number format: double description: Vertical rate in feet per minute. onGround: type: boolean description: Whether the aircraft is on the ground. squawk: type: string description: Transponder squawk code. origin: type: string description: ICAO code of the origin airport. destination: type: string description: ICAO code of the destination airport. lastSeenAt: type: integer format: int64 description: >- Last seen time, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript firstSeenAt: type: integer format: int64 description: >- First seen time, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript confidence: type: string enum: - MILITARY_CONFIDENCE_UNSPECIFIED - MILITARY_CONFIDENCE_LOW - MILITARY_CONFIDENCE_MEDIUM - MILITARY_CONFIDENCE_HIGH description: MilitaryConfidence represents confidence in asset identification. isInteresting: type: boolean description: Whether flagged for unusual activity. note: type: string description: Analyst note. enrichment: $ref: '#/components/schemas/FlightEnrichment' required: - id description: >- MilitaryFlight represents a tracked military aircraft from OpenSky or Wingbits. GeoCoordinates: type: object properties: latitude: type: number maximum: 90 minimum: -90 format: double description: Latitude in decimal degrees (-90 to 90). longitude: type: number maximum: 180 minimum: -180 format: double description: Longitude in decimal degrees (-180 to 180). description: GeoCoordinates represents a geographic location using WGS84 coordinates. FlightEnrichment: type: object properties: manufacturer: type: string description: Aircraft manufacturer. owner: type: string description: Registered owner. operatorName: type: string description: Operator name. typeCode: type: string description: ICAO type code. builtYear: type: string description: Year the aircraft was built. confirmedMilitary: type: boolean description: Whether confirmed as military. militaryBranch: type: string description: Military branch designation. description: >- FlightEnrichment contains additional data from Wingbits aircraft database. MilitaryFlightCluster: type: object properties: id: type: string description: Unique cluster identifier. name: type: string description: Descriptive name of the cluster. location: $ref: '#/components/schemas/GeoCoordinates' flightCount: type: integer format: int32 description: Number of flights in the cluster. flights: type: array items: $ref: '#/components/schemas/MilitaryFlight' dominantOperator: type: string enum: - MILITARY_OPERATOR_UNSPECIFIED - MILITARY_OPERATOR_USAF - MILITARY_OPERATOR_USN - MILITARY_OPERATOR_USMC - MILITARY_OPERATOR_USA - MILITARY_OPERATOR_RAF - MILITARY_OPERATOR_RN - MILITARY_OPERATOR_FAF - MILITARY_OPERATOR_GAF - MILITARY_OPERATOR_PLAAF - MILITARY_OPERATOR_PLAN - MILITARY_OPERATOR_VKS - MILITARY_OPERATOR_IAF - MILITARY_OPERATOR_NATO - MILITARY_OPERATOR_OTHER description: >- MilitaryOperator represents the military branch or force operating an asset. activityType: type: string enum: - MILITARY_ACTIVITY_TYPE_UNSPECIFIED - MILITARY_ACTIVITY_TYPE_EXERCISE - MILITARY_ACTIVITY_TYPE_PATROL - MILITARY_ACTIVITY_TYPE_TRANSPORT - MILITARY_ACTIVITY_TYPE_DEPLOYMENT - MILITARY_ACTIVITY_TYPE_TRANSIT - MILITARY_ACTIVITY_TYPE_UNKNOWN description: >- MilitaryActivityType represents the assessed type of military activity. description: >- MilitaryFlightCluster represents a geographic cluster of military flights. PaginationResponse: type: object properties: nextCursor: type: string description: >- Cursor for fetching the next page. Empty string indicates no more pages. totalCount: type: integer format: int32 description: >- Total count of items matching the query, if known. Zero if the total is unknown. description: >- PaginationResponse contains pagination metadata returned alongside list results. GetTheaterPostureRequest: type: object properties: theater: type: string description: >- Theater name (e.g., "indo-pacific", "european", "middle-east"). Empty for all theaters. Accepted but currently ignored; no-op until this handler supports the parameter. description: GetTheaterPostureRequest specifies the theater to assess. GetTheaterPostureResponse: type: object properties: theaters: type: array items: $ref: '#/components/schemas/TheaterPosture' description: GetTheaterPostureResponse contains theater posture assessments. TheaterPosture: type: object properties: theater: type: string description: Theater name (e.g., "Indo-Pacific", "European", "Middle East"). postureLevel: type: string description: Overall posture assessment. activeFlights: type: integer format: int32 description: Number of active flights in the theater. trackedVessels: type: integer format: int32 description: Number of tracked vessels in the theater. activeOperations: type: array items: type: string description: Notable ongoing operations. assessedAt: type: integer format: int64 description: >- Assessment timestamp, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript description: >- TheaterPosture represents an assessed military posture for a geographic theater. GetAircraftDetailsRequest: type: object properties: icao24: type: string minLength: 1 description: ICAO 24-bit hex address (lowercase). required: - icao24 description: GetAircraftDetailsRequest looks up a single aircraft by ICAO 24-bit hex. GetAircraftDetailsResponse: type: object properties: details: $ref: '#/components/schemas/AircraftDetails' configured: type: boolean description: Whether the Wingbits API is configured. description: GetAircraftDetailsResponse contains the aircraft enrichment data. AircraftDetails: type: object properties: icao24: type: string description: ICAO 24-bit hex address. registration: type: string description: Aircraft registration number. manufacturerIcao: type: string description: ICAO manufacturer code. manufacturerName: type: string description: Full manufacturer name. model: type: string description: Aircraft model. typecode: type: string description: ICAO type designator code. serialNumber: type: string description: Manufacturer serial number. icaoAircraftType: type: string description: ICAO aircraft type designator. operator: type: string description: Operator name. operatorCallsign: type: string description: Operator callsign. operatorIcao: type: string description: Operator ICAO code. owner: type: string description: Registered owner. built: type: string description: Build date. engines: type: string description: Engine description. categoryDescription: type: string description: ICAO category description. description: AircraftDetails contains Wingbits aircraft enrichment data. GetAircraftDetailsBatchRequest: type: object properties: icao24s: type: array items: type: string maxItems: 20 minItems: 1 description: >- ICAO 24-bit hex addresses (lowercase). Up to 20 are accepted by validation, but the handler de-duplicates, sorts, and processes at most the first 10 addresses. maxItems: 20 minItems: 1 description: >- GetAircraftDetailsBatchRequest looks up multiple aircraft by ICAO 24-bit hex. GetAircraftDetailsBatchResponse: type: object properties: results: type: object additionalProperties: $ref: '#/components/schemas/AircraftDetails' description: Map of icao24 -> aircraft details for found aircraft. fetched: type: integer format: int32 description: Number of aircraft successfully fetched from upstream. requested: type: integer format: int32 description: Number of aircraft requested. configured: type: boolean description: Whether the Wingbits API is configured. description: GetAircraftDetailsBatchResponse contains the batch lookup results. ResultsEntry: type: object properties: key: type: string value: $ref: '#/components/schemas/AircraftDetails' GetWingbitsStatusRequest: type: object description: >- GetWingbitsStatusRequest checks whether the Wingbits enrichment API is configured. GetWingbitsStatusResponse: type: object properties: configured: type: boolean description: Whether the Wingbits API key is configured on the server. description: GetWingbitsStatusResponse indicates whether Wingbits is available. GetUSNIFleetReportRequest: type: object properties: forceRefresh: type: boolean description: When true, bypass cache and fetch fresh data from USNI. description: GetUSNIFleetReportRequest requests the latest USNI Fleet Tracker report. GetUSNIFleetReportResponse: type: object properties: report: $ref: '#/components/schemas/USNIFleetReport' cached: type: boolean description: Whether the response was served from cache. stale: type: boolean description: Whether the cached data is stale (served after a fetch failure). error: type: string description: Error message, if any. description: GetUSNIFleetReportResponse returns the parsed USNI Fleet Tracker report. USNIFleetReport: type: object properties: articleUrl: type: string description: URL of the source article. articleDate: type: string description: Publication date of the article. articleTitle: type: string description: Title of the article. battleForceSummary: $ref: '#/components/schemas/BattleForceSummary' vessels: type: array items: $ref: '#/components/schemas/USNIVessel' strikeGroups: type: array items: $ref: '#/components/schemas/USNIStrikeGroup' regions: type: array items: type: string description: Unique region names mentioned in the article. parsingWarnings: type: array items: type: string description: Warnings generated during parsing. timestamp: type: integer format: int64 description: >- Time the report was generated, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript description: >- USNIFleetReport is the full parsed output of a USNI Fleet Tracker article. BattleForceSummary: type: object properties: totalShips: type: integer minimum: 0 format: int32 description: Total ships in the battle force. deployed: type: integer minimum: 0 format: int32 description: Number of ships currently deployed. underway: type: integer minimum: 0 format: int32 description: Number of ships currently underway. description: BattleForceSummary contains fleet-wide ship count statistics. USNIVessel: type: object properties: name: type: string minLength: 1 description: Vessel name (e.g., "USS Abraham Lincoln"). hullNumber: type: string minLength: 1 description: Hull designation (e.g., "CVN-72", "DDG-51"). vesselType: type: string description: >- Vessel type classification (e.g., "carrier", "destroyer", "submarine"). region: type: string description: Region name where the vessel is operating. regionLat: type: number format: double description: Approximate latitude for the region. regionLon: type: number format: double description: Approximate longitude for the region. deploymentStatus: type: string description: >- Deployment status (e.g., "deployed", "underway", "in-port", "unknown"). homePort: type: string description: Home port, if identified from the article text. strikeGroup: type: string description: Strike group assignment, if any. activityDescription: type: string description: Brief activity description parsed from article prose. articleUrl: type: string description: URL of the USNI article this vessel was parsed from. articleDate: type: string description: Publication date of the USNI article. required: - name - hullNumber description: >- USNIVessel represents a single vessel parsed from a USNI Fleet Tracker article. USNIStrikeGroup: type: object properties: name: type: string description: Strike group name (e.g., "Abraham Lincoln Carrier Strike Group"). carrier: type: string description: Carrier name and hull (e.g., "USS Abraham Lincoln (CVN-72)"). airWing: type: string description: Assigned air wing (e.g., "Carrier Air Wing Nine"). destroyerSquadron: type: string description: Assigned destroyer squadron. escorts: type: array items: type: string description: Escort vessels in the strike group. description: >- USNIStrikeGroup represents a carrier strike group parsed from the article. ListMilitaryBasesRequest: type: object properties: neLat: type: number format: double description: North-east corner latitude of the map bounding box. neLon: type: number format: double description: North-east corner longitude of the map bounding box. swLat: type: number format: double description: South-west corner latitude of the map bounding box. swLon: type: number format: double description: South-west corner longitude of the map bounding box. zoom: type: integer format: int32 description: Map zoom level used to decide whether to return bases or clusters. type: type: string description: Optional military base type filter. kind: type: string description: Optional military base kind filter. country: type: string description: Optional country filter for military bases. ListMilitaryBasesResponse: type: object properties: bases: type: array items: $ref: '#/components/schemas/MilitaryBaseEntry' clusters: type: array items: $ref: '#/components/schemas/MilitaryBaseCluster' totalInView: type: integer format: int32 truncated: type: boolean MilitaryBaseEntry: type: object properties: id: type: string name: type: string latitude: type: number format: double longitude: type: number format: double kind: type: string countryIso2: type: string type: type: string tier: type: integer format: int32 catAirforce: type: boolean catNaval: type: boolean catNuclear: type: boolean catSpace: type: boolean catTraining: type: boolean branch: type: string status: type: string MilitaryBaseCluster: type: object properties: latitude: type: number format: double longitude: type: number format: double count: type: integer format: int32 dominantType: type: string expansionZoom: type: integer format: int32 GetWingbitsLiveFlightRequest: type: object properties: icao24: type: string minLength: 1 description: ICAO 24-bit hex address (lowercase, 6 characters). required: - icao24 description: >- GetWingbitsLiveFlightRequest fetches live Wingbits ECS data for a single aircraft. GetWingbitsLiveFlightResponse: type: object properties: flight: $ref: '#/components/schemas/WingbitsLiveFlight' description: >- GetWingbitsLiveFlightResponse contains the live flight data, if available. WingbitsLiveFlight: type: object properties: icao24: type: string description: ICAO 24-bit hex address. callsign: type: string description: Live callsign. lat: type: number format: double description: Latitude in decimal degrees. lon: type: number format: double description: Longitude in decimal degrees. altitude: type: number format: double description: Altitude in feet. speed: type: number format: double description: Ground speed in knots. heading: type: number format: double description: Track/heading in degrees. verticalRate: type: number format: double description: >- Vertical rate in feet per minute (positive = climb, negative = descent). registration: type: string description: Aircraft registration number. model: type: string description: Aircraft model (e.g. "PC-12/45"). operator: type: string description: Operator name. onGround: type: boolean description: True if the aircraft is on the ground. lastSeen: type: string format: int64 description: Unix timestamp of the last position update. depIata: type: string description: |- Schedule — from ecs-api.wingbits.com/v1/flights/schedule/{callsign} Departure airport IATA code (e.g. "FJR"). arrIata: type: string description: Arrival airport IATA code (e.g. "BOM"). depTimeUtc: type: string description: Scheduled departure time UTC (ISO 8601). arrTimeUtc: type: string description: Scheduled arrival time UTC (ISO 8601). depEstimatedUtc: type: string description: Estimated departure time UTC (ISO 8601). arrEstimatedUtc: type: string description: Estimated arrival time UTC (ISO 8601). depDelayedMin: type: integer format: int32 description: Departure delay in minutes (negative = early). arrDelayedMin: type: integer format: int32 description: Arrival delay in minutes (negative = early). flightStatus: type: string description: Flight status string (e.g. "en-route", "landed", "scheduled"). flightDurationMin: type: integer format: int32 description: Scheduled flight duration in minutes. arrTerminal: type: string description: Arrival terminal (e.g. "2"). photoUrl: type: string description: |- Photo — from api.planespotters.net/pub/photos/hex/{icao24} Aircraft photo URL (large thumbnail ~497x280). photoLink: type: string description: Permalink to the photo page on planespotters.net. photoCredit: type: string description: Photographer credit name. callsignIata: type: string description: |- Airline — resolved server-side from the ICAO callsign prefix. IATA-equivalent callsign (e.g. "EK528" for ICAO "UAE528"). Empty if no mapping. airlineName: type: string description: Airline name (e.g. "Emirates"). Empty if no mapping. description: >- WingbitsLiveFlight contains real-time flight position data from the Wingbits ECS network. ListDefensePatentsRequest: type: object properties: cpcCode: type: string description: >- CPC category filter (e.g. "H04B", "F42B"). Empty returns all categories. assignee: type: string description: >- Assignee keyword filter (case-insensitive substring match). Empty returns all. limit: type: integer format: int32 description: Maximum results to return (default 20, max 100). description: ListDefensePatentsRequest filters defense/dual-use patent filings. ListDefensePatentsResponse: type: object properties: patents: type: array items: $ref: '#/components/schemas/DefensePatentFiling' total: type: integer format: int32 description: Total number of filings in the seeded dataset. fetchedAt: type: string description: ISO 8601 timestamp when data was seeded. description: >- ListDefensePatentsResponse contains recent defense/dual-use patent filings. DefensePatentFiling: type: object properties: patentId: type: string description: USPTO patent ID. title: type: string description: Patent title. date: type: string description: Filing date (YYYY-MM-DD). assignee: type: string description: Primary assignee organization name. cpcCode: type: string description: CPC classification code (e.g. "H04B", "F42B"). cpcDesc: type: string description: CPC class description. abstract: type: string description: >- Compatibility field retained for existing clients. Always empty because USPTO Open Data Portal Patent File Wrapper records do not include abstracts. url: type: string description: USPTO patent URL. description: >- DefensePatentFiling is a single patent filing from a defense/dual-use organization.