> **Client contract note:** Apply [`shared/response-envelope.md`](../shared/response-envelope.md) to JSON responses after the response-contract release. Legacy wrapper examples below may reflect the prior API; the documented endpoint-specific payload fields are still useful. Not staging-verified.

# Scheduler — Dashboard API handoff (source-reviewed)

**Base:** `/api/v1` · **Authentication:** `Authorization: Bearer <token>` (Sanctum) · **Content:** `Accept: application/json`.

**Sources:** [`Routes/api.php`](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Scheduler/Routes/api.php), [`SchedulerController.php`](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Scheduler/Interfaces/Http/Controllers/SchedulerController.php), [`ScheduleCatalog.php`](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Scheduler/Application/ScheduleCatalog.php), [`RunTaskNow.php`](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Scheduler/Application/RunTaskNow.php). Reviewed against `main`, 2026-11-22. JSON values below are illustrative, field structure is derived from source; not captured live.

## 1. `GET /api/v1/scheduler/status`

**Screen:** Scheduler health/monitoring. **Permission:** `scheduler.view`. **Request:** no path/query/body parameters.

**200 response:**
```json
{"data":{"alive":true,"last_heartbeat_at":"2026-11-22T10:30:00+00:00","failed_last_24h":2}}
```

| `data` field | Type | Meaning |
|---|---|---|
| `alive` | boolean | Last heartbeat exists and is at most `scheduler.alive_within_seconds` old (configured as 180 seconds) |
| `last_heartbeat_at` | string ISO-8601 \| null | UTC timestamp from cached scheduler heartbeat; null if absent |
| `failed_last_24h` | integer | Count of scheduled runs with status `failed` or `abandoned` started in last 24h |

**Business rule:** This endpoint reads cached heartbeat and recent failures; it does **not** execute a verification or task. **Errors:** 401 unauthenticated, 403 missing permission; precise global error envelope not verified.

## 2. `GET /api/v1/scheduler/tasks`

**Screen:** Scheduled tasks table. **Permission:** `scheduler.view`. **Request:** no path/query/body parameters.

**200 response:**
```json
{"data":[{"key":"0123456789abcdef","name":"Example scheduled command","expression":"* * * * *","command":"example:run","next_due":"2026-11-22T10:31:00+00:00","runnable":true,"last_status":"completed","last_started_at":"2026-11-22 10:30:00","last_error":null}]}
```

| Item field | Type | Meaning |
|---|---|---|
| `key` | string | Stable scheduler task identifier; manual-run route requires exactly 16 lowercase hex characters |
| `name` | string | Task name |
| `expression` | string | Cron expression |
| `command` | string \| null | Artisan command, null for tasks that cannot be manually run |
| `next_due` | string \| null | Next scheduled execution timestamp; exact serialization from catalog implementation not separately verified |
| `runnable` | boolean | `command !== null` |
| `last_status` | string \| null | Status from latest `scheduled_runs` record |
| `last_started_at` | string \| null | Last run start as serialized by DB query; timezone/format may depend on DB driver |
| `last_error` | string \| null | Last recorded error |

**Business rule:** Each task is merged with its most recent run (max run ID per task). No pagination. **Errors:** 401, 403.

## 3. `GET /api/v1/scheduler/runs`

**Screen:** Scheduler execution history. **Permission:** `scheduler.view`.

| Query parameter | Type | Required | Validation / behavior |
|---|---|---|---|
| `task` | string | No | Exact `task_key` filter when truthy; controller does not explicitly validate format |
| `status` | string | No | Exact `status` filter when truthy; no explicit allowlist validation in controller |
| `per_page` | integer-like | No | Defaults to 25, capped at 100; controller has no explicit minimum validation |
| `page` | integer-like | No | Laravel paginator page index |

**Example:** `GET /api/v1/scheduler/runs?task=0123456789abcdef&status=failed&per_page=25&page=1`

**200 response:** The controller returns the **raw Laravel length-aware paginator**, not `ApiResponse::ok`. Individual `data` records are raw database rows from `scheduled_runs`, not a dedicated resource serializer.
```json
{"current_page":1,"data":[{"id":10,"task_key":"0123456789abcdef","status":"failed","started_at":"2026-11-22 10:00:00","error":"Example failure"}],"first_page_url":"https://example.test/api/v1/scheduler/runs?page=1","from":1,"last_page":1,"last_page_url":"https://example.test/api/v1/scheduler/runs?page=1","links":[],"next_page_url":null,"path":"https://example.test/api/v1/scheduler/runs","per_page":25,"prev_page_url":null,"to":1,"total":1}
```
**Caution:** The sample `data` row is partial; the full `scheduled_runs` table schema and exact serialized fields have not been verified. Standard Laravel pagination metadata shown; actual URLs depend on deployment. Sorted by `id DESC`. **Errors:** 401, 403; invalid/negative pagination may produce framework-level errors because there is no explicit minimum validation.

## 4. `POST /api/v1/scheduler/tasks/{key}/run`

**Screen:** “Run now” action on a runnable scheduled command. **Permission:** `scheduler.run`. **Rate limit:** 10 requests/minute. **Path:** `key` required, exactly 16 lowercase hex characters (`[a-f0-9]{16}`). **Request body/query:** none required.

```http
POST /api/v1/scheduler/tasks/0123456789abcdef/run
Authorization: Bearer <token>
Accept: application/json
```

**202 response:**
```json
{"data":{"queued":true}}
```

| Field | Type | Meaning |
|---|---|---|
| `data.queued` | boolean | Task dispatch accepted, **not** a claim that execution completed |

**Business rules:** Only a task already registered in the scheduler catalog with a non-null command can be dispatched. The endpoint cannot run arbitrary Artisan commands. The task is dispatched asynchronously; use `GET /scheduler/runs` to inspect execution history. **Errors:** 401 unauthenticated, 403 missing `scheduler.run`, 404 when key fails route regex, 429 rate limit. `TaskNotRunnable` is thrown for missing/non-runnable commands; exact HTTP mapping and error JSON need verification in exception handler.

## Integration guidance

- Poll `status` for health indicators, but avoid treating `alive=true` as proof that every task succeeded.
- Populate task rows from `tasks`; disable “Run now” when `runnable=false` or the user lacks `scheduler.run`.
- Treat `202 queued` as an accepted job, not completed work; refresh runs separately.
- Do not hardcode illustrative task keys, names, commands or timestamps in clients.

**Verification gaps:** Runtime samples, exception-handler payloads, `scheduled_runs` migration column inventory, concrete catalog `next_due` serialization and worker delivery were not tested in this pass.
