{"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 | **1,034** | `/v1/entities` |\n| Historical events | **643** | `/v1/events` |\n| Historical periods | **55** | `/v1/periods` |\n| Historical cities | **110** | `/v1/cities` |\n| Archaeological sites | **1,249** | `/v1/sites` |\n| Historical rulers | **105** | `/v1/rulers` |\n| Historical languages | **29** | `/v1/languages` |\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.it\"\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.it/v1/snapshot/year/1492 | jq .periods\ncurl -s https://atlaspi.it/v1/entities/1/similar | jq '.similar[0]'\ncurl -s https://atlaspi.it/v1/periods/by-slug/bronze-age\ncurl -s \"https://atlaspi.it/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.99.114"},"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":-4000000},{"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":500,"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"},{"name":"include_deprecated","in":"query","required":false,"schema":{"type":"boolean","description":"Includi entità marcate status='deprecated' (ADR-005)","default":false,"title":"Include Deprecated"},"description":"Includi entità marcate status='deprecated' (ADR-005)"}],"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**⚡ PERFORMANCE TIP for AI agents and scrapers**: when you only need names/types/years/coordinates and NOT the full polygon geometry, pass `exclude_geometry=true` — the response is **~10x faster** at limit≥100 (e.g. `?limit=300&exclude_geometry=true` ≈ 250ms vs 2.5s). For an even lighter overview of ALL entities in one shot, prefer `/v1/entities/light`. Fetch the full polygon for a single entity later via `/v1/entities/{id}` or render via `/v1/render`.\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- `exclude_geometry` — omit `boundary_geojson` for ~10x speedup at high limit\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":"year","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":2100,"minimum":-5000},{"type":"null"}],"description":"Entities active in this year","title":"Year"},"description":"Entities active in this year"},{"name":"entity_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"description":"Exact entity_type match (empire, kingdom, sultanate, ...)","title":"Entity Type"},"description":"Exact entity_type match (empire, kingdom, sultanate, ...)"},{"name":"continent","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"description":"Filter by derived continent from capital coordinates","title":"Continent"},"description":"Filter by derived continent from capital coordinates"},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["confirmed","uncertain","disputed"],"type":"string"},{"type":"null"}],"description":"Filter by status (confirmed / uncertain / disputed)","title":"Status"},"description":"Filter by status (confirmed / uncertain / disputed)"},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"ILIKE search on name_original + name_variants","title":"Search"},"description":"ILIKE search on name_original + name_variants"},{"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":"contains","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}],"description":"Point-in-polygon: 'lat,lon'. Restituisce entita' il cui boundary_geom contiene il punto (PostGIS ST_Contains, indice GiST). Esempio: ?contains=41.9,12.5 -> entita' con territorio che includeva Roma. PostGIS only — SQLite dev ritorna empty.","title":"Contains"},"description":"Point-in-polygon: 'lat,lon'. Restituisce entita' il cui boundary_geom contiene il punto (PostGIS ST_Contains, indice GiST). Esempio: ?contains=41.9,12.5 -> entita' con territorio che includeva Roma. PostGIS only — SQLite dev ritorna empty."},{"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":500,"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"},{"name":"include_deprecated","in":"query","required":false,"schema":{"type":"boolean","description":"Includi entità marcate status='deprecated' (ADR-005)","default":false,"title":"Include Deprecated"},"description":"Includi entità marcate status='deprecated' (ADR-005)"},{"name":"exclude_geometry","in":"query","required":false,"schema":{"type":"boolean","description":"Se true, omette `boundary_geojson` dalle entity (None in response) e ne defer-loada la colonna dal DB. Riduce la latenza a limit alto (~10x più veloce a limit=300). Per il polygon usa /v1/entities/{id}.","default":false,"title":"Exclude Geometry"},"description":"Se true, omette `boundary_geojson` dalle entity (None in response) e ne defer-loada la colonna dal DB. Riduce la latenza a limit alto (~10x più veloce a limit=300). Per il polygon usa /v1/entities/{id}."}],"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/light":{"get":{"tags":["entità"],"summary":"List ALL entities without boundary_geojson — optimized for map viewport","description":"Returns all historical entities with ONLY lightweight fields (id, name_original, entity_type, year range, capital coords, confidence, status). Excludes `boundary_geojson` which is the dominant payload driver. Single call returns ~1000 entities in ~200KB vs ~2MB+ from paginated `/v1/entities` (9 calls, ~17MB).\n\n**Primary use case**: frontend map bootstrap. Client loads ALL entities at once, filters client-side by year/type/continent. On click, frontend calls `/v1/entities/{id}` for full detail + boundary polygon.\n\n**Query params**:\n- `year` (optional): filter entities active in this year\n- `bbox` (optional): filter by capital-point-in-bbox (no polygon intersect here)\n\n**For AI agents**: use this first for 'give me an overview of all X', then fetch full detail on specific IDs as needed.","operationId":"list_entities_light_v1_entities_light_get","parameters":[{"name":"year","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":2100,"minimum":-5000},{"type":"null"}],"description":"Active in this year","title":"Year"},"description":"Active in this year"},{"name":"bbox","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Bbox"}},{"name":"include_deprecated","in":"query","required":false,"schema":{"type":"boolean","description":"Include status='deprecated' entities (ADR-005)","default":false,"title":"Include Deprecated"},"description":"Include status='deprecated' entities (ADR-005)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LightListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/entities/batch":{"get":{"tags":["entità"],"summary":"Fetch multiple entities by ID in a single request","description":"Batch endpoint for AI agents: given a comma-separated list of entity IDs, returns all matching entities in a single round-trip. Reduces latency significantly when an agent needs to display a timeline, comparison table, or collection of related entities.\n\n**Usage**: `GET /v1/entities/batch?ids=1,2,3,4,5` (max 100 per call)\n\n**Response shape**:\n```json\n{\n  \"requested\": 5,\n  \"found\": 4,\n  \"not_found\": [999],\n  \"entities\": [ ... full detail for each ID ... ]\n}\n```\n\n**Example**: the MCP client calls this when a user asks 'compare these 5 empires side-by-side'. One request instead of five, 5× faster.","operationId":"get_entities_batch_v1_entities_batch_get","parameters":[{"name":"ids","in":"query","required":true,"schema":{"type":"string","description":"Comma-separated entity IDs (max 100)","examples":["1,2,3","10,42,201,333"],"title":"Ids"},"description":"Comma-separated entity IDs (max 100)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResponse"}}}},"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/where-was":{"get":{"tags":["entità"],"summary":"Reverse-geocoding temporale: quali entità controllavano un punto in un anno","description":"Given a geographic point (lat, lon) and a year, returns all historical entities whose documented `boundary_geojson` contains that point. Primary use case: **genealogy / diaspora research** (\"my great-grandfather from Lviv in 1905 — which country was that?\"), historical tourism, and educational AI tutors.\n\n**Two modes**:\n- **Year-specific** (`?lat=X&lon=Y&year=Z`): entities controlling that point in year Z\n- **History timeline** (`?lat=X&lon=Y&include_history=true`): ALL entities that ever controlled that point, sorted chronologically — shows the full succession at that location from ancient times to today.\n\n**Backend**: PostgreSQL+PostGIS uses native `ST_Contains` (O(log n) with GiST index). SQLite dev uses shapely Python fallback. Semantic parity guaranteed within ~0.1° tolerance from polygon simplification.\n\n**For AI agents**: ideal for grounding \"where was X\" questions. After getting the entity list, follow up with `/v1/entities/{id}` for full context (boundaries, rulers, events).","operationId":"where_was_v1_where_was_get","parameters":[{"name":"lat","in":"query","required":true,"schema":{"type":"number","maximum":90,"minimum":-90,"description":"Latitudine del punto","title":"Lat"},"description":"Latitudine del punto"},{"name":"lon","in":"query","required":true,"schema":{"type":"number","maximum":180,"minimum":-180,"description":"Longitudine del punto","title":"Lon"},"description":"Longitudine del punto"},{"name":"year","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":2100,"minimum":-5000},{"type":"null"}],"description":"Anno di riferimento. Richiesto se include_history=false.","title":"Year"},"description":"Anno di riferimento. Richiesto se include_history=false."},{"name":"include_history","in":"query","required":false,"schema":{"type":"boolean","description":"Se true, ritorna tutte le entità che hanno controllato il punto storicamente (serie temporale). Se false, solo l'anno richiesto.","default":false,"title":"Include History"},"description":"Se true, ritorna tutte le entità che hanno controllato il punto storicamente (serie temporale). Se false, solo l'anno richiesto."}],"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"},{"name":"include_deprecated","in":"query","required":false,"schema":{"type":"boolean","description":"Includi entità marcate status='deprecated' (ADR-005)","default":false,"title":"Include Deprecated"},"description":"Includi entità marcate status='deprecated' (ADR-005)"}],"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":-4000000},{"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"},{"name":"include_deprecated","in":"query","required":false,"schema":{"type":"boolean","description":"Includi entità status='deprecated' (ADR-005: escluse di default)","default":false,"title":"Include Deprecated"},"description":"Includi entità status='deprecated' (ADR-005: escluse di default)"}],"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","parameters":[{"name":"include_deprecated","in":"query","required":false,"schema":{"type":"boolean","description":"Includi entità status='deprecated' (ADR-005: escluse di default)","default":false,"title":"Include Deprecated"},"description":"Includi entità status='deprecated' (ADR-005: escluse di default)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/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","parameters":[{"name":"include_deprecated","in":"query","required":false,"schema":{"type":"boolean","description":"Includi entità status='deprecated' (ADR-005: escluse di default)","default":false,"title":"Include Deprecated"},"description":"Includi entità status='deprecated' (ADR-005: escluse di default)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/export/sites.geojson":{"get":{"tags":["esportazione"],"summary":"Export archaeological sites as GeoJSON FeatureCollection","description":"Standard GeoJSON Points per tutti i siti archeologici / UNESCO. Compatibile con QGIS, Leaflet, Mapbox, D3. Filtro opzionale `year` (siti con documentata attivita' in quell'anno).","operationId":"export_sites_geojson_v1_export_sites_geojson_get","parameters":[{"name":"year","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":2100,"minimum":-4000000},{"type":"null"}],"title":"Year"}},{"name":"unesco_only","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Unesco Only"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/export/rulers.geojson":{"get":{"tags":["esportazione"],"summary":"Export historical rulers as GeoJSON","description":"GeoJSON Points per rulers — geometry derivata da capitale dell'entita' governata (se `entity_id` risolvibile). Per rulers senza entita' mappata, geometry = null (feature incluso per completezza). Filtro `year` per rulers in carica in quell'anno.","operationId":"export_rulers_geojson_v1_export_rulers_geojson_get","parameters":[{"name":"year","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":2100,"minimum":-5000},{"type":"null"}],"title":"Year"}},{"name":"region","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":50},{"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/export/languages.geojson":{"get":{"tags":["esportazione"],"summary":"Export historical languages as GeoJSON","description":"GeoJSON Points usando `center_lat/center_lon`. Filtro opzionale per year (lingue parlate in quell'anno), family, vitality_status.","operationId":"export_languages_geojson_v1_export_languages_geojson_get","parameters":[{"name":"year","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":2100,"minimum":-10000},{"type":"null"}],"title":"Year"}},{"name":"family","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Family"}},{"name":"vitality_status","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":30},{"type":"null"}],"title":"Vitality Status"}}],"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}/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":{"$ref":"#/components/schemas/EventListResponse"}}}},"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/sites":{"get":{"tags":["siti archeologici"],"summary":"List archaeological / cultural sites (paginated)","description":"Returns a paginated list of archaeological sites and historical monuments (UNESCO World Heritage, ruins, sacred sites, ancient cities, pyramids, etc.). Distinct from `/v1/entities` (political states) and `/v1/cities` (urban centers with political life).\n\n**Filters** (all optional):\n- `year` — sites with documented use in this year (date_start <= Y <= date_end)\n- `site_type` — ruins, monument, temple, pyramid, sacred_site, etc.\n- `entity_id` — sites belonging to a specific historical entity\n- `unesco_only=true` — only UNESCO World Heritage Sites\n- `status` — confirmed, uncertain, disputed\n\n**For AI agents**: use alongside `/v1/entities/{id}/sites` (not yet available) to discover material heritage within a historical entity.","operationId":"list_sites_v1_sites_get","parameters":[{"name":"year","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":2100,"minimum":-10000},{"type":"null"}],"description":"Site active in this year","title":"Year"},"description":"Site active in this year"},{"name":"site_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Site Type"}},{"name":"entity_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"title":"Entity Id"}},{"name":"unesco_only","in":"query","required":false,"schema":{"type":"boolean","description":"Filter to only UNESCO sites","default":false,"title":"Unesco Only"},"description":"Filter to only UNESCO sites"},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["confirmed","uncertain","disputed"],"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"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/sites/types":{"get":{"tags":["siti archeologici"],"summary":"List site types with counts","description":"Enum of SiteType values with count of sites per type.","operationId":"site_types_v1_sites_types_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/sites/unesco":{"get":{"tags":["siti archeologici"],"summary":"UNESCO World Heritage Sites only","description":"Shortcut for `/v1/sites?unesco_only=true`. Returns all sites with a non-null `unesco_id`, ordered by inscription year descending.","operationId":"unesco_sites_v1_sites_unesco_get","parameters":[{"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/sites/nearby":{"get":{"tags":["siti archeologici"],"summary":"Archaeological sites near coordinates","description":"Find archaeological / cultural sites within `radius` km of a lat/lon point. Ordered by distance. Python haversine (dev/SQLite) — PostGIS native `ST_DWithin` in prod adds minimal speedup since sites are point-located (no polygon complexity).","operationId":"sites_nearby_v1_sites_nearby_get","parameters":[{"name":"lat","in":"query","required":true,"schema":{"type":"number","maximum":90,"minimum":-90,"title":"Lat"}},{"name":"lon","in":"query","required":true,"schema":{"type":"number","maximum":180,"minimum":-180,"title":"Lon"}},{"name":"radius","in":"query","required":false,"schema":{"type":"number","maximum":5000,"minimum":1,"description":"Radius in km","default":50,"title":"Radius"},"description":"Radius in km"},{"name":"site_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Site Type"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/sites/{site_id}":{"get":{"tags":["siti archeologici"],"summary":"Site detail","description":"Full detail for a single archaeological site by numeric ID.","operationId":"get_site_v1_sites__site_id__get","parameters":[{"name":"site_id","in":"path","required":true,"schema":{"type":"integer","title":"Site Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/rulers":{"get":{"tags":["sovrani"],"summary":"List historical rulers (paginated)","description":"Returns historical rulers: emperors, kings, sultans, khagan, presidents, dictators. Indexed by name_original (in native script). Use filters to narrow by region, dynasty, title, reign year.\n\n**ETHICS**: `ethical_notes` documents violence, genocides, slavery explicitly — no euphemism. Leopoldo II's Congo atrocities, Qin Shi Huangdi's book-burning, Aurangzeb's temple destruction all surfaced.","operationId":"list_rulers_v1_rulers_get","parameters":[{"name":"region","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Region"}},{"name":"dynasty","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Dynasty"}},{"name":"title","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Title"}},{"name":"entity_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"title":"Entity Id"}},{"name":"year","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":2100,"minimum":-5000},{"type":"null"}],"description":"Ruler in reign in this year","title":"Year"},"description":"Ruler in reign in this year"},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["confirmed","uncertain","disputed","legendary"],"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"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/rulers/at-year/{year}":{"get":{"tags":["sovrani"],"summary":"Rulers in office in a given year","description":"Returns all historical rulers who were actively reigning in the specified year. Optionally filtered by region.\n\nCritical for 'who ruled X in year Y' queries — AI agents can answer 'Chi regnava in Cina nel 1200?' directly.","operationId":"rulers_at_year_v1_rulers_at_year__year__get","parameters":[{"name":"year","in":"path","required":true,"schema":{"type":"integer","title":"Year"}},{"name":"region","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":50},{"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/rulers/by-entity/{entity_id}":{"get":{"tags":["sovrani"],"summary":"Rulers of a specific historical entity","description":"All rulers linked to a specific GeoEntity (via entity_id FK).","operationId":"rulers_by_entity_v1_rulers_by_entity__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":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/rulers/{ruler_id}":{"get":{"tags":["sovrani"],"summary":"Ruler detail","description":"Full biography, sources, ethical_notes.","operationId":"get_ruler_v1_rulers__ruler_id__get","parameters":[{"name":"ruler_id","in":"path","required":true,"schema":{"type":"integer","title":"Ruler Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/languages":{"get":{"tags":["lingue"],"summary":"List historical languages (paginated)","operationId":"list_languages_v1_languages_get","parameters":[{"name":"family","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Family"}},{"name":"region","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Region"}},{"name":"iso_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}],"title":"Iso Code"}},{"name":"vitality_status","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":30},{"type":"null"}],"title":"Vitality Status"}},{"name":"year","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":2100,"minimum":-10000},{"type":"null"}],"description":"Language active in this year","title":"Year"},"description":"Language active in this year"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"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/languages/at-year/{year}":{"get":{"tags":["lingue"],"summary":"Lingue attive in un dato anno","operationId":"languages_at_year_v1_languages_at_year__year__get","parameters":[{"name":"year","in":"path","required":true,"schema":{"type":"integer","title":"Year"}},{"name":"region","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"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/languages/families":{"get":{"tags":["lingue"],"summary":"Language families with counts","operationId":"language_families_v1_languages_families_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/languages/{lang_id}":{"get":{"tags":["lingue"],"summary":"Language detail","operationId":"get_language_v1_languages__lang_id__get","parameters":[{"name":"lang_id","in":"path","required":true,"schema":{"type":"integer","title":"Lang Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/render/snapshot/{year}.png":{"get":{"tags":["rendering"],"summary":"Render PNG del mondo in un dato anno","description":"Returns a PNG image showing all historical entities active in the given year, with boundaries colored by status (confirmed/uncertain/disputed).\n\n**Primary use case**: AI agents that want to insert a visual into chat ('show me Europe in 800 CE'). Also useful for social sharing thumbnails (Open Graph) and PDF reports.\n\n**Backend**: matplotlib with 'Agg' backend (no GUI). Cached 1h.","operationId":"render_snapshot_png_v1_render_snapshot__year__png_get","parameters":[{"name":"year","in":"path","required":true,"schema":{"type":"integer","title":"Year"}},{"name":"width","in":"query","required":false,"schema":{"type":"integer","maximum":3000,"minimum":200,"description":"Image width in pixels","default":1200,"title":"Width"},"description":"Image width in pixels"},{"name":"height","in":"query","required":false,"schema":{"type":"integer","maximum":2000,"minimum":100,"description":"Image height in pixels","default":600,"title":"Height"},"description":"Image height in pixels"},{"name":"title","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Optional title override","title":"Title"},"description":"Optional title override"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/render/entity/{entity_id}.png":{"get":{"tags":["rendering"],"summary":"Render PNG del boundary di una singola entity","description":"Focused map showing a single entity's boundary.","operationId":"render_entity_png_v1_render_entity__entity_id__png_get","parameters":[{"name":"entity_id","in":"path","required":true,"schema":{"type":"integer","title":"Entity Id"}},{"name":"width","in":"query","required":false,"schema":{"type":"integer","maximum":2000,"minimum":200,"default":800,"title":"Width"}},{"name":"height","in":"query","required":false,"schema":{"type":"integer","maximum":1500,"minimum":100,"default":600,"title":"Height"}}],"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":"include_deprecated","in":"query","required":false,"schema":{"type":"boolean","description":"Includi entità status='deprecated' (ADR-005: escluse di default)","default":false,"title":"Include Deprecated"},"description":"Includi entità status='deprecated' (ADR-005: escluse di default)"},{"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":"include_deprecated","in":"query","required":false,"schema":{"type":"boolean","description":"Includi entità status='deprecated' (ADR-005: escluse di default)","default":false,"title":"Include Deprecated"},"description":"Includi entità status='deprecated' (ADR-005: escluse di default)"},{"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"}}}}}}},"/v1/feedback":{"post":{"tags":["feedback"],"summary":"Submit feedback su entita'/evento/citta'","description":"Sottometti una correzione, segnalazione di fonte mancante, boundary dispute, bias report, ecc. \n\nTutti i feedback vanno in stato `pending`. La review umana e' richiesta per contenuti storici (ETHICS).\n\n**Rate limit**: 5/min per IP anonimo, 30/min per submitter identificato (con submitter_id non-vuoto).\n\nEndpoint pubblico, no auth richiesta.","operationId":"submit_feedback_v1_feedback_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackSubmitRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["feedback"],"summary":"Lista pubblica feedback (trasparenza)","description":"Filtri opzionali per status/category/entity_id/submitter_type. Pubblicamente accessibile per permettere ad agenti AI di leggere il feedback pending e fare cross-validation.","operationId":"list_feedback_v1_feedback_get","parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filtra per status. Se omesso, mostra solo pending/under_review/accepted (rejected/duplicate visibili solo con filter esplicito).","title":"Status"},"description":"Filtra per status. Se omesso, mostra solo pending/under_review/accepted (rejected/duplicate visibili solo con filter esplicito)."},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filtra per categoria","title":"Category"},"description":"Filtra per categoria"},{"name":"entity_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Filtra per entity_id","title":"Entity Id"},"description":"Filtra per entity_id"},{"name":"submitter_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filtra per submitter_type","title":"Submitter Type"},"description":"Filtra per submitter_type"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"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":{"$ref":"#/components/schemas/FeedbackListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/feedback/stats":{"get":{"tags":["feedback"],"summary":"Aggregate statistics per status/category","operationId":"feedback_stats_v1_feedback_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackStatsResponse"}}}}}}},"/v1/feedback/contributors":{"get":{"tags":["feedback"],"summary":"Leaderboard contributori","description":"Top submitter per numero di feedback accettati. Email mascherate per privacy. Usato per gamification + accountability.","operationId":"contributors_v1_feedback_contributors_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ContributorRow"},"title":"Response Contributors V1 Feedback Contributors Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/feedback/{feedback_id}":{"get":{"tags":["feedback"],"summary":"Dettaglio singolo feedback","operationId":"get_feedback_v1_feedback__feedback_id__get","parameters":[{"name":"feedback_id","in":"path","required":true,"schema":{"type":"integer","title":"Feedback Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["feedback"],"summary":"Review feedback (admin only)","description":"Aggiorna lo status di un feedback. Richiede header `X-Admin-Token` corrispondente a env var `ATLASPI_ADMIN_TOKEN`.","operationId":"review_feedback_v1_feedback__feedback_id__patch","parameters":[{"name":"feedback_id","in":"path","required":true,"schema":{"type":"integer","title":"Feedback Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackReviewRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agents/insights/overview":{"get":{"tags":["agents"],"summary":"Overview di traffico AI agent","operationId":"overview_agents_insights_overview_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentOverview"}}}}}}},"/agents/insights/by-family":{"get":{"tags":["agents"],"summary":"Breakdown per famiglia AI agent","operationId":"by_family_agents_insights_by_family_get","parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":365,"minimum":1,"description":"Finestra temporale in giorni","default":30,"title":"Days"},"description":"Finestra temporale in giorni"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/FamilyRow"},"title":"Response By Family Agents Insights By Family Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agents/insights/top-queries":{"get":{"tags":["agents"],"summary":"Top query patterns dagli AI agents","operationId":"top_queries_agents_insights_top_queries_get","parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":365,"minimum":1,"default":30,"title":"Days"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":25,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TopQueryRow"},"title":"Response Top Queries Agents Insights Top Queries Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agents/insights/zero-results":{"get":{"tags":["agents"],"summary":"Queries che hanno 404 / 0 risultati (gap analysis)","operationId":"zero_results_agents_insights_zero_results_get","parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":365,"minimum":1,"default":30,"title":"Days"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ZeroResultRow"},"title":"Response Zero Results Agents Insights Zero Results Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/embed/badge.svg":{"get":{"tags":["embed"],"summary":"SVG badge per embed in blog/wiki","description":"Genera un badge SVG (400x88) per linkare a una entita' AtlasPI.\n\nEsempio:\n```html\n<a href='https://atlaspi.it/app?entity=178'>\n  <img src='https://atlaspi.it/embed/badge.svg?entity=178' alt='Ptolemaic Kingdom on AtlasPI'>\n</a>\n```\n\nCache 1h client + 6h CDN.","operationId":"badge_svg_embed_badge_svg_get","parameters":[{"name":"entity","in":"query","required":true,"schema":{"type":"integer","minimum":1,"description":"ID entita'","title":"Entity"},"description":"ID entita'"},{"name":"style","in":"query","required":false,"schema":{"type":"string","pattern":"^(dark|light)$","description":"dark | light","default":"dark","title":"Style"},"description":"dark | light"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/embed/preview/{entity_id}":{"get":{"tags":["embed"],"summary":"HTML preview con snippet copy-paste per embed","operationId":"badge_preview_embed_preview__entity_id__get","parameters":[{"name":"entity_id","in":"path","required":true,"schema":{"type":"integer","title":"Entity Id"}}],"responses":{"200":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/citations/data":{"get":{"tags":["citations"],"summary":"Citation tracking JSON","operationId":"citations_data_citations_data_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CitationsResponse"}}}}}}},"/citations/refresh":{"post":{"tags":["citations"],"summary":"Force refresh citation cache (admin only)","operationId":"citations_refresh_citations_refresh_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CitationsResponse"}}}}}}},"/citations":{"get":{"tags":["citations"],"summary":"HTML page con paper che citano AtlasPI","description":"HTML public page.","operationId":"citations_page_citations_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"AgentOverview":{"properties":{"total_requests":{"type":"integer","title":"Total Requests"},"distinct_agents":{"type":"integer","title":"Distinct Agents"},"total_ai_agent_requests":{"type":"integer","title":"Total Ai Agent Requests"},"by_category":{"additionalProperties":{"type":"integer"},"type":"object","title":"By Category"},"last_24h_ai_requests":{"type":"integer","title":"Last 24H Ai Requests"},"last_7d_ai_requests":{"type":"integer","title":"Last 7D Ai Requests"},"most_active_family":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Most Active Family"}},"type":"object","required":["total_requests","distinct_agents","total_ai_agent_requests","by_category","last_24h_ai_requests","last_7d_ai_requests","most_active_family"],"title":"AgentOverview"},"BatchResponse":{"properties":{"requested":{"type":"integer","title":"Requested"},"found":{"type":"integer","title":"Found"},"not_found":{"items":{"type":"integer"},"type":"array","title":"Not Found"},"entities":{"items":{"$ref":"#/components/schemas/EntityResponse"},"type":"array","title":"Entities"}},"type":"object","required":["requested","found","entities"],"title":"BatchResponse","description":"Risposta di /v1/entities/batch — fetch multiplo per ID in un round-trip."},"CapitalHistoryResponse":{"properties":{"name":{"type":"string","title":"Name","description":"Nome della capitale (lingua locale, ETHICS-001)"},"lat":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Lat","description":"Latitudine (null per corte itinerante)"},"lon":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Lon","description":"Longitudine"},"year_start":{"type":"integer","title":"Year Start","description":"Anno inizio periodo come capitale"},"year_end":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Year End","description":"Anno fine (null = ultima/attuale)"},"ordering":{"type":"integer","title":"Ordering","description":"Sort secondario per periodi sovrapposti","default":0},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes","description":"Spiegazione del ruolo"}},"type":"object","required":["name","year_start"],"title":"CapitalHistoryResponse","description":"Capitale storica con range temporale (v6.87 — ADR-004).\n\nPer polities long-duration con capitali multiple (Ottoman, HRE, Mughal,\nMing, Song, Solomonic Ethiopia, ecc.). Permette query 'capital of X\nin year Y' senza anacronismo.\n\n`lat/lon` può essere null per polities con corte itinerante.\n`year_end` null = capitale attuale o ultima.\n`ordering` per casi sovrapposti (es. dual monarchy Wien+Budapest)."},"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à."},"Citation":{"properties":{"source":{"type":"string","title":"Source"},"type":{"type":"string","title":"Type"},"title":{"type":"string","title":"Title"},"authors":{"items":{"type":"string"},"type":"array","title":"Authors","default":[]},"year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Year"},"doi":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Doi"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"cited_doi":{"type":"string","title":"Cited Doi"}},"type":"object","required":["source","type","title","cited_doi"],"title":"Citation"},"CitationsResponse":{"properties":{"total":{"type":"integer","title":"Total"},"by_source":{"additionalProperties":{"type":"integer"},"type":"object","title":"By Source"},"by_type":{"additionalProperties":{"type":"integer"},"type":"object","title":"By Type"},"items":{"items":{"$ref":"#/components/schemas/Citation"},"type":"array","title":"Items"},"cited_dois":{"items":{"type":"string"},"type":"array","title":"Cited Dois"}},"type":"object","required":["total","by_source","by_type","items","cited_dois"],"title":"CitationsResponse"},"ContinentInfo":{"properties":{"continent":{"type":"string","title":"Continent"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["continent","count"],"title":"ContinentInfo"},"ContributorRow":{"properties":{"submitter_id":{"type":"string","title":"Submitter Id"},"submitter_type":{"type":"string","title":"Submitter Type"},"total_submissions":{"type":"integer","title":"Total Submissions"},"accepted":{"type":"integer","title":"Accepted"},"pending":{"type":"integer","title":"Pending"},"rejected":{"type":"integer","title":"Rejected"},"reputation":{"type":"number","title":"Reputation"}},"type":"object","required":["submitter_id","submitter_type","total_submissions","accepted","pending","rejected","reputation"],"title":"ContributorRow"},"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, approximate_circle, historical_approximation"},"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_reference_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Boundary Reference Year","description":"Anno di riferimento del polygon. Il boundary è UNO snapshot STATICO per l'intero lifespan dell'entità: interrogando un anno diverso da questo, i confini mostrati possono essere anacronistici (es. Mughal alla massima estensione ~1700 anche per query sul 1550). NULL = anno di riferimento non noto (approssimazione generica). Oggi coincide con boundary_aourednik_year quando la provenienza è aourednik."},"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"},"wikidata_qid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Wikidata Qid","description":"Wikidata Q-ID di riferimento (formato 'Q12345'). Null se nessun match high-confidence è stato trovato (audit v4, v6.69)."},"capital_history":{"items":{"$ref":"#/components/schemas/CapitalHistoryResponse"},"type":"array","title":"Capital History","description":"Cronologia capitali per polities long-duration (ADR-004). Vuoto se l'entity ha solo `capital` singola. Ordinato per year_start ASC, poi ordering."}},"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","wikidata_qid":"Q2277","year_end":476,"year_start":-27}},"EventListResponse":{"properties":{"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"events":{"items":{"$ref":"#/components/schemas/EventSummaryResponse"},"type":"array","title":"Events"}},"type":"object","required":["total","limit","offset","events"],"title":"EventListResponse","description":"Risposta di /v1/events (list)."},"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."},"EventSummaryResponse":{"properties":{"id":{"type":"integer","title":"Id"},"name_original":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name Original"},"name_original_lang":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name Original Lang"},"event_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Event Type"},"year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Year"},"year_end":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Year End"},"month":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Month"},"day":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Day"},"date_precision":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date Precision"},"iso_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Iso Date"},"location_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location Name"},"location_lat":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Location Lat"},"location_lon":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Location Lon"},"main_actor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Main Actor"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"},"confidence_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence Score"},"known_silence":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Known Silence"}},"type":"object","required":["id"],"title":"EventSummaryResponse","description":"Evento storico in forma compatta (liste) — mirror di _event_summary."},"FamilyRow":{"properties":{"family":{"type":"string","title":"Family"},"category":{"type":"string","title":"Category"},"request_count":{"type":"integer","title":"Request Count"},"unique_paths":{"type":"integer","title":"Unique Paths"},"last_seen":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Seen"}},"type":"object","required":["family","category","request_count","unique_paths","last_seen"],"title":"FamilyRow"},"FeedbackListResponse":{"properties":{"total":{"type":"integer","title":"Total"},"count":{"type":"integer","title":"Count"},"offset":{"type":"integer","title":"Offset"},"limit":{"type":"integer","title":"Limit"},"items":{"items":{"$ref":"#/components/schemas/FeedbackResponse"},"type":"array","title":"Items"}},"type":"object","required":["total","count","offset","limit","items"],"title":"FeedbackListResponse"},"FeedbackResponse":{"properties":{"id":{"type":"integer","title":"Id"},"created_at":{"type":"string","title":"Created At"},"entity_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Entity Id"},"event_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Event Id"},"city_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"City Id"},"field_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Field Name"},"category":{"type":"string","title":"Category"},"submitter_type":{"type":"string","title":"Submitter Type"},"submitter_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Submitter Id"},"submitter_reputation":{"type":"number","title":"Submitter Reputation"},"current_value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Value"},"suggested_value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Suggested Value"},"citation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Citation"},"reasoning":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reasoning"},"confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence"},"status":{"type":"string","title":"Status"},"reviewed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reviewed At"},"review_notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Review Notes"},"applied_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Applied At"},"applied_in_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Applied In Version"}},"type":"object","required":["id","created_at","entity_id","event_id","city_id","field_name","category","submitter_type","submitter_id","submitter_reputation","current_value","suggested_value","citation","reasoning","confidence","status","reviewed_at","review_notes","applied_at","applied_in_version"],"title":"FeedbackResponse","description":"Schema response per GET /v1/feedback/{id}."},"FeedbackReviewRequest":{"properties":{"status":{"type":"string","title":"Status"},"review_notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Review Notes"},"applied_in_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Applied In Version"}},"type":"object","required":["status"],"title":"FeedbackReviewRequest","description":"Schema per PATCH /v1/feedback/{id} (admin)."},"FeedbackStatsResponse":{"properties":{"total":{"type":"integer","title":"Total"},"by_status":{"additionalProperties":{"type":"integer"},"type":"object","title":"By Status"},"by_category":{"additionalProperties":{"type":"integer"},"type":"object","title":"By Category"},"by_submitter_type":{"additionalProperties":{"type":"integer"},"type":"object","title":"By Submitter Type"},"last_24h":{"type":"integer","title":"Last 24H"},"last_7d":{"type":"integer","title":"Last 7D"}},"type":"object","required":["total","by_status","by_category","by_submitter_type","last_24h","last_7d"],"title":"FeedbackStatsResponse"},"FeedbackSubmitRequest":{"properties":{"entity_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Entity Id","description":"ID entita' (geo_entities)"},"event_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Event Id","description":"ID evento (historical_events)"},"city_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"City Id","description":"ID citta' (historical_cities)"},"field_name":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Field Name","description":"Campo specifico (es. 'year_end', 'boundary_geojson')"},"category":{"type":"string","title":"Category","description":"Categoria. Uno di: ['bias_report', 'boundary_dispute', 'ethics_concern', 'incorrect_data', 'missing_entity', 'missing_source', 'other', 'translation_error']"},"submitter_type":{"type":"string","title":"Submitter Type","description":"Tipo submitter. Uno di: ['ai_agent', 'anonymous', 'bot', 'human']"},"submitter_id":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Submitter Id","description":"Email umano | nome agente AI | handle pubblico"},"current_value":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"title":"Current Value","description":"Valore attuale (snapshot). Max 4000 chars."},"suggested_value":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"title":"Suggested Value","description":"Valore corretto proposto. Max 4000 chars."},"citation":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Citation","description":"Riferimento bibliografico/accademico. Max 2000 chars."},"reasoning":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"title":"Reasoning","description":"Spiegazione breve (1-3 frasi). Max 4000 chars."},"confidence":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Confidence","description":"Self-reported confidence (0.0-1.0)"}},"type":"object","required":["category","submitter_type"],"title":"FeedbackSubmitRequest","description":"Schema per POST /v1/feedback."},"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."},"LightEntityResponse":{"properties":{"id":{"type":"integer","title":"Id"},"name_original":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name Original"},"name_original_lang":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name Original Lang"},"entity_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Type"},"year_start":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Year Start"},"year_end":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Year End"},"capital_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Capital Name"},"capital_lat":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Capital Lat"},"capital_lon":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Capital Lon"},"confidence_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence Score"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"},"continent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Continent","description":"Continente derivato dalle coordinate capitale"}},"type":"object","required":["id"],"title":"LightEntityResponse","description":"Entità in forma leggera (senza boundary_geojson) — vedi /v1/entities/light."},"LightListResponse":{"properties":{"total":{"type":"integer","title":"Total"},"count":{"type":"integer","title":"Count","description":"DEPRECATED — alias di total (retro-compat)"},"entities":{"items":{"$ref":"#/components/schemas/LightEntityResponse"},"type":"array","title":"Entities"}},"type":"object","required":["total","count","entities"],"title":"LightListResponse","description":"Risposta di /v1/entities/light — bootstrap mappa / overview agent."},"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":{"total":{"type":"integer","title":"Total","description":"Numero totale di risultati che matchano i filtri (prima di limit/offset)"},"count":{"type":"integer","title":"Count","description":"DEPRECATED (v6.66) — alias di `total`. Sarà rimosso in v6.68."},"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"},"hint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hint","description":"Presente solo con total=0 su ricerche per nome: suggerisce il retry via /v1/search/fuzzy"}},"type":"object","required":["total","count","limit","offset","entities"],"title":"PaginatedEntityResponse","description":"Risposta paginata per liste di entità.\n\nv6.66 FIX 4: include sia `total` (standard) sia `count` (legacy).\n`count` è deprecato ma restituito per retro-compatibilità per 1-2 release."},"SearchResponse":{"properties":{"total":{"type":"integer","title":"Total"},"count":{"type":"integer","title":"Count"},"results":{"items":{"$ref":"#/components/schemas/SearchResult"},"type":"array","title":"Results"},"hint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hint"}},"type":"object","required":["total","count","results"],"title":"SearchResponse","description":"Risposta search.\n\nv6.66 FIX 4: include sia `total` (canonico) sia `count` (legacy deprecato)."},"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)."},"TopQueryRow":{"properties":{"path":{"type":"string","title":"Path"},"query_type":{"type":"string","title":"Query Type"},"request_count":{"type":"integer","title":"Request Count"},"distinct_agents":{"type":"integer","title":"Distinct Agents"},"sample_params":{"items":{"type":"string"},"type":"array","title":"Sample Params","default":[]}},"type":"object","required":["path","query_type","request_count","distinct_agents"],"title":"TopQueryRow"},"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"},"ZeroResultRow":{"properties":{"path":{"type":"string","title":"Path"},"query_string":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Query String"},"status_code":{"type":"integer","title":"Status Code"},"count":{"type":"integer","title":"Count"},"last_seen":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Seen"}},"type":"object","required":["path","query_string","status_code","count","last_seen"],"title":"ZeroResultRow"}}},"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"}]}