Scenario Configuration Manager - API Contract

GET /api/v1/scenario-configurations/api/v1/scenario-configurations

List chapter scenario configurations across all chapters

Public

Response Example

{
  "data": [
    {
      "chapter_id": "ch_boston_001",
      "chapter_name": "Boston Marathon 2026",
      "enabled_scenario_count": 5,
      "total_scenario_count": 6,
      "last_updated_at": "2026-02-14T12:00:00Z"
    },
    {
      "chapter_id": "ch_denver_007",
      "chapter_name": "Denver Run Club Q1",
      "enabled_scenario_count": 6,
      "total_scenario_count": 6,
      "last_updated_at": "2026-03-01T09:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 14
  }
}

GET /api/v1/scenario-configurations/api/v1/scenario-configurations/:chapter_id

Fetch full scenario configuration for a chapter (maps to getChapterConfig)

Public

Response Example

{
  "chapter_id": "ch_boston_001",
  "chapter_name": "Boston Marathon 2026",
  "scenarios": {
    "missed_activity_3day": {
      "enabled": true,
      "delay_hours": 24
    },
    "low_mileage_week": {
      "enabled": true,
      "delay_hours": 12
    },
    "first_long_run": {
      "enabled": true,
      "delay_hours": 2
    },
    "pace_improvement": {
      "enabled": false,
      "delay_hours": 6
    }
  },
  "default_delay_hours": 24,
  "last_updated_at": "2026-02-14T12:00:00Z"
}

POST /api/v1/scenario-configurations/api/v1/scenario-configurations

Create a new chapter scenario configuration (initialised from defaults)

Public

Request Example

{
  "chapter_id": "ch_seattle_012",
  "chapter_name": "Seattle Trail Series",
  "default_delay_hours": 18,
  "scenarios": {
    "missed_activity_3day": {
      "enabled": true,
      "delay_hours": 24
    },
    "low_mileage_week": {
      "enabled": true,
      "delay_hours": 12
    }
  }
}

Response Example

{
  "chapter_id": "ch_seattle_012",
  "chapter_name": "Seattle Trail Series",
  "scenarios": {
    "missed_activity_3day": {
      "enabled": true,
      "delay_hours": 24
    },
    "low_mileage_week": {
      "enabled": true,
      "delay_hours": 12
    }
  },
  "default_delay_hours": 18,
  "last_updated_at": "2026-03-26T09:00:00Z"
}

PUT /api/v1/scenario-configurations/api/v1/scenario-configurations/:chapter_id

Replace the full scenario configuration for a chapter

Public

Request Example

{
  "default_delay_hours": 12,
  "scenarios": {
    "missed_activity_3day": {
      "enabled": true,
      "delay_hours": 24
    },
    "low_mileage_week": {
      "enabled": false,
      "delay_hours": 12
    },
    "first_long_run": {
      "enabled": true,
      "delay_hours": 2
    }
  }
}

Response Example

{
  "chapter_id": "ch_boston_001",
  "chapter_name": "Boston Marathon 2026",
  "default_delay_hours": 12,
  "scenarios": {
    "missed_activity_3day": {
      "enabled": true,
      "delay_hours": 24
    },
    "low_mileage_week": {
      "enabled": false,
      "delay_hours": 12
    },
    "first_long_run": {
      "enabled": true,
      "delay_hours": 2
    }
  },
  "last_updated_at": "2026-03-26T10:00:00Z"
}

DELETE /api/v1/scenario-configurations/api/v1/scenario-configurations/:chapter_id

Delete the scenario configuration for a chapter

Public

Response Example

{
  "deleted": true,
  "chapter_id": "ch_boston_001"
}

PATCH /api/v1/scenario-configurations/api/v1/scenario-configurations/:chapter_id/scenarios/:scenario_id

Toggle a single scenario on or off for a chapter (maps to updateScenarioEnabled)

Public

Request Example

{
  "enabled": false
}

Response Example

{
  "chapter_id": "ch_boston_001",
  "scenario_id": "low_mileage_week",
  "enabled": false,
  "updated_at": "2026-03-26T10:15:00Z"
}

POST /api/v1/scenario-configurations/api/v1/scenario-configurations/validate-rule

Validate a rule JSON definition before saving (maps to validateRuleDefinition)

Public

Request Example

{
  "rule": {
    "scenario_id": "custom_pace_drop",
    "trigger_type": "pace_degradation",
    "trigger_conditions": {
      "threshold_percent": 15,
      "window_weeks": 2
    },
    "delay_hours": 6,
    "prompt_template_id": "tmpl_pace_check_01"
  }
}

Response Example

{
  "valid": true,
  "errors": [],
  "warnings": [
    "prompt_template_id 'tmpl_pace_check_01' does not exist in template registry — ensure it is created before enabling this rule"
  ]
}

GET /api/v1/scenario-configurations/api/v1/scenario-configurations/defaults

Retrieve the system default scenario rules (maps to getDefaultScenarios)

Public

Response Example

{
  "data": [
    {
      "scenario_id": "missed_activity_3day",
      "trigger_type": "activity_missed",
      "trigger_conditions": {
        "consecutive_missed": 1
      },
      "trigger_threshold_days": 3,
      "delay_hours": 24,
      "prompt_template_id": "tmpl_re_engage_01",
      "priority": 1
    },
    {
      "scenario_id": "low_mileage_week",
      "trigger_type": "below_weekly_target",
      "trigger_conditions": {
        "threshold_percent": 60
      },
      "trigger_threshold_days": 7,
      "delay_hours": 12,
      "prompt_template_id": "tmpl_mileage_nudge_01",
      "priority": 2
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 6
  }
}

Additional Metadata

{
  "contract_summary": {
    "total_contracts": 410,
    "total_endpoints": 2416,
    "api_styles_used": [
      "rest"
    ]
  },
  "generated_at": "2026-03-26T06:55:53.316Z"
}