Files
worldmonitor/docs/api/IntelligenceService.openapi.yaml
Elie Habib 248bdad6ae fix: move 5 path-param endpoints to query params for Vercel routing (#472)
Vercel's `api/[domain]/v1/[rpc].ts` captures one dynamic segment.
Path params like `/get-humanitarian-summary/SA` add an extra segment
that has no matching route file, causing 404 on both OPTIONS preflight
and direct requests. These endpoints were broken in production.

Changes:
- Remove `{param}` from 5 service.proto HTTP paths
- Add `(sebuf.http.query)` annotations to request message fields
- Update generated client/server code to use URLSearchParams
- Update OpenAPI specs (YAML + JSON) to declare query params
- Add early-return guards in 4 handlers for missing required params
- Add happy.worldmonitor.app to runtime.ts redirect hosts

Affected endpoints:
- GET /api/conflict/v1/get-humanitarian-summary?country_code=SA
- GET /api/economic/v1/get-fred-series?series_id=T10Y2Y&limit=120
- GET /api/market/v1/get-country-stock-index?country_code=US
- GET /api/intelligence/v1/get-country-intel-brief?country_code=US
- GET /api/military/v1/get-aircraft-details?icao24=a12345
2026-02-27 21:01:05 +04:00

663 lines
27 KiB
YAML

openapi: 3.1.0
info:
title: IntelligenceService API
version: 1.0.0
paths:
/api/intelligence/v1/get-risk-scores:
get:
tags:
- IntelligenceService
summary: GetRiskScores
description: GetRiskScores retrieves composite instability and strategic risk assessments.
operationId: GetRiskScores
parameters:
- name: region
in: query
description: Optional region filter. Empty returns all tracked regions.
required: false
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetRiskScoresResponse'
"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/intelligence/v1/get-pizzint-status:
get:
tags:
- IntelligenceService
summary: GetPizzintStatus
description: GetPizzintStatus retrieves Pentagon Pizza Index and GDELT tension pair data.
operationId: GetPizzintStatus
parameters:
- name: include_gdelt
in: query
description: Whether to include GDELT tension pairs in the response.
required: false
schema:
type: boolean
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetPizzintStatusResponse'
"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/intelligence/v1/classify-event:
post:
tags:
- IntelligenceService
summary: ClassifyEvent
description: ClassifyEvent classifies a real-world event using AI (Groq).
operationId: ClassifyEvent
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ClassifyEventRequest'
required: true
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ClassifyEventResponse'
"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/intelligence/v1/get-country-intel-brief:
get:
tags:
- IntelligenceService
summary: GetCountryIntelBrief
description: GetCountryIntelBrief generates an AI intelligence brief for a country (OpenRouter).
operationId: GetCountryIntelBrief
parameters:
- name: country_code
in: query
description: ISO 3166-1 alpha-2 country code.
required: true
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetCountryIntelBriefResponse'
"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/intelligence/v1/search-gdelt-documents:
get:
tags:
- IntelligenceService
summary: SearchGdeltDocuments
description: SearchGdeltDocuments searches the GDELT 2.0 Doc API for news articles.
operationId: SearchGdeltDocuments
parameters:
- name: query
in: query
description: Search query string.
required: false
schema:
type: string
- name: max_records
in: query
description: Maximum number of articles to return (1-250).
required: false
schema:
type: integer
format: int32
- name: timespan
in: query
description: Time span filter (e.g., "15min", "1h", "24h").
required: false
schema:
type: string
- name: tone_filter
in: query
description: |-
Tone filter appended to query (e.g., "tone>5" for positive, "tone<-5" for negative).
Left empty to skip tone filtering.
required: false
schema:
type: string
- name: sort
in: query
description: 'Sort mode: "DateDesc" (default), "ToneDesc", "ToneAsc", "HybridRel".'
required: false
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/SearchGdeltDocumentsResponse'
"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.
GetRiskScoresRequest:
type: object
properties:
region:
type: string
description: Optional region filter. Empty returns all tracked regions.
description: GetRiskScoresRequest specifies parameters for retrieving risk scores.
GetRiskScoresResponse:
type: object
properties:
ciiScores:
type: array
items:
$ref: '#/components/schemas/CiiScore'
strategicRisks:
type: array
items:
$ref: '#/components/schemas/StrategicRisk'
description: GetRiskScoresResponse contains composite risk scores and strategic assessments.
CiiScore:
type: object
properties:
region:
type: string
description: Region or country identifier.
staticBaseline:
type: number
maximum: 100
minimum: 0
format: double
description: Static baseline score (0-100).
dynamicScore:
type: number
maximum: 100
minimum: 0
format: double
description: Dynamic real-time score (0-100).
combinedScore:
type: number
maximum: 100
minimum: 0
format: double
description: Combined weighted score (0-100).
trend:
type: string
enum:
- TREND_DIRECTION_UNSPECIFIED
- TREND_DIRECTION_RISING
- TREND_DIRECTION_STABLE
- TREND_DIRECTION_FALLING
description: |-
TrendDirection represents the directional movement of a metric over time.
Used in markets, GDELT tension scores, and risk assessments.
components:
$ref: '#/components/schemas/CiiComponents'
computedAt:
type: integer
format: int64
description: 'Last computation time, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
description: CiiScore represents a Composite Instability Index score for a region or country.
CiiComponents:
type: object
properties:
newsActivity:
type: number
maximum: 100
minimum: 0
format: double
description: News activity signal contribution (0-100).
ciiContribution:
type: number
maximum: 100
minimum: 0
format: double
description: CII index contribution (0-100).
geoConvergence:
type: number
maximum: 100
minimum: 0
format: double
description: Geographic convergence score (0-100).
militaryActivity:
type: number
maximum: 100
minimum: 0
format: double
description: Military activity contribution (0-100).
description: CiiComponents represents the contributing factors to a CII score.
StrategicRisk:
type: object
properties:
region:
type: string
description: Country or region identifier.
level:
type: string
enum:
- SEVERITY_LEVEL_UNSPECIFIED
- SEVERITY_LEVEL_LOW
- SEVERITY_LEVEL_MEDIUM
- SEVERITY_LEVEL_HIGH
description: |-
SeverityLevel represents a three-tier severity classification used across domains.
Maps to existing TS unions: 'low' | 'medium' | 'high'.
score:
type: number
maximum: 100
minimum: 0
format: double
description: Risk score (0-100).
factors:
type: array
items:
type: string
description: Risk factors contributing to the assessment.
trend:
type: string
enum:
- TREND_DIRECTION_UNSPECIFIED
- TREND_DIRECTION_RISING
- TREND_DIRECTION_STABLE
- TREND_DIRECTION_FALLING
description: |-
TrendDirection represents the directional movement of a metric over time.
Used in markets, GDELT tension scores, and risk assessments.
description: StrategicRisk represents a strategic risk assessment for a country or region.
GetPizzintStatusRequest:
type: object
properties:
includeGdelt:
type: boolean
description: Whether to include GDELT tension pairs in the response.
description: GetPizzintStatusRequest specifies parameters for retrieving PizzINT and GDELT data.
GetPizzintStatusResponse:
type: object
properties:
pizzint:
$ref: '#/components/schemas/PizzintStatus'
tensionPairs:
type: array
items:
$ref: '#/components/schemas/GdeltTensionPair'
description: GetPizzintStatusResponse contains Pentagon Pizza Index and GDELT tension data.
PizzintStatus:
type: object
properties:
defconLevel:
type: integer
maximum: 5
minimum: 1
format: int32
description: DEFCON-style level (1-5).
defconLabel:
type: string
description: Human-readable DEFCON label.
aggregateActivity:
type: number
format: double
description: Aggregate activity score.
activeSpikes:
type: integer
format: int32
description: Number of active spike locations.
locationsMonitored:
type: integer
format: int32
description: Total monitored locations.
locationsOpen:
type: integer
format: int32
description: Currently open locations.
updatedAt:
type: integer
format: int64
description: 'Last data update time, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
dataFreshness:
type: string
enum:
- DATA_FRESHNESS_UNSPECIFIED
- DATA_FRESHNESS_FRESH
- DATA_FRESHNESS_STALE
description: DataFreshness represents how current the data is.
locations:
type: array
items:
$ref: '#/components/schemas/PizzintLocation'
description: PizzintStatus represents the Pentagon Pizza Index status (proxy for late-night DC activity).
PizzintLocation:
type: object
properties:
placeId:
type: string
description: Google Places ID.
name:
type: string
description: Location name.
address:
type: string
description: Street address.
currentPopularity:
type: integer
format: int32
description: Current popularity score (0-200+).
percentageOfUsual:
type: integer
format: int32
description: Percentage of usual activity. Zero if unavailable.
isSpike:
type: boolean
description: Whether activity constitutes a spike.
spikeMagnitude:
type: number
format: double
description: Spike magnitude above baseline. Zero if no spike.
dataSource:
type: string
description: Data source identifier.
recordedAt:
type: string
description: Recording timestamp as ISO 8601 string.
dataFreshness:
type: string
enum:
- DATA_FRESHNESS_UNSPECIFIED
- DATA_FRESHNESS_FRESH
- DATA_FRESHNESS_STALE
description: DataFreshness represents how current the data is.
isClosedNow:
type: boolean
description: Whether the location is currently closed.
lat:
type: number
format: double
description: Latitude of the location.
lng:
type: number
format: double
description: Longitude of the location.
description: PizzintLocation represents a single monitored pizza location near the Pentagon.
GdeltTensionPair:
type: object
properties:
id:
type: string
description: Pair identifier.
countries:
type: array
items:
type: string
description: Country pair (ISO 3166-1 alpha-2 codes).
label:
type: string
description: Human-readable label (e.g., "US-China").
score:
type: number
maximum: 100
minimum: 0
format: double
description: Tension score (0-100).
trend:
type: string
enum:
- TREND_DIRECTION_UNSPECIFIED
- TREND_DIRECTION_RISING
- TREND_DIRECTION_STABLE
- TREND_DIRECTION_FALLING
description: |-
TrendDirection represents the directional movement of a metric over time.
Used in markets, GDELT tension scores, and risk assessments.
changePercent:
type: number
format: double
description: Percentage change from previous period.
region:
type: string
description: Geographic region.
description: GdeltTensionPair represents a bilateral tension score between two countries from GDELT.
ClassifyEventRequest:
type: object
properties:
title:
type: string
minLength: 1
description: Event title or headline.
description:
type: string
description: Event description or body text.
source:
type: string
description: Event source (e.g., "reuters", "acled").
country:
type: string
description: Country context (ISO 3166-1 alpha-2).
required:
- title
description: ClassifyEventRequest specifies an event to classify using AI.
ClassifyEventResponse:
type: object
properties:
classification:
$ref: '#/components/schemas/EventClassification'
description: ClassifyEventResponse contains the AI-generated event classification.
EventClassification:
type: object
properties:
category:
type: string
description: Event category (e.g., "military", "economic", "social").
subcategory:
type: string
description: Event subcategory.
severity:
type: string
enum:
- SEVERITY_LEVEL_UNSPECIFIED
- SEVERITY_LEVEL_LOW
- SEVERITY_LEVEL_MEDIUM
- SEVERITY_LEVEL_HIGH
description: |-
SeverityLevel represents a three-tier severity classification used across domains.
Maps to existing TS unions: 'low' | 'medium' | 'high'.
confidence:
type: number
maximum: 1
minimum: 0
format: double
description: Classification confidence (0.0 to 1.0).
analysis:
type: string
description: Brief AI-generated analysis.
entities:
type: array
items:
type: string
description: Related entities identified.
description: EventClassification represents an AI-generated classification of a real-world event.
GetCountryIntelBriefRequest:
type: object
properties:
countryCode:
type: string
pattern: ^[A-Z]{2}$
description: ISO 3166-1 alpha-2 country code.
required:
- countryCode
description: GetCountryIntelBriefRequest specifies which country to generate a brief for.
GetCountryIntelBriefResponse:
type: object
properties:
countryCode:
type: string
description: ISO 3166-1 alpha-2 country code.
countryName:
type: string
description: Country name.
brief:
type: string
description: AI-generated intelligence brief text.
model:
type: string
description: AI model used for generation.
generatedAt:
type: integer
format: int64
description: 'Brief generation time, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
description: GetCountryIntelBriefResponse contains an AI-generated intelligence brief for a country.
SearchGdeltDocumentsRequest:
type: object
properties:
query:
type: string
minLength: 1
description: Search query string.
maxRecords:
type: integer
maximum: 250
minimum: 1
format: int32
description: Maximum number of articles to return (1-250).
timespan:
type: string
description: Time span filter (e.g., "15min", "1h", "24h").
toneFilter:
type: string
description: |-
Tone filter appended to query (e.g., "tone>5" for positive, "tone<-5" for negative).
Left empty to skip tone filtering.
sort:
type: string
description: 'Sort mode: "DateDesc" (default), "ToneDesc", "ToneAsc", "HybridRel".'
required:
- query
description: SearchGdeltDocumentsRequest specifies filters for searching GDELT news articles.
SearchGdeltDocumentsResponse:
type: object
properties:
articles:
type: array
items:
$ref: '#/components/schemas/GdeltArticle'
query:
type: string
description: Echo of the search query.
error:
type: string
description: Error message if the search failed.
description: SearchGdeltDocumentsResponse contains GDELT article search results.
GdeltArticle:
type: object
properties:
title:
type: string
description: Article headline.
url:
type: string
description: Article URL.
source:
type: string
description: Source domain name.
date:
type: string
description: Publication date string.
image:
type: string
description: Article image URL.
language:
type: string
description: Article language code.
tone:
type: number
format: double
description: GDELT tone score (negative = negative tone, positive = positive tone).
description: GdeltArticle represents a single article from the GDELT document API.