docs/api/MilitaryService.openapi.yaml
Rama main · réplica de lectura del repositorio original.
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 returns paginated military aircraft observations within a bounding box, including callsign, position, altitude, operator, and source fields.
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).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
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'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
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: Retrieve military posture assessments for all cached theaters, including posture levels, active flights, operations and assessment times in regional monitoring.
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).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
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'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
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: Retrieve Wingbits aircraft enrichment by ICAO24 hex, including available aircraft type and build details. PRO-gated. Requires an active Pro subscription.
operationId: GetAircraftDetails
security:
- WorldMonitorKey: []
- ApiKeyHeader: []
- BearerAuth: []
parameters:
- name: icao24
in: query
description: ICAO 24-bit hex address (lowercase).
required: true
example: "a835af"
schema:
type: string
pattern: '^[0-9a-fA-F]{6}$'
- 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: Pro subscription required.
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
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'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
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: Retrieve Wingbits enrichment for multiple ICAO24 aircraft identifiers in one request, with aircraft details and requested versus fetched result counts.
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'
"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
"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).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
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'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
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: Check whether Wingbits aircraft enrichment is configured for World Monitor, using the configuration flag before requesting aircraft details or batch enrichment.
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).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
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'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
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: Retrieve the latest parsed USNI Fleet Tracker report, with article date, source link, fleet summary and cache status for understanding published naval activity.
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).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
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'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
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: Explore military bases by country, type, map bounds and zoom level, with base details and server-side clusters for geographic military infrastructure analysis.
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).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
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'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
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 returns one aircraft's live Wingbits ECS position by ICAO24 hex, with its schedule, delays and a Planespotters photo, cached 30 seconds.
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).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
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'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
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 returns weekly-seeded USPTO filings by key defense and dual-use assignees, filterable by CPC class and assignee, up to 100 rows.
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).
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
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'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
default:
description: Gateway or handler error response.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/GatewayError'
/api/military/v1/get-defense-industrial-base:
get:
tags:
- MilitaryService
summary: GetDefenseIndustrialBase
description: GetDefenseIndustrialBase returns annual military capacity and five-year arms-supplier dependency aggregates for one country. PRO-gated. Requires entitlement tier >= 1.
operationId: GetDefenseIndustrialBase
security:
- WorldMonitorKey: []
- ApiKeyHeader: []
- BearerAuth: []
parameters:
- name: country_code
in: query
description: ISO 3166-1 alpha-2 country code.
required: true
example: "US"
schema:
type: string
pattern: '^[A-Z]{2}$'
- 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:
"armsExportsTiv":
"available": true
"previousValue": 1.5
"previousYear": 1
"source": "example"
"value": 1.5
"armsImportsTiv":
"available": true
"previousValue": 1.5
"previousYear": 1
"source": "example"
"value": 1.5
"available": true
"countryCode": "US"
"expenditurePctGdp":
"available": true
"previousValue": 1.5
"previousYear": 1
"source": "example"
"value": 1.5
schema:
$ref: '#/components/schemas/GetDefenseIndustrialBaseResponse'
"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: PRO entitlement access denied.
headers:
X-Billing-Verification:
description: Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`).
schema:
type: string
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'
"503":
description: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
headers:
Retry-After:
description: Seconds to wait before retrying (1-60).
schema:
type: string
X-Billing-Verification:
description: Billing-verification state that produced this response (matches the body `code`).
schema:
type: string
X-Validation-Mode:
description: Present with value degraded when user API-key validation is temporarily unavailable.
schema:
type: string
X-RateLimit-Mode:
description: Present with value degraded when a fail-closed rate-limit dependency is unavailable.
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BillingVerificationError'
- $ref: '#/components/schemas/GatewayError'
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).
BearerAuth:
type: http
scheme: bearer
description: 'Bearer token: a Clerk-issued JWT for browser session flows, passed as Authorization: Bearer <token>.'
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.
BillingVerificationError:
type: object
description: "Returned with HTTP 503 when paid access cannot be confirmed right now: the billing provider is re-verifying a recently expired subscription, or the entitlement backend is unreachable. Retryable — honor Retry-After."
properties:
error:
type: string
description: Human-readable billing-verification failure reason.
code:
type: string
enum:
- renewal_verification_pending
- renewal_verification_failed
- entitlement_verification_unavailable
description: Machine-readable billing-verification state, mirrored in the X-Billing-Verification response header.
requiredTier:
type: integer
format: int32
description: Minimum entitlement tier required for this endpoint, when the denial came from a tier gate.
required:
- error
- code
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.
code:
type: string
enum:
- subscription_lapsed
description: Machine-readable denial code, present when the 403 is a billing-provider-confirmed subscription lapse (mirrored in the X-Billing-Verification response header).
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, uppercase.
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'
source:
type: string
description: Provider that supplied this observation (for example, "adsb.lol" or "wingbits").
required:
- id
description: MilitaryFlight represents a tracked military aircraft from the configured ADS-B providers.
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
pattern: ^[0-9a-fA-F]{6}$
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). Validation accepts up to 20, but the handler
de-duplicates, sorts, and processes at most the first 10 addresses -- anything beyond
that is silently discarded, so send at most 10 per call. The official browser client
caps its own requests at the same bound.
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.
GetDefenseIndustrialBaseRequest:
type: object
properties:
countryCode:
type: string
pattern: ^[A-Z]{2}$
description: ISO 3166-1 alpha-2 country code.
required:
- countryCode
GetDefenseIndustrialBaseResponse:
type: object
properties:
countryCode:
type: string
available:
type: boolean
expenditurePctGdp:
$ref: '#/components/schemas/DefenseIndustrialMetric'
expenditureUsd:
$ref: '#/components/schemas/DefenseIndustrialMetric'
personnel:
$ref: '#/components/schemas/DefenseIndustrialMetric'
armsExportsTiv:
$ref: '#/components/schemas/DefenseIndustrialMetric'
armsImportsTiv:
$ref: '#/components/schemas/DefenseIndustrialMetric'
suppliers:
type: array
items:
$ref: '#/components/schemas/ArmsSupplierDependency'
supplierHhi:
type: number
format: double
windowStartYear:
type: integer
format: int32
windowEndYear:
type: integer
format: int32
supplierSource:
type: string
fetchedAt:
type: string
description: Oldest timestamp among the source values served. Kept for compatibility.
industrialFetchedAt:
type: string
supplierFetchedAt:
type: string
supplierRetained:
type: boolean
supplierMappingCoverage:
type: number
format: double
DefenseIndustrialMetric:
type: object
properties:
available:
type: boolean
value:
type: number
format: double
year:
type: integer
format: int32
previousValue:
type: number
format: double
previousYear:
type: integer
format: int32
source:
type: string
ArmsSupplierDependency:
type: object
properties:
supplierIso2:
type: string
tivShare:
type: number
format: double