Nightly Scheduler - API Contract

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

List all registered scheduler jobs

Public

Response Example

{
  "data": [
    {
      "job_name": "certification-expiry-nightly",
      "cron_expression": "0 2 * * *",
      "is_active": true,
      "last_run_at": "2026-03-26T02:00:00Z",
      "last_run_status": "success",
      "next_run_at": "2026-03-27T02:00:00Z"
    },
    {
      "job_name": "pause-auto-lift-check",
      "cron_expression": "0 6 * * *",
      "is_active": true,
      "last_run_at": "2026-03-26T06:00:00Z",
      "last_run_status": "success",
      "next_run_at": "2026-03-27T06:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 4
  }
}

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

Register a new scheduler job

Public

Request Example

{
  "job_name": "weekly-expiry-summary-report",
  "cron_expression": "0 8 * * 1",
  "handler": "generateWeeklyExpiryReport",
  "is_active": true
}

Response Example

{
  "job_name": "weekly-expiry-summary-report",
  "cron_expression": "0 8 * * 1",
  "is_active": true,
  "created_at": "2026-03-26T09:00:00Z",
  "next_run_at": "2026-03-30T08:00:00Z"
}

POST /api/v1/scheduler/api/v1/scheduler/jobs/:jobName/trigger

Manually trigger a registered job immediately

Public

Request Example

{
  "triggered_by": "coordinator-007",
  "dry_run": false
}

Response Example

{
  "job_name": "certification-expiry-nightly",
  "triggered_at": "2026-03-26T10:15:00Z",
  "run_id": "run-0094",
  "status": "running"
}

GET /api/v1/scheduler/api/v1/scheduler/jobs/:jobName/last-result

Get the result of the most recent execution of a job

Public

Response Example

{
  "job_name": "certification-expiry-nightly",
  "run_id": "run-0093",
  "started_at": "2026-03-26T02:00:00Z",
  "completed_at": "2026-03-26T02:00:01Z",
  "status": "success",
  "result_summary": {
    "mentors_checked": 87,
    "expired_found": 2,
    "auto_paused": 2,
    "reminders_sent": 5,
    "errors": 0
  }
}

DELETE /api/v1/scheduler/api/v1/scheduler/jobs/:jobName

Cancel and deregister a scheduler job

Public

Response Example

{
  "deleted": true,
  "job_name": "weekly-expiry-summary-report",
  "cancelled_at": "2026-03-26T11:00:00Z"
}

Additional Metadata

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