mirror of
https://github.com/koala73/worldmonitor.git
synced 2026-04-25 17:14:57 +02:00
6669d373cf
* feat: convert 52 API endpoints from POST to GET for edge caching Convert all cacheable sebuf RPC endpoints to HTTP GET with query/path parameters, enabling CDN edge caching to reduce costs. Flatten nested request types (TimeRange, PaginationRequest, BoundingBox) into scalar query params. Add path params for resource lookups (GetFredSeries, GetHumanitarianSummary, GetCountryStockIndex, GetCountryIntelBrief, GetAircraftDetails). Rewrite router with hybrid static/dynamic matching for path param support. Kept as POST: SummarizeArticle, ClassifyEvent, RecordBaselineSnapshot, GetAircraftDetailsBatch, RegisterInterest. Generated with sebuf v0.9.0 (protoc-gen-ts-client, protoc-gen-ts-server). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: add rate_limited field to market response protos The rateLimited field was hand-patched into generated files on main but never declared in the proto definitions. Regenerating wiped it out, breaking the build. Now properly defined in both ListEtfFlowsResponse and ListMarketQuotesResponse protos. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * chore: remove accidentally committed .planning files Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
663 lines
27 KiB
YAML
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/{country_code}:
|
|
get:
|
|
tags:
|
|
- IntelligenceService
|
|
summary: GetCountryIntelBrief
|
|
description: GetCountryIntelBrief generates an AI intelligence brief for a country (OpenRouter).
|
|
operationId: GetCountryIntelBrief
|
|
parameters:
|
|
- name: country_code
|
|
in: path
|
|
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.
|