Certification Expiry Cron - API Contract

GET /api/v1/certification-cron/api/v1/certification-cron

List all scheduled cron jobs for certification expiry checks

Public

Response Example

{
  "data": [
    {
      "id": "cron-001",
      "name": "nightly_expiry_check",
      "cron_expression": "0 2 * * *",
      "status": "active",
      "last_run_at": "2026-03-25T02:00:00Z",
      "last_run_status": "success",
      "next_run_at": "2026-03-26T02:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1
  }
}

GET /api/v1/certification-cron/api/v1/certification-cron/:id

Get details of a specific cron job

Public

Response Example

{
  "id": "cron-001",
  "name": "nightly_expiry_check",
  "cron_expression": "0 2 * * *",
  "status": "active",
  "last_run_at": "2026-03-25T02:00:00Z",
  "last_run_status": "success",
  "last_run_result": {
    "mentors_checked": 124,
    "reminders_sent": 3,
    "errors": 0
  },
  "next_run_at": "2026-03-26T02:00:00Z",
  "created_at": "2025-01-15T00:00:00Z"
}

POST /api/v1/certification-cron/api/v1/certification-cron

Create and schedule a new nightly run (maps to scheduleNightlyRun)

Public

Request Example

{
  "name": "nightly_expiry_check",
  "cron_expression": "0 2 * * *",
  "enabled": true
}

Response Example

{
  "id": "cron-001",
  "name": "nightly_expiry_check",
  "cron_expression": "0 2 * * *",
  "status": "active",
  "next_run_at": "2026-03-27T02:00:00Z",
  "created_at": "2026-03-26T10:00:00Z"
}

PUT /api/v1/certification-cron/api/v1/certification-cron/:id

Update cron schedule or enable/disable job

Public

Request Example

{
  "cron_expression": "0 3 * * *",
  "enabled": true
}

Response Example

{
  "id": "cron-001",
  "cron_expression": "0 3 * * *",
  "status": "active",
  "next_run_at": "2026-03-27T03:00:00Z",
  "updated_at": "2026-03-26T10:00:00Z"
}

DELETE /api/v1/certification-cron/api/v1/certification-cron/:id

Delete a scheduled cron job

Public

Response Example

{
  "deleted": true,
  "id": "cron-001"
}

POST /api/v1/certification-cron/api/v1/certification-cron/:id/execute

Trigger an immediate execution of the expiry check (maps to executeExpiryCheck)

Public

Request Example

{
  "dry_run": false
}

Response Example

{
  "run_id": "run-0089",
  "cron_id": "cron-001",
  "triggered_at": "2026-03-26T10:05:00Z",
  "status": "running"
}

GET /api/v1/certification-cron/api/v1/certification-cron/:id/runs

List past execution runs for a cron job

Public

Response Example

{
  "data": [
    {
      "run_id": "run-0088",
      "cron_id": "cron-001",
      "started_at": "2026-03-25T02:00:00Z",
      "completed_at": "2026-03-25T02:01:12Z",
      "status": "success",
      "result": {
        "mentors_checked": 124,
        "reminders_sent": 3,
        "errors": 0
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 90
  }
}

Additional Metadata

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