{
 "openapi": "3.1.0",
 "info": {
  "title": "RiskPulse API",
  "description": "Global risk intelligence API. AI-synthesized travel safety alerts, country risk profiles, sanctions screening, business risk analysis, supply chain disruption intelligence, nomad visa/tax guidance, expat risk assessment, and emergency evacuation protocols. Covers 195 countries with real-time data. Serves travel risk managers, insurance brokers, compliance teams, expats, and digital nomads. Travel insurance affiliates (SafetyWing, WorldNomads) included in relevant endpoints. All endpoints support any language via ?lang=. Pricing: $0.08–$0.20 USDC/call via x402 micropayment.",
  "version": "1.2.0",
  "contact": {
   "url": "https://riskpulse.theaslangroupllc.com"
  }
 },
 "servers": [
  {
   "url": "https://riskpulse.theaslangroupllc.com"
  }
 ],
 "components": {
  "securitySchemes": {
   "x402": {
    "type": "apiKey",
    "in": "header",
    "name": "PAYMENT-SIGNATURE",
    "description": "x402 payment signature. Omit to receive a 402 with payment requirements."
   }
  }
 },
 "paths": {
  "/api/risk/country": {
   "get": {
    "summary": "Country risk profile",
    "description": "Comprehensive risk profile across 6 dimensions: political, economic, security, health, natural disaster, and legal/regulatory. Powered by World Bank governance indicators and real-time intelligence.",
    "operationId": "riskCountry",
    "security": [
     {
      "x402": []
     }
    ],
    "parameters": [
     {
      "name": "country",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Country name (e.g. Mexico, Thailand, Nigeria)"
     },
     {
      "name": "lang",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Country risk profile with dimensional scores and recommendations"
     },
     "402": {
      "description": "Payment required"
     }
    },
    "x-price-usd": 0.1,
    "x-agent-use-case": "on-demand",
    "x-agent-chaining": "Comprehensive country profile — run first for any country-specific workflow; chain to /api/risk/travel for traveler view or /api/risk/business for enterprise view"
   }
  },
  "/api/risk/travel": {
   "get": {
    "summary": "Travel safety assessment",
    "description": "Advisory level (1-4), crime and health risks, entry requirements, safe/avoid areas, emergency contacts, and travel insurance recommendations.",
    "operationId": "riskTravel",
    "security": [
     {
      "x402": []
     }
    ],
    "parameters": [
     {
      "name": "country",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "nationality",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Traveler nationality (default: US)"
     },
     {
      "name": "lang",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Travel safety assessment with insurance referrals"
     },
     "402": {
      "description": "Payment required"
     }
    },
    "x-price-usd": 0.08,
    "x-agent-use-case": "on-demand",
    "x-agent-chaining": "Run before any trip booking; pairs with TravelPulse /api/travel/insurance; SafetyWing + WorldNomads insurance links auto-appended in response"
   }
  },
  "/api/risk/business": {
   "get": {
    "summary": "Business risk analysis",
    "description": "Market entry risk assessment covering regulatory quality, corruption, rule of law, IP protection, contract enforcement, profit repatriation, and due diligence checklist.",
    "operationId": "riskBusiness",
    "security": [
     {
      "x402": []
     }
    ],
    "parameters": [
     {
      "name": "country",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "industry",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "lang",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Business risk analysis with market entry guidance"
     },
     "402": {
      "description": "Payment required"
     }
    },
    "x-price-usd": 0.1,
    "x-agent-use-case": "on-demand",
    "x-agent-chaining": "Pairs with /api/risk/sanctions for compliance check; follow with /api/risk/supply for supply chain exposure; combine with FilingsPulse for due diligence workflows"
   }
  },
  "/api/risk/compare": {
   "get": {
    "summary": "Country risk comparison",
    "description": "Side-by-side risk comparison of 2-4 countries — safety, stability, business environment, expat friendliness, category winners, and overall ranking.",
    "operationId": "riskCompare",
    "security": [
     {
      "x402": []
     }
    ],
    "parameters": [
     {
      "name": "countries",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Comma-separated country names (e.g. Mexico,Colombia,Costa Rica)"
     },
     {
      "name": "lang",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Side-by-side country risk comparison"
     },
     "402": {
      "description": "Payment required"
     }
    },
    "x-price-usd": 0.1,
    "x-agent-use-case": "on-demand",
    "x-agent-chaining": "Risk comparison between destinations — run before trip planning to pick safer alternative; chain to /api/risk/travel for selected destination"
   }
  },
  "/api/risk/expat": {
   "get": {
    "summary": "Expat living guide",
    "description": "Comprehensive expat guide covering safety, healthcare quality, cost of living, visa ease, language barrier, expat community, best cities, challenges, and travel insurance links.",
    "operationId": "riskExpat",
    "security": [
     {
      "x402": []
     }
    ],
    "parameters": [
     {
      "name": "country",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "from",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Country of origin (default: US)"
     },
     {
      "name": "lang",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Expat living guide with insurance referrals"
     },
     "402": {
      "description": "Payment required"
     }
    },
    "x-price-usd": 0.1,
    "x-agent-use-case": "on-demand",
    "x-agent-chaining": "Pairs with ImmigrationPulse /api/status for visa; pairs with RemittancePulse for cross-border payments; SafetyWing expat insurance link auto-appended"
   }
  },
  "/api/risk/alerts": {
   "get": {
    "summary": "Situational security alerts",
    "description": "Real-time security awareness for a current location with actionable guidance.",
    "operationId": "riskAlerts",
    "security": [
     {
      "x402": []
     }
    ],
    "parameters": [
     {
      "name": "location",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Location"
     },
     {
      "name": "lang",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Response language (default en)"
     }
    ],
    "responses": {
     "200": {
      "description": "Situational security alerts"
     },
     "402": {
      "description": "Payment required"
     }
    },
    "x-price-usd": 0.1,
    "x-agent-use-case": "real-time",
    "x-agent-chaining": "Pairs with /api/risk/evac when the situation is deteriorating; combine with /api/risk/country for baseline risk context"
   }
  },
  "/api/risk/evac": {
   "get": {
    "summary": "Evacuation plan",
    "description": "48-hour plan with airports, embassy contacts, cash, documents, and transport options.",
    "operationId": "riskEvac",
    "security": [
     {
      "x402": []
     }
    ],
    "parameters": [
     {
      "name": "location",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Location"
     },
     {
      "name": "nationality",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Nationality"
     },
     {
      "name": "lang",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Response language (default en)"
     }
    ],
    "responses": {
     "200": {
      "description": "Evacuation plan"
     },
     "402": {
      "description": "Payment required"
     }
    },
    "x-price-usd": 0.1,
    "x-agent-use-case": "on-demand",
    "x-agent-chaining": "Chain from /api/risk/alerts once a location crosses Level 3-4; travel/expat insurance links auto-appended"
   }
  },
  "/api/risk/nomad": {
   "get": {
    "summary": "Digital nomad score",
    "description": "7-dimension ranking: internet, visa, cost, safety, healthcare, community, QoL.",
    "operationId": "riskNomad",
    "security": [
     {
      "x402": []
     }
    ],
    "parameters": [
     {
      "name": "country",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Country"
     },
     {
      "name": "city",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "City"
     },
     {
      "name": "lang",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Response language (default en)"
     }
    ],
    "responses": {
     "200": {
      "description": "Digital nomad score"
     },
     "402": {
      "description": "Payment required"
     }
    },
    "x-price-usd": 0.1,
    "x-agent-use-case": "on-demand",
    "x-agent-chaining": "Pairs with /api/risk/expat for a full relocation-risk workflow"
   }
  },
  "/api/risk/sanctions": {
   "get": {
    "summary": "Sanctions exposure analysis",
    "description": "OFAC, EU, and UN sanctions exposure with official screening resources.",
    "operationId": "riskSanctions",
    "security": [
     {
      "x402": []
     }
    ],
    "parameters": [
     {
      "name": "entity",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Entity name"
     },
     {
      "name": "entity_type",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Entity type (person, company, vessel)"
     },
     {
      "name": "lang",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Response language (default en)"
     }
    ],
    "responses": {
     "200": {
      "description": "Sanctions exposure analysis"
     },
     "402": {
      "description": "Payment required"
     }
    },
    "x-price-usd": 0.15,
    "x-agent-use-case": "on-demand",
    "x-agent-chaining": "Pairs with /api/risk/business for market-entry compliance workflows"
   }
  },
  "/api/risk/supply": {
   "get": {
    "summary": "Supply chain risk",
    "description": "Concentration risk, disruption scenarios, and diversification strategy.",
    "operationId": "riskSupply",
    "security": [
     {
      "x402": []
     }
    ],
    "parameters": [
     {
      "name": "product",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Product or component"
     },
     {
      "name": "country",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Country"
     },
     {
      "name": "lang",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Response language (default en)"
     }
    ],
    "responses": {
     "200": {
      "description": "Supply chain risk"
     },
     "402": {
      "description": "Payment required"
     }
    },
    "x-price-usd": 0.15,
    "x-agent-use-case": "on-demand",
    "x-agent-chaining": "Pairs with /api/risk/business and /api/risk/sanctions for full enterprise risk workflows"
   }
  }
 }
}