Scenario Rule Repository - API Contract

GET /api/v1/scenario-rules/api/v1/scenario-rules

List scenario rules, optionally filtered by chapter_id and/or enabled state

Public

Response Example

{
  "data": [
    {
      "id": "rule_8f3a2c",
      "chapter_id": "ch_boston_001",
      "scenario_id": "missed_activity_3day",
      "trigger_type": "activity_missed",
      "trigger_conditions": {
        "consecutive_missed": 1,
        "activity_types": [
          "run",
          "bike"
        ]
      },
      "trigger_threshold_days": 3,
      "delay_hours": 24,
      "prompt_template_id": "tmpl_re_engage_01",
      "enabled": true,
      "priority": 1,
      "created_at": "2026-01-15T10:00:00Z",
      "updated_at": "2026-02-20T14:30:00Z"
    },
    {
      "id": "rule_3b9e7d",
      "chapter_id": "ch_boston_001",
      "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",
      "enabled": true,
      "priority": 2,
      "created_at": "2026-01-20T09:00:00Z",
      "updated_at": "2026-03-01T08:15:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 34
  }
}

GET /api/v1/scenario-rules/api/v1/scenario-rules/:id

Fetch a single scenario rule by ID

Public

Response Example

{
  "id": "rule_8f3a2c",
  "chapter_id": "ch_boston_001",
  "scenario_id": "missed_activity_3day",
  "trigger_type": "activity_missed",
  "trigger_conditions": {
    "consecutive_missed": 1,
    "activity_types": [
      "run",
      "bike"
    ]
  },
  "trigger_threshold_days": 3,
  "delay_hours": 24,
  "prompt_template_id": "tmpl_re_engage_01",
  "enabled": true,
  "priority": 1,
  "created_at": "2026-01-15T10:00:00Z",
  "updated_at": "2026-02-20T14:30:00Z"
}

POST /api/v1/scenario-rules/api/v1/scenario-rules

Create a new scenario rule for a chapter

Public

Request Example

{
  "chapter_id": "ch_boston_001",
  "scenario_id": "first_long_run",
  "trigger_type": "activity_completed",
  "trigger_conditions": {
    "min_distance_meters": 16000,
    "activity_types": [
      "run"
    ]
  },
  "trigger_threshold_days": 1,
  "delay_hours": 2,
  "prompt_template_id": "tmpl_milestone_01",
  "enabled": true,
  "priority": 3
}

Response Example

{
  "id": "rule_c7a4f1",
  "chapter_id": "ch_boston_001",
  "scenario_id": "first_long_run",
  "trigger_type": "activity_completed",
  "trigger_conditions": {
    "min_distance_meters": 16000,
    "activity_types": [
      "run"
    ]
  },
  "trigger_threshold_days": 1,
  "delay_hours": 2,
  "prompt_template_id": "tmpl_milestone_01",
  "enabled": true,
  "priority": 3,
  "created_at": "2026-03-26T09:00:00Z",
  "updated_at": "2026-03-26T09:00:00Z"
}

PUT /api/v1/scenario-rules/api/v1/scenario-rules/:id

Update an existing scenario rule (full or partial update)

Public

Request Example

{
  "enabled": false,
  "delay_hours": 48,
  "priority": 5
}

Response Example

{
  "id": "rule_8f3a2c",
  "chapter_id": "ch_boston_001",
  "scenario_id": "missed_activity_3day",
  "trigger_type": "activity_missed",
  "trigger_conditions": {
    "consecutive_missed": 1,
    "activity_types": [
      "run",
      "bike"
    ]
  },
  "trigger_threshold_days": 3,
  "delay_hours": 48,
  "prompt_template_id": "tmpl_re_engage_01",
  "enabled": false,
  "priority": 5,
  "created_at": "2026-01-15T10:00:00Z",
  "updated_at": "2026-03-26T10:15:00Z"
}

DELETE /api/v1/scenario-rules/api/v1/scenario-rules/:id

Delete a scenario rule permanently

Public

Response Example

{
  "deleted": true,
  "id": "rule_8f3a2c"
}

POST /api/v1/scenario-rules/api/v1/scenario-rules/defaults

Insert the default rule set for a chapter (idempotent — skips existing rules)

Public

Request Example

{
  "chapter_id": "ch_denver_007"
}

Response Example

{
  "chapter_id": "ch_denver_007",
  "inserted_count": 6,
  "skipped_count": 0,
  "rules": [
    {
      "id": "rule_d1a2b3",
      "scenario_id": "missed_activity_3day",
      "enabled": true
    },
    {
      "id": "rule_e4f5c6",
      "scenario_id": "low_mileage_week",
      "enabled": true
    }
  ]
}

GET /api/v1/scenario-rules/api/v1/scenario-rules/:id/stream

Server-Sent Events stream for real-time rule change notifications for a chapter (replaces watchRulesForChapter stream)

Public

Response Example

event: rule_updated
data: {"id":"rule_8f3a2c","enabled":false,"updated_at":"2026-03-26T10:15:00Z"}

Additional Metadata

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