{"openapi":"3.1.0","info":{"title":"AtlasPI","description":"\n# AtlasPI — Historical Geography API for AI Agents\n\n**The first REST API and MCP server for structured historical geography.**\nFree, public, Apache 2.0 licensed. No login. No API key. No registration.\n\n## What AtlasPI is\n\nA structured historical-geographic database designed specifically for AI agents,\nresearchers, and digital-humanities developers. Every record carries:\n\n- **Real boundaries** (GeoJSON polygons/multipolygons from Natural Earth,\n  aourednik/historical-basemaps, and curated academic maps — not placeholders)\n- **Academic sources** (2,400+ bibliographic citations)\n- **Confidence scores** (0.0–1.0 per entity/event)\n- **Explicit ethical framings** (conquests labeled as CONQUEST not \"succession\";\n  contested names preserved; colonial renamings documented)\n- **Native-language primary names** (Mēxihcah not \"Aztec\"; Tawantinsuyu not\n  \"Inca\"; 漢朝 not \"Han Dynasty\")\n\n## What's in the dataset (live)\n\n| Resource | Count | Endpoint |\n|---|---|---|\n| Historical entities | **862** | `/v1/entities` |\n| Historical events | **490** | `/v1/events` |\n| Historical periods | **48** | `/v1/periods` |\n| Historical cities | **110** | `/v1/cities` |\n| Trade routes | **41** | `/v1/routes` |\n| Dynasty chains | **94** | `/v1/chains` |\n| Sources | **2,400+** | (embedded) |\n\n**Temporal range**: 4500 BCE → 2024 CE.\n**Geographic range**: all inhabited continents (Europe 17%, Asia 31%, Africa 18%,\nAmericas 17%, Middle East 11%, Oceania 2%).\n\n## Why this API exists\n\nExisting geo datasets (Natural Earth, OSM, Wikidata) are either modern-only,\nunstructured, or poorly cross-linked. AI agents need:\n1. Semantic queries — not just SPARQL\n2. Contextualized answers — e.g., \"what was happening in 1250 globally\" in\n   one call (`/v1/snapshot/year/1250`)\n3. Cross-referenced entities — e.g., \"which periods did Imperium Romanum\n   overlap with?\" (`/v1/entities/{id}/periods`)\n4. Ethical framings — e.g., \"Aztec Imperial Period\" is labeled\n   region=americas, with historiographic_note on Spanish conquest\n\nAtlasPI provides all of this in a uniform REST API.\n\n## Quick Start\n\n**Python:**\n```python\nimport requests\nBASE = \"https://atlaspi.cra-srl.com\"\n\n# Discover entities existing in 1500 CE\nr = requests.get(f\"{BASE}/v1/entities\", params={\"year\": 1500, \"limit\": 20})\n\n# Single-call world snapshot\nr = requests.get(f\"{BASE}/v1/snapshot/year/1250\")\nprint(r.json()[\"periods\"][\"items\"])  # periods active in 1250, by region\n\n# Events on a specific date\nr = requests.get(f\"{BASE}/v1/events/on-this-day/07-14\")  # Bastille Day\n\n# Find similar entities by weighted algorithm\nr = requests.get(f\"{BASE}/v1/entities/1/similar?limit=10\")\n\n# Cross-resource period linkage\nr = requests.get(f\"{BASE}/v1/entities/1/periods\")  # Imperium Romanum periods\n```\n\n**curl:**\n```bash\ncurl -s https://atlaspi.cra-srl.com/v1/snapshot/year/1492 | jq .periods\ncurl -s https://atlaspi.cra-srl.com/v1/entities/1/similar | jq '.similar[0]'\ncurl -s https://atlaspi.cra-srl.com/v1/periods/by-slug/bronze-age\ncurl -s \"https://atlaspi.cra-srl.com/v1/events?year=1453\"\n```\n\n## Key endpoint categories\n\n- **Discovery**: `/v1/entities`, `/v1/events`, `/v1/periods`, `/v1/chains`\n- **Detail**: `/v1/entities/{id}`, `/v1/events/{id}`, `/v1/periods/by-slug/{slug}`\n- **Cross-resource**: `/v1/entities/{id}/periods`, `/v1/events/{id}/periods`,\n  `/v1/entities/{id}/predecessors`, `/v1/entities/{id}/successors`\n- **Temporal**: `/v1/snapshot/year/{year}`, `/v1/periods/at-year/{year}`,\n  `/v1/events/on-this-day/{mm-dd}`, `/v1/events/at-date/{iso-date}`\n- **Spatial**: `/v1/nearby`, `/v1/entities?bbox=...`\n- **Semantic**: `/v1/entities/{id}/similar`, `/v1/search/advanced`, `/v1/compare/{id1}/{id2}`\n- **Export**: `/v1/export/geojson`, `/v1/export/csv`, `/v1/export/timeline`\n\n## Also available\n\n- **MCP Server** (34 tools, v0.7.0): [github.com/Soil911/AtlasPI](https://github.com/Soil911/AtlasPI/tree/main/mcp-server) — plug directly into Claude Desktop, Claude Code, or any MCP client\n- **OpenAPI spec**: `/openapi.json` — machine-readable schema\n- **Swagger UI**: `/docs` — interactive documentation\n- **LLMs.txt**: `/llms.txt` — AI-agent-friendly site map\n- **Plugin manifest**: `/.well-known/ai-plugin.json` — OpenAI plugin spec\n\n## Ethics (ETHICS-001 → ETHICS-010)\n\n- Native-language primary names (ETHICS-001)\n- Explicit conquest/violence labeling (ETHICS-002)\n- Contested territories with all versions (ETHICS-003)\n- Boundary provenance transparent (ETHICS-005)\n- Geographic guard against fuzzy-match displacement (ETHICS-006)\n- Academic event terminology (GENOCIDE, COLONIAL_VIOLENCE) — no euphemisms (ETHICS-007)\n- Known-silence fields for events with suppressed documentation (ETHICS-008)\n- Colonial renamings documented, not hidden (ETHICS-009)\n- Slavery-involved trade routes flagged (ETHICS-010)\n\n## Data sources\n\n- **Natural Earth** (public domain): ne_110m_admin_0_countries\n- **aourednik/historical-basemaps** (CC BY 4.0): 54 period snapshots 4500 BCE → 2025\n- **Academic citations**: Cambridge Histories, Oxford Handbooks, regional specialists\n\n## License\n\n**Apache License 2.0** — free for commercial and non-commercial use.\nFull source: [github.com/Soil911/AtlasPI](https://github.com/Soil911/AtlasPI)\n","version":"6.32.0"},"paths":{"/health":{"get":{"tags":["sistema"],"summary":"Stato di salute del servizio","description":"Health check multi-livello: connettivita' DB, conta entita', stato Sentry, uptime. Ritorna 'ok' se tutto funziona, 'degraded' se qualcosa non e' al 100%, 'down' se il DB e' irraggiungibile. Il codice HTTP e' sempre 200 per non confondere monitoring tools, tranne 503 in caso di 'down'.","operationId":"health_check_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/v1/entity":{"get":{"tags":["entità"],"summary":"Cerca entità per nome, anno, status e tipo","description":"Endpoint principale (ADR-002). Cerca per nome (anche varianti), filtra per anno, status e tipo. Supporta ordinamento.","operationId":"query_entity_v1_entity_get","parameters":[{"name":"name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Nome (parziale) dell'entità","title":"Name"},"description":"Nome (parziale) dell'entità"},{"name":"year","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":2100,"minimum":-4000},{"type":"null"}],"description":"Anno di riferimento (negativo = a.C.)","title":"Year"},"description":"Anno di riferimento (negativo = a.C.)"},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["confirmed","uncertain","disputed"],"type":"string"},{"type":"null"}],"description":"Filtra per status","title":"Status"},"description":"Filtra per status"},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"description":"Filtra per entity_type (empire, kingdom, city, etc.)","title":"Type"},"description":"Filtra per entity_type (empire, kingdom, city, etc.)"},{"name":"continent","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"description":"Filtra per continente (Europe, Asia, Africa, Americas, Middle East, Oceania)","title":"Continent"},"description":"Filtra per continente (Europe, Asia, Africa, Americas, Middle East, Oceania)"},{"name":"bbox","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"description":"Bounding box geografico 'min_lon,min_lat,max_lon,max_lat' (RFC 7946). Restituisce entità il cui boundary_geojson interseca il bbox; per entità senza boundary, fallback alla capitale dentro il bbox. PostGIS in prod, approssimato in dev SQLite.","title":"Bbox"},"description":"Bounding box geografico 'min_lon,min_lat,max_lon,max_lat' (RFC 7946). Restituisce entità il cui boundary_geojson interseca il bbox; per entità senza boundary, fallback alla capitale dentro il bbox. PostGIS in prod, approssimato in dev SQLite."},{"name":"sort","in":"query","required":false,"schema":{"anyOf":[{"enum":["name","year_start","confidence","year_end"],"type":"string"},{"type":"null"}],"description":"Ordina per: name, year_start, confidence, year_end","title":"Sort"},"description":"Ordina per: name, year_start, confidence, year_end"},{"name":"order","in":"query","required":false,"schema":{"enum":["asc","desc"],"type":"string","description":"Direzione ordinamento","default":"asc","title":"Order"},"description":"Direzione ordinamento"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Risultati per pagina","default":20,"title":"Limit"},"description":"Risultati per pagina"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Offset per paginazione","default":0,"title":"Offset"},"description":"Offset per paginazione"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedEntityResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/entities":{"get":{"tags":["entità"],"summary":"List all historical entities (paginated)","description":"Primary discovery endpoint for AtlasPI's 862 historical geopolitical entities. Returns empires, kingdoms, sultanates, republics, chiefdoms, confederations, dynasties, caliphates, and more — spanning 4500 BCE to 2024 across all inhabited continents.\n\n**Filters** (all optional, combinable):\n- `year` — entities existing in this specific year\n- `status` — confirmed / uncertain / disputed\n- `entity_type` — empire, kingdom, sultanate, etc.\n- `continent` — Europe, Asia, Africa, Americas, Middle East, Oceania\n- `bbox` — spatial bounding box (minLon,minLat,maxLon,maxLat)\n- `search` — fuzzy match on name_original and name_variants\n\n**For AI agents**: use this as the entry point to discover entities, then follow `/v1/entities/{id}/periods`, `/successors`, `/predecessors`, `/similar`, `/events` for rich contextualization.\n\n**Free public API — no authentication required.**","operationId":"list_entities_v1_entities_get","parameters":[{"name":"bbox","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"description":"Bounding box 'min_lon,min_lat,max_lon,max_lat' (vedi /v1/entity).","title":"Bbox"},"description":"Bounding box 'min_lon,min_lat,max_lon,max_lat' (vedi /v1/entity)."},{"name":"sort","in":"query","required":false,"schema":{"anyOf":[{"enum":["name","year_start","confidence","year_end"],"type":"string"},{"type":"null"}],"description":"Ordina per: name, year_start, confidence, year_end","title":"Sort"},"description":"Ordina per: name, year_start, confidence, year_end"},{"name":"order","in":"query","required":false,"schema":{"enum":["asc","desc"],"type":"string","description":"Direzione ordinamento","default":"asc","title":"Order"},"description":"Direzione ordinamento"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Risultati per pagina","default":20,"title":"Limit"},"description":"Risultati per pagina"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Offset","default":0,"title":"Offset"},"description":"Offset"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedEntityResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/entities/{entity_id}":{"get":{"tags":["entità"],"summary":"Get detailed information for a single historical entity","description":"Full detail view of a historical entity by its numeric ID. Returns:\n\n- **Core**: name_original (in native script), entity_type, year_start, year_end, capital name/lat/lon\n- **Geographic**: boundary_geojson (full polygon/multipolygon geometry), boundary_source (natural_earth / aourednik / historical_map / approximate_generated — provenance tier), boundary tracking fields\n- **Quality**: confidence_score (0.0-1.0), status (confirmed/uncertain/disputed)\n- **Names**: name_variants in multiple languages/scripts\n- **Sources**: full bibliographic citations (academic, primary, archaeological, etc.)\n- **Territory changes**: documented acquisitions/losses with dates, explicit change_type (CONQUEST, SUCCESSION, COLONIZATION, etc.)\n- **Ethical notes**: contested territories, colonial framings, alternative names\n\nFor AI agents: after fetching an entity detail, chain requests to `/v1/entities/{id}/periods` (which historical epochs it existed in), `/v1/entities/{id}/events` (events involving this entity), `/v1/entities/{id}/similar` (top-N similar by confidence).","operationId":"get_entity_v1_entities__entity_id__get","parameters":[{"name":"entity_id","in":"path","required":true,"schema":{"type":"integer","title":"Entity Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/search":{"get":{"tags":["entità"],"summary":"Ricerca veloce per autocomplete","description":"Restituisce risultati leggeri (senza GeoJSON) per ricerca rapida.","operationId":"search_entities_v1_search_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"description":"Testo da cercare","title":"Q"},"description":"Testo da cercare"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"Max risultati","default":10,"title":"Limit"},"description":"Max risultati"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/search/fuzzy":{"get":{"tags":["entità"],"summary":"Ricerca fuzzy multi-script su name_original + name_variants","description":"Ranking per similarità (SequenceMatcher ratio) sul nome originale e sulle varianti. Funziona cross-script (Greek, Persian, Chinese, Cyrillic) perché la metrica è character-level. Utile per agenti AI che ricevono nomi approssimati o in trascrizione errata.","operationId":"search_entities_fuzzy_v1_search_fuzzy_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"description":"Testo da cercare (fuzzy)","title":"Q"},"description":"Testo da cercare (fuzzy)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"Max risultati","default":10,"title":"Limit"},"description":"Max risultati"},{"name":"min_score","in":"query","required":false,"schema":{"type":"number","maximum":1.0,"minimum":0.0,"description":"Soglia minima di similarità (0.0=tutto, 1.0=solo match esatti)","default":0.4,"title":"Min Score"},"description":"Soglia minima di similarità (0.0=tutto, 1.0=solo match esatti)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/types":{"get":{"tags":["entità"],"summary":"List all entity types with counts","description":"Returns the distinct `entity_type` values used across the dataset, with a count of entities per type. Used for populating filter UI and for AI agents to understand the categorization vocabulary.\n\nTypical types include: empire, kingdom, sultanate, republic, confederation, dynasty, caliphate, khanate, principality, duchy, city-state, chiefdom, tribal_nation, cultural_region, civilization.\n\nUse with `/v1/entities?entity_type=<type>` to filter.","operationId":"list_types_v1_types_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/TypeInfo"},"type":"array","title":"Response List Types V1 Types Get"}}}}}}},"/v1/continents":{"get":{"tags":["entità"],"summary":"Elenco continenti con conteggio entità","description":"Restituisce i continenti disponibili calcolati dalle coordinate delle capitali.","operationId":"list_continents_v1_continents_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/ContinentInfo"},"type":"array","title":"Response List Continents V1 Continents Get"}}}}}}},"/v1/random":{"get":{"tags":["entità"],"summary":"Entità casuale (con filtri opzionali)","description":"Restituisce un'entità casuale dal dataset. Supporta filtri per tipo, anno, status e continente.","operationId":"random_entity_v1_random_get","parameters":[{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"description":"Filtra per entity_type","title":"Type"},"description":"Filtra per entity_type"},{"name":"year","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":2100,"minimum":-4500},{"type":"null"}],"description":"Entità attiva in questo anno","title":"Year"},"description":"Entità attiva in questo anno"},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["confirmed","uncertain","disputed"],"type":"string"},{"type":"null"}],"description":"Filtra per status","title":"Status"},"description":"Filtra per status"},{"name":"continent","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"description":"Filtra per continente","title":"Continent"},"description":"Filtra per continente"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/nearby":{"get":{"tags":["entità"],"summary":"Entità vicine a coordinate date","description":"Trova entità storiche vicine a una posizione geografica. Utile per agenti AI che partono da coordinate.","operationId":"nearby_entities_v1_nearby_get","parameters":[{"name":"lat","in":"query","required":true,"schema":{"type":"number","maximum":90,"minimum":-90,"description":"Latitudine","title":"Lat"},"description":"Latitudine"},{"name":"lon","in":"query","required":true,"schema":{"type":"number","maximum":180,"minimum":-180,"description":"Longitudine","title":"Lon"},"description":"Longitudine"},{"name":"radius","in":"query","required":false,"schema":{"type":"number","maximum":5000,"minimum":1,"description":"Raggio in km","default":500,"title":"Radius"},"description":"Raggio in km"},{"name":"year","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":2100,"minimum":-4500},{"type":"null"}],"description":"Anno (opzionale)","title":"Year"},"description":"Anno (opzionale)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"Max risultati","default":10,"title":"Limit"},"description":"Max risultati"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/snapshot/{year}":{"get":{"tags":["entità"],"summary":"Snapshot del mondo in un anno specifico","description":"Restituisce tutte le entità attive in un dato anno, con conteggi per tipo e continente. Ideale per agenti AI che vogliono ricostruire il mondo in un momento storico.","operationId":"year_snapshot_v1_snapshot__year__get","parameters":[{"name":"year","in":"path","required":true,"schema":{"type":"integer","title":"Year"}},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"description":"Filtra per tipo","title":"Type"},"description":"Filtra per tipo"},{"name":"continent","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"description":"Filtra per continente","title":"Continent"},"description":"Filtra per continente"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/stats":{"get":{"tags":["entità"],"summary":"Statistiche del dataset","description":"Panoramica del dataset: conteggi, range, media confidence.","operationId":"dataset_stats_v1_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsResponse"}}}}}}},"/v1/aggregation":{"get":{"tags":["entità"],"summary":"Statistiche aggregate per secolo, tipo, continente e status","description":"Restituisce conteggi aggregati delle entità raggruppati per secolo (basato su year_start), tipo, continente e status. Ideale per dashboard e analisi AI.","operationId":"aggregation_v1_aggregation_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/export/geojson":{"get":{"tags":["esportazione"],"summary":"Esporta tutte le entità come GeoJSON FeatureCollection","description":"Standard GeoJSON — importabile in QGIS, Leaflet, Mapbox, etc. Usa `geometry=none` per esportare solo le proprieta' (molto piu' veloce) o `geometry=centroid` per esportare solo le capitali come Point.","operationId":"export_geojson_v1_export_geojson_get","parameters":[{"name":"year","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":2100,"minimum":-4000},{"type":"null"}],"title":"Year"}},{"name":"geometry","in":"query","required":false,"schema":{"type":"string","pattern":"^(full|centroid|none)$","description":"full = poligoni completi (default); centroid = Point capitali; none = solo properties","default":"full","title":"Geometry"},"description":"full = poligoni completi (default); centroid = Point capitali; none = solo properties"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/export/csv":{"get":{"tags":["esportazione"],"summary":"Esporta entità come CSV","description":"CSV tabellare per analisi in Excel, Pandas, R.","operationId":"export_csv_v1_export_csv_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/export/timeline":{"get":{"tags":["esportazione"],"summary":"Dati per visualizzazione timeline","description":"JSON ottimizzato per rendering timeline interattiva.","operationId":"export_timeline_v1_export_timeline_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/entities/{entity_id}/contemporaries":{"get":{"tags":["relazioni"],"summary":"Entità contemporanee","description":"Restituisce le entità attive nello stesso periodo dell'entità data.","operationId":"get_contemporaries_v1_entities__entity_id__contemporaries_get","parameters":[{"name":"entity_id","in":"path","required":true,"schema":{"type":"integer","title":"Entity Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":10,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/entities/{entity_id}/related":{"get":{"tags":["relazioni"],"summary":"Entità correlate","description":"Restituisce entità correlate per tipo, periodo e riferimenti incrociati nei cambi territoriali.","operationId":"get_related_v1_entities__entity_id__related_get","parameters":[{"name":"entity_id","in":"path","required":true,"schema":{"type":"integer","title":"Entity Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/entities/{entity_id}/similar":{"get":{"tags":["relazioni"],"summary":"Entità più simili","description":"Trova entità simili a quella data, ordinate per punteggio di similarità (0.0-1.0). Il punteggio considera: tipo di entità (35%), sovrapposizione temporale (30%), durata simile (15%), confidence simile (10%), stesso status (10%). Utile per agenti AI che cercano paragoni storici.","operationId":"get_similar_v1_entities__entity_id__similar_get","parameters":[{"name":"entity_id","in":"path","required":true,"schema":{"type":"integer","title":"Entity Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"Max results","default":10,"title":"Limit"},"description":"Max results"},{"name":"min_score","in":"query","required":false,"schema":{"type":"number","maximum":1.0,"minimum":0.0,"description":"Minimum similarity score","default":0.3,"title":"Min Score"},"description":"Minimum similarity score"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/entities/{entity_id}/evolution":{"get":{"tags":["relazioni"],"summary":"Evoluzione temporale di un'entità","description":"Restituisce la cronologia completa di un'entità: fondazione, cambiamenti territoriali ordinati, fase finale. Utile per agenti AI che devono ricostruire la storia di un'entità nel tempo.","operationId":"get_evolution_v1_entities__entity_id__evolution_get","parameters":[{"name":"entity_id","in":"path","required":true,"schema":{"type":"integer","title":"Entity Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/entities/{entity_id}/timeline":{"get":{"tags":["relazioni"],"summary":"Timeline unificata di un'entità","description":"Fonde in un unico stream cronologico: (1) territory_changes dell'entità, (2) historical_events che coinvolgono l'entità (via event_entity_links), (3) chain_transitions dove l'entità entra/esce da una catena dinastica. Ogni evento ha un campo `kind` (territory_change|event|chain_transition) per disambiguare la sorgente. Utile per agenti AI che devono ricostruire la traiettoria completa di un'entità storica senza fare 3-4 chiamate separate.","operationId":"get_entity_timeline_v1_entities__entity_id__timeline_get","parameters":[{"name":"entity_id","in":"path","required":true,"schema":{"type":"integer","title":"Entity Id"}},{"name":"include_entity_links","in":"query","required":false,"schema":{"type":"boolean","description":"Se True include tutti gli eventi con un link all'entità (MAIN_ACTOR, VICTIM, PARTICIPANT, AFFECTED, WITNESS, FOUNDED, DISSOLVED). Se False include solo eventi dove l'entità è MAIN_ACTOR o FOUNDED/DISSOLVED.","default":true,"title":"Include Entity Links"},"description":"Se True include tutti gli eventi con un link all'entità (MAIN_ACTOR, VICTIM, PARTICIPANT, AFFECTED, WITNESS, FOUNDED, DISSOLVED). Se False include solo eventi dove l'entità è MAIN_ACTOR o FOUNDED/DISSOLVED."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/compare/{id1}/{id2}":{"get":{"tags":["relazioni"],"summary":"Confronta due entità storiche","description":"Restituisce un confronto strutturato tra due entità: durata, overlap temporale, metriche di qualità dati.","operationId":"compare_entities_v1_compare__id1___id2__get","parameters":[{"name":"id1","in":"path","required":true,"schema":{"type":"integer","title":"Id1"}},{"name":"id2","in":"path","required":true,"schema":{"type":"integer","title":"Id2"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/events":{"get":{"tags":["eventi"],"summary":"Lista eventi storici","description":"Lista paginata di eventi storici con filtri su anno, tipo, stato e silenzi. ETHICS-007: nessun eufemismo nei termini EventType (GENOCIDE, COLONIAL_VIOLENCE, ...). ETHICS-008: `known_silence=true` restituisce solo eventi con documentazione contemporanea assente/cancellata.","operationId":"list_events_v1_events_get","parameters":[{"name":"year_min","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Anno minimo (incluso)","title":"Year Min"},"description":"Anno minimo (incluso)"},{"name":"year_max","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Anno massimo (incluso)","title":"Year Max"},"description":"Anno massimo (incluso)"},{"name":"event_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filtra per EventType (es. BATTLE, GENOCIDE)","title":"Event Type"},"description":"Filtra per EventType (es. BATTLE, GENOCIDE)"},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"confirmed / uncertain / disputed","title":"Status"},"description":"confirmed / uncertain / disputed"},{"name":"known_silence","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Solo eventi con silenzio documentato","title":"Known Silence"},"description":"Solo eventi con silenzio documentato"},{"name":"month","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":12,"minimum":1},{"type":"null"}],"description":"Filtra per mese (1-12)","title":"Month"},"description":"Filtra per mese (1-12)"},{"name":"day","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":31,"minimum":1},{"type":"null"}],"description":"Filtra per giorno (1-31)","title":"Day"},"description":"Filtra per giorno (1-31)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/events/types":{"get":{"tags":["eventi"],"summary":"Enumera i tipi di evento","description":"Restituisce i tipi di evento supportati (EventType enum) con breve descrizione dell'uso corretto. ETHICS-007: i termini sono espliciti — GENOCIDE, COLONIAL_VIOLENCE, ETHNIC_CLEANSING, MASSACRE, DEPORTATION — e non vanno sostituiti con eufemismi.","operationId":"list_event_types_v1_events_types_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/events/map":{"get":{"tags":["eventi"],"summary":"Eventi per visualizzazione mappa","description":"Payload leggero ottimizzato per il rendering di marker su mappa. Restituisce solo eventi con coordinate (lat/lon non null) entro una finestra temporale centrata su `year`. La finestra si auto-espande per epoche antiche: ±50 per anni < -1000, ±25 per anni da -1000 a 0.","operationId":"events_for_map_v1_events_map_get","parameters":[{"name":"year","in":"query","required":true,"schema":{"type":"integer","description":"Anno centrale della finestra temporale","title":"Year"},"description":"Anno centrale della finestra temporale"},{"name":"window","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Semi-ampiezza finestra in anni (auto-espansa per epoche antiche)","default":10,"title":"Window"},"description":"Semi-ampiezza finestra in anni (auto-espansa per epoche antiche)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Numero massimo di eventi","default":200,"title":"Limit"},"description":"Numero massimo di eventi"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/events/on-this-day/{mm_dd}":{"get":{"tags":["eventi"],"summary":"Eventi accaduti in un giorno dell'anno","description":"Restituisce gli eventi storici con month/day corrispondenti, ordinati per anno. Formato path: MM-DD (es. 07-14 per il 14 luglio). Restituisce lista vuota (non 404) se nessun evento coincide.","operationId":"events_on_this_day_v1_events_on_this_day__mm_dd__get","parameters":[{"name":"mm_dd","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{2}-\\d{2}$","description":"Mese-giorno in formato MM-DD","title":"Mm Dd"},"description":"Mese-giorno in formato MM-DD"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/events/at-date/{date_str}":{"get":{"tags":["eventi"],"summary":"Eventi in una data esatta","description":"Restituisce gli eventi in una data esatta ISO-like. Formato: YYYY-MM-DD (es. 1789-07-14) o -YYYY-MM-DD per BCE (es. -0331-10-01 per il 1 ottobre 331 a.C.). Restituisce lista vuota (non 404) se nessun evento coincide.","operationId":"events_at_date_v1_events_at_date__date_str__get","parameters":[{"name":"date_str","in":"path","required":true,"schema":{"type":"string","description":"Data in formato [-]YYYY-MM-DD","title":"Date Str"},"description":"Data in formato [-]YYYY-MM-DD"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/events/date-coverage":{"get":{"tags":["eventi"],"summary":"Copertura date per on-this-day","description":"Restituisce le date (MM-DD) che hanno almeno un evento nel dataset. Utile per un agente AI che vuole sapere prima di chiamare on-this-day se quella data avrà risultati, o per suggerire date 'interessanti' all'utente.","operationId":"events_date_coverage_v1_events_date_coverage_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/events/{event_id}":{"get":{"tags":["eventi"],"summary":"Dettaglio evento storico","description":"Dettaglio completo di un evento con entity_links (ruolo esplicito per ogni entità coinvolta) e sources. ETHICS-007: main_actor obbligatorio.","operationId":"get_event_v1_events__event_id__get","parameters":[{"name":"event_id","in":"path","required":true,"schema":{"type":"integer","title":"Event Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/entities/{entity_id}/events":{"get":{"tags":["eventi"],"summary":"Eventi collegati a un'entità","description":"Restituisce tutti gli eventi in cui l'entità compare (qualunque ruolo). Utile per ricostruire la storia eventuale di un'entità: fondazione, conquiste, dissoluzione, eventi subiti (violenze coloniali, epidemie).","operationId":"get_events_for_entity_v1_entities__entity_id__events_get","parameters":[{"name":"entity_id","in":"path","required":true,"schema":{"type":"integer","title":"Entity Id"}},{"name":"role","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filtra per ruolo (es. MAIN_ACTOR, VICTIM)","title":"Role"},"description":"Filtra per ruolo (es. MAIN_ACTOR, VICTIM)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/cities":{"get":{"tags":["cities-routes"],"summary":"Lista città storiche","description":"Lista paginata di città storiche con filtri su anno, tipo, entità, bbox e prossimità geografica. Una città è separata dalla capital_* di GeoEntity perché può sopravvivere più entità politiche.","operationId":"list_cities_v1_cities_get","parameters":[{"name":"year","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Anno di attività (città esistente in quell'anno): founded_year <= year AND (abandoned_year IS NULL OR abandoned_year >= year).","title":"Year"},"description":"Anno di attività (città esistente in quell'anno): founded_year <= year AND (abandoned_year IS NULL OR abandoned_year >= year)."},{"name":"city_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filtra per CityType (es. TRADE_HUB, CAPITAL)","title":"City Type"},"description":"Filtra per CityType (es. TRADE_HUB, CAPITAL)"},{"name":"entity_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Filtra per entità politica di appartenenza","title":"Entity Id"},"description":"Filtra per entità politica di appartenenza"},{"name":"bbox","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filtro spaziale. Formato: min_lon,min_lat,max_lon,max_lat.","title":"Bbox"},"description":"Filtro spaziale. Formato: min_lon,min_lat,max_lon,max_lat."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"confirmed / uncertain / disputed","title":"Status"},"description":"confirmed / uncertain / disputed"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/cities/types":{"get":{"tags":["cities-routes"],"summary":"Enumera i tipi di città","description":"Restituisce l'enum CityType con breve descrizione.","operationId":"list_city_types_v1_cities_types_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/cities/{city_id}":{"get":{"tags":["cities-routes"],"summary":"Dettaglio città storica","description":"Dettaglio di una città storica con name_variants (ETHICS-009: rename coloniali/imperiali), sources e entità di appartenenza.","operationId":"get_city_v1_cities__city_id__get","parameters":[{"name":"city_id","in":"path","required":true,"schema":{"type":"integer","title":"City Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/routes":{"get":{"tags":["cities-routes"],"summary":"Lista rotte commerciali","description":"Lista paginata di rotte commerciali storiche (Silk Road, Trans-Saharan, Trans-Atlantic slave trade, Amber Route, etc). ETHICS-010: `involves_slavery=true` filtra le rotte che trafficavano esseri umani — il flag è esplicito perché la distinzione è eticamente rilevante.","operationId":"list_routes_v1_routes_get","parameters":[{"name":"year","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Anno di attività (start_year <= year <= end_year).","title":"Year"},"description":"Anno di attività (start_year <= year <= end_year)."},{"name":"route_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"LAND / SEA / RIVER / CARAVAN / MIXED","title":"Route Type"},"description":"LAND / SEA / RIVER / CARAVAN / MIXED"},{"name":"involves_slavery","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"ETHICS-010: filtra rotte che trafficavano esseri umani","title":"Involves Slavery"},"description":"ETHICS-010: filtra rotte che trafficavano esseri umani"},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"confirmed / uncertain / disputed","title":"Status"},"description":"confirmed / uncertain / disputed"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/routes/types":{"get":{"tags":["cities-routes"],"summary":"Enumera i tipi di rotta","description":"Restituisce l'enum RouteType con breve descrizione.","operationId":"list_route_types_v1_routes_types_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/routes/{route_id}":{"get":{"tags":["cities-routes"],"summary":"Dettaglio rotta commerciale","description":"Dettaglio completo con geometria GeoJSON, commodities, waypoints ordinati e sources. ETHICS-010: `ethical_notes` esplicita scala e main_actors per le rotte schiaviste.","operationId":"get_route_v1_routes__route_id__get","parameters":[{"name":"route_id","in":"path","required":true,"schema":{"type":"integer","title":"Route Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/chains":{"get":{"tags":["chains"],"summary":"Lista catene successorie","description":"Lista paginata di catene successorie / dinastiche / coloniali. Ogni catena lega più entità geopolitiche con un transition_type esplicito (ETHICS-002): CONQUEST e REVOLUTION non sono sostituibili da SUCCESSION generico. Filtri opzionali su chain_type, region, year (almeno una entità della catena attiva in quell'anno).","operationId":"list_chains_v1_chains_get","parameters":[{"name":"chain_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"DYNASTY / SUCCESSION / RESTORATION / COLONIAL / IDEOLOGICAL / OTHER","title":"Chain Type"},"description":"DYNASTY / SUCCESSION / RESTORATION / COLONIAL / IDEOLOGICAL / OTHER"},{"name":"region","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filtro substring case-insensitive sul campo region","title":"Region"},"description":"Filtro substring case-insensitive sul campo region"},{"name":"year","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Anno di interesse: ritorna catene con almeno un'entità attiva in quell'anno.","title":"Year"},"description":"Anno di interesse: ritorna catene con almeno un'entità attiva in quell'anno."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"confirmed / uncertain / disputed","title":"Status"},"description":"confirmed / uncertain / disputed"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/chains/types":{"get":{"tags":["chains"],"summary":"Enumera ChainType + TransitionType","description":"Restituisce gli enum di tipologia per catene e transizioni.","operationId":"list_chain_types_v1_chains_types_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/chains/{chain_id}":{"get":{"tags":["chains"],"summary":"Dettaglio catena successoria","description":"Dettaglio di una catena con tutti i link in ordine cronologico. Ogni link include transition_type esplicito (ETHICS-002) + is_violent + ethical_notes specifiche della transizione.","operationId":"get_chain_v1_chains__chain_id__get","parameters":[{"name":"chain_id","in":"path","required":true,"schema":{"type":"integer","title":"Chain Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/entities/{entity_id}/predecessors":{"get":{"tags":["chains"],"summary":"Predecessori di un'entità nelle catene","description":"Restituisce le catene in cui questa entità ha un predecessore (sequence_order > 0), insieme al predecessore immediato e al tipo di transizione che ha portato A questa entità.","operationId":"get_entity_predecessors_v1_entities__entity_id__predecessors_get","parameters":[{"name":"entity_id","in":"path","required":true,"schema":{"type":"integer","title":"Entity Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/entities/{entity_id}/successors":{"get":{"tags":["chains"],"summary":"Successori di un'entità nelle catene","description":"Restituisce le catene in cui questa entità ha un successore, insieme al successore immediato e al tipo di transizione che ha portato DA questa entità all'entità successiva.","operationId":"get_entity_successors_v1_entities__entity_id__successors_get","parameters":[{"name":"entity_id","in":"path","required":true,"schema":{"type":"integer","title":"Entity Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/periods":{"get":{"tags":["periods"],"summary":"List historical periods","description":"Lista strutturata di epoche storiche. Filtrabile per regione, tipo, anno e status.","operationId":"list_periods_v1_periods_get","parameters":[{"name":"region","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by region scope","title":"Region"},"description":"Filter by region scope"},{"name":"period_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by period type (age, era, period, dynasty, epoch)","title":"Period Type"},"description":"Filter by period type (age, era, period, dynasty, epoch)"},{"name":"year","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Only periods that include this year","title":"Year"},"description":"Only periods that include this year"},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by status (confirmed, debated, deprecated)","title":"Status"},"description":"Filter by status (confirmed, debated, deprecated)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":200,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/periods/types":{"get":{"tags":["periods"],"summary":"List all period types in the database","description":"Return the distinct period_type values used in the dataset.","operationId":"period_types_v1_periods_types_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/periods/regions":{"get":{"tags":["periods"],"summary":"List all regions used by periods","description":"Return the distinct region values used in the dataset.","operationId":"period_regions_v1_periods_regions_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/periods/at-year/{year}":{"get":{"tags":["periods"],"summary":"Find periods that include a given year","description":"Returns all periods whose range includes the given year, across regions.","operationId":"periods_at_year_v1_periods_at_year__year__get","parameters":[{"name":"year","in":"path","required":true,"schema":{"type":"integer","maximum":3000,"minimum":-4000000,"description":"Year to query (negative = BCE)","title":"Year"},"description":"Year to query (negative = BCE)"},{"name":"region","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional region filter","title":"Region"},"description":"Optional region filter"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/periods/by-slug/{slug}":{"get":{"tags":["periods"],"summary":"Get period by URL-friendly slug","description":"Fetch a single period by its unique slug (e.g. 'bronze-age', 'edo-period').","operationId":"period_by_slug_v1_periods_by_slug__slug__get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"title":"Slug"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/periods/{period_id}":{"get":{"tags":["periods"],"summary":"Get full detail for a historical period","description":"Returns the complete record for a historical period by numeric ID, including description, historiographic_note (documenting scholarly contestation), alternative_names (competing/deprecated labels like 'Dark Ages' for Early Middle Ages), and full academic sources.\n\nFor AI agents: periods are region-scoped (Europe, Asia_East, Africa, Americas, etc.) — no global Eurocentric defaults. The `historiographic_note` field is critical context — it documents how historians contest these periodizations.","operationId":"period_detail_v1_periods__period_id__get","parameters":[{"name":"period_id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"title":"Period Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/entities/{entity_id}/periods":{"get":{"tags":["periods"],"summary":"Historical periods that overlap with this entity's lifespan","description":"Returns the historical periods whose year range overlaps with this entity's [year_start, year_end]. Useful for contextualizing an entity within its historiographic era.","operationId":"entity_periods_v1_entities__entity_id__periods_get","parameters":[{"name":"entity_id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"title":"Entity Id"}},{"name":"region","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Region"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/events/{event_id}/periods":{"get":{"tags":["periods"],"summary":"Historical periods that contain this event's year","description":"Returns the historical periods whose year range contains this event's year. Useful for contextualizing an event (e.g., 'Battle of Tours happened during the Early Middle Ages in Europe and the Abbasid Caliphate era in the Near East').","operationId":"event_periods_v1_events__event_id__periods_get","parameters":[{"name":"event_id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"title":"Event Id"}},{"name":"region","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Region"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/snapshot/year/{year}":{"get":{"tags":["snapshot"],"summary":"World snapshot at a given year","description":"Aggregated snapshot of the world at a specific year: active entities, historical periods in effect, events that year, active cities, chains in progress. Designed for AI agents answering 'What was the world like in year X?' with a single API call.","operationId":"world_snapshot_v1_snapshot_year__year__get","parameters":[{"name":"year","in":"path","required":true,"schema":{"type":"integer","maximum":2025,"minimum":-5000,"description":"Year (negative = BCE)","title":"Year"},"description":"Year (negative = BCE)"},{"name":"top_n","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"How many top-items to include per category","default":10,"title":"Top N"},"description":"How many top-items to include per category"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/timeline-data":{"get":{"tags":["esportazione"],"summary":"Dati ottimizzati per la timeline","description":"Restituisce entita', eventi e catene successorie in un unico payload leggero, ottimizzato per il rendering della timeline SVG interattiva. Nessuna descrizione, nessun GeoJSON — solo i campi temporali necessari. Cache aggressiva (1 ora).","operationId":"get_timeline_data_v1_timeline_data_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/compare":{"get":{"tags":["relazioni"],"summary":"Confronta 2-4 entita' storiche","description":"Confronto multi-entita' strutturato. Restituisce dettagli completi per ogni entita', eventi collegati, catene successorie e calcolo dell'overlap temporale. Minimo 2, massimo 4 entita' per richiesta.","operationId":"compare_entities_v1_compare_get","parameters":[{"name":"ids","in":"query","required":true,"schema":{"type":"string","description":"Comma-separated entity IDs (2-4), e.g. ids=1,2,3","examples":["1,2"],"title":"Ids"},"description":"Comma-separated entity IDs (2-4), e.g. ids=1,2,3"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/search/advanced":{"get":{"tags":["ricerca"],"summary":"Unified search across all data types","description":"Searches entities, events, cities, and trade routes in a single query. Results are ranked by relevance (exact match > starts with > contains). Supports optional filters: type (entity_type), year_min, year_max, status, confidence_min, confidence_max, data_type (entity/event/city/route).","operationId":"advanced_search_v1_search_advanced_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":300,"description":"Search query","title":"Q"},"description":"Search query"},{"name":"data_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by data type: entity, event, city, route (or comma-separated)","title":"Data Type"},"description":"Filter by data type: entity, event, city, route (or comma-separated)"},{"name":"entity_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter entities by entity_type (empire, kingdom, etc.)","title":"Entity Type"},"description":"Filter entities by entity_type (empire, kingdom, etc.)"},{"name":"year_min","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Minimum year (inclusive)","title":"Year Min"},"description":"Minimum year (inclusive)"},{"name":"year_max","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Maximum year (inclusive)","title":"Year Max"},"description":"Maximum year (inclusive)"},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by status (confirmed/uncertain/disputed)","title":"Status"},"description":"Filter by status (confirmed/uncertain/disputed)"},{"name":"confidence_min","in":"query","required":false,"schema":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"description":"Minimum confidence score","title":"Confidence Min"},"description":"Minimum confidence score"},{"name":"confidence_max","in":"query","required":false,"schema":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"description":"Maximum confidence score","title":"Confidence Max"},"description":"Maximum confidence score"},{"name":"sort","in":"query","required":false,"schema":{"type":"string","description":"Sort by: relevance, name, year, confidence","default":"relevance","title":"Sort"},"description":"Sort by: relevance, name, year, confidence"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Max results","default":30,"title":"Limit"},"description":"Max results"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Offset for pagination","default":0,"title":"Offset"},"description":"Offset for pagination"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/export/entities":{"get":{"tags":["esportazione"],"summary":"Export entities as CSV or GeoJSON","description":"Export entities with filters. Formats: csv (UTF-8 with BOM for Excel), geojson (FeatureCollection). Max 1000 rows per export.","operationId":"export_entities_v1_export_entities_get","parameters":[{"name":"format","in":"query","required":false,"schema":{"type":"string","description":"Export format: csv or geojson","default":"csv","title":"Format"},"description":"Export format: csv or geojson"},{"name":"entity_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by entity_type","title":"Entity Type"},"description":"Filter by entity_type"},{"name":"year_min","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Minimum year_start","title":"Year Min"},"description":"Minimum year_start"},{"name":"year_max","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Maximum year_start","title":"Year Max"},"description":"Maximum year_start"},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by status","title":"Status"},"description":"Filter by status"},{"name":"confidence_min","in":"query","required":false,"schema":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Confidence Min"}},{"name":"confidence_max","in":"query","required":false,"schema":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Confidence Max"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/export/events":{"get":{"tags":["esportazione"],"summary":"Export events as CSV or JSON","description":"Export historical events with filters. Formats: csv (UTF-8 with BOM), json (JSON array). Max 1000 rows per export.","operationId":"export_events_v1_export_events_get","parameters":[{"name":"format","in":"query","required":false,"schema":{"type":"string","description":"Export format: csv or json","default":"csv","title":"Format"},"description":"Export format: csv or json"},{"name":"event_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by event_type","title":"Event Type"},"description":"Filter by event_type"},{"name":"year_min","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Minimum year","title":"Year Min"},"description":"Minimum year"},{"name":"year_max","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Maximum year","title":"Year Max"},"description":"Maximum year"},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by status","title":"Status"},"description":"Filter by status"},{"name":"confidence_min","in":"query","required":false,"schema":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Confidence Min"}},{"name":"confidence_max","in":"query","required":false,"schema":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Confidence Max"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"CapitalResponse":{"properties":{"name":{"type":"string","title":"Name"},"lat":{"type":"number","title":"Lat"},"lon":{"type":"number","title":"Lon"}},"type":"object","required":["name","lat","lon"],"title":"CapitalResponse","description":"Capitale dell'entità."},"ContinentInfo":{"properties":{"continent":{"type":"string","title":"Continent"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["continent","count"],"title":"ContinentInfo"},"EntityResponse":{"properties":{"id":{"type":"integer","title":"Id"},"entity_type":{"type":"string","title":"Entity Type","description":"Tipo: empire, kingdom, city-state, colony, disputed_territory"},"year_start":{"type":"integer","title":"Year Start","description":"Anno inizio (negativo = a.C.)"},"year_end":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Year End","description":"Anno fine (null = ancora esistente)"},"name_original":{"type":"string","title":"Name Original","description":"Nome nella lingua originale/locale (ETHICS-001)"},"name_original_lang":{"type":"string","title":"Name Original Lang","description":"Codice lingua ISO 639-1"},"name_variants":{"items":{"$ref":"#/components/schemas/NameVariantResponse"},"type":"array","title":"Name Variants","description":"Nomi in altre lingue con contesto"},"capital":{"anyOf":[{"$ref":"#/components/schemas/CapitalResponse"},{"type":"null"}]},"boundary_geojson":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Boundary Geojson","description":"Confini GeoJSON (Polygon o MultiPolygon)"},"boundary_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Boundary Source","description":"Tier di provenienza del confine (ETHICS-005): historical_map, natural_earth, aourednik, academic_source, approximate_generated"},"boundary_aourednik_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Boundary Aourednik Name","description":"Nome esatto della feature matchata in aourednik/historical-basemaps (riproducibilita' scientifica)"},"boundary_aourednik_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Boundary Aourednik Year","description":"Anno dello snapshot aourednik usato (uno dei 53 disponibili, -123000..2010)"},"boundary_aourednik_precision":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Boundary Aourednik Precision","description":"Precisione BORDERPRECISION dell'upstream aourednik (README historical-basemaps): 1=approssimato, 2=moderatamente preciso, 3=determinato da legge internazionale. Il valore 0 e' un edge-case legacy (4 feature upstream). Converte in confidence via PRECISION_CONFIDENCE (3->0.85, 2->0.70, 1->0.55, 0->0.45)."},"boundary_ne_iso_a3":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Boundary Ne Iso A3","description":"ISO_A3 del paese Natural Earth quando il match passa per NE"},"confidence_score":{"type":"number","title":"Confidence Score","description":"Affidabilità complessiva 0.0-1.0"},"status":{"type":"string","title":"Status","description":"confirmed, uncertain, o disputed"},"territory_changes":{"items":{"$ref":"#/components/schemas/TerritoryChangeResponse"},"type":"array","title":"Territory Changes","description":"Cambi territoriali (ETHICS-002)"},"sources":{"items":{"$ref":"#/components/schemas/SourceResponse"},"type":"array","title":"Sources","description":"Fonti bibliografiche"},"ethical_notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ethical Notes","description":"Note sulla governance etica del dato"},"continent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Continent","description":"Continente derivato dalle coordinate della capitale"}},"type":"object","required":["id","entity_type","year_start","name_original","name_original_lang","confidence_score","status"],"title":"EntityResponse","description":"Risposta completa per una singola entità — formato da ADR-002.","example":{"boundary_ne_iso_a3":"ITA","boundary_source":"natural_earth","capital":{"lat":41.9028,"lon":12.4964,"name":"Roma"},"confidence_score":0.9,"continent":"Europe","entity_type":"empire","id":1,"name_original":"Imperium Romanum","name_original_lang":"la","status":"confirmed","year_end":476,"year_start":-27}},"EventStatsInfo":{"properties":{"total_events":{"type":"integer","title":"Total Events"},"events_with_day":{"type":"integer","title":"Events With Day"},"events_with_month":{"type":"integer","title":"Events With Month"},"date_coverage_unique_days":{"type":"integer","title":"Date Coverage Unique Days"},"date_coverage_pct":{"type":"number","title":"Date Coverage Pct"},"date_precision_breakdown":{"additionalProperties":{"type":"integer"},"type":"object","title":"Date Precision Breakdown"}},"type":"object","required":["total_events","events_with_day","events_with_month","date_coverage_unique_days","date_coverage_pct","date_precision_breakdown"],"title":"EventStatsInfo","description":"Statistiche aggregate eventi storici."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HealthResponse":{"properties":{"status":{"type":"string","title":"Status","description":"'ok' | 'degraded' | 'down'"},"version":{"type":"string","title":"Version"},"environment":{"type":"string","title":"Environment","description":"development, staging, production","default":"unknown"},"database":{"type":"string","title":"Database","description":"Tipo e stato del database"},"entity_count":{"type":"integer","title":"Entity Count"},"uptime_seconds":{"type":"number","title":"Uptime Seconds","description":"Secondi dall'avvio del processo","default":0.0},"check_duration_ms":{"type":"number","title":"Check Duration Ms","description":"Tempo speso in questo health check","default":0.0},"sentry_active":{"type":"boolean","title":"Sentry Active","description":"Se Sentry sta catturando errori","default":false},"checks":{"additionalProperties":{"type":"string"},"type":"object","title":"Checks","description":"Esito delle sotto-verifiche (database, seed, rate_limit, ...)"}},"type":"object","required":["status","version","database","entity_count"],"title":"HealthResponse","description":"Stato di salute del servizio."},"NameVariantResponse":{"properties":{"name":{"type":"string","title":"Name","description":"Nome nella lingua indicata"},"lang":{"type":"string","title":"Lang","description":"Codice lingua ISO 639-1"},"period_start":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Period Start","description":"Anno inizio uso (negativo = a.C.)"},"period_end":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Period End","description":"Anno fine uso"},"context":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Context","description":"Contesto storico-politico del nome"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"Fonte bibliografica"}},"type":"object","required":["name","lang"],"title":"NameVariantResponse","description":"Variante di nome con contesto storico (ETHICS-001)."},"PaginatedEntityResponse":{"properties":{"count":{"type":"integer","title":"Count","description":"Numero totale di risultati"},"limit":{"type":"integer","title":"Limit","description":"Limite per pagina"},"offset":{"type":"integer","title":"Offset","description":"Offset corrente"},"entities":{"items":{"$ref":"#/components/schemas/EntityResponse"},"type":"array","title":"Entities"}},"type":"object","required":["count","limit","offset","entities"],"title":"PaginatedEntityResponse","description":"Risposta paginata per liste di entità."},"SearchResponse":{"properties":{"count":{"type":"integer","title":"Count"},"results":{"items":{"$ref":"#/components/schemas/SearchResult"},"type":"array","title":"Results"}},"type":"object","required":["count","results"],"title":"SearchResponse"},"SearchResult":{"properties":{"id":{"type":"integer","title":"Id"},"name_original":{"type":"string","title":"Name Original"},"name_original_lang":{"type":"string","title":"Name Original Lang"},"entity_type":{"type":"string","title":"Entity Type"},"year_start":{"type":"integer","title":"Year Start"},"year_end":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Year End"},"status":{"type":"string","title":"Status"},"confidence_score":{"type":"number","title":"Confidence Score"},"continent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Continent"}},"type":"object","required":["id","name_original","name_original_lang","entity_type","year_start","year_end","status","confidence_score"],"title":"SearchResult"},"SourceResponse":{"properties":{"citation":{"type":"string","title":"Citation","description":"Citazione bibliografica"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"URL della fonte"},"source_type":{"type":"string","title":"Source Type","description":"Tipo: primary, secondary, academic"}},"type":"object","required":["citation","source_type"],"title":"SourceResponse","description":"Fonte bibliografica tracciabile."},"StatsResponse":{"properties":{"total_entities":{"type":"integer","title":"Total Entities"},"types":{"items":{"$ref":"#/components/schemas/TypeInfo"},"type":"array","title":"Types"},"status_counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Status Counts"},"year_range":{"additionalProperties":{"type":"integer"},"type":"object","title":"Year Range"},"avg_confidence":{"type":"number","title":"Avg Confidence"},"total_sources":{"type":"integer","title":"Total Sources"},"total_territory_changes":{"type":"integer","title":"Total Territory Changes"},"disputed_count":{"type":"integer","title":"Disputed Count"},"continents":{"items":{"$ref":"#/components/schemas/ContinentInfo"},"type":"array","title":"Continents","default":[]},"events":{"anyOf":[{"$ref":"#/components/schemas/EventStatsInfo"},{"type":"null"}]}},"type":"object","required":["total_entities","types","status_counts","year_range","avg_confidence","total_sources","total_territory_changes","disputed_count"],"title":"StatsResponse"},"TerritoryChangeResponse":{"properties":{"year":{"type":"integer","title":"Year","description":"Anno del cambio (negativo = a.C.)"},"region":{"type":"string","title":"Region","description":"Regione coinvolta"},"change_type":{"type":"string","title":"Change Type","description":"Tipo: CONQUEST_MILITARY, TREATY, COLONIZATION, etc."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Descrizione del cambio"},"population_affected":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Population Affected","description":"Stima popolazione colpita"},"confidence_score":{"type":"number","title":"Confidence Score","description":"Affidabilità dato 0.0-1.0"}},"type":"object","required":["year","region","change_type","confidence_score"],"title":"TerritoryChangeResponse","description":"Cambio territoriale con tipo esplicito (ETHICS-002)."},"TypeInfo":{"properties":{"type":{"type":"string","title":"Type"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["type","count"],"title":"TypeInfo"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"tags":[{"name":"entità","description":"CRUD e ricerca entità geopolitiche storiche"},{"name":"relazioni","description":"Contemporanei, correlazioni e confronto tra entità"},{"name":"esportazione","description":"Export GeoJSON, CSV e Timeline"},{"name":"sistema","description":"Health check e diagnostica"}]}