Data Contracts & API
Complete JSON data contracts and API endpoints exchanged between the five AESOP microservices.
API Endpoint Map
JSON Data Contracts
1. Entity Payload
{ "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 }] }
1b. Orientation / RFI
POST /api/intell/orientation/ X-API-Key{ "event_type": "tree.orientation", "idempotency_key": "<sha256>", "payload": { "system": "munitions-ua-2026", "target": {"name": "Azote", "kind": "substance"}, "gap_type": "unsatisfied", "question": "D'où provient l'azote ?", "priority": "high" } }
1c. Tree Entity Intake
POST /api/webhooks/intell-entity/{ "idempotency_key": "<sha256>", "payload": { "payload": { "entity_id": 501, "entity_type": "infrastructure", "name": "Usine d'ammoniac d'Odessa", "lat": 46.48, "lon": 30.74, "actor": "friendly" } } }
→ résolu en Node instance ; une réponse à une RFI rentre par ce même webhook et clôt l'orientation.
2. Infrastructure Alert
{ "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
{ "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
{ "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
{ "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 |