openapi: 3.1.0 info: title: InfrastructureService API version: 1.0.0 paths: /api/infrastructure/v1/list-internet-outages: get: tags: - InfrastructureService summary: ListInternetOutages description: ListInternetOutages retrieves detected internet outages from Cloudflare Radar. operationId: ListInternetOutages parameters: - name: start in: query description: Start of time range (inclusive), Unix epoch milliseconds. required: false schema: type: string format: int64 - name: end in: query description: End of time range (inclusive), Unix epoch milliseconds. required: false schema: type: string format: int64 - name: page_size in: query description: Maximum items per page. required: false schema: type: integer format: int32 - name: cursor in: query description: Cursor for next page. required: false schema: type: string - name: country in: query description: Optional country filter (ISO 3166-1 alpha-2). required: false schema: type: string responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/ListInternetOutagesResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/infrastructure/v1/list-service-statuses: get: tags: - InfrastructureService summary: ListServiceStatuses description: ListServiceStatuses retrieves operational status of monitored external services. operationId: ListServiceStatuses parameters: - name: status in: query description: Optional status filter. Returns only services in this state. required: false schema: type: string responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/ListServiceStatusesResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/infrastructure/v1/get-temporal-baseline: get: tags: - InfrastructureService summary: GetTemporalBaseline description: GetTemporalBaseline checks current activity count against stored baseline for anomaly detection. operationId: GetTemporalBaseline parameters: - name: type in: query description: 'Activity type: "military_flights", "vessels", "protests", "news", "ais_gaps", "satellite_fires".' required: false schema: type: string - name: region in: query description: Geographic region key, defaults to "global". required: false schema: type: string - name: count in: query description: Current observed count to compare against baseline. required: false schema: type: number format: double responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/GetTemporalBaselineResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/infrastructure/v1/record-baseline-snapshot: post: tags: - InfrastructureService summary: RecordBaselineSnapshot description: RecordBaselineSnapshot batch-updates baseline statistics using Welford's online algorithm. operationId: RecordBaselineSnapshot requestBody: content: application/json: schema: $ref: '#/components/schemas/RecordBaselineSnapshotRequest' required: true responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/RecordBaselineSnapshotResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/infrastructure/v1/get-cable-health: get: tags: - InfrastructureService summary: GetCableHealth description: GetCableHealth computes health status for submarine cables from NGA maritime warning signals. operationId: GetCableHealth responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/GetCableHealthResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/infrastructure/v1/list-temporal-anomalies: get: tags: - InfrastructureService summary: ListTemporalAnomalies description: ListTemporalAnomalies returns server-computed temporal anomalies for news and satellite_fires. operationId: ListTemporalAnomalies responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/ListTemporalAnomaliesResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: 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. 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. cursor: type: string description: Cursor for next page. 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' 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: Geographic region key, defaults to "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. RecordBaselineSnapshotRequest: type: object properties: updates: type: array items: $ref: '#/components/schemas/BaselineUpdate' description: RecordBaselineSnapshotRequest batch-updates baselines using Welford's online algorithm. BaselineUpdate: type: object properties: type: type: string minLength: 1 description: Activity type key. region: type: string description: Geographic region key, defaults to "global". count: type: number format: double description: Observed count value. required: - type description: BaselineUpdate is a single metric observation to incorporate into the running baseline. RecordBaselineSnapshotResponse: type: object properties: updated: type: integer format: int32 description: Number of baselines that were written. error: type: string description: Error message if the request was invalid. description: RecordBaselineSnapshotResponse reports how many baselines were successfully 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