Data Contracts & API

Complete JSON data contracts and API endpoints exchanged between the three AESOP microservices.

API Endpoint Map

intell modelisation simulation aesop_intell Intelligence — port 8000 aesop_modelisation Modelisation (MIDAS) — port 8001 aesop_simulation Simulation (AESOP) — port 8002 intell → modelisation POST /api/webhooks/intell-entity/ POST /api/webhooks/intell-alert/ intell → simulation (GET) GET /api/entities/?domain=X GET /api/l1-reports/?domain=X modelisation → simulation (GET) GET /api/simulation/{id}/state/ GET /api/pnaiv/ · GET /api/is/{id}/nodes/ simulation → modelisation POST /api/webhooks/simulation-action/ simulation → intell POST /api/webhooks/simulation-event/

JSON Data Contracts

1. Entity Payload

intell → modelisation
{
  "entity_id": 1234,
  "entity_text": "EDF",
  "entity_type": "Organization",
  "confidence": 0.92,
  "latitude": 48.8566,
  "longitude": 2.3522,
  "h3_index": "891f1d48177ffff",
  "domain_category": "energy",
  "source_documents": [101, 102],
  "relationships": [{
    "target": "Gravelines Nuclear Plant",
    "relation": "OPERATES",
    "confidence": 0.88
  }]
}

2. Infrastructure Alert

intell → modelisation
{
  "alert_type": "infrastructure_change",
  "severity": "high",
  "sector": "energy",
  "description": "Reports of power grid disruption in eastern region",
  "affected_entities": ["EDF", "RTE"],
  "location": {
    "lat": 48.85,
    "lon": 7.35,
    "h3": "891f1d48177ffff"
  },
  "source_l1_report_id": 42,
  "timestamp": "2026-04-10T14:30:00Z"
}

3. Infrastructure State

modelisation → simulation
{
  "session_id": 1,
  "turn": 5,
  "pnaiv_health": {
    "telecom": 87.2,
    "electricity": 42.1,
    "hydrocarbons": 95.0,
    "transport": 78.4,
    "water": 91.3
  },
  "is_indicators": [{
    "is_id": 1,
    "name": "IS_energie_elec",
    "ieg_is": 42.1,
    "ieg_noeuds": 38.5,
    "ieg_liaisons": 45.7
  }],
  "cross_dependencies": [{
    "source": "IS_energie_elec",
    "target": "IS_comm_materiel",
    "iep": 55.2
  }]
}

4. Combat Effect on Infrastructure

simulation → modelisation
{
  "session_id": 1,
  "turn": 8,
  "effects": [
    {
      "is_node_id": 42,
      "node_name": "Gravelines Nuclear Plant",
      "damage_type": "kinetic",
      "state_reduction": 150
    },
    {
      "is_edge_id": 17,
      "edge_type": "power_line",
      "new_state": 0
    }
  ],
  "source_unit": "3RIMA",
  "combat_engagement_id": 234
}

5. Simulation Event

simulation → intell
{
  "event_type": "territory_change",
  "turn": 12,
  "description": "Belligerant A captured hex 85184a3ffffffff, displacing 45000 civilians",
  "location": {
    "h3": "85184a3ffffffff",
    "lat": 51.01,
    "lon": 2.10
  },
  "belligerants_involved": ["Belligerant A", "Belligerant B"]
}

Shared Conventions

Convention Value Notes
H3 Resolution 5 (default) Configurable per session; resolution 5 gives ~252 km² hexagons
Coordinate System WGS 84 (EPSG:4326) All lat/lon values use decimal degrees in WGS84
Time Format ISO 8601 UTC timezone, e.g. 2026-04-10T14:30:00Z
Authentication API key in header Authorization: Api-Key <key>
Content Type application/json All request and response bodies are JSON