Scenario Edge Function Scheduler - API Contract

GET /api/v1/scheduler-invocations/api/v1/scheduler-invocations

List all scheduler invocation run logs

Public

Response Example

{
  "data": [
    {
      "id": "run_01HSCHED01",
      "invoked_at": "2026-03-26T08:00:00Z",
      "status": "success",
      "users_evaluated": 148,
      "notifications_dispatched": 23,
      "duration_ms": 4210,
      "error_message": null
    },
    {
      "id": "run_01HSCHED02",
      "invoked_at": "2026-03-25T08:00:00Z",
      "status": "success",
      "users_evaluated": 151,
      "notifications_dispatched": 19,
      "duration_ms": 3980,
      "error_message": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 90
  }
}

GET /api/v1/scheduler-invocations/api/v1/scheduler-invocations/:id

Get details of a specific scheduler invocation run

Public

Response Example

{
  "id": "run_01HSCHED01",
  "invoked_at": "2026-03-26T08:00:00Z",
  "status": "success",
  "users_evaluated": 148,
  "notifications_dispatched": 23,
  "duration_ms": 4210,
  "error_message": null,
  "batch_results": [
    {
      "batch_index": 0,
      "user_count": 50,
      "notifications_sent": 8,
      "duration_ms": 1400
    },
    {
      "batch_index": 1,
      "user_count": 50,
      "notifications_sent": 9,
      "duration_ms": 1410
    },
    {
      "batch_index": 2,
      "user_count": 48,
      "notifications_sent": 6,
      "duration_ms": 1400
    }
  ]
}

POST /api/v1/scheduler-invocations/api/v1/scheduler-invocations

Manually trigger a new scheduler invocation (ad-hoc run)

Public

Request Example

{
  "reason": "manual_trigger",
  "triggered_by": "admin_usr_001"
}

Response Example

{
  "id": "run_01HSCHED99",
  "invoked_at": "2026-03-26T10:15:00Z",
  "status": "running",
  "triggered_by": "admin_usr_001",
  "reason": "manual_trigger"
}

PUT /api/v1/scheduler-invocations/api/v1/scheduler-invocations/:id

Update a scheduler run record (e.g. attach error details or completion status)

Public

Request Example

{
  "status": "failed",
  "error_message": "OpenAI rate limit exceeded at batch 2"
}

Response Example

{
  "id": "run_01HSCHED99",
  "status": "failed",
  "error_message": "OpenAI rate limit exceeded at batch 2",
  "invoked_at": "2026-03-26T10:15:00Z"
}

DELETE /api/v1/scheduler-invocations/api/v1/scheduler-invocations/:id

Delete a scheduler run log record

Public

Response Example

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

GET /api/v1/scheduler-invocations/api/v1/scheduler-invocations/active-peer-mentors

Fetch the list of currently active peer mentors eligible for scenario evaluation

Public

Response Example

{
  "active_peer_mentors": [
    {
      "user_id": "usr_mentor_7821",
      "org_id": "org_oslo_01",
      "last_active_at": "2026-03-24T12:00:00Z"
    },
    {
      "user_id": "usr_mentor_4402",
      "org_id": "org_bergen_02",
      "last_active_at": "2026-03-20T09:00:00Z"
    }
  ],
  "total": 148
}

POST /api/v1/scheduler-invocations/api/v1/scheduler-invocations/evaluation-batch

Run a scenario evaluation batch for a specific set of user IDs

Public

Request Example

{
  "user_ids": [
    "usr_mentor_7821",
    "usr_mentor_4402",
    "usr_mentor_5503"
  ],
  "run_id": "run_01HSCHED99"
}

Response Example

{
  "run_id": "run_01HSCHED99",
  "batch_index": 0,
  "users_evaluated": 3,
  "notifications_dispatched": 2,
  "duration_ms": 870,
  "results": [
    {
      "user_id": "usr_mentor_7821",
      "scenario_type": "inactivity",
      "notified": true
    },
    {
      "user_id": "usr_mentor_4402",
      "scenario_type": "certification_expiry",
      "notified": true
    },
    {
      "user_id": "usr_mentor_5503",
      "scenario_type": "inactivity",
      "notified": false,
      "reason": "cooldown_active"
    }
  ]
}

Additional Metadata

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