Scenario Trigger Engine - API Contract

GET /api/v1/scenario-trigger-evaluations/api/v1/scenario-trigger-evaluations

List all scenario trigger evaluation records with optional filtering by user or scenario type

Public

Response Example

{
  "data": [
    {
      "id": "trg_01HXYZ123",
      "user_id": "usr_mentor_7821",
      "scenario_type": "inactivity",
      "should_notify": true,
      "evaluated_at": "2026-03-25T08:00:00Z",
      "evaluation_metadata": {
        "threshold_days": 7,
        "days_inactive": 9,
        "last_active_at": "2026-03-16T14:22:00Z"
      }
    },
    {
      "id": "trg_01HXYZ124",
      "user_id": "usr_mentor_4402",
      "scenario_type": "certification_expiry",
      "should_notify": true,
      "evaluated_at": "2026-03-25T08:01:00Z",
      "evaluation_metadata": {
        "lead_time_days": 30,
        "expiry_date": "2026-04-24T00:00:00Z",
        "certification_id": "cert_safety_003"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 387
  }
}

GET /api/v1/scenario-trigger-evaluations/api/v1/scenario-trigger-evaluations/:id

Get a specific trigger evaluation record by ID

Public

Response Example

{
  "id": "trg_01HXYZ123",
  "user_id": "usr_mentor_7821",
  "scenario_type": "inactivity",
  "should_notify": true,
  "evaluated_at": "2026-03-25T08:00:00Z",
  "evaluation_metadata": {
    "threshold_days": 7,
    "days_inactive": 9,
    "last_active_at": "2026-03-16T14:22:00Z"
  }
}

POST /api/v1/scenario-trigger-evaluations/api/v1/scenario-trigger-evaluations

Create and run a new scenario trigger evaluation for a user

Public

Request Example

{
  "user_id": "usr_mentor_7821",
  "scenario_type": "inactivity",
  "threshold_days": 7
}

Response Example

{
  "id": "trg_01HXYZ199",
  "user_id": "usr_mentor_7821",
  "scenario_type": "inactivity",
  "should_notify": true,
  "evaluated_at": "2026-03-26T09:15:00Z",
  "evaluation_metadata": {
    "threshold_days": 7,
    "days_inactive": 9,
    "last_active_at": "2026-03-17T14:22:00Z"
  }
}

PUT /api/v1/scenario-trigger-evaluations/api/v1/scenario-trigger-evaluations/:id

Update an existing trigger evaluation record (e.g. override should_notify or add metadata)

Public

Request Example

{
  "should_notify": false,
  "evaluation_metadata": {
    "threshold_days": 7,
    "days_inactive": 9,
    "override_reason": "manual_suppression"
  }
}

Response Example

{
  "id": "trg_01HXYZ123",
  "user_id": "usr_mentor_7821",
  "scenario_type": "inactivity",
  "should_notify": false,
  "evaluated_at": "2026-03-25T08:00:00Z",
  "evaluation_metadata": {
    "threshold_days": 7,
    "days_inactive": 9,
    "override_reason": "manual_suppression"
  }
}

DELETE /api/v1/scenario-trigger-evaluations/api/v1/scenario-trigger-evaluations/:id

Delete a trigger evaluation record

Public

Response Example

{
  "success": true,
  "deleted_id": "trg_01HXYZ123"
}

POST /api/v1/scenario-trigger-evaluations/api/v1/scenario-trigger-evaluations/evaluate/inactivity

Run inactivity scenario evaluation for a specific user against a given threshold

Public

Request Example

{
  "user_id": "usr_mentor_7821",
  "threshold_days": 7
}

Response Example

{
  "id": "trg_01HXYZ200",
  "user_id": "usr_mentor_7821",
  "scenario_type": "inactivity",
  "should_notify": true,
  "evaluated_at": "2026-03-26T09:20:00Z",
  "evaluation_metadata": {
    "threshold_days": 7,
    "days_inactive": 9,
    "last_active_at": "2026-03-17T14:22:00Z"
  }
}

POST /api/v1/scenario-trigger-evaluations/api/v1/scenario-trigger-evaluations/evaluate/milestone

Run milestone scenario evaluation for a user and milestone type

Public

Request Example

{
  "user_id": "usr_mentor_7821",
  "milestone_type": "first_session_completed"
}

Response Example

{
  "id": "trg_01HXYZ201",
  "user_id": "usr_mentor_7821",
  "scenario_type": "milestone",
  "should_notify": true,
  "evaluated_at": "2026-03-26T09:21:00Z",
  "evaluation_metadata": {
    "milestone_type": "first_session_completed",
    "achieved_at": "2026-03-26T09:00:00Z",
    "sessions_count": 1
  }
}

POST /api/v1/scenario-trigger-evaluations/api/v1/scenario-trigger-evaluations/evaluate/certification-expiry

Run certification expiry scenario evaluation for a user with a given lead time

Public

Request Example

{
  "user_id": "usr_mentor_7821",
  "lead_time_days": 30
}

Response Example

{
  "id": "trg_01HXYZ202",
  "user_id": "usr_mentor_7821",
  "scenario_type": "certification_expiry",
  "should_notify": true,
  "evaluated_at": "2026-03-26T09:22:00Z",
  "evaluation_metadata": {
    "lead_time_days": 30,
    "certification_id": "cert_safety_003",
    "expiry_date": "2026-04-25T00:00:00Z",
    "days_until_expiry": 30
  }
}

GET /api/v1/scenario-trigger-evaluations/api/v1/scenario-trigger-evaluations/users/:userId/should-notify

Check whether a user should receive a notification for a given scenario type right now

Public

Response Example

{
  "user_id": "usr_mentor_7821",
  "scenario_type": "inactivity",
  "should_notify": true,
  "cooldown_satisfied": true,
  "preference_enabled": true,
  "evaluated_at": "2026-03-26T09:25:00Z",
  "reason": "User inactive for 9 days; threshold 7 days; cooldown 3 days satisfied"
}

Additional Metadata

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