Skip to main content
The IntelligenceService provides APIs for cross-domain intelligence synthesis including risk scores, PizzINT monitoring, GDELT analysis, and AI-powered event classification and country intelligence briefs.

Base Path

/api/intelligence/v1

GetRiskScores

Retrieves composite instability and strategic risk assessments for regions. Endpoint: GET /api/intelligence/v1/get-risk-scores

Request Parameters

region
string
Optional region filter. Empty returns all tracked regions.

Response

cii_scores
CiiScore[]
Composite Instability Index scores
strategic_risks
StrategicRisk[]
Strategic risk assessments

Example Request

curl "https://your-domain.com/api/intelligence/v1/get-risk-scores?region=middle-east"

GetPizzintStatus

Retrieves Pentagon Pizza Index and GDELT tension pair data for early warning indicators. Endpoint: GET /api/intelligence/v1/get-pizzint-status

Request Parameters

include_gdelt
bool
Whether to include GDELT tension pairs in the response

Response

pizzint
PizzintStatus
Pentagon Pizza Index status
tension_pairs
GdeltTensionPair[]
GDELT bilateral tension pairs

Example Request

curl "https://your-domain.com/api/intelligence/v1/get-pizzint-status?include_gdelt=true"

ClassifyEvent

Classifies a real-world event using AI (Groq) to determine event type, severity, and context. Endpoint: POST /api/intelligence/v1/classify-event

Request Body

event_description
string
required
Description of the event to classify
context
string
Additional contextual information

Response

classification
string
AI-generated event classification
severity
string
Assessed severity level
confidence
double
Classification confidence score (0-1)
model
string
AI model used for classification
reasoning
string
Explanation of the classification

Example Request

curl -X POST "https://your-domain.com/api/intelligence/v1/classify-event" \
  -H "Content-Type: application/json" \
  -d '{
    "event_description": "Large explosion reported near military facility in Damascus",
    "context": "Ongoing regional tensions between Israel and Syria"
  }'

Example Response

{
  "classification": "Military Strike",
  "severity": "High",
  "confidence": 0.87,
  "model": "llama-3.1-70b-versatile",
  "reasoning": "The event description indicates a targeted military action near a strategic facility, with high regional implications given the stated context of Israel-Syria tensions. The severity is assessed as high due to the potential for escalation."
}

GetCountryIntelBrief

Generates an AI intelligence brief for a country using OpenRouter, synthesizing multiple data sources. Endpoint: GET /api/intelligence/v1/get-country-intel-brief

Request Parameters

country_code
string
required
ISO 3166-1 alpha-2 country code (e.g., “YE”, “SD”, “UA”)

Response

country_code
string
ISO 3166-1 alpha-2 country code
country_name
string
Country name
brief
string
AI-generated intelligence brief text
model
string
AI model used for generation
generated_at
int64
Brief generation time, as Unix epoch milliseconds

Example Request

curl "https://your-domain.com/api/intelligence/v1/get-country-intel-brief?country_code=UA"

Example Response

{
  "country_code": "UA",
  "country_name": "Ukraine",
  "brief": "# Ukraine Intelligence Brief\n\n## Security Situation\nThe security environment remains highly dynamic with ongoing military operations in eastern regions. ACLED data shows 347 conflict events in the past 30 days, with concentration in Donetsk and Luhansk oblasts...\n\n## Humanitarian Impact\nUCDP reports indicate 892 fatalities over the reference period. Displacement continues to affect approximately 5.1 million internally displaced persons...\n\n## Strategic Assessment\nMilitary posture analysis indicates sustained defensive operations with periodic counteroffensive activities. Air defense systems remain active with 23 intercepts recorded in the past week...",
  "model": "anthropic/claude-3.5-sonnet",
  "generated_at": 1709251200000
}

SearchGdeltDocuments

Searches the GDELT 2.0 Doc API for news articles matching specific criteria. Endpoint: GET /api/intelligence/v1/search-gdelt-documents

Request Parameters

query
string
required
Search query string
country
string
Optional country filter (ISO 3166-1 alpha-2)
start_date
string
Start date in YYYYMMDDHHMMSS format
end_date
string
End date in YYYYMMDDHHMMSS format
max_records
int32
Maximum number of records to return (default: 250)

Response

documents
GdeltDocument[]
Matching news articles from GDELT
total_results
int32
Total number of matching documents

Example Request

curl "https://your-domain.com/api/intelligence/v1/search-gdelt-documents?query=military+exercises&country=CN&max_records=50"

Example Response

{
  "documents": [
    {
      "url": "https://example.com/article-123",
      "title": "China conducts large-scale military drills near Taiwan",
      "seendate": "20240301120000",
      "socialimage": "https://example.com/images/drill.jpg",
      "domain": "example.com",
      "language": "eng",
      "sourcecountry": "US"
    }
  ],
  "total_results": 847
}

Use Cases

Risk Assessment

Combine GetRiskScores with GetCountryIntelBrief to get comprehensive risk analysis for a region.

Event Monitoring

Use SearchGdeltDocuments to find relevant news articles, then ClassifyEvent to automatically categorize breaking developments.

Early Warning

Monitor GetPizzintStatus for anomalous activity indicators that may signal heightened security situations.

Build docs developers (and LLMs) love