{
  "openapi": "3.0.3",
  "info": {
    "title": "American Ascent RESTful API",
    "version": "1.0.0",
    "description": "Production grade RESTful API for the American Ascent political scouting, recruitment, and opposition intelligence database.",
    "contact": {
      "name": "American Ascent Architecture Team",
      "email": "architect@americanascent.internal"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://americanascent.org/terms"
    }
  },
  "servers": [
    {
      "url": "http://localhost:8420",
      "description": "Primary API Server"
    }
  ],
  "tags": [
    {
      "name": "System",
      "description": "Health, telemetry, and API documentation endpoints"
    },
    {
      "name": "Authentication",
      "description": "Session token generation and role inspection"
    },
    {
      "name": "Candidates",
      "description": "Candidate profiles, verified dossiers, resumes, and career history"
    },
    {
      "name": "Districts",
      "description": "Congressional districts, PVI metrics, media costs, and ground strategy"
    },
    {
      "name": "Senate Races",
      "description": "2028 Senate gerontocracy targets and race status"
    },
    {
      "name": "Governor Races",
      "description": "2028 Gubernatorial open seat transitions and qualifications"
    },
    {
      "name": "Anticipated Seats",
      "description": "Multi-chamber empirical vacancy criteria and signals"
    },
    {
      "name": "Outreach Pipeline",
      "description": "Recruitment outreach tracking, contact milestones, and memos"
    },
    {
      "name": "Network Graph",
      "description": "Ecosystem relationship graph nodes, edges, and PageRank scores"
    },
    {
      "name": "Opposition Research",
      "description": "Incumbent dossiers, contrast research, and donor intelligence"
    },
    {
      "name": "Organizations",
      "description": "Coalition partner validator organizations and PAC intelligence"
    },
    {
      "name": "Elections & Voting",
      "description": "Congressional and statewide historical election contest outcomes and voting history"
    },
    {
      "name": "Candidate Prospecting & Lifecycle",
      "description": "Candidate prospecting roster, predictive race electorate models, lifecycle milestone tracking, outreach logs, matchup simulations, and viability scoring"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "HMAC",
        "description": "HMAC signed session token"
      },
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Bootstrap or provisioned API key"
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "required": [
          "error",
          "status_code"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "detail": {
            "type": "string"
          },
          "status_code": {
            "type": "integer"
          }
        }
      },
      "LoginRequest": {
        "type": "object",
        "required": [
          "api_key"
        ],
        "properties": {
          "api_key": {
            "type": "string",
            "example": "ascent-admin-key-2027"
          }
        }
      },
      "LoginResponse": {
        "type": "object",
        "properties": {
          "token": {
            "type": "string"
          },
          "role": {
            "type": "string",
            "enum": [
              "ADMIN",
              "STAFF",
              "READER"
            ]
          },
          "user_id": {
            "type": "string"
          },
          "expires_in": {
            "type": "integer"
          }
        }
      },
      "UserContext": {
        "type": "object",
        "properties": {
          "user_id": {
            "type": "string"
          },
          "role": {
            "type": "string"
          },
          "auth_type": {
            "type": "string"
          }
        }
      },
      "CandidateSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "candidate_id": {
            "type": "string",
            "example": "ASC-OK04-001"
          },
          "name": {
            "type": "string"
          },
          "target_district_code": {
            "type": "string",
            "example": "OK-04"
          },
          "state": {
            "type": "string"
          },
          "birth_year": {
            "type": "integer"
          },
          "estimated_age_2027": {
            "type": "integer"
          },
          "current_role": {
            "type": "string"
          },
          "primary_career_track": {
            "type": "string"
          },
          "sector": {
            "type": "string"
          },
          "readiness_tier": {
            "type": "string"
          },
          "national_rank": {
            "type": "integer"
          }
        }
      },
      "CandidateDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CandidateSummary"
          },
          {
            "type": "object",
            "properties": {
              "city": {
                "type": "string"
              },
              "county_residence": {
                "type": "string"
              },
              "organization": {
                "type": "string"
              },
              "education": {
                "type": "string"
              },
              "headline_achievement": {
                "type": "string"
              },
              "fit_rationale": {
                "type": "string"
              },
              "seed_capital_feasibility_score": {
                "type": "number"
              },
              "seed_capital_rating": {
                "type": "string"
              },
              "first_90_days_seed_target": {
                "type": "number"
              },
              "outreach": {
                "type": "object"
              },
              "career_positions": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              },
              "contact": {
                "type": "object"
              }
            }
          }
        ]
      },
      "CandidateUpdate": {
        "type": "object",
        "properties": {
          "current_role": {
            "type": "string"
          },
          "organization": {
            "type": "string"
          },
          "headline_achievement": {
            "type": "string"
          },
          "fit_rationale": {
            "type": "string"
          },
          "readiness_tier": {
            "type": "string",
            "enum": [
              "Tier 1: High-Priority Ready",
              "Tier 2: High-Potential Cultivate",
              "Tier 3: Farm Team Monitor"
            ]
          },
          "sector": {
            "type": "string",
            "enum": [
              "BUSINESS",
              "EDUCATION",
              "TRADES",
              "PUBLIC_SERVICE",
              "VETERANS"
            ]
          },
          "primary_career_track": {
            "type": "string"
          },
          "seed_capital_rating": {
            "type": "string"
          },
          "seed_capital_feasibility_score": {
            "type": "number",
            "minimum": 0,
            "maximum": 100
          }
        }
      },
      "CareerPositionCreate": {
        "type": "object",
        "required": [
          "organization_name",
          "title"
        ],
        "properties": {
          "organization_name": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "position_type": {
            "type": "string",
            "default": "FORMER_EMPLOYER"
          },
          "start_date": {
            "type": "string",
            "example": "2021-01-01"
          },
          "end_date": {
            "type": "string",
            "example": "2024-05-01"
          },
          "is_current": {
            "type": "boolean",
            "default": false
          },
          "supervisor_name": {
            "type": "string"
          },
          "supervisor_title": {
            "type": "string"
          },
          "relationship_type": {
            "type": "string",
            "default": "WORKED_WITH"
          },
          "colleagues_worked_with": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "key_achievements": {
            "type": "string"
          },
          "data_source": {
            "type": "string",
            "default": "DIRECT_STAFF_INTEL"
          }
        }
      },
      "OutreachUpdate": {
        "type": "object",
        "properties": {
          "outreach_tier": {
            "type": "string",
            "enum": [
              "TIER_1_IMMEDIATE",
              "TIER_2_EXPANSION",
              "TIER_3_PIPELINE"
            ]
          },
          "contact_status": {
            "type": "string",
            "enum": [
              "UNCONTACTED",
              "MEMO_DISPATCHED",
              "BRIEFING_SCHEDULED",
              "FELLOWSHIP_INTERVIEW",
              "CAMPAIGN_COMMITTED",
              "DECLINED"
            ]
          },
          "notes": {
            "type": "string"
          },
          "contact_attempts": {
            "type": "integer"
          }
        }
      },
      "DistrictDetail": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "district_code": {
            "type": "string"
          },
          "state": {
            "type": "string"
          },
          "cook_pvi": {
            "type": "string"
          },
          "pvi_num": {
            "type": "integer"
          },
          "media_market_dma": {
            "type": "string"
          },
          "media_cost_tier": {
            "type": "string"
          },
          "primary_win_budget": {
            "type": "number"
          },
          "expected_turnout_volume": {
            "type": "string"
          },
          "geography_type": {
            "type": "string"
          },
          "ground_strategy": {
            "type": "string"
          },
          "candidates": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "incumbent": {
            "type": "object"
          }
        }
      },
      "SenateRace": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "senate_code": {
            "type": "string"
          },
          "state": {
            "type": "string"
          },
          "state_abbr": {
            "type": "string"
          },
          "incumbent_name": {
            "type": "string"
          },
          "incumbent_age_2027": {
            "type": "integer"
          },
          "is_aging_target": {
            "type": "boolean"
          },
          "seat_status": {
            "type": "string"
          }
        }
      },
      "GovernorRace": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "gov_code": {
            "type": "string"
          },
          "state": {
            "type": "string"
          },
          "state_abbr": {
            "type": "string"
          },
          "is_open_seat": {
            "type": "boolean"
          },
          "current_governor_name": {
            "type": "string"
          },
          "open_seat_reason": {
            "type": "string"
          }
        }
      },
      "TelemetrySummary": {
        "type": "object",
        "properties": {
          "total_candidates": {
            "type": "integer"
          },
          "total_districts": {
            "type": "integer"
          },
          "total_senate_races": {
            "type": "integer"
          },
          "total_governor_races": {
            "type": "integer"
          },
          "anticipated_criteria_count": {
            "type": "integer"
          },
          "graph_node_count": {
            "type": "integer"
          },
          "graph_edge_count": {
            "type": "integer"
          },
          "outreach_summary": {
            "type": "object"
          },
          "candidates_by_sector": {
            "type": "object"
          }
        }
      },
      "OrganizationSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "code": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "pillar_number": {
            "type": "integer"
          },
          "pillar_name": {
            "type": "string"
          },
          "state": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "website": {
            "type": "string"
          },
          "executive_director_name": {
            "type": "string"
          },
          "direct_phone": {
            "type": "string"
          },
          "direct_email": {
            "type": "string"
          },
          "org_directory_id": {
            "type": "string"
          },
          "has_pac": {
            "type": "boolean"
          },
          "pac_name": {
            "type": "string"
          },
          "pac_cash_on_hand_usd": {
            "type": "number"
          },
          "logo_url": {
            "type": "string"
          }
        }
      },
      "OrganizationPacResponse": {
        "type": "object",
        "properties": {
          "org_code": {
            "type": "string"
          },
          "organization_code": {
            "type": "string"
          },
          "has_pac": {
            "type": "boolean"
          },
          "pac_intelligence": {
            "type": "object",
            "properties": {
              "has_pac": {
                "type": "boolean"
              },
              "pac_name": {
                "type": "string"
              },
              "cash_on_hand_usd": {
                "type": "number"
              },
              "total_receipts_usd": {
                "type": "number"
              },
              "independent_expenditures_usd": {
                "type": "number"
              },
              "direct_candidate_contributions_usd": {
                "type": "number"
              }
            }
          },
          "disbursements": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "ElectionContest": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "office_type": {
            "type": "string"
          },
          "state": {
            "type": "string"
          },
          "district_code": {
            "type": "string"
          },
          "election_year": {
            "type": "integer"
          },
          "election_date": {
            "type": "string"
          },
          "contest_type": {
            "type": "string"
          },
          "winner_name": {
            "type": "string"
          },
          "winner_party": {
            "type": "string"
          },
          "total_votes_cast": {
            "type": "integer"
          },
          "results": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "DistrictVotingHistory": {
        "type": "object",
        "properties": {
          "district_code": {
            "type": "string"
          },
          "state": {
            "type": "string"
          },
          "cook_pvi": {
            "type": "string"
          },
          "median_household_income": {
            "type": "number"
          },
          "college_educated_pct": {
            "type": "number"
          },
          "voter_turnout_pct": {
            "type": "number"
          },
          "total_registered_voters": {
            "type": "integer"
          },
          "contests": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ElectionContest"
            }
          }
        }
      },
      "IncumbentTopDonorsResponse": {
        "type": "object",
        "properties": {
          "target_code": {
            "type": "string"
          },
          "district_code": {
            "type": "string"
          },
          "donors": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "CandidateMilestone": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "candidate_id": {
            "type": "integer"
          },
          "milestone_code": {
            "type": "string"
          },
          "milestone_title": {
            "type": "string"
          },
          "milestone_stage": {
            "type": "string"
          },
          "target_date": {
            "type": "string",
            "format": "date",
            "nullable": true
          },
          "completion_date": {
            "type": "string",
            "format": "date",
            "nullable": true
          },
          "status": {
            "type": "string",
            "enum": [
              "PENDING",
              "IN_PROGRESS",
              "ACHIEVED",
              "BLOCKED",
              "WAIVED"
            ]
          },
          "verification_evidence": {
            "type": "string"
          },
          "assigned_director": {
            "type": "string"
          },
          "sort_order": {
            "type": "integer"
          }
        }
      },
      "CandidateOutreachActivity": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "candidate_id": {
            "type": "integer"
          },
          "activity_type": {
            "type": "string"
          },
          "contact_person": {
            "type": "string"
          },
          "staff_member": {
            "type": "string"
          },
          "activity_date": {
            "type": "string",
            "format": "date"
          },
          "disposition": {
            "type": "string"
          },
          "executive_summary": {
            "type": "string"
          },
          "action_items": {
            "type": "string"
          },
          "next_followup_date": {
            "type": "string",
            "format": "date",
            "nullable": true
          }
        }
      },
      "RaceElectorateModel": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "race_code": {
            "type": "string"
          },
          "office_type": {
            "type": "string"
          },
          "state": {
            "type": "string"
          },
          "state_abbr": {
            "type": "string"
          },
          "district_number": {
            "type": "string"
          },
          "cycle_year": {
            "type": "integer"
          },
          "registered_voters_republican": {
            "type": "integer"
          },
          "registered_voters_total": {
            "type": "integer"
          },
          "projected_primary_turnout": {
            "type": "integer"
          },
          "primary_win_number": {
            "type": "integer"
          },
          "projected_general_turnout": {
            "type": "integer"
          },
          "general_win_number": {
            "type": "integer"
          },
          "target_vote_share_pct": {
            "type": "number"
          },
          "cost_per_primary_vote": {
            "type": "number"
          },
          "total_primary_budget_target": {
            "type": "number"
          },
          "grassroots_doors_target": {
            "type": "integer"
          },
          "absentee_mail_voters_pool": {
            "type": "integer"
          },
          "incumbent_vulnerability_index": {
            "type": "number"
          },
          "coalition_readiness_score": {
            "type": "number"
          },
          "primary_electorate_character": {
            "type": "string"
          },
          "strategic_imperative_summary": {
            "type": "string"
          }
        }
      },
      "CandidateMatchupSimulation": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "candidate_id": {
            "type": "integer"
          },
          "race_code": {
            "type": "string"
          },
          "opponent_name": {
            "type": "string"
          },
          "opponent_role": {
            "type": "string"
          },
          "opponent_archetype": {
            "type": "string"
          },
          "rural_agrarian_margin": {
            "type": "number"
          },
          "suburban_family_margin": {
            "type": "number"
          },
          "working_class_trades_margin": {
            "type": "number"
          },
          "veterans_first_responders_margin": {
            "type": "number"
          },
          "small_business_margin": {
            "type": "number"
          },
          "simulated_primary_vote_share": {
            "type": "number"
          },
          "projected_margin_of_victory": {
            "type": "number"
          },
          "key_breakthrough_wedge": {
            "type": "string"
          },
          "primary_vulnerability_to_neutralize": {
            "type": "string"
          },
          "turnout_sensitivity_analysis": {
            "type": "object"
          }
        }
      },
      "CandidateViabilityResponse": {
        "type": "object",
        "properties": {
          "candidate_id": {
            "type": "string"
          },
          "candidate_name": {
            "type": "string"
          },
          "target_office": {
            "type": "string"
          },
          "target_district_code": {
            "type": "string"
          },
          "ascent_viability_index": {
            "type": "number"
          },
          "readiness_verdict": {
            "type": "string"
          },
          "projected_primary_vote_share": {
            "type": "number"
          },
          "primary_win_number": {
            "type": "integer"
          },
          "primary_budget_target_usd": {
            "type": "number"
          },
          "milestone_progress": {
            "type": "object"
          },
          "key_breakthrough_wedge": {
            "type": "string"
          },
          "primary_vulnerability_to_neutralize": {
            "type": "string"
          },
          "key_strengths": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "critical_action_items": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "ProspectingCommandRosterResponse": {
        "type": "object",
        "properties": {
          "total_count": {
            "type": "integer"
          },
          "limit": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          },
          "prospects": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "CandidateDevelopmentProfile": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "candidate_id": {
            "type": "integer"
          },
          "candidate_code": {
            "type": "string"
          },
          "candidate_name": {
            "type": "string"
          },
          "media_readiness_score": {
            "type": "number"
          },
          "stump_speech_mastery_score": {
            "type": "number"
          },
          "grassroots_field_appeal_score": {
            "type": "number"
          },
          "fundraising_confidence_score": {
            "type": "number"
          },
          "policy_mastery_score": {
            "type": "number"
          },
          "crisis_management_score": {
            "type": "number"
          },
          "composite_development_index": {
            "type": "number"
          },
          "assigned_mentor": {
            "type": "string"
          },
          "primary_development_priority": {
            "type": "string"
          },
          "stump_speech_video_reference": {
            "type": "string"
          },
          "media_simulation_notes": {
            "type": "string"
          },
          "last_coaching_session_date": {
            "type": "string",
            "format": "date"
          },
          "next_coaching_session_date": {
            "type": "string",
            "format": "date"
          }
        }
      },
      "CandidateTrainingModule": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "candidate_id": {
            "type": "integer"
          },
          "module_code": {
            "type": "string"
          },
          "module_title": {
            "type": "string"
          },
          "curriculum_domain": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "PENDING",
              "IN_PROGRESS",
              "COMPLETED",
              "EXEMPT_VERIFIED"
            ]
          },
          "score": {
            "type": "number",
            "nullable": true
          },
          "certified_by": {
            "type": "string",
            "nullable": true
          },
          "completion_date": {
            "type": "string",
            "format": "date",
            "nullable": true
          },
          "notes": {
            "type": "string"
          }
        }
      },
      "RaceVictoryBattleplan": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "race_code": {
            "type": "string"
          },
          "office_type": {
            "type": "string"
          },
          "state": {
            "type": "string"
          },
          "state_abbr": {
            "type": "string"
          },
          "cycle_year": {
            "type": "integer"
          },
          "battleground_tier": {
            "type": "string"
          },
          "phase_1_recon_and_scouting": {
            "type": "string"
          },
          "phase_2_exploratory_and_seed_capital": {
            "type": "string"
          },
          "phase_3_campaign_launch_and_media": {
            "type": "string"
          },
          "phase_4_ground_operations_and_absentee": {
            "type": "string"
          },
          "phase_5_primary_surge_and_get_out_the_vote": {
            "type": "string"
          },
          "total_campaign_budget_usd": {
            "type": "number"
          },
          "field_offices_target": {
            "type": "integer"
          },
          "precinct_captains_target": {
            "type": "integer"
          },
          "key_victory_milestone_metric": {
            "type": "string"
          },
          "strategic_summary": {
            "type": "string"
          }
        }
      },
      "CandidateEvaluationAssessment": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "candidate_id": {
            "type": "integer"
          },
          "candidate_code": {
            "type": "string"
          },
          "candidate_name": {
            "type": "string"
          },
          "evaluator_name": {
            "type": "string"
          },
          "evaluation_date": {
            "type": "string",
            "format": "date"
          },
          "electoral_viability_score": {
            "type": "number"
          },
          "fundraising_velocity_score": {
            "type": "number"
          },
          "rhetorical_readiness_score": {
            "type": "number"
          },
          "constitutional_orthodoxy_score": {
            "type": "number"
          },
          "adversarial_resilience_score": {
            "type": "number"
          },
          "infrastructure_capacity_score": {
            "type": "number"
          },
          "composite_assessment_score": {
            "type": "number"
          },
          "overall_assessment_tier": {
            "type": "string"
          },
          "executive_summary": {
            "type": "string"
          },
          "strategic_recommendation": {
            "type": "string"
          }
        }
      },
      "CandidateCoachingSession": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "candidate_id": {
            "type": "integer"
          },
          "session_date": {
            "type": "string",
            "format": "date"
          },
          "mentor_name": {
            "type": "string"
          },
          "discipline": {
            "type": "string"
          },
          "drill_scenario": {
            "type": "string"
          },
          "performance_rating": {
            "type": "string"
          },
          "score": {
            "type": "number"
          },
          "mentor_critique": {
            "type": "string"
          },
          "homework_action_items": {
            "type": "string"
          },
          "session_recording_url": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "CandidateCampaignTeamMember": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "candidate_id": {
            "type": "integer"
          },
          "role_title": {
            "type": "string"
          },
          "personnel_name": {
            "type": "string"
          },
          "prior_campaign_credentials": {
            "type": "string"
          },
          "vetting_clearance_status": {
            "type": "string"
          },
          "start_date": {
            "type": "string",
            "format": "date",
            "nullable": true
          },
          "monthly_retainer_usd": {
            "type": "number"
          },
          "notes": {
            "type": "string"
          }
        }
      },
      "RacePrecinctTarget": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "race_code": {
            "type": "string"
          },
          "county_name": {
            "type": "string"
          },
          "priority_tier": {
            "type": "string"
          },
          "registered_primary_voters": {
            "type": "integer"
          },
          "super_voters_universe": {
            "type": "integer"
          },
          "target_vote_share_pct": {
            "type": "number"
          },
          "target_door_knocks": {
            "type": "integer"
          },
          "absentee_chase_universe": {
            "type": "integer"
          },
          "lead_precinct_captain": {
            "type": "string"
          }
        }
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    },
    {
      "apiKeyAuth": []
    }
  ],
  "paths": {
    "/api/v1/health": {
      "get": {
        "tags": [
          "System"
        ],
        "summary": "Health check and database connection status",
        "security": [],
        "responses": {
          "200": {
            "description": "System operational",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "healthy"
                    },
                    "database": {
                      "type": "string",
                      "example": "online"
                    },
                    "version": {
                      "type": "string",
                      "example": "1.0.0"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/openapi.json": {
      "get": {
        "tags": [
          "System"
        ],
        "summary": "Raw OpenAPI 3.0.3 specification in JSON format",
        "security": [],
        "responses": {
          "200": {
            "description": "OpenAPI JSON document"
          }
        }
      }
    },
    "/docs": {
      "get": {
        "tags": [
          "System"
        ],
        "summary": "Interactive Swagger UI documentation page",
        "security": [],
        "responses": {
          "200": {
            "description": "Interactive HTML documentation"
          }
        }
      }
    },
    "/api/v1/auth/login": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Exchange an API key for an HMAC session token",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LoginRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Authenticated session info",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LoginResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      }
    },
    "/api/v1/auth/me": {
      "get": {
        "tags": [
          "Authentication"
        ],
        "summary": "Inspect current authenticated identity and RBAC role",
        "responses": {
          "200": {
            "description": "Current user context",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserContext"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      }
    },
    "/api/v1/telemetry": {
      "get": {
        "tags": [
          "System"
        ],
        "summary": "Mission critical KPIs and aggregate pipeline metrics",
        "responses": {
          "200": {
            "description": "Telemetry summary",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TelemetrySummary"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/candidates": {
      "get": {
        "tags": [
          "Candidates"
        ],
        "summary": "List candidates with filtering and pagination",
        "parameters": [
          {
            "name": "chamber",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Chamber filter (e.g. HOUSE)"
          },
          {
            "name": "state",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "State name or 2 letter abbreviation"
          },
          {
            "name": "sector",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Candidate sector"
          },
          {
            "name": "tier",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Readiness tier (e.g. Tier 1)"
          },
          {
            "name": "search",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Full text search keyword"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          },
          {
            "name": "sort_by",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "national_rank"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated candidate list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total": {
                      "type": "integer"
                    },
                    "limit": {
                      "type": "integer"
                    },
                    "offset": {
                      "type": "integer"
                    },
                    "candidates": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CandidateSummary"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/candidates/{id}": {
      "get": {
        "tags": [
          "Candidates"
        ],
        "summary": "Get candidate complete dossier by identifier",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Candidate full profile",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CandidateDetail"
                }
              }
            }
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      },
      "patch": {
        "tags": [
          "Candidates"
        ],
        "summary": "Update editable candidate attributes (ADMIN only)",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CandidateUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated candidate record"
          },
          "403": {
            "description": "Forbidden: requires ADMIN role"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/resume": {
      "get": {
        "tags": [
          "Candidates"
        ],
        "summary": "Retrieve candidate verified resume and employment timeline",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Candidate resume timeline"
          },
          "404": {
            "description": "Resume not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/blueprint": {
      "get": {
        "tags": [
          "Candidates"
        ],
        "summary": "Retrieve candidate First 90 Days tactical launch blueprint and FEC deadlines",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Candidate launch blueprint"
          },
          "404": {
            "description": "Launch blueprint not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/positions": {
      "get": {
        "tags": [
          "Candidates"
        ],
        "summary": "Retrieve verified career history, employer relationships, and references for a candidate",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Candidate verified career positions list"
          }
        }
      },
      "post": {
        "tags": [
          "Candidates"
        ],
        "summary": "Add verified career position for a candidate (ADMIN or STAFF)",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CareerPositionCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created career position"
          },
          "403": {
            "description": "Forbidden: requires ADMIN or STAFF role"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/osint": {
      "get": {
        "tags": [
          "Candidates",
          "Vetting & OSINT"
        ],
        "summary": "Retrieve complete 4-round deep background search, dark web exposure, and forensic audit",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Candidate deep OSINT intelligence profile"
          },
          "404": {
            "description": "Candidate deep OSINT profile not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/osint-dorks": {
      "get": {
        "tags": [
          "Candidates",
          "Vetting & OSINT"
        ],
        "summary": "Synthesize customized candidate OSINT research dorks across 6 forensic investigation dimensions",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Categorized OSINT search queries and direct investigation links"
          },
          "400": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/vetting/exclusions": {
      "get": {
        "tags": [
          "Vetting & OSINT"
        ],
        "summary": "List disqualified candidate prospects with forensic receipts and exclusion categories",
        "parameters": [
          {
            "name": "district",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated exclusion ledger"
          }
        }
      }
    },
    "/api/v1/districts": {
      "get": {
        "tags": [
          "Districts"
        ],
        "summary": "List congressional districts with PVI and media budgets",
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "District list"
          }
        }
      }
    },
    "/api/v1/districts/{code}": {
      "get": {
        "tags": [
          "Districts"
        ],
        "summary": "Get district details with candidate list and incumbent",
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "District detail and associated candidates"
          },
          "404": {
            "description": "District not found"
          }
        }
      }
    },
    "/api/v1/senate": {
      "get": {
        "tags": [
          "Senate Races"
        ],
        "summary": "List 2028 Senate races and gerontocracy targets",
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "open_only",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Senate races list"
          }
        }
      }
    },
    "/api/v1/senate/{state}": {
      "get": {
        "tags": [
          "Senate Races"
        ],
        "summary": "Get 2028 Senate races for a specific state",
        "parameters": [
          {
            "name": "state",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "State Senate race records"
          }
        }
      }
    },
    "/api/v1/governors": {
      "get": {
        "tags": [
          "Governor Races"
        ],
        "summary": "List 2028 Gubernatorial races and open seat transitions",
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "open_only",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Governor races list"
          }
        }
      }
    },
    "/api/v1/governors/{state}": {
      "get": {
        "tags": [
          "Governor Races"
        ],
        "summary": "Get 2028 Governor race for a specific state",
        "parameters": [
          {
            "name": "state",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "State Governor race records"
          }
        }
      }
    },
    "/api/v1/anticipated": {
      "get": {
        "tags": [
          "Anticipated Seats"
        ],
        "summary": "List empirical vacancy signals and retirement criteria",
        "parameters": [
          {
            "name": "chamber",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "state",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "criterion",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Anticipated seat criteria list"
          }
        }
      }
    },
    "/api/v1/outreach": {
      "get": {
        "tags": [
          "Outreach Pipeline"
        ],
        "summary": "List candidate recruitment pipeline touchpoints and statuses",
        "parameters": [
          {
            "name": "tier",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Pipeline outreach records"
          }
        }
      }
    },
    "/api/v1/outreach/{id}": {
      "patch": {
        "tags": [
          "Outreach Pipeline"
        ],
        "summary": "Update outreach notes, tier, and status (ADMIN or STAFF)",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OutreachUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated outreach pipeline record"
          },
          "403": {
            "description": "Forbidden: requires ADMIN or STAFF role"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/network": {
      "get": {
        "tags": [
          "Network Graph"
        ],
        "summary": "Retrieve ecosystem relationship graph nodes and edges",
        "parameters": [
          {
            "name": "limit_nodes",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 100
            }
          },
          {
            "name": "min_weight",
            "in": "query",
            "schema": {
              "type": "number",
              "default": 1.0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Graph nodes and edges"
          }
        }
      }
    },
    "/api/v1/oppo": {
      "get": {
        "tags": [
          "Opposition Research"
        ],
        "summary": "List incumbent vulnerability overviews, PAC dependency, and contrast ratings",
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated incumbent opposition dossiers"
          }
        }
      }
    },
    "/api/v1/oppo/{target_code}": {
      "get": {
        "tags": [
          "Opposition Research"
        ],
        "summary": "Retrieve full forensic opposition dossier, scorecards, attack vectors, and debate script",
        "parameters": [
          {
            "name": "target_code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "District code (e.g. OK-04) or incumbent code"
          }
        ],
        "responses": {
          "200": {
            "description": "Full opposition dossier and contrast angles"
          },
          "404": {
            "description": "Opposition dossier not found"
          }
        }
      }
    },
    "/api/v1/incumbents/{code}/top-donors": {
      "get": {
        "tags": [
          "Opposition Research"
        ],
        "summary": "Retrieve top PAC and individual mega-donors for an incumbent",
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Top donor records for incumbent",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IncumbentTopDonorsResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/organizations": {
      "get": {
        "tags": [
          "Organizations"
        ],
        "summary": "List coalition partner validator organizations across Five Pillars with leadership contacts",
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "pillar_number",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "search",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated validator organizations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total": {
                      "type": "integer"
                    },
                    "organizations": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/OrganizationSummary"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/organizations/{code}": {
      "get": {
        "tags": [
          "Organizations"
        ],
        "summary": "Get full organizational profile, verified leadership, direct phone, and corporate intelligence",
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Organization profile"
          },
          "404": {
            "description": "Organization not found"
          }
        }
      }
    },
    "/api/v1/organizations/{code}/pac": {
      "get": {
        "tags": [
          "Organizations",
          "Opposition Research"
        ],
        "summary": "Retrieve PAC intelligence, cash on hand, receipts, and historical campaign disbursements",
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "PAC financial metrics and disbursements",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrganizationPacResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/elections/history": {
      "get": {
        "tags": [
          "Elections & Voting"
        ],
        "summary": "Query historical election contests across House, Senate, and Governor races",
        "parameters": [
          {
            "name": "office",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "state",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "district",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "year",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Election contests list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total": {
                      "type": "integer"
                    },
                    "contests": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ElectionContest"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/elections/districts/{code}": {
      "get": {
        "tags": [
          "Elections & Voting"
        ],
        "summary": "Retrieve comprehensive election contest results and demographic voting history for a district",
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "District voting history and historical contests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DistrictVotingHistory"
                }
              }
            }
          },
          "404": {
            "description": "District election history not found"
          }
        }
      }
    },
    "/api/v1/prospecting": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle",
          "Candidates"
        ],
        "summary": "Retrieve unified multi-chamber prospecting command roster with win numbers, primary budgets, milestone progress, and simulated vote share",
        "parameters": [
          {
            "name": "chamber",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by chamber (HOUSE, SENATE, GOVERNOR)"
          },
          {
            "name": "state",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by state code or postal abbreviation"
          },
          {
            "name": "sector",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by background sector"
          },
          {
            "name": "tier",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by readiness tier"
          },
          {
            "name": "outreach_status",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by outreach contact status"
          },
          {
            "name": "search",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Free text query across name, district, role"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          },
          {
            "name": "sort_by",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "seed_capital_feasibility_score"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated prospecting roster response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProspectingCommandRosterResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/candidates/{id}/milestones": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle",
          "Candidates"
        ],
        "summary": "Retrieve chronological campaign lifecycle milestones for a candidate",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Candidate code or integer ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Candidate milestones array",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "candidate_id": {
                      "type": "string"
                    },
                    "total": {
                      "type": "integer"
                    },
                    "milestones": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CandidateMilestone"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Create custom lifecycle milestone for candidate (requires STAFF or ADMIN role)",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "milestone_code",
                  "milestone_title"
                ],
                "properties": {
                  "milestone_code": {
                    "type": "string"
                  },
                  "milestone_title": {
                    "type": "string"
                  },
                  "milestone_stage": {
                    "type": "string"
                  },
                  "target_date": {
                    "type": "string",
                    "format": "date"
                  },
                  "completion_date": {
                    "type": "string",
                    "format": "date"
                  },
                  "status": {
                    "type": "string"
                  },
                  "verification_evidence": {
                    "type": "string"
                  },
                  "assigned_director": {
                    "type": "string"
                  },
                  "sort_order": {
                    "type": "integer"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Milestone successfully created"
          },
          "403": {
            "description": "Forbidden: Requires STAFF role"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/milestones/{id}": {
      "patch": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Update milestone status, completion date, or verification evidence (requires STAFF role)",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string"
                  },
                  "completion_date": {
                    "type": "string",
                    "format": "date"
                  },
                  "verification_evidence": {
                    "type": "string"
                  },
                  "target_date": {
                    "type": "string",
                    "format": "date"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Milestone updated successfully"
          },
          "403": {
            "description": "Forbidden: Requires STAFF role"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/outreach-activities": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle",
          "Outreach Pipeline"
        ],
        "summary": "Retrieve granular outreach touchpoints and follow-up activities for candidate",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Candidate outreach touchpoints history",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "candidate_id": {
                      "type": "string"
                    },
                    "total": {
                      "type": "integer"
                    },
                    "activities": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CandidateOutreachActivity"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Candidate Prospecting & Lifecycle",
          "Outreach Pipeline"
        ],
        "summary": "Log a new recruitment outreach activity for candidate (requires STAFF role)",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "activity_type",
                  "disposition"
                ],
                "properties": {
                  "activity_type": {
                    "type": "string"
                  },
                  "contact_person": {
                    "type": "string"
                  },
                  "staff_member": {
                    "type": "string"
                  },
                  "activity_date": {
                    "type": "string",
                    "format": "date"
                  },
                  "disposition": {
                    "type": "string"
                  },
                  "executive_summary": {
                    "type": "string"
                  },
                  "action_items": {
                    "type": "string"
                  },
                  "next_followup_date": {
                    "type": "string",
                    "format": "date"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Outreach activity logged successfully"
          },
          "403": {
            "description": "Forbidden: Requires STAFF role"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/races/{code}/electorate": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle",
          "Districts"
        ],
        "summary": "Retrieve predictive race electorate model with primary/general turnout, win numbers, and doors target",
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Race code e.g. OK-04, SEN-IA-2028, GOV-OH-2028"
          }
        ],
        "responses": {
          "200": {
            "description": "Predictive race electorate model",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RaceElectorateModel"
                }
              }
            }
          },
          "404": {
            "description": "Race electorate model not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/matchup-simulation": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle",
          "Opposition Research"
        ],
        "summary": "Retrieve head-to-head candidate matchup simulation across key voter blocs and turnout sensitivity",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Candidate matchup simulation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CandidateMatchupSimulation"
                }
              }
            }
          },
          "404": {
            "description": "Matchup simulation not found for candidate"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/viability": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle",
          "Candidates"
        ],
        "summary": "Evaluate multi-dimensional Ascent Viability Index (0 to 100), deployment readiness tier, breakthrough wedges, and critical gaps",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Candidate viability synthesis",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CandidateViabilityResponse"
                }
              }
            }
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/development": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle",
          "Candidates"
        ],
        "summary": "Retrieve candidate coaching evaluation scores across 6 statesmanship disciplines and assigned mentor",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Candidate coaching evaluation profile",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CandidateDevelopmentProfile"
                }
              }
            }
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      },
      "post": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Update candidate statesmanship coaching scores, assigned mentor, or priority (requires STAFF role)",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "media_readiness_score": {
                    "type": "number"
                  },
                  "stump_speech_mastery_score": {
                    "type": "number"
                  },
                  "grassroots_field_appeal_score": {
                    "type": "number"
                  },
                  "fundraising_confidence_score": {
                    "type": "number"
                  },
                  "policy_mastery_score": {
                    "type": "number"
                  },
                  "crisis_management_score": {
                    "type": "number"
                  },
                  "assigned_mentor": {
                    "type": "string"
                  },
                  "primary_development_priority": {
                    "type": "string"
                  },
                  "media_simulation_notes": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Coaching profile updated successfully"
          },
          "403": {
            "description": "Forbidden: Requires STAFF role"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/training-modules": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle",
          "Candidates"
        ],
        "summary": "Retrieve Statesmanship Academy training curriculum progression for candidate",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Training modules array",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "candidate_id": {
                      "type": "string"
                    },
                    "total": {
                      "type": "integer"
                    },
                    "modules": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CandidateTrainingModule"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/training-modules/{id}": {
      "patch": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Update training module status, score, or certification (requires STAFF role)",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string"
                  },
                  "score": {
                    "type": "number"
                  },
                  "certified_by": {
                    "type": "string"
                  },
                  "completion_date": {
                    "type": "string",
                    "format": "date"
                  },
                  "notes": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Training module updated successfully"
          },
          "403": {
            "description": "Forbidden: Requires STAFF role"
          }
        }
      }
    },
    "/api/v1/races/{code}/battleplan": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle",
          "Districts"
        ],
        "summary": "Retrieve tactical 5-phase victory battleplan for targeted House, Senate, or Governor seat",
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Race victory battleplan",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RaceVictoryBattleplan"
                }
              }
            }
          },
          "404": {
            "description": "Race battleplan not found"
          }
        }
      },
      "post": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Update tactical 5-phase victory battleplan for race (requires STAFF role)",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "battleground_tier": {
                    "type": "string"
                  },
                  "phase_1_recon_and_scouting": {
                    "type": "string"
                  },
                  "phase_2_exploratory_and_seed_capital": {
                    "type": "string"
                  },
                  "phase_3_campaign_launch_and_media": {
                    "type": "string"
                  },
                  "phase_4_ground_operations_and_absentee": {
                    "type": "string"
                  },
                  "phase_5_primary_surge_and_get_out_the_vote": {
                    "type": "string"
                  },
                  "total_campaign_budget_usd": {
                    "type": "number"
                  },
                  "key_victory_milestone_metric": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Race battleplan updated successfully"
          },
          "403": {
            "description": "Forbidden: Requires STAFF role"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/assessment": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get comprehensive 6-factor evaluation assessment for candidate",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Candidate evaluation assessment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CandidateEvaluationAssessment"
                }
              }
            }
          },
          "404": {
            "description": "Assessment not found"
          }
        }
      },
      "post": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Create or update candidate evaluation assessment (requires STAFF role)",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "evaluator_name": {
                    "type": "string"
                  },
                  "electoral_viability_score": {
                    "type": "number"
                  },
                  "fundraising_velocity_score": {
                    "type": "number"
                  },
                  "rhetorical_readiness_score": {
                    "type": "number"
                  },
                  "constitutional_orthodoxy_score": {
                    "type": "number"
                  },
                  "adversarial_resilience_score": {
                    "type": "number"
                  },
                  "infrastructure_capacity_score": {
                    "type": "number"
                  },
                  "overall_assessment_tier": {
                    "type": "string"
                  },
                  "executive_summary": {
                    "type": "string"
                  },
                  "strategic_recommendation": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Assessment updated successfully"
          },
          "403": {
            "description": "Forbidden: Requires STAFF role"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/coaching-sessions": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get candidate coaching sessions and performance drill ratings",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Candidate coaching session history"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      },
      "post": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Record new candidate coaching session and drill score (requires STAFF role)",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "mentor_name",
                  "discipline",
                  "drill_scenario",
                  "score"
                ],
                "properties": {
                  "session_date": {
                    "type": "string",
                    "format": "date"
                  },
                  "mentor_name": {
                    "type": "string"
                  },
                  "discipline": {
                    "type": "string"
                  },
                  "drill_scenario": {
                    "type": "string"
                  },
                  "performance_rating": {
                    "type": "string"
                  },
                  "score": {
                    "type": "number"
                  },
                  "mentor_critique": {
                    "type": "string"
                  },
                  "homework_action_items": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Coaching session recorded successfully"
          },
          "403": {
            "description": "Forbidden: Requires STAFF role"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/campaign-team": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get key campaign team personnel roster and vendor appointments",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Candidate campaign team personnel"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      },
      "post": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Appoint or log campaign staff member or vendor (requires STAFF role)",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "role_title",
                  "personnel_name"
                ],
                "properties": {
                  "role_title": {
                    "type": "string"
                  },
                  "personnel_name": {
                    "type": "string"
                  },
                  "prior_campaign_credentials": {
                    "type": "string"
                  },
                  "vetting_clearance_status": {
                    "type": "string"
                  },
                  "monthly_retainer_usd": {
                    "type": "number"
                  },
                  "notes": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Campaign team member appointed successfully"
          },
          "403": {
            "description": "Forbidden: Requires STAFF role"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/evaluation-dossier": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get candidate evaluation dossier (JSON summary or streaming 2-page PDF)",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "pdf",
                "json"
              ],
              "default": "pdf"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Candidate evaluation dossier PDF or JSON assessment",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CandidateAssessment"
                }
              }
            }
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/war-chest-matrix": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get candidate PAC coalition sizing and incumbent war chest matrix with counter-funding analytics",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Candidate PAC sizing and incumbent war chest counter-funding matrix"
          },
          "404": {
            "description": "Candidate or race not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/debate-sparring": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get interactive debate sparring and contrast messaging simulation modules",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Candidate debate sparring modules and coaching doctrine"
          },
          "404": {
            "description": "Candidate or race not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/debate-sparring/evaluate": {
      "post": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Evaluate candidate simulated debate response against 4-dimensional contrast rubric",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "response_text"
                ],
                "properties": {
                  "topic_id": {
                    "type": "string",
                    "example": "fiscal_omnibus"
                  },
                  "response_text": {
                    "type": "string",
                    "example": "Our military families are punished by inflation..."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Debate response evaluation scores, letter grade, and tactical coaching feedback"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/crisis-playbook": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get candidate rapid response media training and crisis defense playbook",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Candidate crisis rapid response scenarios, talking points, and video scripts"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/crisis-playbook/evaluate": {
      "post": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Evaluate emergency candidate rapid response statement against adversarial media rubrics",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "statement_text"
                ],
                "properties": {
                  "scenario_id": {
                    "type": "string",
                    "example": "pac_attack_ad"
                  },
                  "statement_text": {
                    "type": "string",
                    "example": "When Washington lobbyists spend half a million dollars lying..."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Crisis response evaluation score, letter grade, and tactical coaching critique"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/investor-prospectus": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get major donor investment prospectus and Return on Political Capital (ROPC) analytics",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Major donor prospectus with ROPC metrics and 90-day deployment schedule"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/field-deployment-plan": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get precinct ground game, turf packet allocations, and field organizer deployment plan",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Candidate field deployment plan with turf packet counts and 4-phase timeline"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/field-deployment-plan/simulate-canvass": {
      "post": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Simulate ground game volunteer and paid canvass production against primary win target",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "volunteer_canvassers": {
                    "type": "integer",
                    "example": 30
                  },
                  "paid_canvassers": {
                    "type": "integer",
                    "example": 12
                  },
                  "shifts_per_week": {
                    "type": "number",
                    "example": 2.5
                  },
                  "weeks_active": {
                    "type": "integer",
                    "example": 14
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Canvass production metrics, doors knocked, supporters identified, and win coverage"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/digital-ad-matrix": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get micro-targeted digital ad buy allocations and messaging resonance matrix",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Micro-targeted digital ad spend across Meta, X, CTV/OTT, and SMS with creative resonance themes"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/digital-ad-matrix/simulate-flight": {
      "post": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Simulate custom digital ad flight delivery across media channels and estimated voter impressions",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "total_budget_usd": {
                    "type": "number",
                    "example": 35000.0
                  },
                  "focus_channel": {
                    "type": "string",
                    "example": "ctv_ott_youtube"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Digital ad flight delivery results, channel breakdown, impressions, video views, and net reach"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/ballot-chase": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get voter turnout propensity clustering, early ballot chase timeline, and signature cure protocol",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Turnout propensity clusters, 4-wave chase timeline, and 24-hour signature cure protocol"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/ballot-chase/simulate-chase": {
      "post": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Simulate candidate early ballot chase campaign outcomes, ballots banked, and win target coverage",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "chase_budget_usd": {
                    "type": "number",
                    "example": 75000.0
                  },
                  "volunteer_chase_ratio": {
                    "type": "number",
                    "example": 0.65
                  },
                  "digital_sms_share": {
                    "type": "number",
                    "example": 0.3
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ballot chase simulation outcomes, banked early votes, cost per ballot, and efficiency grade"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/faith-coalition": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get faith community grassroots coalition matrix, civic Sundays timeline, and 501c3 guardrails",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Faith coalition sectors, 4-Sunday mobilization timeline, 501c3 legal standards, and pastoral curriculum"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/faith-coalition/simulate-mobilization": {
      "post": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Simulate grassroots faith community mobilization outcomes, values voters mobilized, and win target coverage",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "participating_congregations_count": {
                    "type": "integer",
                    "example": 45
                  },
                  "pastoral_briefing_attendance": {
                    "type": "integer",
                    "example": 60
                  },
                  "voter_guide_print_budget_usd": {
                    "type": "number",
                    "example": 18000.0
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Faith mobilization simulation results, mobilized values voters, early church ballots, and efficiency grade"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/counter-punch-matrix": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get opposition attack vulnerability index, debate counter punch matrix, and sparring exchanges",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Vulnerability attack vectors, debate sparring exchanges, and rapid response arsenal"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/counter-punch-matrix/simulate-exchange": {
      "post": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Simulate opposition attack rebuttal, narrative mitigation percentage, net favorability impact, and voter retention",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "attack_intensity_score": {
                    "type": "number",
                    "example": 7.5
                  },
                  "rapid_response_speed_hours": {
                    "type": "number",
                    "example": 1.5
                  },
                  "ad_spend_counter_usd": {
                    "type": "number",
                    "example": 25000.0
                  },
                  "debate_prep_sparring_hours": {
                    "type": "integer",
                    "example": 40
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Counter punch simulation results, narrative mitigation percentage, and strategic recommendations"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/donor-pipeline": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get multi-chamber recurring donor pipeline, lifetime value analytics, and club tiers",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Recurring donor pipeline summary, donor clubs, acquisition channels, and 6-month growth projection"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/donor-pipeline/simulate-velocity": {
      "post": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Simulate dynamic recurring donor acquisition, revenue velocity, and net war chest runway",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "monthly_acquisition_ad_spend_usd": {
                    "type": "number",
                    "example": 15000.0
                  },
                  "target_monthly_churn_pct": {
                    "type": "number",
                    "example": 3.5
                  },
                  "average_recurring_gift_usd": {
                    "type": "number",
                    "example": 32.0
                  },
                  "simulation_horizon_months": {
                    "type": "integer",
                    "example": 6
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Donor pipeline simulation trajectory, war chest contributions, and strategic takeaways"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/air-cover-pacing": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get media market DMA sizing, GRP saturation curves, and hard money vs IE pacing",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Media flight summary, DMA analytics, channel mix, flight phases, and firewall protocols"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/air-cover-pacing/simulate-flight": {
      "post": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Simulate dynamic media air cover buy pacing, delivered GRPs, voter reach, and flight efficiency grade",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "total_media_budget_usd": {
                    "type": "number",
                    "example": 450000.0
                  },
                  "hard_money_ratio_pct": {
                    "type": "number",
                    "example": 45.0
                  },
                  "planned_weeks": {
                    "type": "integer",
                    "example": 12
                  },
                  "target_grps_per_week": {
                    "type": "number",
                    "example": 200.0
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Air cover flight simulation outcomes, weekly trajectory, and strategic takeaways"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/finance-committee": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get candidate finance committee leadership tiers, bundler network, and marquee events",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Finance committee leadership tiers, bundler network analytics, marquee event calendar, and compliance protocols"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/finance-committee/simulate-velocity": {
      "post": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Simulate monthly bundler collection velocity, VIP reception revenue, and primary budget coverage",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "active_bundlers_count": {
                    "type": "integer",
                    "example": 38
                  },
                  "avg_bundle_commitment_usd": {
                    "type": "number",
                    "example": 25000.0
                  },
                  "event_frequency_monthly": {
                    "type": "integer",
                    "example": 2
                  },
                  "bundler_fulfillment_rate_pct": {
                    "type": "number",
                    "example": 75.0
                  },
                  "simulation_horizon_months": {
                    "type": "integer",
                    "example": 6
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bundler network velocity simulation outcomes, monthly collection trajectory, and strategic takeaways"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/ballot-access": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get candidate statutory ballot qualifying rules, petition signature verification, and forensic legal defense protocols",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Statutory ballot requirements, circulator squad performance, forensic validation checklist, and challenge survival probability"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/ballot-access/simulate-signatures": {
      "post": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Simulate petition signature collection velocity, invalidation scrubbing, and legal challenge survival probability",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "days_remaining": {
                    "type": "integer",
                    "example": 30
                  },
                  "active_circulators": {
                    "type": "integer",
                    "example": 35
                  },
                  "signatures_per_circulator_day": {
                    "type": "number",
                    "example": 12.0
                  },
                  "projected_invalidation_rate_pct": {
                    "type": "number",
                    "example": 16.0
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ballot access simulation results, net valid signatures, statutory buffer percentage, and legal security rating"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/election-day-war-room": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get candidate Election Day incident response command, poll watcher network, and turnout pacing benchmarks",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Real-time incident response board, credentialed observer deployment, legal emergency petitions, and turnout pacing curve"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/election-day-war-room/simulate-pacing": {
      "post": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Simulate Election Day hourly turnout pacing, voter volume curves, and victory margin projections",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "current_hour_est": {
                    "type": "integer",
                    "example": 15
                  },
                  "reported_precincts_pct": {
                    "type": "number",
                    "example": 62.5
                  },
                  "current_ballots_cast": {
                    "type": "integer",
                    "example": 19500
                  },
                  "turnout_deviation_pct": {
                    "type": "number",
                    "example": 4.2
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Simulated turnout pacing results, net win margin projections, security rating, and hourly trajectory"
          },
          "400": {
            "description": "Invalid simulation parameters"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/transition-protocol": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get candidate transition and inauguration strategic protocol, executive staffing roadmap, committee preferences, and 100-day legislative slate",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Executive transition staffing slate, priority committee requests, 100-day legislative agenda, and caucus governance strategy"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/transition-protocol/simulate-velocity": {
      "post": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Simulate transition recruitment velocity, 100-day legislative drafting readiness, and inaugural execution score",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "transition_budget_usd": {
                    "type": "number",
                    "example": 145000.0
                  },
                  "target_staffing_headcount": {
                    "type": "integer",
                    "example": 14
                  },
                  "priority_bills_count": {
                    "type": "integer",
                    "example": 3
                  },
                  "weeks_until_inauguration": {
                    "type": "integer",
                    "example": 8
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Simulated transition velocity results, cost per hire, staffing readiness score, bill drafting score, and overall readiness rating"
          },
          "400": {
            "description": "Invalid simulation parameters"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/delegate-operations": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get candidate congressional district convention, state convention, and primary caucus delegate operations, whip structure, and balloting allocation",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Convention delegate summary, threshold requirements, floor whip organization, balloting scenarios, and credential defense checklist"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/delegate-operations/simulate": {
      "post": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Simulate convention floor balloting velocity, delegate whip count retention, and multi-round runoff consolidation",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "target_first_ballot_threshold_pct": {
                    "type": "number",
                    "example": 50.1
                  },
                  "whip_team_headcount": {
                    "type": "integer",
                    "example": 12
                  },
                  "committed_delegate_retention_pct": {
                    "type": "number",
                    "example": 94.0
                  },
                  "undecided_conversion_pct": {
                    "type": "number",
                    "example": 65.0
                  },
                  "convention_floor_rounds": {
                    "type": "integer",
                    "example": 3
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Simulated convention floor voting results, round by round projections, victory status, and overall readiness rating"
          },
          "400": {
            "description": "Invalid simulation parameters"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/caucus-accords": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get candidate intra party faction reconciliation, rival candidate unification accords, coalition whip metrics, and legislative platform compacts",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Coalition metrics, faction alignments, primary rival reconciliation, legislative accord terms, and whip action items"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/caucus-accords/simulate": {
      "post": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Simulate post primary intra party faction reconciliation velocity, rival voter retention, and general election coalition expansion",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "target_faction_cohesion_pct": {
                    "type": "number",
                    "example": 85.0
                  },
                  "rival_endorsement_retention_pct": {
                    "type": "number",
                    "example": 78.0
                  },
                  "platform_concession_drag_pct": {
                    "type": "number",
                    "example": 4.5
                  },
                  "grassroots_activation_multiplier": {
                    "type": "number",
                    "example": 1.25
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Simulated coalition turnout, retained rival votes, projected vote share, victory margin, and coalition unity rating"
          },
          "400": {
            "description": "Invalid simulation parameters"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/shadow-cabinet": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get candidate transition cabinet oversight teams, regulatory rollback targets, agency reform mandates, and appointment clearance pipeline",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Agency transition portfolios, regulatory repeal targets, key personnel clearances, and transition readiness metrics"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/shadow-cabinet/simulate": {
      "post": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Simulate agency transition velocity, executive order rescission impact, appointment confirmation pacing, and administrative reform leverage index",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "transition_staffing_completion_pct": {
                    "type": "number",
                    "example": 85.0
                  },
                  "regulatory_rescission_aggression_pct": {
                    "type": "number",
                    "example": 90.0
                  },
                  "confirmation_speed_weeks": {
                    "type": "number",
                    "example": 6.0
                  },
                  "policy_durability_multiplier": {
                    "type": "number",
                    "example": 1.2
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Simulated compliance savings, confirmed appointees count, reform leverage index, policy durability score, and execution rating"
          },
          "400": {
            "description": "Invalid simulation parameters"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/voter-registration": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get candidate voter registration drive quotas, civic naturalization outreach, demographic expansion universes, and faith network targets",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Candidate ID or District Code"
          }
        ],
        "responses": {
          "200": {
            "description": "Candidate voter registration drive KPIs, demographic expansion universes, faith network targets, and precinct quotas"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/voter-registration/simulate": {
      "post": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Simulate voter registration field velocity, new voter conversion volume, general election retention turnout, and net vote margin addition",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Candidate ID or District Code"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "canvasser_fte": {
                    "type": "number",
                    "example": 15.0
                  },
                  "weekly_contacts_per_fte": {
                    "type": "number",
                    "example": 320.0
                  },
                  "registration_conversion_rate_pct": {
                    "type": "number",
                    "example": 18.5
                  },
                  "weeks_remaining": {
                    "type": "number",
                    "example": 14.0
                  },
                  "retention_turnout_rate_pct": {
                    "type": "number",
                    "example": 72.0
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Simulated total contacts, newly registered voters, general election turnout, net vote margin, unit cost, and velocity rating"
          },
          "400": {
            "description": "Invalid simulation parameters"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/judicial-nominations": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get candidate judicial appointment vetting slate, constitutional jurisprudence alignment, and confirmation pacing architecture",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Candidate ID or District Code"
          }
        ],
        "responses": {
          "200": {
            "description": "Judicial readiness metrics, priority court slates, constitutional jurisprudence doctrines, and confirmation sparring scenarios"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/judicial-nominations/simulate": {
      "post": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Simulate judicial confirmation velocity, lifetime bench appointment yields, constitutional durability index, and Senate confirmation throughput",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Candidate ID or District Code"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "vetted_nominees_count": {
                    "type": "integer",
                    "example": 15
                  },
                  "confirmation_pacing_weeks": {
                    "type": "number",
                    "example": 6.0
                  },
                  "originalist_fidelity_score": {
                    "type": "number",
                    "example": 95.0
                  },
                  "filibuster_cloture_buffer": {
                    "type": "integer",
                    "example": 3
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Simulated confirmed lifetime judges, effective confirmation rate, constitutional durability index, throughput, and judicial rating"
          },
          "400": {
            "description": "Invalid simulation parameters"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/trade-sovereignty": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get candidate foreign policy doctrine, strategic trade decoupling, supply chain sovereignty, and adversarial land ban architecture",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Candidate ID or District Code"
          }
        ],
        "responses": {
          "200": {
            "description": "Strategic sovereignty metrics, doctrine pillars, critical supply chain portfolios, asset dockets, and trade sparring scenarios"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/defense-surge": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get candidate defense industrial base surge, naval shipyard revival, border sovereignty interdiction, and autonomous asymmetric defense architecture",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Candidate ID or District Code"
          }
        ],
        "responses": {
          "200": {
            "description": "Defense surge metrics, doctrine pillars, infrastructure portfolios, border dockets, and defense sparring scenarios"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/ai-sovereignty": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get candidate artificial intelligence sovereignty, semiconductor foundry autonomy, quantum cryptography defense, and algorithmic neutrality architecture",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Candidate ID or District Code"
          }
        ],
        "responses": {
          "200": {
            "description": "AI sovereignty metrics, doctrine pillars, technology infrastructure portfolios, algorithmic bias dockets, and contrast sparring scenarios"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/nuclear-energy": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get candidate advanced nuclear energy independence, SMR deployment readiness, domestic uranium enrichment, and critical mineral grid sovereignty architecture",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Candidate ID or District Code"
          }
        ],
        "responses": {
          "200": {
            "description": "Nuclear energy metrics, doctrine pillars, energy infrastructure portfolios, grid sovereignty dockets, and contrast sparring scenarios"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/space-sovereignty": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get candidate space exploration sovereignty, commercial launch autonomy, cislunar defense superiority, and orbital manufacturing command architecture",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Candidate ID or District Code"
          }
        ],
        "responses": {
          "200": {
            "description": "Space sovereignty metrics, doctrine pillars, space infrastructure portfolios, orbital sovereignty dockets, and contrast sparring scenarios"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/trade-sovereignty/simulate": {
      "post": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Simulate domestic manufacturing onshoring yield, critical supply chain independence, trade deficit reduction, and sovereign defense resilience index",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Candidate ID or District Code"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "domestic_capital_investment_millions": {
                    "type": "number",
                    "example": 1250.0
                  },
                  "tariff_enforcement_index": {
                    "type": "number",
                    "example": 90.0
                  },
                  "adversarial_import_reduction_pct": {
                    "type": "number",
                    "example": 75.0
                  },
                  "strategic_reshoring_incentive_years": {
                    "type": "integer",
                    "example": 5
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Simulated domestic onshoring yield, critical supply chain independence, composite sovereignty score, deficit reduction, and strategic rating"
          },
          "400": {
            "description": "Invalid simulation parameters"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/defense-surge/simulate": {
      "post": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Simulate defense manufacturing surge yield, ordnance stockpile expansion, border interdiction containment, and composite defense sovereignty index",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Candidate ID or District Code"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "defense_capital_investment_millions": {
                    "type": "number",
                    "example": 1500.0
                  },
                  "munitions_surge_index": {
                    "type": "number",
                    "example": 90.0
                  },
                  "border_interdiction_enforcement_pct": {
                    "type": "number",
                    "example": 85.0
                  },
                  "naval_shipyard_modernization_years": {
                    "type": "integer",
                    "example": 5
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Simulated defense manufacturing surge yield, border containment rate, defense sovereignty score, thwarted interdictions, and readiness rating"
          },
          "400": {
            "description": "Invalid simulation parameters"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/ai-sovereignty/simulate": {
      "post": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Simulate semiconductor fabrication output, quantum defense resilience, energy colocation throughput, and composite tech sovereignty index",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Candidate ID or District Code"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "foundry_capital_investment_millions": {
                    "type": "number",
                    "example": 2500.0
                  },
                  "sovereign_compute_expansion_index": {
                    "type": "number",
                    "example": 88.0
                  },
                  "quantum_encryption_adoption_pct": {
                    "type": "number",
                    "example": 75.0
                  },
                  "clean_energy_colocation_gw": {
                    "type": "number",
                    "example": 3.5
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Simulated semiconductor output surge, grid quantum defense resilience, composite tech sovereignty score, repelled cyber intrusions, and rating"
          },
          "400": {
            "description": "Invalid simulation parameters"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/nuclear-energy/simulate": {
      "post": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Simulate SMR modular deployment velocity, domestic uranium enrichment yield, rare earth mineral processing throughput, and composite grid reliability score",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Candidate ID or District Code"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "smr_capex_target_millions": {
                    "type": "number",
                    "example": 1800.0
                  },
                  "regulatory_approval_timeline_months": {
                    "type": "integer",
                    "example": 18
                  },
                  "domestic_enrichment_capacity_pct": {
                    "type": "number",
                    "example": 85.0
                  },
                  "grid_interconnection_pacing_gw": {
                    "type": "number",
                    "example": 4.5
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Nuclear energy and grid resilience simulation results, milestone trajectory, and strategic recommendations"
          },
          "400": {
            "description": "Invalid simulation parameters"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/candidates/{id}/space-sovereignty/simulate": {
      "post": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Simulate commercial launch cadence velocity, payload mass to orbit, launch cost per kilogram reduction, and tactical reconstitution readiness",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Candidate ID or District Code"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "commercial_launch_capex_millions": {
                    "type": "number",
                    "example": 2400.0
                  },
                  "launch_cadence_annual_flights": {
                    "type": "integer",
                    "example": 120
                  },
                  "faa_approval_timeline_days": {
                    "type": "integer",
                    "example": 14
                  },
                  "tactical_responsive_standby_hours": {
                    "type": "number",
                    "example": 24.0
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Space sovereignty and launch cadence simulation results, milestone trajectory, and strategic recommendations"
          },
          "400": {
            "description": "Invalid simulation parameters"
          },
          "404": {
            "description": "Candidate not found"
          }
        }
      }
    },
    "/api/v1/races/{code}/precinct-targets": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get county and precinct turnout targets and super-voter universes for race",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Race precinct and county targets"
          }
        }
      },
      "post": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Upsert race county or precinct turnout target (requires STAFF role)",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "county_name",
                  "registered_primary_voters",
                  "super_voters_universe"
                ],
                "properties": {
                  "county_name": {
                    "type": "string"
                  },
                  "priority_tier": {
                    "type": "string"
                  },
                  "registered_primary_voters": {
                    "type": "integer"
                  },
                  "super_voters_universe": {
                    "type": "integer"
                  },
                  "target_vote_share_pct": {
                    "type": "number"
                  },
                  "target_door_knocks": {
                    "type": "integer"
                  },
                  "absentee_chase_universe": {
                    "type": "integer"
                  },
                  "lead_precinct_captain": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Precinct target upserted successfully"
          },
          "403": {
            "description": "Forbidden: Requires STAFF role"
          }
        }
      }
    },
    "/api/v1/races/{code}/simulate-turnout": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Simulate primary win-number thresholds and field contact requirements",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "scenario",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "LOW_TURNOUT",
                "BASELINE",
                "HIGH_TURNOUT",
                "SURGE"
              ],
              "default": "BASELINE"
            }
          },
          {
            "name": "candidate_share_pct",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "default": 52.5
            }
          },
          {
            "name": "turnout_modifier_pct",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dynamic primary turnout and victory simulation breakdown"
          }
        }
      },
      "post": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Simulate primary win-number thresholds and field contact requirements via JSON payload",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "scenario": {
                    "type": "string",
                    "enum": [
                      "LOW_TURNOUT",
                      "BASELINE",
                      "HIGH_TURNOUT",
                      "SURGE"
                    ]
                  },
                  "candidate_share_pct": {
                    "type": "number"
                  },
                  "turnout_modifier_pct": {
                    "type": "number"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Dynamic primary turnout and victory simulation breakdown"
          }
        }
      }
    },
    "/api/v1/races/{code}/war-chest-matrix": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get race level PAC coalition sizing and incumbent war chest matrix",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Race PAC sizing and incumbent war chest counter-funding matrix"
          },
          "404": {
            "description": "Race or incumbent not found"
          }
        }
      }
    },
    "/api/v1/races/{code}/debate-sparring": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get race level interactive debate sparring and contrast simulation modules",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Race debate sparring modules and coaching doctrine"
          },
          "404": {
            "description": "Race or incumbent not found"
          }
        }
      }
    },
    "/api/v1/races/{code}/crisis-playbook": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get race level media training and crisis rapid response defense playbook",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Race crisis defense playbook scenarios and talking points"
          },
          "404": {
            "description": "Race not found"
          }
        }
      }
    },
    "/api/v1/races/{code}/field-deployment-plan": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get race level precinct ground game, turf packet allocations, and field organizer deployment plan",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Race field deployment plan with turf packet counts and 4-phase timeline"
          },
          "404": {
            "description": "Race not found"
          }
        }
      }
    },
    "/api/v1/races/{code}/digital-ad-matrix": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get race level micro-targeted digital ad buy allocations and messaging resonance matrix",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Race digital ad matrix with channel allocations and creative resonance themes"
          },
          "404": {
            "description": "Race not found"
          }
        }
      }
    },
    "/api/v1/races/{code}/ballot-chase": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get race level voter turnout propensity clustering and early ballot chase operational plan",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Race level turnout propensity clustering and early ballot chase plan"
          },
          "404": {
            "description": "Race not found"
          }
        }
      }
    },
    "/api/v1/races/{code}/faith-coalition": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get race level faith community grassroots coalition matrix and congregational mobilization plan",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Race level faith coalition overview, sectors, and civic Sunday timeline"
          },
          "404": {
            "description": "Race not found"
          }
        }
      }
    },
    "/api/v1/races/{code}/counter-punch-matrix": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get race level opposition attack vulnerability index, counter punch matrix, and sparring exchanges",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Race level vulnerability attack vectors, debate sparring exchanges, and rapid response arsenal"
          },
          "404": {
            "description": "Race not found"
          }
        }
      }
    },
    "/api/v1/races/{code}/donor-pipeline": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get race level recurring donor pipeline, lifetime value analytics, and club tiers",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Race level donor pipeline summary, donor clubs, and acquisition channels"
          },
          "404": {
            "description": "Race not found"
          }
        }
      }
    },
    "/api/v1/races/{code}/air-cover-pacing": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get race level media market air cover and buy pacing analytics",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Race level air cover flight summary, DMA market analytics, and pacing recommendations"
          },
          "404": {
            "description": "Race not found"
          }
        }
      }
    },
    "/api/v1/races/{code}/finance-committee": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get race level high dollar finance committee structure and targets",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Race level finance committee targets, bundler tiers, and marquee events"
          },
          "404": {
            "description": "Race not found"
          }
        }
      }
    },
    "/api/v1/races/{code}/ballot-access": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get race level statutory ballot access status, qualifying requirements, and filing deadlines",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Race level statutory signature requirements, filing fee, deadlines, and legal security ratings"
          },
          "404": {
            "description": "Race not found"
          }
        }
      }
    },
    "/api/v1/races/{code}/election-day-war-room": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get race level Election Day incident response command, poll watcher network, and turnout pacing benchmarks",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Race level real-time incident response board, credentialed observers, legal emergency petitions, and turnout pacing benchmarks"
          },
          "404": {
            "description": "Race not found"
          }
        }
      }
    },
    "/api/v1/races/{code}/transition-protocol": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get race level transition and inauguration strategic protocol, executive staffing roadmap, and 100-day legislative slate",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Race level executive transition staffing slate, priority committee requests, 100-day legislative agenda, and caucus governance strategy"
          },
          "404": {
            "description": "Race not found"
          }
        }
      }
    },
    "/api/v1/races/{code}/delegate-operations": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get race level primary convention delegate operations, whip allocation, and balloting logistics",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Race level convention delegate operations, floor whip allocation, and balloting threshold analysis"
          },
          "404": {
            "description": "Race not found"
          }
        }
      }
    },
    "/api/v1/races/{code}/caucus-accords": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get race level intra party faction reconciliation, rival candidate unification accords, and legislative platform compacts",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Race level coalition metrics, faction alignments, rival reconciliation, and legislative compact terms"
          },
          "404": {
            "description": "Race not found"
          }
        }
      }
    },
    "/api/v1/races/{code}/shadow-cabinet": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get race level transition cabinet and agency shadow review architecture",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Race transition cabinet architecture and regulatory oversight teams"
          },
          "404": {
            "description": "Race not found"
          }
        }
      }
    },
    "/api/v1/races/{code}/voter-registration": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get race level voter registration drive quotas and civic expansion architecture",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Race level voter registration drive quotas and civic expansion architecture"
          },
          "404": {
            "description": "Race not found"
          }
        }
      }
    },
    "/api/v1/races/{code}/judicial-nominations": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get race level judicial appointment vetting slate and constitutional jurisprudence architecture",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Race level judicial appointment vetting slate and constitutional jurisprudence architecture"
          },
          "404": {
            "description": "Race not found"
          }
        }
      }
    },
    "/api/v1/races/{code}/trade-sovereignty": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get race level foreign policy doctrine, strategic trade decoupling, and supply chain sovereignty architecture",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Race level foreign policy doctrine, strategic trade decoupling, and supply chain sovereignty architecture"
          },
          "404": {
            "description": "Race not found"
          }
        }
      }
    },
    "/api/v1/races/{code}/defense-surge": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get race level defense industrial surge, shipyard revival, and border sovereignty architecture",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Race level defense industrial surge, shipyard revival, and border sovereignty architecture"
          },
          "404": {
            "description": "Race not found"
          }
        }
      }
    },
    "/api/v1/races/{code}/ai-sovereignty": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get race level artificial intelligence sovereignty and semiconductor foundry autonomy architecture",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Race level artificial intelligence sovereignty and semiconductor foundry autonomy architecture"
          },
          "404": {
            "description": "Race not found"
          }
        }
      }
    },
    "/api/v1/races/{code}/nuclear-energy": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get race level advanced nuclear energy independence and grid sovereignty architecture",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Race level advanced nuclear energy independence and grid sovereignty architecture"
          },
          "404": {
            "description": "Race not found"
          }
        }
      }
    },
    "/api/v1/races/{code}/space-sovereignty": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Get race level space exploration sovereignty, commercial launch autonomy, and cislunar defense architecture",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Race level space exploration sovereignty, commercial launch autonomy, and cislunar defense architecture"
          },
          "404": {
            "description": "Race not found"
          }
        }
      }
    },
    "/api/v1/briefing-book/generate": {
      "post": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Generate publication-grade battleground briefing book in HTML and PDF formats",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "candidate_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "example": [
                      "ASC-OK04-001",
                      "ASC-KS04-001"
                    ]
                  },
                  "title": {
                    "type": "string",
                    "example": "American Ascent Battleground Briefing Book"
                  },
                  "render_pdf": {
                    "type": "boolean",
                    "default": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Briefing book generation summary and file paths"
          }
        }
      }
    },
    "/api/v1/briefing-book/download": {
      "get": {
        "tags": [
          "Candidate Prospecting & Lifecycle"
        ],
        "summary": "Download latest or generated battleground briefing book (format=pdf or format=html)",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "pdf",
                "html"
              ],
              "default": "pdf"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Briefing book file stream (PDF or HTML)"
          },
          "404": {
            "description": "Briefing book file not found"
          }
        }
      }
    }
  }
}