docs/api/InfrastructureService.openapi.yaml
Rama main · réplica de lectura del repositorio original.
openapi: 3.1.0
info:
title: InfrastructureService API
version: 1.0.0
security:
- WorldMonitorKey: []
- ApiKeyHeader: []
servers:
- url: https://api.worldmonitor.app
paths:
/api/infrastructure/v1/list-internet-outages:
get:
tags:
- InfrastructureService
summary: ListInternetOutages
description: ListInternetOutages returns Cloudflare Radar outage annotations from the last 28 days, filterable by country and detection time, with severity and cause.
operationId: ListInternetOutages
parameters:
- name: start
in: query
description: Start of time range (inclusive), Unix epoch milliseconds.
required: false
example: "1717200000000"
schema:
type: string
format: int64
- name: end
in: query
description: End of time range (inclusive), Unix epoch milliseconds.
required: false
example: "1717200000000"
schema:
type: string
format: int64
- name: page_size
in: query
description: |-
Maximum items per page.
Accepted but currently ignored; no-op until this handler supports the parameter.
required: false
example: 25
schema:
type: integer
format: int32
- name: cursor
in: query
description: |-
Cursor for next page.
Accepted but currently ignored; no-op until this handler supports the parameter.
required: false
example: "next-page-token"
schema:
type: string
- name: country
in: query
description: Optional country filter (ISO 3166-1 alpha-2).
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:
"fetchedAt": 1717200000000
"outages":
- "categories":
- "example"
"cause": "example"
"country": "US"
"description": "Example WorldMonitor observation."
"detectedAt": 1717200000000
"id": "example-id"
"pagination":
"nextCursor": "next-page-token"
"totalCount": 1
schema:
$ref: '#/components/schemas/ListInternetOutagesResponse'
"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/infrastructure/v1/list-service-statuses:
get:
tags:
- InfrastructureService
summary: ListServiceStatuses
description: ListServiceStatuses checks the public status pages of 30 cloud, developer, communication, AI and SaaS services, sorted worst first and filterable by status.
operationId: ListServiceStatuses
parameters:
- name: status
in: query
description: Optional status filter. Returns only services in this state.
required: false
example: "SERVICE_OPERATIONAL_STATUS_OPERATIONAL"
schema:
type: string
enum:
- 'SERVICE_OPERATIONAL_STATUS_OPERATIONAL'
- 'SERVICE_OPERATIONAL_STATUS_DEGRADED'
- 'SERVICE_OPERATIONAL_STATUS_PARTIAL_OUTAGE'
- 'SERVICE_OPERATIONAL_STATUS_MAJOR_OUTAGE'
- 'SERVICE_OPERATIONAL_STATUS_MAINTENANCE'
- 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:
"statuses":
- "checkedAt": 1717200000000
"description": "Example WorldMonitor observation."
"id": "example-id"
"latencyMs": 1
"name": "WorldMonitor Analyst"
schema:
$ref: '#/components/schemas/ListServiceStatusesResponse'
"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/infrastructure/v1/get-temporal-baseline:
get:
tags:
- InfrastructureService
summary: GetTemporalBaseline
description: GetTemporalBaseline compares a count for signals like military flights, vessels or protests to its weekday and month baseline and flags z-score anomalies.
operationId: GetTemporalBaseline
parameters:
- name: type
in: query
description: 'Activity type: "military_flights", "vessels", "protests", "news", "ais_gaps", "satellite_fires".'
required: true
example: "military_flights"
schema:
type: string
enum:
- 'military_flights'
- 'vessels'
- 'protests'
- 'news'
- 'ais_gaps'
- 'satellite_fires'
- name: region
in: query
description: Only the global baseline is defined. Omitted or empty defaults to global.
required: false
example: "global"
schema:
type: string
enum:
- 'global'
- ''
- name: count
in: query
description: Current observed count to compare against baseline.
required: false
example: 1
schema:
type: number
format: double
- 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:
"anomaly":
"multiplier": 1.5
"severity": "watch"
"zScore": 42.5
"baseline":
"mean": 1.5
"sampleCount": 1
"stdDev": 1.5
"error": "example"
"learning": true
"sampleCount": 1
schema:
$ref: '#/components/schemas/GetTemporalBaselineResponse'
"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/infrastructure/v1/get-ip-geo:
get:
tags:
- InfrastructureService
summary: GetIpGeo
description: GetIpGeo returns the caller's ISO country code, region and city from Cloudflare and Vercel edge headers, with XX when unknown. Responses are never cached.
operationId: GetIpGeo
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:
"city": "example"
"country": "US"
"region": "example"
schema:
$ref: '#/components/schemas/GetIpGeoResponse'
"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/infrastructure/v1/reverse-geocode:
get:
tags:
- InfrastructureService
summary: ReverseGeocode
description: ReverseGeocode resolves latitude and longitude to a country name, ISO code and display name via OpenStreetMap Nominatim, with results cached for 7 days.
operationId: ReverseGeocode
parameters:
- name: lat
in: query
description: Latitude of the point to reverse geocode.
required: false
example: 40.7128
schema:
type: number
format: double
- name: lon
in: query
description: Longitude of the point to reverse geocode.
required: false
example: -74.006
schema:
type: number
format: double
- 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:
"code": "example"
"country": "US"
"displayName": "WorldMonitor Analyst"
"error": "example"
schema:
$ref: '#/components/schemas/ReverseGeocodeResponse'
"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/infrastructure/v1/get-bootstrap-data:
get:
tags:
- InfrastructureService
summary: GetBootstrapData
description: GetBootstrapData returns cached dashboard datasets as JSON strings in one call, for a fast or slow tier or named keys, and lists any keys missing from cache.
operationId: GetBootstrapData
parameters:
- name: tier
in: query
description: 'Fixed public tier: fast or slow. Leave empty when selecting a key.'
required: false
example: "fast"
schema:
type: string
pattern: '^(fast|slow)$'
- name: keys
in: query
description: |-
Registered bootstrap keys, for example insights. Repeat the parameter for
several fast/slow keys. Omit when using tier.
required: false
style: form
explode: true
example:
- "example"
schema:
type: array
maxItems: 100
items:
type: string
minLength: 1
- 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:
"data":
"exampleKey": "example"
"missing":
- "example"
schema:
$ref: '#/components/schemas/GetBootstrapDataResponse'
"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/infrastructure/v1/record-baseline-snapshot:
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}$"
deprecated: true
tags:
- InfrastructureService
summary: RecordBaselineSnapshot
description: RecordBaselineSnapshot is deprecated and DISABLED. Every call is rejected with HTTP 403 because client-supplied counts cannot safely update shared baselines.
operationId: RecordBaselineSnapshot
requestBody:
content:
application/json:
example:
"updates":
- "count": 1
"region": "global"
"type": "military_flights"
schema:
$ref: '#/components/schemas/RecordBaselineSnapshotRequest'
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:
"error": "example"
"updated": 1
schema:
$ref: '#/components/schemas/RecordBaselineSnapshotResponse'
"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/infrastructure/v1/get-cable-health:
get:
tags:
- InfrastructureService
summary: GetCableHealth
description: GetCableHealth rates submarine cables as ok, degraded or fault by matching fault and repair-ship keywords in NGA navigational warnings, refreshed each 30 min.
operationId: GetCableHealth
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:
"cables":
"exampleKey":
"confidence": 0.82
"evidence":
- "source": "example"
"summary": "Example WorldMonitor observation."
"ts": 1
"lastUpdated": 1
"score": 42.5
"status": "CABLE_HEALTH_STATUS_OK"
"generatedAt": 1717200000000
schema:
$ref: '#/components/schemas/GetCableHealthResponse'
"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/infrastructure/v1/list-temporal-anomalies:
get:
tags:
- InfrastructureService
summary: ListTemporalAnomalies
description: ListTemporalAnomalies returns computed news and satellite-fire anomalies with scores, observed values, baselines, tracked signal types, and computation time.
operationId: ListTemporalAnomalies
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:
"anomalies":
- "currentCount": 1
"expectedCount": 1
"message": "Example WorldMonitor observation."
"multiplier": 1.5
"region": "example"
"computedAt": "2026-01-15T12:00:00Z"
"trackedTypes":
- "example"
schema:
$ref: '#/components/schemas/ListTemporalAnomaliesResponse'
"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/infrastructure/v1/list-internet-ddos-attacks:
get:
tags:
- InfrastructureService
summary: ListInternetDdosAttacks
description: ListInternetDdosAttacks returns Cloudflare Radar layer 3 DDoS summaries for the last 7 days by protocol and attack vector, with the top target locations.
operationId: ListInternetDdosAttacks
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:
"dateRangeEnd": "2026-01-15"
"dateRangeStart": "2026-01-15"
"protocol":
- "label": "example"
"percentage": 42.5
"topTargetLocations":
- "countryCode": "US"
"countryName": "US"
"latitude": 40.7128
"longitude": -74.006
"percentage": 42.5
"vector":
- "label": "example"
"percentage": 42.5
schema:
$ref: '#/components/schemas/ListInternetDdosAttacksResponse'
"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/infrastructure/v1/list-internet-traffic-anomalies:
get:
tags:
- InfrastructureService
summary: ListInternetTrafficAnomalies
description: ListInternetTrafficAnomalies returns up to 100 Cloudflare Radar traffic anomalies from the last 7 days with ASN and location, filterable by country code.
operationId: ListInternetTrafficAnomalies
parameters:
- name: country
in: query
description: Optional ISO 3166-1 alpha-2 country code filter.
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:
"anomalies":
- "asn": "example"
"asnName": "WorldMonitor Analyst"
"endDate": 1717200000000
"latitude": 40.7128
"locationCode": "US"
"totalCount": 1
schema:
$ref: '#/components/schemas/ListInternetTrafficAnomaliesResponse'
"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'
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.
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.
ListInternetOutagesRequest:
type: object
properties:
start:
type: integer
format: int64
description: 'Start of time range (inclusive), Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
end:
type: integer
format: int64
description: 'End of time range (inclusive), Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
pageSize:
type: integer
format: int32
description: |-
Maximum items per page.
Accepted but currently ignored; no-op until this handler supports the parameter.
cursor:
type: string
description: |-
Cursor for next page.
Accepted but currently ignored; no-op until this handler supports the parameter.
country:
type: string
description: Optional country filter (ISO 3166-1 alpha-2).
description: ListInternetOutagesRequest specifies filters for retrieving internet outages.
ListInternetOutagesResponse:
type: object
properties:
outages:
type: array
items:
$ref: '#/components/schemas/InternetOutage'
pagination:
$ref: '#/components/schemas/PaginationResponse'
fetchedAt:
type: integer
format: int64
description: |-
When the seeder last fetched the outage list from Cloudflare Radar, Unix
epoch milliseconds. A retained payload keeps its original time; 0 when unknown. Warning: Values > 2^53 may lose precision in JavaScript
description: ListInternetOutagesResponse contains internet outages matching the request.
InternetOutage:
type: object
properties:
id:
type: string
minLength: 1
description: Unique outage identifier.
title:
type: string
description: Outage title.
link:
type: string
description: URL to the outage report.
description:
type: string
description: Outage description.
detectedAt:
type: integer
format: int64
description: 'Detection time, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
country:
type: string
description: Affected country (ISO 3166-1 alpha-2).
region:
type: string
description: Affected region within the country.
location:
$ref: '#/components/schemas/GeoCoordinates'
severity:
type: string
enum:
- OUTAGE_SEVERITY_UNSPECIFIED
- OUTAGE_SEVERITY_PARTIAL
- OUTAGE_SEVERITY_MAJOR
- OUTAGE_SEVERITY_TOTAL
description: |-
OutageSeverity represents the severity of an internet outage.
Maps to TS union: 'partial' | 'major' | 'total'.
categories:
type: array
items:
type: string
description: Affected infrastructure categories.
cause:
type: string
description: Root cause, if determined.
outageType:
type: string
description: Outage type classification.
endedAt:
type: integer
format: int64
description: 'End time of the outage, as Unix epoch milliseconds. Zero if ongoing.. Warning: Values > 2^53 may lose precision in JavaScript'
required:
- id
description: InternetOutage represents a detected internet outage event from Cloudflare Radar.
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.
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.
ListServiceStatusesRequest:
type: object
properties:
status:
type: string
enum:
- SERVICE_OPERATIONAL_STATUS_UNSPECIFIED
- SERVICE_OPERATIONAL_STATUS_OPERATIONAL
- SERVICE_OPERATIONAL_STATUS_DEGRADED
- SERVICE_OPERATIONAL_STATUS_PARTIAL_OUTAGE
- SERVICE_OPERATIONAL_STATUS_MAJOR_OUTAGE
- SERVICE_OPERATIONAL_STATUS_MAINTENANCE
description: ServiceOperationalStatus represents the current status of a service.
description: ListServiceStatusesRequest specifies filters for retrieving service statuses.
ListServiceStatusesResponse:
type: object
properties:
statuses:
type: array
items:
$ref: '#/components/schemas/ServiceStatus'
description: ListServiceStatusesResponse contains service operational statuses.
ServiceStatus:
type: object
properties:
id:
type: string
description: Service identifier.
name:
type: string
description: Service display name.
status:
type: string
enum:
- SERVICE_OPERATIONAL_STATUS_UNSPECIFIED
- SERVICE_OPERATIONAL_STATUS_OPERATIONAL
- SERVICE_OPERATIONAL_STATUS_DEGRADED
- SERVICE_OPERATIONAL_STATUS_PARTIAL_OUTAGE
- SERVICE_OPERATIONAL_STATUS_MAJOR_OUTAGE
- SERVICE_OPERATIONAL_STATUS_MAINTENANCE
description: ServiceOperationalStatus represents the current status of a service.
description:
type: string
description: Status description.
url:
type: string
description: Service URL or homepage.
checkedAt:
type: integer
format: int64
description: 'Last status check time, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
latencyMs:
type: integer
format: int32
description: Response latency in milliseconds.
description: ServiceStatus represents the operational status of a monitored external service.
GetTemporalBaselineRequest:
type: object
properties:
type:
type: string
minLength: 1
description: 'Activity type: "military_flights", "vessels", "protests", "news", "ais_gaps", "satellite_fires".'
region:
type: string
description: Only the global baseline is defined. Omitted or empty defaults to global.
enum:
- 'global'
- ''
count:
type: number
format: double
description: Current observed count to compare against baseline.
required:
- type
description: GetTemporalBaselineRequest checks current activity count against stored baseline.
GetTemporalBaselineResponse:
type: object
properties:
anomaly:
$ref: '#/components/schemas/BaselineAnomaly'
baseline:
$ref: '#/components/schemas/BaselineStats'
learning:
type: boolean
description: True if insufficient samples have been collected.
sampleCount:
type: integer
format: int32
description: Current number of samples stored.
samplesNeeded:
type: integer
format: int32
description: Minimum samples required before anomaly detection activates.
error:
type: string
description: Error message if request was invalid.
description: GetTemporalBaselineResponse returns anomaly info or learning status.
BaselineAnomaly:
type: object
properties:
zScore:
type: number
format: double
description: Number of standard deviations from the mean.
severity:
type: string
description: 'Severity label: "critical", "high", "medium", "normal".'
multiplier:
type: number
format: double
description: Ratio of current count to baseline mean.
description: BaselineAnomaly describes a detected deviation from historical baseline.
BaselineStats:
type: object
properties:
mean:
type: number
format: double
description: Running mean of observed counts.
stdDev:
type: number
format: double
description: Standard deviation derived from Welford's M2.
sampleCount:
type: integer
format: int32
description: Number of samples incorporated so far.
description: BaselineStats contains the running statistics for a baseline key.
GetIpGeoRequest:
type: object
description: GetIpGeoRequest defined for future parameters (e.g., specific IP).
GetIpGeoResponse:
type: object
properties:
country:
type: string
description: ISO 3166-1 alpha-2 country code.
region:
type: string
description: Region or city (if available).
city:
type: string
description: GetIpGeoResponse contains geographic information derived from the request IP.
ReverseGeocodeRequest:
type: object
properties:
lat:
type: number
format: double
description: Latitude of the point to reverse geocode.
lon:
type: number
format: double
description: Longitude of the point to reverse geocode.
description: ReverseGeocodeRequest parameters for coordinate-to-address lookups.
ReverseGeocodeResponse:
type: object
properties:
country:
type: string
description: Human-readable country name.
code:
type: string
description: ISO country code.
displayName:
type: string
description: Full display name/address.
error:
type: string
description: Optional error message.
description: ReverseGeocodeResponse containing the resolved location details.
GetBootstrapDataRequest:
type: object
properties:
tier:
type: string
pattern: ^(fast|slow)$
description: 'Fixed public tier: fast or slow. Leave empty when selecting a key.'
keys:
type: array
items:
type: string
maxItems: 100
description: |-
Registered bootstrap keys, for example insights. Repeat the parameter for
several fast/slow keys. Omit when using tier.
maxItems: 100
description: |-
GetBootstrapDataRequest selects a fixed tier or registered bootstrap keys.
Exactly one selector is required: use tier OR keys, never both.
Several keys are accepted when every key belongs to the fast or slow tier;
an on-demand key must be requested alone. Empty, unknown and mixed
selectors return HTTP 400.
GetBootstrapDataResponse:
type: object
properties:
data:
type: object
additionalProperties:
type: string
description: Map of keys to JSON-encoded data strings.
missing:
type: array
items:
type: string
description: List of keys that were not found in cache.
description: GetBootstrapDataResponse containing pooled data objects.
DataEntry:
type: object
properties:
key:
type: string
value:
type: string
RecordBaselineSnapshotRequest:
type: object
properties:
updates:
type: array
items:
$ref: '#/components/schemas/BaselineUpdate'
description: RecordBaselineSnapshotRequest is retained for compatibility. Client writes are disabled.
BaselineUpdate:
type: object
properties:
type:
type: string
minLength: 1
description: Activity type key.
region:
type: string
description: Geographic region key. Only the global baseline is defined.
const: global
count:
type: number
format: double
description: Submitted count. The disabled endpoint does not persist this value.
required:
- type
description: BaselineUpdate retains the request shape of the disabled compatibility endpoint.
RecordBaselineSnapshotResponse:
type: object
properties:
updated:
type: integer
format: int32
description: Always zero because the endpoint is disabled.
error:
type: string
description: Error message if the request was invalid.
description: RecordBaselineSnapshotResponse reports that no client baseline was updated.
GetCableHealthRequest:
type: object
description: GetCableHealthRequest requests the current health status of all monitored submarine cables.
GetCableHealthResponse:
type: object
properties:
generatedAt:
type: integer
format: int64
description: 'Generation timestamp, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
cables:
type: object
additionalProperties:
$ref: '#/components/schemas/CableHealthRecord'
description: Health records keyed by cable identifier.
description: GetCableHealthResponse contains health status for submarine cables with active signals.
CablesEntry:
type: object
properties:
key:
type: string
value:
$ref: '#/components/schemas/CableHealthRecord'
CableHealthRecord:
type: object
properties:
status:
type: string
enum:
- CABLE_HEALTH_STATUS_UNSPECIFIED
- CABLE_HEALTH_STATUS_OK
- CABLE_HEALTH_STATUS_DEGRADED
- CABLE_HEALTH_STATUS_FAULT
description: CableHealthStatus represents the computed health status of a submarine cable.
score:
type: number
format: double
description: Composite health score (0.0 = healthy, 1.0 = confirmed fault).
confidence:
type: number
format: double
description: Confidence in the health assessment (0.0–1.0).
lastUpdated:
type: integer
format: int64
description: 'Last signal update time, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
evidence:
type: array
items:
$ref: '#/components/schemas/CableHealthEvidence'
description: CableHealthRecord contains the computed health status and supporting evidence for a cable.
CableHealthEvidence:
type: object
properties:
source:
type: string
description: Evidence source (e.g. "NGA").
summary:
type: string
description: Human-readable summary of the evidence.
ts:
type: integer
format: int64
description: 'Evidence timestamp, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
description: CableHealthEvidence represents a single piece of evidence supporting a health assessment.
ListTemporalAnomaliesRequest:
type: object
ListTemporalAnomaliesResponse:
type: object
properties:
anomalies:
type: array
items:
$ref: '#/components/schemas/TemporalAnomaly'
trackedTypes:
type: array
items:
type: string
computedAt:
type: string
TemporalAnomaly:
type: object
properties:
type:
type: string
region:
type: string
currentCount:
type: integer
format: int32
expectedCount:
type: integer
format: int32
zScore:
type: number
format: double
severity:
type: string
multiplier:
type: number
format: double
message:
type: string
ListInternetDdosAttacksRequest:
type: object
description: ListInternetDdosAttacksRequest specifies filters for retrieving DDoS attack summaries.
ListInternetDdosAttacksResponse:
type: object
properties:
protocol:
type: array
items:
$ref: '#/components/schemas/DdosAttackSummaryEntry'
vector:
type: array
items:
$ref: '#/components/schemas/DdosAttackSummaryEntry'
dateRangeStart:
type: string
description: ISO 8601 start of the data window.
dateRangeEnd:
type: string
description: ISO 8601 end of the data window.
topTargetLocations:
type: array
items:
$ref: '#/components/schemas/DdosLocationHit'
description: ListInternetDdosAttacksResponse contains DDoS attack protocol and vector breakdowns.
DdosAttackSummaryEntry:
type: object
properties:
label:
type: string
description: Protocol or vector name (e.g. "TCP", "UDP", "networkFlood").
percentage:
type: number
format: float
description: Percentage share of total DDoS traffic (0–100).
description: DdosAttackSummaryEntry represents a single protocol or vector and its share of DDoS traffic.
DdosLocationHit:
type: object
properties:
countryCode:
type: string
description: ISO 3166-1 alpha-2 country code.
countryName:
type: string
description: Country display name.
percentage:
type: number
format: float
description: Percentage share of total DDoS traffic targeting this location (0-100).
latitude:
type: number
format: float
description: Latitude of the target location.
longitude:
type: number
format: float
description: Longitude of the target location.
description: DdosLocationHit represents a top DDoS target location with geo coordinates.
ListInternetTrafficAnomaliesRequest:
type: object
properties:
country:
type: string
description: Optional ISO 3166-1 alpha-2 country code filter.
description: ListInternetTrafficAnomaliesRequest specifies filters for traffic anomalies.
ListInternetTrafficAnomaliesResponse:
type: object
properties:
anomalies:
type: array
items:
$ref: '#/components/schemas/TrafficAnomaly'
totalCount:
type: integer
format: int32
description: Total anomaly count before filtering.
description: ListInternetTrafficAnomaliesResponse contains detected traffic anomalies.
TrafficAnomaly:
type: object
properties:
uuid:
type: string
description: Unique identifier for the anomaly.
type:
type: string
description: Anomaly type (e.g. "ANOMALY_DNS", "ANOMALY_BGP").
status:
type: string
description: Current status ("ONGOING" or "HISTORICAL").
startDate:
type: integer
format: int64
description: 'Start of the anomaly, Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
endDate:
type: integer
format: int64
description: 'End of the anomaly, Unix epoch milliseconds. Zero if ongoing.. Warning: Values > 2^53 may lose precision in JavaScript'
asn:
type: string
description: Autonomous System Number affected.
asnName:
type: string
description: ASN display name.
locationCode:
type: string
description: ISO 3166-1 alpha-2 country code.
locationName:
type: string
description: Country display name.
latitude:
type: number
format: float
description: Latitude of the affected location.
longitude:
type: number
format: float
description: Longitude of the affected location.
description: TrafficAnomaly represents an anomalous traffic pattern detected by Cloudflare Radar.