Scenario Prompt Scheduler - API Contract

GET /api/v1/scheduler/api/v1/scheduler

List scheduler job runs with outcome summaries

Public

Response Example

{
  "data": [
    {
      "id": "job_a3c2d1",
      "run_at": "2026-03-26T06:00:00Z",
      "activities_fetched": 38,
      "candidates_found": 11,
      "after_deduplication": 7,
      "dispatched": 7,
      "status": "completed",
      "duration_ms": 4210
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 61
  }
}

GET /api/v1/scheduler/api/v1/scheduler/:id

Get detailed results for a single scheduler job run

Public

Response Example

{
  "id": "job_a3c2d1",
  "run_at": "2026-03-26T06:00:00Z",
  "since": "2026-03-25T06:00:00Z",
  "activities_fetched": 38,
  "candidates_found": 11,
  "after_deduplication": 7,
  "dispatched": 7,
  "dispatched_prompts": [
    {
      "user_id": "usr_4bc8d2",
      "scenario_id": "missed_activity_3day",
      "activity_id": "act_7e2f9a",
      "prompt_id": "ph_9c1d4e"
    }
  ],
  "status": "completed",
  "duration_ms": 4210
}

POST /api/v1/scheduler/api/v1/scheduler

Manually trigger a scheduler evaluation run (maps to runScheduledEvaluation)

Public

Request Example

{
  "since": "2026-03-25T06:00:00Z"
}

Response Example

{
  "id": "job_b4d3e2",
  "run_at": "2026-03-26T09:05:00Z",
  "since": "2026-03-25T06:00:00Z",
  "activities_fetched": 22,
  "candidates_found": 5,
  "after_deduplication": 4,
  "dispatched": 4,
  "status": "completed",
  "duration_ms": 3188
}

PUT /api/v1/scheduler/api/v1/scheduler/:id

Update scheduler job run record (e.g. mark as archived)

Public

Request Example

{
  "status": "archived"
}

Response Example

{
  "id": "job_a3c2d1",
  "status": "archived",
  "updated_at": "2026-03-26T10:45:00Z"
}

DELETE /api/v1/scheduler/api/v1/scheduler/:id

Delete a scheduler job run record

Public

Response Example

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

GET /api/v1/scheduler/api/v1/scheduler/eligible-activities

Fetch activities eligible for scenario evaluation since a given datetime (maps to fetchEligibleActivities)

Public

Response Example

{
  "data": [
    {
      "id": "act_7e2f9a",
      "user_id": "usr_4bc8d2",
      "chapter_id": "ch_boston_001",
      "activity_type": "run",
      "distance_meters": 5200,
      "duration_seconds": 1860,
      "completed_at": "2026-03-24T07:30:00Z"
    },
    {
      "id": "act_1b5c8f",
      "user_id": "usr_9ea3c7",
      "chapter_id": "ch_boston_001",
      "activity_type": "bike",
      "distance_meters": 18400,
      "duration_seconds": 3240,
      "completed_at": "2026-03-25T17:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 38
  }
}

POST /api/v1/scheduler/api/v1/scheduler/deduplicate

Remove already-sent prompts from a candidate list (maps to deduplicatePrompts)

Public

Request Example

{
  "candidates": [
    {
      "rule_id": "rule_8f3a2c",
      "scenario_id": "missed_activity_3day",
      "user_id": "usr_4bc8d2",
      "activity_id": "act_7e2f9a",
      "prompt_template_id": "tmpl_re_engage_01"
    },
    {
      "rule_id": "rule_3b9e7d",
      "scenario_id": "low_mileage_week",
      "user_id": "usr_9ea3c7",
      "activity_id": "act_1b5c8f",
      "prompt_template_id": "tmpl_mileage_nudge_01"
    }
  ]
}

Response Example

{
  "input_count": 2,
  "output_count": 1,
  "removed_count": 1,
  "prompts": [
    {
      "rule_id": "rule_3b9e7d",
      "scenario_id": "low_mileage_week",
      "user_id": "usr_9ea3c7",
      "activity_id": "act_1b5c8f",
      "prompt_template_id": "tmpl_mileage_nudge_01"
    }
  ]
}

Additional Metadata

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