{"openapi":"3.1.0","info":{"title":"ambassador-api","description":"\n## Ambassador API\n\nActivity orchestration API for the CivicWall Ambassador Platform.\n\n### Architecture\n\nAmbassador API is an **activity API**, not a data API.\n- **CivicPerson** (port 8040) is the source of truth for persons, memberships, candidacies, and ambassador profiles.\n- **Identity Backend** (port 8010) is the source of truth for authentication and biometric verification.\n- **Ambassador API** (port 8080) orchestrates validation decisions, persists the audit trail (ScyllaDB), and streams real-time events (Redis SSE).\n\n### Validation types\n\n| Type | Module | Upstream | Guard rails |\n|------|--------|----------|-------------|\n| **A — Identity** | area only | Identity Backend | capability, quota, self-validation, module type |\n| **B — Membership** | sectoral only | CivicPerson | module type |\n| **C — Candidate** | all modules | CivicPerson | capability, quota, self-validation, cascade N+1, eligibility |\n| **D — Claim** | all modules | CivicPerson (S2S) | capability, quota, self-validation |\n\n### Guard rails\n\n- **Capability** (AMB-902): each ambassador level has allowed validation types.\n- **Daily quota** (AMB-901): per-level limits on identity and candidate validations.\n- **Self-validation** (AMB-803): blocked for all levels except MASTER_PLATFORM (bootstrap).\n- **Cascade N+1** (AMB-906): an ambassador can only validate the level directly below.\n- **Eligibility** (AMB-903/904): verification_level and account_age minimums per target level.\n\n### Authentication\n\nAll endpoints require a Bearer token (Keycloak). Service-to-service endpoints use `X-Service-API-Key`.\n","version":"1.0.0"},"paths":{"/api/v1/me":{"get":{"tags":["auth"],"summary":"Get Me","description":"Get current ambassador profile.\nProxies Identity Backend /auth/me for identity data,\nthen enriches with ambassador scopes.","operationId":"get_me_api_v1_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserProfile"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/me/scopes":{"get":{"tags":["scopes"],"summary":"Get My Scopes","description":"List all scopes assigned to the current ambassador.","operationId":"get_my_scopes_api_v1_me_scopes_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MyScopesResponse"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/scopes/{scope_id}":{"get":{"tags":["scopes"],"summary":"Get Scope","description":"Get details of a specific scope.","operationId":"get_scope_api_v1_scopes__scope_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"scope_id","in":"path","required":true,"schema":{"type":"string","title":"Scope Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AmbassadorScope"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/scopes/{scope_id}/navigate":{"get":{"tags":["scopes"],"summary":"Navigate Scope","description":"Navigate scope hierarchy (parent + children).","operationId":"navigate_scope_api_v1_scopes__scope_id__navigate_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"scope_id","in":"path","required":true,"schema":{"type":"string","title":"Scope Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScopeNavigationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/scopes/{scope_id}/relations":{"get":{"tags":["scopes"],"summary":"Get Scope Relations","description":"Get all relations for a scope: parent, children, siblings.","operationId":"get_scope_relations_api_v1_scopes__scope_id__relations_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"scope_id","in":"path","required":true,"schema":{"type":"string","title":"Scope Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScopeRelationsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/scopes/{scope_id}/siblings":{"get":{"tags":["scopes"],"summary":"Get Scope Siblings","description":"Get sibling scopes (same parent).","operationId":"get_scope_siblings_api_v1_scopes__scope_id__siblings_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"scope_id","in":"path","required":true,"schema":{"type":"string","title":"Scope Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScopeSiblingsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/scopes/{scope_id}/children":{"get":{"tags":["scopes"],"summary":"Get Scope Children","description":"Lazy-load children for TreeView hierarchy navigation.\n\nK1: Reads from ambassador_territory_navigator (ScyllaDB local) —\npre-synced every 10 minutes with GDAM names (K6) and population counts (K2).\nEnriches with validation stats and ambassador data from ScyllaDB.\nRespects visibility rules: viewer can see all descendants (not just N-1).\n\nZERO network calls to CivicPerson or ClickHouse.","operationId":"get_scope_children_api_v1_scopes__scope_id__children_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"scope_id","in":"path","required":true,"schema":{"type":"string","title":"Scope Id"}},{"name":"level","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Target level to fetch children for","title":"Level"},"description":"Target level to fetch children for"},{"name":"parent_selector","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Parent node code to filter children","title":"Parent Selector"},"description":"Parent node code to filter children"},{"name":"country_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Country code override (for MASTER_PLATFORM navigating a specific country)","title":"Country Code"},"description":"Country code override (for MASTER_PLATFORM navigating a specific country)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HierarchyChildrenResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/scopes/{scope_id}/resolve-path":{"get":{"tags":["scopes"],"summary":"Resolve Path","description":"Resolve a territorial path into human-readable names for breadcrumb display.\n\nQueries ClickHouse GDAM to translate codes (FR_IledeFrance) into names\n(Île-de-France). A single query on the deepest segment suffices because\nGDAM child tables contain all parent names.\n\nAlso computes is_clickable per segment based on the viewer's scope.","operationId":"resolve_path_api_v1_scopes__scope_id__resolve_path_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"scope_id","in":"path","required":true,"schema":{"type":"string","title":"Scope Id"}},{"name":"path","in":"query","required":false,"schema":{"type":"string","description":"Slash-separated territorial codes, e.g. FR_Grand_Est/FR_Grand_Est_Marne","default":"","title":"Path"},"description":"Slash-separated territorial codes, e.g. FR_Grand_Est/FR_Grand_Est_Marne"},{"name":"country_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Country code override (for MASTER_PLATFORM)","title":"Country Code"},"description":"Country code override (for MASTER_PLATFORM)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolvedPathResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/scopes/{scope_id}/navigator/menu":{"get":{"tags":["scopes"],"summary":"Get Navigator Menu","description":"Read navigation menu directly from ambassador_territory_navigator.\nThis avoids heavy CivicPerson territory aggregation requests for UI navigation.","operationId":"get_navigator_menu_api_v1_scopes__scope_id__navigator_menu_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"scope_id","in":"path","required":true,"schema":{"type":"string","title":"Scope Id"}},{"name":"parent_node_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Parent node code to list children for","title":"Parent Node Code"},"description":"Parent node code to list children for"},{"name":"level_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional node level (COUNTRY|REGION|DEPARTMENT|CITY)","title":"Level Code"},"description":"Optional node level (COUNTRY|REGION|DEPARTMENT|CITY)"},{"name":"country_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Country override (required for MASTER_PLATFORM)","title":"Country Code"},"description":"Country override (required for MASTER_PLATFORM)"},{"name":"include_inactive","in":"query","required":false,"schema":{"type":"boolean","description":"Include inactive/no-data nodes","default":false,"title":"Include Inactive"},"description":"Include inactive/no-data nodes"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NavigatorMenuResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/scopes/{scope_id}/navigator/breadcrumb":{"get":{"tags":["scopes"],"summary":"Get Navigator Breadcrumb","description":"Build breadcrumb path directly from ambassador_territory_navigator.","operationId":"get_navigator_breadcrumb_api_v1_scopes__scope_id__navigator_breadcrumb_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"scope_id","in":"path","required":true,"schema":{"type":"string","title":"Scope Id"}},{"name":"node_code","in":"query","required":true,"schema":{"type":"string","title":"Node Code"}},{"name":"country_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Country override (required for MASTER_PLATFORM)","title":"Country Code"},"description":"Country override (required for MASTER_PLATFORM)"},{"name":"include_inactive","in":"query","required":false,"schema":{"type":"boolean","description":"Include inactive/no-data nodes","default":false,"title":"Include Inactive"},"description":"Include inactive/no-data nodes"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NavigatorBreadcrumbResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/scopes/{scope_id}/persons/{person_code}":{"get":{"tags":["scopes"],"summary":"Get Person Detail","description":"Get full person detail from CivicPerson (all identity fields).\n\nReturns the complete CivicPerson Person record (~68 fields) for display\non the citizen detail page.  The lightweight /entities/ endpoint only\nreturns 7 fields and is kept for paginated territory lists.","operationId":"get_person_detail_api_v1_scopes__scope_id__persons__person_code__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"scope_id","in":"path","required":true,"schema":{"type":"string","title":"Scope Id"}},{"name":"person_code","in":"path","required":true,"schema":{"type":"string","title":"Person Code"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/scopes/{scope_id}/entities":{"get":{"tags":["scopes"],"summary":"Get Scope Entities","description":"Get visible entities within a scope (paginated).\n\nK3: Resolution (which person_codes are visible) is now from ScyllaDB local\n(ambassador_node_member_compatibility). Display enrichment (names, status)\nstill proxies to CivicPerson until K4 batch endpoint is available.\n\nWhen `query` (text search) is provided, delegates entirely to CivicPerson\nsince ScyllaDB cannot perform text search.","operationId":"get_scope_entities_api_v1_scopes__scope_id__entities_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"scope_id","in":"path","required":true,"schema":{"type":"string","title":"Scope Id"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}},{"name":"item_selector","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Override geographic scope (must be within ambassador scope)","title":"Item Selector"},"description":"Override geographic scope (must be within ambassador scope)"},{"name":"query","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":2},{"type":"null"}],"description":"Search by name","title":"Query"},"description":"Search by name"},{"name":"entity_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter: HUMAN, MORAL, GROUP","title":"Entity Type"},"description":"Filter: HUMAN, MORAL, GROUP"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/scopes/{scope_id}/territory-tree":{"get":{"tags":["scopes"],"summary":"Get Territory Tree","description":"Get aggregated territory tree (only populated territories).\n\nProxies to CivicPerson territory/tree endpoint which aggregates\nfrom the Person table instead of GDAM geographic data.","operationId":"get_territory_tree_api_v1_scopes__scope_id__territory_tree_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"scope_id","in":"path","required":true,"schema":{"type":"string","title":"Scope Id"}},{"name":"level","in":"query","required":true,"schema":{"type":"string","description":"Territory level: region, department, city","title":"Level"},"description":"Territory level: region, department, city"},{"name":"parent_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Parent territory code","title":"Parent Code"},"description":"Parent territory code"},{"name":"country_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Country code override (for MASTER_PLATFORM)","title":"Country Code"},"description":"Country code override (for MASTER_PLATFORM)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/scopes/{scope_id}/ambassadors":{"get":{"tags":["scopes"],"summary":"Get Zone Ambassadors","description":"Get ambassadors/candidates assigned to a territorial zone.\n\nReads from ScyllaDB civicperson_ambassador_candidacy (all statuses).\nReturns an empty list if no ambassadors are assigned (zone VACANTE).","operationId":"get_zone_ambassadors_api_v1_scopes__scope_id__ambassadors_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"scope_id","in":"path","required":true,"schema":{"type":"string","title":"Scope Id"}},{"name":"zone_code","in":"query","required":true,"schema":{"type":"string","description":"Territorial zone code (e.g. FR_Grand_Est)","title":"Zone Code"},"description":"Territorial zone code (e.g. FR_Grand_Est)"},{"name":"country_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Country code override","title":"Country Code"},"description":"Country code override"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ZoneAmbassadorsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/countries":{"get":{"tags":["countries"],"summary":"List active countries","description":"Returns all active countries from Identity Backend, enriched with lat/lng from ClickHouse GDAM. Restricted to MASTER_PLATFORM ambassadors.","operationId":"get_active_countries_api_v1_countries_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/scopes/{scope_id}/aggregates":{"get":{"tags":["aggregates"],"summary":"Get Aggregates","description":"Get aggregated KPIs for a scope (cached 5min).","operationId":"get_aggregates_api_v1_scopes__scope_id__aggregates_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"scope_id","in":"path","required":true,"schema":{"type":"string","title":"Scope Id"}},{"name":"country_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO2 country code (PM only)","title":"Country Code"},"description":"ISO2 country code (PM only)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScopeAggregates"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/scopes/{scope_id}/trends":{"get":{"tags":["aggregates"],"summary":"Get Trends","description":"Get trend data over 7d or 30d.","operationId":"get_trends_api_v1_scopes__scope_id__trends_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"scope_id","in":"path","required":true,"schema":{"type":"string","title":"Scope Id"}},{"name":"period","in":"query","required":false,"schema":{"type":"string","pattern":"^(7d|30d)$","default":"7d","title":"Period"}},{"name":"country_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO2 country code (PM only)","title":"Country Code"},"description":"ISO2 country code (PM only)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScopeTrends"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/scopes/{scope_id}/alerts":{"get":{"tags":["aggregates"],"summary":"Get Alerts","description":"Get active alerts for sub-zones under threshold.","operationId":"get_alerts_api_v1_scopes__scope_id__alerts_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"scope_id","in":"path","required":true,"schema":{"type":"string","title":"Scope Id"}},{"name":"country_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO2 country code (PM only)","title":"Country Code"},"description":"ISO2 country code (PM only)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ScopeAlert"},"title":"Response Get Alerts Api V1 Scopes  Scope Id  Alerts Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/scopes/{scope_id}/geometry":{"get":{"tags":["geometry"],"summary":"Get GeoJSON geometry for scope sub-zones","description":"Returns a GeoJSON FeatureCollection of sub-zone polygons from ClickHouse GDAM, enriched with coverage_rate and alert_level from aggregates. Includes map center (lat/lng) and recommended zoom level. PM can specify country_code to view a specific country's geometry.","operationId":"get_scope_geometry_api_v1_scopes__scope_id__geometry_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"scope_id","in":"path","required":true,"schema":{"type":"string","title":"Scope Id"}},{"name":"country_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO2 country code (PM only)","title":"Country Code"},"description":"ISO2 country code (PM only)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/scopes/{scope_id}/validation-queue":{"get":{"tags":["validation-queue"],"summary":"Get unified validation queue","description":"Unified validation queue for a scope. Returns pending items by type: area module → identities + candidates, sectoral module → memberships + candidates. Filter with `type` query param: all, identities, memberships, candidates.","operationId":"get_validation_queue_api_v1_scopes__scope_id__validation_queue_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"scope_id","in":"path","required":true,"schema":{"type":"string","title":"Scope Id"}},{"name":"type","in":"query","required":false,"schema":{"type":"string","pattern":"^(all|identities|memberships|candidates|claims)$","default":"all","title":"Type"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationQueueResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/scopes/{scope_id}/validation-history":{"get":{"tags":["validation-queue"],"summary":"Get validation decision history","description":"Paginated history of validation decisions for a scope. Reads from ScyllaDB audit trail. Supports cursor-based pagination. PM can specify country_code to filter by country.","operationId":"get_validation_history_api_v1_scopes__scope_id__validation_history_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"scope_id","in":"path","required":true,"schema":{"type":"string","title":"Scope Id"}},{"name":"country_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO2 country code (PM only)","title":"Country Code"},"description":"ISO2 country code (PM only)"},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"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":{"$ref":"#/components/schemas/ValidationHistoryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/validations/identities/{verification_id}":{"get":{"tags":["validation-identities"],"summary":"Get identity verification detail","description":"Retrieve full identity verification detail including documents, OCR data, and auto-validation scores. **Area module only** — returns 403 for sectoral scopes.","operationId":"get_identity_detail_api_v1_validations_identities__verification_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"verification_id","in":"path","required":true,"schema":{"type":"string","title":"Verification Id"}},{"name":"scope_id","in":"query","required":false,"schema":{"type":"string","title":"Scope Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdentityVerificationDetail"}}}},"403":{"description":"Scope is not an area module, or insufficient capability."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/validations/identities/{verification_id}/approve":{"post":{"tags":["validation-identities"],"summary":"Approve identity verification","description":"Approve an identity verification. **Area module only.** Guard rails: capability check (AMB-902), daily quota (AMB-901), self-validation block (AMB-803).","operationId":"approve_identity_api_v1_validations_identities__verification_id__approve_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"verification_id","in":"path","required":true,"schema":{"type":"string","title":"Verification Id"}},{"name":"scope_id","in":"query","required":false,"schema":{"type":"string","title":"Scope Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApproveIdentityRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationDecisionResponse"}}}},"403":{"description":"Module type mismatch, capability denied, or self-validation blocked."},"422":{"description":"Invalid request body."},"429":{"description":"Daily quota exceeded for this ambassador level."}}}},"/api/v1/validations/identities/{verification_id}/reject":{"post":{"tags":["validation-identities"],"summary":"Reject identity verification","description":"Reject an identity verification with a reason. **Area module only.** Guard rails: capability check, daily quota, self-validation block.","operationId":"reject_identity_api_v1_validations_identities__verification_id__reject_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"verification_id","in":"path","required":true,"schema":{"type":"string","title":"Verification Id"}},{"name":"scope_id","in":"query","required":false,"schema":{"type":"string","title":"Scope Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RejectIdentityRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationDecisionResponse"}}}},"403":{"description":"Module type mismatch, capability denied, or self-validation blocked."},"422":{"description":"Invalid request body or reason."},"429":{"description":"Daily quota exceeded for this ambassador level."}}}},"/api/v1/validations/memberships/{request_id}":{"get":{"tags":["validation-memberships"],"summary":"Get membership request detail","description":"Retrieve full membership request detail from CivicPerson. **Sectoral modules only** — returns 403 for area scopes.","operationId":"get_membership_detail_api_v1_validations_memberships__request_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","title":"Request Id"}},{"name":"scope_id","in":"query","required":false,"schema":{"type":"string","title":"Scope Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MembershipDetail"}}}},"403":{"description":"Scope is an area module (membership validation requires sectoral scope)."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/validations/memberships/{request_id}/approve":{"post":{"tags":["validation-memberships"],"summary":"Approve membership request","description":"Approve a membership request. **Sectoral modules only.** Optionally assign a role_in_scope.","operationId":"approve_membership_api_v1_validations_memberships__request_id__approve_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","title":"Request Id"}},{"name":"scope_id","in":"query","required":false,"schema":{"type":"string","title":"Scope Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApproveMembershipRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationDecisionResponse"}}}},"403":{"description":"Scope is an area module."},"422":{"description":"Invalid request body."}}}},"/api/v1/validations/memberships/{request_id}/reject":{"post":{"tags":["validation-memberships"],"summary":"Reject membership request","description":"Reject a membership request with a reason. **Sectoral modules only.**","operationId":"reject_membership_api_v1_validations_memberships__request_id__reject_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","title":"Request Id"}},{"name":"scope_id","in":"query","required":false,"schema":{"type":"string","title":"Scope Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RejectMembershipRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationDecisionResponse"}}}},"403":{"description":"Scope is an area module."},"422":{"description":"Invalid request body or reason."}}}},"/api/v1/validations/candidates/{person_code}":{"get":{"tags":["validation-candidates"],"summary":"Get ambassador candidate detail","description":"Retrieve full candidate detail from CivicPerson including eligibility criteria.","operationId":"get_candidate_detail_api_v1_validations_candidates__person_code__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"person_code","in":"path","required":true,"schema":{"type":"string","title":"Person Code"}},{"name":"scope_id","in":"query","required":false,"schema":{"type":"string","title":"Scope Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CandidateDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/validations/candidates/{person_code}/approve":{"post":{"tags":["validation-candidates"],"summary":"Approve ambassador candidate","description":"Approve an ambassador candidate (N+1 validates N). Guard rails: capability check (AMB-902), daily quota (AMB-901), self-validation block (AMB-803), cascade N+1 (AMB-906), eligibility: verification_level (AMB-903) and account_age (AMB-904).","operationId":"approve_candidate_api_v1_validations_candidates__person_code__approve_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"person_code","in":"path","required":true,"schema":{"type":"string","title":"Person Code"}},{"name":"scope_id","in":"query","required":false,"schema":{"type":"string","title":"Scope Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApproveCandidateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationDecisionResponse"}}}},"403":{"description":"Capability denied, self-validation blocked, or wrong cascade level."},"422":{"description":"Candidate not eligible (verification_level or account_age too low)."},"429":{"description":"Daily quota exceeded for candidate validations."}}}},"/api/v1/validations/candidates/{person_code}/reject":{"post":{"tags":["validation-candidates"],"summary":"Reject ambassador candidate","description":"Reject an ambassador candidate with a reason. Guard rails: capability check, daily quota, self-validation block, cascade N+1.","operationId":"reject_candidate_api_v1_validations_candidates__person_code__reject_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"person_code","in":"path","required":true,"schema":{"type":"string","title":"Person Code"}},{"name":"scope_id","in":"query","required":false,"schema":{"type":"string","title":"Scope Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RejectCandidateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationDecisionResponse"}}}},"403":{"description":"Capability denied, self-validation blocked, or wrong cascade level."},"422":{"description":"Invalid request body or reason."},"429":{"description":"Daily quota exceeded for candidate validations."}}}},"/api/v1/validations/claims/{claim_id}":{"get":{"tags":["validation-claims"],"summary":"Get claim detail","description":"Retrieve full claim detail including evidence, votes, and claimant info. Only claims with validation_method AMBASSADOR or HYBRID are visible.","operationId":"get_claim_detail_api_v1_validations_claims__claim_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"claim_id","in":"path","required":true,"schema":{"type":"string","title":"Claim Id"}},{"name":"scope_id","in":"query","required":false,"schema":{"type":"string","title":"Scope Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimDetail"}}}},"403":{"description":"Insufficient capability to validate claims."},"404":{"description":"Claim not found."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/validations/claims/{claim_id}/approve":{"post":{"tags":["validation-claims"],"summary":"Approve entity claim","description":"Approve an entity claim. Forwards the decision to CivicPerson which will link the claimant to the entity and activate relevant journeys. Guard rails: capability check, daily quota, self-validation block.","operationId":"approve_claim_api_v1_validations_claims__claim_id__approve_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"claim_id","in":"path","required":true,"schema":{"type":"string","title":"Claim Id"}},{"name":"scope_id","in":"query","required":false,"schema":{"type":"string","title":"Scope Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApproveClaimRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationDecisionResponse"}}}},"403":{"description":"Capability denied or self-validation blocked."},"422":{"description":"Invalid request body."},"429":{"description":"Daily quota exceeded for this ambassador level."}}}},"/api/v1/validations/claims/{claim_id}/reject":{"post":{"tags":["validation-claims"],"summary":"Reject entity claim","description":"Reject an entity claim with a reason. Forwards the decision to CivicPerson which will mark the claim as rejected. Guard rails: capability check, daily quota, self-validation block.","operationId":"reject_claim_api_v1_validations_claims__claim_id__reject_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"claim_id","in":"path","required":true,"schema":{"type":"string","title":"Claim Id"}},{"name":"scope_id","in":"query","required":false,"schema":{"type":"string","title":"Scope Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RejectClaimRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationDecisionResponse"}}}},"403":{"description":"Capability denied or self-validation blocked."},"422":{"description":"Invalid request body or reason."},"429":{"description":"Daily quota exceeded for this ambassador level."}}}},"/api/v1/scopes/{scope_id}/activity":{"get":{"tags":["activity"],"summary":"Get Activity History","description":"Get paginated activity history for a scope.","operationId":"get_activity_history_api_v1_scopes__scope_id__activity_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"scope_id","in":"path","required":true,"schema":{"type":"string","title":"Scope Id"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}},{"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"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActivityResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/scopes/{scope_id}/events":{"get":{"tags":["activity"],"summary":"Sse Events","description":"SSE real-time activity stream for a scope.\nSends events as they arrive in the Redis Stream.","operationId":"sse_events_api_v1_scopes__scope_id__events_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"scope_id","in":"path","required":true,"schema":{"type":"string","title":"Scope Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/system/activity/emit":{"post":{"tags":["system"],"summary":"Emit Activity Event","description":"Service-to-service endpoint to emit activity events.\nUsed by Identity Backend and CivicPerson to push events\n(e.g., new submission, webhook).\nRequires X-Service-API-Key header.","operationId":"emit_activity_event_api_v1_system_activity_emit_post","parameters":[{"name":"X-Service-API-Key","in":"header","required":true,"schema":{"type":"string","title":"X-Service-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Event"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/system/ambassador-profiles":{"post":{"tags":["system"],"summary":"Receive Ambassador Profile","description":"CivicPerson calls this endpoint when an ambassador profile\nis created, updated, suspended or revoked.\nAmbassador API writes an AuditLog and emits SSE event.","operationId":"receive_ambassador_profile_api_v1_system_ambassador_profiles_post","parameters":[{"name":"X-Service-API-Key","in":"header","required":true,"schema":{"type":"string","title":"X-Service-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AmbassadorProfilePayload"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/S2SAckResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/system/candidate-submissions":{"post":{"tags":["system"],"summary":"Receive Candidate Submission","description":"CivicPerson calls this endpoint when a citizen posts\nan ambassador candidacy.\nAmbassador API emits SSE \"candidate_submitted\".","operationId":"receive_candidate_submission_api_v1_system_candidate_submissions_post","parameters":[{"name":"X-Service-API-Key","in":"header","required":true,"schema":{"type":"string","title":"X-Service-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CandidateSubmissionPayload"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/S2SAckResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/system/membership-submissions":{"post":{"tags":["system"],"summary":"Receive Membership Submission","description":"CivicPerson calls this endpoint when a citizen requests\na sectoral membership.\nAmbassador API emits SSE \"membership_submitted\".","operationId":"receive_membership_submission_api_v1_system_membership_submissions_post","parameters":[{"name":"X-Service-API-Key","in":"header","required":true,"schema":{"type":"string","title":"X-Service-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MembershipSubmissionPayload"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/S2SAckResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/system/identity-submissions":{"post":{"tags":["system"],"summary":"Receive Identity Submission","description":"Identity Backend calls this endpoint when a document\npasses to PENDING_REVIEW.\nAmbassador API emits SSE \"validation_submitted\".","operationId":"receive_identity_submission_api_v1_system_identity_submissions_post","parameters":[{"name":"X-Service-API-Key","in":"header","required":true,"schema":{"type":"string","title":"X-Service-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdentitySubmissionPayload"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/S2SAckResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/system/sync/navigator/batch":{"post":{"tags":["system"],"summary":"Sync Navigator Batch","operationId":"sync_navigator_batch_api_v1_system_sync_navigator_batch_post","parameters":[{"name":"X-Service-API-Key","in":"header","required":true,"schema":{"type":"string","title":"X-Service-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectionBatchPayload"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectionBatchAck"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/system/sync/node-member-compatibility/batch":{"post":{"tags":["system"],"summary":"Sync Node Member Compatibility Batch","operationId":"sync_node_member_compatibility_batch_api_v1_system_sync_node_member_compatibility_batch_post","parameters":[{"name":"X-Service-API-Key","in":"header","required":true,"schema":{"type":"string","title":"X-Service-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectionBatchPayload"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectionBatchAck"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/system/sync/node-ambassador-compatibility/batch":{"post":{"tags":["system"],"summary":"Sync Node Ambassador Compatibility Batch","operationId":"sync_node_ambassador_compatibility_batch_api_v1_system_sync_node_ambassador_compatibility_batch_post","parameters":[{"name":"X-Service-API-Key","in":"header","required":true,"schema":{"type":"string","title":"X-Service-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectionBatchPayload"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectionBatchAck"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/system/sync/member-node-compatibility/batch":{"post":{"tags":["system"],"summary":"Sync Member Node Compatibility Batch","operationId":"sync_member_node_compatibility_batch_api_v1_system_sync_member_node_compatibility_batch_post","parameters":[{"name":"X-Service-API-Key","in":"header","required":true,"schema":{"type":"string","title":"X-Service-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectionBatchPayload"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectionBatchAck"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/system/sync/selector-assignments/batch":{"post":{"tags":["system"],"summary":"Sync Selector Assignments Batch","operationId":"sync_selector_assignments_batch_api_v1_system_sync_selector_assignments_batch_post","parameters":[{"name":"X-Service-API-Key","in":"header","required":true,"schema":{"type":"string","title":"X-Service-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectionBatchPayload"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectionBatchAck"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/system/sync/selector-members/batch":{"post":{"tags":["system"],"summary":"Sync Selector Members Batch","operationId":"sync_selector_members_batch_api_v1_system_sync_selector_members_batch_post","parameters":[{"name":"X-Service-API-Key","in":"header","required":true,"schema":{"type":"string","title":"X-Service-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectionBatchPayload"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectionBatchAck"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/system/sync/viewer-members/batch":{"post":{"tags":["system"],"summary":"Sync Viewer Members Batch","operationId":"sync_viewer_members_batch_api_v1_system_sync_viewer_members_batch_post","parameters":[{"name":"X-Service-API-Key","in":"header","required":true,"schema":{"type":"string","title":"X-Service-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectionBatchPayload"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectionBatchAck"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/system/sync/viewer-members-by-selector/batch":{"post":{"tags":["system"],"summary":"Sync Viewer Members By Selector Batch","operationId":"sync_viewer_members_by_selector_batch_api_v1_system_sync_viewer_members_by_selector_batch_post","parameters":[{"name":"X-Service-API-Key","in":"header","required":true,"schema":{"type":"string","title":"X-Service-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectionBatchPayload"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectionBatchAck"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/system/sync/selector-hierarchy/batch":{"post":{"tags":["system"],"summary":"Sync Selector Hierarchy Batch","operationId":"sync_selector_hierarchy_batch_api_v1_system_sync_selector_hierarchy_batch_post","parameters":[{"name":"X-Service-API-Key","in":"header","required":true,"schema":{"type":"string","title":"X-Service-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectionBatchPayload"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectionBatchAck"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/system/sync/navigator/run-once":{"post":{"tags":["system"],"summary":"Run Navigator Sync Once Endpoint","description":"Trigger one navigator sync run (incremental or full rebuild).\nUseful for ops and catch-up control.","operationId":"run_navigator_sync_once_endpoint_api_v1_system_sync_navigator_run_once_post","parameters":[{"name":"full_rebuild","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Full Rebuild"}},{"name":"country_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country Code"}},{"name":"X-Service-API-Key","in":"header","required":true,"schema":{"type":"string","title":"X-Service-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Run Navigator Sync Once Endpoint Api V1 System Sync Navigator Run Once Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/system/sync/compatibility/run-once":{"post":{"tags":["system"],"summary":"Run Compatibility Sync Once Endpoint","description":"Trigger one compatibility sync run (incremental or full rebuild).\nBuilds node-member closure, reverse member-node index and node ACL.","operationId":"run_compatibility_sync_once_endpoint_api_v1_system_sync_compatibility_run_once_post","parameters":[{"name":"full_rebuild","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Full Rebuild"}},{"name":"country_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country Code"}},{"name":"X-Service-API-Key","in":"header","required":true,"schema":{"type":"string","title":"X-Service-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Run Compatibility Sync Once Endpoint Api V1 System Sync Compatibility Run Once Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/system/sync/selectors/run-once":{"post":{"tags":["system"],"summary":"Run Selector Sync Once Endpoint","description":"Trigger one selector sync run (incremental or full rebuild).\nBuilds selector assignments, selector members and viewer materialized indexes.","operationId":"run_selector_sync_once_endpoint_api_v1_system_sync_selectors_run_once_post","parameters":[{"name":"full_rebuild","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Full Rebuild"}},{"name":"country_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country Code"}},{"name":"X-Service-API-Key","in":"header","required":true,"schema":{"type":"string","title":"X-Service-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Run Selector Sync Once Endpoint Api V1 System Sync Selectors Run Once Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/version":{"get":{"tags":["meta"],"summary":"Get Version","operationId":"get_version_version_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/":{"get":{"tags":["meta"],"summary":"API home","operationId":"home__get","responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/health":{"get":{"tags":["meta"],"summary":"Health Check","operationId":"health_check_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"ActivityEvent":{"properties":{"event_id":{"type":"string","title":"Event Id"},"event_type":{"type":"string","enum":["validation_approved","validation_rejected","validation_submitted","alert_threshold","alert_trend_negative","coverage_milestone","daily_summary","membership_approved","membership_rejected","membership_submitted","candidate_approved","candidate_rejected","candidate_submitted"],"title":"Event Type"},"scope_id":{"type":"string","title":"Scope Id"},"sub_scope_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sub Scope Id"},"sub_scope_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sub Scope Name"},"actor_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Actor Name"},"count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Count"},"details":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Details"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["event_id","event_type","scope_id","created_at"],"title":"ActivityEvent"},"ActivityResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ActivityEvent"},"type":"array","title":"Items"},"cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"},"has_more":{"type":"boolean","title":"Has More"}},"type":"object","required":["items","has_more"],"title":"ActivityResponse"},"AmbassadorProfilePayload":{"properties":{"person_code":{"type":"string","title":"Person Code"},"display_name":{"type":"string","title":"Display Name"},"level":{"type":"string","title":"Level"},"role":{"type":"string","title":"Role"},"status":{"type":"string","title":"Status"},"scope_id":{"type":"string","title":"Scope Id"},"scope_name":{"type":"string","title":"Scope Name"},"module_type":{"type":"string","title":"Module Type"},"sector_type":{"type":"string","title":"Sector Type"},"item_selector":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Item Selector"},"granted_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Granted By"},"country_code":{"type":"string","title":"Country Code","default":"FR"}},"type":"object","required":["person_code","display_name","level","role","status","scope_id","scope_name","module_type","sector_type"],"title":"AmbassadorProfilePayload","description":"Received from CivicPerson when an ambassador profile is created/updated."},"AmbassadorScope":{"properties":{"scope_id":{"type":"string","title":"Scope Id"},"scope_name":{"type":"string","title":"Scope Name"},"scope_type":{"type":"string","enum":["GLOBAL","COUNTRY","REGION","DEPARTMENT","CITY","SECTOR"],"title":"Scope Type","default":"COUNTRY"},"country_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country Code"},"sector_type":{"type":"string","enum":["territorial","educational","enterprise","associative"],"title":"Sector Type"},"sector_id":{"type":"string","title":"Sector Id"},"item_selector":{"type":"string","title":"Item Selector"},"level":{"type":"string","title":"Level"},"role":{"type":"string","enum":["PRESIDENT","VICE_PRESIDENT","DELEGATE"],"title":"Role"},"module_type":{"type":"string","title":"Module Type"},"granted_at":{"type":"string","format":"date-time","title":"Granted At"},"granted_by":{"type":"string","title":"Granted By"}},"type":"object","required":["scope_id","scope_name","sector_type","sector_id","item_selector","level","role","module_type","granted_at","granted_by"],"title":"AmbassadorScope"},"ApproveCandidateRequest":{"properties":{"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes"}},"type":"object","title":"ApproveCandidateRequest"},"ApproveClaimRequest":{"properties":{"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes"}},"type":"object","title":"ApproveClaimRequest"},"ApproveIdentityRequest":{"properties":{"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes"}},"type":"object","title":"ApproveIdentityRequest"},"ApproveMembershipRequest":{"properties":{"role_in_scope":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Role In Scope"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes"}},"type":"object","title":"ApproveMembershipRequest"},"AutoValidationScores":{"properties":{"template_match":{"type":"number","title":"Template Match"},"ocr_fields_extracted":{"type":"integer","title":"Ocr Fields Extracted"},"name_match":{"type":"number","title":"Name Match"},"face_match":{"type":"number","title":"Face Match"},"expiry_valid":{"type":"boolean","title":"Expiry Valid"},"duplicate_check":{"type":"boolean","title":"Duplicate Check"},"overall_status":{"type":"string","title":"Overall Status"}},"type":"object","required":["template_match","ocr_fields_extracted","name_match","face_match","expiry_valid","duplicate_check","overall_status"],"title":"AutoValidationScores"},"CandidateDetail":{"properties":{"person_code":{"type":"string","title":"Person Code"},"display_name":{"type":"string","title":"Display Name"},"submitted_at":{"type":"string","format":"date-time","title":"Submitted At"},"target_level":{"type":"string","title":"Target Level"},"requested_zone":{"type":"string","title":"Requested Zone"},"requested_zone_name":{"type":"string","title":"Requested Zone Name"},"motivation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Motivation"},"eligibility":{"$ref":"#/components/schemas/CandidateEligibility"},"verification_level":{"type":"integer","title":"Verification Level"},"citizen_since":{"type":"string","format":"date-time","title":"Citizen Since"},"has_sanctions":{"type":"boolean","title":"Has Sanctions"},"is_resident":{"type":"boolean","title":"Is Resident"},"current_roles":{"items":{"type":"string"},"type":"array","title":"Current Roles"}},"type":"object","required":["person_code","display_name","submitted_at","target_level","requested_zone","requested_zone_name","eligibility","verification_level","citizen_since","has_sanctions","is_resident","current_roles"],"title":"CandidateDetail","examples":[{"citizen_since":"2024-01-01T00:00:00Z","current_roles":["AMBASSADOR_CITY"],"display_name":"Pierre Durand","eligibility":{"all_criteria_met":true,"blocking_criteria":[],"citizen_since_days":365,"has_sanctions":false,"is_resident":true,"verification_level":3},"has_sanctions":false,"is_resident":true,"motivation":"Experience de 3 ans","person_code":"FR-P-300","requested_zone":"FR-ARA","requested_zone_name":"Auvergne-Rhone-Alpes","submitted_at":"2025-06-01T10:00:00Z","target_level":"SENIOR_REGION","verification_level":3}]},"CandidateEligibility":{"properties":{"citizen_since_days":{"type":"integer","title":"Citizen Since Days"},"verification_level":{"type":"integer","title":"Verification Level"},"has_sanctions":{"type":"boolean","title":"Has Sanctions"},"is_resident":{"type":"boolean","title":"Is Resident"},"all_criteria_met":{"type":"boolean","title":"All Criteria Met"},"blocking_criteria":{"items":{"type":"string"},"type":"array","title":"Blocking Criteria"}},"type":"object","required":["citizen_since_days","verification_level","has_sanctions","is_resident","all_criteria_met","blocking_criteria"],"title":"CandidateEligibility"},"CandidateQueue":{"properties":{"total":{"type":"integer","title":"Total"},"cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"},"has_more":{"type":"boolean","title":"Has More"},"items":{"items":{"$ref":"#/components/schemas/PendingCandidate"},"type":"array","title":"Items"}},"type":"object","required":["total","has_more","items"],"title":"CandidateQueue"},"CandidateSubmissionPayload":{"properties":{"person_code":{"type":"string","title":"Person Code"},"display_name":{"type":"string","title":"Display Name"},"target_level":{"type":"string","title":"Target Level"},"requested_zone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Requested Zone"},"requested_zone_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Requested Zone Name"},"motivation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Motivation"},"scope_id":{"type":"string","title":"Scope Id"},"eligibility":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Eligibility"},"country_code":{"type":"string","title":"Country Code","default":"FR"}},"type":"object","required":["person_code","display_name","target_level","scope_id"],"title":"CandidateSubmissionPayload","description":"Received from CivicPerson when a citizen posts an ambassador candidacy."},"ClaimDetail":{"properties":{"claim_id":{"type":"string","title":"Claim Id"},"claimant_person_code":{"type":"string","title":"Claimant Person Code"},"claimant_display_name":{"type":"string","title":"Claimant Display Name"},"target_type":{"type":"string","title":"Target Type"},"target_person_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Person Code"},"target_actor_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Actor Code"},"target_display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Display Name"},"claim_type":{"type":"string","title":"Claim Type"},"claim_role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Claim Role"},"evidence_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Evidence Type"},"validation_method":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Validation Method"},"status":{"type":"string","title":"Status"},"community_votes_yes":{"type":"integer","title":"Community Votes Yes","default":0},"community_votes_no":{"type":"integer","title":"Community Votes No","default":0},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"claim_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Claim Message"},"evidence_document_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Evidence Document Id"},"evidence_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Evidence Url"},"attempt_number":{"type":"integer","title":"Attempt Number","default":1},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At"}},"type":"object","required":["claim_id","claimant_person_code","claimant_display_name","target_type","claim_type","status"],"title":"ClaimDetail","examples":[{"attempt_number":1,"claim_id":"claim-001","claim_message":"Je suis le DG de cette entreprise","claim_role":"DG","claim_type":"OWNS","claimant_display_name":"Jacques Martin","claimant_person_code":"FR-P-400","community_votes_no":0,"community_votes_yes":0,"created_at":"2025-06-01T10:00:00Z","evidence_type":"NONE","status":"PENDING","target_display_name":"ACME SAS","target_person_code":"FR-M-100","target_type":"CIVICPERSON","validation_method":"AMBASSADOR"}]},"ClaimQueue":{"properties":{"total":{"type":"integer","title":"Total"},"cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"},"has_more":{"type":"boolean","title":"Has More"},"items":{"items":{"$ref":"#/components/schemas/PendingClaim"},"type":"array","title":"Items"}},"type":"object","required":["total","has_more","items"],"title":"ClaimQueue"},"GeographicLocation":{"properties":{"country_code":{"type":"string","title":"Country Code"},"region_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Region Code"},"department_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Department Code"},"city_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City Code"}},"type":"object","required":["country_code"],"title":"GeographicLocation"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HierarchyChildrenResponse":{"properties":{"scope_id":{"type":"string","title":"Scope Id"},"parent_level":{"type":"string","title":"Parent Level"},"children_level":{"type":"string","title":"Children Level"},"visible_levels":{"items":{"type":"string"},"type":"array","title":"Visible Levels"},"nodes":{"items":{"$ref":"#/components/schemas/HierarchyNode"},"type":"array","title":"Nodes"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["scope_id","parent_level","children_level","visible_levels","nodes","total"],"title":"HierarchyChildrenResponse","description":"Response for GET /scopes/{id}/children endpoint."},"HierarchyNode":{"properties":{"node_id":{"type":"string","title":"Node Id"},"node_name":{"type":"string","title":"Node Name"},"level":{"type":"string","title":"Level"},"parent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Id"},"item_selector":{"type":"string","title":"Item Selector","default":""},"total_entities":{"type":"integer","title":"Total Entities","default":0},"validated_count":{"type":"integer","title":"Validated Count","default":0},"coverage_rate":{"type":"number","title":"Coverage Rate","default":0.0},"alert_level":{"type":"string","title":"Alert Level","default":"ok"},"has_children":{"type":"boolean","title":"Has Children","default":false},"ambassador_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ambassador Name"},"ambassador_count":{"type":"integer","title":"Ambassador Count","default":0}},"type":"object","required":["node_id","node_name","level"],"title":"HierarchyNode","description":"A node in the territorial hierarchy tree."},"IdentityQueue":{"properties":{"total":{"type":"integer","title":"Total"},"cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"},"has_more":{"type":"boolean","title":"Has More"},"items":{"items":{"$ref":"#/components/schemas/PendingIdentity"},"type":"array","title":"Items"}},"type":"object","required":["total","has_more","items"],"title":"IdentityQueue"},"IdentitySubmissionPayload":{"properties":{"verification_id":{"type":"string","title":"Verification Id"},"person_code":{"type":"string","title":"Person Code"},"display_name":{"type":"string","title":"Display Name"},"document_type":{"type":"string","title":"Document Type"},"location":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Location"},"scope_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scope Id"},"country_code":{"type":"string","title":"Country Code","default":"FR"}},"type":"object","required":["verification_id","person_code","display_name","document_type"],"title":"IdentitySubmissionPayload","description":"Received from Identity Backend when a document passes to PENDING_REVIEW."},"IdentityVerificationDetail":{"properties":{"verification_id":{"type":"string","title":"Verification Id"},"person_code":{"type":"string","title":"Person Code"},"display_name":{"type":"string","title":"Display Name"},"submitted_at":{"type":"string","format":"date-time","title":"Submitted At"},"document_type":{"type":"string","title":"Document Type"},"document_recto_url":{"type":"string","title":"Document Recto Url"},"document_verso_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Verso Url"},"auto_scores":{"$ref":"#/components/schemas/AutoValidationScores"},"profile_photo_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Profile Photo Url"},"document_photo_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Photo Url"},"ocr_data":{"anyOf":[{"$ref":"#/components/schemas/OcrExtractedData"},{"type":"null"}]},"previous_attempts":{"items":{"$ref":"#/components/schemas/PreviousAttempt"},"type":"array","title":"Previous Attempts"}},"type":"object","required":["verification_id","person_code","display_name","submitted_at","document_type","document_recto_url","auto_scores","previous_attempts"],"title":"IdentityVerificationDetail","examples":[{"auto_scores":{"duplicate_check":true,"expiry_valid":true,"face_match":0.92,"name_match":0.98,"ocr_fields_extracted":6,"overall_status":"pass","template_match":0.95},"display_name":"Jean Dupont","document_photo_url":"https://storage.example.com/doc_photo.jpg?token=abc","document_recto_url":"https://storage.example.com/recto.jpg?token=abc","document_type":"national_id","document_verso_url":"https://storage.example.com/verso.jpg?token=abc","ocr_data":{"birth_date":"1990-01-15","document_number":"ABC123456","expiry_date":"2030-12-31","first_name":"Jean","last_name":"Dupont","nationality":"FR"},"person_code":"FR-P-100","previous_attempts":[],"profile_photo_url":"https://storage.example.com/photo.jpg?token=abc","submitted_at":"2025-06-01T10:00:00Z","verification_id":"vid-001"}]},"MembershipDetail":{"properties":{"request_id":{"type":"string","title":"Request Id"},"person_code":{"type":"string","title":"Person Code"},"display_name":{"type":"string","title":"Display Name"},"scope_id":{"type":"string","title":"Scope Id"},"submitted_at":{"type":"string","format":"date-time","title":"Submitted At"},"status":{"type":"string","enum":["pending","approved","rejected"],"title":"Status"},"identity_verified":{"type":"boolean","title":"Identity Verified"},"identity_level":{"type":"integer","title":"Identity Level"},"motivation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Motivation"},"justification_type":{"type":"string","title":"Justification Type"},"justification_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Justification Url"},"person_display_name":{"type":"string","title":"Person Display Name"},"person_city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Person City"},"person_joined_at":{"type":"string","format":"date-time","title":"Person Joined At"},"current_scopes":{"items":{"type":"string"},"type":"array","title":"Current Scopes"}},"type":"object","required":["request_id","person_code","display_name","scope_id","submitted_at","status","identity_verified","identity_level","justification_type","person_display_name","person_joined_at","current_scopes"],"title":"MembershipDetail","examples":[{"current_scopes":["FR-company-edf"],"display_name":"Marie Martin","identity_level":3,"identity_verified":true,"justification_type":"employee_badge","justification_url":"https://storage.example.com/badge.pdf?token=abc","motivation":"Souhait de contribuer","person_city":"Lyon","person_code":"FR-P-200","person_display_name":"Marie Martin","person_joined_at":"2024-01-15T00:00:00Z","request_id":"req-001","scope_id":"FR-company-edf","status":"pending","submitted_at":"2025-06-01T10:00:00Z"}]},"MembershipQueue":{"properties":{"total":{"type":"integer","title":"Total"},"cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"},"has_more":{"type":"boolean","title":"Has More"},"items":{"items":{"$ref":"#/components/schemas/MembershipRequest"},"type":"array","title":"Items"}},"type":"object","required":["total","has_more","items"],"title":"MembershipQueue"},"MembershipRequest":{"properties":{"request_id":{"type":"string","title":"Request Id"},"person_code":{"type":"string","title":"Person Code"},"display_name":{"type":"string","title":"Display Name"},"scope_id":{"type":"string","title":"Scope Id"},"submitted_at":{"type":"string","format":"date-time","title":"Submitted At"},"status":{"type":"string","enum":["pending","approved","rejected"],"title":"Status"},"identity_verified":{"type":"boolean","title":"Identity Verified"},"identity_level":{"type":"integer","title":"Identity Level"},"motivation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Motivation"},"justification_type":{"type":"string","title":"Justification Type"},"justification_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Justification Url"}},"type":"object","required":["request_id","person_code","display_name","scope_id","submitted_at","status","identity_verified","identity_level","justification_type"],"title":"MembershipRequest","examples":[{"display_name":"Marie Martin","identity_level":3,"identity_verified":true,"justification_type":"employee_badge","justification_url":"https://storage.example.com/badge.pdf?token=abc","motivation":"Souhait de contribuer","person_code":"FR-P-200","request_id":"req-001","scope_id":"FR-company-edf","status":"pending","submitted_at":"2025-06-01T10:00:00Z"}]},"MembershipSubmissionPayload":{"properties":{"person_code":{"type":"string","title":"Person Code"},"display_name":{"type":"string","title":"Display Name"},"scope_id":{"type":"string","title":"Scope Id"},"scope_name":{"type":"string","title":"Scope Name"},"module_type":{"type":"string","title":"Module Type"},"justification_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Justification Type"},"country_code":{"type":"string","title":"Country Code","default":"FR"}},"type":"object","required":["person_code","display_name","scope_id","scope_name","module_type"],"title":"MembershipSubmissionPayload","description":"Received from CivicPerson when a citizen requests a sectoral membership."},"MyScopesResponse":{"properties":{"user_country":{"type":"string","title":"User Country"},"scopes":{"items":{"$ref":"#/components/schemas/AmbassadorScope"},"type":"array","title":"Scopes"}},"type":"object","required":["user_country","scopes"],"title":"MyScopesResponse"},"NavigatorBreadcrumbResponse":{"properties":{"scope_id":{"type":"string","title":"Scope Id"},"country_code":{"type":"string","title":"Country Code"},"node_code":{"type":"string","title":"Node Code"},"segments":{"items":{"$ref":"#/components/schemas/NavigatorNode"},"type":"array","title":"Segments"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["scope_id","country_code","node_code","segments","total"],"title":"NavigatorBreadcrumbResponse","description":"Response for GET /scopes/{id}/navigator/breadcrumb endpoint."},"NavigatorMenuResponse":{"properties":{"scope_id":{"type":"string","title":"Scope Id"},"country_code":{"type":"string","title":"Country Code"},"parent_node_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Node Code"},"level_code":{"type":"string","title":"Level Code"},"nodes":{"items":{"$ref":"#/components/schemas/NavigatorNode"},"type":"array","title":"Nodes"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["scope_id","country_code","level_code","nodes","total"],"title":"NavigatorMenuResponse","description":"Response for GET /scopes/{id}/navigator/menu endpoint."},"NavigatorNode":{"properties":{"country_code":{"type":"string","title":"Country Code"},"level_code":{"type":"string","title":"Level Code"},"node_code":{"type":"string","title":"Node Code"},"node_name":{"type":"string","title":"Node Name"},"parent_node_code":{"type":"string","title":"Parent Node Code","default":""},"depth":{"type":"integer","title":"Depth","default":0},"has_data":{"type":"boolean","title":"Has Data","default":true},"is_active":{"type":"boolean","title":"Is Active","default":true},"has_children":{"type":"boolean","title":"Has Children","default":false},"population_count":{"type":"integer","title":"Population Count","default":0}},"type":"object","required":["country_code","level_code","node_code","node_name"],"title":"NavigatorNode","description":"A navigation-only node from ambassador_territory_navigator."},"OcrExtractedData":{"properties":{"first_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"First Name"},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Name"},"birth_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Birth Date"},"expiry_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expiry Date"},"document_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Number"},"nationality":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nationality"}},"type":"object","title":"OcrExtractedData"},"PathSegment":{"properties":{"code":{"type":"string","title":"Code"},"name":{"type":"string","title":"Name"},"level":{"type":"string","title":"Level"},"is_clickable":{"type":"boolean","title":"Is Clickable"}},"type":"object","required":["code","name","level","is_clickable"],"title":"PathSegment","description":"A single segment in a resolved territorial path."},"PendingCandidate":{"properties":{"person_code":{"type":"string","title":"Person Code"},"display_name":{"type":"string","title":"Display Name"},"submitted_at":{"type":"string","format":"date-time","title":"Submitted At"},"target_level":{"type":"string","title":"Target Level"},"requested_zone":{"type":"string","title":"Requested Zone"},"requested_zone_name":{"type":"string","title":"Requested Zone Name"},"motivation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Motivation"},"eligibility":{"$ref":"#/components/schemas/CandidateEligibility"},"verification_level":{"type":"integer","title":"Verification Level"}},"type":"object","required":["person_code","display_name","submitted_at","target_level","requested_zone","requested_zone_name","eligibility","verification_level"],"title":"PendingCandidate","examples":[{"display_name":"Pierre Durand","eligibility":{"all_criteria_met":true,"blocking_criteria":[],"citizen_since_days":365,"has_sanctions":false,"is_resident":true,"verification_level":3},"motivation":"Experience de 3 ans","person_code":"FR-P-300","requested_zone":"FR-ARA","requested_zone_name":"Auvergne-Rhone-Alpes","submitted_at":"2025-06-01T10:00:00Z","target_level":"SENIOR_REGION","verification_level":3}]},"PendingClaim":{"properties":{"claim_id":{"type":"string","title":"Claim Id"},"claimant_person_code":{"type":"string","title":"Claimant Person Code"},"claimant_display_name":{"type":"string","title":"Claimant Display Name"},"target_type":{"type":"string","title":"Target Type"},"target_person_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Person Code"},"target_actor_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Actor Code"},"target_display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Display Name"},"claim_type":{"type":"string","title":"Claim Type"},"claim_role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Claim Role"},"evidence_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Evidence Type"},"validation_method":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Validation Method"},"status":{"type":"string","title":"Status"},"community_votes_yes":{"type":"integer","title":"Community Votes Yes","default":0},"community_votes_no":{"type":"integer","title":"Community Votes No","default":0},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["claim_id","claimant_person_code","claimant_display_name","target_type","claim_type","status"],"title":"PendingClaim","examples":[{"claim_id":"claim-001","claim_role":"DG","claim_type":"OWNS","claimant_display_name":"Jacques Martin","claimant_person_code":"FR-P-400","community_votes_no":0,"community_votes_yes":0,"created_at":"2025-06-01T10:00:00Z","evidence_type":"NONE","status":"PENDING","target_display_name":"ACME SAS","target_person_code":"FR-M-100","target_type":"CIVICPERSON","validation_method":"AMBASSADOR"}]},"PendingIdentity":{"properties":{"verification_id":{"type":"string","title":"Verification Id"},"person_code":{"type":"string","title":"Person Code"},"display_name":{"type":"string","title":"Display Name"},"submitted_at":{"type":"string","format":"date-time","title":"Submitted At"},"document_type":{"type":"string","title":"Document Type"},"auto_scores":{"$ref":"#/components/schemas/AutoValidationScores"},"location":{"$ref":"#/components/schemas/GeographicLocation"},"priority":{"type":"string","enum":["normal","high"],"title":"Priority"}},"type":"object","required":["verification_id","person_code","display_name","submitted_at","document_type","auto_scores","location","priority"],"title":"PendingIdentity","examples":[{"auto_scores":{"duplicate_check":true,"expiry_valid":true,"face_match":0.92,"name_match":0.98,"ocr_fields_extracted":6,"overall_status":"pass","template_match":0.95},"display_name":"Jean Dupont","document_type":"national_id","location":{"city_code":"69123","country_code":"FR","department_code":"69","region_code":"ARA"},"person_code":"FR-P-100","priority":"normal","submitted_at":"2025-06-01T10:00:00Z","verification_id":"vid-001"}]},"PreviousAttempt":{"properties":{"attempt_date":{"type":"string","format":"date-time","title":"Attempt Date"},"status":{"type":"string","title":"Status"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason"}},"type":"object","required":["attempt_date","status"],"title":"PreviousAttempt"},"ProjectionBatchAck":{"properties":{"status":{"type":"string","title":"Status","default":"ok"},"created":{"type":"integer","title":"Created","default":0},"updated":{"type":"integer","title":"Updated","default":0},"failed":{"type":"integer","title":"Failed","default":0}},"type":"object","title":"ProjectionBatchAck","description":"S2S ack for projection batch upserts."},"ProjectionBatchPayload":{"properties":{"country_code":{"type":"string","title":"Country Code"},"sync_batch_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sync Batch Id"},"rows":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Rows"}},"type":"object","required":["country_code","rows"],"title":"ProjectionBatchPayload","description":"Generic S2S batch payload for projection upserts."},"RejectCandidateRequest":{"properties":{"reason":{"type":"string","enum":["insufficient_experience","residency_issue","verification_incomplete","zone_already_covered","other"],"title":"Reason"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes"}},"type":"object","required":["reason"],"title":"RejectCandidateRequest"},"RejectClaimRequest":{"properties":{"reason":{"type":"string","enum":["identity_mismatch","no_evidence","evidence_invalid","entity_not_found","suspected_fraud","other"],"title":"Reason"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes"}},"type":"object","required":["reason"],"title":"RejectClaimRequest"},"RejectIdentityRequest":{"properties":{"reason":{"type":"string","enum":["document_illegible","document_expired","photo_mismatch","name_mismatch","suspected_fraud","other"],"title":"Reason"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes"}},"type":"object","required":["reason"],"title":"RejectIdentityRequest"},"RejectMembershipRequest":{"properties":{"reason":{"type":"string","enum":["not_a_member","justification_invalid","justification_expired","identity_not_verified","other"],"title":"Reason"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes"}},"type":"object","required":["reason"],"title":"RejectMembershipRequest"},"ResolvedPathResponse":{"properties":{"country_code":{"type":"string","title":"Country Code"},"country_name":{"type":"string","title":"Country Name"},"segments":{"items":{"$ref":"#/components/schemas/PathSegment"},"type":"array","title":"Segments"},"current_zone_name":{"type":"string","title":"Current Zone Name"},"current_zone_level":{"type":"string","title":"Current Zone Level"},"children_count":{"type":"integer","title":"Children Count"}},"type":"object","required":["country_code","country_name","segments","current_zone_name","current_zone_level","children_count"],"title":"ResolvedPathResponse","description":"Response for GET /scopes/{id}/resolve-path endpoint."},"S2SAckResponse":{"properties":{"status":{"type":"string","title":"Status","default":"ok"},"event_emitted":{"type":"boolean","title":"Event Emitted","default":true}},"type":"object","title":"S2SAckResponse"},"ScopeAggregates":{"properties":{"scope_id":{"type":"string","title":"Scope Id"},"scope_name":{"type":"string","title":"Scope Name"},"total_entities":{"type":"integer","title":"Total Entities"},"validated_count":{"type":"integer","title":"Validated Count"},"pending_count":{"type":"integer","title":"Pending Count"},"coverage_rate":{"type":"number","title":"Coverage Rate"},"trend_7d":{"type":"number","title":"Trend 7D"},"trend_30d":{"type":"number","title":"Trend 30D"},"sub_scope_stats":{"items":{"$ref":"#/components/schemas/SubScopeStats"},"type":"array","title":"Sub Scope Stats"},"alerts":{"items":{"$ref":"#/components/schemas/ScopeAlert"},"type":"array","title":"Alerts"}},"type":"object","required":["scope_id","scope_name","total_entities","validated_count","pending_count","coverage_rate","trend_7d","trend_30d","sub_scope_stats","alerts"],"title":"ScopeAggregates"},"ScopeAlert":{"properties":{"alert_id":{"type":"string","title":"Alert Id"},"sub_scope_id":{"type":"string","title":"Sub Scope Id"},"sub_scope_name":{"type":"string","title":"Sub Scope Name"},"alert_type":{"type":"string","enum":["threshold_critical","threshold_warning","trend_negative"],"title":"Alert Type"},"message":{"type":"string","title":"Message"},"value":{"type":"number","title":"Value"},"threshold":{"type":"number","title":"Threshold"}},"type":"object","required":["alert_id","sub_scope_id","sub_scope_name","alert_type","message","value","threshold"],"title":"ScopeAlert"},"ScopeNavigationItem":{"properties":{"scope_id":{"type":"string","title":"Scope Id"},"scope_name":{"type":"string","title":"Scope Name"},"level":{"type":"string","title":"Level"},"entity_count":{"type":"integer","title":"Entity Count"},"coverage_rate":{"type":"number","title":"Coverage Rate"},"alert_level":{"type":"string","enum":["ok","warning","critical"],"title":"Alert Level"}},"type":"object","required":["scope_id","scope_name","level","entity_count","coverage_rate","alert_level"],"title":"ScopeNavigationItem"},"ScopeNavigationResponse":{"properties":{"current":{"$ref":"#/components/schemas/AmbassadorScope"},"parent":{"anyOf":[{"$ref":"#/components/schemas/ScopeNavigationItem"},{"type":"null"}]},"children":{"items":{"$ref":"#/components/schemas/ScopeNavigationItem"},"type":"array","title":"Children"}},"type":"object","required":["current","parent","children"],"title":"ScopeNavigationResponse"},"ScopeRelation":{"properties":{"scope_id":{"type":"string","title":"Scope Id"},"scope_name":{"type":"string","title":"Scope Name"},"level":{"type":"string","title":"Level"},"relation_type":{"type":"string","title":"Relation Type"},"module_type":{"type":"string","title":"Module Type","default":""},"sector_type":{"type":"string","title":"Sector Type","default":""}},"type":"object","required":["scope_id","scope_name","level","relation_type"],"title":"ScopeRelation"},"ScopeRelationsResponse":{"properties":{"scope_id":{"type":"string","title":"Scope Id"},"parent":{"anyOf":[{"$ref":"#/components/schemas/ScopeRelation"},{"type":"null"}]},"children":{"items":{"$ref":"#/components/schemas/ScopeRelation"},"type":"array","title":"Children"},"siblings":{"items":{"$ref":"#/components/schemas/ScopeRelation"},"type":"array","title":"Siblings"}},"type":"object","required":["scope_id","children","siblings"],"title":"ScopeRelationsResponse"},"ScopeSiblingsResponse":{"properties":{"scope_id":{"type":"string","title":"Scope Id"},"siblings":{"items":{"$ref":"#/components/schemas/ScopeRelation"},"type":"array","title":"Siblings"}},"type":"object","required":["scope_id","siblings"],"title":"ScopeSiblingsResponse"},"ScopeTrends":{"properties":{"scope_id":{"type":"string","title":"Scope Id"},"period":{"type":"string","enum":["7d","30d"],"title":"Period"},"points":{"items":{"$ref":"#/components/schemas/TrendPoint"},"type":"array","title":"Points"}},"type":"object","required":["scope_id","period","points"],"title":"ScopeTrends"},"SubScopeStats":{"properties":{"sub_scope_id":{"type":"string","title":"Sub Scope Id"},"sub_scope_name":{"type":"string","title":"Sub Scope Name"},"total_entities":{"type":"integer","title":"Total Entities"},"validated_count":{"type":"integer","title":"Validated Count"},"coverage_rate":{"type":"number","title":"Coverage Rate"},"trend_7d":{"type":"number","title":"Trend 7D"},"alert_level":{"type":"string","enum":["ok","warning","critical"],"title":"Alert Level"}},"type":"object","required":["sub_scope_id","sub_scope_name","total_entities","validated_count","coverage_rate","trend_7d","alert_level"],"title":"SubScopeStats"},"TrendPoint":{"properties":{"date":{"type":"string","title":"Date"},"coverage_rate":{"type":"number","title":"Coverage Rate"},"validated_count":{"type":"integer","title":"Validated Count"}},"type":"object","required":["date","coverage_rate","validated_count"],"title":"TrendPoint"},"UserProfile":{"properties":{"user_id":{"type":"string","format":"uuid","title":"User Id"},"person_code":{"type":"string","title":"Person Code"},"display_name":{"type":"string","title":"Display Name"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"scopes":{"items":{"$ref":"#/components/schemas/AmbassadorScope"},"type":"array","title":"Scopes"}},"type":"object","required":["user_id","person_code","display_name","scopes"],"title":"UserProfile"},"ValidationDecisionResponse":{"properties":{"status":{"type":"string","title":"Status"},"message":{"type":"string","title":"Message"}},"type":"object","required":["status","message"],"title":"ValidationDecisionResponse"},"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"},"ValidationHistoryItem":{"properties":{"validation_id":{"type":"string","title":"Validation Id"},"type":{"type":"string","enum":["identity","membership","candidate","claim"],"title":"Type"},"person_code":{"type":"string","title":"Person Code"},"display_name":{"type":"string","title":"Display Name"},"decision":{"type":"string","enum":["approved","rejected"],"title":"Decision"},"decided_at":{"type":"string","format":"date-time","title":"Decided At"},"decided_by":{"type":"string","title":"Decided By"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes"}},"type":"object","required":["validation_id","type","person_code","display_name","decision","decided_at","decided_by"],"title":"ValidationHistoryItem"},"ValidationHistoryResponse":{"properties":{"total":{"type":"integer","title":"Total"},"cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"},"has_more":{"type":"boolean","title":"Has More"},"items":{"items":{"$ref":"#/components/schemas/ValidationHistoryItem"},"type":"array","title":"Items"}},"type":"object","required":["total","has_more","items"],"title":"ValidationHistoryResponse"},"ValidationQueueResponse":{"properties":{"identities":{"anyOf":[{"$ref":"#/components/schemas/IdentityQueue"},{"type":"null"}]},"memberships":{"anyOf":[{"$ref":"#/components/schemas/MembershipQueue"},{"type":"null"}]},"candidates":{"$ref":"#/components/schemas/CandidateQueue"},"claims":{"anyOf":[{"$ref":"#/components/schemas/ClaimQueue"},{"type":"null"}]},"total_identities":{"type":"integer","title":"Total Identities","default":0},"total_memberships":{"type":"integer","title":"Total Memberships","default":0},"total_candidates":{"type":"integer","title":"Total Candidates","default":0},"total_claims":{"type":"integer","title":"Total Claims","default":0}},"type":"object","required":["candidates"],"title":"ValidationQueueResponse","examples":[{"candidates":{"has_more":false,"items":[],"total":0},"claims":{"has_more":false,"items":[],"total":0},"identities":{"has_more":false,"items":[],"total":0},"total_candidates":0,"total_claims":0,"total_identities":0,"total_memberships":0}]},"ZoneAmbassador":{"properties":{"person_code":{"type":"string","title":"Person Code"},"display_name":{"type":"string","title":"Display Name"},"role":{"type":"string","title":"Role"},"verification_level":{"type":"integer","title":"Verification Level","default":0},"is_verified":{"type":"boolean","title":"Is Verified","default":false},"photo_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Photo Url"}},"type":"object","required":["person_code","display_name","role"],"title":"ZoneAmbassador","description":"An ambassador assigned to a territorial zone."},"ZoneAmbassadorsResponse":{"properties":{"zone_code":{"type":"string","title":"Zone Code"},"zone_name":{"type":"string","title":"Zone Name"},"ambassadors":{"items":{"$ref":"#/components/schemas/ZoneAmbassador"},"type":"array","title":"Ambassadors"}},"type":"object","required":["zone_code","zone_name","ambassadors"],"title":"ZoneAmbassadorsResponse","description":"Response for GET /scopes/{id}/ambassadors endpoint."}},"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}}},"tags":[{"name":"meta","description":"Health check, home page, and API metadata."},{"name":"auth","description":"Authentication: current user profile and token introspection."},{"name":"scopes","description":"Scope navigation: hierarchy, relations, siblings, and entities."},{"name":"countries","description":"Active countries list (PM only). Proxied from Identity Backend, enriched with ClickHouse GDAM coordinates."},{"name":"aggregates","description":"KPI aggregates: coverage rates, trends, and alerts (ClickHouse GDAM)."},{"name":"geometry","description":"GeoJSON geometry for map rendering. Reads ClickHouse GDAM (WKT→GeoJSON), enriched with coverage stats."},{"name":"validation-queue","description":"Unified validation queue and decision history across all types."},{"name":"validation-identities","description":"Type A — Identity verification (area module only). Guard rails: capability check, daily quota, self-validation block, module type enforcement."},{"name":"validation-memberships","description":"Type B — Membership requests (sectoral modules only). Guard rails: module type enforcement (area scope → 403)."},{"name":"validation-candidates","description":"Type C — Ambassador candidate promotion (all modules). Guard rails: capability check, daily quota, self-validation block, cascade N+1, eligibility (verification_level, account_age)."},{"name":"validation-claims","description":"Type D — Entity claims (all modules). Guard rails: capability check, daily quota, self-validation block. Decisions forwarded to CivicPerson via S2S /system/claims/{id}/resolve."},{"name":"activity","description":"Activity feed: REST history and SSE real-time events (Redis Streams)."},{"name":"system","description":"Service-to-service endpoints (X-Service-API-Key auth). Used by CivicPerson and Identity Backend."}]}